Package: neatstel
NEATNEar-Axis opTimisationNEAT is a python framework that is intended to find optimized stellarator configurations for fast particle confinement using the near-axis expansion formalism.
The magnetic field is calculated using the codespyQSCandpyQIC, the particle orbits are traced using the codegyronimo(included as a submodule) and the optimization is done using the codesimsopt. The benchmarks are made with theSIMPLEandBEAMS3Dcodes (under construction).We show here the standard way to download and install NEAT. For more information, please visit thedocumentationpresent inhttp://neat-docs.readthedocs.io/.InstallationTo install NEAT, you'll need the following librariesgslboostgcc10and the python packages specified inrequirements.txt.
Note thatpyQSCandpyQICshould be downloaded and installed locally.PyPIThe simplest installation of NEAT is by running the commandpip install neatstelHowever, it doesn't work on every system and the code hosted in PyPI might be outdated.From sourceTo download, clone NEAT using the following command:git clone https://github.com/rogeriojorge/NEAT.gitThe python packages necessary to run NEAT are listed in the filerequirements.txt.
A simple way of installing them is by runningpip install -r requirements.txtThen, to install NEAT, on its root directory runpip install -e .If you do not have permission to install python packages to the
default location, add the--userflag topipso the package
can be installed for your user only::pip install --user -e .To debug any possible problems that might arise, you may also try to install
using the providedsetup.pyfilepython setup.py install --userDone! Now try running an example.Note: the python package is calledneatstel.DockerThis section explains how to build the docker container for NEAT. It can be used to compile gyronimo, install pyQSC, simsopt and compile NEAT in a docker image directly.Using Docker HubThe easiest way to get simsopt docker image which comes with NEAT and all of its dependencies such as gyronimo and VMEC pre-installed is to use Docker Hub. After installing docker, you can run the simsopt container directly from the simsopt docker image uploaded to Docker Hub.docker run -it --rm rjorge123/neatThe above command should load the terminal that comes with the NEAT docker container. When you run it first time, the image is downloaded automatically, so be patient. You should now be able to import the module from python:python3
import neatBuild locallyTo build the image locally, instead of downloading from DockerHub, you can use the commands below:Build the docker image by running thedocker buildcommand in the repo root directory:docker build -t neat -f docker/Dockerfile.NEAT .This process yields an image with roughly 2 GB and may take minute to build.Run the docker image using thedocker runcommand including your results folder:docker run -it neatDone! You are now in an environment with NEAT installed. You can open python and run the examples.UsageFor common uses of NEAT, please check theexamplesfolder.
It has the three main current uses of NEAT:Trace a single particle orbit (examples/plot_single_orbit_qs.py)Trace an ensemble of particles (examples/calculate_loss_fraction_qs.py)Optimize a stellarator magnetic field (examples/optimize_loss_fraction_qs.py)NormalizationsAll units are in SI, except:The mass of the particle, which is in units of the mass of the protonThe charge of the particle is normalized to the charge of the protonThe energy is in eVLambda = mu (SI) / Energy (SI) * B (reference SI)ProfilingProfiling Python codeUse the line_profiler python extension.pip install line_profilerExamplehereProfiling the C++ extensionThere is a C++ script in thesrc/neatppdirectory calledneatpp_profiling.cppthat has the
sole purpose of helping find bottlenecks in the C++ implementation. We show here an example of
how to profile the code using the toolgperftools.https://github.com/gperftools/gperftoolsOn MacOs, it can be installed via Macports or Homebrew.
On Ubuntu, it can be install viasudo apt-get install google-perftools.For it to profile the code, the flagPROFILINGshould beONin thecmake_config_file.jsonfile.
After compiling NEAT, it will create an executable calledprofilingin the temporary build directory.
To profile the code using thegperftools, you can runCPUPROFILE=profile.out build/path_to_profilingwhere the output file for the profiling was namedprofile.out.The results can be ploted using the following commandpprof --gv build/path_to_profiling profile.outOn MacOs, to show the plot, one needs to installgprof2dot,graphivzandgv. On macports, for example, this can be done usingsudo port install py310-gprof2dot graphivz gvwhere the python version 3.10 was specified.If, instead of plotting, you would like text results, you can runprof build/path_to_profiling profile.outFAQpybind11 not found by cmakePlease use the following command to installpybind11[global]instead ofpybind11pip install "pybind11[global]"How to clean all folders created during installation/executionTo clean the build folders and all folders not being tracked by GIT, rungit clean -d -f -x