fmdtools.define.flow

The flow subpackage provides a representation of flows, which are used to connect Blocks in an Architecture. Different types of flows are provided in the following modules, as shown below/

Different types of flows defined in fmdtools.

These are provided in the modules:

• fmdtools.define.flow.base: for Flow, which is used for the base object class used for both objects and blocks/architectures.

• fmdtools.define.flow.multiflow: for MultiFlow class which represents multiple flows in a combined graph.

• fmdtools.define.flow.commsflow: for CommsFlow class which represents perception and communications between agents/functions.

fmdtools.define.flow.base

Flow classes are used to represent variables that are shared between blocks, such as connections or a shared environment. Like blocks, flows (see example below) can hold containers (e.g., States, Parameters, etc.) in order to represent different properties:

Example of defining and instantiating a Flow class to hold x/y fields.

class fmdtools.define.flow.base.Flow(name='', roletypes=[], track='default', **kwargs)

Bases: BaseObject

Superclass for flows.

Flows are used to connect simulable parts of a model (e.g., functions) and respresent shared variables or states.

Examples

>>> class ExampleFlow(Flow):
...     __slots__ = ()
...     container_s = ExampleState

>>> exf = ExampleFlow('exf', s={'x': 0.0})
>>> exf
exf ExampleFlow flow: ExampleState(x=0.0, y=1.0)

Note that copying creates independent copies of states:

>>> exf2 = exf.copy()
>>> exf2
exf ExampleFlow flow: ExampleState(x=0.0, y=1.0)
>>> exf2.s.x = 2.0
>>> exf2.s == exf.s
False

check_role(roletype, rolename)

Flows may be given any role name.

container_p

alias of Parameter

container_s

alias of State

copy(**kwargs)

Return a copy of the flow object (used when copying the model).

create_hist(timerange)

Create state history of the object over the timerange.

Parameters:

timerange (array) – Numpy array of times to initialize in the dictionary.

Returns:

hist – A history of each recorded block property over the given timerange.

Return type:

History

reset()

Reset the flow to the initial state.

return_mutables()

Return mutable properties of the flow.

status()

Return a dict with the current states of the flow.

fmdtools.define.flow.multiflow

Description: A module to define multiflows.

Contains:

• MultiFlow: Class for flows which enable multiple copies to be instantiated

within itself (e.g., for perception)

class fmdtools.define.flow.multiflow.MultiFlow(name='', glob=[], s={}, p={}, track=['s'])

Bases: Flow

MultiFlow class enables represenation of multiple connected copies of the same flow.

It enables the addition of local flows in an overall flow architecture, which are essentially copies of the main flow which live in functions. MultiFlows are helpful in cases where each function has a different view of the same external flow (e.g., perception, etc). Notably, this class adds the methods:

• create_local(), which can be used to add a local flow to a function/block

• get_view(), which can be used to look at other local views of the flow

• update(), which can be used to update one view of the flow from another

A MultiFlow can have any number of local views (listed by name in MultiFlow.locals) as well as a single global view (which may represent the actual value)

check_dict_creation = False

copy(name='', glob=[], p={}, s={}, track=['s'])

Return a copy of the flow object (used when copying the model).

create_hist(timerange)

Create state history of the object over the timerange.

Parameters:

timerange (array) – Numpy array of times to initialize in the dictionary.

Returns:

hist – A history of each recorded block property over the given timerange.

Return type:

History

create_local(name, attrs='all', p='global', s='global', track=['s'], **kwargs)

Create a local view of the Flow.

Parameters:

• name (str) – Name for the view (to retrieve at the Flow level)

• attrs (dict/list/str, optional) –

  Attributes to include in the local copy. The default is “all”. Has options:

  str: to use if only using a single attribute of the local flow list: list of attributes to use in the local flow dict: dict of attributes to use in the local flow and initial values

• p (dict) – Parameters to instantiate the local version with (if params used in flow) Default is ‘global’, which uses the same parameter as the multiflow

• s (dict) – Initial values for the states. Default is ‘global’, which uses the same initial states as the multiflow

Returns:

newflow – Local view of the MultiFlow with its own individual values

Return type:

MultiFlow

get_local_name(name)

Get the name of the view corresponding to the given name.

Enables “local” or “global” options.

get_typename()

get_view(name)

Get the view of the MultiFlow corresponding to the given name.

h

p

reset()

Reset the flow to the initial state.

return_mutables()

Return mutable properties of the flow.

return_states()

s

slots = ['__dict__']

status()

Return a dict with the current states of the flow.

update(to_update='local', to_get='global', *states)

Update a view of the MultiFlow to the values of another view.

Parameters:

• to_update (str/list, optional) – Name of the view to update. The default is “local”. If “all”, updates all locals (or ports for commsflows). If a list is provided, updates the list (in locals)

• to_get (str, optional) – Name of the view to update from. The default is “global”.

• *states (str) – States to update (defaults to all states)

fmdtools.define.flow.commsflow

Description: A module to define multiflows.

Contains:

• CommsFlow: Class for flows which enable communications

(e.g., sending/recieving messages) between functions

class fmdtools.define.flow.commsflow.CommsFlow(name='', glob=[], p={}, s={}, track=['s'])

Bases: MultiFlow

A CommsFlow further extends the MultiFlow class to represent communications.

It does this by giving each block’s view of the flow (in CommsFlow.fxns) an “internal” and “out” copy, as well as an “in” (a dict of messages from other views) and “received” (a set of messages received).

To enable the sending/receiving of messages between functions, it further adds:

• create_comms, for instantiating local copies in functions

• send, for sending messages from one function to another

• receive, for receiving messages from other functions

• inbox, for seeing what messages may be received

• clear_inbox, for clearing the inbox to enable more messages to be received

check_dict_creation = False

clear_inbox(fxnname='local')

Clear the inbox of the function so it can recieve more messages.

copy(name='', glob=[], p={}, s={}, track=['s'])

Return a copy of the flow object (used when copying the model).

create_comms(name, ports=[], **kwargs)

Create an individual view of the CommsFlow (e.g., for a function).

This will have an internal view, out view, in dict, and received set.

Parameters:

• name (str) – Name for the view (e.g., the name of the function)

• ports (list) – Ports to send the information to/from (e.g., names of external fxns/agents)

Returns:

A local view of the CommsFlow for the function

Return type:

CommsFlow

get_port(fxnname, portname, box='internal')

Get a port with name portname.

If there is no port for the name, the default port is given. The argument is ‘internal’ or ‘out’ for the internal state or outbox, respectively.

get_typename()

h

inbox(fxnname='local')

Provide list of messages which have not been received by the function yet

out(fxnname='local')

Provide the view of the message that is being sent by the function.

p

receive(fxn_to='local', fxn_from='all', remove_from_in=True)

Update the internal view of the flow from external functions.

Parameters:

• fxn_to (str) – Name of the view to recieve the view. The default is “local”.

• fxn_from (str/list, optional) – Name of the function to send from. The default is “all”.

• remove_from_in (bool) – Whether to remove the notification from the “inbox.” The default is True.

received(fxnname='local')

reset()

Reset the flow to the initial state.

return_mutables()

Return mutable properties of the flow.

return_states()

s

send(fxn_to, fxn_from='local', *states)

Sends a function’s (fxn_from) view for the CommsFlow to another function fxn_to by updating the function’s out property and fxn_to’s inbox list. Note that the other function must call recieve on the other end for the message to be fully received (update its internal view).

Parameters:

• fxn_to (str/list) – Name/list of names of the functions to send to. The default is “all”

• fxn_from (str, optional) – Name of the function to send from. The default is “local”.

• *states (strs) – Values to send from.

slots = ['__dict__']

status()

Return a dict with the current states of the flow.