Simulation¶

This module consist of three parts.

Simulation:

Simulation infrastructure with helpers and data structures for preprocessing of the given equations and functions for postprocessing of simulation data.

Control:

All classes and functions related to the creation of controllers as well as the implementation for simulation purposes.

Observer:

Some objects for observer implementation which are mostly a combination from the objects for simulation and control tasks.

Simulation¶

class Domain(bounds=None, num=None, step=None, points=None)[source]¶

Bases: object

Helper class that manages ranges for data evaluation, containing parameters.

Parameters:	bounds (tuple) – Interval bounds. num (int) – Number of points in interval. step (numbers.Number) – Distance between points (if homogeneous). points (array_like) – Points themselves.

Note

If num and step are given, num will take precedence.

class SimulationInput(name='')[source]¶

Bases: object

Base class for all objects that want to act as an input for the time-step simulation.

The calculated values for each time-step are stored in internal memory and can be accessed by get_results() (after the simulation is finished).

get_results(time_steps, result_key='output', interpolation='nearest', as_eval_data=False)[source]¶

Return results from internal storage for given time steps.

Raises:	`Error` – If calling this method before a simulation was running.
Parameters:	time_steps – Time points where values are demanded. result_key – Type of values to be returned. interpolation – Interpolation method to use if demanded time-steps are not covered by the storage, see `scipy.interpolate.interp1d()` for all possibilities. as_eval_data (bool) – Return results as `pyinduct.visualization.EvalData` object for straightforward display.
Returns:	Corresponding function values to the given time steps.

class SimulationInputSum(inputs)[source]¶

Bases: pyinduct.simulation.SimulationInput

Helper that represents a signal mixer.

class SimulationInputVector(input_vector)[source]¶

Bases: pyinduct.simulation.SimulationInput

Class that represent the input vector $\boldsymbol{u}\in\mathbb R^n$ from a state space system (StateSpace) like

$\boldsymbol{\dot{x}}(t) &= \boldsymbol{A}\boldsymbol{x}(t) + \boldsymbol{B}\boldsymbol{u}(t) \\ \boldsymbol{y}(t) &= \boldsymbol{C}\boldsymbol{x}(t) + \boldsymbol{D}\boldsymbol{u}(t).$

Parameters:	input_vector (list) – List which holds (in sum) $n$ `SimulationInput` and/or `ObserverError` instances.

class WeakFormulation(terms, dynamic_weights=None, name=None)[source]¶

Bases: object

This class represents the weak formulation of a spatial problem. It can be initialized with several terms (see children of pyinduct.placeholder.EquationTerm). The equation is interpreted as

$term_0 + term_1 + ... + term_N = 0.$

Parameters:	terms (list) – List of object(s) of type EquationTerm. dynamic_weights (str) – Only for multi-pde systems. Weights (weight label) which occur temporal derived. It is only one kind of weight labels (one pde) allowed in the weak formulation if `dynamic_weights` will not provided.

class CanonicalForm(name=None)[source]¶

Bases: object

The canonical form of an ordinary differential equation system of order n.

add_to(term, value, column=None)[source]¶

Adds the value value to term term. term is a dict that describes which coefficient matrix of the canonical form the value shall be added to.

Parameters:

term (dict) –
Targeted term in the canonical form h. It has to contain:
- name: Type of the coefficient matrix: ‘E’, ‘f’, or ‘G’.
- order: Temporal derivative order of the assigned weights.
- exponent: Exponent of the assigned weights.
value (numpy.ndarray) – Value to add. It is converted in numpy.matrix if it is not already a numpy.matrix instance.
column (int) – Add the value only to one column of term (useful if only one dimension of term is known).

convert_to_state_space()[source]¶

Convert the canonical ode system of order n a into an ode system of order 1. This will only work if the highest derivative of the given FieldVariable can be isolated!

Returns:
Return type:	`StateSpace` object

get_terms()[source]¶

Return all coefficient matrices of the canonical formulation.

Returns:	Structure: Type > Order > Exponent.
Return type:	Cascade of dictionaries

class CanonicalForms(dynamic_weight_label)[source]¶

Bases: object

Wrapper that holds several entities of canonical forms for different sets of weights.

add_to(weight_label, term, val, column=None)[source]¶

Add val to the canonical form for weight_label, see CanonicalForm.add_to() for further information.

Parameters:	weight_label (str) – Basis to add onto. term – Coefficient to add onto, see `CanonicalForm.add_to()`. val – Values to add.

get_dynamic_terms()[source]¶

Returns:	Terms of the dynamic `CanonicalForm`.
Return type:	dict

get_static_terms()[source]¶

Returns:	Dictionary of terms for each static `CanonicalForm`.
Return type:	dict

class StateSpace(weight_label, a_matrices, b_matrices, input_handle=None, f_vector=None, c_matrix=None, d_matrix=None, family_tree=None)[source]¶

Bases: object

Standard state space implementation for a dynamic system with

