OR/14/007 Model files: Difference between revisions

From MediaWiki
Jump to navigation Jump to search
No edit summary
(One intermediate revision by the same user not shown)
Line 6: Line 6:
All of the information required to configure and run AquiMod is stored in a series of text files within a defined folder structure (Figure 5.1). The Observations.txt file contains all of the available observational data including rainfall, PET, groundwater level and abstraction rates. The Input.txt file allows the user to specify a number of options such as which module components and simulation mode they wish to use. The files stored in the Calibration and Evaluation folders are only used when AquiMod is set to run in these respective modes. They contain ranges or specific parameter values to be used by AquiMod when running in calibration and evaluation mode respectively. Finally, the Output folder is where all model outputs are generated.
All of the information required to configure and run AquiMod is stored in a series of text files within a defined folder structure (Figure 5.1). The Observations.txt file contains all of the available observational data including rainfall, PET, groundwater level and abstraction rates. The Input.txt file allows the user to specify a number of options such as which module components and simulation mode they wish to use. The files stored in the Calibration and Evaluation folders are only used when AquiMod is set to run in these respective modes. They contain ranges or specific parameter values to be used by AquiMod when running in calibration and evaluation mode respectively. Finally, the Output folder is where all model outputs are generated.


[[Image:14007 fig5.1.png|thumb|center|500px|'''Figure 5.1''' Folder structure of AquiMod.]]
[[Image:14007 fig5.1.png|thumb|center|500px|'''Figure 5.1'''    Folder structure of AquiMod.]]


==Input files==
==Input files==


===5.2.1 Observations.txt===
===Observations.txt===
Before running AquiMod, the user must specify four observation time-series as shown in Table 5.1. These time-series can be summarised as follows:
Before running AquiMod, the user must specify four observation time-series as shown in Table 5.1. These time-series can be summarised as follows:
* '''Climate (rainfall and PET)'''
* '''Climate (rainfall and PET)'''
Line 24: Line 24:
The number of observations must also be input on line 2. In the example shown in Table 5.1, a total of 540 time-steps are specified which run from January 1961.
The number of observations must also be input on line 2. In the example shown in Table 5.1, a total of 540 time-steps are specified which run from January 1961.


<center>
{| class="wikitable"
{| class="wikitable"
 
|+ Table 5.1&nbsp;&nbsp;&nbsp;&nbsp;Example Observations.txt file.
|+ Table 5.1 Example Observations.txt file.
| '''Line number'''  
| '''Line number'''  
| colspan="7" | '''File text'''
| colspan="7" | '''File text'''
Line 111: Line 111:
| .
| .
|}
|}
</center>


The Observations.txt file can also be used to specify a number of other conditions including:
The Observations.txt file can also be used to specify a number of other conditions including:
Line 123: Line 124:
As well as initialising the model with the observed groundwater levels, it is also possible to impose observed groundwater levels mid-simulation. By doing so, the model discards the simulated level for that time-step and uses the observed level instead. This can be done at one or more time-steps by placing an asterisk at the end of the corresponding row(s) in Observations.txt (Table 5.2).
As well as initialising the model with the observed groundwater levels, it is also possible to impose observed groundwater levels mid-simulation. By doing so, the model discards the simulated level for that time-step and uses the observed level instead. This can be done at one or more time-steps by placing an asterisk at the end of the corresponding row(s) in Observations.txt (Table 5.2).


<center>
{| class="wikitable"
{| class="wikitable"
|+ Table 5.2 Imposing groundwater levels in the Observations.txt file.
|+ Table 5.2&nbsp;&nbsp;&nbsp;&nbsp;Imposing groundwater levels in the Observations.txt file.
| '''Line number'''
| '''Line number'''
| colspan="8" |'''File text'''
| colspan="8" |'''File text'''
Line 210: Line 212:
| .
| .
|}
|}
</center>


===Input.txt===
===Input.txt===
Line 240: Line 243:
Here, the user can specify if they wish output files to be written for each model component. When running in calibration mode, a single file is output for each component. In evaluation mode, a separate file is output for each model component and model run which may slow down the overall model run-time.
Here, the user can specify if they wish output files to be written for each model component. When running in calibration mode, a single file is output for each component. In evaluation mode, a separate file is output for each model component and model run which may slow down the overall model run-time.


