Pulled the instructions

compilation_instructions.md

@@ -1,29 +1,39 @@
-## SPEC complition instructions
+# SPEC compilation instructions
 
-Guide for installing SPEC including the python wrappers, relies on usign cmake
+The default installation method for SPEC uses CMake and installs
+the python wrappers and an xspec executable. 
 
-### Compilation
+## Installation using Anaconda
+
+We recommend you use Anaconda to create a coherent build environment and prevent 
+dependency conflicts.
+
+Control over the installation can be had by editing `cmake_config.json`, to guide 
+CMake to the right compilers etc. 
+Configurations for different machines are stored in `${SPEC_ROOT}/cmake_machines`,
+to use these, link them to cmake_config.json: `ln -s cmake_config cmake_machines/<config_file.json>`
+
+>[!TIP]
+>install as much as possible in your environment using the `conda` command, 
+>only use 'pip' at the very end for the last packages. 
+>if you have not added the `conda-forge` channel do so by
+>`conda config --add channels conda-forge`
 
 Get the repository and install the necessary compilers and libraries
-```
+```bash
 git clone git@github.com:PrincetonUniversity/SPEC.git 
-conda create -n "spec_wrapper" python=3.11
+conda create -n "spec_wrapper" python=3.11 # create your environment for SPEC
 conda activate spec_wrapper
-conda install gcc_linux-64 gxx_linux-64 gfortran_linux-64
+conda install gcc_linux-64 gxx_linux-64 gfortran_linux-64 # or macOS versions, see note below
 conda install hdf5 openblas libopenblas fftw scalapack openmpi cmake ninja
 conda install h5py matplotlib f90nml scipy scikit-build mpi4py ipython
 pip install f90wrap
 ```
 
-Link to the correct `f2py`
-```
-ln -s ~/anaconda3/envs/spec_wrapper/bin/f2py ~/anaconda3/envs/spec_wrapper/bin/f2py3
-```
+>[!NOTE]
+> for macOS users use the respective compiler packages; 
+> `conda install clang_osx-64 clangxx_osx-64 gfortran_osx-64`
 
-If necessary, unset HDF5 and FFTW environmental variables
-```
-unset HDF5, HDF5_ROOT, HDF5_HOME, FFTW, FFTW_DIR
-```
 
 Finally, install SPEC and the wrapper (logs will be in `compile.log`)
 ```
@@ -36,6 +46,20 @@ cd Utilities/pythontools/
 pip install -e .
 ```
 
+### Troubleshooting Anaconda install
+If using a newer version of python, `f2py3` is no longer shipped. If your system contains an old python install (for example from your OS), CMake can find its `f2py3` and give try to use it to compile the wrappers instead of your environments `f2py`. 
+Test this by looking if you have an `f2py3` in your path: `$which f2py3`. 
+The easiest workaround is to create a link called f2py3 that links to f2py so it is found first. 
+```
+ln -s ~/anaconda3/envs/spec_wrapper/bin/f2py ~/anaconda3/envs/spec_wrapper/bin/f2py3
+```
+
+You might have HDF5 or FFTW environment variables set (for example for a VMEC install). This can throw off CMake, which we want to use only anaconda. 
+```
+unset HDF5, HDF5_ROOT, HDF5_HOME, FFTW, FFTW_DIR
+```
+
+
 
 ### Testing your SPEC installation
 
@@ -110,4 +134,48 @@ Next, the python wrapper is tested.
     re-converge SPEC, etc. for a set of five values of the central pressure
     in a two-volume classical Stellarator case.
     After the pressure scan with re-convergence,
-    a plot of the MHD energy vs. the central pressure is shown.
+    a plot of the MHD energy vs. the central pressure is shown.
+
+
+## Other legacy installations
+It is still possible to compile SPEC using `make` or `cmake` directly, and bypass the wrapper installation. 
+
+### CMake installation
+Spec can be installed using CMake to find the relevant libraries to link against. 
+You can control 
+in the root directory of SPEC do the following: 
+```bash
+mkdir build
+cd build
+cmake ..
+make
+```
+This will compile SPEC (not the wrappers). The `xspec` executable is found in ${SPEC_ROOT}/build/build/bin/xspec
+
+### Make installation
+SPEC can also be installed using the `make` command in the root directory. 
+
+The `make` install is controlled by the `BUILD_ENV` environment variable. 
+Available options are found in the `SPECfile`
+where different link and compile flags for many machines are found. 
+
+If you cannot find your machine in the list, copy a similar machine and adapt as needed. 
+Then compile by running the command
+
+```bash
+BUILD_ENV=<machine_name> make
+```
+
+The `make` process creates files in the SPEC_ROOT directory, and creates the `xspec` executable there. 
+
+
+## Build process
+the source files are found in the `${SPEC_ROOT}/src/ directory`.
+The `.f90` files contain macros that are expanded during the make process using the `m4` command. 
+
+Depending on the build type, the macro-expanded code is either found in `build/src/`, in the root directory, or in the `_skbuild` folder. 
+
+>[!TIP]
+>The line numbers in error messages correspond to the macro-expanded code
+
+The macros are defined in `src/macros`