pymt.component package

Submodules

pymt.component.component module

Examples

Create an instance of the AirPort component and run it. The go method will initialize the component, run it for its duration, and finalize it.

>>> from pymt.framework.services import register_component_classes
>>> register_component_classes(['pymt.testing.services.AirPort'])
>>> comp = Component('AirPort')
>>> comp.start_time
0.0
>>> comp.current_time
0.0
>>> comp.end_time
100.0
>>> comp.go() 
{name: air_port, status: running, time: 1.0}
...
{name: air_port, status: running, time: 100.0}
>>> comp.current_time
100.0

If you try to create a new component with the same name, it will raise an exception. To create a new instance of the component, you have to give it a new name.

>>> comp = Component('AirPort') 
Traceback (most recent call last):
ValueError: AirPort
>>> comp = Component('AirPort', name='air_port')
>>> comp.current_time
0.0

You can gain finer control over component execution with the initialize, run, and finalize methods.

>>> comp.initialize()
>>> comp.run(10.) 
{name: air_port, status: running, time: 1.0}
...
{name: air_port, status: running, time: 10.0}
>>> comp.current_time
10.0
>>> comp.run(101.) 
Traceback (most recent call last):
ValueError: AirPort
>>> comp.current_time
10.0
>>> comp.run(100.) 
{name: air_port, status: running, time: 11.0}
...
{name: air_port, status: running, time: 100.0}
>>> comp.current_time
100.0
>>> comp.finalize()

class pymt.component.component.Component(port, uses=None, provides=None, events=(), argv=(), time_step=1.0, run_dir='.', name=None)

Bases: GridMixIn

Wrap a BMI object as a component.

Use the Component class to wrap an object that exposes a BMI so that it can operate within the model-coupling framework.

Parameters:

• port (str or port-like) – Name of the port to wrap or a Port instance.

• uses (list, optional) – List of uses port names.

• provides (list, optional) – List of provides port names.

• argv (tuple, optional) – List of command line argument used to initialize the component.

• time_step (float, optional) – Time interval over which component will run uses ports.

• run_dir (str, optional) – Directory where the component will run.

connect(uses, port, vars_to_map=())

Connect a uses port to a provides port.

Parameters:

• uses (str) – Name of the uses port.

• port (port-like) – Port-like object to connect to.

• var_to_map (iterable, optional) – Names of variables to map.

property current_time

Current time for component updating.

property end_time

End time for component updating.

finalize()

Finalize a component and any connected events.

classmethod from_dict(d)

Create a Component instance from a dictionary.

Use configuration paramters from a dict-like object to create a new Component. The dictionary must contain the following keys: * name * class * initialize_args * time_step * run_dir

Parameters:

d (dict-like) – Configuration parameters for the component.

Returns:

A newly-created Component instance.

Return type:

Component

classmethod from_path(path)

Create a component from a file.

Parameters:

path (str) – Path to yaml file.

Returns:

A newly-created component.

Return type:

Component

classmethod from_string(source)

Deprecated.

Note

Deprecated. Use load() instead.

Create a component from a string.

Parameters:

source (str) – Contents of a yaml file.

Returns:

A newly-created component.

Return type:

Component

go(stop=None)

Run a component from start to end.

Run a component starting from its start time and ending at its stop time. The component and any attached ports are first initialized, then updated until the end time and, finally, their finalize methods are called.

Parameters:

stop (float, optional) – Stop time, or None to run until end_time.

initialize()

Initialize a component and any connected events.

classmethod load(source)

Create a Component from a string.

This is an alternate constructor that create a component using values from a yaml-formatted string.

Parameters:

source (str) – Yaml-formatted string.

Returns:

A newly-created component.

Return type:

Component

classmethod load_all(source)

Create multiple components from a string.

This is an alternate constructor that creates a series of components using values from a yaml-formatted string.

Parameters:

source (str) – Yaml-formatted string.

Returns:

A list of newly-created component.

Return type:

List of Components

property provides

Names of connected provides ports.

register(name)

Register component with the framework.

Associate name with the component instance withing the framework.

Parameters:

name (str) – Name to associate component with.

run(stop_time)

Run a component and any connect events.

Parameters:

stop_time (float) – Time to run the component until.

property start_time

Start time for component updating.

property time_step

Component time step.

Time step over which a component will update any connected uses ports.

property uses

Names of connected uses ports.

pymt.component.component.clip_stop_time(stop, stop_min, stop_max)

Clip time between two values.

Clip a stopping time between two values. This is the same as the numpy clip function except that if stop is None then stop_max is returned.

Parameters:

• stop (float) – Stop time.

• stop_min (float) – Minimum stop time

• stop_max (float) – Maximum stop time

Returns:

The, possibly clipped, stop time.

Return type:

float

Examples

>>> clip_stop_time(1., 0, 2.)
1.0
>>> clip_stop_time(1., 2, 3)
2.0
>>> clip_stop_time(4., 2, 3)
3.0
>>> clip_stop_time(None, 0, 1)
1.0

pymt.component.grid module

class pymt.component.grid.GridMixIn

Bases: object

Mix-in that makes a Component grid-like.

Examples

>>> class Port:
...     def get_component_name(self):
...         return 'test-component'
...     def get_input_item_count(self):
...         return 1
...     def get_input_item_list(self):
...         return ['invar']
...     def get_output_item_count(self):
...         return 1
...     def get_output_item_list(self):
...         return ['outvar']
...     def get_grid_shape(self, grid_id):
...         return (2, 3)
...     def get_grid_spacing(self, grid_id):
...         return (2., 1.)
...     def get_grid_origin(self, grid_id):
...         return (0., 0.)

>>> from pymt.component.grid import GridMixIn
>>> class Component(GridMixIn):
...     def __init__(self):
...         self._port = Port()
...         super().__init__()
>>> c = Component()
>>> c.name
'test-component'
>>> c.input_items
['invar']
>>> c.output_items
['outvar']
>>> c.get_grid_type(0)
'RASTER'
>>> c.get_x(0)
array([[ 0.,  1.,  2.],
       [ 0.,  1.,  2.]])
>>> c.get_y(0)
array([[ 0.,  0.,  0.],
       [ 2.,  2.,  2.]])

get_connectivity(grid_id)

get_grid_type(grid_id)

The type of the grid.

Parameters:

grid_id (int) – Grid identifier.

Returns:

type – The type of the grid.

Return type:

str

get_offset(grid_id)

get_value(*args, **kwds)

get_var_units(name)

get_x(grid_id)

get_y(grid_id)

get_z(grid_id)

property input_items

Input item names as a list.

property name

Name of the wrapped component.

property output_items

Output item names as a list.

set_value(name, values)

pymt.component.grid.get_raster_node_coordinates(grid, grid_id)

Get coordinates of nodes on a raster grid.

Parameters:

• grid (grid_like) – A raster grid.

• grid_id (int) – Grid identifier.

Returns:

coords – Coordinates of the grid nodes.

Return type:

ndarray

Examples

>>> from pymt.component.grid import get_raster_node_coordinates
>>> class RasterGrid:
...     def get_grid_shape(self, grid_id):
...         return (2, 3)
...     def get_grid_spacing(self, grid_id):
...         return (1., 2.)
...     def get_grid_origin(self, grid_id):
...         return (2., 1.)
>>> g = RasterGrid()
>>> (y, x) = get_raster_node_coordinates(g, 0)
>>> y
array([[ 2.,  2.,  2.],
       [ 3.,  3.,  3.]])
>>> x
array([[ 1.,  3.,  5.],
       [ 1.,  3.,  5.]])

pymt.component.grid.get_rectilinear_node_coordinates(grid, grid_id)

Get coordinates of nodes on a rectilinear grid.

Parameters:

• grid (grid_like) – A rectilinear grid.

• grid_id (int) – Grid identifier.

Returns:

coords – Coordinates of the grid nodes.

Return type:

ndarray

Examples

>>> from pymt.component.grid import get_rectilinear_node_coordinates
>>> class RectilinearGrid:
...     def get_grid_x(self, grid_id):
...         return (0., 3., 4)
...     def get_grid_y(self, grid_id):
...         return (2., 7.)
>>> g = RectilinearGrid()
>>> (y, x) = get_rectilinear_node_coordinates(g, 0)
>>> y
array([[ 2.,  2.,  2.],
       [ 7.,  7.,  7.]])
>>> x
array([[ 0.,  3.,  4.],
       [ 0.,  3.,  4.]])

pymt.component.grid.get_structured_node_connectivity(grid, grid_id)

Get cell connectivity on a structured grid of quadrilaterals.

Parameters:

• grid (grid_like) – A structured grid.

• grid_id (int) – Grid identifier.

Returns:

conn – Connectivities of nodes to cells.

Return type:

ndarray

Examples

>>> from pymt.component.grid import get_structured_node_connectivity
>>> class StructuredGrid:
...     def get_grid_shape(self, grid_id):
...         return (2, 3)
>>> g = StructuredGrid()
>>> (c, o) = get_structured_node_connectivity(g, 0)
>>> c
array([0, 1, 4, 3, 1, 2, 5, 4])
>>> o
array([4, 8])

pymt.component.grid.get_structured_node_coordinates(grid, grid_id)

Get coordinates of nodes on a structured grid.

Parameters:

• grid (grid_like) – A structured grid.

• grid_id (int) – Grid identifier.

Returns:

coords – Coordinates of the grid nodes.

Return type:

ndarray

Examples

>>> from pymt.component.grid import get_structured_node_coordinates
>>> class StructuredGrid:
...     def get_grid_x(self, grid_id):
...         return np.array((0., 3., 4, 0., 3., 4.)).reshape((2, 3))
...     def get_grid_y(self, grid_id):
...         return np.array((2., 2., 2., 7., 7., 7.)).reshape((2, 3))
...     def get_grid_z(self, grid_id):
...         raise NotImplementedError('get_grid_z')
>>> g = StructuredGrid()
>>> (y, x) = get_structured_node_coordinates(g, 0)
>>> y
array([[ 2.,  2.,  2.],
       [ 7.,  7.,  7.]])
>>> x
array([[ 0.,  3.,  4.],
       [ 0.,  3.,  4.]])

pymt.component.grid.raster_node_coordinates(shape, spacing=None, origin=None)

Node coordinates of a uniform rectilinear grid.

Parameters:

• shape (array_like) – Size of grid in each dimension.

• spacing (array_like (optional)) – Node spacing in each dimension (default is unit spacing).

• origin (array_like (optional)) – Coordinates of the origin node (default is 0.0).

Returns:

coords – Node coordinates.

Return type:

ndarray

Examples

>>> from pymt.component.grid import raster_node_coordinates
>>> (y, x) = raster_node_coordinates((2, 3))
>>> y
array([[ 0.,  0.,  0.],
       [ 1.,  1.,  1.]])
>>> x
array([[ 0.,  1.,  2.],
       [ 0.,  1.,  2.]])

>>> (x, ) = raster_node_coordinates((3, ), (2., ), (1., ))
>>> x
array([ 1.,  3.,  5.])

pymt.component.model module

class pymt.component.model.Model(components, driver=None, duration=0.0)

Bases: object

property components

Names of the components.

property driver

Name of the driver component.

property duration

Length of time the model will run.

classmethod from_file(filename)

Construct a Model from the contents of a file.

Parameters:

filename (str) – Name of the model configuration file.

Returns:

model – A newly-created model.

Return type:

Model

classmethod from_file_like(file_like)

Construct a Model from the contents of a file-like object.

Parameters:

file_like (file_like) – A file-like object that contains the model configuration.

Returns:

model – A newly-created model.

Return type:

Model

classmethod from_string(contents)

Construct a Model from a string.

Parameters:

contents (str) – A string that contains the model configuration.

Returns:

model – A newly-created model.

Return type:

Model

go(filename=None)

Start the model.

classmethod load(source)

Construct a model from a YAML-formatted string.

Parameters:

source (str or file_like) – YAML-formatted model configuration.

Returns:

model – A newly-created Model.

Return type:

Model

Examples

>>> from pymt.framework.services import del_component_instances
>>> del_component_instances(['air_port'])

>>> from pymt.component.model import Model
>>> source = '''
... name: air_port
... class: AirPort
... connectivity: []
... '''
>>> model = Model.load(source)
>>> model.components
['air_port']
>>> model.driver is None
True
>>> model.duration
0.0

>>> model.driver = 'air_port'
>>> model.duration = 1.
>>> model['air_port'].current_time
0.0
>>> model.go() 
{name: air_port, status: running, time: 1.0}
>>> model['air_port'].current_time
1.0

static load_components(source, with_connectivities=False)

Construct a list of model components from a string.

Parameters:

• source (str or file_like) – YAML-formatted components configuration.

• with_connectivities (boolean (optional)) – Return connectivity dictionary along with components.

Returns:

components – Dictionary of newly-created components.

Return type:

dict

Examples

>>> from pymt.framework.services import del_component_instances
>>> del_component_instances(['air_port'])

>>> from pymt.component.model import Model
>>> source = '''
... name: air_port
... class: AirPort
... connectivity: []
... '''
>>> components = Model.load_components(source)
>>> list(components.keys())
['air_port']

pymt.component.model.get_exchange_item_mapping(items)

Construct a mapping for exchange items.

Parameters:

items (iterable) – List of exchange item names or (dest, src) tuples.

Returns:

items – List of (dest, src) tuples of name mappings.

Return type:

list

Examples

>>> from pymt.component.model import get_exchange_item_mapping
>>> get_exchange_item_mapping([('foo', 'bar'), 'baz'])
[('foo', 'bar'), ('baz', 'baz')]
>>> get_exchange_item_mapping([dict(source='bar',
...                                 destination='foo'), 'baz'])
[('foo', 'bar'), ('baz', 'baz')]

Module contents