Quickstart
To run a mesas.py model, you must supply four things.
The first is a timeseries of the system inputs and outputs, and of any time-varying parameters, stored in either
a Pandas dataframe
a
.csv
file
The other three are sets of parameters and options to configure the model, which can be supplied either as text files (in the human-readable JSON format) or as python dictionaries (dict
objects). The three sets are
A specification of the SAS function
A specification of any solute solute_parameters
Any optional parameters and settings
If you are unfamiliar with pandas
and python dict
objects (or even if you are) it is probably easiest to start by using .csv
and .json
input files.
Input timeseries
The .csv
of timeseries data should contain (at minimum) the timeseries of fluid input, output, and any tracer input timeseries. In addition, many SAS function and solute parameters can be time-varying (rather than fixed values). When they vary in time, they must be provided as a column in the dataframe.
The code below creates a .csv
file with some artificial data. We will construct it to be 100 timesteps of steady flow at rate Q_steady
through storage volume Storage_vol
. The inputs will be labeled with tracer at concentration C_tracer_input
for 10% of the total duration near the start of the timeseries. Let’s start by creating some variables to hold this information:
timeseries_duration = 1.
timeseries_length = 100
dt = timeseries_duration/timeseries_length
pulse_start = 0.05
pulse_end = 0.15
C_tracer_input = 0.5
Q_steady = 1.
Storage_vol = 0.1
Now we will create the dataframe in pandas:
import pandas as pd
import numpy as np
data_df = pd.DataFrame(index=np.arange(timeseries_length) * dt)
data_df['Q out [vol/time]'] = Q_steady
data_df['J in [vol/time]'] = Q_steady
data_df['C [conc]'] = 0
data_df.loc[pulse_start:pulse_end, 'C [conc]'] = C_tracer_input
data_df.to_csv('data.csv')
This creates a file data.csv
that contains the input timeseries.
Configuration information
Next, let’s give the specifications of the SAS function, solute parameters, and options in a file config.json
. The part specifying the SAS function looks like this:
"sas_specs": {
"Q out [vol/time]": {
"my first SAS func!": {
"ST": [0, "Storage_vol"]
}
}
}
This specification says the following:
There is only one flux out, and it can be found under the column
"Q out [vol/time]"
in the dataframe.There is only one SAS function associated with this flux, and it is called
"my first SAS func!"
.The SAS function is specified as a piecewise linear function with one linear segment from \(P=0\) at \(ST=0\) to \(P=1\) at \(ST =\)
Storage_vol
.
The only solute information we need to give is the name of the column containing the input timeseries. The part of the config.json
file providing this information looks like this:
"solute_parameters": {
"C [conc]": {}
}
The dictionary associated with our solute is empty {}
, so the default parameters will be used.
The part providing additional options looks like this:
"options":{
"dt": 0.01,
"influx": "J in [vol/time]"
}
This specifies
The timestep of the model
dt
(which depends on the units of the inflow and outflow)The name of the column in the dataframe that contains the inflow rate, given by the keyword argument
influx
The complete config.json
file should look like this:
{
"sas_specs": {
"Q out [vol/time]": {
"my first SAS func!": {
"ST": [0, "Storage_vol"]
}
}
},
"solute_parameters": {
"C [conc]": {}
},
"options":{
"dt": 0.01,
"influx": "J in [vol/time]"
}
}
Running mesas.py
Now we are ready to import mesas.py, create the model, and run it:
from mesas.sas.model import Model
model = Model(data_df='data.csv', config='config.json')
model.run()
model.data_df.to_csv('data_with_results.csv')
Assuming the model runs without incident the predicted discharge concentration has appeared as a new column in the file data_with_results.csv
. The columns generated by the model will have the form '<solute column name> --> <flux column name>'
.
Plot the results
The results can be accessed within python as the pandas
dataframe model.data_df
We can use matplotlib to plot individual columns of the dataframe like this:
import matplotlib.pyplot as plt
plt.plot(model.data_df.index, model.ata_df['C [conc]'])
plt.plot(model.data_df.index, model.data_df['C [conc] --> Q out [vol/time]'])
Which should give this: