6.5. timesteps.nml

This file sets the start and end time of the run. It can also be used to specify an optional spin-up procedure. It contains two namelists called JULES_TIME and JULES_SPINUP.

Warning

It is recommended that all times use Greenwich Mean Time (GMT or UTC), not local time. The use of GMT is essential if certain options are set.

6.5.1. JULES_TIME namelist members

JULES_TIME::timestep_len

Type:integer Permitted:>= 1 Default:None

Model timestep length in seconds.

Typically, 30 or 60 minutes is chosen, depending on the driving data available.

Warning

If the timestep is too long, the model becomes numerically unstable.

JULES_TIME::main_run_start

JULES_TIME::main_run_end

Type:character Default:None

The start and end times for the integration.

Each run of JULES consists of an optional spin-up period and the ‘main run’ that follows the spin-up. See below for more about the specification of the spin-up. These variables specify the start and end times for the ‘main run’.

The times must be given in the format:

"yyyy-mm-dd hh:mm:ss"

JULES_TIME::phenol_period

Type:integer Permitted:>= 1 Default:None

Period for calls to phenology model in days. Only relevant if l_phenol = TRUE.

JULES_TIME::triffid_period

Type:integer Permitted:>= 1 Default:None

Period for calls to TRIFFID model in days. Only relevant if one of l_triffid or l_trif_eq is TRUE.

JULES_TIME::print_step

Type:integer Permitted:>= 1 Default:1

Number of timesteps between printing timestep information to screen, i.e. if print_step = 48, then the timestep start time will only be printed every 48 timesteps.

6.5.2. JULES_SPINUP namelist members

JULES_SPINUP::max_spinup_cycles

Type:integer Permitted:>= 0 Default:0

The maximum number of times the spin-up period is to be repeated:

0

No spin-up.

> 0

At least 1 and at most max_spinup_cycles repetitions of spin-up are used.

After each repetition, the model tests whether the selected variables have changed by more than a specified amount over the last repetition (see tolerance below).

If the change is less than this amount, the model is considered to have spun up and the model moves on to the main run.

JULES_SPINUP::spinup_start

JULES_SPINUP::spinup_end

Type:character Default:None

Only used if max_spinup_cycles > 0.

The start and end times for each cycle of spin-up.

The times must be given in the format:

"yyyy-mm-dd hh:mm:ss"

JULES_SPINUP::terminate_on_spinup_fail

Type:logical Default:F

Only used if :nml:mem`max_spinup_cycles` > 0.

Switch controlling behaviour if the model does not pass the spin-up test after max_spinup_cycles of spin-up.

TRUE

End the run if model has not spun up.

FALSE

Continue the run regardless.

Variables used to specify spin-up conditions

JULES_SPINUP::nvars

Type:integer Permitted:>= 0 Default:0

Only used if max_spinup_cycles > 0.

The number of variables to use to assess if the model has spun up.

JULES_SPINUP::var

Type:character(nvars) Default:None

Only used if nvars > 0.

List of variables to be used to determine if the model has spun up. Spin-up can be assessed in terms of soil temperature and soil moisture.

Possible values are:

smcl

Moisture content of each soil layer (kg m^-2).

t_soil

Temperature of each soil layer (K).

JULES_SPINUP::use_percent

Type:logical(nvars) Default:F

Only used if nvars > 0.

Indicates whether the tolerance for each variable is expressed as a percentage.

TRUE

Tolerance is a percentage.

FALSE

Tolerance is an absolute value.

JULES_SPINUP::tolerance

Type:real(nvars) Default:None

Only used if nvars > 0.

Tolerance for spin-up test for each variable.

For each spin-up variable, this is the maximum allowed change over a spin-up cycle if the variable is to be considered as spun-up.

6.5.3. Note on time conventions

When specifying start times (e.g. main_run_start, spinup_start), the time is taken to be the start of the first timestep. When specifying end times (e.g. main_run_end, spinup_end), the time is taken to be the end of the last timestep. Take the following setup:

&JULES_TIME
  timestep_len   = 3600,
  main_run_start = "1997-01-01 00:00:00",
  main_run_end   = "1998-01-01 00:00:00",

  # ...
/

With this setup, exactly one whole year of timesteps will be run. The first model timestep begins at 1997-01-01 00:00:00, the second at 1997-01-01 01:00:00 etc. The final model timestep begins at 1997-12-31 23:00:00 and ends at 1998-01-01 00:00:00. No processing occurs for any times in 1998.

6.5.4. Note on solar zenith angle

If a run requires that the solar zenith angle be calculated (l_cosz = TRUE), then times must be in Greenwich Mean Time (UTC), so that the code can calculate the zenith angle at each location and time.

If l_cosz = FALSE, the user might prefer to use local time, particularly if this is used for input or validation data, as the timestamp on model output will then match that on the other data. However the use of local time is not recommended as if the user later switches to l_cosz = TRUE without adjusting the time values, the model results will be in error.

6.5.5. Examples

For all these examples, it is assumed that l_phenol = FALSE and l_triffid = FALSE, hence we do not need to specify phenol_period or triffid_period as they will not be used.

6.5.5.1. A run without spin-up

&JULES_TIME
  timestep_len   = 3600,
  main_run_start = "1997-01-01 00:00:00",
  main_run_end   = "1999-01-01 01:00:00"
/

&JULES_SPINUP
  max_spinup_cycles = 0
/

This specifies a run with a timestep length of one hour. The run will begin at midnight on 1st January 1997 and end at 01:00 GMT on 1st January 1999. max_spinup_cycles = 0 means there is no spin-up.

6.5.5.2. A run with spin-up over a period that immediately precedes the main run

&JULES_TIME
  timestep_len   = 3600,
  main_run_start = "1997-01-01 00:00:00",
  main_run_end   = "1999-01-01 01:00:00"
/

&JULES_SPINUP
  max_spinup_cycles = 5,
  spinup_start      = "1996-01-01 00:00:00",
  spinup_end        = "1997-01-01 00:00:00"

  # <spinup variable specification>
/

This specifies a spin-up period from midnight on 1st January 1996 to midnight on 1st January 1997. This spin-up will be repeated up to 5 times, before the main run from midnight on 1st January 1997 until 01:00 GMT on 1st January 1999.

6.5.5.3. A run with spin-up over a period that overlaps the main run

&JULES_TIME
  timestep_len   = 3600,
  main_run_start = "1997-01-01 00:00:00",
  main_run_end   = "1999-01-01 01:00:00"
/

&JULES_SPINUP
  max_spinup_cycles = 5,
  spinup_start      = "1997-01-01 00:00:00",
  spinup_end        = "1998-01-01 00:00:00"

  # <spinup variable specification>
/

This specifies a spin-up period from midnight on 1st January 1997 to midnight on 1st January 1998. This spin-up will be repeated up to 5 times, before the main run from midnight on 1st January 1997 until 01:00 GMT on 1st January 1999.

6.5.5.4. Example of specifying requirements for spin-up

&JULES_SPINUP
  # <spinup time specification>

  terminate_on_spinup_fail = T,

  nvars = 2,
  var         = "smcl"  "t_soil",
  use_percent =     F         T ,
  tolerance   =   1.0       0.1
/

With this setup, terminate_on_spinup_fail = TRUE means that if the spin-up has not ‘converged’ after max_spinup_cycles cycles, the run will end. Convergence is measured using the moisture content and temperature of each soil layer. At every point and in every layer, soil moisture must change by less than 1 kg m^-2, while soil temperature must change by less than 0.1%.

6.5.6. Notes on spin-up

