General¶

class ConstantFunction(constant, **kwargs)¶

Bases: Function

A Function that returns a constant value.

This function can be differentiated without limits.

Parameters:: constant (number) – value to return
Keyword Arguments:: **kwargs – All other kwargs get passed to Function.

derive(order=1)¶

Spatially derive this Function.

This is done by neglecting order derivative handles and to select handle $\text{order} - 1$ as the new evaluation_handle.

Parameters:

order (int) – the amount of derivations to perform

Raises:

TypeError – If order is not of type int.
ValueError – If the requested derivative order is higher than the provided one.

Returns:

Function the derived function.

class FieldVariable(function_label, order=(0, 0), weight_label=None, location=None, exponent=1, raised_spatially=False)¶

Bases: Placeholder

Class that represents terms of the systems field variable $x(z, t)$ .

Parameters:

function_label (str) – Label of shapefunctions to use for approximation, see register_base() for more information about how to register an approximation basis.
int (order tuple of) – Tuple of temporal_order and spatial_order derivation order.
weight_label (str) – Label of weights for which coefficients are to be calculated (defaults to function_label).
location – Where the expression is to be evaluated.
exponent – Exponent of the term.

Examples

Assuming some shapefunctions have been registered under the label "phi" the following expressions hold:

$\frac{\partial^{3}}{\partial t \partial z^2}x(z, t)$

>>> x_dt_dzz = FieldVariable("phi", order=(1, 2))

$\frac{\partial^2}{\partial t^2}x(3, t)$

>>> x_dtt_at_3 = FieldVariable("phi", order=(2, 0), location=3)

derive(*, temp_order=0, spat_order=0)¶

Derive the expression to the specified order.

Parameters:

temp_order – Temporal derivative order.
spat_order – Spatial derivative order.

Returns:

The derived expression.

Return type:

Placeholder

Note

This method uses keyword only arguments, which means that a call will fail if the arguments are passed by order.

class Function(eval_handle, domain=(-np.inf, np.inf), nonzero=(-np.inf, np.inf), derivative_handles=None)¶

Bases: BaseFraction

Most common instance of a BaseFraction. This class handles all tasks concerning derivation and evaluation of functions. It is used broad across the toolbox and therefore incorporates some very specific attributes. For example, to ensure the accurateness of numerical handling functions may only evaluated in areas where they provide nonzero return values. Also their domain has to be taken into account. Therefore the attributes domain and nonzero are provided.

To save implementation time, ready to go version like LagrangeFirstOrder are provided in the pyinduct.simulation module.

For the implementation of new shape functions subclass this implementation or directly provide a callable eval_handle and callable derivative_handles if spatial derivatives are required for the application.

Parameters:

eval_handle (derivatives of) – Callable object that can be evaluated.
domain (nonzero output. Must be a subset of) – Domain on which the eval_handle is defined.
nonzero (tuple) – Region in which the eval_handle will return
domain –
derivative_handles (list) – List of callable(s) that contain
eval_handle –

add_neutral_element()¶

Return the neutral element of addition for this object.

In other words: self + ret_val == self.

property derivative_handles¶

derive(order=1)¶

Spatially derive this Function.

This is done by neglecting order derivative handles and to select handle $\text{order} - 1$ as the new evaluation_handle.

Parameters:

order (int) – the amount of derivations to perform

Raises:

TypeError – If order is not of type int.
ValueError – If the requested derivative order is higher than the provided one.

Returns:

Function the derived function.

static from_data(x, y, **kwargs)¶

Create a Function based on discrete data by interpolating.

The interpolation is done by using interp1d from scipy, the kwargs will be passed.

Parameters:

x (array-like) – Places where the function has been evaluated .
y (array-like) – Function values at x.
**kwargs – all kwargs get passed to Function .

Returns:

An interpolating function.

Return type:

Function

property function_handle¶

function_space_hint()¶: Return the hint that this function is an element of the an scalar product space which is uniquely defined by the scalar product scalar_product_hint().

Note

If you are working on different function spaces, you have to overwrite this hint in order to provide more properties which characterize your specific function space. For example the domain of the functions.

