fmdtools.define.container

Package defining system variables other base constructs.

The containers subpackage provides the elemental building puzzle pieces needed (i.e., containers for holding states, modes, etc.) to develop simulations, shown below.

Container classes in fmdtools and their inheritance.

These classes are provided in the following modules:

fmdtools.define.container.base	Defines BaseContainer class which other containers inherit from.
fmdtools.define.container.mode	Defines Mode class for defining (faulty and otherwise) mode s.
fmdtools.define.container.state	Defines State class for representing variables that change over time.
fmdtools.define.container.parameter	Defines Parameter class to represent attributes that do not change.
fmdtools.define.container.rand	Defines Rand class and other methods defining random properties used in blocks.
fmdtools.define.container.time	Defines Time class for containing timers and time-related constructs.

fmdtools.define.container.base

Defines BaseContainer class which other containers inherit from.

class fmdtools.define.container.base.BaseContainer

Bases: dataobject

Base container class.

A container is a dataobject (from the recordclass library) that fulfills a specific role in a block. This class inherits from dataobject for low memory footprint and has a number of methods for making attribute assignment/copying/tracking easier.

asdict()

Return fields as a dictionary.

assign(obj, *fields, as_copy=True, **fielddict)

Set the same-named values of the current object to those of another.

Further arguments specify which values. e.g.,:

>>> p1 = ExContainer(x=0.0, y=0.0)
>>> p2 = ExContainer(x=10.0, y=20.0)
>>> p1.assign(p2, 'x', 'y')
>>> p1.x
10.0
>>> p1.y
20.0

Can also be used to assign list values to a variable, e.g.,:

>>> p1.assign([3.0,4.0], 'x', 'y')
>>> p1.x
3.0
>>> p1.y
4.0

Can also provide kwargs in case value names don’t match, e.g.,:

>>> p1.assign(p2, x='y', y='x')
>>> p1.x
20.0
>>> p1.y
10.0

as_copy: bool,

set to True for dicts/sets to be copied rather than referenced

base_type()

Return fmdtools type of the model class.

check_role(roletype, rolename)

Check that the container will be given the correct name for its class.

The correct container-names correspond to the role for the class embody, e.g.:

State : s Rand : r Mode : m Parameter : p SimParam : sp

copy()

Create an independent copy of the container with the same attributes.

Returns:

cop – Copy of the container with the same attributes as self.

Return type:

BaseContainer

Examples

>>> ex = ExContainer(4.0, 5.0)
>>> ex2 = ex.copy()
>>> ex2
ExContainer(x=4.0, y=5.0)

>>> ex_nest = ExNestContainer(ex2, 40.0)
>>> ex_nest.copy()
ExNestContainer(e1=ExContainer(x=4.0, y=5.0), z=40.0)

create_hist(timerange=None, track=None, default_str_size='<U20')

Create a History corresponding to the State.

Parameters:

• timerange (iterable, optional) – Time-range to initialize the history over. The default is None.

