Adding Additional Chemical Species
The following document shows the necessary steps required to add a chemical species to the MyLake model. This will be demonstrated through the addition of Fe to the model. The following steps apply to the MyLake V1.2 model currently available on the Biogeochemical Modelling Collaboration as of September 2015, and can be found through the GitHub page: https://github.com/biogeochemistry under the repository MyLake_public. The final version of the MyLake model after the addition can be found on the same page under the repository MyLake_BN_Test.
The first step requires the addition of the desired species to the initialization files. These three files can be found within the program which utilizes the species (from this point assumed as iron/Fe). In the context of the MyLake_public repository, this contains the following three files within the Vansjo_application folder:
- VAN_init_v12.xlsx
- VAN_input_PGS84_00_v12.xlsx
- VAN_para_v12.xlsx
Within these files, add an entry for the new species in a logical location such that its format matches that of similar entries:
will become
These files all contain different information about the chemical you wish to add. Thus, we will go over each file to state exactly what you must add.
This file contains the initial concentrations of each chemical species separated by depth in units of mg/m3. The depth ‘slice’ can be seen in the first column under the header Z (m). There are two already established naming conventions within this file. Firstly, if an element is dissolved, simply type the name of the element followed by “z”. For example, to add dissolved iron, we could write Fez (mg/m3). Likewise, if the chemical species is a sediment, it follows the same naming pattern as above, but is appended by “_sed”. Thus, iron sediment can be written as Fez_sed (mg/m3). To add the desired species to the initialization file, insert a full column using Excel, shifting all other column information forward. One can then populate the desired data underneath the newly named column header. This data must be in the units of mg/m3 to assist with consistency, as well as ease with the modification of the code base. Remember where in the list the new species is added in relation to other species. This will allow the files to remain consistent.
This file contains three main groups of information. It is important to note that instead of depth dependant, this file is time dependant. The first three columns contain the date information, and columns 4-10 contain weather and external condition information. The columns which follow represent the inflow data, once again measured in mg/m3. The naming convention is “Inflow_” followed by the chemical name. As such, iron would be written as Inflow_Fe (mg/m3). Once again, to add the species to the inflow file, insert a column using Excel. If possible, add the column to a position which corresponds to the first file that was modified. For example, in the first model, the iron column was added between the columns Chla, and DOC. In the current file, the inflow data was added between Inflow_Chla and Inflow_DOC. This data must be in the units of mg/m3 to assist with consistency, as well as ease with the modification of the code base. Remember where in the list the new species is added in relation to other species. This will allow the files to remain consistent.
This file contains a long list of physical parameters, inflow scaling parameters, and biological parameters. For the purposes of adding a new species, the only adjustment to be made is the addition of inflow scaling parameters. These care values which are multiplied by the inflow added by the previous files. In most cases, these can be left as 1. These values are unitless, and the row labels follow the structure “I_sc” followed by the chemical species. For iron, this is I_scFe. To add the species to the parameter file, insert a row in Excel in the same relative position to the other chemicals used thus far. For iron, it is once again located between Chl and DOC. Add the name of the chemical to the Parameter column, followed by the scaling factor in the Value column. If the scaling value was 1, set Min and Max to “NaN” to inform the program that it will not perform a simulation between two values. If the value is less than one, these values can be set as desired. The unit column is “(-)” for unitless.
With the initialization files set-up, we must now alter the following files such that the main function can function properly. While they may be edited in any order, the following order was selected to avoid any conflicts.
| Function | Changes (Approximate Line Location |
| modelinputs_v12.m |
|
| convection_v12_1a.m |
|
###modelinputs_v12.m
-
Within the function header, add any chemical species added to the initial depth profile file (VAN_init_v12.xlsx) to the set of input arguments. The arguments should follow the same order as the column headers, and thus the new species should be added in the same location. For iron, the dissolved iron was added between In_Chlz and In_DOCz.
-
In the input/output comment section of the file, add in a new entry for the chemical species which were added. For the most part, it will follow the same format as all similar entries.
-
At around lines 50-57, there is a group of values set based on the parameter file (VAN_para_v12.xlsx). Since the species scaling parameter was added, these values are no longer accurate. Thus, the highlighted values must be changed to reflect the added species:
The first group of values (currently 26) must be increased by the number of species inflow scaling factors added. As a check, these values will equal the row value of the final scaling factor. In addition, the biological parameters must also be increased by the same amount. These are also equivalent to the Excel values. -
By adding species to the initial depth profile initialization file, the output array indices must also be changed. At approximately lines 65-83, the individual depth profiles of each chemical species is separated into their own individual array. Depending on which column the species was added, the following changes must be made: The species must be added in the correct location (positioned similarly to the Excel sheet), all future indices must be shifted down one, and no two elements should be sharing the same index.
-
If a chemical inflow was added to the time dependent inflow sheet, this change must be carried over to the inflow initialization code. At approximately line 91-93, the input initialization file (VAN_input_PGS84_00_v12.xlsx) is separated into 3 arrays: date, meteorological data, and inflow. The inflow indices must be adjusted such that in encompasses all of the inflows. In the case of adding iron inflow, the index was increased by 1.
-
There is a log message displaying the number of columns read around line 106. This must be changed to reflect the new number of columns.
-
The number of columns to be interpolated must also be increased to reflect the new number of inflows.
###convection_v12_1a.m
-
The function header must change to incorporate the new dissolved species in the water. This should once again follow the same location guidelines to encourage consistency.
-
The input and output comment section should also be updated to include the new chemical species added to the system. The formatting should be similar to the current species already present.
-
At approximately lines 55-74, there is a set of mixing commands. The new chemical species should be added to this set of commands. To do this, copy an existing group of lines, and paste it in the correct relative position to the rest of the chemicals. Then, change all of the values associated with the previous chemical, and change it to the new chemical variable.
will become -
At the end of the file, there is a large set of commands which set the final output values. Create one of these commands to generate the output of the new chemical species:
##Adding Species to the 'Solve Model' Function
Once the initialization files have been set, and the function handles have been changed, we must now add the species to the main solvemodel_v12.m function. The following shows a step-by-step list of all locations in which the main function must be altered.
- Add species to the function header (9)
- Add species to the function comments (44-62)
- Add species to the overridden input argument logic tree (80-90)
- Add physical parameter initialization (101-123)
- Add output matrix initialization for new species (182-198)
- Initialize value used in loop from initial value (236-245)
- Edit convection_v12_1a function inputs and outputs (394/409/437/651)
- If inflow was added, add new inflow and modify existing indices (571-576)
- In inflow was added, add new inflow calculation (607-637)
- Add potential remixing (680-700)
- Add potential remixing (714-740)
- Output matrices (890-910)
##Final Notes If implementing in an already existing model, remember to adjust the model output to include the new species.