Code organization and design philosophy

Table of Contents ED2 code structure The src directory The build directory Good coding practices

ED2 code structure

The ED2 code is mostly written in Fortran 95, with very few file handling utilities that are written in C language. New contributions to the code should be all written in standard Fortran 95, because ED has a unique data structure which is not easily ported to different languages. Also, make sure to check the [good]coding practices section (see below) before contributing.

The main ED2 directory (.../EDBRAMS/ED) is divided in the following subfolders:

• src: The source code directory;
• build: The compilation instructions;
• run: The directory containing a sample ED2IN namelist.
• Template: A few system-specific utilities for setting multiple simulations.

The src directory

The source code directory, in turn, is divided in several sub-folders:

• driver : The main ED drivers. This directory contains the main program, and subroutines that organize the model initialization and the time step call.
• dynamics : Contains most subroutines that drive the ecosystem dynamics at various time steps.
• include : Contains some header files used by the very few functions written in C;
• init : Contains subroutines that will initialize various model variables and parameters;
• io : Contains the functions and subroutines that read and write files;
• memory : Contains all modules with the model global variables, and some functions that allocate and deallocate the global variables;
• mpi : Contains all the message-passing interface procedures needed for a parallel run.
• utils : Contains subroutines that don't really fit into any of the previous directories.
• preproc : Not part of the main code, it contains some basic tools needed to convert ASCII datasets into HDF5. Check the Drivers section for additional information on how to prepare meteorological drivers for ED2.

The build directory

The build directory has the following sub-folders and the install.sh script:

• make . This directory contain most compilation instructions:
  • paths.mk : This will set up all the folder structure for the compiler. Unless you are developing the code and has changed the code structure (i.e. added new directories), you don't need to change anything.
  • objects.mk : This file contains the list of all objects to be compiled. This shouldn't be changed unless you are developing the code and added a new fortran file;
  • rules.mk : This file contains the instructions on how to compile each object. Unless you are adding code that is in a new file, this should not be changed.
  • Makefile : This is the main instruction file, which will handle the compilation. Normally this file shouldn't be changed.
  • include.mk.[PLATFORM] : These are system (platform)-dependent files, which set the compiler, the compilation options, and the library paths for MPI and HDF5. You will likely need to edit one of them, or create a new file specific for the computer/cluster where you are going to run ED2.
• shell. This directory has a few shell and perl scripts used during the compilation. You do not need to run any of the scripts by themselves, they will be called by install.sh.
  • generate_deps.sh : This shell calls sfmakedepend.pl and creates the list of dependencies to set the order in which the fortran files must be compiled. Normally this file should not be changed.
  • sfmakedepend.pl : The perl script that actually creates the dependency list. Normally this file should not be changed.
  • 2ndcomp.sh : This partially cleans the compilation when checking interfaces. Unless you are adding code that is in a new file, this should not be changed.

The install.sh calls the Makefile as well as any script needed for compilation. Make sure to visit the compilation instructions page before running this script.

Good coding practices

We appreciate new contributions on model development, but we ask you to follow a few good coding practices. Below is a list of things to keep in mind when writing new code:

• Comments. Make sure to explain the rationale and the steps in the code. We are planning to make all comments in ED-2.2 compatible with Doxygen, so if you add new code in this format, it will help us.
• Modules. If you create sub-routines or functions that have pointers/targets as arguments, please put them inside a Fortran module. Also, for consistency with the rest of the code, use the same name for the Fortran file and the module name (i.e. module my_new_feature goes to file my_new_feature.f90).
• Variables. Make sure that all variables are declared (i.e. always use implicit none), and prefer to give intuitive names. Likewise, if you need to load variables from modules, make sure they are explicitly declared when you use the use command (i.e. always use the only statement).
• Constants. Never set physical constants (e.g. gravity acceleration, Avogrado's number) as undeclared numbers in the code, it is nearly impossible to track them. Instead, define them in ED/src/memory/consts_coms.F90 (and the constant you are looking for may be already there).
• Parameters. Similar to constants, but in this case do not include in consts_coms.F90. Importantly, do not use the parameter option when declaring the variable, and do not initialise the variable in the module. Instead, insert code in ED/src/init/ed_params.f90 to set the default value, and include code in ED/src/io/ed_xml_config.f90 to allow the variable to be read through xml.
• f90 or F90. For most files, the extension should be .f90. The only cases that you must use .F90 is when you include pre-processor instructions in the code. Currently in ED-2.2, this happens in the following cases:
  • Code that must be skipped if not compiled with MPI libraries. Example: ED/src/driver/ed_driver.F90
  • Code that must be compiled in case of coupled ED-BRAMS code. Example: ED/src/init/ed_init_atm.F90
  • System-dependent libraries. Example: ED/src/utils/rsys.F90
• Debug. Always compile the code with strict compilation settings, and make sure that the code runs for at least a few years under these settings. The code is going to run a lot slower, but it will catch common code mistakes.
• Clean the clutter. Once you are happy with your new code, make sure to remove any declared variable or module variable that is no longer used. This helps with code readability.