• track (list/str/dict, optional) – argument specifying attributes for :func:`get_sub_include’. The default is None.

Returns:

hist – History of fields specified in track.

Return type:

History

Examples

>>> nest_hist = ExNestContainer().create_hist()
>>> nest_hist
e1:
--x:                            array(1)
--y:                            array(1)
z:                              array(1)
>>> nest_hist.e1.x
[1.0]

default_track = 'all'

get_code(source)

Get the code defining the Container.

get_field_dict(obj, *fields, **fielddict)

Get dict of values from object corresponding to Container fields.

Parameters:

• obj (dataobject, list, tuple, or ndarray) – Object to get field dictionary from.

• *fields (str) – Names of corresponding fields (in self.__fields__)

• **fielddict – Mapping of fields in obj corresponding to fields in self.

Returns:

field_dict – Dictionary of fields and their values.

Return type:

dict

Examples

>>> ex = ExContainer(1.0, 2.0)
>>> ex.get_field_dict([5.0])
{'x': 5.0}

>>> ex2 = ExContainer(3.0, 4.0)
>>> ex.get_field_dict(ex2)
{'x': 3.0, 'y': 4.0}

>>> ex.get_field_dict({'x': 3.0, 'z': 40.0}, x='x', y='z')
{'x': 3.0, 'y': 40.0}

>>> ex.get_field_dict(ex)
{'x': 1.0, 'y': 2.0}

get_memory()

Get approximate memory impact of dataobject and its fields.

get_pref_attrs(prefix, space='_')

Return dict of Container attributes with ‘prefix_’ as the var name.

get_track(track)

Get tracking params for a given dataobject (State, Mode, Rand, etc).

Parameters:

• obj (dataobject) – State/Mode/Rand. Requires .default_track class variable.

• track (track) – str/tuple. Attributes to track. ‘all’ tracks all fields ‘default’ tracks fields defined in default_track for the dataobject ‘none’ tracks none of the fields

Returns:

track – fields to track

Return type:

tuple

get_true_field(fieldname, *args, **kwargs)

Get the value that will be set to fieldname given *args and **kwargs.

get_true_fields(*args, force_kwargs=False, **kwargs)

Resolve the args to pass given certain defaults, *args and **kwargs.

NOTE: must be used for pickling, since pickle passes arguments as *args and not **kwargs.

get_typename()

Containers are typed as containers unless specified otherwise.

init_hist_att(hist, att, timerange, track, str_size='<U20')

Initialize a field in the history.

reset()

return_mutables()

Return mutable aspects of the container.

rolename = 'x'

set_arg_type(*args, **kwargs)

Set Parameter field input to the predetermined field type.

e.g., if the input to parameter is int for a float field, this converts it to a float in initialization.

Parameters:

• obj (dataobject (or class)) – dataobject to get argument type for

• *args (*args) – args to dataobject

• **kwargs (**kwargs) – kwargs to dataobject

Returns:

• *new_args (tuple) – new args to dataobject (with proper type)

• **new_kwargs (dict) – new kwargs to dataobject (with proper type)

set_field(fieldname, value, as_copy=True)

Set the field of the container to the given value.

Parameters:

• fieldname (str) – Name of the field.

• value (value) – Value to set the field to.

• as_copy (bool, optional) – Whether to copy value. The default is True.

Examples

>>> ex_nest = ExNestContainer()
>>> ex_inside = ExContainer(3.0, 4.0)
>>> ex_nest.set_field('e1', ex_inside)
>>> ex_nest
ExNestContainer(e1=ExContainer(x=3.0, y=4.0), z=20.0)

to_default(*fieldnames)

Reset given fields to their default values.

Examples

>>> ex = ExContainer(3.0, 4.0)
>>> ex.to_default()
>>> ex
ExContainer(x=1.0, y=2.0)

>>> ex = ExContainer(4.0, 5.0)
>>> ex.to_default('x')
>>> ex
ExContainer(x=1.0, y=5.0)

class fmdtools.define.container.base.ExContainer(x: float = 1.0, y: float = 2.0)

Bases: BaseContainer

Create class ExContainer instance

x: float

y: float

class fmdtools.define.container.base.ExNestContainer(e1: ExContainer = ExContainer(x=1.0, y=2.0), z: float = 20.0)

Bases: BaseContainer

Create class ExNestContainer instance

e1: ExContainer

z: float

fmdtools.define.container.base.check_container_pick(container, *args, **kwargs)

Check that a given container class or object will pickle.

Examples

>>> ex = ExContainer()
>>> check_container_pick(ex)
True
>>> check_container_pick(ExContainer, x=2.0)
True
>>> check_container_pick(ExContainer, 5.0, 40.0)
True

fmdtools.define.container.mode

The following template shows the basic syntax to use to define modes:

Mode class template/example.

Defines Mode class for defining (faulty and otherwise) mode s.

Has classes:

• Fault: Class for defining fault parameters

• Mode: Class for defining the mode property (and associated probability model) held in Blocks.

class fmdtools.define.container.mode.ExampleMode(*args, s_kwargs={}, **kwargs)

Bases: Mode

Example mode for testing/docs.

exclusive = True

fault_no_charge = Fault(prob=1e-05, cost=100, phases=(('standby', 1.0),), disturbances=(), units='sim')

fault_short = (1e-05, 100, (('supply', 1.0),))

faults: set

mode: str

opermodes = ('supply', 'charge', 'standby')

sub_faults: bool

class fmdtools.define.container.mode.Fault(*args, failrate=1.0, **kwargs)

Bases: BaseContainer

Stores Default Attributes for individual fault modes.

Fields

probfloat

Mode probability or rate per operation

costfloat

Individual mode cost (e.g., of repair)

phasestuple

Opportunity vector mapping phases of operation to relative probability. i.e., phase_probability = Fault.prob * Fault.phases[phase] Has format (‘phasename1’, value, ‘phasename2’, value2)

disturbancestuple

Disturbances caused by the fault to aspect(s) of the containing simulable. e.g. (‘s.x’, 1.0, ‘s.y’, 2.0)

unitsstr

Units on probability. Can be a unit of continuous (‘sec’, ‘min’, ‘hr’, ‘day’) or discrete (‘sim’) time. Default is ‘sim’.

calc_rate(time, phasemap={}, sim_time=1.0, sim_units='hr', weight=1.0)

Calculate the rate of a given fault mode.

Parameters:

• time (float) – Time the fault will be injected.

• phasemap (PhaseMap, optional) – Map of phases/modephases that define operations the mode will be injected during (and maps to the opportunity vector phases). The default is {}.

• sim_time (float, optional) – Duration of the simulation. Used to determine fault exposure time when time-units (‘sec’, ‘min’, etc) define the fault rate. The default is 1.0.

• sim_units (float, optional) – Simulation time units. Used to determine fault exposure time when time-units define the fault rate. The default is ‘hr’.

• weight (float, optional) – Weight for the fault/scenario (e.g., for multiple scens.). The default is 1.

Returns:

rate – Calculated rate of the scenario with the given information.

Return type:

float

Examples

>>> # Calculating the rate of a mode in the 'on phase':
>>> from fmdtools.analyze.phases import PhaseMap
>>> pm = PhaseMap({'on': [0, 5], 'off': [6, 10]})
>>> exfault = Fault(prob=0.5, phases = {'on': 0.9, 'off': 0.1}, units='hr')
>>> rate = exfault.calc_rate(4, pm, sim_time=10.0, sim_units='min')
>>> # note that this rate is the same as what we would calculate:
>>> manual_calc = 0.5 * 6 * 0.9 / 60
>>> manual_calc == rate
True
>>> rate_off = exfault.calc_rate(7, pm, sim_time=10.0, sim_units='min')
>>> # note that the interval for off (6-10) is 5 while (0-5) is 6
>>> manual_calc_off = 0.5 * 5 * 0.1 / 60
>>> manual_calc_off == rate_off
True

cost: float

disturbances: tuple

phases: tuple

prob: float

units: str

class fmdtools.define.container.mode.FlexibleMode(faults: set = set(), sub_faults: bool = False, faultmodes: dict = {})

Bases: Mode

Create class FlexibleMode instance

faultmodes: dict

faults: set

fm_args = {}

fs_args = {}

get_all_faultnames()

Get all names of faults.

get_fault(faultname)

Get the Fault object associated with the given faultname.

Parameters:

faultname (str) – Name of the fault (if defined as a part of the mode at value fault_name). Can also be parameters of the fault.

Returns:

fault – Fault container with given fields..

Return type:

Fault

init_faultmodes(**faults)

Initialize the self.faultmodes dictionary from the parameters of the Mode.

Parameters:

**faults (kwargs) – Arguments to instantiate for the faultmodes. e.g., faultname=(0.1, 200).

init_faultspace(franges, n='all', seed=42, prefix='hmode_', **kwargs)

Associate n-disturbance mode combinations as faults.

Parameters:

• franges (dict, optional) – Dictionary of form {‘varname’: {val1, val2…} of ranges of values for for each disturbance (if used to generate modes). The default is {}.

• n (int, optional) – Number of faultstate combinations to sample. The default is ‘all’.

• seed (int, optional) – Seed used in selection (if n!=’all). The default is 42.

• prefix (str) – Prefix of fault names. Default is “hmode_”

• **kwargs (kwargs) – Entries for the Fault (e.g., phases, etc)

set_field(fieldname, value, as_copy=True)

Extend BaseContainer.assign to not set faultmodes (always the same).

sub_faults: bool

class fmdtools.define.container.mode.HumanErrorMode(*args, **kwargs)

Bases: Mode

Mode for Human Errors using HEART-based model.

Overall failrate of human error determined by given:

gtpfloat

Generic task probability

epc_XXtuple/list

Error producing condition factors. May be specified as performance shaping factors or tuple (factor, effect proportion).

Examples

>>> class ExHMode(HumanErrorMode):
...     gtp : float = 0.01
...     epc_1 : tuple = (2, 0.5)
>>> exh = ExHMode()
>>> exh.failrate
0.015
>>> class ExHMode2(HumanErrorMode):
...     gtp : float = 0.01
...     epc_1 : float = 2.0
...     epc_2 : float = 3.0
>>> exh2 = ExHMode2()
>>> exh2.failrate
0.06

calc_he_rate()

Calculate self.failrate based on a human error probability model.

This model uses an overall generic task probability (set by self.gtp) as well as error producing conditions (EPCs) to determine the overall failure rate of the task.

failrate: float

faults: set

gtp = 1.0

sub_faults: bool

class fmdtools.define.container.mode.Mode(*args, s_kwargs={}, **kwargs)

Bases: BaseContainer

Class for defining the mode property (and probability model) held in Blocks.

Mode is meant to be inherited in order to define the specific faults related to a given Block.

Class Variables

opermodestuple

Names of non-faulty operational modes.

failratefloat

Overall failure rate for the block. The default is 1.0. Note that if a failrate is provided, the prob argument in faultparams is a conditional probability (e.g. Fault.prob = Mode.failrate * Mode.faultparams[‘mode’][‘prob’]).

probtypestr, optional

Type of probability in the probability model, a per-time ‘rate’ or per-run ‘prob’. The default is ‘rate’.

exclusiveTrue/False

Whether fault modes are exclusive of each other or not. Default is False (i.e. more than one can be present).

default_xxfloat

Default values for Fault fields (e.g., prob, phases, etc)

These fields are then used in simulation and elsewhere.

Fields

faultsset

Set of faults present (or not) at any given time

sub_faultsbool

Whether objects contained by the object are faulty.

modestr

Name of the current mode. the default is ‘nominal’

faultmodesdict

Dictionary of Fault defining possible fault modes and their properties

Examples

>>> class ExampleMode(Mode):
...    fault_no_charge = Fault(1e-5, 100, (('standby', 1.0),))
...    fault_short = (1e-5, 100, (('supply', 1.0),))
...    opermodes = ("supply", "charge", "standby")
...    exclusive = True
...    mode: str = "standby"
>>> exm = ExampleMode()
>>> exm.mode
'standby'
>>> exm.any_faults()
False
>>> exm.get_faults()
{'no_charge': Fault(prob=1e-05, cost=100, phases=(('standby', 1.0),), disturbances=(), units='sim'), 'short': Fault(prob=1e-05, cost=100, phases=(('supply', 1.0),), disturbances=(), units='sim')}

add_fault(*faults)

Add fault (a str) to the block.

Parameters:

*fault (str(s)) – name(s) of the fault to add to the black

any_faults()

Check if the block has any fault modes.

base_type()

Return fmdtools type of the model class.

default_track = ('mode', 'faults', 'sub_faults')

exclusive = False

failrate = 1.0

faults: set

get_all_faultnames()

Get all names of faults.

get_fault(faultname)

Get the Fault object associated with the given faultname.

Parameters:

faultname (str) – Name of the fault (if defined as a part of the mode at value fault_name). Can also be parameters of the fault.

Returns:

fault – Fault container with given fields..

Return type:

Fault

get_fault_disturbances(*faults)

Get all disturbances caused by present (or specified) faults.

get_faults(*faults)

Get Fault objects for all associated faults.

has_fault(*faults)

Check if the block has fault (a str).

Parameters:

*faults (strs) – names of the fault to check.

in_mode(*modes)

Check if the system is in a given operational mode.

Parameters:

*modes (strs) – names of the mode to check

init_hist_att(hist, att, timerange, track, str_size='<U20')

Add field ‘att’ to history. Accommodates faults and mode tracking.

mode = 'nominal'

no_fault(fault)

Check if the block does not have fault (a str).

Parameters:

fault (str) – name of the fault to check.

opermodes = ('nominal',)

remove_any_faults(opermode=False, warnmessage=False)

Reset fault mode to nominal and returns to the given operational mode.

Parameters:

• opermode (str (optional)) – operational mode to return to when the fault mode is removed

• warnmessage (str/False) – Warning to give when performing operation. Default is False (no warning)

remove_fault(fault_to_remove, opermode=False, warnmessage=False)

Remove fault in the set of faults and returns to given operational mode.

Parameters:

• fault_to_replace (str) – name of the fault to remove

• opermode (str (optional)) – operational mode to return to when the fault mode is removed

• warnmessage (str/False) – Warning to give when performing operation. Default is False (no warning)

replace_fault(fault_to_replace, fault_to_add)

Replace fault_to_replace with fault_to_add in the set of faults.

Parameters:

• fault_to_replace (str) – name of the fault to replace

• fault_to_add (str) – name of the fault to add in its place

return_mutables()

Return mutable aspects of the container.

rolename = 'm'

set_mode(mode)

Set a mode in the block.

Parameters:

mode (str) – name of the mode to enter.

sub_faults: bool

to_fault(fault)

Move from the current fault mode to a new fault mode.

Parameters:

fault (str) – name of the fault mode to switch to

fmdtools.define.container.state

Defines State class for representing variables that change over time.

State classes are used to represent mutables properties of the system that change over time.

State classes are extended and deployed by the user, as shown below:

Example of extending the State class to hold x/y fields.

The following template shows the basic syntax used to define states:

State class template/example.

class fmdtools.define.container.state.State

Bases: BaseContainer

Class for working with model states.

States which are variables in the model which change over time.

State is meant to be extended in the model definition object to add the corresponding field related to a simulation, e.g.,

>>> class ExampleState(State):
...     x : float=1.0
...     y : float=1.0

Creates a class point with fields x and y which are tagged as floats with default values of 1.0.

Instancing State gives normal read/write access, e.g., one can do:

>>> p = ExampleState()
>>> p.x
1.0

or:

>>> p = ExampleState(x=10.0)
>>> p.x
10.0

add(*states)

Return the addition of given attributes of the State.

Examples

>>> p = ExampleState(x=1.0, y=2.0)
>>> p.add('x','y')
3.0

base_type()

Return fmdtools type of the model class.

div(*states)

Return the division of given attributes of the State.

Examples

>>> p = ExampleState(x=1.0, y=2.0)
>>> p.div('x','y')
0.5

get(*attnames, **kwargs)

Return the given attribute names (strings) as a numpy array.

Mainly useful for reducing length of lines/adding clarity to assignment statements. e.g.,:

>>> p = ExampleState(x=1.0, y=2.0)
>>> p_arr = p.get("x", "y")
>>> p_arr
array([1., 2.])
>>> p.get("x")
1.0
>>> p.get("x", "y", as_array=False)
[1.0, 2.0]

gett(*attnames)

Alternative to self.get that returns a tuple, not an array.

Useful when a numpy array would translate the underlying data types poorly (e.g., np.array([1,’b’] would make 1 a string–using a tuple instead preserves the data type)).

Examples

>>> ExampleState().gett("x")
1.0
>>> ExampleState().gett("x", "y")
(1.0, 1.0)

inc(**kwargs)

Increment the given arguments by a given value.

Mainly useful for reducing length/adding clarity to increment statements, e.g.,:

>>> p = ExampleState(x=1.0, y=1.0)
>>> p.inc(x=1, y=2)
>>> p.x
2.0
>>> p.y
3.0

Can additionally be provided with a second value denoting a limit on the increments e.g.,:

>>> p = ExampleState(x=1.0, y=1.0)
>>> p.inc(x=(3, 5.0))
>>> p.x
4.0
>>> p.inc(x=(3, 5.0))
>>> p.x
5.0

init_hist_att(hist, att, timerange, track, str_size='<U20')

Extend init_hist_attr to use _set to get history size.

limit(**kwargs)

Enforce limits on the value of a given property.

Mainly useful for reducing length/adding clarity to increment statements. e.g.,:

>>> p = ExampleState(x=200.0, y=-200.0)
>>> p.limit(x=(0.0,100.0), y=(0.0, 100.0))
>>> p.x
100.0
>>>
0.0

mul(*states)

Return the multiplication of given attributes of the State.

Examples

>>> p = ExampleState(x=2.0, y=3.0)
>>> p.mul("x","y")
6.0

put(as_copy=True, **kwargs)

Set the given fields to a given value.

Mainly useful for reducing length/adding clarity to assignment statements.

Parameters:

• as_copy (bool) – set to True for dicts/sets to be copied rather than referenced

• **kwargs (values) – fields and values to set.

Examples

>>> p = ExampleState()
>>> p.put(x=2.0, y=2.0)
>>> p.x
2.0
>>> p.y
2.0

roundto(**kwargs)

Round the given arguments to a given resolution.

Examples

>>> p = ExampleState(x=1.75850)
>>> p.roundto(x=0.1)
>>> p.x
1.8

same(*args, **kwargs)

Test whether a given iterable values has the same value as each in the state.

Examples

>>> p = ExampleState(x=1.0, y=2.0)
>>> p.same([1.0, 2.0], "x", "y")
True
>>> p.same([0.0, 2.0], "x", "y")
False
>>> p.same([1.0], 'x')
True
>>> p.same(x=1.0, y=2.0)
True
>>> p.same(x=0.0, y=0.0)
False

set_atts(**kwargs)

Set the given arguments to a given value.

Mainly useful for reducing length/adding clarity to assignment statements in __init__ methods (self.put is recomended otherwise so that the iteration is on function/flow states) e.g.,

>>> p = ExampleState()
>>> p.set_atts(x=2.0, y=2.0)
>>> p.x
2.0
>>> p.y
2.0

sub(*states)

Return the subtraction of given attributes of the State.

Examples

>>> p = ExampleState(x=1.0, y=2.0)
>>> p.sub('x','y')
-1.0

values()

Return the values of the defined fields for the state.

warn(*messages, stacklevel=2)

Print warning message(s) when called.

Parameters:

• *messages (str) – Strings to make up the message (will be joined by spaces)

• stacklevel (int) – Where the warning points to. The default is 2 (points to the place in the model)

fmdtools.define.container.parameter

Defines Parameter class to represent attributes that do not change.

Parameter classes are used to represent immutable properties of the system. Parameter classes are extended and deployed by the user, as shown below:

Example of extending the Parameter class to hold x/y/z fields.

The following template shows the basic syntax to use to define parameters:

Parameter class template/example.

class fmdtools.define.container.parameter.Parameter(*args, strict_immutability=True, check_type=True, check_pickle=True, set_type=True, check_lim=True, **kwargs)

Bases: BaseContainer

The Parameter class defines model/function/flow values which are immutable.

That is, the same from model instantiation through a simulation. Parameters inherit from recordclass, giving them a low memory footprint, and use type hints and ranges to ensure parameter values are valid. e.g.,:

Examples

>>> class ExampleParameter(Parameter, readonly=True):
...    x: float = 1.0
...    y: float = 3.0
...    z: float = 0.0
...    x_lim = (0, 10)
...    y_set = (1.0, 2.0, 3.0, 4.0)

defines a parameter with float x and y fields with default values of 30 and x_lim minimum/maximum values for x and y_set possible values for y. Note that readonly=True should be set to ensure fields are not changed.

This parameter can then be instantiated using:

>>> p = ExampleParameter(x=1.0, y=2.0)
>>> p.x
1.0
>>> p.y
2.0

>>> p.copy()
ExampleParameter(x=1.0, y=2.0, z=0.0)

base_type()

Return fmdtools type of the model class.

check_immutable()

Check if a known/common mutable or a known/common immutable.

If known immutable, raise exception. If not known mutable, give a warning.

Raises:

Exception – Throws exception if a known mutable (e.g., dict, set, list, etc)

check_lim(k, v)

Checks to ensure the value v for field k is within the defined limits self.k_lim or set constraints self.k_set

Parameters:

• k (str) – Field to check

• v (mutable) – Value for the field to check

Raises:

Exception – Notification that the field is outside limits/set constraints.

check_pickle()

Checks to make sure pickled object will get *args and **kwargs

check_type()

Check to ensure Parameter type-hints are being followed.

Raises:

Exception – Raises exception if a field is not the same as its defined type.

copy()

Create an independent copy of the container with the same attributes.

Returns:

cop – Copy of the container with the same attributes as self.

Return type:

BaseContainer

Examples

>>> ex = ExContainer(4.0, 5.0)
>>> ex2 = ex.copy()
>>> ex2
ExContainer(x=4.0, y=5.0)

>>> ex_nest = ExNestContainer(ex2, 40.0)
>>> ex_nest.copy()
ExNestContainer(e1=ExContainer(x=4.0, y=5.0), z=40.0)

copy_with_vals(**kwargs)

Creates a copy of itself with modified values given by kwargs

reset()

Do nothing since the parameter is immutable.

return_mutables()

Return mutable aspects of the container.

fmdtools.define.container.rand

Defines Rand class and other methods defining random properties used in blocks.

Has public Classes and Functions:

• Rand: Superclass for Block random properties.

• get_pfunc_for_dist(): Gets the corresponding probability mass/density for outcome x for probability distributions with name ‘randname’ in numpy.

• get_prob_for_rand(): Gets the corresponding probability mass/density for random sample x from ‘randname’ function in numpy.

• calc_prob_for_integers(): Calculate probability for random.integers.

• calc_prob_density_for_random(): Calc probability density for random.random.

• calc_prob_for_choice(): Calculate probability for random.choice.

• calc_prob_for_shuffle_permutation(): Calculate probability for random.shuffle and random.permutation.

• calc_prob_for_permuted(): Calculate probability for random.permuted.

• :func:`array

class fmdtools.define.container.rand.ExampleRand(*args, seed=42, s_kwargs={}, **kwargs)

Bases: Rand

Example Rand for testing and docs.

probdens: float

probs: list

rng: Generator

run_stochastic: bool

s: RandState

seed: int

class fmdtools.define.container.rand.Rand(*args, seed=42, s_kwargs={}, **kwargs)

Bases: BaseContainer

Class for defining and interacting with random states of the model.

rng

random number generator

Type:

np.random.default_rng

probs

probability of the given states

Type:

list

seed

state for the random number generator

Type:

int

Examples

Rand is meant to be extended in model definition with random states, e.g.:

>>> class RandState(State):
...     noise: float=1.0
>>> class ExampleRand(Rand):
...     s: RandState = RandState()

Which enables the use of set_rand_state, update_stochastic_states, etc for updating these states with methods called from the rng when run_stochastic=True.

>>> exr = ExampleRand(run_stochastic='track_pdf')
>>> exr.set_rand_state('noise', 'normal', 1.0, 1.0)
>>> exr.s
RandState(noise=1.3047170797544314)
>>> exr.probs
[0.3808442490605113]

Checking copy:

>>> exr2 = exr.copy()
>>> exr2.s
RandState(noise=1.3047170797544314)
>>> exr2.run_stochastic
'track_pdf'
>>> exr2.rng.__getstate__()['state'] == exr.rng.__getstate__()['state']
True

