Installation and Testing

The GeoModels requires Python >= 3.6. To use GeoModels depends on the following Python packages:

The required Python packages are automatically installed installed by Pip and setuptools:

$ python3 -m pip install geomodels

Please refer to the Pip user manual for details about installation options.

Installation form sources

The GeoModels package provides some binary extensions so the installation from sources also requires:

The user is in charge of ensuring that Cython and the C++ compiler are properly installed and configured.

GeographicLib is bundled with the source tarball available on PyPi (but included in the source tree available on the GeoModels project page on GitHub.

The installation form sources can be done using the following command from the root directory of the source tree:

$ python3 -m setup.py install

Please refer to the distutils documentation for details about installation options.

Using the system GeographicLib

In some cases it is desirable to use the system provided GeographicLib.

Of course in this case the user is in charge of ensuring that GeographicLib is properly installed and configured. On Debian based systems (including Ubuntu) GeographicLib (and its development files) can be installed as follows:

$ sudo apt install libgeographic-dev

To ensure that the system version of the libraries is used instead of the bundled copy of GeographicLib (if present) the GEOMODELS_FORCE_SYSTEM_LIBS environment variable shall be set to TRUE as in the following example:

$ env GEOMODELS_IGNORE_BUNDLED_LIBS=TRUE python3 setup.py install

Also in this case, please refer to the distutils documentation for details about installation options.

Note

if GeographicLib is installed into a non-standard path, the used shall set the environment (e.g. CPPFLAGS, CXXFLAGS and LDFLAGS for the GNU GCC) to allow the compiler to find the GeographicLib header files and libraries.

Also, in this case, the used shall configure the environment to allow the system to find and load GeographicLib shared library (e.g. by setting the LD_LIBRARY_PATH on GNU/Linux systems).

Example:

$ env CPPFLAGS="-I${HOME}/.local/include" \
      LDFLAGS="-L${HOME}/.local/lib" \
      python3 setup.py install

Model data installation

GeoModels uses external data to perform geoid, gravity and magnetic field computations.

If required data are not already available on the system than they can be downloaded and installed using the command line interface provided by the GeoModels package:

$ python3 -m geomodels install-data [-d DATADIR] recommended

The above command installs the recommended subset of data (about 20MB) into the specified DATAROOT folder.

If DATAROOT is not explicitly specified using the -d (or –datadir) option then the default system path is used (e.g. /usr/local/share/GeographicLib).

In any case it is necessary to have write permission on the DATADIR folder, so to install into the default system path it will be probably necessary to use sudo or some equivalent method.

If data are not installed into the default system folder than it is necessary to set the GEOGRAPHICLIB_DATA environment variable to the data installation path to allow GeographicLib to find data. E.g., on systems using bash one can use the following command:

export GEOGRAPHICLIB_DATA=/path/to/data

Please note that with the command line interface it is possible to install different subsets of data:

minimal:only data for the default model of each kind (geoid, gravity and magnetic field) are installed. If GeographicLib v1.5.1 is used then installed data are: geoids/egm96-5, gravity/egm96 and magnetic/wmm2020 (about 20MB)
recommended:the minimal set of data (see above) plus few additional and commonly used data (magnetic/igrf12). The total amount of disk space required is about 20MB. It is guaranteed that the recommended subset always includes all data that are necessary to run the test suite.
all:install all available data (about 670MB of disk space are required)
geoids:install data for all supported geoids
gravity:install data for all supported gravity models
magnetic:install data for all supported magnetic field models

Additionally the command line interface allows also to install data for a single model. See the command line help for details:

$ python3 -m geomodels install-data -h

Please refer to Command line interface for a complete desciption of the command line interface.

Testing

Once the GeoModels package, and recommended data, have been installed, it is possible to run the test suite to be sure that all works correctly.

The recommended way to test GeoModels with using PyTest:

$ env GEOGRAPHICLIB_DATA=/path/to/data \
  python3 -m pytest --pyargs geomodels

As an alternative it is also possible to use the command line interface:

$ python3 -m geomodels test --datadir=/path/to/data