fmdtools.define.block

Package for defining system behaviors.

The block subpackage provides a representation of behavioral blocks, which are simulable models which may contain containers and other properties.

These variants of block are provided in the following modules:

fmdtools.define.block.base	Defines base Simulable and Block classes for defining simulations.
fmdtools.define.block.action	Defines Action class for representing discrete actions.
fmdtools.define.block.component	Defines Component class for representing system components.
fmdtools.define.block.function	Defines Function class for representing system functional behaviors.

fmdtools.define.block.base

Defines base Simulable and Block classes for defining simulations.

Classes:

• Simulable: Superclass for architectures and blocks.

• Block: Superclass for Functions, Components, Actions, etc.

class fmdtools.define.block.base.Block(name='', flows={}, h={}, **kwargs)

Bases: Simulable

Superclass for Function, Component, and Action subclasses.

Has functions for model setup, querying state, and reseting the model.

p

Internal Parameter for the block. Instanced from container_p

Type:

Parameter

s

Internal State of the block. Instanced from container_s.

Type:

State

m

Internal Mode for the block. Instanced from container_m

Type:

Mode

r

Internal Rand for the block. Instanced from container_r

Type:

Rand

t

Internal Time for the block. Instanced from container_t

Type:

Time

name

Block name

Type:

str

flows

Dictionary of flows included in the Block (if any are added via flow_flowname)

Type:

dict

base_type()

Return fmdtools type of the model class.

check_dict_creation = True

check_flows(flows={})

Associate flows with the given Simulable.

Flows must be defined with the flow_flowname class variable pointing to the class to initialize (e.g., flow_flowname = FlowClass).

Parameters:

flows (dict, optional) – If flows is provided AND it contains a flowname corresponding to the function’s flowname, it will be used instead (so that it can act as a connection to the rest of the model)

choose_rand_fault(faults, default='first', combinations=1)

Randomly chooses a fault or combination of faults to insert in fxn.m.

Parameters:

• faults (list) – list of fault modes to choose from

• default (str/list, optional) – Default fault to inject when model is run deterministically. The default is ‘first’, which chooses the first in the list. Can provide a mode as a str or a list of modes

• combinations (int, optional) – Number of combinations of faults to elaborate and select from. The default is 1, which just chooses single fault modes.

containers = ('t', 'sp')

copy(*args, flows={}, **kwargs)

Copy the block with its current attributes.

Parameters:

• args (tuple) – New arguments to use to instantiate the block, (e.g., flows, p, s)

• kwargs – New kwargs to use to instantiate the block.

Returns:

cop – copy of the exising block

Return type:

Block

create_arch_kwargs(**kwargs)

Create keyword arguments for contained architectures.

Enables the passing of flows from block to contained architecture level.

create_repr(rolenames=['s', 'm'], **kwargs)

Restricts default repr to state and mode.

default_track = ['s', 'm', 'r', 't', 'i']

flows = ()

get_flows()

Return a dictionary of the Block’s flows.

get_flowtypes()

Return the names of the flow types in the model.

Returns:

flowtypes – Set of flow type names in the model.

Return type:

set

get_rand_states(auto_update_only=False)

Get dict of random states from block and associated actions/components.

Parameters:

auto_update_only

Returns:

rand_states – Random states from the block and associated actions/components.

Return type:

dict

h

indicators

init_block(**kwargs)

Initilialization method to set initial states etc (placeholder).

m

mut_kwargs

mutables

name

p

r

roletypes = ['container', 'flow']

root

s

sp

t

track

class fmdtools.define.block.base.SimParam(*args, **kwargs)

Bases: Parameter

Class defining Simulation parameters.

Parameters:

• phases (tuple) – phases ((‘name’, start, end)…) that the simulation progresses through

• start_time (float) – Start time of the simulation.

• end_time (float) – End time of the simulation.

• track_times (tuple) –

  Defines what times to include in the history. Options are: - (‘all’,)–all simulated times - (‘interval’, n)–includes every nth time in the history - (‘times’, [t1, … tn])–only includes times defined in the

  vector [t1 … tn]

