Updating Docs for commit 692b11a made on 2024-04-30T14:26:49+00:00 fr…

…om refs/pull/17/merge by ejpaul

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 103ec329d00f478f559ab9b5cf493c81
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/api.rst.txt

@@ -0,0 +1,71 @@
+API Reference
+=============
+
+Python
+^^^^^^
+
+The ``booz_xform`` module provides a class ``Booz_xform``, described
+in detail here.  The same python module also includes several
+functions for plotting, described on the :doc:`plotting` page.
+
+The class ``Booz_xform`` provides a small number of functions to load
+input data, drive the calculation, and save output data.  In addition,
+all the input and output data are available as properties of the
+class. The properties are scalars, 1D numpy arrays, and 2D numpy
+arrays.
+
+Properties of the class are labeled below as being an input or
+output. The input quantities can be either read or written to in
+python, and should be set before calling
+:func:`~booz_xform.Booz_xform.run()`. (Many of these properties can be
+set by calling :func:`~booz_xform.Booz_xform.read_wout()`).  The
+output quantities are read-only, and they are populated when
+:func:`~booz_xform.Booz_xform.run()` is called.
+
+.. autoclass:: booz_xform.Booz_xform
+   :members:
+   :undoc-members:
+   :member-order: groupwise
+
+.. note:: While 1D and 2D array parameters can appear on the left-hand
+          side of assignment operations, individual array elements or
+          array slices cannot. So for instance, if ``b`` is an
+          instance of :class:`booz_xform.Booz_Xform`, ``b.rmnc = [[1,
+          0.1],[1.1, 0.1]]`` will behave as expected, but
+          ``b.rmnc[0,0] = 2.0`` will not. This is due to the copying
+          of data when interfacing python to C++.
+
+
+C++
+^^^
+
+All definitions for the ``booz_xform`` code reside in the namespace ``booz_xform::``,
+which will be omitted for brevity here.
+
+1D and 2D arrays are handled using the `Eigen <http://eigen.tuxfamily.org/>`_ library.
+
+All floating point values have the type ``boozfloat``, which is merely
+a ``typedef`` for ``double``.  All 1D arrays of integers (such as
+``xm``) have the type ``IntVector``, which is merely a ``typedef`` for
+``Eigen::ArrayXi``.  All 1D arrays of floating point values have the
+type ``Vector``, which is merely a ``typedef`` for
+``Eigen::ArrayXd``. 2D arrays of floating point values have the type
+``Matrix``, which is a ``typedef`` for ``Eigen::ArrayXXd``.  If
+desired, the entire code could be switched to single precision by
+changing these ``typedef`` statements, which are defined in
+``vector_matrix.hpp``.
+
+Public variables below are labeled below as being an input or
+output. The input quantities should be set before calling run(). (Many
+of these input quantities can be set by calling read_wout()).  The
+output quantities are populated when run() is called.
+
+The main functionality of the ``booz_xform`` code is contained in a single class,
+``Booz_xform``:
+
+.. doxygenclass:: booz_xform::Booz_xform
+   :members:
+
+..
+   :undoc-members:
+      

_sources/developer.rst.txt

@@ -0,0 +1,54 @@
+Developer notes
+===============
+
+Testing
+^^^^^^^
+
+The ``booz_xform`` package includes both C++ and python tests,
+including unit and regression tests, and continuous integration.
+
+C++ tests
+*********
+
+Unit tests of the C++ code are handled using the `doctest
+<https://github.com/onqtam/doctest>`_ header-only library. A copy of
+the library in ``externalPackages/doctest`` is used. Source code for
+the C++ tests is located in the ``tests`` directory. Whenever
+``booz_xform`` is compiled, a ``unitTests`` executable is compiled
+containing the C++ tests. To access this executable, you should
+compile the code manually (i.e. outside of ``pip``) using ``cd build;
+cmake ..; make -j``, which will create the ``unitTests`` executable in
+the ``build`` directory.
+
+Python tests
+************
+
+The python tests require the packages ``scipy`` and ``matplotlib``,
+which the core part of ``booz_xform`` does not require.
+
+Python tests are based on the standard ``unittest`` python module.
+Source code for the python tests is located in the ``tests`` directory.
+The python tests will use the installed version of the ``booz_xform`` python package,
+not necessarily a shared library compiled manually in the ``build`` directory.
+One way to run the python tests is to call
+
+.. code-block::
+
+   python -m unittest
+
+from the repository home directory or from the ``tests``
+directory. You can also execute individual ``*.py`` test files
+directly.
+
+The python regression tests make use of files in the ``tests/test_files`` directory.
+
+
+Continuous integration
+**********************
+
+The C++ and python tests are automatically run after every commit to
+the repository.  This automation is handled by GitHub Actions, and
+controlled by the script ``.github/workflows/ci.yml``.
+To view the results of the continuous integration runs, you can click on the "Actions"
+link from the `GitHub repository page <https://github.com/hiddenSymmetries/booz_xform>`_,
+or you can directly visit `<https://github.com/hiddenSymmetries/booz_xform/actions>`_.

