class openpnm.io.Dict[source]

Bases: openpnm.io.GenericIO.GenericIO

Generates hierarchical dicts with a high degree of control over the structure.

This is the most important class in the io module, since many other classes use this to manipulate and format the data structures.

Also, it is possible to use Python’s pickle module to save dicts to file.

classmethod export_data(dct, filename)[source]

Saves data from the given dictionary into the specified file.

  • dct (dictionary) – A dictionary to save to file, presumably obtained from the to_dict method of this class.

  • filename (string or path object) – The filename to store the dictionary.


This method uses the pickle module to save the dictionary.

classmethod from_dict(dct, project=None, delim=' | ')[source]

This method converts a correctly formatted dictionary into OpenPNM objects, and returns a handle to the project containing them.

  • dct (dictionary) – The Python dictionary containing the data. The nesting and labeling of the dictionary is used to create the appropriate OpenPNM objects.

  • project (OpenPNM Project Object) – The project with which the created objects should be associated. If not supplied, one will be created.


project – An OpenPNM Project containing the objects created to store the given data.

Return type



The requirement of a correctly formed dictionary is rather strict, and essentially means a dictionary produced by the to_dict method of this class.

classmethod import_data(filename)[source]

Load data from the specified pickle file into a Python dictionary


filename (string) – The path to the file to be opened


This returns a Python dictionary which can be converted into OpenPNM objects using the from_dict method of this class.

classmethod load(*args, **kwargs)[source]

This method is being deprecated. Use import_data instead.

classmethod save(*args, **kwargs)[source]

This method is being deprecated. Use export_data instead.

classmethod to_dict(network=None, phases=[], element=['pore', 'throat'], interleave=True, flatten=True, categorize_by=[])[source]

Returns a single dictionary object containing data from the given OpenPNM objects, with the keys organized differently depending on optional arguments.

  • network (OpenPNM Network Object (optional)) – The network containing the desired data

  • phases (list of OpenPNM Phase Objects (optional, default is none)) – A list of phase objects whose data are to be included

  • element (string or list of strings) – An indication of whether ‘pore’ and/or ‘throat’ data are desired. The default is both.

  • interleave (boolean (default is True)) – When True (default) the data from all Geometry objects (and Physics objects if phases are given) is interleaved into a single array and stored as a network property (or Phase property for Physics data). When False, the data for each object are stored under their own dictionary key, the structuring of which depends on the value of the flatten argument.

  • flatten (boolean (default is True)) – When True, all objects are accessible from the top level of the dictionary. When False objects are nested under their parent object. If interleave is True this argument is ignored.

  • categorize_by (string or list of strings) –

    Indicates how the dictionaries should be organized. The list can contain any, all or none of the following strings:

    ’object’ : If specified the dictionary keys will be stored under a general level corresponding to their type (e.g. ‘network/net_01/pore.all’). If interleave is True then only the only categories are network and phase, since geometry and physics data get stored under their respective network and phase.

    ’data’ : If specified the data arrays are additionally categorized by label and property to separate boolean from numeric data.

    ’element’ : If specified the data arrays are additionally categorized by pore and throat, meaning that the propnames are no longer prepended by a ‘pore.’ or ‘throat.’


  • A dictionary with the data stored in a hierarchical data structure, the

  • actual format of which depends on the arguments to the function.


There is a handy package called flatdict that can be used to access this dictionary using a single key such that:

d[level_1][level_2] == d[level_1/level_2]

Importantly, converting to a flatdict allows it be converted to an HDF5 file directly, since the hierarchy is dictated by the placement of ‘/’ characters.