$\boldsymbol{\dot{x}}(t) &= \boldsymbol{A}\boldsymbol{x}(t) + \boldsymbol{B}u(t) \\ \boldsymbol{y}(t) &= \boldsymbol{C}\boldsymbol{x}(t) + \boldsymbol{D}u(t).$

The corresponding infinite dimensional system has been approximated by a base given by weight_label.

Parameters:

weight_label – Label that has been used for approximation.
a_matrices – $\boldsymbol{A_p}, \dotsc, \boldsymbol{A_0},$
b_matrices – $\boldsymbol{B_q}, \dotsc, \boldsymbol{B_0},$
input_handle – $u(t)$
f_vector –
c_matrix – $\boldsymbol{C}$
d_matrix – $\boldsymbol{D}$
family_tree (collections.OrderedDict or NoneType) – Ordered dictionary which hold informations about nesting of the original weights. Is None if the state space derived from only one weak formulation.

simulate_system(weak_form, initial_states, temporal_domain, spatial_domain, settings=None, der_orders=(0, 0))[source]¶

Convenience wrapper that encapsulates the whole simulation process.

Parameters:

weak_form (WeakFormulation) – Weak formulation of the system to simulate.
initial_states (callable or numpy.ndarray) – Array of core.Functions for $x(t=0, z), \dot{x}(t=0, z), \dotsc, x^{(n)}(t=0, z)$ .
temporal_domain (Domain) – Domain object holding information for time evaluation.
spatial_domain (Domain) – Domain object holding information for spatial evaluation.
der_orders (tuple) – Tuple of derivative orders (time, spat) that shall be evaluated additionally.
settings – Integrator settings, see simulate_state_space().

Returns:

List of pyinduct.visualization.EvalData objects,holding the results for the: FieldVariable and asked derivatives.

Return type:

list

simulate_systems(weak_forms, initial_states, time_interval, time_step, spatial_interval, spatial_step)[source]¶

Convenience wrapper for simulate system, see simulate_system() for parameters.

Parameters:	weak_forms (`WeakFormulation`) – initial_states – time_interval – time_step – spatial_interval – spatial_step –

process_sim_data(weight_lbl, q, temp_domain, spat_domain, temp_order, spat_order, name='')[source]¶

Create handles and evaluate at given points.

Parameters:

weight_lbl (str) – Label of Basis for reconstruction.
temp_order – Order or temporal derivatives to evaluate additionally.
spat_order – Order or spatial derivatives to evaluate additionally.
q – weights
spat_domain (Domain) – Domain object providing values for spatial evaluation.
temp_domain (Domain) – Timesteps on which rows of q are given.
name (str) – Name of the WeakForm, used to generate the dataset.

parse_weak_formulation(weak_form)[source]¶

Creates an ode system for the weights x_i based on the weak formulation.

Parameters:	weak_form (`WeakFormulation`) – Weak formulation of the pde.
Returns:	n’th-order ode system. If the desired canonical form should be from type `CanonicalForms` (as a part of multi-pde system) then the label of the dynamic weights must be defined in `weak_form.dynamic_weights` otherwise you get a `CanonicalForm` object.
Return type:	`CanonicalForm` or `CanonicalForms`

convert_cfs_to_state_space(list_of_cfs)[source]¶

Create StateSpace from list list_of_cfs with elements from type CanonicalForms. In the common case the $N$ list elements are derived from $N$ WeakFormulation`s which represent :math:`N coupled pde’s with boundary conditions.

Parameters:	list_of_cfs (list) – List with elements from type `CanonicalForms`.
Returns:	State space approximation for the time dynamic of (basically) coupled pde’s.
Return type:	`StateSpace`

simulate_state_space(sys_ss, sys_init_state, temp_domain, obs_ss=None, obs_init_state=None, settings=None)[source]¶

Wrapper to simulate a system given in state space form:

$\dot{q} = A_pq^p + A_{p-1}q^{p-1} + \dotsb + A_0q + Bu.$

Parameters:	sys_ss (`StateSpace`) – State space formulation of the system. sys_init_state (numpy.array) – Initial state vector of the system. temp_domain (`Domain`) – Temporal domain object. obs_ss (`Observer`) – State space formulation of the observer. obs_init_state (numpy.array) – Initial state vector of the observer. settings (dict) – Parameters to pass to the `set_integrator()` method of the `scipy.ode` class, with the integrator name included under the key `name`.
Returns:	Time `Domain` object and weights matrix/matrices.
Return type:	tuple

evaluate_approximation(base_label, weights, temp_domain, spat_domain, spat_order=0, name='')[source]¶

Evaluate an approximation given by weights and functions at the points given in spatial and temporal steps.

Parameters:	weights – 2d np.ndarray where axis 1 is the weight index and axis 0 the temporal index. base_label (str) – Functions to use for back-projection. temp_domain (`Domain`) – For steps to evaluate at. spat_domain (`Domain`) – For points to evaluate at (or in). spat_order – Spatial derivative order to use. name – Name to use.
Returns:	`pyinduct.visualization.EvalData`

Control¶

class FeedbackLaw(terms, name='')[source]¶

Bases: object