_sources/getting_started.rst.txt

@@ -0,0 +1,171 @@
+Getting started
+===============
+
+
+Requirements
+^^^^^^^^^^^^
+
+``booz_xform`` requires a C++ compiler and python3.  The python
+interface uses arrays from the ``numpy`` package, and building
+``booz_xform`` requires the `pybind11 package
+<https://pybind11.readthedocs.io/en/stable/>`_.  These packages are
+installed automatically by the ``pip install`` step described in the
+next section.
+
+``booz_xform`` also requires the NetCDF library. The C++ or fortran
+interfaces to NetCDF are not required, only the standard C interface.
+
+OpenMP is an optional dependency. If found, OpenMP is used to
+parallelize the calculation over magnetic surfaces.  MPI is not used.
+
+There are some additional python packages that are optional dependencies.
+The :doc:`plotting` routines require the `matplotlib
+<https://matplotlib.org/>`_ package.  The python unit tests require
+``matplotlib`` as well as ``scipy``.  These packages are not needed for
+carrying out the coordinate transformation, so they are not
+automatically installed by ``pip``, and you should install them
+separately if you want to use these features.
+
+Installation
+^^^^^^^^^^^^
+
+Before attempting to install ``booz_xform``, make sure NetCDF 
+is available on your system. On some HPC systems, this may require
+loading the relevant module.
+
+There are several ways you can install ``booz_xform``, depending on
+whether you are a user or developer.
+
+1. Installation from PyPI
+*************************
+
+If you do not plan to edit the source code, the recommended way to
+install ``booz_xform`` is to install the latest release from `PyPI
+<https://pypi.org/project/booz_xform/>`_ using ``pip``::
+
+    pip install -v booz_xform
+
+This command will download and compile the code. At the start of the
+compilation step, the ``cmake`` build system will search for the
+NetCDF and MPI header files and libraries.  Any of the environment
+variables ``NETCDF_DIR``, ``NETCDF_HOME``, or ``NETCDFDIR`` can be set
+to guide ``cmake`` in this search, and it will also look in standard
+locations such as ``/opt/local/include``.
+
+The ``-v`` flag above (for verbose output) is optional, but it is
+useful since it allows you to see which compiler, NetCDF, and MPI
+libraries were used. This information can be found in the lines
+similar to the following in the output::
+
+  ...
+  -- The CXX compiler identification is AppleClang 11.0.0.11000033
+  -- Detecting CXX compiler ABI info
+  -- Detecting CXX compiler ABI info - done
+  -- Check for working CXX compiler: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/c++ - skipped
+  -- Detecting CXX compile features
+  -- Detecting CXX compile features - done
+  CMAKE_MODULE_PATH=
+  CMAKE_CURRENT_SOURCE_DIR=/private/var/folders/_2/t14gsms50v1dmfz95bz32hk00000gn/T/pip-req-build-0fgxd2du
+  Hello world from FindNetCDF
+  -- Found NetCDF: /opt/local/lib/libnetcdf.dylib
+  NETCDF_INCLUDES=/opt/local/include
+  NETCDF_LIBRARIES=/opt/local/lib/libnetcdf.dylib
+  ...
+
+To change the compiler that is used to build the code, you can insert
+``CXX=`` followed by the compiler name before ``pip``. For example, to
+use the Intel compiler ``icpc``, use
+
+.. code-block::
+
+  CXX=icpc pip install -v booz_xform
+  
+If the installation is successful, ``booz_xform`` will be added to
+your python environment. You should now be able to import the module
+from python::
+
+  >>> import booz_xform
+
+On some systems, you may not have permission to install packages to
+the default location. In this case, add the ``--user`` flag to ``pip``
+so the package can be installed for your user only::
+
+    pip install -v --user booz_xform
+
+  
+2. Installation from a local copy of the repository
+***************************************************
+
+If you prefer to see or edit the source code, you can first clone the
+repository using
+
+.. code-block::
+
+    git clone https://github.com/hiddenSymmetries/booz_xform.git
+
+Then install the package to your local python environment with
+
+.. code-block::
+
+  cd booz_xform
+  pip install -v -e .
+
+The ``-e`` flag is not mandatory but it can be helpful during
+development. This flag makes the installation editable, in that edits
+to the pure python source in ``src/booz_xform`` are immediately
+reflected in the package you import into python. Without this flag,
+you would need to re-install the package for changes to become active.
+
+The ``pip install`` line can be preceded by ``CXX=`` to select a
+specific compiler, as in the PyPI method above.
+
+Again, if you encounter a permissions error trying to install packages
+to the default location, add the ``--user`` flag::
+
+    pip install -v -e --user .
+
+
+3. Installation without pip from a local copy of the repository
+***************************************************************
+
+This option is similar to option 2, and is well suited for code
+development. This option gives a somewhat faster installation than
+option 2, but you must first manually ensure all the dependencies in
+``pyproject.toml`` are installed.
+
+From a cloned copy of the repository, run
+
+.. code-block::
+
+  python setup.py develop
+
+This command can be preceded by ``CXX=`` to select a
+specific compiler, as in the other methods above.
+
+
+4. Building outside of the python package system
+************************************************
+
+If you are actively developing the code, you may wish to compile the
+C++ source without going through the python package system. In this
+case, you should have a local copy of the repository, obtained with
+
+.. code-block::
+
+  git clone https://github.com/hiddenSymmetries/booz_xform.git
+
+You must also have the ``pybind11`` python package installed, as well
+as ``cmake``.  The code then can be built using the usual approach for
+a ``cmake`` project::
+
+  cd booz_xform/build
+  cmake ..
+  make -j
+
+In this case, the python extension library ``_booz_xform`` (with a
+filename usually ending in ``.so``), the standalone executable
+``xbooz_xform``, and the library ``libbooz_xform.a`` will all be
+created in the ``build`` directory. Note that in this approach, no
+python package is installed.  You can import only the ``Booz_xform``
+class with ``import _booz_xform``, which loads the compiled extension
+without importing the pure python functions.

