pyCBD.state_events.locators module

This module contains the standard State Event locators.

class pyCBD.state_events.locators.PreCrossingStateEventLocator[source]

Bases: pyCBD.state_events.locators.StateEventLocator

Assumes that the crossing happens at the start of the interval. Can be used if a precise detection is not a requirement.

This implementation computes a rough under-estimate.

algorithm(p1, p2, output_name, level=0.0, direction=Direction.ANY)[source]

The algorithm that identifies the locator functionality. Must be implemented in sub-classes. Should only ever be called if a crossing exists.

Parameters

  • p1 (tuple) – The (time, value) coordinate before the crossing, shifted towards zero.

  • p2 (tuple) – The (time, value) coordinate after the crossing, shifted towards zero.

  • output_name – The output port name for which the crossing point must be computed, if a CBD is given. Otherwise, a single-argument callable :math`f(t)` is accepted as well.

  • level (float) – The level through which the crossing must be identified. Defaults to 0.

  • direction (Direction) – The direction of the crossing to detect. This value ensures a valid crossing is identified if there are multiple between p1 and p2. Will only provide an acceptable result if the direction of the crossing can be identified. For instance, if there is a crossing from below, according to the detect() function, the algorithm will usually not accurately identify any crossings from above. Defaults to Direction.ANY.

Returns

A suspected time of the crossing.

class pyCBD.state_events.locators.PostCrossingStateEventLocator[source]

Bases: pyCBD.state_events.locators.StateEventLocator

Assumes that the crossing happens at the end of the interval. Can be used if a precise detection is not a requirement.

This implementation computes a rough over-estimate.

Corresponds to the if statement in Modelica, whereas the other locators can be seen as the when statement.

algorithm(p1, p2, output_name, level=0.0, direction=Direction.ANY)[source]

The algorithm that identifies the locator functionality. Must be implemented in sub-classes. Should only ever be called if a crossing exists.

Parameters

  • p1 (tuple) – The (time, value) coordinate before the crossing, shifted towards zero.

  • p2 (tuple) – The (time, value) coordinate after the crossing, shifted towards zero.

  • output_name – The output port name for which the crossing point must be computed, if a CBD is given. Otherwise, a single-argument callable :math`f(t)` is accepted as well.

  • level (float) – The level through which the crossing must be identified. Defaults to 0.

  • direction (Direction) – The direction of the crossing to detect. This value ensures a valid crossing is identified if there are multiple between p1 and p2. Will only provide an acceptable result if the direction of the crossing can be identified. For instance, if there is a crossing from below, according to the detect() function, the algorithm will usually not accurately identify any crossings from above. Defaults to Direction.ANY.

Returns

A suspected time of the crossing.

class pyCBD.state_events.locators.LinearStateEventLocator[source]

Bases: pyCBD.state_events.locators.StateEventLocator

Uses simple linear interpolation to compute the time of the crossing. This is usually a rough, yet centered estimate.

This locator should only be used if it is known that the signal is (mostly) linear between the lower and upper bounds.

algorithm(p1, p2, output_name, level=0.0, direction=Direction.ANY)[source]

The algorithm that identifies the locator functionality. Must be implemented in sub-classes. Should only ever be called if a crossing exists.

Parameters

  • p1 (tuple) – The (time, value) coordinate before the crossing, shifted towards zero.

  • p2 (tuple) – The (time, value) coordinate after the crossing, shifted towards zero.

  • output_name – The output port name for which the crossing point must be computed, if a CBD is given. Otherwise, a single-argument callable :math`f(t)` is accepted as well.

  • level (float) – The level through which the crossing must be identified. Defaults to 0.

  • direction (Direction) – The direction of the crossing to detect. This value ensures a valid crossing is identified if there are multiple between p1 and p2. Will only provide an acceptable result if the direction of the crossing can be identified. For instance, if there is a crossing from below, according to the detect() function, the algorithm will usually not accurately identify any crossings from above. Defaults to Direction.ANY.

Returns

A suspected time of the crossing.

class pyCBD.state_events.locators.BisectionStateEventLocator(n=10)[source]

Bases: pyCBD.state_events.locators.StateEventLocator

Uses the bisection method to compute the crossing. This method is more accurate than a linear algorithm LinearStateEventLocator, but less accurate than regula falsi (RegulaFalsiStateEventLocator).

Parameters

n (int) – The maximal amount of iterations to compute. Roughly very 3 iterations, a decimal place of accuracy is gained. Defaults to 10.

algorithm(p1, p2, output_name, level=0.0, direction=Direction.ANY)[source]

The algorithm that identifies the locator functionality. Must be implemented in sub-classes. Should only ever be called if a crossing exists.

Parameters

  • p1 (tuple) – The (time, value) coordinate before the crossing, shifted towards zero.

  • p2 (tuple) – The (time, value) coordinate after the crossing, shifted towards zero.

  • output_name – The output port name for which the crossing point must be computed, if a CBD is given. Otherwise, a single-argument callable :math`f(t)` is accepted as well.

  • level (float) – The level through which the crossing must be identified. Defaults to 0.

  • direction (Direction) – The direction of the crossing to detect. This value ensures a valid crossing is identified if there are multiple between p1 and p2. Will only provide an acceptable result if the direction of the crossing can be identified. For instance, if there is a crossing from below, according to the detect() function, the algorithm will usually not accurately identify any crossings from above. Defaults to Direction.ANY.

Returns

A suspected time of the crossing.

class pyCBD.state_events.locators.RegulaFalsiStateEventLocator(eps=1e-05, n=5000000)[source]

Bases: pyCBD.state_events.locators.StateEventLocator

Implements the Illinois algorithm for finding the root for a crossing problem.

Parameters

  • eps (float) – Half of the upper bound for the relative error. Defaults to 1e-5.

  • n (int) – The maximal amount of iterations to compute. Defaults to 5 million iterations.

See also

https://en.wikipedia.org/wiki/Regula_falsi

algorithm(p1, p2, output_name, level=0.0, direction=Direction.ANY)[source]

The algorithm that identifies the locator functionality. Must be implemented in sub-classes. Should only ever be called if a crossing exists.

Parameters

  • p1 (tuple) – The (time, value) coordinate before the crossing, shifted towards zero.

  • p2 (tuple) – The (time, value) coordinate after the crossing, shifted towards zero.

  • output_name – The output port name for which the crossing point must be computed, if a CBD is given. Otherwise, a single-argument callable :math`f(t)` is accepted as well.

  • level (float) – The level through which the crossing must be identified. Defaults to 0.

  • direction (Direction) – The direction of the crossing to detect. This value ensures a valid crossing is identified if there are multiple between p1 and p2. Will only provide an acceptable result if the direction of the crossing can be identified. For instance, if there is a crossing from below, according to the detect() function, the algorithm will usually not accurately identify any crossings from above. Defaults to Direction.ANY.

Returns

A suspected time of the crossing.

class pyCBD.state_events.locators.ITPStateEventLocator(eps=1e-05, k1=0.1, k2=1.5, n0=0)[source]

Bases: pyCBD.state_events.locators.StateEventLocator

Implements the Interpolation-Truncation-Projection algorithm for finding the root of a function.

Parameters

  • eps (float) – Minimal interval size. Defaults to 1e-5.

  • k1 (float) – First truncation size hyperparameter. Must be in the range of \((0, \infty)\). Defaults to 0.1.

  • k2 (float) – Second truncation size hyperparameter. Must be in the range of \([1, 1 + \frac{1}{2}(1 + \sqrt{5})]\). Defaults to 1.5.

  • n0 (float) – Slack variable to control the size of the interval for the projection step. Must be in \([0, \infty)\). When 0, the average number of iterations will be less than that of the bisection method. Defaults to 0.

See also

https://en.wikipedia.org/wiki/ITP_method

algorithm(p1, p2, output_name, level=0.0, direction=Direction.ANY)[source]

The algorithm that identifies the locator functionality. Must be implemented in sub-classes. Should only ever be called if a crossing exists.

Parameters

  • p1 (tuple) – The (time, value) coordinate before the crossing, shifted towards zero.

  • p2 (tuple) – The (time, value) coordinate after the crossing, shifted towards zero.

  • output_name – The output port name for which the crossing point must be computed, if a CBD is given. Otherwise, a single-argument callable :math`f(t)` is accepted as well.

  • level (float) – The level through which the crossing must be identified. Defaults to 0.

  • direction (Direction) – The direction of the crossing to detect. This value ensures a valid crossing is identified if there are multiple between p1 and p2. Will only provide an acceptable result if the direction of the crossing can be identified. For instance, if there is a crossing from below, according to the detect() function, the algorithm will usually not accurately identify any crossings from above. Defaults to Direction.ANY.

Returns

A suspected time of the crossing.