More state setting: >>> exr.set_rand_state(‘noise’, ‘normal’, 1.0, 1.0) >>> exr.probs [0.3808442490605113, 0.23230084450139615] >>> exr.return_probdens() 0.08847044068025682 >>> exr2.probs [0.3808442490605113]

base_type()

Return fmdtools type of the model class.

default_track = ('s', 'probdens')

get_rand_states(auto_update_only=False)

Get the randomly-assigned states associated with the Rand at self.s.

Parameters:

auto_update_only (bool, optional) – Whether to only get auto-updated states. The default is False.

Returns:

rand_states – States in self.s

Return type:

dict

Examples

>>> ExampleRand().get_rand_states()
{'noise': 1.0}
>>> ExampleRand().get_rand_states(auto_update_only=True)
{}

init_hist_att(hist, att, timerange, track, str_size='<U20')

Add field ‘att’ to history. Accommodates track_pdf option.

probdens: float

probs: list

reset()

Reset Rand to the initial state.

return_mutables()

Get mutable rand states.

return_probdens()

Return probability density/mass corresponding to random sim.

rng: Generator

rolename = 'r'

run_stochastic: bool

seed: int

set_field(fieldname, value, as_copy=True)

Extend BaseContainer.assign to accomodate the rng.

set_rand_state(statename, methodname, *args)

