OR/14/007 Model files: Difference between revisions
Line 408: | Line 408: | ||
</center> | </center> | ||
=== | ===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). | ||
Latest revision as of 08:40, 22 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.
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.
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).
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.
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.
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 |
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).
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).
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.
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).
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 | . |
. | . | |||||||
. | . | . |