get_member(idx)¶

Implementation of the abstract parent method.

Since the Function has only one member (itself) the parameter idx is ignored and self is returned.

Parameters:: idx – ignored.
Returns:: self

mul_neutral_element()¶

Return the neutral element of multiplication for this object.

In other words: self * ret_val == self.

raise_to(power)¶

Raises the function to the given power.

Warning

Derivatives are lost after this action is performed.

Parameters:: power (numbers.Number) – power to raise the function to
Returns:: raised function

scalar_product_hint()¶: Return the hint that the _dot_product_l2() has to calculated to gain the scalar product.

scale(factor)¶

Factory method to scale a Function.

Parameters:: factor – numbers.Number or a callable.

class Input(function_handle, index=0, order=0, exponent=1)¶

Bases: Placeholder

Class that works as a placeholder for an input of the system.

Parameters:

function_handle (callable) – Handle that will be called by the simulation unit.
index (int) – If the system’s input is vectorial, specify the element to be used.
order (int) – temporal derivative order of this term (See Placeholder).
exponent (numbers.Number) – See FieldVariable.

Note

if order is nonzero, the callable is expected to return the temporal derivatives of the input signal by returning an array of len(order)+1.

class IntegralTerm(integrand, limits, scale=1.0)¶

Bases: EquationTerm

Class that represents an integral term in a weak equation.

Parameters:

integrand –
limits (tuple) –
scale –

class Product(a, b=None)¶

Bases: object

Represents a product.

Parameters:

a –
b –

get_arg_by_class(cls)¶

Extract element from product that is an instance of cls.

Parameters:: cls –
Return type:: list

class ScalarFunction(function_label, order=0, location=None)¶

Bases: SpatialPlaceholder

Class that works as a placeholder for spatial functions in an equation. An example could be spatial dependent coefficients.

Parameters:

function_label (str) – label under which the function is registered
order (int) – spatial derivative order to use
location – location to evaluate at

Warns:

There seems to be a problem when this function is used in combination
with the :py:class:`.Product` class. Make sure to provide this class as
first argument to any product you define.

Todo

see warning.

static from_scalar(scalar, label, **kwargs)¶

create a ScalarFunction from scalar values.

Parameters:

scalar (array like) – Input that is used to generate the placeholder. If a number is given, a constant function will be created, if it is callable it will be wrapped in a Function and registered.
label (string) – Label to register the created base.
**kwargs – All kwargs that are not mentioned below will be passed to Function.

Keyword Arguments:

order (int) – See constructor.
location (int) – See constructor.
overwrite (bool) – See register_base()

Returns:

Placeholder object that can be used in a weak formulation.

Return type:

ScalarFunction

class ScalarTerm(argument, scale=1.0)¶

Bases: EquationTerm

Class that represents a scalar term in a weak equation.

Parameters:

argument –
scale –

class SecondOrderOperator(a2=0, a1=0, a0=0, alpha1=0, alpha0=0, beta1=0, beta0=0, domain=(-np.inf, np.inf))¶

Interface class to collect all important parameters that describe a second order ordinary differential equation.

Parameters:

a2 (Number or callable) – coefficient $a_2$ .
a1 (Number or callable) – coefficient $a_1$ .
a0 (Number or callable) – coefficient $a_0$ .
alpha1 (Number) – coefficient $\alpha_1$ .
alpha0 (Number) – coefficient $\alpha_0$ .
beta1 (Number) – coefficient $\beta_1$ .
beta0 (Number) – coefficient $\beta_0$ .

static from_dict(param_dict, domain=None)¶

static from_list(param_list, domain=None)¶

get_adjoint_problem()¶

Return the parameters of the operator $A^*$ describing the the problem

$(\textup{A}^*\psi)(z) = \bar a_2 \partial_z^2 \psi(z) + \bar a_1 \partial_z \psi(z) + \bar a_0 \psi(z) \:,$

where the $\bar a_i$ are constant and whose boundary conditions are given by

$\bar\alpha_1 \partial_z \psi(z_1) + \bar\alpha_0 \psi(z_1) &= 0 \\ \bar\beta_1 \partial_z \psi(z_2) + \bar\beta_0 \psi(z_2) &= 0 .$

The following mapping is used:

$\bar a_2 = a_2, \quad\bar a_1 = -a_1, \quad\bar a_0 = a_0, \\ \bar\alpha_1 = -1, \quad \bar\alpha_0 = \frac{a_1}{a_2} - \frac{\alpha_0}{\alpha_1} , \\ \bar\beta_1 = -1, \quad \bar\beta_0 = \frac{a_1}{a_2} - \frac{\beta_0}{\beta_1} \:.$

Returns:: Parameter set describing $A^*$ .
Return type:: SecondOrderOperator

class TestFunction(function_label, order=0, location=None, approx_label=None)¶

Bases: SpatialPlaceholder

Class that works as a placeholder for test functions in an equation.

Parameters:

function_label (str) – Label of the function test base.
order (int) – Spatial derivative order.
location (Number) – Point of evaluation / argument of the function.
approx_label (str) – Label of the approximation test base.

class WeakFormulation(terms, name, dominant_lbl=None)¶

Bases: object

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

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

Parameters:

terms (list) – List of object(s) of type EquationTerm.
name (string) – Name of this weak form.
dominant_lbl (string) – Name of the variable that dominates this weak form.

compute_rad_robin_eigenfrequencies(param, l, n_roots=10, show_plot=False)¶

Return the first n_roots eigenfrequencies $\omega$ (and eigenvalues $\lambda$ )

$\omega = \sqrt{-\frac{a_1^2}{4a_2^2}+\frac{a_0-\lambda}{a_2}}$

to the eigenvalue problem

$a_2\varphi''(z) + a_1&\varphi'(z) + a_0\varphi(z) = \lambda\varphi(z) \\ \varphi'(0) &= \alpha\varphi(0) \\ \varphi'(l) &= -\beta\varphi(l).$

Parameters:

param (array_like) – $\Big( a_2, a_1, a_0, \alpha, \beta \Big)^T$
l (numbers.Number) – Right boundary value of the domain $[0,l]\ni z$ .
n_roots (int) – Amount of eigenfrequencies to be compute.
show_plot (bool) – A plot window of the characteristic equation appears if it is True.

Returns:

$\Big(\big[\omega_1,...,\omega_\text{n\_roots}\Big], \Big[\lambda_1,...,\lambda_\text{n\_roots}\big]\Big)$

Return type:

tuple –> two numpy.ndarrays of length nroots

eliminate_advection_term(param, domain_end)¶

This method performs a transformation

$\tilde x(z,t)=x(z,t) e^{\int_0^z \frac{a_1(\bar z)}{2 a_2}\,d\bar z} ,$

on the system, which eliminates the advection term $a_1 x(z,t)$ from a reaction-advection-diffusion equation of the type:

$\dot x(z,t) = a_2 x''(z,t) + a_1(z) x'(z,t) + a_0(z) x(z,t) .$

The boundary can be given by robin

$x'(0,t) = \alpha x(0,t), \quad x'(l,t) = -\beta x(l,t) ,$

dirichlet

$x(0,t) = 0, \quad x(l,t) = 0$

or mixed boundary conditions.

Parameters:

param (array_like) – $\Big( a_2, a_1, a_0, \alpha, \beta \Big)^T$
domain_end (float) – upper bound of the spatial domain

Raises:

TypeError – If $a_1(z)$ is callable but no derivative handle is
defined for it. –

Returns:

Parameters

$\big(a_2, \tilde a_1=0, \tilde a_0(z), \tilde \alpha, \tilde \beta \big) for$

the transformed system

$\dot{\tilde{x}}(z,t) = a_2 \tilde x''(z,t) + \tilde a_0(z) \tilde x(z,t)$

and the corresponding boundary conditions ( $\alpha$ and/or $\beta$ set to None by dirichlet boundary condition).

Return type:

SecondOrderOperator or tuple

find_roots(function, grid, n_roots=None, rtol=1e-05, atol=1e-08, cmplx=False, sort_mode='norm')¶