<center>
{| class="wikitable"
{| class="wikitable"
|+ Table 5.3 Example Input.txt file.
|+ Table 5.3&nbsp;&nbsp;&nbsp;&nbsp;Example Input.txt file.
| '''Line number'''
| '''Line number'''
| '''File text'''
| '''File text'''
Line 362: Line 366:
| N = no do not write output file
| N = no do not write output file
|}
|}
</center>


===Calibration input files===
===Calibration input files===
Line 368: Line 373:
Note that template files for all module components can be downloaded from the AquiMod website.
Note that template files for all module components can be downloaded from the AquiMod website.


<center>
{| class="wikitable"
{| class="wikitable"
|+ Table 5.4 Example of the FAO_calib.txt calibration input file format. The field capacity (line 2) is fixed while the root depth (line 8) will change for each calibration run.
|+ Table 5.4&nbsp;&nbsp;&nbsp;&nbsp;Example of the FAO_calib.txt calibration input file format. The field capacity (line 2) is fixed while the root depth (line 8) will change for each calibration run.
! Line number || File text || Description
! Line number || File text || Description
|-
|-
Line 400: Line 406:
| 14 || 0.7 0.9  || Minimum and maximum value
| 14 || 0.7 0.9  || Minimum and maximum value
|}
|}
</center>


===5.2.4  Evaluation input files===
===5.2.4  Evaluation input files===
In evaluation mode, AquiMod requires the user to specify one or more parameter sets using input text files for each module component. These files must be located in the Evaluation folder and they follow a standard naming convention: *_eval.txt where the asterisk should be replaced by the component name. Table 5.5 provides an example of the FAO_eval.txt file. Here only a single parameter set is defined, but multiple parameter sets can be included on separate lines (e.g. see Section 6.2).
In evaluation mode, AquiMod requires the user to specify one or more parameter sets using input text files for each module component. These files must be located in the Evaluation folder and they follow a standard naming convention: *_eval.txt where the asterisk should be replaced by the component name. Table 5.5 provides an example of the FAO_eval.txt file. Here only a single parameter set is defined, but multiple parameter sets can be included on separate lines (e.g. see Section 6.2).


<center>
{| class="wikitable"
{| class="wikitable"
|+ Table 5.5 Example of FAO_eval.txt file.
|+ Table 5.5&nbsp;&nbsp;&nbsp;&nbsp;Example of FAO_eval.txt file.
| '''Line number'''
| '''Line number'''
| '''File text'''
| '''File text'''
Line 430: Line 438:
| Parameter values
| Parameter values
|}
|}
</center>


==Onput files==
==Onput files==
Line 439: Line 448:
Note that the file structure is identical to the evaluation input files. This allows for easy transfer between calibration and evaluation modes (see Section 6.2).
Note that the file structure is identical to the evaluation input files. This allows for easy transfer between calibration and evaluation modes (see Section 6.2).


 
<center>
{| class="wikitable"
{| class="wikitable"
|+ Table 5.6 Example of FAO_calib.out file.
|+ Table 5.6&nbsp;&nbsp;&nbsp;&nbsp;Example of FAO_calib.out file.
| '''Line number'''
| '''Line number'''
| '''File text'''
| '''File text'''
Line 491: Line 500:
| .
| .
|}
|}
</center>


In conjunction with the module component output files, a fit_calib.out file is also produced (see example in Table 5.7) which lists the corresponding objective function scores of the acceptable parameter sets obtained.
In conjunction with the module component output files, a fit_calib.out file is also produced (see example in Table 5.7) which lists the corresponding objective function scores of the acceptable parameter sets obtained.


<center>
{| class="wikitable"
{| class="wikitable"
|+ Table 5.7 Example of fit_calib.out file produced by AquiMod using the NSE objective function.
|+ Table 5.7&nbsp;&nbsp;&nbsp;&nbsp;Example of fit_calib.out file produced by AquiMod using the NSE objective function.
| '''Line number'''
| '''Line number'''
| '''File text'''
| '''File text'''
Line 528: Line 539:
| .
| .
|}
|}
</center>


===Evaluation output files===
===Evaluation output files===
Line 534: Line 546:
A corresponding fit_eval.out file is also produced which returns the objective function score for each parameter set. The structure of this file is identical to that for a calibration run (Table 5.6).
A corresponding fit_eval.out file is also produced which returns the objective function score for each parameter set. The structure of this file is identical to that for a calibration run (Table 5.6).


