Update installation documentation

README.md

@@ -1,86 +1,91 @@
 ## ParaStell
-Parametric 3D CAD modeling tool for stellarator fusion devices. This toolset takes VMEC plasma equilibrium data to build intra-magnet components of varying thickness from a user-specified radial build, as well as corresponding coil filament point-locus data to build magnet coils of user-specified cross-section.
+Parametric 3-D CAD modeling toolset for stellarator fusion devices. This open-source Python package uses plasma equilibrium VMEC data and CadQuery to model in-vessel components of varying thickness in low-fidelity from a user-specified radial build. Furthermore, coil filament point-locus data corresponding to VMEC data and Coreform Cubit are used to model magnet coils of user-specified cross-section. Additional neutronics support includes the use of VMEC data and MOAB to generate tetrahedral neutron source definitions and Coreform Cubit to generate DAGMC geometries for use in Monte Carlo radiation transport software.
 
 ## Dependencies
-This tool depends on:
+ParaStell depends on:
 
-- [The VMEC tools](https://github.com/aaroncbader/pystell_uw) developed by @aaroncbader 
+- [PyYAML](https://pyyaml.org/wiki/PyYAMLDocumentation)
+- [NumPy](https://numpy.org/install/)
+- [SciPy](https://scipy.org/install/)
+- [scikit-learn](https://scikit-learn.org/stable/install.html)
+- [Coreform Cubit](https://coreform.com/products/downloads/), version 2023.11
 - [CadQuery](https://cadquery.readthedocs.io/en/latest/installation.html)
 - [MOAB](https://bitbucket.org/fathomteam/moab/src/master/)
-- [Coreform Cubit](https://coreform.com/products/downloads/) or [Cubit](https://cubit.sandia.gov/downloads/) by Sandia National Laboratories
-- [cad-to-dagmc](https://pypi.org/project/cad-to-dagmc/)
-- [Gmsh](https://pypi.org/project/gmsh/)
-- [YAML](https://pyyaml.org/wiki/PyYAML)
-## Install with Mamba
+- [PyStell-UW](https://github.com/aaroncbader/pystell_uw) developed by @aaroncbader 
+- [CAD-to-DAGMC](https://github.com/fusion-energy/cad_to_dagmc)
 
-This guide will use the mamba package manager to install dependencies in a conda environment. Conda allows for easily installing and switching between different versions of software packages through the use of [environments](https://conda.io/projects/conda/en/latest/user-guide/concepts/environments.html).
+## Install Python Dependencies
 
-If you have not already installed conda, you can use one of the following installers to do so: [Miniconda](https://docs.conda.io/en/latest/miniconda.html), [Anaconda](https://www.anaconda.com/), or [Miniforge](https://github.com/conda-forge/miniforge).
+This guide will use the conda and mamba package managers to install Python dependencies. Conda provides straight-forward installation of Python packages and switching between different collections of Python packages through the use of [environments](https://conda.io/projects/conda/en/latest/user-guide/concepts/environments.html).
 
-Mamba is available through conda with `conda install -c conda-forge mamba`. Begin by creating a new conda environment with mamba installed.
+If you have not already installed conda, you can use one of the following installers to do so:
+- [Miniforge](https://github.com/conda-forge/miniforge)
+- [Miniconda](https://docs.conda.io/en/latest/miniconda.html)
+- [Anaconda](https://www.anaconda.com/)
 
-```
-conda create -n parastell_env
-conda activate parastell_env
-conda install -c conda-forge mamba
-```
+Mamba is a faster, more reliable conda alternative that is fully compatible with conda packages. Mamba is available via conda (note that Miniforge ships with mamba already installed).
 
-The subsequent mamba and pip install commands should be run with this environment activated.
+### Option 1: Using the ParaStell Environment File
 
-### Install Dependencies using Mamba and Pip
-Install ParaStell dependencies available on conda-forge.
+A working conda environment with all ParaStell Python dependencies can be found in this repository's `environment.yml` file. To create the corresponding `parastell_env` conda environment on your machine, create the environment from the `environment.yml` file and activate the new environment:
 
 ```
-mamba install -c conda-forge cadquery moab
+conda env create -f environment.yml
+conda activate parastell_env
 ```
 
-Install pystell_uw dependencies.
+### Option 2: Manually Creating the ParaStell Environment
+
+Alternatively, to create the environment manually, begin by creating a new conda environment, installing mamba if needed. Note that ParaStell's dependencies are sensitive to Python version; ensure that Python 3.11.6 is installed.
 
 ```
-mamba install matplotlib
+conda create --name parastell_env python=3.11.6
+conda activate parastell_env
+conda install -c conda-forge mamba
 ```
 
-Pip install remaining pystell_uw dependency.
+The subsequent mamba and pip install commands should be run with this environment activated.
+
+Mamba install ParaStell and PyStell-UW Python dependencies available on `conda-forge`:
 
 ```
-pip install netCDF4
+mamba install -c conda-forge numpy scipy scikit-learn cadquery cad_to_dagmc matplotlib
+mamba install -c conda-forge moab=5.5.0=nompi_tempest_*
 ```
 
-Pip install remaining ParaStell dependencies.
+Pip install the remaining ParaStell and PyStell-UW Python dependencies:
 
 ```
-pip install cad-to-dagmc
-pip install gmsh
+pip install netCDF4
 pip install pyyaml
 ```
-### Coreform Cubit
-Download and install version 2023.11 from [Coreform's Website](https://coreform.com/products/downloads/), then add the /Coreform-Cubit-2023.11/bin/ directory to the `PYTHONPATH` by adding a line to the .bashrc file like the following:
+
+## Install Coreform Cubit
+Download and install version 2023.11 from [Coreform's Website](https://coreform.com/products/downloads/), then add the `/Coreform-Cubit-2023.11/bin/` directory to your `PYTHONPATH` by adding a line similar to the following to your `.bashrc` file:
 
 ```
 export PYTHONPATH=$PYTHONPATH:$HOME/Coreform-Cubit-2023.11/bin/
 ```
 
-Replace $HOME with the path to the Cubit directory on your system. Additional information about adding modules to the `PYTHONPATH` can be found [here](https://www.tutorialspoint.com/How-to-set-python-environment-variable-PYTHONPATH-on-Linux).
+Replace `$HOME` with the path to the Coreform Cubit directory on your system. Additional information about adding modules to your `PYTHONPATH` can be found [here](https://www.tutorialspoint.com/How-to-set-python-environment-variable-PYTHONPATH-on-Linux).
 While it is possible to use ParaStell with older versions of Cubit, additional steps not in this guide may be required.
 
-If you do not have a Cubit license, you may be able to get one through [Cubit Learn](https://coreform.com/products/coreform-cubit/free-meshing-software/) at no cost.
+If you do not have a Coreform Cubit license, you may be able to get one through [Cubit Learn](https://coreform.com/products/coreform-cubit/free-meshing-software/) at no cost.
 
-### VMEC Tools
-Download and extract the repository for pystell_uw using
+## Install PyStell-UW
+Download and extract the PyStell-UW repository:
 
 ```
 git clone https://github.com/aaroncbader/pystell_uw.git
 ```
 
-or download the and extract the zip from [pystell_uw](https://github.com/aaroncbader/pystell_uw). Once extracted, add the directory to the `PYTHONPATH`.
+or download the and extract the ZIP file from [PyStell-UW](https://github.com/aaroncbader/pystell_uw). Once extracted, add the repository directory to your `PYTHONPATH`.
 
-### Parastell
-Download and extract the repository for parastell using
+## Install ParaStell
+Download and extract the ParaStell repository:
 
 ```
 git clone [email protected]:svalinn/parastell.git
 ```
 
-or download the zip from the repository home page. Once extracted, add the directory to the `PYTHONPATH`.
-
-
+or download the ZIP file from the repository home page. Once extracted, add the repository directory to your `PYTHONPATH`.

environment.yml

@@ -0,0 +1,20 @@
+name: parastell_env
+channels:
+  - conda-forge
+dependencies:
+  - python=3.11.6
+  - mamba
+  - pip=24.0
+  - numpy
+  - scipy
+  - scikit-learn
+  - cadquery
+  - moab==5.5.0[build=nompi_tempest_*]
+  - cad_to_dagmc
+  - ca-certificates
+  - certifi
+  - openssl
+  - matplotlib
+  - pip:
+      - netcdf4
+      - pyyaml