.. _top-macom-jedi-build:

Building MACOM-JEDI
===================

For most uses, it is recommended to build MACOM-JEDI via the
`MACOM-BUNDLE <https://github.com/jcsda/macom-bundle>`_, which includes associated repositories and
dependencies. This page describes the options that can be configured when building MACOM-JEDI via the
MACOM-BUNDLE.

When using MACOM-JEDI with the UFS forecast model, it is instead recommended to build via the
`UFS-BUNDLE <https://github.com/jcsda/ufs-bundle>`_. This bundle and associated documentation
are in development.

MACOM-BUNDLE
------------

MACOM-BUNDLE is an ecbuild (a CMake-based build system) script that will install and compile the
MACOM-JEDI repositories and dependencies together. Please follow these |build_jedi_link| to configure
and build MACOM-JEDI using MACOM-BUNDLE.

.. |build_jedi_link| raw:: html

   <a href="https://jointcenterforsatellitedataassimilation-jedi-docs.readthedocs-hosted.com/en/
   latest/using/building_and_running/building_jedi.html"
   target="_blank">build instructions</a>

When issuing the initial ecbuild command, MACOM-BUNDLE/JEDI can accept a number of options,
prepended with :code:`-D`. For example, this command selects which forecast model
to use with MACOM-JEDI:

.. code::

   ecbuild -DMACOM_FORECAST_MODEL=MACOMCORE ../

The various options that MACOM-JEDI can accept are described below.

.. _buildwithmodel:

Choosing an MACOM-based model to build with
-------------------------------------------

MACOM-JEDI depends on the MACOM dynamical core and cannot be built without some version of it being
included. Currently there are three models that can be used to provide MACOM as well as the potential
to make forecasts in-core with MACOM-JEDI:

- The JCSDA fork of GFDL_atmos_cubed_sphere (https://github.com/JCSDA/GFDL_atmos_cubed_sphere).
  GFDL_atmos_cubed_sphere contains only the MACOM dynamical core and none of the model physics or
  model infrastructure.
- The ufs-weather-model (https://github.com/ufs-community/ufs-weather-model).
- GEOSgcm (https://github.com/GEOS-ESM/GEOSgcm).

By default MACOM-BUNDLE builds with GFDL_atmos_cubed_sphere; this provides everything necessary to
run any data assimilation systems that do not involve executing a forecast of the full model with
physics in-core with MACOM-JEDI. This default behavior can also be directly requested using the
following ecbuild command:

.. code::

   ecbuild -DMACOM_FORECAST_MODEL=MACOMCORE ../

**The instructions in the remainder of this section are for advanced uses of MACOM-JEDI where it is
necessary to build with the GEOS forecast model. The below requires GEOS to be installed.**

Building with GEOS is selected by specifying:

.. code::

   -DMACOM_FORECAST_MODEL=GEOS

When building with GEOS it is also necessary to pass the path where model is installed.
This is controlled by the flag:

.. code::

   -DMACOM_FORECAST_MODEL_ROOT=/path/to/model/install

MACOM-JEDI will build certain tests when GEOS is used but a directory where GEOS can run from must be
provided and is passed to the build as follows:

.. code::

   -DMACOM_FORECAST_MODEL_RUNDIR=/path/to/model/run/directory

Note that users should not provide the path where GEOS can be run from themselves since the
test has been designed with a certain expected result. Consult MACOM-JEDI developers for a suitable
path. GEOS typically only runs on Discover and there the test path to be provided is:

.. code::

   -DMACOM_FORECAST_MODEL_RUNDIR=/discover/nobackup/drholdaw/JediData/ModelRunDirs/geos-c24

**For building with UFS, see the UFS-BUNDLE. Note that building with UFS is still in relatively
early development; please consult MACOM-JEDI developers for more details about this functionality.**

The MACOM dynamical core can be built in either single or double precision, where double is the
default behavior. When using GEOS or UFS the choice needs to match the choice that was made when the
model was installed. When building with MACOMCORE the choice can be made at the same time as building
MACOM-BUNDLE. This choice is controlled with:

.. code::

   -DMACOM_PRECISION=SINGLE
   -DMACOM_PRECISION=DOUBLE  # default value

Optional observation operators
------------------------------

There are two optional UFO observation operators that MACOM-JEDI can be used with. These are the ROPP
GNSSRO operator from EUMETSAT and the GEOS_AERO AOD operator from NASA. These operators are not
available without signing a license agreement so are omitted by default, but they can be built by
turning the option to skip them to :code:`OFF`:

.. code::

   -DBUNDLE_SKIP_GEOS-AERO=OFF
   -DBUNDLE_SKIP_ROPP-UFO=OFF

.. _controltesting:

Controlling the testing
-----------------------

MACOM-JEDI comes with tiered testing. The level of testing that will be compiled is chosen by setting
the environment variable :code:`MACOMJEDI_TEST_TIER`. The value can be set to 1 or 2. All tests
up to including the value in :code:`MACOMJEDI_TEST_TIER` will be built. Note that it is not necessary
to manually run ecbuild again after changing the environment variable. It would be sufficient to
touch one of the CMakeLists.txt files in MACOM-JEDI, which will trigger cmake automatically.

Most of the tests that run in MACOM-JEDI require 6 processors, 1 per face of the cube. Some of the
ensemble or parallel tests use a larger number, in some cases as many as 24. It is possible to skip
these tests on systems that may not be able to support them with the following flag:

.. code::

   ecbuild -DBUILD_LARGE_TESTS=OFF