Update the given random state with a given method and arguments.

(if in run_stochastic mode)

Parameters:

• statename (str) – name of the random state defined

• methodname – str name of the numpy method to call in the rng

• *args (args) – arguments for the numpy method

set_rng(other_rng)

Set the state of the rng in the Rand to the same state as other_rng.

update_seed(seed)

Update the random seed to the given value.

update_stochastic_states()

Update the defined stochastic states defined to auto-update.

class fmdtools.define.container.rand.RandState

Bases: State

Example random state for testing and docs.

noise: float

fmdtools.define.container.rand.as_prob(pd)

Return array output of probabilities as single joint probability.

fmdtools.define.container.rand.calc_prob_density_for_random(x)

Get probability density for np.default_rng.random.

Examples

>>> calc_prob_density_for_random([0.5])
1.0
>>> calc_prob_density_for_random([0.5, 0.1, 0.9, 0.5])
0.25
>>> calc_prob_density_for_random([0.5, 0.1, 0.9, 0.5, 1.1])
0.0

fmdtools.define.container.rand.calc_prob_for_choice(x, options=[], size=1, replace=True, p=None)

Get probability corresponding to a call to np.choice.

Examples

>>> calc_prob_for_choice([1], [1,2])
0.5
>>> calc_prob_for_choice([1,2], [1,2], replace=False)
0.5
>>> calc_prob_for_choice([1,2], [1,2,3], p=[0.1, 0.1, 0.9])
0.01