• dt (float) – time-step used in the simulation. default is 1.0

• units (str) – time-units. default is hours`

• end_condition (str) – Name of indicator method to use to end the simulation. If not provided (‘’), the simulation ends at the final time. Default is ‘’

• use_local (bool) – Whether to use locally-defined time-steps in functions (if any). Default is True.

• with_loadings (bool) – Whether to execute simulable with defined loading methods. Default is False.

• run_stochastic (bool) – Whether to run stochastic behaviors or use default values. Default is False.

• track_pdf (bool) – If run_stochastic=True, track_pdf is used to calculate/track the probability densities of random states over time.

base_type()

Return fmdtools type of the model class.

dt: float

end_condition: str

end_time: float

find_any_phase_overlap()

Check that simparam phases don’t overlap.

get_hist_ind(t_ind, t)

Get the index of the history given the simulation time/index and shift.

Examples

>>> SimParam().get_hist_ind(2, 2.0)
2
>>> SimParam(track_times=('interval', 2)).get_hist_ind(4, 4.0)
2

get_histrange(start_time=0.0, end_time=None)

Get the history range associated with the SimParam.

get_sub_kwargs()

Get keyword arguments for contained sim from larger sim.

get_timerange(start_time=None, end_time=None, min_r=7)

Generate the timerange to simulate over.

Examples

>>> SimParam(end_time=5.0).get_timerange()
array([0., 1., 2., 3., 4., 5.])

phases: tuple

rolename = 'sp'

run_stochastic: bool

start_time: float

track_pdf: bool

track_times: tuple

units: str

units_set = ('sec', 'min', 'hr', 'day', 'wk', 'month', 'year')

use_local: bool

with_loadings: bool

class fmdtools.define.block.base.Simulable(**kwargs)

Bases: BaseObject

Base class for object which simulate (blocks and architectures).

Note that classes solely based on Simulable may not be able to be simulated.

Parameters:

• t (Time) – Time tracker and options.

• sp (SimParam) – Parameters defining the simulation.

• mut_kwargs (dict) – Non-default kwargs for mutable containers/roles (to use for reset)

classify(scen={}, **kwargs)

Classify the results of the simulation (placeholder).

container_sp

alias of SimParam

container_t

alias of Time

containers = ('t', 'sp')

cut_hist()

Cut the simulation history to the current time.

default_sp = {}

default_track = ['all']

execute_static_behaviors()

Execute static behaviors.

get_endclass(to_return={}, result={}, **kwargs)

Get the end-state classification from self.classify().

Parameters:

• to_return (iterable, optional) – Iterable with attributes to get from model. If “class” is in to_return, it returns the whole dictionary. If “class.att” is in to_return, it gets the attribute “att” from dict returned by classify(). The default is {}.

• result (Result, optional) – Result to add the result to. The default is Result().

• **kwargs (kwargs) – Keyword arguments to self.classify().

Returns:

result – Result with returned class attributes.

Return type:

Result

get_fault(scope, faultmode, **kwargs)

Get the named Fault for the Simulable in the given scope of the model.

Will also get a Fault for a contained object at the given scope.

Parameters:

• scope (str) – Scope to get the fault from (e.g., self.name, ‘self’, or ‘global’)

• faultmode (str) – Name of the fault (e.g., “short”).

• **kwargs (kwargs) – Keyword arguments to Mode.get_fault.

get_faults(with_sub_faults=True, with_base_faults=True, only_present=True)

Get faults associated with the given block.

Parameters:

• with_sub_faults (bool, optional) – Whether to get faults from the block. The default is True.

• with_base_faults (bool, optional) – Whether to get faults from objects contained by the block. The default is True.

• only_present (bool, optional) – Whether to get only present faults (if True) or all possible faults. The default is True.

Returns:

all_faults – Dictionary of blocks and faults present in the block. Of structure {blockname: faults}

Return type:

dict

get_fxns()

Get fxns associated with the Simulable (self if Function, self.fxns if Model).

Returns:

fxns – Dict with structure {fxnname: fxnobj}

Return type:

dict

get_resgraph(to_return={}, result={}, nomresult={})

Get the graph corresponding to the state of the simulation.

Parameters:

• to_return (iterable, optional) – Iterable with attributes to get from the model. If “graph” is in to_return, it returns the graph from self.get_modelgraph. If “graph.obj” is in to_return, it returns the graph from obj.get_modelgraph. If to_return is a dict, the values of the dict can specify arguments to get_modelgraph. The default is {}.

• result (Result, optional) – Result to add the graph to. The default is Result().

• nomresult (dict, optional) – Nominal result. If provided, set_resgraph() adds degradations to the graph attributes. The default is {}.

Returns:

result – Result with graph added.

Return type:

Result

get_result(to_return={}, nomresult={}, **kwargs)

Get the Result for the simulation corresponding to to_return.

Parameters:

• to_return (iterable, optional) – Iterable of stings to get. The default is {}.

• **kwargs (kwargs) – Keyword arguments to self.classify or self.as_modelgraph.

Returns:

result – DESCRIPTION.

Return type:

TYPE

get_resvars(to_return={}, result={})

Get variables specified in to_return.

Parameters:

• to_return (Iterable, optional) – Iterable of values to get from the object. Keys could start with “vars” or simply not be “class”, “faults”, or “graph”. The default is {}.

• result (Result, optional) – REsult to add the variables to. The default is Result().

Returns:

result – Result with variables added.

Return type:

Result

get_scen_rate(scope, faultmode, time, phasemap={}, weight=1.0, **kwargs)

Get the scenario rate for the given single-fault scenario.

Parameters:

• scope (str) – Name of the block or sub-block with the fault

• faultmode (str) – Name of the fault mode

• time (int) – Time when the scenario is to occur

• 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 {}.

• weight (int, optional) – Scenario weight (e.g., if more than one scenario is sampled for the fault). The default is 1.

• **kwargs (kwargs) – Non-default keyword arguments for Fault/Mode.

Returns:

rate – Rate of the scenario

Return type:

float

get_sims()

Return dict of simulable objects within the object.

h

immutable_roles = ['p', 'sp']

inc_sim_time(**kwargs)

Update the simulation time t_ind at the end of the timestep.

indicators

init_hist(h={})

Initialize the history of the sim using SimParam parameters and track.

init_time_hist()

Add time history to the model (only done at top level).

inject_faults(faults=[])

Inject faults into the block and its contained architectures.

Parameters:

faults (str/list/dict, optional) – Faults to inject. The default is [].

is_dynamic()

Check if Block has dynamic execution step.

is_static()

Check if Block has static execution step.

mut_kwargs

mutables

name

new(**kwargs)

Create a new Model with the same parameters as the current model.

Can initiate with with changes to mutable parameters (p, sp, track, rand etc.).

new_params(name='', p={}, sp={}, r={}, track={}, **kwargs)

Create a copy of the defining immutable parameters for use in a new Simulable.

Parameters:

• p (dict) – Parameter args to update

• sp (dict) – SimParam args to update

• r (dict) – Rand args to update

• track (dict) – track kwargs to update.

Returns:

param_dict – Dict with immutable parameters/options. (e.g., ‘p’, ‘sp’, ‘track’)

Return type:

dict

p

r

return_faultmodes()

Return all faults as a single dictionary.

return_probdens()

Get the probability density associated with Block and things it contains.

root

set_fault_disturbances(*faults)

Set Mode-based disturbances (if present).

set_sub_faults()

Set the mode to have sub_faults if contained objs have faults.

set_time()

Set time from SimParam.

sp

t

track

update_arch_behaviors(proptype)

Propagate behaviors into contained architectures.

Iterates through the Block’s contained architectures and calls the corresponding propagation type.

Parameters:

• time (float) – Time to update the architecture behaviors at.

• proptype (str) – Propagation step to perform (‘dynamic’ or ‘static’).

update_dynamic_behaviors(proptype='dynamic')

Run the dynamic behaviors of the block, including loadings (if specified).

Runs in the defined order:

1.) running dynamic_loading_before() (if sp.with_loadings is set to True) 2.) updating contained architecture dynamic behaviors/propagation 3.) running dynamic_behavior()) 4.) running dynamic_loading_after (if sp.with_loadings is set to True)

Parameters:

proptype (str) – Propagation the system is in. Skips if proptype=”static.” Default is “dynamic”

update_seed(seed=[])

Update seed and propogates update to contained actions/components.

(keeps seeds in sync)

Parameters:

seed (int, optional) – Random seed. The default is [].

update_static_behaviors(proptype='static')

Run the static behaviors of the block, including loadings (if specified).

Runs in the defined order:

1.) updating contained architecture static behaviors/propagation 2.) running static_behavior()) 3.) running static_loading (if sp.with_loadings is set to True)

Parameters:

• time (float) – Time to update the static behavior at.

• proptype (str) – Propagation the system is in. Skips if proptype=”dynamic.” If “static-once”, static behaviors are only executed once. This option is used when executing in architectures. Default is “static”

update_stochastic_states()

Update stochastic states if in run_stochastic configuration.

fmdtools.define.block.action

Defines Action class for representing discrete actions.

class fmdtools.define.block.action.Action(name=None, duration=0.0, out_delay=0.0, **kwargs)

Bases: Block

Superclass for actions.

Actions are blocks which have behaviors and live in an ActionArchitecture.

Examples

>>> exa = ExampleAction()
>>> exa
exampleaction ExampleAction
- t=ActionTime(time=-0.1, timers={})
- exf=ExampleFlow(s=(x=np.float64(1.0), y=np.float64(1.0)))
>>> exa(1.0)
>>> exa
exampleaction ExampleAction
- t=ActionTime(time=1.0, timers={})
- exf=ExampleFlow(s=(x=np.float64(2.0), y=np.float64(1.0)))
>>> exa.indicate_done()
True

base_type()

Return fmdtools type of the model class.

container_t

alias of ActionTime

containers = ('t', 'sp')

flows = ()

h

inc_sim_time(time=None, **kwargs)

Increment the simulation time (update from external time).

indicators

m

mut_kwargs

mutables

name

p

r

root

s

sp

t

track

update_dynamic_behaviors(proptype='dynamic')

Update the behavior of the Action provided the action is not complete.

class fmdtools.define.block.action.ActionTime(*args, **kwargs)

Bases: Time

Time class with extra attributes for Actions.

out_delay

Time after which the duration is complete before moving to the next action(s)

Type:

float

duration

Duration of the Action.

Type:

float

t_loc

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

Type:

float

complete()

Return True if the duration and delay are over.

dt: float

duration: float

duration_complete()

Return True if the local time is over the given duration.

executed_dynamic: bool

executed_static: bool

executing: bool

out_delay: float

reset()

Reset the time.

return_mutables()

Return mutable attributes.

t_ind: int

t_loc: float

time: float

timers: dict

use_local: bool

class fmdtools.define.block.action.ExampleAction(name=None, duration=0.0, out_delay=0.0, **kwargs)

Bases: Action

Example action for use in testing/docs.

container_p

alias of ExampleParameter

containers = ('t', 'sp', 'p')

dynamic_behavior()

Increase x when executed.

e

exf

f

flow_exf

alias of ExampleFlow

flows = ('exf',)

h

indicate_done()

When it reaches the threshold, it enters ‘done’ status.

indicators

m

mut_kwargs

mutables

name

p

r

root

s

sp

t

track

x

fmdtools.define.block.component

Defines Component class for representing system components.

class fmdtools.define.block.component.Component(name='', flows={}, h={}, **kwargs)

Bases: Block

Superclass for components (most attributes inherited from Block superclass).

Components may be called from external Component Architectures or on their own.

Typically, components are meant to represent physical realizations of systems that maybe multifunctional.

Examples

>>> c = ExampleComponent()
>>> c
examplecomponent ExampleComponent
- t=Time(time=-0.1, timers={})
- s=ExampleState(x=np.float64(0.0), y=np.float64(0.0))
>>> c()
>>> c
examplecomponent ExampleComponent
- t=Time(time=1.0, timers={})
- s=ExampleState(x=np.float64(2.0), y=np.float64(1.0))
>>> c()
>>> c
examplecomponent ExampleComponent
- t=Time(time=2.0, timers={})
- s=ExampleState(x=np.float64(2.0), y=np.float64(2.0))

Calling a particular propagation step individually only runs the given behavior method (in this case, dynamic and not static).

>>> c(proptype="dynamic")
>>> c
examplecomponent ExampleComponent
- t=Time(time=3.0, timers={})
- s=ExampleState(x=np.float64(2.0), y=np.float64(3.0))

Note that we can also simulate to a given time, which should give the same results. >>> c2 = ExampleComponent() >>> c2(time=2.0) >>> c2 examplecomponent ExampleComponent - t=Time(time=2.0, timers={}) - s=ExampleState(x=np.float64(2.0), y=np.float64(2.0))

base_type()

Return fmdtools type of the model class.

containers = ('t', 'sp')

flows = ()

h

indicators

m

mut_kwargs

mutables

name

p

r

root

s

sp

t

track

class fmdtools.define.block.component.ExampleComponent(name='', flows={}, h={}, **kwargs)

Bases: Component

Example component used for testing.

The desired behavior is for x and y to start at 0, for y to increase at the second timestep, causing x to leapfrog it (since it increments by 2).

container_s

alias of ExampleState

containers = ('t', 'sp', 's')

default_s = {'x': 0.0, 'y': 0.0}

dynamic_behavior()

Increment y.

flows = ()

h

indicators

m

mut_kwargs

mutables

name

p

r

root

s

sp

static_behavior()

Increment x if y is higher.

t

track

fmdtools.define.block.function

Defines Function class for representing system functional behaviors.

Has classes:

• Function: Class for defining model Functions.

• GenericFxn: Function class to use as a placeholder.

Functions are used to represent overall system functionality and behaviors (i.e., what a system does).

Functions are defined by extending the Function class, which may then be instantiated, as shown below:

Example of a Function class and its corresponding instantiation.

To define a function class, it can be helpful to use this code template:

Code template for Function used to define high-level system functions and their behavior.

class fmdtools.define.block.function.Function(name=None, args_f={}, **kwargs)

Bases: Block

Superclass for representing system functions.

Functions are distinguished from other blocks in their ability to contain architectures, which may be used to hold multiple components or an action sequence graph within the function.

Additional role types

archArchitecture

component, action, function architectures at ca, aa, fa, etc.

Examples

>>> exf = ExampleFunction("exf")
>>> exf
exf ExampleFunction
- t=Time(time=-0.1, timers={})
- s=ExampleState(x=np.float64(0.0), y=np.float64(0.0))
- m=ExampleMode(mode='standby', faults=set(), sub_faults=False)
- exf=ExampleFlow(s=(x=np.float64(1.0), y=np.float64(1.0)))

Behavior can be called using __call__ or the user-defined behavior method:

>>> exf(time=1.0, proptype="dynamic")
>>> exf
exf ExampleFunction
- t=Time(time=1.0, timers={})
- s=ExampleState(x=np.float64(1.0), y=np.float64(0.0))
- m=ExampleMode(mode='standby', faults=set(), sub_faults=False)
- exf=ExampleFlow(s=(x=np.float64(2.0), y=np.float64(1.0)))

Which can also be used to inject faults:

>>> exf(time=2.0, proptype="dynamic", faults=['no_charge'])
>>> exf
exf ExampleFunction
- t=Time(time=2.0, timers={})
- s=ExampleState(x=np.float64(1.0), y=np.float64(3.0))
- m=ExampleMode(mode='no_charge', faults={'no_charge'}, sub_faults=False)
- exf=ExampleFlow(s=(x=np.float64(3.0), y=np.float64(1.0)))

aa

archs = ()

args_f

base_type()

Return fmdtools type of the model class.

ca

containers = ('t', 'sp')

default_track = ['ca', 'aa', 'fa', 's', 'm', 'r', 't', 'i']

fa

flows = ()

h

indicators

m

mut_kwargs

mutables

name

p

r

roletypes = ['container', 'flow', 'arch']

root

s

sp

t

track