Installation¶
Requirements¶
The following packages are required to work with ESMPy:
The following packages are optional:
Getting the code¶
The ESMF User’s Guide contains information on building and installing ESMF. The ESMF Reference Manual contains information on the architecture of ESMF, example code, and details of the API (Application Programming Interface).
Instructions on how to download the ESMPy code can be found at the ESMPy Download page.
Installing ESMPy¶
Installation of ESMPy requires a pointer to a file named esmf.mk inside of an ESMF installation. This file resides in a directory which looks like:
<ESMF_INSTALL_DIR>/lib/lib<g<or>O>/<platform>/esmf.mk
If the ESMFMKFILE
flag is set when building ESMPy then it will not need to be
referenced again. If not, an environment variable of the same name must be set
with the path to the esmf.mk file every time that a new shell is initiated.
The ESMPy build can be installed in a custom location using the
--prefix
, --home
, or --install-base
flags to the install command. If this
is done, then this location needs to be added to the PYTHONPATH
environment
variable in the user’s shell every time that a new shell is initiated. If a
customized install location is not specified, ESMPy will be installed in the
standard Python package installation directory on that particular machine.
Note
The ESMPy build does not have to be installed to be used. The
PYTHONPATH
environment variable can simply be pointed to the directory
containing the ESMF module (esmf/src/addon/ESMPy/src from a default git clone)
after the build command.
As usual, any command followed by --help
should print out some information
on what options are available.
An installation of ESMPy in the default location for Python packages can be done with the following command issued from the top level ESMPy directory:
- default Python package installation:
python setup.py build --ESMFMKFILE=<DIR_TO_esmf.mk> install
- custom install location:
python setup.py build --ESMFMKFILE=<DIR_TO_esmf.mk>
python setup.py install --prefix=<custom_install_location>
setenv PYTHONPATH <custom_install_location>/lib/\*/site_packages
Please contact esmf_support@list.woc.noaa.gov with any questions or problems.
Anaconda Packages¶
ESMPy conda packages are available through the NESII channel:
conda install -c nesii esmpy
There are Python3 compatible development versions available through the conda-forge channel:
conda install -c nesii/label/dev-esmf -c conda-forge esmpy
Validation¶
The ESMPy testing is done with the nose package, both in serial and parallel. The nose commands are wrapped in the following ESMPy targets:
python setup.py test
python setup.py test_examples
python setup.py test_regrid_from_file
python setup.py test_parallel
python setup.py test_examples_parallel
python setup.py test_regrid_from_file_parallel
Note
The regrid_from_file
tests can take up a lot of memory and bandwidth.
The test_regrid_from_file_dryrun
command will simply download the test
files without actually running them (allowing the stress on the machine to
be applied to bandwidth first, and then memory).
Alternatively, individual tests can be run with nose using the following format:
nosetests <file>:<test>
e.g.
nosetests src/ESMF/test/test_api/test_regrid.py:TestRegrid.test_field_regrid
Limitations¶
ESMPy doesn’t include many aspects of ESMF, including components, field bundles, time management, etc. The limitations listed here are relative to ESMF offline and integrated regridding capabilities.
- ESMPy cannot use an ESMF installation that is built with external LAPACK support.
- Coordinates cannot be retrieved from the elements of a
Mesh
. This can affect the ability to setField
values on a sourceMesh
created from file when using conservative regridding. - Multi-tile
Grid
support is limited to cubed-sphere grids created on 6 processors. A cubed-sphere grid can be created on any number of processors, but only when it is created on 6 processors will the coordinates be retrievable for the entire object. - There is no
FieldBundle
class, only singleFields
.
Testing related:
- Nightly regression testing is limited to a small subset of the ESMF test platforms, including Darwin and Linux running gfortran with openMPI.