From 1bc505168cc242804a42b0fb43fa5a92577eed06 Mon Sep 17 00:00:00 2001 From: Connor Moreno Date: Fri, 29 Mar 2024 17:57:09 -0500 Subject: [PATCH 1/3] Modify installation instructions to reflect new dependencies --- README.md | 62 ++++++++++++++++++++++++++----------------------------- 1 file changed, 29 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 9799393b..5920633b 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,52 @@ ## 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 using Mamba -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 Mamba package manager to install dependencies in a Conda environment. 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/) + +Mamba is available via conda (note that Miniforge ships with mamba already installed). + +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. ``` -conda create -n parastell_env +conda create --name parastell_env python=3.11.6 conda activate parastell_env conda install -c conda-forge mamba ``` The subsequent mamba and pip install commands should be run with this environment activated. -### Install Dependencies using Mamba and Pip -Install ParaStell dependencies available on conda-forge. - -``` -mamba install -c conda-forge cadquery moab -``` - -Install pystell_uw dependencies. +### Installing Dependencies using Mamba and Pip +Mamba install ParaStell and PyStell-UW dependencies available on conda-forge. ``` -mamba install matplotlib +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 pystell_uw dependency. +Pip install remaining ParaStell and PyStell-UW dependencies. ``` pip install netCDF4 -``` - -Pip install remaining ParaStell dependencies. - -``` -pip install cad-to-dagmc -pip install gmsh pip install pyyaml ``` ### Coreform Cubit @@ -65,8 +61,8 @@ While it is possible to use ParaStell with older versions of Cubit, additional s 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. -### VMEC Tools -Download and extract the repository for pystell_uw using +### PyStell-UW +Download and extract the repository for PyStell-UW using ``` git clone https://github.com/aaroncbader/pystell_uw.git @@ -74,8 +70,8 @@ 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`. -### Parastell -Download and extract the repository for parastell using +### ParaStell +Download and extract the repository for ParaStell using ``` git clone git@github.com:svalinn/parastell.git From 48052f4fcd83564847365d94fcc0a6aea83bc279 Mon Sep 17 00:00:00 2001 From: Connor Moreno Date: Mon, 1 Apr 2024 12:33:40 -0500 Subject: [PATCH 2/3] Include option for installation via conda evironment file --- README.md | 47 ++++++++++++++++++++++++++++------------------- environment.yml | 20 ++++++++++++++++++++ 2 files changed, 48 insertions(+), 19 deletions(-) create mode 100644 environment.yml diff --git a/README.md b/README.md index 5920633b..26bd2953 100644 --- a/README.md +++ b/README.md @@ -14,18 +14,29 @@ ParaStell depends on: - [PyStell-UW](https://github.com/aaroncbader/pystell_uw) developed by @aaroncbader - [CAD-to-DAGMC](https://github.com/fusion-energy/cad_to_dagmc) -## Install using Mamba +## Install Python Dependencies -This guide will use the Mamba package manager to install dependencies in a Conda environment. 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). +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). 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/) -Mamba is available via conda (note that Miniforge ships with mamba already installed). +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). -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. +### Option 1: Using the ParaStell Environment File + +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: + +``` +conda env create -f environment.yml +conda activate parastell_env +``` + +### 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. ``` conda create --name parastell_env python=3.11.6 @@ -35,48 +46,46 @@ conda install -c conda-forge mamba The subsequent mamba and pip install commands should be run with this environment activated. -### Installing Dependencies using Mamba and Pip -Mamba install ParaStell and PyStell-UW dependencies available on conda-forge. +Mamba install ParaStell and PyStell-UW Python dependencies available on `conda-forge`: ``` 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 and PyStell-UW dependencies. +Pip install the remaining ParaStell and PyStell-UW Python dependencies: ``` 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. -### PyStell-UW -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 git@github.com: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`. diff --git a/environment.yml b/environment.yml new file mode 100644 index 00000000..738213ee --- /dev/null +++ b/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 From 1e54f4b706494c520aa1be38ba69c125e37418ca Mon Sep 17 00:00:00 2001 From: Connor Moreno Date: Mon, 1 Apr 2024 16:54:00 -0500 Subject: [PATCH 3/3] Separate conda/YAML and mamba installation guides --- INSTALL.md | 27 +++++++++++++++++++++++++++ README.md | 34 +++------------------------------- environment.yml | 1 - 3 files changed, 30 insertions(+), 32 deletions(-) create mode 100644 INSTALL.md diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..c50bf098 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,27 @@ +## Manually Installing Python Dependencies with Mamba + +This guide will use the mamba package manager to install Python dependencies. 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). + +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. + +``` +conda create --name parastell_env python=3.11.6 +conda activate parastell_env +conda install -c conda-forge mamba +``` + +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`: + +``` +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 the remaining ParaStell and PyStell-UW Python dependencies: + +``` +pip install netCDF4 +pip install pyyaml +``` \ No newline at end of file diff --git a/README.md b/README.md index 26bd2953..d6be2bbf 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ ## ParaStell -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. +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 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 ParaStell depends on: @@ -16,17 +16,13 @@ ParaStell depends on: ## Install Python Dependencies -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). +This guide will use the conda package manager 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). 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/) -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). - -### Option 1: Using the ParaStell Environment File - 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: ``` @@ -34,31 +30,7 @@ conda env create -f environment.yml conda activate parastell_env ``` -### 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. - -``` -conda create --name parastell_env python=3.11.6 -conda activate parastell_env -conda install -c conda-forge mamba -``` - -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`: - -``` -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 the remaining ParaStell and PyStell-UW Python dependencies: - -``` -pip install netCDF4 -pip install pyyaml -``` +Alternatively, view `INSTALL.md` for instructions on manually installing these Python dependencies using mamba. ## 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: diff --git a/environment.yml b/environment.yml index 738213ee..9a723c57 100644 --- a/environment.yml +++ b/environment.yml @@ -3,7 +3,6 @@ channels: - conda-forge dependencies: - python=3.11.6 - - mamba - pip=24.0 - numpy - scipy