Searches n_roots roots of the function $f(\boldsymbol{x})$ on the given grid and checks them for uniqueness with aid of rtol.

In Detail scipy.optimize.root() is used to find initial candidates for roots of $f(\boldsymbol{x})$ . If a root satisfies the criteria given by atol and rtol it is added. If it is already in the list, a comprehension between the already present entries’ error and the current error is performed. If the newly calculated root comes with a smaller error it supersedes the present entry.

Raises:

ValueError – If the demanded amount of roots can’t be found.

Parameters:

function (callable) – Function handle for math:f(boldsymbol{x}) whose roots shall be found.
grid (list) – Grid to use as starting point for root detection. The $i$ th element of this list provides sample points for the $i$ th parameter of $\boldsymbol{x}$ .
n_roots (int) – Number of roots to find. If none is given, return all roots that could be found in the given area.
rtol – Tolerance to be exceeded for the difference of two roots to be unique: $f(r1) - f(r2) > \textrm{rtol}$ .
atol – Absolute tolerance to zero: $f(x^0) < \textrm{atol}$ .
cmplx (bool) – Set to True if the given function is complex valued.
sort_mode (str) – Specify tho order in which the extracted roots shall be sorted. Default “norm” sorts entries by their $l_2$ norm, while “component” will sort them in increasing order by every component.

Returns:

numpy.ndarray of roots; sorted in the order they are returned by $f(\boldsymbol{x})$ .

get_in_domain_transformation_matrix(k1, k2, mode='n_plus_1')¶

Returns the transformation matrix M.

M is one part of a transformation

$x = My + Ty$

where x is the field variable of an interior point controlled parabolic system and y is the field variable of an boundary controlled parabolic system. T is a (Fredholm-) integral transformation (which can be approximated with M).

Parameters:

k1 –
k2 –
mode –
Available modes
- n_plus_1: M.shape = $(n+1,n+1), w = (w(0),...,w(n))^T, w \in {x,y}$
- 2n: M.shape = (2n,2n), $w = (w(0),...,w(n),...,w(1))^T, w \in {x,y}$

Returns:

Transformation matrix M.

Return type:

numpy.array

get_parabolic_dirichlet_weak_form(init_func_label, test_func_label, input_handle, param, spatial_domain)¶

Return the weak formulation of a parabolic 2nd order system, using an inhomogeneous dirichlet boundary at both sides.

Parameters:

init_func_label (str) – Label of shape base to use.
test_func_label (str) – Label of test base to use.
input_handle (SimulationInput) – Input.
param (tuple) – Parameters of the spatial operator.
spatial_domain (#) – Spatial domain of the problem.
spatial_domain – Spatial domain of the
problem. (#) –

Returns:

Weak form of the system.

Return type:

WeakFormulation

get_parabolic_robin_weak_form(shape_base_label, test_base_label, input_handle, param, spatial_domain, actuation_type_point=None)¶

Provide the weak formulation for the diffusion system with advection term, reaction term, robin boundary condition and robin actuation.

$\begin{align*} \dot x(z,t) &= a_2 x''(z,t) + a_1(z) x'(z,t) + a_0(z) x(z,t), && z\in (0, l) \\ x'(0,t) &= \alpha x(0,t) \\ x'(l,t) &= -\beta x(l,t) + u(t) \end{align*}$

Parameters:

shape_base_label (str) – State space base label
test_base_label (str) – Test base label
input_handle (SimulationInput) – System input
param (array-like) –
List of parameters:
- $a_2$ (numbers.Number) ~ diffusion coefficient
- $a_1(z)$ (callable) ~ advection coefficient
- $a_0(z)$ (callable) ~ reaction coefficient
- $\alpha, \beta$ (numbers.Number) ~ constants for robin boundary conditions
spatial_domain (tuple) – Limits of the spatial domain $(0,l) \ni z$
actuation_type_point (numbers.number) – Here you can shift the point of actuation from $z=l$ to a other point in the spatial domain.

Returns:

WeakFormulation
strings for the created base lables for the advection and reaction coefficient

Return type:

tuple

General¶

PyInduct

Navigation

Related Topics