fv3gfs-wrapper (import fv3gfs.wrapper), is a Python wrapper for the FV3GFS
global climate model.
See the documentation for more detailed instructions.
This is currently alpha development software used for research. If you would like to contribute to or collaborate on the software, please get in touch with [email protected] or another developer.
Running the tests as they are currently written requires private credentials to google cloud services, as the data access is set to "requester pays". To run the tests and examples with your credentials, set an environment variable GOOGLE_APPLICATION_CREDENTIALS as a path to your JSON key file. (E.g., export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json) Note: your project will incur some data transfer charges if you run these tests or examples.
Checking out
This package uses submodules. After you check out the repository, you must run
git submodule update --init --recursive in the root directory of this package.
- Free software: BSD license
Local Machine Installation
The Docker image can be built using make build-docker, or built and then
tested using make test-docker (which will use the existing build if present).
The first time you build, both ESMF and FMS will be
built, taking up quite a lot of time. On subsequent builds, these may be retrieved
from cached images, if you allow caching on your system.
The ESMF, FMS, MPICH, and Serialbox images can instead be retrieved from docker if you build with
the flag BUILD_FROM_INTERMEDIATE=y make build-docker. This can greatly decrease
build time.
On a host, the package can be built using make build, and then installed
in development mode with pip install -e ..
This package only supports linux and Python 3.5 or greater.
Building Docs
Once the docker image is built, the documentation can be built and shown using:
make docs-docker
This will produce html documentation in docs/html.
Iterative development
When making changes to the Fortran source code, you may want to rebuild just part of
the model, keeping build artifacts between rebuilds. You can do this by running the
docker image with bind-mounts into your local filesystem. Just be sure to make clean
when you're done to remove the build artifacts, or it may cause problems when you
build the docker image.
With the image already built by make build-docker or pulled using
docker pull us.gcr.io/vcm-ml/fv3gfs-wrapper:gnu7-mpich314-nocuda, run dev_docker.sh. This will
bind-mount the fv3gfs, lib, tests, external, and templates directories into the
docker image. Inside the docker image, you can build or re-build the model with
make build inside the /fv3gfs-wrapper directory, and run the test suite with
make test.
Re-building the model inside the image is necessary since your local filesystem won't already have the build artifacts necessary to build the compiled wrapper.
Usage
Example run scripts are included in examples/runfiles.
These run scripts act as a drop-in replacement for fv3.exe, and get executed
in the same way, using mpirun:
mpirun -np 6 python online_code.py
Running these files requires them to be placed inside a valid run directory. This is
done automatically if you run them using fv3run, as is done in
the Makefile in that directory.