This class represents the approximated formulation of a control law or observer error. It can be initialized with several terms (see children of pyinduct.placeholder.EquationTerm). The equation is interpreted as

$term_0 + term_1 + ... + term_N = u$

where $u$ is the control output.

Parameters:	terms (list) – List with object(s) of type `pyinduct.placeholder.EquationTerm`.

class Feedback(feedback_law)[source]¶

Bases: pyinduct.simulation.SimulationInput

Wrapper class for all state feedbacks that have to interact with the simulation environment.

Parameters:	feedback_law (`FeedbackLaw`) – Function handle that calculates the state feedback if provided with correct weights.

class FeedbackCanonicalForms(name)[source]¶

Bases: object

Wrapper that holds several entities of canonical forms for different sets of weights.

add_to(weight_label, term, val)[source]¶

Add val to the canonical form for weight_label, see CanonicalForm.add_to() for further information.

Parameters:	weight_label (str) – Basis to add onto. term – Coefficient to add onto, see `CanonicalForm.add_to()`. val – Values to add.

get_dynamic_terms()[source]¶

Returns:	Dictionary of terms for each weight set.
Return type:	dict

get_static_terms()[source]¶

Returns:	Terms that do not depend on a certain weight set.

class LawEvaluator(cfs, storage=None)[source]¶

Bases: object

Object that evaluates the feedback law approximation given by a pyinduct.simulation.CanonicalForms object.

Parameters:	cfs (`pyinduct.simulation.FeedbackCanonicalForms`) – evaluation handle

approximate_feedback_law(feedback_law)[source]¶

Function that approximates the feedback law, given by a list of sum terms that equal u. The result is a function handle that contains pre-evaluated terms and only needs the current weights (and their respective label) to be applied.

Parameters:	feedback_law (`FeedbackLaw`) – Function handle that calculates the feedback law output if provided with correct weights.
Returns:	evaluation handle
Return type:	`pyinduct.simulation.FeedbackCanonicalForms`

_parse_feedback_law(law)[source]¶

Parses the given feedback law by approximating given terms.

Parameters:	law (list) – List of `pyinduct.placeholders.EquationTerm`‘s
Returns:	evaluation handle
Return type:	`pyinduct.simulation.FeedbackCanonicalForms`

Observer¶

class ObserverError(sys_part, obs_part, weighted_initial_error=None)[source]¶

Bases: pyinduct.simulation.SimulationInput

Wrapper class for all observer errors that have to interact with the simulation environment. The terms which have to approximated on the basis of the system weights have to provided through the argument sys_part and the terms which have to approximated on the basis of the observer weights have to provided through the argument obs_part. The observer error is provided as sum of the FeedbackLaw‘s sys_part and obs_part.

Parameters:

sys_part (FeedbackLaw) – Hold the terms which approximated from system weights.
obs_part (FeedbackLaw) – Hold the terms which approximated from observer weights.

Keyword Arguments:

weighted_initial_error (numbers.Number) –

Time $t^*$ (default: None). If the kwarg is given the observer error will be weighted $\tilde{y}_{\varphi}(t) = \varphi(t)\tilde{y}(t)$ with the function

$\begin{align*} \varphi(t) = \left\{\begin{array}{lll} 0 & \forall & t < 0 \\ (1-\cos\pi\frac{t}{t^*}) / 2 & \forall & t \in [0, 1] \\ 1 & \forall & t > 1. \end{array}\right. \end{align*}$

class Observer(weight_label, a_matrices, b_matrices, input_handle=None, f_vector=None, c_matrix=None, d_matrix=None, family_tree=None, l_matrices=None)[source]¶

Bases: pyinduct.simulation.StateSpace

Standard observer class which correspond structurally to the standard state space implementation StateSpace (from which it is derived).

$\dot{\boldsymbol{x}}(t) &= \boldsymbol{A}\boldsymbol{x}(t) + \boldsymbol{B}u(t) + \boldsymbol{L} \tilde{\boldsymbol{y}} \\ \boldsymbol{y}(t) &= \boldsymbol{C}\boldsymbol{x}(t) + \boldsymbol{D}u(t)$

Where $\tilde{\boldsymbol{y}}$ is the observer error. The corresponding infinite dimensional observer has been approximated by a base given by weight_label.

Parameters:	weight_label – Label that has been used for approximation. a_matrices – $\boldsymbol{A_p}, \dotsc, \boldsymbol{A_0},$ b_matrices – $\boldsymbol{B_q}, \dotsc, \boldsymbol{B_0},$ input_handle – $u(t)$ f_vector – c_matrix – $\boldsymbol{C}$ d_matrix – $\boldsymbol{D}$ family_tree – l_matrices –

build_observer_from_state_space(state_space)[source]¶

Return a Observer object based on the given StateSpace object. The method return None if state_space.input is not a instance of ObserverError or if self._input_function is a instance of SimulationInputSum which not hold any ObserverError instance.

Parameters:	state_space (`StateSpace`) – State space to be convert.
Returns:	See docstring.
Return type:	`pyinduct.simulation.Observer` or None