_sources/index.rst.txt

@@ -0,0 +1,24 @@
+=========================
+booz\_xform documentation
+=========================
+
+``booz_xform`` is a package for computing Boozer coordinates in toroidal magnetohydrodynamic
+equilibria, including both stellarators and tokamaks.
+The package described here follows the same algorithm as the fortran 77 code of the same name
+in `Stellopt <https://github.com/PrincetonUniversity/STELLOPT/tree/develop/BOOZ_XFORM>`_.
+However the package here is written in C++, with python bindings.
+The package here is also written so as to allow input from equilibrium codes other than VMEC,
+it is parallelized using OpenMP, and it includes functions for plotting output.
+It is also equipped with unit and regression tests and continuous integration.
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents
+
+   getting_started
+   theory
+   usage
+   plotting
+   api
+   developer
+   source

_sources/plotting.rst.txt

@@ -0,0 +1,27 @@
+Plotting
+========
+
+The ``booz_xform`` python module includes several routines for plotting.
+These functions take a :class:`~booz_xform.Booz_xform` instance as an argument.
+This object can be one which was used to drive the coordinate transformation.
+Or, this :class:`~booz_xform.Booz_xform` instance could be one in which results from an earlier
+transformation were loaded using the :meth:`~booz_xform.Booz_xform.read_boozmn` function.
+
+The plotting routine require the python `matplotlib
+<https://matplotlib.org/>`_ package. This package must be installed
+manually since it is not required for the core functionality of
+``booz_xform`` and so is not installed by ``pip``.
+
+All plotting routines use matplotlib's current axis. When using these
+routines in a script, you typically need to call ``plt.show()`` at the
+end to actually display the figure.
+
+A `gallery of plots that can be generated
+<https://github.com/hiddenSymmetries/booz_xform/blob/main/examples/plots_demo.ipynb>`_
+can be found in ``plots_demo`` notebook in the ``examples`` directory.
+The full API of the available plotting routines follow.
+
+.. automodule:: booz_xform
+   :members: surfplot, symplot, modeplot
+
+

_sources/source.rst.txt

@@ -0,0 +1,4 @@
+`Source code on GitHub <https://github.com/hiddenSymmetries/booz_xform>`_
+=========================================================================
+
+The source code for ``booz_xform`` can be found at https://github.com/hiddenSymmetries/booz_xform.