fmdtools.define.container.rand.calc_prob_for_integers(x, *args)

Get probability for np.default_rng.integers.

Examples

>>> calc_prob_for_integers([0], 2)
0.5
>>> calc_prob_for_integers([0, 1], 0, 2)
0.25
>>> calc_prob_for_integers([0, 1, 2], 0, 2)
0.0

fmdtools.define.container.rand.calc_prob_for_permuted(x, axis=None)

Get probability corresponding to rng.permuted.

Examples

>>> calc_prob_for_permuted(np.array([[1,2], [3,4]]))
0.041666666666666664
>>> calc_prob_for_permuted(np.array([[1,2], [3,4], [5,6]]), 0)
0.16666666666666666
>>> calc_prob_for_permuted(np.array([[1,2], [3,4], [5,6]]), 1)
0.5

fmdtools.define.container.rand.calc_prob_for_shuffle_permutation(x, options, *args, check_valid=True)

Get probability corresponding to rng.shuffle and rng.permutation.

Examples

>>> calc_prob_for_shuffle_permutation([1,2], [1,2])
0.5
>>> calc_prob_for_shuffle_permutation([2,1,3], [1,2,3])
0.16666666666666666

fmdtools.define.container.rand.get_custom_pfunc(func_handle, *args, **kwargs)

