propti data structure

[[TOC]]

PROPTI's Data Structure

PROPTI's data structure is a very important part of the overall package. They are objects (class in Python) that contain relevant information for the inverse modelling process (IMP) in an organised fashion. The classes themselves are organised to give them a kind of hierarchy.

An overview of the data structure is here provided by presenting an example case. Assume, one wants to create a material input parameter set for a simulation of the combustion of wood, based on Cone Calorimeter experiments. The experiments have been performed with three different heat fluxes and each one has been repeated three time. This would lead to nine different experimental data sets, in total. Now the question is, what input parameters for the simulation would describe the material behaviour of wood, so that the simulation results match those of the experiment.

OptimiserProperties

propti.OptimiserProperties is used to store information that needs to be provided to the optimiser itself. This would be information like what kind of optimisation algorithm to use, how many repetitions to perform or how to name the file the results are saved into.

Parameter

propti.Parameter is used to store general parameter information. This could be for parameters that are worked on by the optimisation algorithm, as well as general information (meta data) that describes environmental conditions within the simulation.

Here, the density of the wood would be worked on, by the optimisation algorithm. The heat flux from the Cone Calorimeter during the experiment would be an environmental conditions the wood sample is subjected to.

propti.Parameter(name: str, units: str = None, place_holder: str = None, value: float = None, distribution: str = 'uniform', min_value: float = None, max_value: float = None, max_increment: float = None)

class propti.Parameter

The constructor of the Parameter class accepts the following input for its constructor:

propti.Parameter(name: str, units: str = None, place_holder: str = None, 
                 value: float = None, distribution: str = 'uniform', 
                 min_value: float = None, max_value: float = None, 
                 max_increment: float = None)

• name A character string that describes the parameter. Used for internal reference that is human readable.

• units Character string that describes the measurement units.

• place_holder Character string that is used in the template to mark the location where this parameter is to be written. If no value is provided, name is chosen.

• value Holds the current parameter value as a float. Can be initialised with a specific value for optimisation algorithms that need a guess vector to start from.

• distribution Specifies a distribution by which the algorithm shall sample individual parameters during the IMP, if needed by the algorithm. Possible values: 'uniform'.

• min_value Lower limit of the range in which the algorithm is allowed to sample parameter values.

• max_value Lower limit of the range in which the algorithm is allowed to sample parameter values.

• max_increment Increment by which the algorithm is allowed to change the parameter value between simulations. This option is needed for some algorithms.

---

The Parameter class has the following public methods:

• create_spotpy_parameter No fuctionality right now - WIP.

• upgrade This method upgrades legacy object instances with missing default values. Used to ensure compatibility of legacy inverse modelling projects with newer PROPTI versions.

• __str__ When called, it provides a human-readable output of the parameter, based on predefined definitions coded into this method (thus not exposed to the user).

ParameterSet

propti.ParameterSet is a container for the parameters. For the wood material there could be multiple different parameters like the density, thermal conductivity or heat of combustion. All are used by the optimisation algorithm and need to be grouped together within a ParameterSet. Also, all the meta data need to be grouped into a different ParameterSet.

DataSource

The class propti.DataSource is used as a container for data, in preparation for the fitness evaluation. Meta data is stored that identifies the desired data, as well as the data itself. This means the file name and the labels to read a data series. The pandas library is working in the background to extract the information, thus the lables follow those conventions.

The intended use is the storage of the experimental and simulation data.

Relation

propti.Relation utilises the propti.DataSource to connect specific experimental data with simulation results. Later, this created relationship is referred to when the fitness of a parameter set is to be evaluated. Multiple relations can be assigned to account for different repetitions under the same experimental conditions.

For the Cone Calorimeter example the relations could be made between mass loss of the sample over time or the energy release rate per unit area. In this example one would end up with three relations, because each test was repeated three times.

SimulationSetup

A propti.SimulationSetup is a specific set of information that describes an intended simulation completely. It draws upon the classes that have been described above, further meta data is added as well. In general, it merges information on where the simulation is to be executed (working directory), what simulation software template and data shall be used, as well as where to store the results.

One could regard it as an experimental setup, with information on a sample and the conditions to be tested in. Based on the example, it would be one of the three different heat fluxes, but with the three repetitions.

SimulationSetupSet

Finally, the propti.SimulationSetupSet merges all the different SimulationSetup. Thus, a complete set of information, defining the overall inverse modelling process, is obtained.

Now, all the different experiments, based on the heat fluxes, from the Cone Calorimeter example would be combined.