<center>
{| class="wikitable"
{| class="wikitable"
|+ Table 5.8 Example of Q3K3S1_TimeSeries1.out from an evaluation run.
|+ Table 5.8&nbsp;&nbsp;&nbsp;&nbsp;Example of Q3K3S1_TimeSeries1.out from an evaluation run.
| '''Line number'''
| '''Line number'''
| '''File text'''
| '''File text'''
Line 626: Line 639:
| .
| .
|}  
|}  
 
</center>


[[Category:OR/14/007_AquiMod User Manual (v1.0)| 05]]
[[Category:OR/14/007_AquiMod User Manual (v1.0)| 05]]

Revision as of 08:56, 20 October 2021

Mackay, J D, Jackson, C R, and Wang, L. 2014. AquiMod User Manual (v1.0). Nottingham, UK, British geological Survey. (OR/14/007).

This section provides more details about the model files that are used to configure AquiMod as well as the output files produced by the software. Most text editors are suitable for reading and editing AquiMod files, although it is advantageous to use an editor that displays line numbers as these are used in the file tables in this section. Examples include Notepad++ and PSPad, both of which are freely available to download from the internet.

General file and folder structure

All of the information required to configure and run AquiMod is stored in a series of text files within a defined folder structure (Figure 5.1). The Observations.txt file contains all of the available observational data including rainfall, PET, groundwater level and abstraction rates. The Input.txt file allows the user to specify a number of options such as which module components and simulation mode they wish to use. The files stored in the Calibration and Evaluation folders are only used when AquiMod is set to run in these respective modes. They contain ranges or specific parameter values to be used by AquiMod when running in calibration and evaluation mode respectively. Finally, the Output folder is where all model outputs are generated.

Figure 5.1    Folder structure of AquiMod.

Input files

Observations.txt

Before running AquiMod, the user must specify four observation time-series as shown in Table 5.1. These time-series can be summarised as follows:

  • Climate (rainfall and PET)

A continuous time-series of rainfall and PET data is required to drive the model, specified in units of mm d-1.

  • Groundwater levels

At least one time-stamped measurement of groundwater level is required specified in units of metres above a datum. AquiMod uses these data to calculate the specified objective function. Where measurements are not available, a -9999 value should be entered.

  • Abstraction rates

A continuous abstraction rate time-series specified in units of m3 d-1 is required. This is subtracted from the saturated zone component during simulation.

The number of observations must also be input on line 2. In the example shown in Table 5.1, a total of 540 time-steps are specified which run from January 1961.

Table 5.1    Example Observations.txt file.
Line number File text Description
1 NUMBER OF OBSERVATIONS Comment Line
2 540 Number of time-steps for simulation
3 DAY MONTH YEAR RAIN PET GWL ABS Headers for columns
4 31 1 1961 4.8 0.42 70.7 0.0 [day, month, year, rain (mm d-1), PET (mm d-1), groundwater level (m), groundwater abstraction rate (m3 d-1)]
5 28 2 1961 3.1 0.54 67.6 0.0 .
6 31 3

1961 0.07 1.1 59.3 0.0 .
. . .
. . .

The Observations.txt file can also be used to specify a number of other conditions including:

MODEL TIME-STEP

The model time-step is defined by the length of time between each time-stamp in the Observations.txt file. The minimum time-step is one day and the time-step length can vary throughout the simulation sequence. Note that in Table 5.1, the model has been configured to run on a monthly time-step, producing groundwater level simulations at the end of each month.

INITIAL CONDITIONS

AquiMod assumes a dry soil and unsaturated zone initially. The saturated zone is always initialised at the first time-step where an observed groundwater level measurement is available in Observations.txt. If this is not the first time-step, as well as initialising the model at the first groundwater level observation, AquiMod also uses the mean of all available groundwater level data in Observations.txt to initialise the model at the first time-step. In the example, the first time-step has a groundwater level measurement of 70.7 m, and as such this is used to initialise the saturated zone component.

IMPOSED GROUNDWATER LEVELS

As well as initialising the model with the observed groundwater levels, it is also possible to impose observed groundwater levels mid-simulation. By doing so, the model discards the simulated level for that time-step and uses the observed level instead. This can be done at one or more time-steps by placing an asterisk at the end of the corresponding row(s) in Observations.txt (Table 5.2).

Table 5.2    Imposing groundwater levels in the Observations.txt file.
Line number File text Description
1 NUMBER OF OBSERVATIONS
2 540
3 DAY MONTH YEAR RAIN PET GWL ABS
4 31 1 1961 4.8 0.42 70.7 0.0
5 28 2 1961 3.1 0.54 67.6 0.0 * Here the simulated groundwater level will be discarded and set to the observed level
6 31 3 1961 0.07 1.1 59.3 0.0 .
. . .
. . .

Input.txt

The Input.txt file is where the user can specify a number of different options, each indicated by a corresponding header line (Table 5.3). These are detailed as follows:

  • Component IDs

The ID numbers for the desired soil, unsaturated and saturated zone components as indicated in the Tables in section 3. For example, in Table 5.3 all have been set to 1 which indicates that the FAO, Weibull and Q3K3S1 components are to be used.

  • Simulation mode

Here, the choice of either calibration (‘c’) or evaluation (‘e’) mode is specified.

  • Number of runs

The number of runs can range from 1 to approximately 107 (the maximum in calibration mode is dependent on available computer memory).

  • Objective function

Here, the objective function used to evaluate the model simulations against the observed levels in Observations.txt is specified.

  • Spin-up period

Due to the fact that the soil and unsaturated zone components are initiated without any water in them, there is an initial wetting-up period, or spin-up period where AquiMod may not be able to simulate the groundwater level time-series adequately which can result in poor optimization of the model parameters when running in calibration mode. To prevent this, the length of this period should be specified as a number of time-steps. AquiMod will then ignore this portion of the simulation when calculating the chosen objective function.

The length of this period is likely to depend on the choice of model structure and parameters. Past experience has shown that the unsaturated zone component often has the longest 'memory' of the three components in AquiMod. For example, when using the Weibull unsaturated zone component, the n parameter, which defines the number of time-steps over which recharge is spread, can also be used to define the spin-up period (see section 6.1 for further information on defining the spin-up period).

  • Acceptable model threshold

This option is only applicable when running AquiMod in the Monte Carlo calibration mode. It defines the objective function threshold that must be reached, for the parameter set of the simulation to be stored and output.

  • Maximum number of acceptable models

This option is only applicable when running AquiMod in the Monte Carlo calibration mode. It defines the maximum number of parameter sets that exceed the acceptable threshold that will be output. Note that AquiMod uses the quick sort algorithm to sort the Monte Carlo runs by objective function. Simulation time may increase if large numbers of acceptable parameter sets are stored.

  • Write model output files

Here, the user can specify if they wish output files to be written for each model component. When running in calibration mode, a single file is output for each component. In evaluation mode, a separate file is output for each model component and model run which may slow down the overall model run-time.

Table 5.3    Example Input.txt file.
Line number File text Description
1 Component IDs Comment Line
2 1 1 1 Module component selection [Soil, Unsat., Sat.] (integers)
3 Blank
4 Simulation mode Comment Line
5 e Simulation mode
c = calibration
e = evaluation
6 Blank
7 Number of runs Comment Line
8 1 Number of model runs (for calibration and evaluation modes)
1 to ~107 (integer)
9 Blank
10 Objective function Comment Line
11 1 Objective function ID (integer)
12 Blank
13 Spin-up period Comment Line
14 6 Spin up period over which objective function will not be calculated.
number of time-steps (integer)
15 Blank
16 Acceptable model threshold (calibration only) Comment Line
17 0.9 Objective function which must be reached for results to be output (float)
18 Blank
19 Maximum number of acceptable models (calibration only) Comment Line
20 1 Maximum number of acceptable models output from calibration mode (integer)
21 Blank
22 Write model output files Comment Line
23 Y Y Y Switch for writing output files [Soil, Unsat., Sat.]
Y = yes write output file
N = no do not write output file

Calibration input files

When running in calibration mode, a separate input file for each module component must be configured in the Calibration folder. These files specify the range of values from which the Monte Carlo parameter sets are randomly sampled (see Appendix 1 for a list of recommended ranges). All files have the same naming convention: *_calib.txt where the asterisk should be replaced by the component name. An example of the FAO_calib.txt calibration input file is given in Table 5.4. Note the general structure: header lines followed by two numerical values which specify the maximum and the minimum of the range of values to be sampled randomly. Also note that parameters can be fixed simply by specifying the same minimum and maximum values, as has been done for the field capacity parameter.

