expanded instructions to cover legacy build methods

compilation_instructions.md

@@ -1,29 +1,35 @@
 ## SPEC complition instructions
 
-Guide for installing SPEC including the python wrappers, relies on usign cmake
+The default installation for SPEC 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 and BLAS vendor. 
+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 not in conda. 
+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 [email protected]: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 #
 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
-```
-
-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 +42,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 soft-link f2py3 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 +130,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