Skip to content

Quick start

Jump to bottom Edit New page
Marcos Longo edited this page Dec 2, 2025 · 3 revisions

Data Requirements for any ED2 simulation

The following data is the minimum necessary to start a simulation with near bare ground, for a single polygon.

  • Meteorology data with sub-daily resolution (recommended between 15 min to 1hr). The following data are needed:
    • Air temperature
    • Air pressure
    • Air specific humidity
    • Wind speed
    • Incoming solar (short wave) irradiaance
    • Incoming thermal (long wave) irradiance
    • Precipitation
  • ED2IN Namelist with the appropriate configuration.

Additional data required for a regional ED2 simulation

  • Land/sea fraction (only land points are solved by ED2)
  • Soil texture map (homogeneous soil type is an option, but not recommended)
  • Soil depth map (homogeneous soil depth is an option, but not recommended)
  • Soil colour map (homogeneous soil colour is an option, but not recommended)

Additional data required for a simulation with initial conditions other than near bare ground

  • Tree-level inventory data (minimum: species, DBH)
  • Soil Carbon stocks

Optional data (the model will use default values if these are not provided)===

  • Soil texture profile (assumed homogeneous if not provided).
  • Leaf phenology data
  • Model and PFT parameters
  • Land use change data (assumed inexistent if not provided).

File Requirements

From the data above you then need to build:

  • Meteorology/Radiation boundary condition files (hdf5)
  • ED2IN settings file
  • Soil texture, depth and colour databases (hdf5) OR Site file (*.sss, used when running with NL%IED_INIT_MODE = 8.)
  • Vegetation Initial Condition Files (*.pss, *.css) (optional).
  • XML parameter file (optional)
  • Phenology boundary conditions (optional)
  • Land Use boundary conditions (optional)

Computer Requirements

  • Fortran compiler. We recommend ifx (ifort in older systems) or gfortran.
  • C compiler. We recommend icx (icc in older systems) or gcc. Make sure that the C compiler is consistent with the Fortran compiler (i.e., pick icx if using ifx, or gcc if using gfortran).
  • HDF5. The HDF5 libraries must be compatible with the Fortran and C compilers.
  • Lapack. The Linear Algebra Packages. This is required when using gfortran and gcc. Most Intel compiler distributions come with Lapack libraries through the Intel Math Kernel Library.
  • MPI (optional). MPI libraries are only used in regional (multi-polygon) simulations. If this is your case, make sure that MPI libraries are compatible with the Fortran and C compilers you are using.

Code version

  • Check out most recent code using git following instructions available in this link.

Installing required programs and libraries on Ubuntu (Linux)

To compile the model on an Ubuntu machine, execute the following commands

sudo apt-get update                      # Updates application information
sudo apt-get install git                 # Skip if you have Git already
sudo apt-get install gcc                 # You probably want the latest <code>GCC</code>
sudo apt-get install gfortran            # You probably want the latest <code>gfortran</code>
sudo apt-get install libhdf5-openmpi-dev # In case it fails, try 'sudo apt-cache hdf5' to see what is available.
sudo apt-get install libhdf5-tools       # Installs e.g. h5dump, which you probably want. 
sudo apt-get install libblas-dev         # Installs the Basic Linear Algebra Subprograms (required by Lapack).
sudo apt-get install liblapack-dev       # Installs the Linear Algebra Package (aka lapack).

In case you want the MPI libraries:

sudo apt-get libopenmpi-dev    # The latest OpenMPI version with libraries
sudo apt-get openmpi-doc       # Documentation
sudo apt-get openmpi-bin       # Standalone binaries

Installing required programs and libraries on MacOS

To compile the model on a Mac, you must first install HomeBrew

brew update         # Updates application information
brew install git    # Skip if you have Git already
brew install gcc    # This will install `gcc` and `gfortran`.
brew install hdf5   # This will install HDF5 and its libraries 
brew install lapack # Installs the Linear Algebra Package (aka lapack).

In case you want the MPI libraries:

brew install open-mpi   # The latest OpenMPI version with libraries
sudo apt-get hdf5-mpi   # HDF5 with MPI support

Next, move to the directory in which you'd like to install ED and clone the main repo:

git clone https://github.com/EDmodel/ED2.git