Note that template files for all module components can be downloaded from the AquiMod website.

Table 5.4    Example of the FAO_calib.txt calibration input file format. The field capacity (line 2) is fixed while the root depth (line 8) will change for each calibration run.
Line number File text Description
1 Field Capacity(-) Comment Line
2 0.31 0.31 Minimum and maximum value
3 Blank
4 Wilting Point(-) Comment Line
5 0.1 0.2 Minimum and maximum value
6 Blank
7 Root Depth(mm) Comment Line
8 100 3000 Minimum and maximum value
9 Blank
10 Depletion Factor(-) Comment Line
11 0.01 0.99 Minimum and maximum value
12 Blank
13 Baseflow index(-) Comment Line
14 0.7 0.9 Minimum and maximum value

5.2.4 Evaluation input files

In evaluation mode, AquiMod requires the user to specify one or more parameter sets using input text files for each module component. These files must be located in the Evaluation folder and they follow a standard naming convention: *_eval.txt where the asterisk should be replaced by the component name. Table 5.5 provides an example of the FAO_eval.txt file. Here only a single parameter set is defined, but multiple parameter sets can be included on separate lines (e.g. see Section 6.2).

Table 5.5    Example of FAO_eval.txt file.
Line number File text Description
1 FieldCapacity(-) WiltingPoint(-) MaxRootDepth(mm) DepletionFactor(-) BaseflowIndex(-) Header Line
2 0.31 0.15 2000.0 0.6 0.85 Parameter values

Onput files

After executing the AquiMod software, a series of output files will be generated in the Output folder (the number of files generated depends on the user specifications in Input.txt). All output files use the ‘.out’ file extension.

Calibration output files

Assuming that the output file switches in the input.txt file have all been set to ‘Y’, AquiMod will produce a single output file for each module component selected for a calibration run. These files follow the naming convention *_calib.out where the asterisk is replaced by the component name. An example Weibull_calib.out file is shown in Table 5.6. Within these files, the parameter sets that resulted in a simulation that met acceptable model threshold (as defined in input.txt) are listed.

Note that the file structure is identical to the evaluation input files. This allows for easy transfer between calibration and evaluation modes (see Section 6.2).

Table 5.6    Example of FAO_calib.out file.
Line number File text Description
1 k(-) lambda(-) n(timesteps) Header Line
2 2.78 2.43 6 Parameter values
3 4.43 2.10 6 .
4 6.49 1.64 6 .
5 3.12 2.06 6 .
. . .

In conjunction with the module component output files, a fit_calib.out file is also produced (see example in Table 5.7) which lists the corresponding objective function scores of the acceptable parameter sets obtained.

Table 5.7    Example of fit_calib.out file produced by AquiMod using the NSE objective function.
Line number File text Description number
1 ObjectiveFunction Header Line
2 0.913 Objective function score
3 0.912 .
4 0.908 .
5 0.907 .
. . .
. . .

Evaluation output files

Assuming that the output file switches in the input.txt file have all been set to ‘Y’, AquiMod will produce a time-series output files for each parameter set specified in the *_eval.txt files and each module component selected for a given evaluation run. These files follow the naming convention *1_TimeSeries*2.out where *1 is the component name and *2 is the model run number. An example of the Q3K3S1 output file for parameter set 1 is shown in Table 5.8. Note that here the output variables include the simulated discharges from the three outlets and the groundwater level time-series. For more information on the output variables produced for each module component see Appendix 2.

A corresponding fit_eval.out file is also produced which returns the objective function score for each parameter set. The structure of this file is identical to that for a calibration run (Table 5.6).

Table 5.8    Example of Q3K3S1_TimeSeries1.out from an evaluation run.
Line number File text Description
1 Day Month Year Q3(m3/d) Q2(m3/d) Q1(m3/d) GWL(m) Header Line
2 31 1 1961 0 0 0 70.665 Variable values
3 28 2 1961 4.82748 5.21203 0.248902 61.1048 .
4 31 3 1961 0.893412 4.06564 0.219899 55.6219 .
5 30 4 1961 0.0516189 3.40817 0.203265 53.9034 .
6 31 5 1961 4.61944e-006 3.20209 0.198052 50.2362 .
. .
. . .