Spin-up is assessed using the difference between instantaneous values at the end of consecutive cycles of spin-up. For example, if the spin-up period is from 2005-01-01 00:00:00 to 2006-01-01 00:00:00 then every time the model gets to the end of 2005 the spin-up variables are compared with their value at the end of the previous cycle. The model is considered spun-up when all the spin-up variables are spun-up at all points. A spin-up variable is considered spun-up if, at each point, the absolute value of the change (percentage change if use_percent = TRUE) over the spin-up cycle is less than or equal to the given tolerance.

At present the analysis of whether the model has spun up or not is limited to aspects of the ‘physical’ state of the system, and does not explicitly consider carbon stores, making it less useful for runs with interactive vegetation (the equilibrium mode of TRIFFID is designed to spin-up TRIFFID) or prognostic soil carbon.

During the spin-up phase of a run, JULES provides the correct driving data (for example, meteorological data) as the model time ‘cycles’ round over the spin-up period. Consider the case of a spin-up from 2005-01-01 00:00:00 to 2006-01-01 00:00:00. At or near the end of 31st December 2005 during the spin-up, the driving data will start to adjust to the values for 1st January 2005. The calculated driving data may vary slightly between the start or end of the first cycle and similar times in later cycles, because of the need to match the data at the end of each cycle to that at the start of the next cycle. When the main run begins after a period of spin-up, the driving data is reset to the start of the main run - no effort is made to adjust the data for a smooth transition. Generally this does not cause a problem.

Depending upon the details of the input data and any temporal interpolation, the driving data may vary rapidly at the end of a cycle of spin-up, causing an extreme response from the model. In most cases the model will adjust, possibly with large heat fluxes over a few hours, but the user should be aware that unusual behaviour near the end/start of a spin-up cycle may be the result of this adjustment. Consider the case of a spin-up from 2005-01-01 00:00:00 to 2006-01-01 00:00:00. At or near the end of 31st December 2005 during the spin-up, the driving data will start to adjust to the values for 1st January 2005, which could be very different from conditions on 31st December 2005. The length of time over which the driving data adjust depends on the frequency of the data, and the choice of temporal interpolation. For example, with 3-hourly data that is interpolated onto a one hour timestep, the adjustment will take place over 3 hours. However, hourly data and an hourly timestep will force an instantaneous adjustment at the start of 1st January 2005.

Although max_spinup_cycles specifies the maximum number of spin-up cycles, some of which might not be used if the model is considered to have spun up earlier, it is possible to specify the exact number of cycles that will be performed. This can be done by demanding an impossible level of convergence by setting tolerance < 0 (remember that tolerance is compared with the absolute change over a cycle) and setting terminate_on_spinup_fail = FALSE so that the integration continues when spin-up is judged to have failed after max_spinup_cycles cycles.

Although it is expected that a spin-up phase will be followed by the main run in the same integration, it is possible to do the spin-up and main run in separate integrations. This can be done by demanding an impossible level of convergence by setting tolerance < 0 and setting terminate_on_spinup_fail = TRUE so that the integration stops when spin-up is judged to have failed. The final state of the model, after max_spinup_cycles cycles of spin-up, will be written to the final dump, and a subsequent simulation can be started from this dump.

A limitation of the current code is that it cannot cope with a spin-up cycle that is short in comparison to the period of any input data. For example, a spin-up cycle of 1 day cannot use 10-day vegetation data. The code will likely run but the evolution of the vegetation data will probably not be what the user intended! However, it is unlikely that a user would want to try such a run.

Occasionally, the model fails to diagnose a spun up state when in fact the integration has reached a quasi-steady state that is not detected by the procedure of assessing spin-up through comparison of instantaneous values at the end of consecutive cycles of spin-up. An example of this is ‘period-2’ behaviour, where the model state repeats itself over a period of 2 cycles. Such behaviour should be apparent in the model output during spin-up, and the user can opt to repeat the integration over a given number of spin-up cycles, and not to wait for a spun-up state to be diagnosed.