To install ED2, you must have the following library files:

  • libhdf5.a (Linux) or libhdf5.dylib (MacOS)
  • libhdf5_fortran.a or libhdf5_fortran.dylib (MacOS)
  • libhdf5_hl.a or libhdf5_hl.dylib (MacOS)

If using GNU-based Fortran and C, you must have the following library files too:

  • libblas.a (Linux) or libblas.dylib (MacOS)
  • liblapack.a (Linux) or liblapack.dylib (MacOS)

In most cases, these libraries will be in one of the following standard paths: /usr/lib, /usr/local/lib. If using a MacBook with an Apple Silicon processor, most libraries should be in /opt/homebrew/lib, whereas lapack libraries may be at /opt/homebrew/opt/lapack/lib. In case the libraries are not in any of these paths, contact your system's administrator for guidance.

Installing ED2

Preparing the compiler instructions

Once you've cloned the mainline and set up the compilers, HDF5 libraries, and optionally the MPI libraries, navigate to ED2/ED/build/make. There are a few templates of files based on the operational system and family of compilers:

  • include.mk.gnu. Linux using gfortran and gcc
  • include.mk.intel. Linux using ifx and icx
  • include.mk.macos. MacOS using one version of gfortran and gcc

Select the one that is the closest to your system, and copy it to a unique file in the same directory. For example: (cd /path/to/ED2/ED/build/make; cp include.mk.gnu include.mk.mylab) Then make sure to edit it. For more information, check the compiler instructions page.

Compiling ED2

To compile ED2, navigate to ED2/ED/build/make, where you should find the install.sh script.

The install.sh script calls Makefile as well as any script needed for compilation. The install.sh script accepts the following options.

  • -p [PLATFORM] or --platform [PLATFORM]. This selects with platform (system) to use. There must be an include.mk.[PLATFORM] file in the ED2/ED/build/make directory. For example, if you copied the file to include.mk.mylab, set -p mylab. In case no platform is provided, the script assumes --platform gnu.
  • -c or --clean. This removes the compilation defined by the platform.
  • -k [KIND] or --kind [KIND]. For some platforms, there are multiple pre-defined options to compile more strict checks (useful for debugging) or less strict checks (useful for production). Typically KIND = A is the most strict option, and KIND = E is the least strict (fastest) option. If not provided, the installation will assume --kind E.
  • -g or --gitoff. Use this option in case you do not want the git commit label attached to the executable name.
  • -s [STEP] or --step [STEP]. This option is used only when the code is being compiled with interface check settings (normally ifx or ifort compiler with --kind A). To thoroughly check interfaces, you must compile the code in 3 steps. 1. Generate interfaces; 2. Clean compilation except for the interface modules; 3. Re-compile, this time checking interfaces.

For example, in case you want to compile the model with fast (not debugging) options using include.mk.intel and attach the GitHub label, type:

./install.sh -k E -p intel

If installation is successful, you should see a message similar to this:

Finished building === ed_2.2-opt-master-e6xy61a9

Also, note that you can also set multiple working versions. Additional details at Using Github with ED2

Running ED-2

Serial run

Single polygon runs must be run in serial mode. To run this, simply copy or link the executable (for example, ed_2.2-opt-master-e6xy61a9 to the same directory where the ED2IN file you modified is located, then type:

> ./ed_2.2-opt-master-e6xy61a9

In case your namelist is called anything other than ED2IN (e.g., my-ED2IN, you must provide the correct name using the -f option

> ./ed_2.2-opt-master-e6xy61a9 -f my-ED2IN

Parallel run

Regional runs can be run using MPI. In this case, you must submit the job with the mpirun command:

> mpirun -np [n] ./ed_2.2-opt-master-e6xy61a9

where [n] should be replaced with the number of processors to use. The -f option for invoking a non-standard namelist also works in parallel simulations. Users will rarely call the command above directly. Instead, they will likely need to submit a job to the queueing system (e.g., SLURM, PBS) of their high-performance computing (HPC) facility. Reach out to your HPC help desk for assistance.

Additional information about running on specific systems

Below is a partial list of systems in which ED2 has been used. Additional suggestions are welcome:

Add a custom footer
Add a custom sidebar

Clone this wiki locally