fmdtools.define

Package for modelling system structure and behavior.

The define package provides the building blocks to develop a simulation. Simulations are defined in the sub-classes of the Simulable class (in the block and architecture subpackages), as shown below:

Inheritance of simulable fmdtools classes — Structure of simulable fmdtools subclasses used for developing simulations.

Aside from their internal methods defining behavior, events/indicators, and results, Simulations are additionally composed of internal containers (or sub-attributes) of the class which are defined in their own class.

`fmdtools.define.architecture`	Package for defining system Architecture.
`fmdtools.define.block`	Package for defining system behaviors.
`fmdtools.define.flow`	Package for defining Flow connections between behavioral elements.
`fmdtools.define.object`	Package defining various model building blocks.
`fmdtools.define.base`	Common methods used commonly in model definition constructs.
`fmdtools.define.environment`	Module for representing environments with the `Environment` class.

fmdtools.define.base

Common methods used commonly in model definition constructs.

Includes functions:

get_var():Gets the variable value of the object
set_var():Sets variable of the object to a given value
nest_dict(): Nest a dictionary by a certin number of levels.
set_arg_as_type(): Change argument to given type.
is_iter(): Checks whether a data type should be interpreted as an iterable
is_numeric(): Check if a data type is numeric.
is_bool() : check if a data type is boolean.
is_numeric(): Helper function for Result Class, checks if a given value is numeric
unpack_x(): Unpack an array x as a tuple argument.
array_x(): Pack x into an array.
eq_units(): Find conversion factor between rates and times.
t_key():Used to generate keys for a given (float) time that is queryable as an attribute of an object/dict
round_float(): Round a float to a given precision.
nan_to_x(): Helper function for Result Class, returns nan as zero if present, otherwise returns the number

gen_timerange(): Generates timerange from start/endtime

get_code_atrs(): Get code attributes defining a given object or method.

remove_para(): Remove paragraph newlines in a string.

get_obj_name(): Get the name of an object.

get_memory(): Get the memory an object takes.

get_inheritanc(): Find the bases classes an object inherits from.

fmdtools.define.base.array_x(*x): Translate variable-length x into an array input.

fmdtools.define.base.eq_units(rateunit, timeunit)

Find conversion factor from rateunit (str) to timeunit (str).

Options for units are: ‘sec’, ‘min’, ‘hr’, ‘day’, ‘wk’, ‘month’, and ‘year’.

fmdtools.define.base.gen_timerange(start_time, end_time, dt=1.0, min_r=7): Generate the times in a given interval given the timestep dt.

fmdtools.define.base.get_code_attrs(obj)

Get a dict of code attributes for a given object or method.

Must be run from file other than where the code was originally written.

Parameters:: obj (Object/method) – Class to get code from.
Returns:: code_attrs – Dict of “source”, “code”, and “docs” code attributes.
Return type:: dict

fmdtools.define.base.get_inheritance(obj)

Get the base class(es) that the object inherits from.

Parameters:: obj (object) – Object to get base of.
Returns:: classes – Tuple of classes that are the base of the object.
Return type:: tuple

fmdtools.define.base.get_memory(role): Get memory of an object.

fmdtools.define.base.get_methods(obj): Get methods from the given object.

fmdtools.define.base.get_obj_name(obj, role='', basename='')

Get the name of an object.

Parameters:

obj (object) – Object to be graphed (BaseObject, BaseContainer, or other).
role (str) – Role the object plays in the larger system. Determines the name of Containers.

Returns:

name – Name of the object.

Return type:

str

fmdtools.define.base.get_var(obj, var)

Get the variable value of the object.

Parameters:: var (str/list) – list specifying the attribute (or sub-attribute of the object
Returns:: var_value – value of the variable
Return type:: any

fmdtools.define.base.is_bool(val)

Check if the value is a boolean.

Examples

>>> is_bool(True)
True
>>> is_bool(1.0)
False
>>> is_bool(np.array([True])[0])
True
>>> is_bool(np.array([1.0])[0])
False

fmdtools.define.base.is_iter(data)

Check whether a data type should be interpreted as an iterable or not.

Returned as a single value or tuple/array.

fmdtools.define.base.is_known_immutable(val): Check if value is known immutable.

fmdtools.define.base.is_known_mutable(val): Check if value is a known mutable.

fmdtools.define.base.is_numeric(val)

Check if a given value is a number.

Examples

>>> is_numeric(1.0)
True
>>> is_numeric("hi")
False
>>> is_numeric(np.array([1.0])[0])
True
>>> is_numeric(np.array(["hi"])[0])
False

fmdtools.define.base.nan_to_x(metric, x=0.0)

Return nan as zero if present, otherwise return the number.

Examples

>>> nan_to_x(1.0)
1.0
>>> nan_to_x(np.nan, 10.0)
10.0

fmdtools.define.base.nest_dict(dic, levels=inf, separator='.', skip=0)

Nest a dictionary a certain number of levels by separator.

Parameters:

dict (dict) – Dictionary to nest. e.g. {‘a.b’: 1.0}
levels (int, optional) – Levels to nest over. The default is float(‘inf’).
separator (str) – Seperator to nest by. The default is “.”
skip (str) – Levels to skip. The default is 0.

Returns:

newhist – Nested dictionary. e.g. {‘a’: {‘b’: 1.0}}

Return type:

dict

fmdtools.define.base.remove_para(source): Remove paragraph newlines in a string (e.g., of code).

fmdtools.define.base.round_float(number, res=1.0, min_r=7): Round floats to a given resolution (avoiding fp errors).

fmdtools.define.base.set_arg_as_type(true_type, new_arg)

Set a given argument as the type true_type.

Parameters:

true_type (class/type) – Class/type to set to
new_arg (value) – Value to set as.

Returns:

new_arg – Value with correct type (if possible).

Return type:

value

fmdtools.define.base.set_var(obj, var, val)

Set variable of the object to a given value.

Parameters:

var (list/tuple of strings) – list of nested attributes
val (attr) – attribute to set the value to

Returns:

flowdict – dict of flows indexed by flownames

Return type:

dict

fmdtools.define.base.t_key(time)

Generate keys for a given (float) time in a queryable format.

e.g. endresults.t10p0, the result at time t=10.0

fmdtools.define.base.unpack_x(*x): Unpack arrays/lists sent from libraries into tuples.

fmdtools.define.environment

Module for representing environments with the Environment class.

class fmdtools.define.environment.Environment(name='', root='', glob=[], p={}, s={}, r={}, c={}, ga={}, track='default')

Bases: CommsFlow

Class for representing environments (in development).

Environments are CommsFlows in order to readily enable perception as well as sending and recieving of information. In addition to having normal flow properties, they also contain the roles:

TODO: Properly expand create_local, update, send, recieve, etc to use ga and coords.

Roles

c: Coords: Representation of gridworld properties
r: Rand: Representation of random variables/rng
ga: GeomArch: Representaion of shapes/forms

Examples

>>> class ExampleEnvironment(Environment):
...    coords_c = ExampleCoords
...    arch_ga = ExGeomArch
>>> env = ExampleEnvironment('env')
>>> env.create_hist([1.0])
c.r.probdens:                   array(1)
c.st:                           array(1)
ga.points.ex_point:             array(1)
ga.lines.ex_line:               array(1)
ga.polys.ex_poly:               array(1)

arch_ga: alias of GeomArchitecture

base_type(): Return fmdtools type of the model class.

container_r: alias of Rand

coords_c: alias of Coords

copy(glob=[], p={}, s={})

Copy the Environment.

Examples

Copies should be identical but independent after copying, e.g.:

>>> e = ExampleEnvironment("env")
>>> e.ga.points['ex_point'].s.occupied = True
>>> e.c.st[0, 0] = 1

Given these changes, the copy should have the same states (and not default):

>>> d = e.copy()
>>> d.ga.points['ex_point'].s.occupied
True
>>> d.c.st[0, 0]
1.0

It should also be independent, meaning changes don’t effect the original:

>>> d.c.st[0, 1] = 1.0
>>> e.c.st[0, 1]
0.0
>>> d.ga.lines['ex_line'].s.occupied = True
>>> e.ga.lines['ex_line'].s.occupied
False

reset(): Reset the CommsFlow (and all subflows).