Get callable for calc_func pdf/pmf function with provided arguments.

fmdtools.define.container.rand.get_exp_ray_pdf(randname, *args)

Get callable for scipy exponential and rayleigh pdf with numpy.random arguments.

Examples

>>> get_exp_ray_pdf("rayleigh", 2)(2.0)
0.3032653298563167
>>> get_exp_ray_pdf("rayleigh", 2, 2)(2.0)
0.0
>>> get_exp_ray_pdf("exponential", 1)(0.0)
1.0
>>> get_exp_ray_pdf("exponential", 1, -1.0)(0.0)
0.36787944117144233

fmdtools.define.container.rand.get_hypergeometric_pmf(*args)

Get callable for scipy hypergeomeric pmf with numpy.random arguments.

Examples

>>> get_hypergeometric_pmf(50, 450, 100)(10)
0.14736784420411747

fmdtools.define.container.rand.get_lognormal_pdf(*args)

Get callable for scipy lognormal pdf with numpy.random arguments.

Examples

>>> get_lognormal_pdf(0, .25)(1.0)
1.5957691216057308

fmdtools.define.container.rand.get_pfunc_for_dist(randname, *args)

Get the probability mass/density function corresponding to a numpy random draw.

Uses a call to scipy.stats when available (with the correct arguments), otherwise uses a custom function provided in this module.

