Installation

The eoxmagmod packages is installed from sources. The sources can be obtained either from the releases (eoxmagmod-<version>.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.

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.

To install eoxmagmod in a Conda environment follow these steps:

Before the start, change to the root source directory MagneticModel/.

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

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:

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

Create a new Conda environment from the provided conda_env.yaml file:

conda env create -n <environment-name> -f conda_env.yaml

Activate the new Conda environment and install the eoxmagmod package:
```
conda activate <environment-name>
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/.

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=<install directory>

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=<install prefix>

Install other eoxmagmod dependencies (assuming pure pip installation):

pip3 install 'numpy<2'
pip3 install scipy
pip3 install 'SpacePy>0.5'

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