From 3053d7a2394fc9fe0b8b43cea1abe3574ae3e3d7 Mon Sep 17 00:00:00 2001 From: Martin Paces Date: Mon, 16 Dec 2024 10:34:44 +0100 Subject: [PATCH] Adding content to the documentation. --- README.md | 101 +++++++++++++++++++------------ conda_env.yaml | 13 ++++ docs/conf.py | 44 ++++++-------- docs/index.rst | 33 +++++----- docs/installation.rst | 138 ++++++++++++++++++++++++++++++++++++++++++ docs/introduction.rst | 36 +++++++++++ docs/license.rst | 22 +++++++ 7 files changed, 305 insertions(+), 82 deletions(-) create mode 100644 conda_env.yaml create mode 100644 docs/installation.rst create mode 100644 docs/introduction.rst create mode 100644 docs/license.rst diff --git a/README.md b/README.md index 778e8e0..e32e494 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,56 @@ +## VirES for Swarm - Magnetic Models, Coordinates and Other Utilities - -## Magnetic Model - -This repository contains various utilities related to Earth magnetic field -modelling and spherical harmonics. +This repository contains various utilities for calculation of Earth magnetic +field models, magnetic coordinates and other auxiliary variables. The repository contains following directories: -- `eoxmagmod` - Collection models of the Earth magnetic field - python module +- `eoxmagmod` - Python package for calculation of the Earth magnetic field, + magnetic coordinates, time conversions and other auxiliary variables. - `qdipole` - Quasi-Dipole apex coordinates evaluation - Fortran code compiled as a shared library (dependency of the `eoxmagmod` package) - `libcdf` - [CDF library](https://cdf.gsfc.nasa.gov/) source installation (dependency of the `eoxmagmod` package) -### Installation from Sources +For more details read the [on-line documentation](https://esa-vires.github.io/MagneticModel/) + +### Installation + +#### Conda Installation + +Step in the MagneticModel directory and follow these steps: + +1) Build the binary dependencies: +``` +conda install conda-build +conda build ./qdipole +conda build ./libcdf +conda build purge +``` +Tested on GNU/Linux. Possibly works on other POSIX systems. + +2) Create an new Conda environment and install `eoxmagmod` dependencies + +``` +conda env create -n -f conda_env.yaml +``` + +3) Install `eoxmagmod` in your new Conda environment: +``` +conda activate +pip install ./eoxmagmod +``` + +#### Installation from Sources + +The installation requires: +- GCC C compiler +- GFortran Fortran compiler +- `make` -#### CDF +1) Build and install `cdf` library + +The CDF build script download sources and builds the [NASA CDF library](https://cdf.gsfc.nasa.gov/) ``` $ cd libcdf/ @@ -30,7 +65,7 @@ variable: $ make install INSTALLDIR= ``` -#### QDIPOLE +2) Build and install `qdipole` library ``` $ cd qdipole/ @@ -39,44 +74,32 @@ $ make build $ sudo make install ``` -#### EOxMagMod -Requires QDIPOLE, CDF libraries + NumPy and SpacePy Python packages -to be installed. -NumPy and SpacePy can be installed using `pip`. +By default the ``qdipole`` library is installed in the ``/usr`` system directory. +To install the library in a custom location use configuration with a custom prefix:: ``` -$ cd eoxmagmod/ -$ python ./setup.py build -$ sudo python ./setup.py install +./configure --prefix= ``` -### Conda installation - -The package contains the `conda-build` scripts allowing local conda build and -installation following this procedure: +3) Build and install `eoxmagmod` pip dependencies -1) build the binary dependencies: ``` -conda install conda-build -conda build ./qdipole -conda build ./libcdf -conda build purge +pip3 install 'numpy<2' +pip3 install scipy +pip3 install 'SpacePy>0.5' ``` -Tested on GNU/Linux. Possibly works on other POSIX systems. Does not work on MS -Windows (primarily because of a missing Fortran compiler). -2) install the `eoxmagmod` in your conda environment: +4) Finally, install `eoxmagmod` package + ``` -conda activate -conda install --use-local qdipole cdf -conda install numpy scipy matplotlib h5py networkx -conda install gcc_linux-64 # spacepy and eoxmagmod require C compiler -conda install gfortran_linux-64 # spacepy requires Fortran compiler -conda deactivate -conda activate # re-activation is required to update the environment variables -pip install spacepy -pip install ./eoxmagmod +pip3 install ./eoxmagmod ``` -The `gfortran_linux-64` and`gcc_linux-64` compilers work on a x86_64 GNU/Linux system. -Other platforms might provide different compilers. +### Testing + +To test the fresh installation, leave the `MagneticModel` directory and run +the following command: + +``` +python3 -m unittest discover -p '[a-z]*.py' -v eoxmagmod +``` diff --git a/conda_env.yaml b/conda_env.yaml new file mode 100644 index 0000000..2e4ae29 --- /dev/null +++ b/conda_env.yaml @@ -0,0 +1,13 @@ +dependencies: + - python >=3.11,<3.12 + - pip + - numpy <2 + - scipy + - matplotlib + - h5py + - conda-forge::c-compiler + - conda-forge::fortran-compiler + - local::qdipole + - local::cdf + - pip: + - SpacePy >0.5 diff --git a/docs/conf.py b/docs/conf.py index 687b61e..be13f7c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -3,13 +3,11 @@ # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - import os import inspect import shutil +#import sphinx try: # for Sphinx >= 1.7 from sphinx.ext import apidoc @@ -20,8 +18,6 @@ os.getcwd(), os.path.dirname(inspect.getfile(inspect.currentframe())) ) -print(__location__) - output_dir = os.path.join(__location__, "api") module_dir = os.path.join(__location__, "../eoxmagmod/eoxmagmod") @@ -31,32 +27,28 @@ except FileNotFoundError: pass -try: - import sphinx - - cmd_line_template = ( - "sphinx-apidoc --implicit-namespaces -f -o {outputdir} {moduledir}" - ) - cmd_line = cmd_line_template.format(outputdir=output_dir, moduledir=module_dir) - - args = cmd_line.split(" ") - if tuple(sphinx.__version__.split(".")) >= ("1", "7"): - # This is a rudimentary parse_version to avoid external dependencies - args = args[1:] - - apidoc.main(args) -except Exception as e: - print("Running `sphinx-apidoc` failed!\n{}".format(e)) +#try: +# args = ( +# f"sphinx-apidoc --implicit-namespaces -f -o {output_dir} {module_dir}" +# ).split(" ") +# if tuple(sphinx.__version__.split(".")) >= ("1", "7"): +# # This is a rudimentary parse_version to avoid external dependencies +# args = args[1:] +# apidoc.main(args) +#except Exception as e: +# print("Running `sphinx-apidoc` failed!\n{}".format(e)) def setup(app): app.add_css_file("css/custom.css") -project = 'MagneticModel' -copyright = '2022, dolezalovat' -author = 'dolezalovat' +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information +project = 'VirES for Swarm - Magnetic Models, Coordinates and Other Utilities' +copyright = '2022-2024, EOX IT Services GmbH' +author = 'Martin Pačes, Týna Doležalova' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration @@ -72,7 +64,7 @@ def setup(app): "sphinx.ext.ifconfig", "sphinx.ext.mathjax", "sphinx.ext.napoleon", - "myst_parser", + #"myst_parser", "sphinx_rtd_theme", "sphinx-jsonschema", "frigate.sphinx.ext", @@ -85,7 +77,7 @@ def setup(app): # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = "sphinx_rtd_theme" -html_static_path = ["static"] +#html_static_path = ["static"] source_suffix = { ".rst": "restructuredtext", diff --git a/docs/index.rst b/docs/index.rst index 52472d2..6e2d19b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,27 +1,26 @@ -.. MagneticModel documentation master file, created by - sphinx-quickstart on Mon Oct 24 10:55:30 2022. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. -Welcome to eoxmagmod documentation! -=================================== +.. include:: introduction.rst -The ``eoxmagmod``_ library collects low-level subroutines employed -by the `VirES for Swarm`_ service to calculate: - -- geomagnetic models (Spherical Harmonic expansion) -- magnetic coordinates (quasi-dipole and dipole latitude and longitude, magnetic local time) -- coordinate system conversions (geodetic, geocentric spherical, geocentric Cartesian coordinates) -- time conversions (modified Julian date 2000, decimal year) -- and perform other auxiliary calculations. +.. toctree:: + :hidden: + :caption: VirES for Swarm -.. _VirES for Swarm: https://vires.service -.. _eoxmagmod: https://vires.service + Git Repository + VirES for Swarm Service + Swarm Virtual Research Environment (JupyterHub) + Example Swarm Notebooks + VirES Python Client Documentaion .. toctree:: :maxdepth: 2 +.. toctree:: + :hidden: + :caption: Package Documentation + + Installation + License - Module Reference +.. Module Reference diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..5369580 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,138 @@ +Installation +============ + +The ``eoxmagmod`` packages is installed from sources. The sources can be +obtained either from the `releases`_ (``eoxmagmod-.tar.gz``) or by +cloning the `git repository`_ (latest development version). + +The sources contain these directories: + +- ``eoxmagmod`` - containing the sources of the ``eoxmagmod`` Python package +- ``qdipole`` - containing sources of the shared library calculating + Quasi-Dipole apex coordinates (QD-latitude, QD-longitude, and Magnetic Local + Time). This shared library is a dependency of the ``eoxmagmod`` package. +- ``libcdf`` - containing installator of the `NASA CDF library`_. + The installator script downloads its sources, builds and installs the shared + library. This shared library is a dependency of the ``eoxmagmod`` package. + +The installation requires C and Fortran compilers and Make build tool. + +The package is tested to work on x86_64 GNU/Linux using GCC and GFortran +compilers. Porting to other platforms should be technically possible, although +formally not supported. + +.. _releases: https://github.com/ESA-VirES/MagneticModel/releases +.. _git repository: https://github.com/ESA-VirES/MagneticModel +.. _NASA CDF library: https://cdf.gsfc.nasa.gov/ + + +Conda Installation +------------------ + +`Conda` is package management system used for distribution of Python packages +and their dependencies. Conda is part of the `Anaconda`_ and `Miniconda`_ +installers. + +Due to the automatic handling of dependencies the Conda installation is simpler +than the generic source installation. + +.. _Anaconda: https://docs.anaconda.com/anaconda/ +.. _Miniconda: https://docs.anaconda.com/miniconda/ + +To install ``eoxmagmod`` in a Conda environment follow these steps: + +Before the start, change to the root source directory ``MagneticModel/``. + +1) Build the shared libraries:: + + conda install conda-build # install build tools + conda build ./qdipole # build qdipole local binary installation package + conda build ./libcdf # build cdf local binary installation package + conda build purge # remove build tools and artefacts + +The built packages can be listed with:: + + conda search --use-local --offline + + +The output may look like:: + + Loading channels: done + # Name Version Build Channel + cdf 3.9.0 h3218e01_0 .../conda/conda-bld + qdipole 0.6.0 h3218e01_0 .../conda/conda-bld + + +2) Create a new Conda environment with the ``eoxmagmod`` dependencies: + +The sources contain Conda environment file ``conda_env.yaml`` defining all +required dependencies. Its content may look like: + +.. literalinclude:: ../conda_env.yaml + :language: YAML + + +Create a new Conda environment from the provided ``conda_env.yaml`` file:: + + conda env create -n -f conda_env.yaml + + +3) Activate the new Conda environment and install the ``eoxmagmod`` package:: + + conda activate + pip install ./eoxmagmod + + +Generic Source Installation +--------------------------- + +The installation requires the C (GCC) and Fortran (GFortran) compilers and +the `make` build command. + +Before the start, change to the root source directory ``MagneticModel/``. + +1) Build and install CDF library:: + + cd libcdf/ + make build + make test + make install + make clean + +By default, the library is installed in ``/usr/local/cdf`` directory. +To install it to a different path override the ``INSTALLDIR`` variable:: + + make install INSTALLDIR= + +2) Build and install ``qdipole`` library:: + + cd qdipole/ + ./configure + make build + make install + make clean + make test + +By default the ``qdipole`` library is installed in the ``/usr`` system directory. +To install the library in a custom location use configuration with a custom prefix:: + + ./configure --prefix= + +3) Install other ``eoxmagmod`` dependencies (assuming pure ``pip`` installation):: + + pip3 install 'numpy<2' + pip3 install scipy + pip3 install 'SpacePy>0.5' + +3) Finally install ``eoxmagmod`` package:: + + pip3 install ./eoxmagmod + + +Test Installation +----------------- +To test the installation, leave the ``MagneticModel`` directory and run the +test command:: + + cd .. # make sure you leave the MagneticModel directory! + python3 -m unittest discover -p '[a-z]*.py' -v eoxmagmod diff --git a/docs/introduction.rst b/docs/introduction.rst new file mode 100644 index 0000000..d3cee1e --- /dev/null +++ b/docs/introduction.rst @@ -0,0 +1,36 @@ +Introduction +============ + +This is the documentation of the ``eoxmagmod`` utility Python package used by +the *VirES for Swarm* (https://vires.services) service for the calculation +of: + +- geomagnetic models (Spherical Harmonic expansion) +- magnetic coordinates (quasi-dipole and dipole latitude and longitude, magnetic local time) +- coordinate system conversions (geodetic, geocentric spherical, geocentric Cartesian coordinates) +- time conversions (modified Julian date 2000, decimal year) +- and other auxiliary calculations. + +This package has been developed and maintained as a collection of various +performance-optimized support algorithms serving the VirES for Swarm service, +usability and portability being our prime objective. + +Nonetheless, this packages if freely available to anybody under the terms of +the :doc:`MIT license`. This documentation then provides information +about the installation and use of the module. + +The ``eoxmagmod`` is pre-installed in the *Swarm Virtual Research Environment* +(https://vre.vires.services), a JupyterHub instance dedicated to exploration +of data provided by the VirES for Swarm service. +See an `example Jupyter notebook`_. + +The ``eoxmagmod`` package may include 3rd party datasets. The package shall not +be used as the primary source of these data. These datasets are added for +for testing and may not be up-to-date. +The package itself currently does not provide any means for the synchronization +of these datasets. + +To report an issue create a ticket in the `Git repository`_. + +.. _example Jupyter notebook: https://notebooks.vires.services/notebooks/04b1_geomag-models-eoxmagmod +.. _Git repository: https://github.com/ESA-VirES/MagneticModel diff --git a/docs/license.rst b/docs/license.rst new file mode 100644 index 0000000..b091047 --- /dev/null +++ b/docs/license.rst @@ -0,0 +1,22 @@ +License +======= + +© Copyright 2014-2024, EOX IT Services GmbH + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies of this Software or works derived from this Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE