coffee.io package

Submodules

coffee.io.simulation_data module

The io module provides a wrapper around h5py so as to translate between system, solver, and timeslice objects in a COFFEE friendly way.

Datagroups in an hdf file are assumed to contain all data associated to a simulation. Each dataset in a data group

The module hdf_output is closely related to this module. The dictionary dgTypes maps data group names to SimOutputType class names. It is best to read the hdf_output module documentation as well as this modules documentation if the dgTypes dictionary needs to be altered.

class coffee.io.simulation_data.DataGroup(grp, returnValue=False)[source]

Bases: object

The DataGroup class wraps a h5py group so that the setter, getter and iter methods do sensible array-like things.

Datagroups are assumed to represent an entire simulation. Datasets are assumed to represent each timeslice. Each dataset in a data group is the value of a keyword “i” where i is the iteration number of the timeslice that the dataset contains.

This class abstracts these details so that a given a data group g we can write g[2]'' to get the timeslice of the second iteration and ``g[3] to get the timeslice of the following iteration.

property attrs

Wraps the attrs dictionary of a hdf datagroup.

attrs_list(kwd)[source]

Represents the attributes of each data set of the data group as a list.

Returns:

Each entry in the list is a value of some keyword in the attrs dictionary of a sub data set.

Return type:

list

index_of_attr(attr, value, start_index=0, value_comparor=<function DataGroup.<lambda>>)[source]

Returns the index of the dataset in self whose attribute attr has the given value.

The function value_comparor allows for fudging a little. It is a function that takes the attrs of a data set and returns true or false. Once true is found the index of that data set is returned.

Parameters:

  • attr – A keyword to be applied to the attrs attribute of each dataset.

  • value – The value that is searched for.

  • start_index (int, Optional) – The index at which to start the search.

  • value_comparor (function(value)) – A function which returns true if the given value matched the desired value.

Returns:

The index of the dataset whose attrs attributes matched.

Return type:

int

property name

Wraps the hdf datagroup name.

class coffee.io.simulation_data.DomainDataGroup(grp, returnValue=False)[source]

Bases: DataGroup

A DataGroup wrapper that handles the specific case of function data over the computational grid.

class coffee.io.simulation_data.Sim(simName, simHDF)[source]

Bases: object

Represents the data associated to a simulation as stored in an HDF file.

Designed to be accessed via a SimulationHDF object.

GNUplot(group, gnuCommands=None, gnuInitialisationCommands=None, tstart=-inf, tstop=inf, animationLength=2, framesPerSec=60)[source]

A utility function which plots a given group.

There is no return, but gnuplot is called hence, depending on what parameters are parsed, plots will be created.

Parameters:

  • group (DataGroup) – A DataGroup containing the data to be plotted.

  • gnuCommands (list of strings, Optional) – A list of string commands for GnuPlot.

  • gnuInitialisationCommands (list of strings, Optional) – A list of string commands to be parsed to GnuPlot on initialisation.

  • tstart (float, Optional) – The time at which to start plotting data.

  • tstop (float, Optional) – The time at which to stop plotting data.

  • animationLength (float) – The length of time of the animation.

  • framesPerSec (int) – The number of frames per second of display.

animate(dgType='raw', gnuCommands=None, gnuInitialisationCommands={'debug': 0, 'persist': 1}, tstart=-inf, tstop=inf, animationLength=2, framesPerSec=60)[source]

A utility method that provide nice defaults for the GNUplot method.

Parameters:

  • dgType (string) – A key of the dbTypes dictionary. The type of data to be displayed.

  • gnuCommands (list of strings, Optional) – A list of string commands for GnuPlot.

  • gnuInitialisationCommands (list of strings, Optional) – A list of string commands to be parsed to GnuPlot on initialisation.

  • tstart (float, Optional) – The time at which to start plotting data.

  • tstop (float, Optional) – The time at which to stop plotting data.

  • animationLength (float) – The length of time of the animation.

  • framesPerSec (int) – The number of frames per second of display.

class dsReturnValue(dataset)[source]

Bases: object

getDgType(dgType)[source]

Wraps the SimulationHDF method of the same name.

Parameters:

dgType (string) – A key from the dgTypes dictionary.

Return type:

DataGroup

getDgTypeAttr(dgType, attr, i)[source]

Wraps the SimulationHDF class’ method of the same name.

Parameters:

  • dgType (string) – A key of the dgTypes dictionary. The dgType whose attributes are desired.

  • attr (string) – The attribute to return.

  • i (int) – The index of the iteration whose attributes are desired.

Return type:

DataGroup

indexOfTime(t)[source]

Wraps the SimulationHDF method of the same name.

Assumes that the simulation used is the one represented by this object.

Parameters:

  • t (float) – The time whose index is desired.

  • sim (string) – The name of the simulation to search.

Returns:

The iteration index that matches the given time up to the assumed NUMERICAL_TOLERANCE.

Return type:

int

plot(time, dgType='raw', gnuCommands=None, gnuInitialisationCommands={'debug': 0, 'persist': 1})[source]

A utility that plots the data at a particular time.

This is a wrapper to the animate method that gives the same start and stop times.

Parameters:

  • time (float) – The time of the data that should be plotted.

  • dgType (string, Optinal) – A key of the dgTypes dictionary.

  • gnuCommands (list of strings) – Commands to be parsed to GnuPlot when the data is plotted.

  • gnuInitialisationCommands (list of strings) – Commands to be parsed to GnuPlot on initialisation.

tslice(i)[source]

Wraps the SimulationHDF method of the same name.

Assumes that the simulation used is the one represented by this object.

Parameters:

  • i (int) – The iteration number of the timeslice to return.

  • sim (string) – The name of the simulation to access

  • dgType (string, Optional) – The name of the type of data to retrieve. See the dgTypes dictionary for a list of possible values.

Return type:

tslice.TimeSlice

write(dgType, it, data, name=None, derivedAttrs=None)[source]

Wraps the SimulationHDF file of the same name.

Assumes that the simulation name is given by this object.

Parameters:

  • dgType (string) – A key from the module level dgTypes dictionary.

  • it (int) – The iteration number of the data to be written.

  • data – The data to write. It must be able to be stored in an h5py.dataset.

  • name (string, Optional) – A parameter used to create a sub-datagroup. See comments above.

  • derivedAttrs (dictionary, Optional) – A dictionary of additional attributes to add to created datasets

class coffee.io.simulation_data.SimulationHDF(fileName, **kwds)[source]

Bases: object

Represents the data associated to all simulations as stored in an HDF file.

getDgType(dgType, sim)[source]

Returns a DataGroup object wrapping the given simulations data for the given dgType.

Parameters:

  • dgType (string) – A key from the dgTypes dictionary.

  • sim (string) – The name of the simulation whose data to access.

Return type:

DataGroup

getDgTypeAttr(attr, i, sim)[source]

Returns a DataGroup object wrapping the given simulations data set attributes for the given dgType.

Parameters:

  • dgType (string) – A key from the dgTypes dictionary.

  • sim (string) – The name of the simulation whose data to access.

Return type:

DataGroup

getSimData(sim)[source]

Returns a dictionary giving access to the hdf objects corresponding to the given simulation name.

Parameters:

sim (string) – The name of the simulation whose data to retrieve.

Return type:

dictionary

getSims()[source]

Returns a list of Sim objects representing the simulations contained in the hdf file.

Returns:

The Sim classes wrapping the simulation contained in this hdf file.

Return type:

list of Sim classses

indexOfTime(t, sim)[source]

A utility method that supports the translation of a simulation time to the iteration index.

The tolerance for the required float comparison is given in the module variable NUMERICAL_TOLERANCE.

Parameters:

  • t (float) – The time whose index is desired.

  • sim (string) – The name of the simulation to search.

Returns:

The iteration index that matches the given time up to the assumed NUMERICAL_TOLERANCE.

Return type:

int

name()[source]

The name of the file that this class wraps.

Returns:

The filename.

Return type:

string

sim(name)[source]

Returns a Sim class wrapping the data for the appropriate simulation.

tslice(i, sim, dgType='raw')[source]

The timeslice of the given simulation at the given iteration.

Parameters:

  • i (int) – The iteration number of the timeslice to return.

  • sim (string) – The name of the simulation to access

  • dgType (string, Optional) – The name of the type of data to retrieve. See the dgTypes dictionary for a list of possible values.

Return type:

tslice.TimeSlice

write(dgType, sim, it, data, name=None, derivedAttrs=None, overwrite=True)[source]

This method allows for writing to SimulationHDF objects.

Note that if dgType is an error type data group then name must be given. We recommend that its value be taken as the data group from which the error data was generated. To ensure that name is not / is needed refer to how the data is extracted.

Parameters:

  • dgType (string) – A key from the module level dgTypes dictionary.

  • sim (string) – The name of the simulation to write to.

  • it (int) – The iteration number of the data to be written.

  • data – The data to write. It must be able to be stored in an h5py.dataset.

  • name (string, Optional) – A parameter used to create a sub-datagroup. See comments above.

  • derivedAttrs (dictionary, Optional) – A dictionary of additional attributes to add to created datasets

  • overwrite (bool) – If true data will be overwritten, otherwise an error will be raised.

coffee.io.simulation_data.array_value_index_mapping(correct, comparison, compare_on_axes=1)[source]

A utility function which is useful when comparing data.

The function takes two arrays and returns a list of pairs of indices (index1, index2) so that correct[index1] = comparison[index2] (up to NUMERICAL_TOLERANCE) this is very useful when performing error calculations.

The idea is that data over two arbitrary domains can be easily compared.

Parameters:

  • correct (numpy.ndaray) –

  • comparison (numpy.ndarray) –

  • compare_on_axes (int) – If 0 then the first axes is included in the indices

Returns:

Each pair of tuples of ints represents the data values which are defined over the same point.

Return type:

list of 2-tuples of tuples of ints

coffee.io.simulation_data.dgTypes = {'IJ': 'Weyl_Constants_IJ', 'constraint': 'Constraint', 'constraints': 'Constraints', 'domain': 'Domain', 'dt': 'Time_Step', 'errorExa': 'Error_Exact', 'errorNum': 'Error_Numeric', 'exact': 'Exact_Data', 'mu': 'mu', 'mup': 'mup', 'raw': 'Raw_Data', 'scrif': 'Scri+', 'time': 'Time'}

The dgTypes dictionary maps data types that are produced during simulation to the keys used in the hdf file to store that data. The dgTypesInv dictionary provide the reverse mapping.

If you need a new data type to be written out you can dynamically modify this dictionary. Changes will also need to be reflected in the hdf output action.

coffee.io.simulation_data.dgTypes_DataGroups = {'domain': (None, <class 'coffee.io.simulation_data.DomainDataGroup'>)}

The dgTypes_DataGroups dictionary maps keys in the dgTypes dictionary to a 2-tuple.

The first entry in the two tuple is a module name that is imported using __import__, the second entry is the name of a class in that module that provides DataGroup functionality suitable for the given dgType.

If the first entry is none then it is assumed that the appropriate data group is in this module. The class name rather than the class string should be in the second entry of the tuple.

If a dgType key is not in the dictionary the DataGroup class is used.

coffee.io.simulation_data.sysDTypes = {'cmp': 'cmp', 'grid': 'Grid', 'numvar': 'NumVariables', 'solver': 'Solver', 'system': 'System'}

The sysDTypes dictionary lists the data types in a system object (keys) against the key used in the hdf file to store that data (values).

Feel free to dynamically alter the dictionary. Logic is based on correctness of the keys not the values. New data types for system objects should be added in this dictionary as key value pairs.

coffee.io.simulation_data.systemD = 'System'

The systemD variable store the hdf key used to create datagroups that store data for system objects.

Module contents