Parameters:

• randname (str) – Name of numpy.random distribution

• args (tuple) – Arguments sent to numpy.random distribution

Returns:

pfunc – pdf/pmf for the draw.

Return type:

callable

fmdtools.define.container.rand.get_prob_for_rand(x, randname, *args)

Get the probability density/mass for random sample x.

Pulled from ‘randname’ function in numpy. Calls get_pfunc_for_dist when scipy has a corresponding distribution function, otherwise calls custom functions to calculate the probabilities/probability densities.

Parameters:

• x (int/float/array) – samples to get probability mass/density of

• randname (str) – Name of numpy.random distribution

• *args (tuple) – Arguments sent to numpy.random distribution

Returns:

prob

Return type:

float of probability density or mass, depending on function

Examples

>>> get_prob_for_rand(0, "normal", 0, 1)
0.3989422804014327
>>> get_prob_for_rand([0,0], "normal", 0, 1)
0.15915494309189535
>>> get_prob_for_rand(2, "integers", 4)
0.25

fmdtools.define.container.rand.get_scipy_pdf(randname, *args, **kwargs)

Get callable for scipy pdf function with given name and arguments.

fmdtools.define.container.rand.get_scipy_pmf(randname, *args, **kwargs)

Get callable for scipy pmf function with given name and arguments.

fmdtools.define.container.rand.get_standard_t_pdf(*args)

Get callable for scipy multivariate_t dist for a numpy.random.standard_t call.

Note: doesn’t support len(x)>1.

Examples

>>> get_standard_t_pdf(1)([0.0])
0.31830988618379075

fmdtools.define.container.rand.get_triangular_pdf(*args)

Get callable for scipy.triang corresponding to a numpy.random.triangular call.

Examples

>>> get_triangular_pdf(0,1,2)(0.0)
0.0
>>> get_triangular_pdf(0,1,2)(1.0)
1.0
>>> get_triangular_pdf(0,1,2)(1.5)
0.5
>>> get_triangular_pdf(0,1,2)(0.5, 0.5)
0.25

fmdtools.define.container.rand.get_vonmises_pdf(*args)

Get callable for scipy.vonmises corresponding to numpy.random arguments.

fmdtools.define.container.time

Defines Time class for containing timers and time-related constructs.

class fmdtools.define.container.time.ExtendedTime(*args, **kwargs)

Bases: Time

Example extended time class for testing, etc.

dt: float

run_times: int

t_ind: int

t_loc: float

time: float

timernames = ('t1', 't2')

timers: dict

use_local: bool

class fmdtools.define.container.time.Time(*args, **kwargs)

Bases: BaseContainer

Class for defining all time-based aspects of a Block (e.g., time, timestep, timers).

time

real time for the model

Type:

float

dt

timestep size

Type:

float

t_ind

index of the given time

Type:

int

t_loc

local time (e.g., for actions with durations)

Type:

float

run_times

number of times to run the behavior if running at a different timestep than global

Type:

int

timers

dictionary of instantiated timers

Type:

dict

use_local

Whether to use the local timetep (vs global timestep)

Type:

bool

timernames

Names of timers to instantiate.

Type:

tuple

Examples

Extending the time class gives one access to a dict of timers:

>>> class ExtendedTime(Time):
...     timernames = ('t1', 't2')

>>> t = ExtendedTime()
>>> t.timers['t1']
Timer t1: mode= standby, time= 0.0

These timers can then be used:

>>> t.timers['t1'].inc(1.0)
>>> t.timers['t1']
Timer t1: mode= ticking, time= 1.0

Checking copy:

>>> t2 = t.copy()
>>> t2.timers
{'t1': Timer t1: mode= ticking, time= 1.0, 't2': Timer t2: mode= standby, time= 0.0}

Check that copied timers are independent:

>>> t2.timers['t1'].__hash__() == t.timers['t1'].__hash__()
False

base_type()

Return fmdtools type of the model class.

default_track = 'timers'

dt: float

init_hist_att(hist, att, timerange, track, str_size='<U20')

Add field ‘att’ to history. Accommodates time and timer tracking.

local_dt = 1.0

reset()

Reset time to the initial state.

return_mutables()

Return mutable aspects of the container.

rolename = 't'

run_times: int

set_timestep()

Set the timestep of the function given.

If using the option use_local, local_timestep is used instead of global_timestep.

t_ind: int

t_loc: float

time: float

timernames = ()

timers: dict

use_local: bool