pydrake.systems.framework

Bindings for the core Systems framework.

class pydrake.systems.framework.AbstractParameterIndex

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.AbstractParameterIndex) -> None

Default constructor; the result is an invalid index. This only exists to serve applications which require a default constructor.

2. __init__(self: pydrake.systems.framework.AbstractParameterIndex, arg0: int) -> None

Construction from a non-negative int value. The value must lie in the range of [0, 2³¹). Constructor only promises to test validity in Debug build.

is_valid(self: pydrake.systems.framework.AbstractParameterIndex) → bool

Reports if the index is valid–the only operation on an invalid index that doesn’t throw an exception in Debug builds.

class pydrake.systems.framework.AbstractStateIndex

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.AbstractStateIndex) -> None

Default constructor; the result is an invalid index. This only exists to serve applications which require a default constructor.

2. __init__(self: pydrake.systems.framework.AbstractStateIndex, arg0: int) -> None

Construction from a non-negative int value. The value must lie in the range of [0, 2³¹). Constructor only promises to test validity in Debug build.

is_valid(self: pydrake.systems.framework.AbstractStateIndex) → bool

Reports if the index is valid–the only operation on an invalid index that doesn’t throw an exception in Debug builds.

class pydrake.systems.framework.AbstractValues

AbstractValues is a container for non-numerical state and parameters. It may or may not own the underlying data, and therefore is suitable for both leaf Systems and diagrams.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.AbstractValues) -> None

Constructs an empty AbstractValues.

2. __init__(self: pydrake.systems.framework.AbstractValues, arg0: list[pydrake.common.value.AbstractValue]) -> None

Constructs an AbstractValues that does not own the underlying data.

Clone(self: pydrake.systems.framework.AbstractValues) → pydrake.systems.framework.AbstractValues

get_mutable_value(self: pydrake.systems.framework.AbstractValues, index: int) → pydrake.common.value.AbstractValue

Returns the element of AbstractValues at the given index, or aborts if the index is out-of-bounds.

get_value(self: pydrake.systems.framework.AbstractValues, index: int) → pydrake.common.value.AbstractValue

Returns the element of AbstractValues at the given index, or aborts if the index is out-of-bounds.

SetFrom(self: pydrake.systems.framework.AbstractValues, arg0: pydrake.systems.framework.AbstractValues) → None

Copies all of the AbstractValues in other into this. Asserts if the two are not equal in size.

Raises

RuntimeError if any of the elements are of incompatible type. –

size(self: pydrake.systems.framework.AbstractValues) → int

Returns the number of elements of AbstractValues.

class pydrake.systems.framework.BasicVector

Bases: pydrake.systems.framework.VectorBase

BasicVector is a semantics-free wrapper around an Eigen vector that satisfies VectorBase. Once constructed, its size is fixed.

Note

This class is templated; see BasicVector_ for the list of instantiations.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.BasicVector, data: numpy.ndarray[numpy.float64[m, 1]]) -> None

Constructs a BasicVector with the specified vec data.

2. __init__(self: pydrake.systems.framework.BasicVector, size: int) -> None

Initializes with the given size using the drake::dummy_value<T>, which is NaN when T = double.

Clone(self: pydrake.systems.framework.BasicVector) → pydrake.systems.framework.BasicVector

get_mutable_value(self: pydrake.systems.framework.BasicVector) → numpy.ndarray[numpy.float64[m, 1], flags.writeable]

Returns the entire vector as a mutable Eigen::VectorBlock, which allows mutation of the values, but does not allow resize() to be invoked on the returned object.

get_value(self: pydrake.systems.framework.BasicVector) → numpy.ndarray[numpy.float64[m, 1]]

(Don’t use this in new code) Returns the entire vector as a const Eigen::VectorBlock. Prefer value() which returns direct access to the underlying VectorX rather than wrapping it in a VectorBlock.

set_value(self: pydrake.systems.framework.BasicVector, arg0: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets the vector to the given value. After a.set_value(b.get_value()), a must be identical to b.

Raises

RuntimeError if the new value has different dimensions. –

value(self: pydrake.systems.framework.BasicVector) → numpy.ndarray[numpy.float64[m, 1]]

Returns a const reference to the contained VectorX<T>. This is the preferred method for examining a BasicVector’s value.

template pydrake.systems.framework.BasicVector_

Instantiations: BasicVector_[float], BasicVector_[AutoDiffXd], BasicVector_[Expression]

class pydrake.systems.framework.BasicVector_[AutoDiffXd]

Bases: pydrake.systems.framework.VectorBase_[AutoDiffXd]

BasicVector is a semantics-free wrapper around an Eigen vector that satisfies VectorBase. Once constructed, its size is fixed.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.BasicVector_[AutoDiffXd], data: numpy.ndarray[object[m, 1]]) -> None

Constructs a BasicVector with the specified vec data.

2. __init__(self: pydrake.systems.framework.BasicVector_[AutoDiffXd], size: int) -> None

Initializes with the given size using the drake::dummy_value<T>, which is NaN when T = double.

Clone(self: pydrake.systems.framework.BasicVector_[AutoDiffXd]) → pydrake.systems.framework.BasicVector_[AutoDiffXd]

get_mutable_value(self: pydrake.systems.framework.BasicVector_[AutoDiffXd]) → numpy.ndarray[object[m, 1], flags.writeable]

Returns the entire vector as a mutable Eigen::VectorBlock, which allows mutation of the values, but does not allow resize() to be invoked on the returned object.

get_value(self: pydrake.systems.framework.BasicVector_[AutoDiffXd]) → numpy.ndarray[object[m, 1]]

(Don’t use this in new code) Returns the entire vector as a const Eigen::VectorBlock. Prefer value() which returns direct access to the underlying VectorX rather than wrapping it in a VectorBlock.

set_value(self: pydrake.systems.framework.BasicVector_[AutoDiffXd], arg0: numpy.ndarray[object[m, 1]]) → None

Sets the vector to the given value. After a.set_value(b.get_value()), a must be identical to b.

Raises

RuntimeError if the new value has different dimensions. –

value(self: pydrake.systems.framework.BasicVector_[AutoDiffXd]) → numpy.ndarray[object[m, 1]]

Returns a const reference to the contained VectorX<T>. This is the preferred method for examining a BasicVector’s value.

class pydrake.systems.framework.BasicVector_[Expression]

Bases: pydrake.systems.framework.VectorBase_[Expression]

BasicVector is a semantics-free wrapper around an Eigen vector that satisfies VectorBase. Once constructed, its size is fixed.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.BasicVector_[Expression], data: numpy.ndarray[object[m, 1]]) -> None

Constructs a BasicVector with the specified vec data.

2. __init__(self: pydrake.systems.framework.BasicVector_[Expression], size: int) -> None

Initializes with the given size using the drake::dummy_value<T>, which is NaN when T = double.

Clone(self: pydrake.systems.framework.BasicVector_[Expression]) → pydrake.systems.framework.BasicVector_[Expression]

get_mutable_value(self: pydrake.systems.framework.BasicVector_[Expression]) → numpy.ndarray[object[m, 1], flags.writeable]

Returns the entire vector as a mutable Eigen::VectorBlock, which allows mutation of the values, but does not allow resize() to be invoked on the returned object.

get_value(self: pydrake.systems.framework.BasicVector_[Expression]) → numpy.ndarray[object[m, 1]]

(Don’t use this in new code) Returns the entire vector as a const Eigen::VectorBlock. Prefer value() which returns direct access to the underlying VectorX rather than wrapping it in a VectorBlock.

set_value(self: pydrake.systems.framework.BasicVector_[Expression], arg0: numpy.ndarray[object[m, 1]]) → None

Sets the vector to the given value. After a.set_value(b.get_value()), a must be identical to b.

Raises

RuntimeError if the new value has different dimensions. –

value(self: pydrake.systems.framework.BasicVector_[Expression]) → numpy.ndarray[object[m, 1]]

Returns a const reference to the contained VectorX<T>. This is the preferred method for examining a BasicVector’s value.

class pydrake.systems.framework.CacheEntry

A CacheEntry belongs to a System and represents the properties of one of that System’s cached computations. CacheEntry objects are assigned CacheIndex values in the order they are declared; these are unique within a single System and can be used for quick access to both the CacheEntry and the corresponding CacheEntryValue in the System’s Context.

CacheEntry objects are allocated automatically for known System computations like output ports and time derivatives, and may also be allocated by user code for other cached computations.

A cache entry’s value is always stored as an AbstractValue, which can hold a concrete value of any copyable type. However, once a value has been allocated using a particular concrete type, the type cannot be changed.

CacheEntry objects support four important operations: - Allocate() returns an object that can hold the cached value. - Calc() unconditionally computes the cached value. - Eval() returns a reference to the cached value, first updating with Calc() if it was out of date. - GetKnownUpToDate() returns a reference to the current value that you are certain must already be up to date.

The allocation and calculation functions must be provided at the time a cache entry is declared. That is typically done in a System constructor, in a manner very similar to the declaration of output ports.

__init__(*args, **kwargs)

cache_index(self: pydrake.systems.framework.CacheEntry) → pydrake.systems.framework.CacheIndex

Returns the CacheIndex used to locate this CacheEntry within the containing System.

description(self: pydrake.systems.framework.CacheEntry) → str

Return the human-readable description for this CacheEntry.

disable_caching(self: pydrake.systems.framework.CacheEntry, context: pydrake.systems.framework.ContextBase) → None

(Debugging) Disables caching for this cache entry in the given context. Eval() will recompute the cached value every time it is invoked, regardless of the state of the out_of_date flag. That should have no effect on any computed results, other than speed. See class documentation for ideas as to what might be wrong if you see a change. Note that the context is const here; cache entry values are mutable.

disable_caching_by_default(self: pydrake.systems.framework.CacheEntry) → None

(Debugging) Marks this cache entry so that the corresponding CacheEntryValue object in any allocated Context is created with its disabled flag initially set. This can be useful for debugging when you have observed a difference between cached and non-cached behavior that can’t be diagnosed with the runtime disable_caching() method.

See also

disable_caching()

enable_caching(self: pydrake.systems.framework.CacheEntry, context: pydrake.systems.framework.ContextBase) → None

(Debugging) Enables caching for this cache entry in the given context if it was previously disabled.

Eval(self: pydrake.systems.framework.CacheEntry, context: pydrake.systems.framework.ContextBase) → object

Returns a reference to the up-to-date value of this cache entry contained in the given Context. This is the preferred way to obtain a cached value. If the value is not already up to date with respect to its prerequisites, or if caching is disabled for this entry, then this entry’s Calc() method is used first to update the value before the reference is returned. The Calc() method may be arbitrarily expensive, but this method is constant time and very fast if the value is already up to date. If you are certain the value should be up to date already, you may use the GetKnownUpToDate() method instead.

Precondition:

context is a subcontext that is compatible with the subsystem that owns this cache entry.

Raises

RuntimeError if the value doesn't actually have type V. –

EvalAbstract(self: pydrake.systems.framework.CacheEntry, context: pydrake.systems.framework.ContextBase) → pydrake.common.value.AbstractValue

get_cache_entry_value(self: pydrake.systems.framework.CacheEntry, context: pydrake.systems.framework.ContextBase) → pydrake.systems.framework.CacheEntryValue

(Advanced) Returns a const reference to the CacheEntryValue object that corresponds to this CacheEntry, from the supplied Context. The returned object contains the current value and tracks whether it is up to date with respect to its prerequisites. If you just need the value, use the Eval() method rather than this one. This method is constant time and very fast in all circumstances.

get_mutable_cache_entry_value(self: pydrake.systems.framework.CacheEntry, context: pydrake.systems.framework.ContextBase) → pydrake.systems.framework.CacheEntryValue

(Advanced) Returns a mutable reference to the CacheEntryValue object that corresponds to this CacheEntry, from the supplied Context. Note that context is const; cache values are mutable. Don’t call this method unless you know what you’re doing. This method is constant time and very fast in all circumstances.

has_default_prerequisites(self: pydrake.systems.framework.CacheEntry) → bool

(Advanced) Returns True if this cache entry was created without specifying any prerequisites. This can be useful in determining whether the apparent dependencies should be believed, or whether they may just be due to some user’s ignorance.

Note

Currently we can’t distinguish between “no prerequisites given” (in which case we default to all_sources_ticket()) and “prerequisite specified as all_sources_ticket()`". Either of those cases makes this method return `true now, but we intend to change so that explicit specification of all_sources_ticket() will be considered non-default. So don’t depend on the current behavior.

is_cache_entry_disabled(self: pydrake.systems.framework.CacheEntry, context: pydrake.systems.framework.ContextBase) → bool

(Debugging) Returns True if caching has been disabled for this cache entry in the given context. That means Eval() will recalculate even if the entry is marked up to date.

is_disabled_by_default(self: pydrake.systems.framework.CacheEntry) → bool

(Debugging) Returns the current value of this flag. It is False unless a call to disable_caching_by_default() has previously been made.

is_out_of_date(self: pydrake.systems.framework.CacheEntry, context: pydrake.systems.framework.ContextBase) → bool

Returns True if the current value of this cache entry is out of date with respect to its prerequisites. If this returns False then the Eval() method will not perform any computation when invoked, unless caching has been disabled for this entry. If this returns True the GetKnownUpToDate() methods will fail if invoked.

prerequisites(self: pydrake.systems.framework.CacheEntry) → set[pydrake.systems.framework.DependencyTicket]

Returns a reference to the set of prerequisites needed by this cache entry’s Calc() function. These are all within the same subsystem that owns this CacheEntry.

ticket(self: pydrake.systems.framework.CacheEntry) → pydrake.systems.framework.DependencyTicket

Returns the DependencyTicket used to register dependencies on the value of this CacheEntry. This can also be used to locate the DependencyTracker that manages dependencies at runtime for the associated CacheEntryValue in a Context.

class pydrake.systems.framework.CacheEntryValue

(Advanced) This is the representation in the Context for the value of one of a System’s CacheEntry objects. Most users will not use this class directly – System and CacheEntry provide the most common APIs, and Context provides additional useful methods.

See also

System, CacheEntry, Context for user-facing APIs.

A CacheEntryValue consists of a single type-erased value, a serial number, an out_of_date flag, and a DependencyTracker ticket. Details: - “Out of date” means that some prerequisite of this cache entry’s computation has been changed in the current Context since the stored value was last computed, and thus must be recomputed prior to use. On the other hand, if the entry is not out of date, then it is “up to date” meaning that if you were to recompute it using the current Context values you would get the identical result (so don’t bother!). - The “serial number” is an integer that is incremented whenever the value is modified, or made available for mutable access. You can use it to recognize that you are looking at the same value as you saw at some earlier time. It is also useful for performance studies since it is a count of how many times this value was recomputed. Note that marking the value “out of date” is not a modification; that does not change the serial number. The serial number is maintained internally and cannot be user-modified. - The DependencyTicket (“ticket”) stored here identifies the DependencyTracker (“tracker”) associated with this cache entry. The tracker maintains lists of all upstream prerequisites and downstream dependents of the value stored here, and also has a pointer to this CacheEntryValue that it uses for invalidation. Upstream modifications cause the tracker to set the out_of_date flag here, and mark all downstream dependents out of date also. The tracker lives in the same subcontext that owns the Cache that owns this CacheEntryValue.

We sometimes use the terms “invalid” and “invalidate” as synonyms for “out of date” and “mark out of date”.

For debugging purposes, caching may be disabled for an entire Context or for particular cache entry values. This is independent of the out_of_date flag described above, which is still expected to be operational when caching is disabled. However, when caching is disabled the Eval() methods will recompute the contained value even if it is not marked out of date. That should have no effect other than to slow computation; if results change, something is wrong. There could be a problem with the specification of dependencies, a bug in user code such as improper retention of a stale reference, or a bug in the caching system.

__init__(*args, **kwargs)

GetMutableValueOrThrow(self: pydrake.systems.framework.CacheEntryValue) → object

(Advanced) Convenience method that returns a mutable reference to the contained value downcast to its known concrete type. Throws an exception if the contained value does not have the indicated concrete type. Note that you must call mark_up_to_date() after modifying the value through the returned reference. See GetMutableAbstractValueOrThrow() above for more information.

Raises

• RuntimeError if there is no value, or if the value is already up –

• to date, of it doesn't actually have type V. –

• RuntimeError if the cache is frozen. –

See also

SetValueOrThrow(), set_value(), mark_up_to_date()

Template parameter V:

The known actual value type.

GetValueOrThrow(self: pydrake.systems.framework.CacheEntryValue) → object

Returns a const reference to the contained value of known type V. It is an error to call this if there is no stored value, or the value is out of date, or the value doesn’t actually have type V.

Raises

• RuntimeError if there is no stored value, or if it is out of date, –

• or it doesn't actually have type V. –

See also

get_value()

class pydrake.systems.framework.CacheIndex

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.CacheIndex) -> None

Default constructor; the result is an invalid index. This only exists to serve applications which require a default constructor.

2. __init__(self: pydrake.systems.framework.CacheIndex, arg0: int) -> None

Construction from a non-negative int value. The value must lie in the range of [0, 2³¹). Constructor only promises to test validity in Debug build.

is_valid(self: pydrake.systems.framework.CacheIndex) → bool

Reports if the index is valid–the only operation on an invalid index that doesn’t throw an exception in Debug builds.

class pydrake.systems.framework.Context

Bases: pydrake.systems.framework.ContextBase

Context is an abstract class template that represents all the typed values that are used in a System’s computations: time, numeric-valued input ports, numerical state, and numerical parameters. There are also type-erased abstract state variables, abstract-valued input ports, abstract parameters, and a double accuracy setting. The framework provides two concrete subclasses of Context: LeafContext (for leaf Systems) and DiagramContext (for composite System Diagrams). Users are forbidden to extend DiagramContext and are discouraged from subclassing LeafContext.

A Context is designed to be used only with the System that created it. Data encapsulated with State and Parameter objects can be copied between contexts for compatible systems with some restrictions. For details, see system_compatibility.

Note

This class is templated; see Context_ for the list of instantiations.

__init__(*args, **kwargs)

Clone(self: pydrake.systems.framework.Context) → pydrake.systems.framework.Context

Returns a deep copy of this Context.

Raises

RuntimeError if this is not the root context. –

get_abstract_parameter(self: pydrake.systems.framework.Context, index: int) → pydrake.common.value.AbstractValue

Returns a const reference to the vector-valued parameter at index.

Precondition:

index must identify an existing parameter.

get_abstract_state(*args, **kwargs)

Overloaded function.

1. get_abstract_state(self: pydrake.systems.framework.Context) -> pydrake.systems.framework.AbstractValues

Returns a const reference to the abstract component of the state, which may be of size zero.

2. get_abstract_state(self: pydrake.systems.framework.Context, index: int) -> pydrake.common.value.AbstractValue

Returns a const reference to the abstract component of the state at index.

Precondition:

index must identify an existing element.

Precondition:

the abstract state’s type must match the template argument.

get_accuracy(self: pydrake.systems.framework.Context) → Optional[float]

Returns the accuracy setting (if any). Note that the return type is optional<double> rather than the double value itself.

See also

SetAccuracy() for details.

get_continuous_state(self: pydrake.systems.framework.Context) → pydrake.systems.framework.ContinuousState

Returns a const reference to the continuous component of the state, which may be of size zero.

get_continuous_state_vector(self: pydrake.systems.framework.Context) → pydrake.systems.framework.VectorBase

Returns a reference to the continuous state vector, devoid of second-order structure. The vector may be of size zero.

get_discrete_state(*args, **kwargs)

Overloaded function.

1. get_discrete_state(self: pydrake.systems.framework.Context) -> pydrake.systems.framework.DiscreteValues

Returns a reference to the entire discrete state, which may consist of multiple discrete state vectors (groups).

2. get_discrete_state(self: pydrake.systems.framework.Context, arg0: int) -> pydrake.systems.framework.BasicVector

Returns a const reference to group (vector) index of the discrete state.

Precondition:

index must identify an existing group.

get_discrete_state_vector(self: pydrake.systems.framework.Context) → pydrake.systems.framework.BasicVector

Returns a reference to the only discrete state vector. The vector may be of size zero.

Precondition:

There is only one discrete state group.

get_mutable_abstract_parameter(self: pydrake.systems.framework.Context, index: int) → pydrake.common.value.AbstractValue

Returns a mutable reference to element index of the abstract-valued parameters. Sends out of date notifications for all computations dependent on this parameter.

Precondition:

index must identify an existing abstract parameter.

Note

Currently notifies dependents of all abstract parameters.

get_mutable_abstract_state(*args, **kwargs)

Overloaded function.

1. get_mutable_abstract_state(self: pydrake.systems.framework.Context) -> pydrake.systems.framework.AbstractValues

Returns a mutable reference to the abstract component of the state, which may be of size zero. Sends out of date notifications for all abstract-state-dependent computations.

Warning

You must not use the returned reference to modify the size, number, or types of abstract state variables.

2. get_mutable_abstract_state(self: pydrake.systems.framework.Context, index: int) -> pydrake.common.value.AbstractValue

Returns a mutable reference to element index of the abstract state. Sends out of date notifications for all computations that depend on this abstract state variable.

Precondition:

index must identify an existing element.

Precondition:

the abstract state’s type must match the template argument.

Note

Currently notifies dependents of any abstract state variable.

get_mutable_continuous_state(self: pydrake.systems.framework.Context) → pydrake.systems.framework.ContinuousState

Returns a mutable reference to the continuous component of the state, which may be of size zero. Sends out of date notifications for all continuous-state-dependent computations.

get_mutable_continuous_state_vector(self: pydrake.systems.framework.Context) → pydrake.systems.framework.VectorBase

Returns a mutable reference to the continuous state vector, devoid of second-order structure. The vector may be of size zero. Sends out of date notifications for all continuous-state-dependent computations.

get_mutable_discrete_state(*args, **kwargs)

Overloaded function.

1. get_mutable_discrete_state(self: pydrake.systems.framework.Context) -> pydrake.systems.framework.DiscreteValues

Returns a mutable reference to the discrete component of the state, which may be of size zero. Sends out of date notifications for all discrete-state-dependent computations.

Warning

You must not use the returned reference to modify the size or number of discrete state variables.

2. get_mutable_discrete_state(self: pydrake.systems.framework.Context, arg0: int) -> pydrake.systems.framework.BasicVector

Returns a mutable reference to group (vector) index of the discrete state. Sends out of date notifications for all computations that depend on this discrete state group.

Precondition:

index must identify an existing group.

Note

Currently notifies dependents of all groups.

get_mutable_discrete_state_vector(self: pydrake.systems.framework.Context) → pydrake.systems.framework.BasicVector

Returns a mutable reference to the only discrete state vector. Sends out of date notifications for all discrete-state-dependent computations.

See also

get_discrete_state_vector().

Precondition:

There is only one discrete state group.

get_mutable_numeric_parameter(self: pydrake.systems.framework.Context, index: int) → pydrake.systems.framework.BasicVector

Returns a mutable reference to element index of the vector-valued (numeric) parameters. Sends out of date notifications for all computations dependent on this parameter.

Precondition:

index must identify an existing numeric parameter.

Note

Currently notifies dependents of all numeric parameters.

get_mutable_parameters(self: pydrake.systems.framework.Context) → pydrake.systems.framework.Parameters

Returns a mutable reference to this Context’s parameters. Sends out of date notifications for all parameter-dependent computations. If you don’t mean to change all the parameters, use the indexed methods to modify only some of the parameters so that fewer computations are invalidated and fewer notifications need be sent.

Warning

You must not use the returned reference to modify the size, number, or types of parameters.

get_mutable_state(self: pydrake.systems.framework.Context) → pydrake.systems.framework.State

Returns a mutable reference to the whole State, potentially invalidating all state-dependent computations so requiring out of date notifications to be made for all such computations. If you don’t mean to change the whole state, use more focused methods to modify only a portion of the state. See class documentation for more information.

Warning

You must not use the returned reference to modify the size, number, or types of state variables.

get_numeric_parameter(self: pydrake.systems.framework.Context, index: int) → pydrake.systems.framework.BasicVector

Returns a const reference to the vector-valued parameter at index.

Precondition:

index must identify an existing parameter.

get_parameters(self: pydrake.systems.framework.Context) → pydrake.systems.framework.Parameters

Returns a const reference to this Context’s parameters.

get_state(self: pydrake.systems.framework.Context) → pydrake.systems.framework.State

Returns a const reference to the whole State.

get_time(self: pydrake.systems.framework.Context) → float

Returns the current time in seconds.

See also

SetTime()

has_only_continuous_state(self: pydrake.systems.framework.Context) → bool

Returns true if the Context has continuous state, but no discrete or abstract state.

has_only_discrete_state(self: pydrake.systems.framework.Context) → bool

Returns true if the Context has discrete state, but no continuous or abstract state.

is_stateless(self: pydrake.systems.framework.Context) → bool

Returns true if the Context has no state.

num_abstract_parameters(self: pydrake.systems.framework.Context) → int

Returns the number of abstract-valued parameters.

num_abstract_states(self: pydrake.systems.framework.Context) → int

Returns the number of elements in the abstract state.

num_continuous_states(self: pydrake.systems.framework.Context) → int

Returns the number of continuous state variables xc = {q, v, z}.

num_discrete_state_groups(self: pydrake.systems.framework.Context) → int

Returns the number of vectors (groups) in the discrete state.

num_numeric_parameter_groups(self: pydrake.systems.framework.Context) → int

Returns the number of vector-valued parameters.

num_total_states(self: pydrake.systems.framework.Context) → int

Returns the total dimension of all of the basic vector states (as if they were muxed).

Raises

RuntimeError if the system contains any abstract state. –

SetAbstractState(self: object, index: int, value: object) → None

Sets the value of the abstract state variable selected by index. Sends out of date notifications for all computations that depend on that abstract state variable. The template type will be inferred and need not be specified explicitly.

Precondition:

index must identify an existing abstract state variable.

Precondition:

the abstract state’s type must match the template argument.

Note

Currently notifies dependents of any abstract state variable.

SetAccuracy(self: pydrake.systems.framework.Context, accuracy: Optional[float]) → None

Records the user’s requested accuracy, which is a unit-less quantity designed for use with simulation and other numerical studies. Since accuracy is unit-less, algorithms and systems are free to interpret this quantity as they wish. The intention is that more computational work is acceptable as the accuracy setting is tightened (set closer to zero). If no accuracy is requested, computations are free to choose suitable defaults, or to refuse to proceed without an explicit accuracy setting. The accuracy of a complete simulation or other numerical study depends on the accuracy of all contributing computations, so it is important that each computation is done in accordance with the requested accuracy. Some examples of where this is needed: - Error-controlled numerical integrators use the accuracy setting to decide what step sizes to take. - The Simulator employs a numerical integrator, but also uses accuracy to decide how precisely to isolate witness function zero crossings. - Iterative calculations reported as results or cached internally depend on accuracy to decide how strictly to converge the results. Examples of these are: constraint projection, calculation of distances between smooth shapes, and deformation calculations for soft contact.

The common thread among these examples is that they all share the same Context, so by keeping accuracy here it can be used effectively to control all accuracy-dependent computations.

Any accuracy-dependent computation in this Context and its subcontexts may be invalidated by a change to the accuracy setting, so out of date notifications are sent to all such computations (at least if the accuracy setting has actually changed). Accuracy must have the same value in every subcontext within the same context tree so may only be modified at the root context of a tree.

Requested accuracy is stored in the Context for two reasons: - It permits all computations performed over a System to see the same accuracy request since accuracy is stored in one shared place, and - it allows us to notify accuracy-dependent cached results that they are out of date when the accuracy setting changes.

Raises

RuntimeError if this is not the root context. –

SetContinuousState(self: pydrake.systems.framework.Context, arg0: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets the continuous state to xc, including q, v, and z partitions. The supplied vector must be the same size as the existing continuous state. Sends out of date notifications for all continuous-state-dependent computations.

SetDiscreteState(*args, **kwargs)

Overloaded function.

1. SetDiscreteState(self: pydrake.systems.framework.Context, xd: numpy.ndarray[numpy.float64[m, 1]]) -> None

Sets the discrete state to xd, assuming there is just one discrete state group. The supplied vector must be the same size as the existing discrete state. Sends out of date notifications for all discrete-state-dependent computations. Use the other signature for this method if you have multiple discrete state groups.

Precondition:

There is exactly one discrete state group.

2. SetDiscreteState(self: pydrake.systems.framework.Context, group_index: int, xd: numpy.ndarray[numpy.float64[m, 1]]) -> None

Sets the discrete state group indicated by group_index to xd. The supplied vector xd must be the same size as the existing discrete state group. Sends out of date notifications for all computations that depend on this discrete state group.

Precondition:

group_index identifies an existing group.

Note

Currently notifies dependents of all groups.

3. SetDiscreteState(self: pydrake.systems.framework.Context, xd: pydrake.systems.framework.DiscreteValues) -> None

Sets all the discrete state variables in this Context from a compatible DiscreteValues object.

Raises

• RuntimeError unless the number of groups and size of each group of –

• xd` matches those in this Context –

SetStateAndParametersFrom(*args, **kwargs)

Overloaded function.

1. SetStateAndParametersFrom(self: pydrake.systems.framework.Context, source: pydrake.systems.framework.Context) -> None

Copies all state and parameters in source, where numerical values are of type U, to this context. Time and accuracy are unchanged in this context, which means that this method can be called on a subcontext. Sends out of date notifications for all dependent computations in this context.

Note

Currently does not copy fixed input port values from source. See System::FixInputPortsFrom() if you want to copy those.

See also

SetTimeStateAndParametersFrom() if you want to copy time and accuracy along with state and parameters to a root context.

2. SetStateAndParametersFrom(self: pydrake.systems.framework.Context, source: pydrake.systems.framework.Context_[AutoDiffXd]) -> None

Copies all state and parameters in source, where numerical values are of type U, to this context. Time and accuracy are unchanged in this context, which means that this method can be called on a subcontext. Sends out of date notifications for all dependent computations in this context.

Note

Currently does not copy fixed input port values from source. See System::FixInputPortsFrom() if you want to copy those.

See also

SetTimeStateAndParametersFrom() if you want to copy time and accuracy along with state and parameters to a root context.

3. SetStateAndParametersFrom(self: pydrake.systems.framework.Context, source: pydrake.systems.framework.Context_[Expression]) -> None

Copies all state and parameters in source, where numerical values are of type U, to this context. Time and accuracy are unchanged in this context, which means that this method can be called on a subcontext. Sends out of date notifications for all dependent computations in this context.

Note

Currently does not copy fixed input port values from source. See System::FixInputPortsFrom() if you want to copy those.

See also

SetTimeStateAndParametersFrom() if you want to copy time and accuracy along with state and parameters to a root context.

SetTime(self: pydrake.systems.framework.Context, time_sec: float) → None

Sets the current time in seconds. Sends out of date notifications for all time-dependent computations (at least if the time has actually changed). Time must have the same value in every subcontext within the same Diagram context tree so may only be modified at the root context of the tree.

Raises

RuntimeError if this is not the root context. –

SetTimeAndContinuousState(self: pydrake.systems.framework.Context, arg0: float, arg1: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets time to time_sec and continuous state to xc. Performs a single notification sweep to avoid duplicate notifications for computations that depend on both time and state.

Raises

RuntimeError if this is not the root context. –

SetTimeStateAndParametersFrom(*args, **kwargs)

Overloaded function.

1. SetTimeStateAndParametersFrom(self: pydrake.systems.framework.Context, source: pydrake.systems.framework.Context) -> None

Copies time, accuracy, all state and all parameters in source, where numerical values are of type U, to this context. This method can only be called on root contexts because time and accuracy are copied. Sends out of date notifications for all dependent computations in this context.

Raises

RuntimeError if this is not the root context. –

Note

Currently does not copy fixed input port values from source. See System::FixInputPortsFrom() if you want to copy those.

See also

SetStateAndParametersFrom() if you want to copy state and parameters to a non-root context.

2. SetTimeStateAndParametersFrom(self: pydrake.systems.framework.Context, source: pydrake.systems.framework.Context_[AutoDiffXd]) -> None

Copies time, accuracy, all state and all parameters in source, where numerical values are of type U, to this context. This method can only be called on root contexts because time and accuracy are copied. Sends out of date notifications for all dependent computations in this context.

Raises

RuntimeError if this is not the root context. –

Note

Currently does not copy fixed input port values from source. See System::FixInputPortsFrom() if you want to copy those.

See also

SetStateAndParametersFrom() if you want to copy state and parameters to a non-root context.

3. SetTimeStateAndParametersFrom(self: pydrake.systems.framework.Context, source: pydrake.systems.framework.Context_[Expression]) -> None

Copies time, accuracy, all state and all parameters in source, where numerical values are of type U, to this context. This method can only be called on root contexts because time and accuracy are copied. Sends out of date notifications for all dependent computations in this context.

Raises

RuntimeError if this is not the root context. –

Note

Currently does not copy fixed input port values from source. See System::FixInputPortsFrom() if you want to copy those.

See also

SetStateAndParametersFrom() if you want to copy state and parameters to a non-root context.

template pydrake.systems.framework.Context_

Instantiations: Context_[float], Context_[AutoDiffXd], Context_[Expression]

class pydrake.systems.framework.Context_[AutoDiffXd]

Bases: pydrake.systems.framework.ContextBase

Context is an abstract class template that represents all the typed values that are used in a System’s computations: time, numeric-valued input ports, numerical state, and numerical parameters. There are also type-erased abstract state variables, abstract-valued input ports, abstract parameters, and a double accuracy setting. The framework provides two concrete subclasses of Context: LeafContext (for leaf Systems) and DiagramContext (for composite System Diagrams). Users are forbidden to extend DiagramContext and are discouraged from subclassing LeafContext.

A Context is designed to be used only with the System that created it. Data encapsulated with State and Parameter objects can be copied between contexts for compatible systems with some restrictions. For details, see system_compatibility.

__init__(*args, **kwargs)

Clone(self: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.systems.framework.Context_[AutoDiffXd]

Returns a deep copy of this Context.

Raises

RuntimeError if this is not the root context. –

get_abstract_parameter(self: pydrake.systems.framework.Context_[AutoDiffXd], index: int) → pydrake.common.value.AbstractValue

Returns a const reference to the vector-valued parameter at index.

Precondition:

index must identify an existing parameter.

get_abstract_state(*args, **kwargs)

Overloaded function.

1. get_abstract_state(self: pydrake.systems.framework.Context_[AutoDiffXd]) -> pydrake.systems.framework.AbstractValues

Returns a const reference to the abstract component of the state, which may be of size zero.

2. get_abstract_state(self: pydrake.systems.framework.Context_[AutoDiffXd], index: int) -> pydrake.common.value.AbstractValue

Returns a const reference to the abstract component of the state at index.

Precondition:

index must identify an existing element.

Precondition:

the abstract state’s type must match the template argument.

get_accuracy(self: pydrake.systems.framework.Context_[AutoDiffXd]) → Optional[float]

Returns the accuracy setting (if any). Note that the return type is optional<double> rather than the double value itself.

See also

SetAccuracy() for details.

get_continuous_state(self: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.systems.framework.ContinuousState_[AutoDiffXd]

Returns a const reference to the continuous component of the state, which may be of size zero.

get_continuous_state_vector(self: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.systems.framework.VectorBase_[AutoDiffXd]

Returns a reference to the continuous state vector, devoid of second-order structure. The vector may be of size zero.

get_discrete_state(*args, **kwargs)

Overloaded function.

1. get_discrete_state(self: pydrake.systems.framework.Context_[AutoDiffXd]) -> pydrake.systems.framework.DiscreteValues_[AutoDiffXd]

Returns a reference to the entire discrete state, which may consist of multiple discrete state vectors (groups).

2. get_discrete_state(self: pydrake.systems.framework.Context_[AutoDiffXd], arg0: int) -> pydrake.systems.framework.BasicVector_[AutoDiffXd]

Returns a const reference to group (vector) index of the discrete state.

Precondition:

index must identify an existing group.

get_discrete_state_vector(self: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.systems.framework.BasicVector_[AutoDiffXd]

Returns a reference to the only discrete state vector. The vector may be of size zero.

Precondition:

There is only one discrete state group.

get_mutable_abstract_parameter(self: pydrake.systems.framework.Context_[AutoDiffXd], index: int) → pydrake.common.value.AbstractValue

Returns a mutable reference to element index of the abstract-valued parameters. Sends out of date notifications for all computations dependent on this parameter.

Precondition:

index must identify an existing abstract parameter.

Note

Currently notifies dependents of all abstract parameters.

get_mutable_abstract_state(*args, **kwargs)

Overloaded function.

1. get_mutable_abstract_state(self: pydrake.systems.framework.Context_[AutoDiffXd]) -> pydrake.systems.framework.AbstractValues

Returns a mutable reference to the abstract component of the state, which may be of size zero. Sends out of date notifications for all abstract-state-dependent computations.

Warning

You must not use the returned reference to modify the size, number, or types of abstract state variables.

2. get_mutable_abstract_state(self: pydrake.systems.framework.Context_[AutoDiffXd], index: int) -> pydrake.common.value.AbstractValue

Returns a mutable reference to element index of the abstract state. Sends out of date notifications for all computations that depend on this abstract state variable.

Precondition:

index must identify an existing element.

Precondition:

the abstract state’s type must match the template argument.

Note

Currently notifies dependents of any abstract state variable.

get_mutable_continuous_state(self: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.systems.framework.ContinuousState_[AutoDiffXd]

Returns a mutable reference to the continuous component of the state, which may be of size zero. Sends out of date notifications for all continuous-state-dependent computations.

get_mutable_continuous_state_vector(self: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.systems.framework.VectorBase_[AutoDiffXd]

Returns a mutable reference to the continuous state vector, devoid of second-order structure. The vector may be of size zero. Sends out of date notifications for all continuous-state-dependent computations.

get_mutable_discrete_state(*args, **kwargs)

Overloaded function.

1. get_mutable_discrete_state(self: pydrake.systems.framework.Context_[AutoDiffXd]) -> pydrake.systems.framework.DiscreteValues_[AutoDiffXd]

Returns a mutable reference to the discrete component of the state, which may be of size zero. Sends out of date notifications for all discrete-state-dependent computations.

Warning

You must not use the returned reference to modify the size or number of discrete state variables.

2. get_mutable_discrete_state(self: pydrake.systems.framework.Context_[AutoDiffXd], arg0: int) -> pydrake.systems.framework.BasicVector_[AutoDiffXd]

Returns a mutable reference to group (vector) index of the discrete state. Sends out of date notifications for all computations that depend on this discrete state group.

Precondition:

index must identify an existing group.

Note

Currently notifies dependents of all groups.

get_mutable_discrete_state_vector(self: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.systems.framework.BasicVector_[AutoDiffXd]

Returns a mutable reference to the only discrete state vector. Sends out of date notifications for all discrete-state-dependent computations.

See also

get_discrete_state_vector().

Precondition:

There is only one discrete state group.

get_mutable_numeric_parameter(self: pydrake.systems.framework.Context_[AutoDiffXd], index: int) → pydrake.systems.framework.BasicVector_[AutoDiffXd]

Returns a mutable reference to element index of the vector-valued (numeric) parameters. Sends out of date notifications for all computations dependent on this parameter.

Precondition:

index must identify an existing numeric parameter.

Note

Currently notifies dependents of all numeric parameters.

get_mutable_parameters(self: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.systems.framework.Parameters_[AutoDiffXd]

Returns a mutable reference to this Context’s parameters. Sends out of date notifications for all parameter-dependent computations. If you don’t mean to change all the parameters, use the indexed methods to modify only some of the parameters so that fewer computations are invalidated and fewer notifications need be sent.

Warning

You must not use the returned reference to modify the size, number, or types of parameters.

get_mutable_state(self: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.systems.framework.State_[AutoDiffXd]

Returns a mutable reference to the whole State, potentially invalidating all state-dependent computations so requiring out of date notifications to be made for all such computations. If you don’t mean to change the whole state, use more focused methods to modify only a portion of the state. See class documentation for more information.

Warning

You must not use the returned reference to modify the size, number, or types of state variables.

get_numeric_parameter(self: pydrake.systems.framework.Context_[AutoDiffXd], index: int) → pydrake.systems.framework.BasicVector_[AutoDiffXd]

Returns a const reference to the vector-valued parameter at index.

Precondition:

index must identify an existing parameter.

get_parameters(self: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.systems.framework.Parameters_[AutoDiffXd]

Returns a const reference to this Context’s parameters.

get_state(self: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.systems.framework.State_[AutoDiffXd]

Returns a const reference to the whole State.

get_time(self: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.autodiffutils.AutoDiffXd

Returns the current time in seconds.

See also

SetTime()

has_only_continuous_state(self: pydrake.systems.framework.Context_[AutoDiffXd]) → bool

Returns true if the Context has continuous state, but no discrete or abstract state.

has_only_discrete_state(self: pydrake.systems.framework.Context_[AutoDiffXd]) → bool

Returns true if the Context has discrete state, but no continuous or abstract state.

is_stateless(self: pydrake.systems.framework.Context_[AutoDiffXd]) → bool

Returns true if the Context has no state.

num_abstract_parameters(self: pydrake.systems.framework.Context_[AutoDiffXd]) → int

Returns the number of abstract-valued parameters.

num_abstract_states(self: pydrake.systems.framework.Context_[AutoDiffXd]) → int

Returns the number of elements in the abstract state.

num_continuous_states(self: pydrake.systems.framework.Context_[AutoDiffXd]) → int

Returns the number of continuous state variables xc = {q, v, z}.

num_discrete_state_groups(self: pydrake.systems.framework.Context_[AutoDiffXd]) → int

Returns the number of vectors (groups) in the discrete state.

num_numeric_parameter_groups(self: pydrake.systems.framework.Context_[AutoDiffXd]) → int

Returns the number of vector-valued parameters.

num_total_states(self: pydrake.systems.framework.Context_[AutoDiffXd]) → int

Returns the total dimension of all of the basic vector states (as if they were muxed).

Raises

RuntimeError if the system contains any abstract state. –

SetAbstractState(self: object, index: int, value: object) → None

Sets the value of the abstract state variable selected by index. Sends out of date notifications for all computations that depend on that abstract state variable. The template type will be inferred and need not be specified explicitly.

Precondition:

index must identify an existing abstract state variable.

Precondition:

the abstract state’s type must match the template argument.

Note

Currently notifies dependents of any abstract state variable.

SetAccuracy(self: pydrake.systems.framework.Context_[AutoDiffXd], accuracy: Optional[float]) → None

Records the user’s requested accuracy, which is a unit-less quantity designed for use with simulation and other numerical studies. Since accuracy is unit-less, algorithms and systems are free to interpret this quantity as they wish. The intention is that more computational work is acceptable as the accuracy setting is tightened (set closer to zero). If no accuracy is requested, computations are free to choose suitable defaults, or to refuse to proceed without an explicit accuracy setting. The accuracy of a complete simulation or other numerical study depends on the accuracy of all contributing computations, so it is important that each computation is done in accordance with the requested accuracy. Some examples of where this is needed: - Error-controlled numerical integrators use the accuracy setting to decide what step sizes to take. - The Simulator employs a numerical integrator, but also uses accuracy to decide how precisely to isolate witness function zero crossings. - Iterative calculations reported as results or cached internally depend on accuracy to decide how strictly to converge the results. Examples of these are: constraint projection, calculation of distances between smooth shapes, and deformation calculations for soft contact.

The common thread among these examples is that they all share the same Context, so by keeping accuracy here it can be used effectively to control all accuracy-dependent computations.

Any accuracy-dependent computation in this Context and its subcontexts may be invalidated by a change to the accuracy setting, so out of date notifications are sent to all such computations (at least if the accuracy setting has actually changed). Accuracy must have the same value in every subcontext within the same context tree so may only be modified at the root context of a tree.

Requested accuracy is stored in the Context for two reasons: - It permits all computations performed over a System to see the same accuracy request since accuracy is stored in one shared place, and - it allows us to notify accuracy-dependent cached results that they are out of date when the accuracy setting changes.

Raises

RuntimeError if this is not the root context. –

SetContinuousState(self: pydrake.systems.framework.Context_[AutoDiffXd], arg0: numpy.ndarray[object[m, 1]]) → None

Sets the continuous state to xc, including q, v, and z partitions. The supplied vector must be the same size as the existing continuous state. Sends out of date notifications for all continuous-state-dependent computations.

SetDiscreteState(*args, **kwargs)

Overloaded function.

1. SetDiscreteState(self: pydrake.systems.framework.Context_[AutoDiffXd], xd: numpy.ndarray[object[m, 1]]) -> None

Sets the discrete state to xd, assuming there is just one discrete state group. The supplied vector must be the same size as the existing discrete state. Sends out of date notifications for all discrete-state-dependent computations. Use the other signature for this method if you have multiple discrete state groups.

Precondition:

There is exactly one discrete state group.

2. SetDiscreteState(self: pydrake.systems.framework.Context_[AutoDiffXd], group_index: int, xd: numpy.ndarray[object[m, 1]]) -> None

Sets the discrete state group indicated by group_index to xd. The supplied vector xd must be the same size as the existing discrete state group. Sends out of date notifications for all computations that depend on this discrete state group.

Precondition:

group_index identifies an existing group.

Note

Currently notifies dependents of all groups.

3. SetDiscreteState(self: pydrake.systems.framework.Context_[AutoDiffXd], xd: pydrake.systems.framework.DiscreteValues_[AutoDiffXd]) -> None

Sets all the discrete state variables in this Context from a compatible DiscreteValues object.

Raises

• RuntimeError unless the number of groups and size of each group of –

• xd` matches those in this Context –

SetStateAndParametersFrom(*args, **kwargs)

Overloaded function.

1. SetStateAndParametersFrom(self: pydrake.systems.framework.Context_[AutoDiffXd], source: pydrake.systems.framework.Context) -> None

Copies all state and parameters in source, where numerical values are of type U, to this context. Time and accuracy are unchanged in this context, which means that this method can be called on a subcontext. Sends out of date notifications for all dependent computations in this context.

Note

Currently does not copy fixed input port values from source. See System::FixInputPortsFrom() if you want to copy those.

See also

SetTimeStateAndParametersFrom() if you want to copy time and accuracy along with state and parameters to a root context.

2. SetStateAndParametersFrom(self: pydrake.systems.framework.Context_[AutoDiffXd], source: pydrake.systems.framework.Context_[AutoDiffXd]) -> None

Copies all state and parameters in source, where numerical values are of type U, to this context. Time and accuracy are unchanged in this context, which means that this method can be called on a subcontext. Sends out of date notifications for all dependent computations in this context.

Note

Currently does not copy fixed input port values from source. See System::FixInputPortsFrom() if you want to copy those.

See also

SetTimeStateAndParametersFrom() if you want to copy time and accuracy along with state and parameters to a root context.

3. SetStateAndParametersFrom(self: pydrake.systems.framework.Context_[AutoDiffXd], source: pydrake.systems.framework.Context_[Expression]) -> None

Copies all state and parameters in source, where numerical values are of type U, to this context. Time and accuracy are unchanged in this context, which means that this method can be called on a subcontext. Sends out of date notifications for all dependent computations in this context.

Note

Currently does not copy fixed input port values from source. See System::FixInputPortsFrom() if you want to copy those.

See also

SetTimeStateAndParametersFrom() if you want to copy time and accuracy along with state and parameters to a root context.

SetTime(self: pydrake.systems.framework.Context_[AutoDiffXd], time_sec: pydrake.autodiffutils.AutoDiffXd) → None

Sets the current time in seconds. Sends out of date notifications for all time-dependent computations (at least if the time has actually changed). Time must have the same value in every subcontext within the same Diagram context tree so may only be modified at the root context of the tree.

Raises

RuntimeError if this is not the root context. –

SetTimeAndContinuousState(self: pydrake.systems.framework.Context_[AutoDiffXd], arg0: pydrake.autodiffutils.AutoDiffXd, arg1: numpy.ndarray[object[m, 1]]) → None

Sets time to time_sec and continuous state to xc. Performs a single notification sweep to avoid duplicate notifications for computations that depend on both time and state.

Raises

RuntimeError if this is not the root context. –

SetTimeStateAndParametersFrom(*args, **kwargs)

Overloaded function.

1. SetTimeStateAndParametersFrom(self: pydrake.systems.framework.Context_[AutoDiffXd], source: pydrake.systems.framework.Context) -> None

Copies time, accuracy, all state and all parameters in source, where numerical values are of type U, to this context. This method can only be called on root contexts because time and accuracy are copied. Sends out of date notifications for all dependent computations in this context.

Raises

RuntimeError if this is not the root context. –

Note

Currently does not copy fixed input port values from source. See System::FixInputPortsFrom() if you want to copy those.

See also

SetStateAndParametersFrom() if you want to copy state and parameters to a non-root context.

2. SetTimeStateAndParametersFrom(self: pydrake.systems.framework.Context_[AutoDiffXd], source: pydrake.systems.framework.Context_[AutoDiffXd]) -> None

Copies time, accuracy, all state and all parameters in source, where numerical values are of type U, to this context. This method can only be called on root contexts because time and accuracy are copied. Sends out of date notifications for all dependent computations in this context.

Raises

RuntimeError if this is not the root context. –

Note

Currently does not copy fixed input port values from source. See System::FixInputPortsFrom() if you want to copy those.

See also

SetStateAndParametersFrom() if you want to copy state and parameters to a non-root context.

3. SetTimeStateAndParametersFrom(self: pydrake.systems.framework.Context_[AutoDiffXd], source: pydrake.systems.framework.Context_[Expression]) -> None

Copies time, accuracy, all state and all parameters in source, where numerical values are of type U, to this context. This method can only be called on root contexts because time and accuracy are copied. Sends out of date notifications for all dependent computations in this context.

Raises

RuntimeError if this is not the root context. –

Note

Currently does not copy fixed input port values from source. See System::FixInputPortsFrom() if you want to copy those.

See also

SetStateAndParametersFrom() if you want to copy state and parameters to a non-root context.

class pydrake.systems.framework.Context_[Expression]

Bases: pydrake.systems.framework.ContextBase

Context is an abstract class template that represents all the typed values that are used in a System’s computations: time, numeric-valued input ports, numerical state, and numerical parameters. There are also type-erased abstract state variables, abstract-valued input ports, abstract parameters, and a double accuracy setting. The framework provides two concrete subclasses of Context: LeafContext (for leaf Systems) and DiagramContext (for composite System Diagrams). Users are forbidden to extend DiagramContext and are discouraged from subclassing LeafContext.

A Context is designed to be used only with the System that created it. Data encapsulated with State and Parameter objects can be copied between contexts for compatible systems with some restrictions. For details, see system_compatibility.

__init__(*args, **kwargs)

Clone(self: pydrake.systems.framework.Context_[Expression]) → pydrake.systems.framework.Context_[Expression]

Returns a deep copy of this Context.

Raises

RuntimeError if this is not the root context. –

get_abstract_parameter(self: pydrake.systems.framework.Context_[Expression], index: int) → pydrake.common.value.AbstractValue

Returns a const reference to the vector-valued parameter at index.

Precondition:

index must identify an existing parameter.

get_abstract_state(*args, **kwargs)

Overloaded function.

1. get_abstract_state(self: pydrake.systems.framework.Context_[Expression]) -> pydrake.systems.framework.AbstractValues

Returns a const reference to the abstract component of the state, which may be of size zero.

2. get_abstract_state(self: pydrake.systems.framework.Context_[Expression], index: int) -> pydrake.common.value.AbstractValue

Returns a const reference to the abstract component of the state at index.

Precondition:

index must identify an existing element.

Precondition:

the abstract state’s type must match the template argument.

get_accuracy(self: pydrake.systems.framework.Context_[Expression]) → Optional[float]

Returns the accuracy setting (if any). Note that the return type is optional<double> rather than the double value itself.

See also

SetAccuracy() for details.

get_continuous_state(self: pydrake.systems.framework.Context_[Expression]) → pydrake.systems.framework.ContinuousState_[Expression]

Returns a const reference to the continuous component of the state, which may be of size zero.

get_continuous_state_vector(self: pydrake.systems.framework.Context_[Expression]) → pydrake.systems.framework.VectorBase_[Expression]

Returns a reference to the continuous state vector, devoid of second-order structure. The vector may be of size zero.

get_discrete_state(*args, **kwargs)

Overloaded function.

1. get_discrete_state(self: pydrake.systems.framework.Context_[Expression]) -> pydrake.systems.framework.DiscreteValues_[Expression]

Returns a reference to the entire discrete state, which may consist of multiple discrete state vectors (groups).

2. get_discrete_state(self: pydrake.systems.framework.Context_[Expression], arg0: int) -> pydrake.systems.framework.BasicVector_[Expression]

Returns a const reference to group (vector) index of the discrete state.

Precondition:

index must identify an existing group.

get_discrete_state_vector(self: pydrake.systems.framework.Context_[Expression]) → pydrake.systems.framework.BasicVector_[Expression]

Returns a reference to the only discrete state vector. The vector may be of size zero.

Precondition:

There is only one discrete state group.

get_mutable_abstract_parameter(self: pydrake.systems.framework.Context_[Expression], index: int) → pydrake.common.value.AbstractValue

Returns a mutable reference to element index of the abstract-valued parameters. Sends out of date notifications for all computations dependent on this parameter.

Precondition:

index must identify an existing abstract parameter.

Note

Currently notifies dependents of all abstract parameters.

get_mutable_abstract_state(*args, **kwargs)

Overloaded function.

1. get_mutable_abstract_state(self: pydrake.systems.framework.Context_[Expression]) -> pydrake.systems.framework.AbstractValues

Returns a mutable reference to the abstract component of the state, which may be of size zero. Sends out of date notifications for all abstract-state-dependent computations.

Warning

You must not use the returned reference to modify the size, number, or types of abstract state variables.

2. get_mutable_abstract_state(self: pydrake.systems.framework.Context_[Expression], index: int) -> pydrake.common.value.AbstractValue

Returns a mutable reference to element index of the abstract state. Sends out of date notifications for all computations that depend on this abstract state variable.

Precondition:

index must identify an existing element.

Precondition:

the abstract state’s type must match the template argument.

Note

Currently notifies dependents of any abstract state variable.

get_mutable_continuous_state(self: pydrake.systems.framework.Context_[Expression]) → pydrake.systems.framework.ContinuousState_[Expression]

Returns a mutable reference to the continuous component of the state, which may be of size zero. Sends out of date notifications for all continuous-state-dependent computations.

get_mutable_continuous_state_vector(self: pydrake.systems.framework.Context_[Expression]) → pydrake.systems.framework.VectorBase_[Expression]

Returns a mutable reference to the continuous state vector, devoid of second-order structure. The vector may be of size zero. Sends out of date notifications for all continuous-state-dependent computations.

get_mutable_discrete_state(*args, **kwargs)

Overloaded function.

1. get_mutable_discrete_state(self: pydrake.systems.framework.Context_[Expression]) -> pydrake.systems.framework.DiscreteValues_[Expression]

Returns a mutable reference to the discrete component of the state, which may be of size zero. Sends out of date notifications for all discrete-state-dependent computations.

Warning

You must not use the returned reference to modify the size or number of discrete state variables.

2. get_mutable_discrete_state(self: pydrake.systems.framework.Context_[Expression], arg0: int) -> pydrake.systems.framework.BasicVector_[Expression]

Returns a mutable reference to group (vector) index of the discrete state. Sends out of date notifications for all computations that depend on this discrete state group.

Precondition:

index must identify an existing group.

Note

Currently notifies dependents of all groups.

get_mutable_discrete_state_vector(self: pydrake.systems.framework.Context_[Expression]) → pydrake.systems.framework.BasicVector_[Expression]

Returns a mutable reference to the only discrete state vector. Sends out of date notifications for all discrete-state-dependent computations.

See also

get_discrete_state_vector().

Precondition:

There is only one discrete state group.

get_mutable_numeric_parameter(self: pydrake.systems.framework.Context_[Expression], index: int) → pydrake.systems.framework.BasicVector_[Expression]

Returns a mutable reference to element index of the vector-valued (numeric) parameters. Sends out of date notifications for all computations dependent on this parameter.

Precondition:

index must identify an existing numeric parameter.

Note

Currently notifies dependents of all numeric parameters.

get_mutable_parameters(self: pydrake.systems.framework.Context_[Expression]) → pydrake.systems.framework.Parameters_[Expression]

Returns a mutable reference to this Context’s parameters. Sends out of date notifications for all parameter-dependent computations. If you don’t mean to change all the parameters, use the indexed methods to modify only some of the parameters so that fewer computations are invalidated and fewer notifications need be sent.

Warning

You must not use the returned reference to modify the size, number, or types of parameters.

get_mutable_state(self: pydrake.systems.framework.Context_[Expression]) → pydrake.systems.framework.State_[Expression]

Returns a mutable reference to the whole State, potentially invalidating all state-dependent computations so requiring out of date notifications to be made for all such computations. If you don’t mean to change the whole state, use more focused methods to modify only a portion of the state. See class documentation for more information.

Warning

You must not use the returned reference to modify the size, number, or types of state variables.

get_numeric_parameter(self: pydrake.systems.framework.Context_[Expression], index: int) → pydrake.systems.framework.BasicVector_[Expression]

Returns a const reference to the vector-valued parameter at index.

Precondition:

index must identify an existing parameter.

get_parameters(self: pydrake.systems.framework.Context_[Expression]) → pydrake.systems.framework.Parameters_[Expression]

Returns a const reference to this Context’s parameters.

get_state(self: pydrake.systems.framework.Context_[Expression]) → pydrake.systems.framework.State_[Expression]

Returns a const reference to the whole State.

get_time(self: pydrake.systems.framework.Context_[Expression]) → pydrake.symbolic.Expression

Returns the current time in seconds.

See also

SetTime()

has_only_continuous_state(self: pydrake.systems.framework.Context_[Expression]) → bool

Returns true if the Context has continuous state, but no discrete or abstract state.

has_only_discrete_state(self: pydrake.systems.framework.Context_[Expression]) → bool

Returns true if the Context has discrete state, but no continuous or abstract state.

is_stateless(self: pydrake.systems.framework.Context_[Expression]) → bool

Returns true if the Context has no state.

num_abstract_parameters(self: pydrake.systems.framework.Context_[Expression]) → int

Returns the number of abstract-valued parameters.

num_abstract_states(self: pydrake.systems.framework.Context_[Expression]) → int

Returns the number of elements in the abstract state.

num_continuous_states(self: pydrake.systems.framework.Context_[Expression]) → int

Returns the number of continuous state variables xc = {q, v, z}.

num_discrete_state_groups(self: pydrake.systems.framework.Context_[Expression]) → int

Returns the number of vectors (groups) in the discrete state.

num_numeric_parameter_groups(self: pydrake.systems.framework.Context_[Expression]) → int

Returns the number of vector-valued parameters.

num_total_states(self: pydrake.systems.framework.Context_[Expression]) → int

Returns the total dimension of all of the basic vector states (as if they were muxed).

Raises

RuntimeError if the system contains any abstract state. –

SetAbstractState(self: object, index: int, value: object) → None

Sets the value of the abstract state variable selected by index. Sends out of date notifications for all computations that depend on that abstract state variable. The template type will be inferred and need not be specified explicitly.

Precondition:

index must identify an existing abstract state variable.

Precondition:

the abstract state’s type must match the template argument.

Note

Currently notifies dependents of any abstract state variable.

SetAccuracy(self: pydrake.systems.framework.Context_[Expression], accuracy: Optional[float]) → None

Records the user’s requested accuracy, which is a unit-less quantity designed for use with simulation and other numerical studies. Since accuracy is unit-less, algorithms and systems are free to interpret this quantity as they wish. The intention is that more computational work is acceptable as the accuracy setting is tightened (set closer to zero). If no accuracy is requested, computations are free to choose suitable defaults, or to refuse to proceed without an explicit accuracy setting. The accuracy of a complete simulation or other numerical study depends on the accuracy of all contributing computations, so it is important that each computation is done in accordance with the requested accuracy. Some examples of where this is needed: - Error-controlled numerical integrators use the accuracy setting to decide what step sizes to take. - The Simulator employs a numerical integrator, but also uses accuracy to decide how precisely to isolate witness function zero crossings. - Iterative calculations reported as results or cached internally depend on accuracy to decide how strictly to converge the results. Examples of these are: constraint projection, calculation of distances between smooth shapes, and deformation calculations for soft contact.

The common thread among these examples is that they all share the same Context, so by keeping accuracy here it can be used effectively to control all accuracy-dependent computations.

Any accuracy-dependent computation in this Context and its subcontexts may be invalidated by a change to the accuracy setting, so out of date notifications are sent to all such computations (at least if the accuracy setting has actually changed). Accuracy must have the same value in every subcontext within the same context tree so may only be modified at the root context of a tree.

Requested accuracy is stored in the Context for two reasons: - It permits all computations performed over a System to see the same accuracy request since accuracy is stored in one shared place, and - it allows us to notify accuracy-dependent cached results that they are out of date when the accuracy setting changes.

Raises

RuntimeError if this is not the root context. –

SetContinuousState(self: pydrake.systems.framework.Context_[Expression], arg0: numpy.ndarray[object[m, 1]]) → None

Sets the continuous state to xc, including q, v, and z partitions. The supplied vector must be the same size as the existing continuous state. Sends out of date notifications for all continuous-state-dependent computations.

SetDiscreteState(*args, **kwargs)

Overloaded function.

1. SetDiscreteState(self: pydrake.systems.framework.Context_[Expression], xd: numpy.ndarray[object[m, 1]]) -> None

Sets the discrete state to xd, assuming there is just one discrete state group. The supplied vector must be the same size as the existing discrete state. Sends out of date notifications for all discrete-state-dependent computations. Use the other signature for this method if you have multiple discrete state groups.

Precondition:

There is exactly one discrete state group.

2. SetDiscreteState(self: pydrake.systems.framework.Context_[Expression], group_index: int, xd: numpy.ndarray[object[m, 1]]) -> None

Sets the discrete state group indicated by group_index to xd. The supplied vector xd must be the same size as the existing discrete state group. Sends out of date notifications for all computations that depend on this discrete state group.

Precondition:

group_index identifies an existing group.

Note

Currently notifies dependents of all groups.

3. SetDiscreteState(self: pydrake.systems.framework.Context_[Expression], xd: pydrake.systems.framework.DiscreteValues_[Expression]) -> None

Sets all the discrete state variables in this Context from a compatible DiscreteValues object.

Raises

• RuntimeError unless the number of groups and size of each group of –

• xd` matches those in this Context –

SetStateAndParametersFrom(*args, **kwargs)

Overloaded function.

1. SetStateAndParametersFrom(self: pydrake.systems.framework.Context_[Expression], source: pydrake.systems.framework.Context) -> None

Copies all state and parameters in source, where numerical values are of type U, to this context. Time and accuracy are unchanged in this context, which means that this method can be called on a subcontext. Sends out of date notifications for all dependent computations in this context.

Note

Currently does not copy fixed input port values from source. See System::FixInputPortsFrom() if you want to copy those.

See also

SetTimeStateAndParametersFrom() if you want to copy time and accuracy along with state and parameters to a root context.

2. SetStateAndParametersFrom(self: pydrake.systems.framework.Context_[Expression], source: pydrake.systems.framework.Context_[AutoDiffXd]) -> None

Copies all state and parameters in source, where numerical values are of type U, to this context. Time and accuracy are unchanged in this context, which means that this method can be called on a subcontext. Sends out of date notifications for all dependent computations in this context.

Note

Currently does not copy fixed input port values from source. See System::FixInputPortsFrom() if you want to copy those.

See also

SetTimeStateAndParametersFrom() if you want to copy time and accuracy along with state and parameters to a root context.

3. SetStateAndParametersFrom(self: pydrake.systems.framework.Context_[Expression], source: pydrake.systems.framework.Context_[Expression]) -> None

Copies all state and parameters in source, where numerical values are of type U, to this context. Time and accuracy are unchanged in this context, which means that this method can be called on a subcontext. Sends out of date notifications for all dependent computations in this context.

Note

Currently does not copy fixed input port values from source. See System::FixInputPortsFrom() if you want to copy those.

See also

SetTimeStateAndParametersFrom() if you want to copy time and accuracy along with state and parameters to a root context.

SetTime(self: pydrake.systems.framework.Context_[Expression], time_sec: pydrake.symbolic.Expression) → None

Sets the current time in seconds. Sends out of date notifications for all time-dependent computations (at least if the time has actually changed). Time must have the same value in every subcontext within the same Diagram context tree so may only be modified at the root context of the tree.

Raises

RuntimeError if this is not the root context. –

SetTimeAndContinuousState(self: pydrake.systems.framework.Context_[Expression], arg0: pydrake.symbolic.Expression, arg1: numpy.ndarray[object[m, 1]]) → None

Sets time to time_sec and continuous state to xc. Performs a single notification sweep to avoid duplicate notifications for computations that depend on both time and state.

Raises

RuntimeError if this is not the root context. –

SetTimeStateAndParametersFrom(*args, **kwargs)

Overloaded function.

1. SetTimeStateAndParametersFrom(self: pydrake.systems.framework.Context_[Expression], source: pydrake.systems.framework.Context) -> None

Copies time, accuracy, all state and all parameters in source, where numerical values are of type U, to this context. This method can only be called on root contexts because time and accuracy are copied. Sends out of date notifications for all dependent computations in this context.

Raises

RuntimeError if this is not the root context. –

Note

Currently does not copy fixed input port values from source. See System::FixInputPortsFrom() if you want to copy those.

See also

SetStateAndParametersFrom() if you want to copy state and parameters to a non-root context.

2. SetTimeStateAndParametersFrom(self: pydrake.systems.framework.Context_[Expression], source: pydrake.systems.framework.Context_[AutoDiffXd]) -> None

Copies time, accuracy, all state and all parameters in source, where numerical values are of type U, to this context. This method can only be called on root contexts because time and accuracy are copied. Sends out of date notifications for all dependent computations in this context.

Raises

RuntimeError if this is not the root context. –

Note

Currently does not copy fixed input port values from source. See System::FixInputPortsFrom() if you want to copy those.

See also

SetStateAndParametersFrom() if you want to copy state and parameters to a non-root context.

3. SetTimeStateAndParametersFrom(self: pydrake.systems.framework.Context_[Expression], source: pydrake.systems.framework.Context_[Expression]) -> None

Copies time, accuracy, all state and all parameters in source, where numerical values are of type U, to this context. This method can only be called on root contexts because time and accuracy are copied. Sends out of date notifications for all dependent computations in this context.

Raises

RuntimeError if this is not the root context. –

Note

Currently does not copy fixed input port values from source. See System::FixInputPortsFrom() if you want to copy those.

See also

SetStateAndParametersFrom() if you want to copy state and parameters to a non-root context.

class pydrake.systems.framework.ContextBase

Provides non-templatized Context functionality shared by the templatized derived classes. That includes caching, dependency tracking, and management of local values for fixed input ports.

Terminology: in general a Drake System is a tree structure composed of “subsystems”, which are themselves System objects. The corresponding Context is a parallel tree structure composed of “subcontexts”, which are themselves Context objects. There is a one-to-one correspondence between subsystems and subcontexts. Within a given System (Context), its child subsystems (subcontexts) are indexed using a SubsystemIndex; there is no separate SubcontextIndex since the numbering must be identical.

__init__(*args, **kwargs)

DisableCaching(self: pydrake.systems.framework.ContextBase) → None

(Debugging) Disables caching recursively for this context and all its subcontexts. Caching is enabled by default. Disabling forces every Eval() method to perform a full calculation rather than returning the cached one. Results should be identical with or without caching, except for performance. If they are not, there is likely a problem with (a) the specified dependencies for some calculation, or (b) a misuse of references into cached values that hides modifications from the caching system, or (c) a bug in the caching system. The is_disabled flags are independent of the out_of_date flags, which continue to be maintained even when caching is disabled (though they are ignored). Caching can be re-enabled using EnableCaching().

EnableCaching(self: pydrake.systems.framework.ContextBase) → None

(Debugging) Re-enables caching recursively for this context and all its subcontexts. Caching is enabled by default but may have been disabled via a call to DisableCaching(). The is_disabled flags are independent of the out_of_date flags, which continue to be maintained even when caching is disabled (though they are ignored). Hence re-enabling the cache with this method may result in some entries being already considered up to date. See SetAllCacheEntriesOutOfDate() if you want to ensure that caching restarts with everything out of date. You might want to do that, for example, for repeatability or because you modified something in the debugger and want to make sure it gets used.

FreezeCache(self: pydrake.systems.framework.ContextBase) → None

(Advanced) Freezes the cache at its current contents, preventing any further cache updates. When frozen, accessing an out-of-date cache entry causes an exception to be throw. This is applied recursively to this Context and all its subcontexts, but not to its parent or siblings so it is most useful when called on the root Context. If the cache was already frozen this method does nothing but waste a little time.

is_cache_frozen(self: pydrake.systems.framework.ContextBase) → bool

(Advanced) Reports whether this Context’s cache is currently frozen. This checks only locally; it is possible that parent, child, or sibling subcontext caches are in a different state than this one.

num_input_ports(self: pydrake.systems.framework.ContextBase) → int

Returns the number of input ports in this context.

num_output_ports(self: pydrake.systems.framework.ContextBase) → int

Returns the number of output ports represented in this context.

SetAllCacheEntriesOutOfDate(self: pydrake.systems.framework.ContextBase) → None

(Debugging) Marks all cache entries out of date, recursively for this context and all its subcontexts. This forces the next Eval() request for each cache entry to perform a full calculation rather than returning the cached one. After that first recalculation, normal caching behavior resumes (assuming the cache is not disabled). Results should be identical whether this is called or not, since the caching system should be maintaining this flag correctly. If they are not, see the documentation for SetIsCacheDisabled() for suggestions.

UnfreezeCache(self: pydrake.systems.framework.ContextBase) → None

(Advanced) Unfreezes the cache if it was previously frozen. This is applied recursively to this Context and all its subcontexts, but not to its parent or siblings. If the cache was not frozen, this does nothing but waste a little time.

class pydrake.systems.framework.ContinuousState

%ContinuousState is a view of, and optionally a container for, all the continuous state variables xc of a Drake System. Continuous state variables are those whose values are defined by differential equations, so we expect there to be a well-defined time derivative xcdot ≜ d/dt xc.

The contents of xc are conceptually partitioned into three groups:

• q is generalized position

• v is generalized velocity

• z is other continuous state

For a Drake LeafSystem these partitions are stored contiguously in memory in this sequence: xc=[q v z]. But because a Drake System may be a Diagram composed from subsystems, each with its own continuous state variables (“substates”), the composite continuous state will not generally be stored in contiguous memory. In that case the most we can say is that xc={q,v,z}, that is, it consists of all the q’s, v’s, and z’s, in some order.

Nevertheless, this ContinuousState class provides a vector view of the data that groups together all the q partitions, v partitions, and z partitions. For example, if there are three subsystems (possibly Diagrams) whose continuous state variables are respectively xc₁={q₁,v₁,z₁}, xc₂={q₂,v₂,z₂}, and xc₃={q₃,v₃,z₃} the composite xc includes all the partitions in an undefined order. However, composite q, v, and z appear ordered as q=[q₁ q₂ q₃], v=[v₁ v₂ v₃], z=[z₁ z₂ z₃]. Note that the element ordering of the composite xc is not a concatenation of the composite subgroups. Do not index elements of the full state xc unless you know it is the continuous state of a LeafSystem (a LeafSystem looking at its own Context can depend on that).

Any of the groups may be empty. However, groups q and v must be either both present or both empty, because the time derivative qdot of the second-order state variables q must be computable using a linear mapping qdot=N(q)*v.

The time derivative xcdot has the identical substructure to xc, with the partitions interpreted as qdot, vdot, and zdot. We use identical ContinuousState objects for both.

Memory ownership

When a ContinuousState represents the state of a LeafSystem, it always owns the memory that is used for the state variables and is responsible for destruction. For a Diagram, ContinuousState can instead be a view of the underlying LeafSystem substates, so that modifying the Diagram’s continuous state affects the LeafSystems appropriately. In that case, the memory is owned by the underlying LeafSystems. However, when a ContinuousState object of any structure is cloned, the resulting object always owns all its underlying memory, which is initialized with a copy of the original state variable values but is otherwise independent. The cloned object retains the structure and ordering of the elements and does not guarantee contiguous storage.

See also

DiagramContinuousState for more information.

Note

This class is templated; see ContinuousState_ for the list of instantiations.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.ContinuousState, state: pydrake.systems.framework.VectorBase) -> None

Constructs a ContinuousState for a system that does not have second-order structure. The q and v partitions are empty; all of the state xc is miscellaneous continuous state z.

2. __init__(self: pydrake.systems.framework.ContinuousState, state: pydrake.systems.framework.VectorBase, num_q: int, num_v: int, num_z: int) -> None

Constructs a ContinuousState that exposes second-order structure.

Parameter state:

The source xc of continuous state information.

Parameter num_q:

The number of position variables q.

Parameter num_v:

The number of velocity variables v.

Parameter num_z:

The number of other continuous variables z.

We require that num_q ≥ num_v and that the sum of the partition sizes adds up to the size of state.

3. __init__(self: pydrake.systems.framework.ContinuousState) -> None

Constructs a zero-length ContinuousState.

Clone(self: pydrake.systems.framework.ContinuousState) → pydrake.systems.framework.ContinuousState

CopyToVector(self: pydrake.systems.framework.ContinuousState) → numpy.ndarray[numpy.float64[m, 1]]

Returns a copy of the entire continuous state vector into an Eigen vector.

get_generalized_position(self: pydrake.systems.framework.ContinuousState) → pydrake.systems.framework.VectorBase

Returns a const reference to the subset of the state vector that is generalized position q. May be zero length.

get_generalized_velocity(self: pydrake.systems.framework.ContinuousState) → pydrake.systems.framework.VectorBase

Returns a const reference to the subset of the continuous state vector that is generalized velocity v. May be zero length.

get_misc_continuous_state(self: pydrake.systems.framework.ContinuousState) → pydrake.systems.framework.VectorBase

Returns a const reference to the subset of the continuous state vector that is other continuous state z. May be zero length.

get_mutable_generalized_position(self: pydrake.systems.framework.ContinuousState) → pydrake.systems.framework.VectorBase

Returns a mutable reference to the subset of the state vector that is generalized position q. May be zero length.

get_mutable_generalized_velocity(self: pydrake.systems.framework.ContinuousState) → pydrake.systems.framework.VectorBase

Returns a mutable reference to the subset of the continuous state vector that is generalized velocity v. May be zero length.

get_mutable_misc_continuous_state(self: pydrake.systems.framework.ContinuousState) → pydrake.systems.framework.VectorBase

Returns a mutable reference to the subset of the continuous state vector that is other continuous state z. May be zero length.

get_mutable_vector(self: pydrake.systems.framework.ContinuousState) → pydrake.systems.framework.VectorBase

Returns a mutable reference to the entire continuous state vector.

get_vector(self: pydrake.systems.framework.ContinuousState) → pydrake.systems.framework.VectorBase

Returns a reference to the entire continuous state vector.

num_q(self: pydrake.systems.framework.ContinuousState) → int

Returns the number of generalized positions q in this state vector.

num_v(self: pydrake.systems.framework.ContinuousState) → int

Returns the number of generalized velocities v in this state vector.

num_z(self: pydrake.systems.framework.ContinuousState) → int

Returns the number of miscellaneous continuous state variables z in this state vector.

SetFrom(self: pydrake.systems.framework.ContinuousState, arg0: pydrake.systems.framework.ContinuousState) → None

Copies the values from other into this, converting the scalar type as necessary.

SetFromVector(self: pydrake.systems.framework.ContinuousState, value: numpy.ndarray[numpy.float64[m, 1]]) → None

Sets the entire continuous state vector from an Eigen expression.

size(self: pydrake.systems.framework.ContinuousState) → int

Returns the size of the entire continuous state vector, which is necessarily num_q + num_v + num_z.

template pydrake.systems.framework.ContinuousState_

Instantiations: ContinuousState_[float], ContinuousState_[AutoDiffXd], ContinuousState_[Expression]

class pydrake.systems.framework.ContinuousState_[AutoDiffXd]

%ContinuousState is a view of, and optionally a container for, all the continuous state variables xc of a Drake System. Continuous state variables are those whose values are defined by differential equations, so we expect there to be a well-defined time derivative xcdot ≜ d/dt xc.

The contents of xc are conceptually partitioned into three groups:

• q is generalized position

• v is generalized velocity

• z is other continuous state

For a Drake LeafSystem these partitions are stored contiguously in memory in this sequence: xc=[q v z]. But because a Drake System may be a Diagram composed from subsystems, each with its own continuous state variables (“substates”), the composite continuous state will not generally be stored in contiguous memory. In that case the most we can say is that xc={q,v,z}, that is, it consists of all the q’s, v’s, and z’s, in some order.

Nevertheless, this ContinuousState class provides a vector view of the data that groups together all the q partitions, v partitions, and z partitions. For example, if there are three subsystems (possibly Diagrams) whose continuous state variables are respectively xc₁={q₁,v₁,z₁}, xc₂={q₂,v₂,z₂}, and xc₃={q₃,v₃,z₃} the composite xc includes all the partitions in an undefined order. However, composite q, v, and z appear ordered as q=[q₁ q₂ q₃], v=[v₁ v₂ v₃], z=[z₁ z₂ z₃]. Note that the element ordering of the composite xc is not a concatenation of the composite subgroups. Do not index elements of the full state xc unless you know it is the continuous state of a LeafSystem (a LeafSystem looking at its own Context can depend on that).

Any of the groups may be empty. However, groups q and v must be either both present or both empty, because the time derivative qdot of the second-order state variables q must be computable using a linear mapping qdot=N(q)*v.

The time derivative xcdot has the identical substructure to xc, with the partitions interpreted as qdot, vdot, and zdot. We use identical ContinuousState objects for both.

Memory ownership

When a ContinuousState represents the state of a LeafSystem, it always owns the memory that is used for the state variables and is responsible for destruction. For a Diagram, ContinuousState can instead be a view of the underlying LeafSystem substates, so that modifying the Diagram’s continuous state affects the LeafSystems appropriately. In that case, the memory is owned by the underlying LeafSystems. However, when a ContinuousState object of any structure is cloned, the resulting object always owns all its underlying memory, which is initialized with a copy of the original state variable values but is otherwise independent. The cloned object retains the structure and ordering of the elements and does not guarantee contiguous storage.

See also

DiagramContinuousState for more information.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.ContinuousState_[AutoDiffXd], state: pydrake.systems.framework.VectorBase_[AutoDiffXd]) -> None

Constructs a ContinuousState for a system that does not have second-order structure. The q and v partitions are empty; all of the state xc is miscellaneous continuous state z.

2. __init__(self: pydrake.systems.framework.ContinuousState_[AutoDiffXd], state: pydrake.systems.framework.VectorBase_[AutoDiffXd], num_q: int, num_v: int, num_z: int) -> None

Constructs a ContinuousState that exposes second-order structure.

Parameter state:

The source xc of continuous state information.

Parameter num_q:

The number of position variables q.

Parameter num_v:

The number of velocity variables v.

Parameter num_z:

The number of other continuous variables z.

We require that num_q ≥ num_v and that the sum of the partition sizes adds up to the size of state.

3. __init__(self: pydrake.systems.framework.ContinuousState_[AutoDiffXd]) -> None

Constructs a zero-length ContinuousState.

Clone(self: pydrake.systems.framework.ContinuousState_[AutoDiffXd]) → pydrake.systems.framework.ContinuousState_[AutoDiffXd]

CopyToVector(self: pydrake.systems.framework.ContinuousState_[AutoDiffXd]) → numpy.ndarray[object[m, 1]]

Returns a copy of the entire continuous state vector into an Eigen vector.

get_generalized_position(self: pydrake.systems.framework.ContinuousState_[AutoDiffXd]) → pydrake.systems.framework.VectorBase_[AutoDiffXd]

Returns a const reference to the subset of the state vector that is generalized position q. May be zero length.

get_generalized_velocity(self: pydrake.systems.framework.ContinuousState_[AutoDiffXd]) → pydrake.systems.framework.VectorBase_[AutoDiffXd]

Returns a const reference to the subset of the continuous state vector that is generalized velocity v. May be zero length.

get_misc_continuous_state(self: pydrake.systems.framework.ContinuousState_[AutoDiffXd]) → pydrake.systems.framework.VectorBase_[AutoDiffXd]

Returns a const reference to the subset of the continuous state vector that is other continuous state z. May be zero length.

get_mutable_generalized_position(self: pydrake.systems.framework.ContinuousState_[AutoDiffXd]) → pydrake.systems.framework.VectorBase_[AutoDiffXd]

Returns a mutable reference to the subset of the state vector that is generalized position q. May be zero length.

get_mutable_generalized_velocity(self: pydrake.systems.framework.ContinuousState_[AutoDiffXd]) → pydrake.systems.framework.VectorBase_[AutoDiffXd]

Returns a mutable reference to the subset of the continuous state vector that is generalized velocity v. May be zero length.

get_mutable_misc_continuous_state(self: pydrake.systems.framework.ContinuousState_[AutoDiffXd]) → pydrake.systems.framework.VectorBase_[AutoDiffXd]

Returns a mutable reference to the subset of the continuous state vector that is other continuous state z. May be zero length.

get_mutable_vector(self: pydrake.systems.framework.ContinuousState_[AutoDiffXd]) → pydrake.systems.framework.VectorBase_[AutoDiffXd]

Returns a mutable reference to the entire continuous state vector.

get_vector(self: pydrake.systems.framework.ContinuousState_[AutoDiffXd]) → pydrake.systems.framework.VectorBase_[AutoDiffXd]

Returns a reference to the entire continuous state vector.

num_q(self: pydrake.systems.framework.ContinuousState_[AutoDiffXd]) → int

Returns the number of generalized positions q in this state vector.

num_v(self: pydrake.systems.framework.ContinuousState_[AutoDiffXd]) → int

Returns the number of generalized velocities v in this state vector.

num_z(self: pydrake.systems.framework.ContinuousState_[AutoDiffXd]) → int

Returns the number of miscellaneous continuous state variables z in this state vector.

SetFrom(self: pydrake.systems.framework.ContinuousState_[AutoDiffXd], arg0: pydrake.systems.framework.ContinuousState) → None

Copies the values from other into this, converting the scalar type as necessary.

SetFromVector(self: pydrake.systems.framework.ContinuousState_[AutoDiffXd], value: numpy.ndarray[object[m, 1]]) → None

Sets the entire continuous state vector from an Eigen expression.

size(self: pydrake.systems.framework.ContinuousState_[AutoDiffXd]) → int

Returns the size of the entire continuous state vector, which is necessarily num_q + num_v + num_z.

class pydrake.systems.framework.ContinuousState_[Expression]

%ContinuousState is a view of, and optionally a container for, all the continuous state variables xc of a Drake System. Continuous state variables are those whose values are defined by differential equations, so we expect there to be a well-defined time derivative xcdot ≜ d/dt xc.

The contents of xc are conceptually partitioned into three groups:

• q is generalized position

• v is generalized velocity

• z is other continuous state

For a Drake LeafSystem these partitions are stored contiguously in memory in this sequence: xc=[q v z]. But because a Drake System may be a Diagram composed from subsystems, each with its own continuous state variables (“substates”), the composite continuous state will not generally be stored in contiguous memory. In that case the most we can say is that xc={q,v,z}, that is, it consists of all the q’s, v’s, and z’s, in some order.

Nevertheless, this ContinuousState class provides a vector view of the data that groups together all the q partitions, v partitions, and z partitions. For example, if there are three subsystems (possibly Diagrams) whose continuous state variables are respectively xc₁={q₁,v₁,z₁}, xc₂={q₂,v₂,z₂}, and xc₃={q₃,v₃,z₃} the composite xc includes all the partitions in an undefined order. However, composite q, v, and z appear ordered as q=[q₁ q₂ q₃], v=[v₁ v₂ v₃], z=[z₁ z₂ z₃]. Note that the element ordering of the composite xc is not a concatenation of the composite subgroups. Do not index elements of the full state xc unless you know it is the continuous state of a LeafSystem (a LeafSystem looking at its own Context can depend on that).

Any of the groups may be empty. However, groups q and v must be either both present or both empty, because the time derivative qdot of the second-order state variables q must be computable using a linear mapping qdot=N(q)*v.

The time derivative xcdot has the identical substructure to xc, with the partitions interpreted as qdot, vdot, and zdot. We use identical ContinuousState objects for both.

Memory ownership

When a ContinuousState represents the state of a LeafSystem, it always owns the memory that is used for the state variables and is responsible for destruction. For a Diagram, ContinuousState can instead be a view of the underlying LeafSystem substates, so that modifying the Diagram’s continuous state affects the LeafSystems appropriately. In that case, the memory is owned by the underlying LeafSystems. However, when a ContinuousState object of any structure is cloned, the resulting object always owns all its underlying memory, which is initialized with a copy of the original state variable values but is otherwise independent. The cloned object retains the structure and ordering of the elements and does not guarantee contiguous storage.

See also

DiagramContinuousState for more information.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.ContinuousState_[Expression], state: pydrake.systems.framework.VectorBase_[Expression]) -> None

Constructs a ContinuousState for a system that does not have second-order structure. The q and v partitions are empty; all of the state xc is miscellaneous continuous state z.

2. __init__(self: pydrake.systems.framework.ContinuousState_[Expression], state: pydrake.systems.framework.VectorBase_[Expression], num_q: int, num_v: int, num_z: int) -> None

Constructs a ContinuousState that exposes second-order structure.

Parameter state:

The source xc of continuous state information.

Parameter num_q:

The number of position variables q.

Parameter num_v:

The number of velocity variables v.

Parameter num_z:

The number of other continuous variables z.

We require that num_q ≥ num_v and that the sum of the partition sizes adds up to the size of state.

3. __init__(self: pydrake.systems.framework.ContinuousState_[Expression]) -> None

Constructs a zero-length ContinuousState.

Clone(self: pydrake.systems.framework.ContinuousState_[Expression]) → pydrake.systems.framework.ContinuousState_[Expression]

CopyToVector(self: pydrake.systems.framework.ContinuousState_[Expression]) → numpy.ndarray[object[m, 1]]

Returns a copy of the entire continuous state vector into an Eigen vector.

get_generalized_position(self: pydrake.systems.framework.ContinuousState_[Expression]) → pydrake.systems.framework.VectorBase_[Expression]

Returns a const reference to the subset of the state vector that is generalized position q. May be zero length.

get_generalized_velocity(self: pydrake.systems.framework.ContinuousState_[Expression]) → pydrake.systems.framework.VectorBase_[Expression]

Returns a const reference to the subset of the continuous state vector that is generalized velocity v. May be zero length.

get_misc_continuous_state(self: pydrake.systems.framework.ContinuousState_[Expression]) → pydrake.systems.framework.VectorBase_[Expression]

Returns a const reference to the subset of the continuous state vector that is other continuous state z. May be zero length.

get_mutable_generalized_position(self: pydrake.systems.framework.ContinuousState_[Expression]) → pydrake.systems.framework.VectorBase_[Expression]

Returns a mutable reference to the subset of the state vector that is generalized position q. May be zero length.

get_mutable_generalized_velocity(self: pydrake.systems.framework.ContinuousState_[Expression]) → pydrake.systems.framework.VectorBase_[Expression]

Returns a mutable reference to the subset of the continuous state vector that is generalized velocity v. May be zero length.

get_mutable_misc_continuous_state(self: pydrake.systems.framework.ContinuousState_[Expression]) → pydrake.systems.framework.VectorBase_[Expression]

Returns a mutable reference to the subset of the continuous state vector that is other continuous state z. May be zero length.

get_mutable_vector(self: pydrake.systems.framework.ContinuousState_[Expression]) → pydrake.systems.framework.VectorBase_[Expression]

Returns a mutable reference to the entire continuous state vector.

get_vector(self: pydrake.systems.framework.ContinuousState_[Expression]) → pydrake.systems.framework.VectorBase_[Expression]

Returns a reference to the entire continuous state vector.

num_q(self: pydrake.systems.framework.ContinuousState_[Expression]) → int

Returns the number of generalized positions q in this state vector.

num_v(self: pydrake.systems.framework.ContinuousState_[Expression]) → int

Returns the number of generalized velocities v in this state vector.

num_z(self: pydrake.systems.framework.ContinuousState_[Expression]) → int

Returns the number of miscellaneous continuous state variables z in this state vector.

SetFrom(self: pydrake.systems.framework.ContinuousState_[Expression], arg0: pydrake.systems.framework.ContinuousState) → None

Copies the values from other into this, converting the scalar type as necessary.

SetFromVector(self: pydrake.systems.framework.ContinuousState_[Expression], value: numpy.ndarray[object[m, 1]]) → None

Sets the entire continuous state vector from an Eigen expression.

size(self: pydrake.systems.framework.ContinuousState_[Expression]) → int

Returns the size of the entire continuous state vector, which is necessarily num_q + num_v + num_z.

class pydrake.systems.framework.ContinuousStateIndex

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.ContinuousStateIndex) -> None

Default constructor; the result is an invalid index. This only exists to serve applications which require a default constructor.

2. __init__(self: pydrake.systems.framework.ContinuousStateIndex, arg0: int) -> None

Construction from a non-negative int value. The value must lie in the range of [0, 2³¹). Constructor only promises to test validity in Debug build.

is_valid(self: pydrake.systems.framework.ContinuousStateIndex) → bool

Reports if the index is valid–the only operation on an invalid index that doesn’t throw an exception in Debug builds.

class pydrake.systems.framework.DependencyTicket

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.DependencyTicket) -> None

Default constructor; the result is an invalid index. This only exists to serve applications which require a default constructor.

2. __init__(self: pydrake.systems.framework.DependencyTicket, arg0: int) -> None

Construction from a non-negative int value. The value must lie in the range of [0, 2³¹). Constructor only promises to test validity in Debug build.

is_valid(self: pydrake.systems.framework.DependencyTicket) → bool

Reports if the index is valid–the only operation on an invalid index that doesn’t throw an exception in Debug builds.

class pydrake.systems.framework.Diagram

Bases: pydrake.systems.framework.System

Diagram is a System composed of one or more constituent Systems, arranged in a directed graph where the vertices are the constituent Systems themselves, and the edges connect the output of one constituent System to the input of another. To construct a Diagram, use a DiagramBuilder.

Each System in the Diagram must have a unique, non-empty name.

Note

This class is templated; see Diagram_ for the list of instantiations.

__init__(self: pydrake.systems.framework.Diagram) → None

Constructs an uninitialized Diagram. Subclasses that use this constructor are obligated to call DiagramBuilder::BuildInto(this). Provides scalar- type conversion support only if every contained subsystem provides the same support.

connection_map(self: pydrake.systems.framework.Diagram) → dict

Returns a reference to the map of connections between Systems.

get_output_port_locator(self: pydrake.systems.framework.Diagram, port_index: pydrake.systems.framework.OutputPortIndex) → tuple

Returns the “locator” for the subsystem output port that was exported as the port_index output port for the Diagram.

GetInputPortLocators(self: pydrake.systems.framework.Diagram, port_index: pydrake.systems.framework.InputPortIndex) → list

Returns the collection of “locators” for the subsystem input ports that were exported or connected to the port_index input port for the Diagram.

GetMutableSubsystemState(self: pydrake.systems.framework.Diagram, arg0: pydrake.systems.framework.System, arg1: pydrake.systems.framework.Context) → pydrake.systems.framework.State

Retrieves the state for a particular subsystem from the context for the entire diagram. Invalidates all entries in that subsystem’s cache that depend on State. Aborts if subsystem is not actually a subsystem of this diagram.

GetSubsystemByName(self: pydrake.systems.framework.Diagram, name: str) → pydrake.systems.framework.System

Retrieves a const reference to the subsystem with name name returned by get_name().

Raises

RuntimeError if a match cannot be found. –

See also

GetDowncastSubsystemByName()

See also

System<T>::get_name()

GetSystems(self: pydrake.systems.framework.Diagram) → list[pydrake.systems.framework.System]

Returns the list of contained Systems.

HasSubsystemNamed(self: pydrake.systems.framework.Diagram, name: str) → bool

Returns true iff this contains a subsystem with the given name.

See also

GetSubsystemByName()

template pydrake.systems.framework.Diagram_

Instantiations: Diagram_[float], Diagram_[AutoDiffXd], Diagram_[Expression]

class pydrake.systems.framework.Diagram_[AutoDiffXd]

Bases: pydrake.systems.framework.System_[AutoDiffXd]

Diagram is a System composed of one or more constituent Systems, arranged in a directed graph where the vertices are the constituent Systems themselves, and the edges connect the output of one constituent System to the input of another. To construct a Diagram, use a DiagramBuilder.

Each System in the Diagram must have a unique, non-empty name.

__init__(self: pydrake.systems.framework.Diagram_[AutoDiffXd]) → None

Constructs an uninitialized Diagram. Subclasses that use this constructor are obligated to call DiagramBuilder::BuildInto(this). Provides scalar- type conversion support only if every contained subsystem provides the same support.

connection_map(self: pydrake.systems.framework.Diagram_[AutoDiffXd]) → dict

Returns a reference to the map of connections between Systems.

get_output_port_locator(self: pydrake.systems.framework.Diagram_[AutoDiffXd], port_index: pydrake.systems.framework.OutputPortIndex) → tuple

Returns the “locator” for the subsystem output port that was exported as the port_index output port for the Diagram.

GetInputPortLocators(self: pydrake.systems.framework.Diagram_[AutoDiffXd], port_index: pydrake.systems.framework.InputPortIndex) → list

Returns the collection of “locators” for the subsystem input ports that were exported or connected to the port_index input port for the Diagram.

GetMutableSubsystemState(self: pydrake.systems.framework.Diagram_[AutoDiffXd], arg0: pydrake.systems.framework.System_[AutoDiffXd], arg1: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.systems.framework.State_[AutoDiffXd]

Retrieves the state for a particular subsystem from the context for the entire diagram. Invalidates all entries in that subsystem’s cache that depend on State. Aborts if subsystem is not actually a subsystem of this diagram.

GetSubsystemByName(self: pydrake.systems.framework.Diagram_[AutoDiffXd], name: str) → pydrake.systems.framework.System_[AutoDiffXd]

Retrieves a const reference to the subsystem with name name returned by get_name().

Raises

RuntimeError if a match cannot be found. –

See also

GetDowncastSubsystemByName()

See also

System<T>::get_name()

GetSystems(self: pydrake.systems.framework.Diagram_[AutoDiffXd]) → list[pydrake.systems.framework.System_[AutoDiffXd]]

Returns the list of contained Systems.

HasSubsystemNamed(self: pydrake.systems.framework.Diagram_[AutoDiffXd], name: str) → bool

Returns true iff this contains a subsystem with the given name.

See also

GetSubsystemByName()

class pydrake.systems.framework.Diagram_[Expression]

Bases: pydrake.systems.framework.System_[Expression]

Diagram is a System composed of one or more constituent Systems, arranged in a directed graph where the vertices are the constituent Systems themselves, and the edges connect the output of one constituent System to the input of another. To construct a Diagram, use a DiagramBuilder.

Each System in the Diagram must have a unique, non-empty name.

__init__(self: pydrake.systems.framework.Diagram_[Expression]) → None

Constructs an uninitialized Diagram. Subclasses that use this constructor are obligated to call DiagramBuilder::BuildInto(this). Provides scalar- type conversion support only if every contained subsystem provides the same support.

connection_map(self: pydrake.systems.framework.Diagram_[Expression]) → dict

Returns a reference to the map of connections between Systems.

get_output_port_locator(self: pydrake.systems.framework.Diagram_[Expression], port_index: pydrake.systems.framework.OutputPortIndex) → tuple

Returns the “locator” for the subsystem output port that was exported as the port_index output port for the Diagram.

GetInputPortLocators(self: pydrake.systems.framework.Diagram_[Expression], port_index: pydrake.systems.framework.InputPortIndex) → list

Returns the collection of “locators” for the subsystem input ports that were exported or connected to the port_index input port for the Diagram.

GetMutableSubsystemState(self: pydrake.systems.framework.Diagram_[Expression], arg0: pydrake.systems.framework.System_[Expression], arg1: pydrake.systems.framework.Context_[Expression]) → pydrake.systems.framework.State_[Expression]

Retrieves the state for a particular subsystem from the context for the entire diagram. Invalidates all entries in that subsystem’s cache that depend on State. Aborts if subsystem is not actually a subsystem of this diagram.

GetSubsystemByName(self: pydrake.systems.framework.Diagram_[Expression], name: str) → pydrake.systems.framework.System_[Expression]

Retrieves a const reference to the subsystem with name name returned by get_name().

Raises

RuntimeError if a match cannot be found. –

See also

GetDowncastSubsystemByName()

See also

System<T>::get_name()

GetSystems(self: pydrake.systems.framework.Diagram_[Expression]) → list[pydrake.systems.framework.System_[Expression]]

Returns the list of contained Systems.

HasSubsystemNamed(self: pydrake.systems.framework.Diagram_[Expression], name: str) → bool

Returns true iff this contains a subsystem with the given name.

See also

GetSubsystemByName()

class pydrake.systems.framework.DiagramBuilder

DiagramBuilder is a factory class for Diagram.

It is single use: after calling Build or BuildInto, DiagramBuilder gives up ownership of the constituent systems, and should therefore be discarded; all member functions will throw an exception after this point.

When a Diagram (or DiagramBuilder) that owns systems is destroyed, the systems will be destroyed in the reverse of the order they were added.

A system must be added to the DiagramBuilder with AddSystem or AddNamedSystem before it can be wired up in any way. Every system must have a unique, non-empty name.

When building large Diagrams with many added systems and input-output port connections, the runtime performance of DiagramBuilder::Build() might become relevant.

As part of its correctness checks, the DiagramBuilder::Build() function performs a graph search of the diagram’s dependencies. In the graph, the nodes are the child systems that have been added to the diagram, and the edges are the diagram connections from one child’s output port to another child’s input port(s). The builder must confirm that the graph is acyclic; a cycle would imply an infinite loop in an output calculation function. With a large graph, this check can be computationally expensive. To speed it up, ensure that your output ports do not gratuitously depend on irrelevant input ports.

The dependencies are supplied via the prerequisites_of_calc argument to DeclareOutputPort family of functions. If the default value is used (i.e., when no prerequisites are provided), the default is to assume the output port value is dependent on all possible sources.

Refer to the DeclareLeafOutputPort_feedthrough “Direct feedthrough” documentation for additional details and examples. In particular, the SystemBase::all_sources_except_input_ports_ticket() is a convenient shortcut for outputs that do not depend on any inputs.

Note

This class is templated; see DiagramBuilder_ for the list of instantiations.

__init__(self: pydrake.systems.framework.DiagramBuilder) → None

AddNamedSystem(self: pydrake.systems.framework.DiagramBuilder, name: str, system: pydrake.systems.framework.System) → pydrake.systems.framework.System

Takes ownership of system, applies name to it, and adds it to the builder. Returns a bare pointer to the System, which will remain valid for the lifetime of the Diagram built by this builder.

Click to expand C++ code...

DiagramBuilder<T> builder;
  auto bar = builder.AddNamedSystem("bar", std::make_unique<Bar<T>>());

Template parameter S:

The type of system to add.

Postcondition:

The system’s name is name.

AddSystem(self: pydrake.systems.framework.DiagramBuilder, system: pydrake.systems.framework.System) → pydrake.systems.framework.System

Takes ownership of system and adds it to the builder. Returns a bare pointer to the System, which will remain valid for the lifetime of the Diagram built by this builder.

If the system’s name is unset, sets it to System::GetMemoryObjectName() as a default in order to have unique names within the diagram.

Click to expand C++ code...

DiagramBuilder<T> builder;
  auto foo = builder.AddSystem(std::make_unique<Foo<T>>());

Template parameter S:

The type of system to add.

already_built(self: pydrake.systems.framework.DiagramBuilder) → bool

Returns true iff Build() or BuildInto() has been called on this Builder, in which case it’s an error to call any member function other than the the destructor.

Build(self: pydrake.systems.framework.DiagramBuilder) → pydrake.systems.framework.Diagram

Builds the Diagram that has been described by the calls to Connect, ExportInput, and ExportOutput.

Raises

RuntimeError if the graph is not buildable. –

See DiagramBuilder_feedthrough “Building large Diagrams” for tips on improving runtime performance of this function.

BuildInto(self: pydrake.systems.framework.DiagramBuilder, target: pydrake.systems.framework.Diagram) → None

Configures target to have the topology that has been described by the calls to Connect, ExportInput, and ExportOutput.

Raises

RuntimeError if the graph is not buildable. –

Only Diagram subclasses should call this method. The target must not already be initialized.

Connect(self: pydrake.systems.framework.DiagramBuilder, arg0: pydrake.systems.framework.OutputPort, arg1: pydrake.systems.framework.InputPort) → None

Declares that input port dest is connected to output port src.

Note

The connection created between src and dest via a call to this method can be effectively overridden by any subsequent call to InputPort::FixValue(). That is, calling InputPort::FixValue() on an already connected input port causes the resultant FixedInputPortValue to override any other value present on that port.

ConnectInput(*args, **kwargs)

Overloaded function.

1. ConnectInput(self: pydrake.systems.framework.DiagramBuilder, diagram_port_name: str, input: pydrake.systems.framework.InputPort) -> None

Connects an input to the entire Diagram, indicated by diagram_port_name, to the given input port of a constituent system.

Precondition:

The Diagram input indicated by diagram_port_name must have been previously built via ExportInput().

Postcondition:

input is connected to the indicated Diagram input port.

2. ConnectInput(self: pydrake.systems.framework.DiagramBuilder, diagram_port_index: pydrake.systems.framework.InputPortIndex, input: pydrake.systems.framework.InputPort) -> None

Connects an input to the entire Diagram, indicated by diagram_port_index, to the given input port of a constituent system.

Precondition:

The Diagram input indicated by diagram_port_index must have been previously built via ExportInput().

Postcondition:

input is connected to the indicated Diagram input port.

connection_map(self: pydrake.systems.framework.DiagramBuilder) → dict

(Advanced) Returns a reference to the map of connections between Systems. The reference becomes invalid upon any call to Build or BuildInto.

ConnectToSame(self: pydrake.systems.framework.DiagramBuilder, exemplar: pydrake.systems.framework.InputPort, dest: pydrake.systems.framework.InputPort) → bool

Connects dest to the same source as exemplar is connected to.

If exemplar was connected to an output port, then dest is connected to that same output. Or, if exemplar was exported as an input of this diagram, then dest will be connected to that same diagram input. Or, if exemplar was neither connected or exported, then this function is a no-op.

Both exemplar and dest must be ports of constituent systems that have already been added to this diagram.

Returns

True iff any connection or was made; or false when a no-op.

empty(self: pydrake.systems.framework.DiagramBuilder) → bool

Returns whether any Systems have been added yet.

ExportInput(self: pydrake.systems.framework.DiagramBuilder, input: pydrake.systems.framework.InputPort, name: Union[str, pydrake.systems.framework.UseDefaultName] = kUseDefaultName) → pydrake.systems.framework.InputPortIndex

Declares that the given input port of a constituent system is connected to a new input to the entire Diagram. name is an optional name for the new input port; if it is unspecified, then a default name will be provided.

Precondition:

If supplied at all, name must not be empty.

Precondition:

A port indicated by the resolution of name must not exist.

Postcondition:

input is connected to the new exported input port.

Returns

The index of the exported input port of the entire diagram.

ExportOutput(self: pydrake.systems.framework.DiagramBuilder, output: pydrake.systems.framework.OutputPort, name: Union[str, pydrake.systems.framework.UseDefaultName] = kUseDefaultName) → pydrake.systems.framework.OutputPortIndex

Declares that the given output port of a constituent system is an output of the entire diagram. name is an optional name for the output port; if it is unspecified, then a default name will be provided.

Precondition:

If supplied at all, name must not be empty.

Returns

The index of the exported output port of the entire diagram.

GetMutableSubsystemByName(self: pydrake.systems.framework.DiagramBuilder, name: str) → pydrake.systems.framework.System

Retrieves a mutable reference to the subsystem with name name returned by get_name().

Raises

RuntimeError if a unique match cannot be found. –

See also

System<T>::get_name()

See also

GetSubsystemByName()

See also

GetMutableDowncastSubsystemByName()

GetMutableSystems(self: pydrake.systems.framework.DiagramBuilder) → list[pydrake.systems.framework.System]

Returns the list of contained Systems.

See also

GetMutableSubsystemByName()

See also

GetSystems()

GetSubsystemByName(self: pydrake.systems.framework.DiagramBuilder, name: str) → pydrake.systems.framework.System

Retrieves a const reference to the subsystem with name name returned by get_name().

Raises

RuntimeError if a unique match cannot be found. –

See also

System<T>::get_name()

See also

GetMutableSubsystemByName()

See also

GetDowncastSubsystemByName()

GetSystems(self: pydrake.systems.framework.DiagramBuilder) → list[pydrake.systems.framework.System]

Returns the list of contained Systems.

See also

GetSubsystemByName()

See also

GetMutableSystems()

HasSubsystemNamed(self: pydrake.systems.framework.DiagramBuilder, name: str) → bool

Returns true iff this contains a subsystem with the given name.

See also

GetSubsystemByName()

IsConnectedOrExported(self: pydrake.systems.framework.DiagramBuilder, port: pydrake.systems.framework.InputPort) → bool

Returns true iff the given input port of a constituent system is either connected to another constituent system or exported as a diagram input.

num_input_ports(self: pydrake.systems.framework.DiagramBuilder) → int

Returns the current number of diagram input ports. The count may change as more ports are exported.

num_output_ports(self: pydrake.systems.framework.DiagramBuilder) → int

Returns the current number of diagram output outputs. The count may change as more ports are exported.

RemoveSystem(self: pydrake.systems.framework.DiagramBuilder, system: pydrake.systems.framework.System) → None

Removes the given system from this builder and disconnects any connections or exported ports associated with it.

Note that un-exporting this system’s ports might have a ripple effect on other exported port index assignments. The relative order will remain intact, but any “holes” created by this removal will be filled in by decrementing the indices of all higher-numbered ports that remain.

Warning

Because a DiagramBuilder owns the objects it contains, the system will be deleted.

template pydrake.systems.framework.DiagramBuilder_

Instantiations: DiagramBuilder_[float], DiagramBuilder_[AutoDiffXd], DiagramBuilder_[Expression]

class pydrake.systems.framework.DiagramBuilder_[AutoDiffXd]

DiagramBuilder is a factory class for Diagram.

It is single use: after calling Build or BuildInto, DiagramBuilder gives up ownership of the constituent systems, and should therefore be discarded; all member functions will throw an exception after this point.

When a Diagram (or DiagramBuilder) that owns systems is destroyed, the systems will be destroyed in the reverse of the order they were added.

A system must be added to the DiagramBuilder with AddSystem or AddNamedSystem before it can be wired up in any way. Every system must have a unique, non-empty name.

When building large Diagrams with many added systems and input-output port connections, the runtime performance of DiagramBuilder::Build() might become relevant.

As part of its correctness checks, the DiagramBuilder::Build() function performs a graph search of the diagram’s dependencies. In the graph, the nodes are the child systems that have been added to the diagram, and the edges are the diagram connections from one child’s output port to another child’s input port(s). The builder must confirm that the graph is acyclic; a cycle would imply an infinite loop in an output calculation function. With a large graph, this check can be computationally expensive. To speed it up, ensure that your output ports do not gratuitously depend on irrelevant input ports.

The dependencies are supplied via the prerequisites_of_calc argument to DeclareOutputPort family of functions. If the default value is used (i.e., when no prerequisites are provided), the default is to assume the output port value is dependent on all possible sources.

Refer to the DeclareLeafOutputPort_feedthrough “Direct feedthrough” documentation for additional details and examples. In particular, the SystemBase::all_sources_except_input_ports_ticket() is a convenient shortcut for outputs that do not depend on any inputs.

__init__(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd]) → None

AddNamedSystem(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd], name: str, system: pydrake.systems.framework.System_[AutoDiffXd]) → pydrake.systems.framework.System_[AutoDiffXd]

Takes ownership of system, applies name to it, and adds it to the builder. Returns a bare pointer to the System, which will remain valid for the lifetime of the Diagram built by this builder.

Click to expand C++ code...

DiagramBuilder<T> builder;
  auto bar = builder.AddNamedSystem("bar", std::make_unique<Bar<T>>());

Template parameter S:

The type of system to add.

Postcondition:

The system’s name is name.

AddSystem(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd], system: pydrake.systems.framework.System_[AutoDiffXd]) → pydrake.systems.framework.System_[AutoDiffXd]

Takes ownership of system and adds it to the builder. Returns a bare pointer to the System, which will remain valid for the lifetime of the Diagram built by this builder.

If the system’s name is unset, sets it to System::GetMemoryObjectName() as a default in order to have unique names within the diagram.

Click to expand C++ code...

DiagramBuilder<T> builder;
  auto foo = builder.AddSystem(std::make_unique<Foo<T>>());

Template parameter S:

The type of system to add.

already_built(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd]) → bool

Returns true iff Build() or BuildInto() has been called on this Builder, in which case it’s an error to call any member function other than the the destructor.

Build(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd]) → pydrake.systems.framework.Diagram_[AutoDiffXd]

Builds the Diagram that has been described by the calls to Connect, ExportInput, and ExportOutput.

Raises

RuntimeError if the graph is not buildable. –

See DiagramBuilder_feedthrough “Building large Diagrams” for tips on improving runtime performance of this function.

BuildInto(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd], target: pydrake.systems.framework.Diagram_[AutoDiffXd]) → None

Configures target to have the topology that has been described by the calls to Connect, ExportInput, and ExportOutput.

Raises

RuntimeError if the graph is not buildable. –

Only Diagram subclasses should call this method. The target must not already be initialized.

Connect(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd], arg0: pydrake.systems.framework.OutputPort_[AutoDiffXd], arg1: pydrake.systems.framework.InputPort_[AutoDiffXd]) → None

Declares that input port dest is connected to output port src.

Note

The connection created between src and dest via a call to this method can be effectively overridden by any subsequent call to InputPort::FixValue(). That is, calling InputPort::FixValue() on an already connected input port causes the resultant FixedInputPortValue to override any other value present on that port.

ConnectInput(*args, **kwargs)

Overloaded function.

1. ConnectInput(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd], diagram_port_name: str, input: pydrake.systems.framework.InputPort_[AutoDiffXd]) -> None

Connects an input to the entire Diagram, indicated by diagram_port_name, to the given input port of a constituent system.

Precondition:

The Diagram input indicated by diagram_port_name must have been previously built via ExportInput().

Postcondition:

input is connected to the indicated Diagram input port.

2. ConnectInput(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd], diagram_port_index: pydrake.systems.framework.InputPortIndex, input: pydrake.systems.framework.InputPort_[AutoDiffXd]) -> None

Connects an input to the entire Diagram, indicated by diagram_port_index, to the given input port of a constituent system.

Precondition:

The Diagram input indicated by diagram_port_index must have been previously built via ExportInput().

Postcondition:

input is connected to the indicated Diagram input port.

connection_map(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd]) → dict

(Advanced) Returns a reference to the map of connections between Systems. The reference becomes invalid upon any call to Build or BuildInto.

ConnectToSame(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd], exemplar: pydrake.systems.framework.InputPort_[AutoDiffXd], dest: pydrake.systems.framework.InputPort_[AutoDiffXd]) → bool

Connects dest to the same source as exemplar is connected to.

If exemplar was connected to an output port, then dest is connected to that same output. Or, if exemplar was exported as an input of this diagram, then dest will be connected to that same diagram input. Or, if exemplar was neither connected or exported, then this function is a no-op.

Both exemplar and dest must be ports of constituent systems that have already been added to this diagram.

Returns

True iff any connection or was made; or false when a no-op.

empty(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd]) → bool

Returns whether any Systems have been added yet.

ExportInput(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd], input: pydrake.systems.framework.InputPort_[AutoDiffXd], name: Union[str, pydrake.systems.framework.UseDefaultName] = kUseDefaultName) → pydrake.systems.framework.InputPortIndex

Declares that the given input port of a constituent system is connected to a new input to the entire Diagram. name is an optional name for the new input port; if it is unspecified, then a default name will be provided.

Precondition:

If supplied at all, name must not be empty.

Precondition:

A port indicated by the resolution of name must not exist.

Postcondition:

input is connected to the new exported input port.

Returns

The index of the exported input port of the entire diagram.

ExportOutput(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd], output: pydrake.systems.framework.OutputPort_[AutoDiffXd], name: Union[str, pydrake.systems.framework.UseDefaultName] = kUseDefaultName) → pydrake.systems.framework.OutputPortIndex

Declares that the given output port of a constituent system is an output of the entire diagram. name is an optional name for the output port; if it is unspecified, then a default name will be provided.

Precondition:

If supplied at all, name must not be empty.

Returns

The index of the exported output port of the entire diagram.

GetMutableSubsystemByName(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd], name: str) → pydrake.systems.framework.System_[AutoDiffXd]

Retrieves a mutable reference to the subsystem with name name returned by get_name().

Raises

RuntimeError if a unique match cannot be found. –

See also

System<T>::get_name()

See also

GetSubsystemByName()

See also

GetMutableDowncastSubsystemByName()

GetMutableSystems(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd]) → list[pydrake.systems.framework.System_[AutoDiffXd]]

Returns the list of contained Systems.

See also

GetMutableSubsystemByName()

See also

GetSystems()

GetSubsystemByName(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd], name: str) → pydrake.systems.framework.System_[AutoDiffXd]

Retrieves a const reference to the subsystem with name name returned by get_name().

Raises

RuntimeError if a unique match cannot be found. –

See also

System<T>::get_name()

See also

GetMutableSubsystemByName()

See also

GetDowncastSubsystemByName()

GetSystems(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd]) → list[pydrake.systems.framework.System_[AutoDiffXd]]

Returns the list of contained Systems.

See also

GetSubsystemByName()

See also

GetMutableSystems()

HasSubsystemNamed(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd], name: str) → bool

Returns true iff this contains a subsystem with the given name.

See also

GetSubsystemByName()

IsConnectedOrExported(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd], port: pydrake.systems.framework.InputPort_[AutoDiffXd]) → bool

Returns true iff the given input port of a constituent system is either connected to another constituent system or exported as a diagram input.

num_input_ports(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd]) → int

Returns the current number of diagram input ports. The count may change as more ports are exported.

num_output_ports(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd]) → int

Returns the current number of diagram output outputs. The count may change as more ports are exported.

RemoveSystem(self: pydrake.systems.framework.DiagramBuilder_[AutoDiffXd], system: pydrake.systems.framework.System_[AutoDiffXd]) → None

Removes the given system from this builder and disconnects any connections or exported ports associated with it.

Note that un-exporting this system’s ports might have a ripple effect on other exported port index assignments. The relative order will remain intact, but any “holes” created by this removal will be filled in by decrementing the indices of all higher-numbered ports that remain.

Warning

Because a DiagramBuilder owns the objects it contains, the system will be deleted.

class pydrake.systems.framework.DiagramBuilder_[Expression]

DiagramBuilder is a factory class for Diagram.

It is single use: after calling Build or BuildInto, DiagramBuilder gives up ownership of the constituent systems, and should therefore be discarded; all member functions will throw an exception after this point.

When a Diagram (or DiagramBuilder) that owns systems is destroyed, the systems will be destroyed in the reverse of the order they were added.

A system must be added to the DiagramBuilder with AddSystem or AddNamedSystem before it can be wired up in any way. Every system must have a unique, non-empty name.

When building large Diagrams with many added systems and input-output port connections, the runtime performance of DiagramBuilder::Build() might become relevant.

As part of its correctness checks, the DiagramBuilder::Build() function performs a graph search of the diagram’s dependencies. In the graph, the nodes are the child systems that have been added to the diagram, and the edges are the diagram connections from one child’s output port to another child’s input port(s). The builder must confirm that the graph is acyclic; a cycle would imply an infinite loop in an output calculation function. With a large graph, this check can be computationally expensive. To speed it up, ensure that your output ports do not gratuitously depend on irrelevant input ports.

The dependencies are supplied via the prerequisites_of_calc argument to DeclareOutputPort family of functions. If the default value is used (i.e., when no prerequisites are provided), the default is to assume the output port value is dependent on all possible sources.

Refer to the DeclareLeafOutputPort_feedthrough “Direct feedthrough” documentation for additional details and examples. In particular, the SystemBase::all_sources_except_input_ports_ticket() is a convenient shortcut for outputs that do not depend on any inputs.

__init__(self: pydrake.systems.framework.DiagramBuilder_[Expression]) → None

AddNamedSystem(self: pydrake.systems.framework.DiagramBuilder_[Expression], name: str, system: pydrake.systems.framework.System_[Expression]) → pydrake.systems.framework.System_[Expression]

Takes ownership of system, applies name to it, and adds it to the builder. Returns a bare pointer to the System, which will remain valid for the lifetime of the Diagram built by this builder.

Click to expand C++ code...

DiagramBuilder<T> builder;
  auto bar = builder.AddNamedSystem("bar", std::make_unique<Bar<T>>());

Template parameter S:

The type of system to add.

Postcondition:

The system’s name is name.

AddSystem(self: pydrake.systems.framework.DiagramBuilder_[Expression], system: pydrake.systems.framework.System_[Expression]) → pydrake.systems.framework.System_[Expression]

Takes ownership of system and adds it to the builder. Returns a bare pointer to the System, which will remain valid for the lifetime of the Diagram built by this builder.

If the system’s name is unset, sets it to System::GetMemoryObjectName() as a default in order to have unique names within the diagram.

Click to expand C++ code...

DiagramBuilder<T> builder;
  auto foo = builder.AddSystem(std::make_unique<Foo<T>>());

Template parameter S:

The type of system to add.

already_built(self: pydrake.systems.framework.DiagramBuilder_[Expression]) → bool

Returns true iff Build() or BuildInto() has been called on this Builder, in which case it’s an error to call any member function other than the the destructor.

Build(self: pydrake.systems.framework.DiagramBuilder_[Expression]) → pydrake.systems.framework.Diagram_[Expression]

Builds the Diagram that has been described by the calls to Connect, ExportInput, and ExportOutput.

Raises

RuntimeError if the graph is not buildable. –

See DiagramBuilder_feedthrough “Building large Diagrams” for tips on improving runtime performance of this function.

BuildInto(self: pydrake.systems.framework.DiagramBuilder_[Expression], target: pydrake.systems.framework.Diagram_[Expression]) → None

Configures target to have the topology that has been described by the calls to Connect, ExportInput, and ExportOutput.

Raises

RuntimeError if the graph is not buildable. –

Only Diagram subclasses should call this method. The target must not already be initialized.

Connect(self: pydrake.systems.framework.DiagramBuilder_[Expression], arg0: pydrake.systems.framework.OutputPort_[Expression], arg1: pydrake.systems.framework.InputPort_[Expression]) → None

Declares that input port dest is connected to output port src.

Note

The connection created between src and dest via a call to this method can be effectively overridden by any subsequent call to InputPort::FixValue(). That is, calling InputPort::FixValue() on an already connected input port causes the resultant FixedInputPortValue to override any other value present on that port.

ConnectInput(*args, **kwargs)

Overloaded function.

1. ConnectInput(self: pydrake.systems.framework.DiagramBuilder_[Expression], diagram_port_name: str, input: pydrake.systems.framework.InputPort_[Expression]) -> None

Connects an input to the entire Diagram, indicated by diagram_port_name, to the given input port of a constituent system.

Precondition:

The Diagram input indicated by diagram_port_name must have been previously built via ExportInput().

Postcondition:

input is connected to the indicated Diagram input port.

2. ConnectInput(self: pydrake.systems.framework.DiagramBuilder_[Expression], diagram_port_index: pydrake.systems.framework.InputPortIndex, input: pydrake.systems.framework.InputPort_[Expression]) -> None

Connects an input to the entire Diagram, indicated by diagram_port_index, to the given input port of a constituent system.

Precondition:

The Diagram input indicated by diagram_port_index must have been previously built via ExportInput().

Postcondition:

input is connected to the indicated Diagram input port.

connection_map(self: pydrake.systems.framework.DiagramBuilder_[Expression]) → dict

(Advanced) Returns a reference to the map of connections between Systems. The reference becomes invalid upon any call to Build or BuildInto.

ConnectToSame(self: pydrake.systems.framework.DiagramBuilder_[Expression], exemplar: pydrake.systems.framework.InputPort_[Expression], dest: pydrake.systems.framework.InputPort_[Expression]) → bool

Connects dest to the same source as exemplar is connected to.

If exemplar was connected to an output port, then dest is connected to that same output. Or, if exemplar was exported as an input of this diagram, then dest will be connected to that same diagram input. Or, if exemplar was neither connected or exported, then this function is a no-op.

Both exemplar and dest must be ports of constituent systems that have already been added to this diagram.

Returns

True iff any connection or was made; or false when a no-op.

empty(self: pydrake.systems.framework.DiagramBuilder_[Expression]) → bool

Returns whether any Systems have been added yet.

ExportInput(self: pydrake.systems.framework.DiagramBuilder_[Expression], input: pydrake.systems.framework.InputPort_[Expression], name: Union[str, pydrake.systems.framework.UseDefaultName] = kUseDefaultName) → pydrake.systems.framework.InputPortIndex

Declares that the given input port of a constituent system is connected to a new input to the entire Diagram. name is an optional name for the new input port; if it is unspecified, then a default name will be provided.

Precondition:

If supplied at all, name must not be empty.

Precondition:

A port indicated by the resolution of name must not exist.

Postcondition:

input is connected to the new exported input port.

Returns

The index of the exported input port of the entire diagram.

ExportOutput(self: pydrake.systems.framework.DiagramBuilder_[Expression], output: pydrake.systems.framework.OutputPort_[Expression], name: Union[str, pydrake.systems.framework.UseDefaultName] = kUseDefaultName) → pydrake.systems.framework.OutputPortIndex

Declares that the given output port of a constituent system is an output of the entire diagram. name is an optional name for the output port; if it is unspecified, then a default name will be provided.

Precondition:

If supplied at all, name must not be empty.

Returns

The index of the exported output port of the entire diagram.

GetMutableSubsystemByName(self: pydrake.systems.framework.DiagramBuilder_[Expression], name: str) → pydrake.systems.framework.System_[Expression]

Retrieves a mutable reference to the subsystem with name name returned by get_name().

Raises

RuntimeError if a unique match cannot be found. –

See also

System<T>::get_name()

See also

GetSubsystemByName()

See also

GetMutableDowncastSubsystemByName()

GetMutableSystems(self: pydrake.systems.framework.DiagramBuilder_[Expression]) → list[pydrake.systems.framework.System_[Expression]]

Returns the list of contained Systems.

See also

GetMutableSubsystemByName()

See also

GetSystems()

GetSubsystemByName(self: pydrake.systems.framework.DiagramBuilder_[Expression], name: str) → pydrake.systems.framework.System_[Expression]

Retrieves a const reference to the subsystem with name name returned by get_name().

Raises

RuntimeError if a unique match cannot be found. –

See also

System<T>::get_name()

See also

GetMutableSubsystemByName()

See also

GetDowncastSubsystemByName()

GetSystems(self: pydrake.systems.framework.DiagramBuilder_[Expression]) → list[pydrake.systems.framework.System_[Expression]]

Returns the list of contained Systems.

See also

GetSubsystemByName()

See also

GetMutableSystems()

HasSubsystemNamed(self: pydrake.systems.framework.DiagramBuilder_[Expression], name: str) → bool

Returns true iff this contains a subsystem with the given name.

See also

GetSubsystemByName()

IsConnectedOrExported(self: pydrake.systems.framework.DiagramBuilder_[Expression], port: pydrake.systems.framework.InputPort_[Expression]) → bool

Returns true iff the given input port of a constituent system is either connected to another constituent system or exported as a diagram input.

num_input_ports(self: pydrake.systems.framework.DiagramBuilder_[Expression]) → int

Returns the current number of diagram input ports. The count may change as more ports are exported.

num_output_ports(self: pydrake.systems.framework.DiagramBuilder_[Expression]) → int

Returns the current number of diagram output outputs. The count may change as more ports are exported.

RemoveSystem(self: pydrake.systems.framework.DiagramBuilder_[Expression], system: pydrake.systems.framework.System_[Expression]) → None

Removes the given system from this builder and disconnects any connections or exported ports associated with it.

Note that un-exporting this system’s ports might have a ripple effect on other exported port index assignments. The relative order will remain intact, but any “holes” created by this removal will be filled in by decrementing the indices of all higher-numbered ports that remain.

Warning

Because a DiagramBuilder owns the objects it contains, the system will be deleted.

class pydrake.systems.framework.DiscreteStateIndex

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.DiscreteStateIndex) -> None

Default constructor; the result is an invalid index. This only exists to serve applications which require a default constructor.

2. __init__(self: pydrake.systems.framework.DiscreteStateIndex, arg0: int) -> None

Construction from a non-negative int value. The value must lie in the range of [0, 2³¹). Constructor only promises to test validity in Debug build.

is_valid(self: pydrake.systems.framework.DiscreteStateIndex) → bool

Reports if the index is valid–the only operation on an invalid index that doesn’t throw an exception in Debug builds.

class pydrake.systems.framework.DiscreteUpdateEvent

Bases: pydrake.systems.framework.Event

This class represents a discrete update event. It has an optional callback function to do custom handling of this event, and that can write updates to a mutable, non-null DiscreteValues object.

See also

LeafSystem for more convenient interfaces to discrete update events via the Declare*DiscreteUpdateEvent() methods.

Note

This class is templated; see DiscreteUpdateEvent_ for the list of instantiations.

__init__(*args, **kwargs)

template pydrake.systems.framework.DiscreteUpdateEvent_

Instantiations: DiscreteUpdateEvent_[float], DiscreteUpdateEvent_[AutoDiffXd], DiscreteUpdateEvent_[Expression]

class pydrake.systems.framework.DiscreteUpdateEvent_[AutoDiffXd]

Bases: pydrake.systems.framework.Event_[AutoDiffXd]

This class represents a discrete update event. It has an optional callback function to do custom handling of this event, and that can write updates to a mutable, non-null DiscreteValues object.

See also

LeafSystem for more convenient interfaces to discrete update events via the Declare*DiscreteUpdateEvent() methods.

__init__(*args, **kwargs)

class pydrake.systems.framework.DiscreteUpdateEvent_[Expression]

Bases: pydrake.systems.framework.Event_[Expression]

This class represents a discrete update event. It has an optional callback function to do custom handling of this event, and that can write updates to a mutable, non-null DiscreteValues object.

See also

LeafSystem for more convenient interfaces to discrete update events via the Declare*DiscreteUpdateEvent() methods.

__init__(*args, **kwargs)

class pydrake.systems.framework.DiscreteValues

%DiscreteValues is a container for numerical but non-continuous state and parameters. It may own its underlying data, for use with leaf Systems, or not, for use with Diagrams.

DiscreteValues is an ordered collection xd of BasicVector “groups” so xd = [xd₀, xd₁…], where each group xdᵢ is a contiguous vector. Requesting a specific group index from this collection is the most granular way to retrieve discrete values from the Context, and thus is the unit of cache invalidation. System authors are encouraged to partition their DiscreteValues such that each cacheable computation within the System may depend on only the elements of DiscreteValues that it needs.

None of the contained vectors (groups) may be null, although any of them may be zero-length.

Note

This class is templated; see DiscreteValues_ for the list of instantiations.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.DiscreteValues, datum: pydrake.systems.framework.BasicVector) -> None

Constructs a one-group DiscreteValues object that owns a single datum vector which may not be null.

2. __init__(self: pydrake.systems.framework.DiscreteValues, data: list[pydrake.systems.framework.BasicVector]) -> None

Constructs a DiscreteValues that owns the underlying data. Every entry must be non-null.

3. __init__(self: pydrake.systems.framework.DiscreteValues) -> None

Constructs an empty DiscreteValues object containing no groups.

Clone(self: pydrake.systems.framework.DiscreteValues) → pydrake.systems.framework.DiscreteValues

get_data(self: pydrake.systems.framework.DiscreteValues) → list[pydrake.systems.framework.BasicVector]

get_mutable_value(self: pydrake.systems.framework.DiscreteValues, index: int = 0) → numpy.ndarray[numpy.float64[m, 1], flags.writeable]

Returns the entire vector for the indicated group as a mutable Eigen::VectorBlock, which allows mutation of the values, but does not allow resize() to be called on the vector.

get_mutable_vector(self: pydrake.systems.framework.DiscreteValues, index: int = 0) → pydrake.systems.framework.BasicVector

(Advanced) Returns a mutable reference to the BasicVector holding data for the indicated group. Prefer get_mutable_value() to get the underlying Eigen object unless you really need the BasicVector wrapping it.

get_value(self: pydrake.systems.framework.DiscreteValues, index: int = 0) → numpy.ndarray[numpy.float64[m, 1]]

(Don’t use this in new code) Returns the entire vector as a const Eigen::VectorBlock for the indicated group. Prefer value() which returns direct access to the underlying VectorX rather than wrapping it in a VectorBlock.

get_vector(self: pydrake.systems.framework.DiscreteValues, index: int = 0) → pydrake.systems.framework.BasicVector

(Advanced) Returns a const reference to the BasicVector holding data for the indicated group. Prefer value(index) to get the underlying VectorX directly unless you really need the BasicVector wrapping it.

num_groups(self: pydrake.systems.framework.DiscreteValues) → int

set_value(*args, **kwargs)

Overloaded function.

1. set_value(self: pydrake.systems.framework.DiscreteValues, value: numpy.ndarray[numpy.float64[m, 1]]) -> None

Sets the vector to the given value for the only group.

2. set_value(self: pydrake.systems.framework.DiscreteValues, index: int, value: numpy.ndarray[numpy.float64[m, 1]]) -> None

Sets the vector to the given value for the indicated group.

SetFrom(self: pydrake.systems.framework.DiscreteValues, arg0: pydrake.systems.framework.DiscreteValues) → None

Resets the values in this DiscreteValues from the values in other, possibly writing through to unowned data. Throws if the dimensions don’t match.

size(self: pydrake.systems.framework.DiscreteValues) → int

Returns the number of elements in the only DiscreteValues group.

value(self: pydrake.systems.framework.DiscreteValues, index: int = 0) → numpy.ndarray[numpy.float64[m, 1]]

Returns a const reference to the underlying VectorX containing the values for the indicated group. This is the preferred method for examining the value of a group.

template pydrake.systems.framework.DiscreteValues_

Instantiations: DiscreteValues_[float], DiscreteValues_[AutoDiffXd], DiscreteValues_[Expression]

class pydrake.systems.framework.DiscreteValues_[AutoDiffXd]

%DiscreteValues is a container for numerical but non-continuous state and parameters. It may own its underlying data, for use with leaf Systems, or not, for use with Diagrams.

DiscreteValues is an ordered collection xd of BasicVector “groups” so xd = [xd₀, xd₁…], where each group xdᵢ is a contiguous vector. Requesting a specific group index from this collection is the most granular way to retrieve discrete values from the Context, and thus is the unit of cache invalidation. System authors are encouraged to partition their DiscreteValues such that each cacheable computation within the System may depend on only the elements of DiscreteValues that it needs.

None of the contained vectors (groups) may be null, although any of them may be zero-length.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.DiscreteValues_[AutoDiffXd], datum: pydrake.systems.framework.BasicVector_[AutoDiffXd]) -> None

Constructs a one-group DiscreteValues object that owns a single datum vector which may not be null.

2. __init__(self: pydrake.systems.framework.DiscreteValues_[AutoDiffXd], data: list[pydrake.systems.framework.BasicVector_[AutoDiffXd]]) -> None

Constructs a DiscreteValues that owns the underlying data. Every entry must be non-null.

3. __init__(self: pydrake.systems.framework.DiscreteValues_[AutoDiffXd]) -> None

Constructs an empty DiscreteValues object containing no groups.

Clone(self: pydrake.systems.framework.DiscreteValues_[AutoDiffXd]) → pydrake.systems.framework.DiscreteValues_[AutoDiffXd]

get_data(self: pydrake.systems.framework.DiscreteValues_[AutoDiffXd]) → list[pydrake.systems.framework.BasicVector_[AutoDiffXd]]

get_mutable_value(self: pydrake.systems.framework.DiscreteValues_[AutoDiffXd], index: int = 0) → numpy.ndarray[object[m, 1], flags.writeable]

Returns the entire vector for the indicated group as a mutable Eigen::VectorBlock, which allows mutation of the values, but does not allow resize() to be called on the vector.

get_mutable_vector(self: pydrake.systems.framework.DiscreteValues_[AutoDiffXd], index: int = 0) → pydrake.systems.framework.BasicVector_[AutoDiffXd]

(Advanced) Returns a mutable reference to the BasicVector holding data for the indicated group. Prefer get_mutable_value() to get the underlying Eigen object unless you really need the BasicVector wrapping it.

get_value(self: pydrake.systems.framework.DiscreteValues_[AutoDiffXd], index: int = 0) → numpy.ndarray[object[m, 1]]

(Don’t use this in new code) Returns the entire vector as a const Eigen::VectorBlock for the indicated group. Prefer value() which returns direct access to the underlying VectorX rather than wrapping it in a VectorBlock.

get_vector(self: pydrake.systems.framework.DiscreteValues_[AutoDiffXd], index: int = 0) → pydrake.systems.framework.BasicVector_[AutoDiffXd]

(Advanced) Returns a const reference to the BasicVector holding data for the indicated group. Prefer value(index) to get the underlying VectorX directly unless you really need the BasicVector wrapping it.

num_groups(self: pydrake.systems.framework.DiscreteValues_[AutoDiffXd]) → int

set_value(*args, **kwargs)

Overloaded function.

1. set_value(self: pydrake.systems.framework.DiscreteValues_[AutoDiffXd], value: numpy.ndarray[object[m, 1]]) -> None

Sets the vector to the given value for the only group.

2. set_value(self: pydrake.systems.framework.DiscreteValues_[AutoDiffXd], index: int, value: numpy.ndarray[object[m, 1]]) -> None

Sets the vector to the given value for the indicated group.

SetFrom(self: pydrake.systems.framework.DiscreteValues_[AutoDiffXd], arg0: pydrake.systems.framework.DiscreteValues) → None

Resets the values in this DiscreteValues from the values in other, possibly writing through to unowned data. Throws if the dimensions don’t match.

size(self: pydrake.systems.framework.DiscreteValues_[AutoDiffXd]) → int

Returns the number of elements in the only DiscreteValues group.

value(self: pydrake.systems.framework.DiscreteValues_[AutoDiffXd], index: int = 0) → numpy.ndarray[object[m, 1]]

Returns a const reference to the underlying VectorX containing the values for the indicated group. This is the preferred method for examining the value of a group.

class pydrake.systems.framework.DiscreteValues_[Expression]

%DiscreteValues is a container for numerical but non-continuous state and parameters. It may own its underlying data, for use with leaf Systems, or not, for use with Diagrams.

DiscreteValues is an ordered collection xd of BasicVector “groups” so xd = [xd₀, xd₁…], where each group xdᵢ is a contiguous vector. Requesting a specific group index from this collection is the most granular way to retrieve discrete values from the Context, and thus is the unit of cache invalidation. System authors are encouraged to partition their DiscreteValues such that each cacheable computation within the System may depend on only the elements of DiscreteValues that it needs.

None of the contained vectors (groups) may be null, although any of them may be zero-length.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.DiscreteValues_[Expression], datum: pydrake.systems.framework.BasicVector_[Expression]) -> None

Constructs a one-group DiscreteValues object that owns a single datum vector which may not be null.

2. __init__(self: pydrake.systems.framework.DiscreteValues_[Expression], data: list[pydrake.systems.framework.BasicVector_[Expression]]) -> None

Constructs a DiscreteValues that owns the underlying data. Every entry must be non-null.

3. __init__(self: pydrake.systems.framework.DiscreteValues_[Expression]) -> None

Constructs an empty DiscreteValues object containing no groups.

Clone(self: pydrake.systems.framework.DiscreteValues_[Expression]) → pydrake.systems.framework.DiscreteValues_[Expression]

get_data(self: pydrake.systems.framework.DiscreteValues_[Expression]) → list[pydrake.systems.framework.BasicVector_[Expression]]

get_mutable_value(self: pydrake.systems.framework.DiscreteValues_[Expression], index: int = 0) → numpy.ndarray[object[m, 1], flags.writeable]

Returns the entire vector for the indicated group as a mutable Eigen::VectorBlock, which allows mutation of the values, but does not allow resize() to be called on the vector.

get_mutable_vector(self: pydrake.systems.framework.DiscreteValues_[Expression], index: int = 0) → pydrake.systems.framework.BasicVector_[Expression]

(Advanced) Returns a mutable reference to the BasicVector holding data for the indicated group. Prefer get_mutable_value() to get the underlying Eigen object unless you really need the BasicVector wrapping it.

get_value(self: pydrake.systems.framework.DiscreteValues_[Expression], index: int = 0) → numpy.ndarray[object[m, 1]]

(Don’t use this in new code) Returns the entire vector as a const Eigen::VectorBlock for the indicated group. Prefer value() which returns direct access to the underlying VectorX rather than wrapping it in a VectorBlock.

get_vector(self: pydrake.systems.framework.DiscreteValues_[Expression], index: int = 0) → pydrake.systems.framework.BasicVector_[Expression]

(Advanced) Returns a const reference to the BasicVector holding data for the indicated group. Prefer value(index) to get the underlying VectorX directly unless you really need the BasicVector wrapping it.

num_groups(self: pydrake.systems.framework.DiscreteValues_[Expression]) → int

set_value(*args, **kwargs)

Overloaded function.

1. set_value(self: pydrake.systems.framework.DiscreteValues_[Expression], value: numpy.ndarray[object[m, 1]]) -> None

Sets the vector to the given value for the only group.

2. set_value(self: pydrake.systems.framework.DiscreteValues_[Expression], index: int, value: numpy.ndarray[object[m, 1]]) -> None

Sets the vector to the given value for the indicated group.

SetFrom(self: pydrake.systems.framework.DiscreteValues_[Expression], arg0: pydrake.systems.framework.DiscreteValues) → None

Resets the values in this DiscreteValues from the values in other, possibly writing through to unowned data. Throws if the dimensions don’t match.

size(self: pydrake.systems.framework.DiscreteValues_[Expression]) → int

Returns the number of elements in the only DiscreteValues group.

value(self: pydrake.systems.framework.DiscreteValues_[Expression], index: int = 0) → numpy.ndarray[object[m, 1]]

Returns a const reference to the underlying VectorX containing the values for the indicated group. This is the preferred method for examining the value of a group.

class pydrake.systems.framework.Event

Abstract base class that represents an event. The base event contains two main pieces of information: an enum trigger type and an optional attribute that can be used to explain why the event is triggered.

Concrete derived classes contain a function pointer to an optional callback that handles the event. No-op is the default handling behavior. The System framework supports three concrete event types: PublishEvent, DiscreteUpdateEvent, and UnrestrictedUpdateEvent distinguished by their callback functions’ write access level to the State.

The most common and convenient use of events and callbacks will happen via the LeafSystem Declare*Event() methods. To that end, the callback signature always passes the const System<T>& as the first argument, so that LeafSystem does not need to capture this into the lambda; typically only a pointer-to-member- function is captured. Capturing any more than that would defeat std::function’s small buffer optimization and cause heap allocations when scheduling events.

Event handling occurs during a simulation of a system. The logic that describes when particular event types are handled is described in the class documentation for Simulator.

Note

This class is templated; see Event_ for the list of instantiations.

__init__(*args, **kwargs)

get_trigger_type(self: pydrake.systems.framework.Event) → pydrake.systems.framework.TriggerType

Returns the trigger type.

template pydrake.systems.framework.Event_

Instantiations: Event_[float], Event_[AutoDiffXd], Event_[Expression]

class pydrake.systems.framework.Event_[AutoDiffXd]

Abstract base class that represents an event. The base event contains two main pieces of information: an enum trigger type and an optional attribute that can be used to explain why the event is triggered.

Concrete derived classes contain a function pointer to an optional callback that handles the event. No-op is the default handling behavior. The System framework supports three concrete event types: PublishEvent, DiscreteUpdateEvent, and UnrestrictedUpdateEvent distinguished by their callback functions’ write access level to the State.

The most common and convenient use of events and callbacks will happen via the LeafSystem Declare*Event() methods. To that end, the callback signature always passes the const System<T>& as the first argument, so that LeafSystem does not need to capture this into the lambda; typically only a pointer-to-member- function is captured. Capturing any more than that would defeat std::function’s small buffer optimization and cause heap allocations when scheduling events.

Event handling occurs during a simulation of a system. The logic that describes when particular event types are handled is described in the class documentation for Simulator.

__init__(*args, **kwargs)

get_trigger_type(self: pydrake.systems.framework.Event_[AutoDiffXd]) → pydrake.systems.framework.TriggerType

Returns the trigger type.

class pydrake.systems.framework.Event_[Expression]

Abstract base class that represents an event. The base event contains two main pieces of information: an enum trigger type and an optional attribute that can be used to explain why the event is triggered.

Concrete derived classes contain a function pointer to an optional callback that handles the event. No-op is the default handling behavior. The System framework supports three concrete event types: PublishEvent, DiscreteUpdateEvent, and UnrestrictedUpdateEvent distinguished by their callback functions’ write access level to the State.

The most common and convenient use of events and callbacks will happen via the LeafSystem Declare*Event() methods. To that end, the callback signature always passes the const System<T>& as the first argument, so that LeafSystem does not need to capture this into the lambda; typically only a pointer-to-member- function is captured. Capturing any more than that would defeat std::function’s small buffer optimization and cause heap allocations when scheduling events.

Event handling occurs during a simulation of a system. The logic that describes when particular event types are handled is described in the class documentation for Simulator.

__init__(*args, **kwargs)

get_trigger_type(self: pydrake.systems.framework.Event_[Expression]) → pydrake.systems.framework.TriggerType

Returns the trigger type.

class pydrake.systems.framework.EventStatus

Holds the return status from execution of an event handler function, or the effective status after a series of handler executions due to dispatching of simultaneous events. Drake API users will typically use only the four factory methods below to return status, and optionally a human-readable message, from their event handlers.

__init__(*args, **kwargs)

static DidNothing() → pydrake.systems.framework.EventStatus

Returns “did nothing” status, with no message.

static Failed(system: drake::systems::SystemBase, message: str) → pydrake.systems.framework.EventStatus

Returns “failed” status, with a message explaining why.

KeepMoreSevere(self: pydrake.systems.framework.EventStatus, candidate: pydrake.systems.framework.EventStatus) → pydrake.systems.framework.EventStatus

(Advanced) Replaces the contents of this with the more-severe status if candidate is a more severe status than this one. Does nothing if candidate severity is less than or equal to this severity. This method is for use in event dispatchers for accumulating status returns from a series of event handlers for a set of simultaneous events.

message(self: pydrake.systems.framework.EventStatus) → str

Returns the optionally-provided human-readable message supplied by the event handler that produced the current status. Returns an empty string if no message was provided.

static ReachedTermination(system: drake::systems::SystemBase, message: str) → pydrake.systems.framework.EventStatus

Returns “reached termination” status, with a message explaining why.

class Severity

The numerical values are ordered, with did_nothing < success < terminate < fatal.

Members:

kDidNothing : Successful, but nothing happened; no state update needed.

kSucceeded : Handler executed successfully; state may have been updated.

kReachedTermination : Handler succeeded but detected a normal termination condition (has

message). Intended primarily for internal use by the Simulator.

kFailed : Handler was unable to perform its job (has message).

__init__(self: pydrake.systems.framework.EventStatus.Severity, value: int) → None

kDidNothing = <Severity.kDidNothing: 0>

kFailed = <Severity.kFailed: 3>

kReachedTermination = <Severity.kReachedTermination: 2>

kSucceeded = <Severity.kSucceeded: 1>

property name

property value

severity(self: pydrake.systems.framework.EventStatus) → pydrake.systems.framework.EventStatus.Severity

Returns the severity of the current status.

static Succeeded() → pydrake.systems.framework.EventStatus

Returns “succeeded” status, with no message.

system(self: pydrake.systems.framework.EventStatus) → drake::systems::SystemBase

Returns the optionally-provided subsystem that generated a status return that can include a message (reached termination or failed). Returns nullptr if no subsystem was provided.

class pydrake.systems.framework.FixedInputPortValue

A FixedInputPortValue encapsulates a vector or abstract value for use as an internal value source for one of a System’s input ports. The semantics are identical to a Parameter. We assign a DependencyTracker to this object and subscribe the InputPort to it when that port is fixed. Any modification to the value here issues a notification to its dependent, and increments a serial number kept here.

__init__(*args, **kwargs)

GetMutableData(self: pydrake.systems.framework.FixedInputPortValue) → pydrake.common.value.AbstractValue

Returns a pointer to the data inside this FixedInputPortValue, and notifies the dependent input port that the value has changed.

To ensure invalidation notifications are delivered, callers should call this method every time they wish to update the stored value. In particular, callers MUST NOT write through the returned pointer if there is any possibility this FixedInputPortValue has been accessed since the last time this method was called.

class pydrake.systems.framework.InputPort

An InputPort is a System resource that describes the kind of input a System accepts, on a given port. It does not directly contain any runtime input port data; that is always contained in a Context. The actual value will be either the value of an OutputPort to which this is connected, or a fixed value set in a Context.

Note

This class is templated; see InputPort_ for the list of instantiations.

__init__(*args, **kwargs)

Allocate(self: pydrake.systems.framework.InputPort) → pydrake.common.value.AbstractValue

Allocates a concrete object suitable for holding the value to be provided by this input port, and returns that as an AbstractValue. The returned object will never be null.

Eval(self: pydrake.systems.framework.InputPort, arg0: pydrake.systems.framework.Context) → object

EvalAbstract(self: pydrake.systems.framework.InputPort, context: pydrake.systems.framework.Context) → pydrake.common.value.AbstractValue

(Advanced.) Returns the value of this input port, typed as an AbstractValue. Most users should call Eval() instead. This method is only needed when the result will be passed into some other API that only accepts an AbstractValue.

EvalBasicVector(self: pydrake.systems.framework.InputPort, context: pydrake.systems.framework.Context) → object

(Advanced.) Returns the value of this input port, typed as a BasicVector. Most users should call Eval() instead. This method is only needed when the result will be passed into some other API that only accepts a BasicVector.

FixValue(*args, **kwargs)

Overloaded function.

1. FixValue(self: pydrake.systems.framework.InputPort, context: pydrake.systems.framework.Context, value: pydrake.common.value.AbstractValue) -> pydrake.systems.framework.FixedInputPortValue

Provides a fixed value for this InputPort in the given Context. If the port is already connected, this value will override the connected source value. (By “connected” we mean that the port appeared in a DiagramBuilder::Connect() call.)

For vector-valued input ports, you can provide an Eigen vector expression, a BasicVector object, or a scalar (treated as a Vector1). In each of these cases the value is copied into a Value<BasicVector>. If the original value was a BasicVector-derived object, its concrete type is maintained although the stored type is still Value<BasicVector>. The supplied vector must have the right size for the vector port or an RuntimeError is thrown.

For abstract-valued input ports, you can provide any ValueType that is compatible with the model type provided when the port was declared. If the type has a copy constructor it will be copied into a Value<ValueType> object for storage. Otherwise it must have an accessible Clone() method and it is stored using the type returned by that method, which must be ValueType or a base class of ValueType. Eigen objects and expressions are not accepted directly, but you can store then in abstract ports by providing an already-abstract object like Value<MatrixXd>(your_matrix).

The returned FixedInputPortValue reference may be used to modify the input port’s value subsequently using the appropriate FixedInputPortValue method, which will ensure that cache invalidation notifications are delivered.

Template parameter ValueType:

The type of the supplied value object. This will be inferred so no template argument need be specified. The type must be copy constructible or have an accessible Clone() method.

Parameter context:

A Context that is compatible with the System that owns this port.

Parameter value:

The fixed value for this port. Must be convertible to the input port’s data type.

Returns

a reference to the FixedInputPortValue object in the Context that contains this port’s value.

Precondition:

context is compatible with the System that owns this InputPort.

Precondition:

value is compatible with this InputPort’s data type.

2. FixValue(self: pydrake.systems.framework.InputPort, context: pydrake.systems.framework.Context, value: object) -> pydrake.systems.framework.FixedInputPortValue

Provides a fixed value for this InputPort in the given Context. If the port is already connected, this value will override the connected source value. (By “connected” we mean that the port appeared in a DiagramBuilder::Connect() call.)

For vector-valued input ports, you can provide an Eigen vector expression, a BasicVector object, or a scalar (treated as a Vector1). In each of these cases the value is copied into a Value<BasicVector>. If the original value was a BasicVector-derived object, its concrete type is maintained although the stored type is still Value<BasicVector>. The supplied vector must have the right size for the vector port or an RuntimeError is thrown.

For abstract-valued input ports, you can provide any ValueType that is compatible with the model type provided when the port was declared. If the type has a copy constructor it will be copied into a Value<ValueType> object for storage. Otherwise it must have an accessible Clone() method and it is stored using the type returned by that method, which must be ValueType or a base class of ValueType. Eigen objects and expressions are not accepted directly, but you can store then in abstract ports by providing an already-abstract object like Value<MatrixXd>(your_matrix).

The returned FixedInputPortValue reference may be used to modify the input port’s value subsequently using the appropriate FixedInputPortValue method, which will ensure that cache invalidation notifications are delivered.

Template parameter ValueType:

The type of the supplied value object. This will be inferred so no template argument need be specified. The type must be copy constructible or have an accessible Clone() method.

Parameter context:

A Context that is compatible with the System that owns this port.

Parameter value:

The fixed value for this port. Must be convertible to the input port’s data type.

Returns

a reference to the FixedInputPortValue object in the Context that contains this port’s value.

Precondition:

context is compatible with the System that owns this InputPort.

Precondition:

value is compatible with this InputPort’s data type.

get_data_type(self: pydrake.systems.framework.InputPort) → pydrake.systems.framework.PortDataType

Returns the port data type.

get_index(self: pydrake.systems.framework.InputPort) → pydrake.systems.framework.InputPortIndex

Returns the index of this input port within the owning System. For a Diagram, this will be the index within the Diagram, not the index within a LeafSystem whose input port was exported.

get_name(self: pydrake.systems.framework.InputPort) → str

Get port name.

get_system(self: pydrake.systems.framework.InputPort) → drake::systems::System<double>

Returns a reference to the System that owns this input port. Note that for a Diagram input port this will be the Diagram, not the LeafSystem whose input port was exported.

GetFullDescription(self: pydrake.systems.framework.InputPort) → str

Returns a verbose human-readable description of port. This is useful for error messages or debugging.

HasValue(self: pydrake.systems.framework.InputPort, context: pydrake.systems.framework.Context) → bool

Returns true iff this port is connected or has had a fixed value provided in the given Context. Beware that at the moment, this could be an expensive operation, because the value is brought up-to-date as part of this operation.

size(self: pydrake.systems.framework.InputPort) → int

Returns the fixed size expected for a vector-valued port. Not meaningful for abstract-valued ports.

ticket(self: pydrake.systems.framework.InputPort) → pydrake.systems.framework.DependencyTicket

(Advanced.) Returns the DependencyTicket for this port within the owning System.

template pydrake.systems.framework.InputPort_

Instantiations: InputPort_[float], InputPort_[AutoDiffXd], InputPort_[Expression]

class pydrake.systems.framework.InputPort_[AutoDiffXd]

An InputPort is a System resource that describes the kind of input a System accepts, on a given port. It does not directly contain any runtime input port data; that is always contained in a Context. The actual value will be either the value of an OutputPort to which this is connected, or a fixed value set in a Context.

__init__(*args, **kwargs)

Allocate(self: pydrake.systems.framework.InputPort_[AutoDiffXd]) → pydrake.common.value.AbstractValue

Allocates a concrete object suitable for holding the value to be provided by this input port, and returns that as an AbstractValue. The returned object will never be null.

Eval(self: pydrake.systems.framework.InputPort_[AutoDiffXd], arg0: pydrake.systems.framework.Context_[AutoDiffXd]) → object

EvalAbstract(self: pydrake.systems.framework.InputPort_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.common.value.AbstractValue

(Advanced.) Returns the value of this input port, typed as an AbstractValue. Most users should call Eval() instead. This method is only needed when the result will be passed into some other API that only accepts an AbstractValue.

EvalBasicVector(self: pydrake.systems.framework.InputPort_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → object

(Advanced.) Returns the value of this input port, typed as a BasicVector. Most users should call Eval() instead. This method is only needed when the result will be passed into some other API that only accepts a BasicVector.

FixValue(*args, **kwargs)

Overloaded function.

1. FixValue(self: pydrake.systems.framework.InputPort_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], value: pydrake.common.value.AbstractValue) -> pydrake.systems.framework.FixedInputPortValue

Provides a fixed value for this InputPort in the given Context. If the port is already connected, this value will override the connected source value. (By “connected” we mean that the port appeared in a DiagramBuilder::Connect() call.)

For vector-valued input ports, you can provide an Eigen vector expression, a BasicVector object, or a scalar (treated as a Vector1). In each of these cases the value is copied into a Value<BasicVector>. If the original value was a BasicVector-derived object, its concrete type is maintained although the stored type is still Value<BasicVector>. The supplied vector must have the right size for the vector port or an RuntimeError is thrown.

For abstract-valued input ports, you can provide any ValueType that is compatible with the model type provided when the port was declared. If the type has a copy constructor it will be copied into a Value<ValueType> object for storage. Otherwise it must have an accessible Clone() method and it is stored using the type returned by that method, which must be ValueType or a base class of ValueType. Eigen objects and expressions are not accepted directly, but you can store then in abstract ports by providing an already-abstract object like Value<MatrixXd>(your_matrix).

The returned FixedInputPortValue reference may be used to modify the input port’s value subsequently using the appropriate FixedInputPortValue method, which will ensure that cache invalidation notifications are delivered.

Template parameter ValueType:

The type of the supplied value object. This will be inferred so no template argument need be specified. The type must be copy constructible or have an accessible Clone() method.

Parameter context:

A Context that is compatible with the System that owns this port.

Parameter value:

The fixed value for this port. Must be convertible to the input port’s data type.

Returns

a reference to the FixedInputPortValue object in the Context that contains this port’s value.

Precondition:

context is compatible with the System that owns this InputPort.

Precondition:

value is compatible with this InputPort’s data type.

2. FixValue(self: pydrake.systems.framework.InputPort_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], value: object) -> pydrake.systems.framework.FixedInputPortValue

Provides a fixed value for this InputPort in the given Context. If the port is already connected, this value will override the connected source value. (By “connected” we mean that the port appeared in a DiagramBuilder::Connect() call.)

For vector-valued input ports, you can provide an Eigen vector expression, a BasicVector object, or a scalar (treated as a Vector1). In each of these cases the value is copied into a Value<BasicVector>. If the original value was a BasicVector-derived object, its concrete type is maintained although the stored type is still Value<BasicVector>. The supplied vector must have the right size for the vector port or an RuntimeError is thrown.

For abstract-valued input ports, you can provide any ValueType that is compatible with the model type provided when the port was declared. If the type has a copy constructor it will be copied into a Value<ValueType> object for storage. Otherwise it must have an accessible Clone() method and it is stored using the type returned by that method, which must be ValueType or a base class of ValueType. Eigen objects and expressions are not accepted directly, but you can store then in abstract ports by providing an already-abstract object like Value<MatrixXd>(your_matrix).

The returned FixedInputPortValue reference may be used to modify the input port’s value subsequently using the appropriate FixedInputPortValue method, which will ensure that cache invalidation notifications are delivered.

Template parameter ValueType:

The type of the supplied value object. This will be inferred so no template argument need be specified. The type must be copy constructible or have an accessible Clone() method.

Parameter context:

A Context that is compatible with the System that owns this port.

Parameter value:

The fixed value for this port. Must be convertible to the input port’s data type.

Returns

a reference to the FixedInputPortValue object in the Context that contains this port’s value.

Precondition:

context is compatible with the System that owns this InputPort.

Precondition:

value is compatible with this InputPort’s data type.

get_data_type(self: pydrake.systems.framework.InputPort_[AutoDiffXd]) → pydrake.systems.framework.PortDataType

Returns the port data type.

get_index(self: pydrake.systems.framework.InputPort_[AutoDiffXd]) → pydrake.systems.framework.InputPortIndex

Returns the index of this input port within the owning System. For a Diagram, this will be the index within the Diagram, not the index within a LeafSystem whose input port was exported.

get_name(self: pydrake.systems.framework.InputPort_[AutoDiffXd]) → str

Get port name.

get_system(self: pydrake.systems.framework.InputPort_[AutoDiffXd]) → drake::systems::System<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >

Returns a reference to the System that owns this input port. Note that for a Diagram input port this will be the Diagram, not the LeafSystem whose input port was exported.

GetFullDescription(self: pydrake.systems.framework.InputPort_[AutoDiffXd]) → str

Returns a verbose human-readable description of port. This is useful for error messages or debugging.

HasValue(self: pydrake.systems.framework.InputPort_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → bool

Returns true iff this port is connected or has had a fixed value provided in the given Context. Beware that at the moment, this could be an expensive operation, because the value is brought up-to-date as part of this operation.

size(self: pydrake.systems.framework.InputPort_[AutoDiffXd]) → int

Returns the fixed size expected for a vector-valued port. Not meaningful for abstract-valued ports.

ticket(self: pydrake.systems.framework.InputPort_[AutoDiffXd]) → pydrake.systems.framework.DependencyTicket

(Advanced.) Returns the DependencyTicket for this port within the owning System.

class pydrake.systems.framework.InputPort_[Expression]

An InputPort is a System resource that describes the kind of input a System accepts, on a given port. It does not directly contain any runtime input port data; that is always contained in a Context. The actual value will be either the value of an OutputPort to which this is connected, or a fixed value set in a Context.

__init__(*args, **kwargs)

Allocate(self: pydrake.systems.framework.InputPort_[Expression]) → pydrake.common.value.AbstractValue

Allocates a concrete object suitable for holding the value to be provided by this input port, and returns that as an AbstractValue. The returned object will never be null.

Eval(self: pydrake.systems.framework.InputPort_[Expression], arg0: pydrake.systems.framework.Context_[Expression]) → object

EvalAbstract(self: pydrake.systems.framework.InputPort_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.common.value.AbstractValue

(Advanced.) Returns the value of this input port, typed as an AbstractValue. Most users should call Eval() instead. This method is only needed when the result will be passed into some other API that only accepts an AbstractValue.

EvalBasicVector(self: pydrake.systems.framework.InputPort_[Expression], context: pydrake.systems.framework.Context_[Expression]) → object

(Advanced.) Returns the value of this input port, typed as a BasicVector. Most users should call Eval() instead. This method is only needed when the result will be passed into some other API that only accepts a BasicVector.

FixValue(*args, **kwargs)

Overloaded function.

1. FixValue(self: pydrake.systems.framework.InputPort_[Expression], context: pydrake.systems.framework.Context_[Expression], value: pydrake.common.value.AbstractValue) -> pydrake.systems.framework.FixedInputPortValue

Provides a fixed value for this InputPort in the given Context. If the port is already connected, this value will override the connected source value. (By “connected” we mean that the port appeared in a DiagramBuilder::Connect() call.)

For vector-valued input ports, you can provide an Eigen vector expression, a BasicVector object, or a scalar (treated as a Vector1). In each of these cases the value is copied into a Value<BasicVector>. If the original value was a BasicVector-derived object, its concrete type is maintained although the stored type is still Value<BasicVector>. The supplied vector must have the right size for the vector port or an RuntimeError is thrown.

For abstract-valued input ports, you can provide any ValueType that is compatible with the model type provided when the port was declared. If the type has a copy constructor it will be copied into a Value<ValueType> object for storage. Otherwise it must have an accessible Clone() method and it is stored using the type returned by that method, which must be ValueType or a base class of ValueType. Eigen objects and expressions are not accepted directly, but you can store then in abstract ports by providing an already-abstract object like Value<MatrixXd>(your_matrix).

The returned FixedInputPortValue reference may be used to modify the input port’s value subsequently using the appropriate FixedInputPortValue method, which will ensure that cache invalidation notifications are delivered.

Template parameter ValueType:

The type of the supplied value object. This will be inferred so no template argument need be specified. The type must be copy constructible or have an accessible Clone() method.

Parameter context:

A Context that is compatible with the System that owns this port.

Parameter value:

The fixed value for this port. Must be convertible to the input port’s data type.

Returns

a reference to the FixedInputPortValue object in the Context that contains this port’s value.

Precondition:

context is compatible with the System that owns this InputPort.

Precondition:

value is compatible with this InputPort’s data type.

2. FixValue(self: pydrake.systems.framework.InputPort_[Expression], context: pydrake.systems.framework.Context_[Expression], value: object) -> pydrake.systems.framework.FixedInputPortValue

Provides a fixed value for this InputPort in the given Context. If the port is already connected, this value will override the connected source value. (By “connected” we mean that the port appeared in a DiagramBuilder::Connect() call.)

For vector-valued input ports, you can provide an Eigen vector expression, a BasicVector object, or a scalar (treated as a Vector1). In each of these cases the value is copied into a Value<BasicVector>. If the original value was a BasicVector-derived object, its concrete type is maintained although the stored type is still Value<BasicVector>. The supplied vector must have the right size for the vector port or an RuntimeError is thrown.

For abstract-valued input ports, you can provide any ValueType that is compatible with the model type provided when the port was declared. If the type has a copy constructor it will be copied into a Value<ValueType> object for storage. Otherwise it must have an accessible Clone() method and it is stored using the type returned by that method, which must be ValueType or a base class of ValueType. Eigen objects and expressions are not accepted directly, but you can store then in abstract ports by providing an already-abstract object like Value<MatrixXd>(your_matrix).

The returned FixedInputPortValue reference may be used to modify the input port’s value subsequently using the appropriate FixedInputPortValue method, which will ensure that cache invalidation notifications are delivered.

Template parameter ValueType:

The type of the supplied value object. This will be inferred so no template argument need be specified. The type must be copy constructible or have an accessible Clone() method.

Parameter context:

A Context that is compatible with the System that owns this port.

Parameter value:

The fixed value for this port. Must be convertible to the input port’s data type.

Returns

a reference to the FixedInputPortValue object in the Context that contains this port’s value.

Precondition:

context is compatible with the System that owns this InputPort.

Precondition:

value is compatible with this InputPort’s data type.

get_data_type(self: pydrake.systems.framework.InputPort_[Expression]) → pydrake.systems.framework.PortDataType

Returns the port data type.

get_index(self: pydrake.systems.framework.InputPort_[Expression]) → pydrake.systems.framework.InputPortIndex

Returns the index of this input port within the owning System. For a Diagram, this will be the index within the Diagram, not the index within a LeafSystem whose input port was exported.

get_name(self: pydrake.systems.framework.InputPort_[Expression]) → str

Get port name.

get_system(self: pydrake.systems.framework.InputPort_[Expression]) → drake::systems::System<drake::symbolic::Expression>

Returns a reference to the System that owns this input port. Note that for a Diagram input port this will be the Diagram, not the LeafSystem whose input port was exported.

GetFullDescription(self: pydrake.systems.framework.InputPort_[Expression]) → str

Returns a verbose human-readable description of port. This is useful for error messages or debugging.

HasValue(self: pydrake.systems.framework.InputPort_[Expression], context: pydrake.systems.framework.Context_[Expression]) → bool

Returns true iff this port is connected or has had a fixed value provided in the given Context. Beware that at the moment, this could be an expensive operation, because the value is brought up-to-date as part of this operation.

size(self: pydrake.systems.framework.InputPort_[Expression]) → int

Returns the fixed size expected for a vector-valued port. Not meaningful for abstract-valued ports.

ticket(self: pydrake.systems.framework.InputPort_[Expression]) → pydrake.systems.framework.DependencyTicket

(Advanced.) Returns the DependencyTicket for this port within the owning System.

class pydrake.systems.framework.InputPortIndex

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.InputPortIndex) -> None

Default constructor; the result is an invalid index. This only exists to serve applications which require a default constructor.

2. __init__(self: pydrake.systems.framework.InputPortIndex, arg0: int) -> None

Construction from a non-negative int value. The value must lie in the range of [0, 2³¹). Constructor only promises to test validity in Debug build.

is_valid(self: pydrake.systems.framework.InputPortIndex) → bool

Reports if the index is valid–the only operation on an invalid index that doesn’t throw an exception in Debug builds.

class pydrake.systems.framework.InputPortSelection

Members:

kNoInput

kUseFirstInputIfItExists

__init__(self: pydrake.systems.framework.InputPortSelection, value: int) → None

kNoInput = <InputPortSelection.kNoInput: -1>

kUseFirstInputIfItExists = <InputPortSelection.kUseFirstInputIfItExists: -2>

property name

property value

class pydrake.systems.framework.LeafContext

Bases: pydrake.systems.framework.Context

LeafContext contains all prerequisite data necessary to uniquely determine the results of computations performed by the associated LeafSystem.

See also

Context for more information.

Note

This class is templated; see LeafContext_ for the list of instantiations.

__init__(*args, **kwargs)

template pydrake.systems.framework.LeafContext_

Instantiations: LeafContext_[float], LeafContext_[AutoDiffXd], LeafContext_[Expression]

class pydrake.systems.framework.LeafContext_[AutoDiffXd]

Bases: pydrake.systems.framework.Context_[AutoDiffXd]

LeafContext contains all prerequisite data necessary to uniquely determine the results of computations performed by the associated LeafSystem.

See also

Context for more information.

__init__(*args, **kwargs)

class pydrake.systems.framework.LeafContext_[Expression]

Bases: pydrake.systems.framework.Context_[Expression]

LeafContext contains all prerequisite data necessary to uniquely determine the results of computations performed by the associated LeafSystem.

See also

Context for more information.

__init__(*args, **kwargs)

class pydrake.systems.framework.LeafOutputPort

Bases: pydrake.systems.framework.OutputPort

(Advanced.) Implements an output port whose value is managed by a cache entry in the same LeafSystem as the port. This is intended for internal use in implementing the DeclareOutputPort() variants in LeafSystem.

Note

This class is templated; see LeafOutputPort_ for the list of instantiations.

__init__(*args, **kwargs)

cache_entry(self: pydrake.systems.framework.LeafOutputPort) → pydrake.systems.framework.CacheEntry

Returns the cache entry associated with this output port.

disable_caching_by_default(self: pydrake.systems.framework.LeafOutputPort) → None

(Debugging) Specifies that caching should be disabled for this output port when a Context is first allocated. This is useful if you have observed different behavior with caching on or off and would like to determine if the problem is caused by this port.

See also

CacheEntry::disable_caching_by_default()

template pydrake.systems.framework.LeafOutputPort_

Instantiations: LeafOutputPort_[float], LeafOutputPort_[AutoDiffXd], LeafOutputPort_[Expression]

class pydrake.systems.framework.LeafOutputPort_[AutoDiffXd]

Bases: pydrake.systems.framework.OutputPort_[AutoDiffXd]

(Advanced.) Implements an output port whose value is managed by a cache entry in the same LeafSystem as the port. This is intended for internal use in implementing the DeclareOutputPort() variants in LeafSystem.

__init__(*args, **kwargs)

cache_entry(self: pydrake.systems.framework.LeafOutputPort_[AutoDiffXd]) → pydrake.systems.framework.CacheEntry

Returns the cache entry associated with this output port.

disable_caching_by_default(self: pydrake.systems.framework.LeafOutputPort_[AutoDiffXd]) → None

(Debugging) Specifies that caching should be disabled for this output port when a Context is first allocated. This is useful if you have observed different behavior with caching on or off and would like to determine if the problem is caused by this port.

See also

CacheEntry::disable_caching_by_default()

class pydrake.systems.framework.LeafOutputPort_[Expression]

Bases: pydrake.systems.framework.OutputPort_[Expression]

(Advanced.) Implements an output port whose value is managed by a cache entry in the same LeafSystem as the port. This is intended for internal use in implementing the DeclareOutputPort() variants in LeafSystem.

__init__(*args, **kwargs)

cache_entry(self: pydrake.systems.framework.LeafOutputPort_[Expression]) → pydrake.systems.framework.CacheEntry

Returns the cache entry associated with this output port.

disable_caching_by_default(self: pydrake.systems.framework.LeafOutputPort_[Expression]) → None

(Debugging) Specifies that caching should be disabled for this output port when a Context is first allocated. This is useful if you have observed different behavior with caching on or off and would like to determine if the problem is caused by this port.

See also

CacheEntry::disable_caching_by_default()

class pydrake.systems.framework.LeafSystem

Bases: pydrake.systems.framework.System

A superclass template that extends System with some convenience utilities that are not applicable to Diagrams.

Note

This class is templated; see LeafSystem_ for the list of instantiations.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.LeafSystem) -> None

Default constructor that declares no inputs, outputs, state, parameters, events, nor scalar-type conversion support (AutoDiff, etc.). To enable AutoDiff support, use the SystemScalarConverter-based constructor.

2. __init__(self: pydrake.systems.framework.LeafSystem, converter: pydrake.systems.framework.SystemScalarConverter) -> None

Constructor that declares no inputs, outputs, state, parameters, or events, but allows subclasses to declare scalar-type conversion support (AutoDiff, etc.).

The scalar-type conversion support will use converter. To enable scalar-type conversion support, pass a SystemTypeTag<S>{} where S must be the exact class of this being constructed.

See system_scalar_conversion for detailed background and examples related to scalar-type conversion support.

DeclareAbstractInputPort(self: pydrake.systems.framework.LeafSystem, name: str, model_value: pydrake.common.value.AbstractValue) → pydrake.systems.framework.InputPort

Declares an abstract-valued input port using the given model_value. This is the best way to declare LeafSystem abstract input ports.

Any port connected to this input, and any call to FixValue for this input, must provide for values whose type matches this model_value.

See also

System::DeclareInputPort() for more information.

DeclareAbstractOutputPort(self: pydrake.systems.framework.LeafSystem, name: str, alloc: Callable[[], pydrake.common.value.AbstractValue], calc: Callable[[pydrake.systems.framework.Context, pydrake.common.value.AbstractValue], None], prerequisites_of_calc: set[pydrake.systems.framework.DependencyTicket] = {DependencyTicket(15)}) → pydrake.systems.framework.OutputPort

(Advanced) Declares an abstract-valued output port using the given allocator and calculator functions provided in their most generic forms. If you have a member function available use one of the other signatures.

See also

LeafOutputPort::AllocCallback, LeafOutputPort::CalcCallback

DeclareAbstractParameter(self: pydrake.systems.framework.LeafSystem, model_value: pydrake.common.value.AbstractValue) → int

Declares an abstract parameter using the given model_value. LeafSystem’s default implementation of SetDefaultParameters() will reset parameters to their model values. Returns the index of the new parameter.

DeclareAbstractState(self: pydrake.systems.framework.LeafSystem, model_value: pydrake.common.value.AbstractValue) → pydrake.systems.framework.AbstractStateIndex

Declares an abstract state variable and provides a model value for it. A Context obtained with CreateDefaultContext() will contain this abstract state variable initially set to a clone of the model_value given here. The actual concrete type is always preserved.

Parameter model_value:

The abstract state model value to be cloned as needed.

Returns

index of the declared abstract state variable.

DeclareContinuousState(*args, **kwargs)

Overloaded function.

1. DeclareContinuousState(self: pydrake.systems.framework.LeafSystem, num_state_variables: int) -> pydrake.systems.framework.ContinuousStateIndex

Declares that this System should reserve continuous state with num_state_variables state variables, which have no second-order structure.

Returns

index of the declared state (currently always zero).

2. DeclareContinuousState(self: pydrake.systems.framework.LeafSystem, num_q: int, num_v: int, num_z: int) -> pydrake.systems.framework.ContinuousStateIndex

Declares that this System should reserve continuous state with num_q generalized positions, num_v generalized velocities, and num_z miscellaneous state variables.

Returns

index of the declared state (currently always zero).

3. DeclareContinuousState(self: pydrake.systems.framework.LeafSystem, model_vector: pydrake.systems.framework.BasicVector) -> pydrake.systems.framework.ContinuousStateIndex

Declares that this System should reserve continuous state with model_vector.size() miscellaneous state variables, stored in a vector cloned from model_vector.

Returns

index of the declared state (currently always zero).

4. DeclareContinuousState(self: pydrake.systems.framework.LeafSystem, model_vector: pydrake.systems.framework.BasicVector, num_q: int, num_v: int, num_z: int) -> pydrake.systems.framework.ContinuousStateIndex

Declares that this System should reserve continuous state with num_q generalized positions, num_v generalized velocities, and num_z miscellaneous state variables, stored in a vector cloned from model_vector. Aborts if model_vector has the wrong size. If the model_vector declares any VectorBase::GetElementBounds() constraints, they will be re-declared as inequality constraints on this system (see DeclareInequalityConstraint()).

Returns

index of the declared state (currently always zero).

DeclareDiscreteState(*args, **kwargs)

Overloaded function.

1. DeclareDiscreteState(self: pydrake.systems.framework.LeafSystem, model_vector: pydrake.systems.framework.BasicVector) -> pydrake.systems.framework.DiscreteStateIndex

Declares a discrete state group with model_vector.size() state variables, stored in a vector cloned from model_vector (preserving the concrete type and value).

2. DeclareDiscreteState(self: pydrake.systems.framework.LeafSystem, vector: numpy.ndarray[numpy.float64[m, 1]]) -> pydrake.systems.framework.DiscreteStateIndex

Declares a discrete state group with vector.size() state variables, stored in a BasicVector initialized with the contents of vector.

3. DeclareDiscreteState(self: pydrake.systems.framework.LeafSystem, num_state_variables: int) -> pydrake.systems.framework.DiscreteStateIndex

Declares a discrete state group with num_state_variables state variables, stored in a BasicVector initialized to be all-zero. If you want non-zero initial values, use an alternate DeclareDiscreteState() signature that accepts a model_vector parameter.

Precondition:

num_state_variables must be non-negative.

DeclareForcedDiscreteUpdateEvent(self: pydrake.systems.framework.LeafSystem, update: Callable[[pydrake.systems.framework.Context, pydrake.systems.framework.DiscreteValues], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares a function that is called whenever a user directly calls CalcForcedDiscreteVariableUpdate(const Context&, DiscreteValues<T>*). Multiple calls to DeclareForcedDiscreteUpdateEvent() will cause multiple handlers to be called upon a call to CalcForcedDiscreteVariableUpdate(); these handlers will be called with the same const Context in arbitrary order. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyDiscreteVariableUpdates(const Context<T>&,
DiscreteValues<T>*);

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_forced_events “Declare forced events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

DeclareForcedPublishEvent(self: pydrake.systems.framework.LeafSystem, publish: Callable[[pydrake.systems.framework.Context], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares a function that is called whenever a user directly calls ForcedPublish(const Context&). Multiple calls to DeclareForcedPublishEvent() will cause multiple handlers to be called upon a call to ForcedPublish(); these handlers which will be called with the same const Context in arbitrary order. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyPublish(const Context<T>&) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_forced_events “Declare forced events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

publish must not be null.

DeclareForcedUnrestrictedUpdateEvent(self: pydrake.systems.framework.LeafSystem, update: Callable[[pydrake.systems.framework.Context, pydrake.systems.framework.State], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares a function that is called whenever a user directly calls CalcForcedUnrestrictedUpdate(const Context&, State<T>*). Multiple calls to DeclareForcedUnrestrictedUpdateEvent() will cause multiple handlers to be called upon a call to CalcForcedUnrestrictedUpdate(); these handlers which will be called with the same const Context in arbitrary order.The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUnrestrictedUpdates(const Context<T>&,
State<T>*);

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_forced_events “Declare forced events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

DeclareInitializationDiscreteUpdateEvent(self: pydrake.systems.framework.LeafSystem, update: Callable[[pydrake.systems.framework.Context, pydrake.systems.framework.DiscreteValues], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that a DiscreteUpdate event should occur at initialization and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUpdate(const Context<T>&,
DiscreteValues<T>*) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_initialization_events “Declare initialization events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

See also

DeclareInitializationPublishEvent()

See also

DeclareInitializationUnrestrictedUpdateEvent()

See also

DeclareInitializationEvent()

DeclareInitializationEvent(self: pydrake.systems.framework.LeafSystem, event: pydrake.systems.framework.Event) → None

(Advanced) Declares that a particular Event object should be dispatched at initialization. This is the most general form for declaring initialization events and most users should use one of the other methods in this group instead.

See also

DeclareInitializationPublishEvent()

See also

DeclareInitializationDiscreteUpdateEvent()

See also

DeclareInitializationUnrestrictedUpdateEvent()

See declare_initialization_events “Declare initialization events” for more information.

Depending on the type of event, on initialization it will be passed to the Publish, DiscreteUpdate, or UnrestrictedUpdate event dispatcher. If the event object contains a handler function, Drake’s default dispatchers will invoke that handler. If not, then no further action is taken. Thus an event with no handler has no effect unless its dispatcher has been overridden. We strongly recommend that you do not override the dispatcher and instead do supply a handler.

The given event object is deep-copied (cloned), and the copy is stored internally so you do not need to keep the object around after this call.

Precondition:

event’s associated trigger type must be TriggerType::kUnknown or already set to TriggerType::kInitialization.

DeclareInitializationPublishEvent(self: pydrake.systems.framework.LeafSystem, publish: Callable[[pydrake.systems.framework.Context], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that a Publish event should occur at initialization and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyPublish(const Context<T>&) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_initialization_events “Declare initialization events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

publish must not be null.

See also

DeclareInitializationDiscreteUpdateEvent()

See also

DeclareInitializationUnrestrictedUpdateEvent()

See also

DeclareInitializationEvent()

DeclareInitializationUnrestrictedUpdateEvent(self: pydrake.systems.framework.LeafSystem, update: Callable[[pydrake.systems.framework.Context, pydrake.systems.framework.State], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that an UnrestrictedUpdate event should occur at initialization and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUpdate(const Context<T>&,
State<T>*) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_initialization_events “Declare initialization events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

See also

DeclareInitializationPublishEvent()

See also

DeclareInitializationDiscreteUpdateEvent()

See also

DeclareInitializationEvent()

DeclareNumericParameter(self: pydrake.systems.framework.LeafSystem, model_vector: pydrake.systems.framework.BasicVector) → int

Declares a numeric parameter using the given model_vector. LeafSystem’s default implementation of SetDefaultParameters() will reset parameters to their model vectors. If the model_vector declares any VectorBase::GetElementBounds() constraints, they will be re-declared as inequality constraints on this system (see DeclareInequalityConstraint()). Returns the index of the new parameter.

DeclarePeriodicDiscreteUpdateEvent(self: pydrake.systems.framework.LeafSystem, period_sec: float, offset_sec: float, update: Callable[[pydrake.systems.framework.Context, pydrake.systems.framework.DiscreteValues], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that a DiscreteUpdate event should occur periodically and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUpdate(const Context<T>&,
DiscreteValues<T>*) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_periodic_events “Declare periodic events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

See also

DeclarePeriodicPublishEvent()

See also

DeclarePeriodicUnrestrictedUpdateEvent()

See also

DeclarePeriodicEvent()

DeclarePeriodicEvent(self: pydrake.systems.framework.LeafSystem, period_sec: float, offset_sec: float, event: pydrake.systems.framework.Event) → None

(Advanced) Declares that a particular Event object should be dispatched periodically. This is the most general form for declaring periodic events and most users should use one of the other methods in this group instead.

See also

DeclarePeriodicPublishEvent()

See also

DeclarePeriodicDiscreteUpdateEvent()

See also

DeclarePeriodicUnrestrictedUpdateEvent()

See declare_periodic_events “Declare periodic events” for more information.

Depending on the type of event, when triggered it will be passed to the Publish, DiscreteUpdate, or UnrestrictedUpdate event dispatcher. If the event object contains a handler function, Drake’s default dispatchers will invoke that handler. If not, then no further action is taken. Thus an event with no handler has no effect unless its dispatcher has been overridden. We strongly recommend that you do not override the dispatcher and instead do supply a handler.

The given event object is deep-copied (cloned), and the copy is stored internally so you do not need to keep the object around after this call.

Precondition:

event’s associated trigger type must be TriggerType::kUnknown or already set to TriggerType::kPeriodic.

DeclarePeriodicPublishEvent(self: pydrake.systems.framework.LeafSystem, period_sec: float, offset_sec: float, publish: Callable[[pydrake.systems.framework.Context], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that a Publish event should occur periodically and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyPublish(const Context<T>&) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_periodic_events “Declare periodic events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

publish must not be null.

See also

DeclarePeriodicDiscreteUpdateEvent()

See also

DeclarePeriodicUnrestrictedUpdateEvent()

See also

DeclarePeriodicEvent()

DeclarePeriodicUnrestrictedUpdateEvent(self: pydrake.systems.framework.LeafSystem, period_sec: float, offset_sec: float, update: Callable[[pydrake.systems.framework.Context, pydrake.systems.framework.State], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that an UnrestrictedUpdate event should occur periodically and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUpdate(const Context<T>&, State<T>*) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_periodic_events “Declare periodic events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

See also

DeclarePeriodicPublishEvent()

See also

DeclarePeriodicDiscreteUpdateEvent()

See also

DeclarePeriodicEvent()

DeclarePerStepDiscreteUpdateEvent(self: pydrake.systems.framework.LeafSystem, update: Callable[[pydrake.systems.framework.Context, pydrake.systems.framework.DiscreteValues], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that a DiscreteUpdate event should occur at the start of every trajectory-advancing step and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUpdate(const Context<T>&,
DiscreteValues<T>*) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_per-step_events “Declare per-step events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

See also

DeclarePerStepPublishEvent()

See also

DeclarePerStepUnrestrictedUpdateEvent()

See also

DeclarePerStepEvent()

DeclarePerStepEvent(self: pydrake.systems.framework.LeafSystem, event: pydrake.systems.framework.Event) → None

(Advanced) Declares that a particular Event object should be dispatched at every trajectory-advancing step. Publish events are dispatched at the end of initialization and at the end of each step. Discrete- and unrestricted update events are dispatched at the start of each step. This is the most general form for declaring per-step events and most users should use one of the other methods in this group instead.

See also

DeclarePerStepPublishEvent()

See also

DeclarePerStepDiscreteUpdateEvent()

See also

DeclarePerStepUnrestrictedUpdateEvent()

See declare_per-step_events “Declare per-step events” for more information.

Depending on the type of event, at each step it will be passed to the Publish, DiscreteUpdate, or UnrestrictedUpdate event dispatcher. If the event object contains a handler function, Drake’s default dispatchers will invoke that handler. If not, then no further action is taken. Thus an event with no handler has no effect unless its dispatcher has been overridden. We strongly recommend that you do not override the dispatcher and instead do supply a handler.

The given event object is deep-copied (cloned), and the copy is stored internally so you do not need to keep the object around after this call.

Precondition:

event’s associated trigger type must be TriggerType::kUnknown or already set to TriggerType::kPerStep.

DeclarePerStepPublishEvent(self: pydrake.systems.framework.LeafSystem, publish: Callable[[pydrake.systems.framework.Context], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that a Publish event should occur at initialization and at the end of every trajectory-advancing step and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyPublish(const Context<T>&) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

Warning

These per-step publish events are independent of the Simulator’s optional “publish every time step” and “publish at initialization” features. Generally if you are declaring per-step publish events yourself you should turn off those Simulation options.

See declare_per-step_events “Declare per-step events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

publish must not be null.

See also

DeclarePerStepDiscreteUpdateEvent()

See also

DeclarePerStepUnrestrictedUpdateEvent()

See also

DeclarePerStepEvent()

See also

Simulator::set_publish_at_initialization()

See also

Simulator::set_publish_every_time_step()

DeclarePerStepUnrestrictedUpdateEvent(self: pydrake.systems.framework.LeafSystem, update: Callable[[pydrake.systems.framework.Context, pydrake.systems.framework.State], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that an UnrestrictedUpdate event should occur at the start of every trajectory-advancing step and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUpdate(const Context<T>&,
State<T>*) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_per-step_events “Declare per-step events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

See also

DeclarePerStepPublishEvent()

See also

DeclarePerStepDiscreteUpdateEvent()

See also

DeclarePerStepEvent()

DeclareStateOutputPort(*args, **kwargs)

Overloaded function.

1. DeclareStateOutputPort(self: pydrake.systems.framework.LeafSystem, name: Union[str, pydrake.systems.framework.UseDefaultName], state_index: pydrake.systems.framework.ContinuousStateIndex) -> pydrake.systems.framework.LeafOutputPort

Declares a vector-valued output port whose value is the continuous state of this system.

Parameter state_index:

must be ContinuousStateIndex(0) for now, since LeafSystem only supports a single continuous state group at the moment.

2. DeclareStateOutputPort(self: pydrake.systems.framework.LeafSystem, name: Union[str, pydrake.systems.framework.UseDefaultName], state_index: pydrake.systems.framework.DiscreteStateIndex) -> pydrake.systems.framework.LeafOutputPort

Declares a vector-valued output port whose value is the given discrete state group of this system.

3. DeclareStateOutputPort(self: pydrake.systems.framework.LeafSystem, name: Union[str, pydrake.systems.framework.UseDefaultName], state_index: pydrake.systems.framework.AbstractStateIndex) -> pydrake.systems.framework.LeafOutputPort

Declares an abstract-valued output port whose value is the given abstract state of this system.

DeclareVectorInputPort(*args, **kwargs)

Overloaded function.

1. DeclareVectorInputPort(self: pydrake.systems.framework.LeafSystem, name: str, model_vector: pydrake.systems.framework.BasicVector, random_type: Optional[pydrake.common.RandomDistribution] = None) -> pydrake.systems.framework.InputPort

Declares a vector-valued input port using the given model_vector. This is the best way to declare LeafSystem input ports that require subclasses of BasicVector. The port’s size and type will be the same as model_vector. If the port is intended to model a random noise or disturbance input, random_type can (optionally) be used to label it as such. If the model_vector declares any VectorBase::GetElementBounds() constraints, they will be re-declared as inequality constraints on this system (see DeclareInequalityConstraint()).

See also

System::DeclareInputPort() for more information.

2. DeclareVectorInputPort(self: pydrake.systems.framework.LeafSystem, name: str, size: int, random_type: Optional[pydrake.common.RandomDistribution] = None) -> pydrake.systems.framework.InputPort

Declares a vector-valued input port with type BasicVector and size size. If the port is intended to model a random noise or disturbance input, random_type can (optionally) be used to label it as such.

See also

System::DeclareInputPort() for more information.

DeclareVectorOutputPort(*args, **kwargs)

Overloaded function.

1. DeclareVectorOutputPort(self: pydrake.systems.framework.LeafSystem, name: str, model_value: pydrake.systems.framework.BasicVector, calc: Callable[[pydrake.systems.framework.Context, pydrake.systems.framework.BasicVector], None], prerequisites_of_calc: set[pydrake.systems.framework.DependencyTicket] = {DependencyTicket(15)}) -> pydrake.systems.framework.OutputPort

(Advanced) Declares a vector-valued output port using the given model_vector and a function for calculating the port’s value at runtime. The port’s size will be model_vector.size(), and the default allocator for the port will be model_vector.Clone(). Note that this takes the calculator function in its most generic form; if you have a member function available use one of the other signatures.

See also

LeafOutputPort::CalcVectorCallback

2. DeclareVectorOutputPort(self: pydrake.systems.framework.LeafSystem, name: str, size: int, calc: Callable[[pydrake.systems.framework.Context, pydrake.systems.framework.BasicVector], None], prerequisites_of_calc: set[pydrake.systems.framework.DependencyTicket] = {DependencyTicket(15)}) -> pydrake.systems.framework.OutputPort

(Advanced) Declares a vector-valued output port with type BasicVector<T> and size size, using the drake::dummy_value<T>, which is NaN when T = double. vector_calc_function is a function for calculating the port’s value at runtime. Note that this takes the calculator function in its most generic form; if you have a member function available use one of the other signatures.

See also

LeafOutputPort::CalcVectorCallback

DoCalcTimeDerivatives(self: pydrake.systems.framework.LeafSystem, arg0: pydrake.systems.framework.Context, arg1: pydrake.systems.framework.ContinuousState) → None

MakeWitnessFunction(*args, **kwargs)

Overloaded function.

1. MakeWitnessFunction(self: pydrake.systems.framework.LeafSystem, description: str, direction_type: pydrake.systems.framework.WitnessFunctionDirection, calc: Callable[[pydrake.systems.framework.Context], Optional[float]]) -> pydrake.systems.framework.WitnessFunction

Constructs the witness function with the given description (used primarily for debugging and logging), direction type, and calculator function; and with no event object.

Note

In order for the witness function to be used, you MUST overload System::DoGetWitnessFunctions().

2. MakeWitnessFunction(self: pydrake.systems.framework.LeafSystem, description: str, direction_type: pydrake.systems.framework.WitnessFunctionDirection, calc: Callable[[pydrake.systems.framework.Context], float], e: pydrake.systems.framework.Event) -> pydrake.systems.framework.WitnessFunction

Constructs the witness function with the given description (used primarily for debugging and logging), direction type, and calculator function, and with an object corresponding to the event that is to be dispatched when this witness function triggers. Example types of event objects are publish, discrete variable update, unrestricted update events. A clone of the event will be owned by the newly constructed WitnessFunction.

Note

In order for the witness function to be used, you MUST overload System::DoGetWitnessFunctions().

template pydrake.systems.framework.LeafSystem_

Instantiations: LeafSystem_[float], LeafSystem_[AutoDiffXd], LeafSystem_[Expression]

class pydrake.systems.framework.LeafSystem_[AutoDiffXd]

Bases: pydrake.systems.framework.System_[AutoDiffXd]

A superclass template that extends System with some convenience utilities that are not applicable to Diagrams.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd]) -> None

Default constructor that declares no inputs, outputs, state, parameters, events, nor scalar-type conversion support (AutoDiff, etc.). To enable AutoDiff support, use the SystemScalarConverter-based constructor.

2. __init__(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], converter: pydrake.systems.framework.SystemScalarConverter) -> None

Constructor that declares no inputs, outputs, state, parameters, or events, but allows subclasses to declare scalar-type conversion support (AutoDiff, etc.).

The scalar-type conversion support will use converter. To enable scalar-type conversion support, pass a SystemTypeTag<S>{} where S must be the exact class of this being constructed.

See system_scalar_conversion for detailed background and examples related to scalar-type conversion support.

DeclareAbstractInputPort(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], name: str, model_value: pydrake.common.value.AbstractValue) → pydrake.systems.framework.InputPort_[AutoDiffXd]

Declares an abstract-valued input port using the given model_value. This is the best way to declare LeafSystem abstract input ports.

Any port connected to this input, and any call to FixValue for this input, must provide for values whose type matches this model_value.

See also

System::DeclareInputPort() for more information.

DeclareAbstractOutputPort(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], name: str, alloc: Callable[[], pydrake.common.value.AbstractValue], calc: Callable[[pydrake.systems.framework.Context_[AutoDiffXd], pydrake.common.value.AbstractValue], None], prerequisites_of_calc: set[pydrake.systems.framework.DependencyTicket] = {DependencyTicket(15)}) → pydrake.systems.framework.OutputPort_[AutoDiffXd]

(Advanced) Declares an abstract-valued output port using the given allocator and calculator functions provided in their most generic forms. If you have a member function available use one of the other signatures.

See also

LeafOutputPort::AllocCallback, LeafOutputPort::CalcCallback

DeclareAbstractParameter(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], model_value: pydrake.common.value.AbstractValue) → int

Declares an abstract parameter using the given model_value. LeafSystem’s default implementation of SetDefaultParameters() will reset parameters to their model values. Returns the index of the new parameter.

DeclareAbstractState(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], model_value: pydrake.common.value.AbstractValue) → pydrake.systems.framework.AbstractStateIndex

Declares an abstract state variable and provides a model value for it. A Context obtained with CreateDefaultContext() will contain this abstract state variable initially set to a clone of the model_value given here. The actual concrete type is always preserved.

Parameter model_value:

The abstract state model value to be cloned as needed.

Returns

index of the declared abstract state variable.

DeclareContinuousState(*args, **kwargs)

Overloaded function.

1. DeclareContinuousState(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], num_state_variables: int) -> pydrake.systems.framework.ContinuousStateIndex

Declares that this System should reserve continuous state with num_state_variables state variables, which have no second-order structure.

Returns

index of the declared state (currently always zero).

2. DeclareContinuousState(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], num_q: int, num_v: int, num_z: int) -> pydrake.systems.framework.ContinuousStateIndex

Declares that this System should reserve continuous state with num_q generalized positions, num_v generalized velocities, and num_z miscellaneous state variables.

Returns

index of the declared state (currently always zero).

3. DeclareContinuousState(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], model_vector: pydrake.systems.framework.BasicVector_[AutoDiffXd]) -> pydrake.systems.framework.ContinuousStateIndex

Declares that this System should reserve continuous state with model_vector.size() miscellaneous state variables, stored in a vector cloned from model_vector.

Returns

index of the declared state (currently always zero).

4. DeclareContinuousState(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], model_vector: pydrake.systems.framework.BasicVector_[AutoDiffXd], num_q: int, num_v: int, num_z: int) -> pydrake.systems.framework.ContinuousStateIndex

Declares that this System should reserve continuous state with num_q generalized positions, num_v generalized velocities, and num_z miscellaneous state variables, stored in a vector cloned from model_vector. Aborts if model_vector has the wrong size. If the model_vector declares any VectorBase::GetElementBounds() constraints, they will be re-declared as inequality constraints on this system (see DeclareInequalityConstraint()).

Returns

index of the declared state (currently always zero).

DeclareDiscreteState(*args, **kwargs)

Overloaded function.

1. DeclareDiscreteState(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], model_vector: pydrake.systems.framework.BasicVector_[AutoDiffXd]) -> pydrake.systems.framework.DiscreteStateIndex

Declares a discrete state group with model_vector.size() state variables, stored in a vector cloned from model_vector (preserving the concrete type and value).

2. DeclareDiscreteState(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], vector: numpy.ndarray[object[m, 1]]) -> pydrake.systems.framework.DiscreteStateIndex

Declares a discrete state group with vector.size() state variables, stored in a BasicVector initialized with the contents of vector.

3. DeclareDiscreteState(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], num_state_variables: int) -> pydrake.systems.framework.DiscreteStateIndex

Declares a discrete state group with num_state_variables state variables, stored in a BasicVector initialized to be all-zero. If you want non-zero initial values, use an alternate DeclareDiscreteState() signature that accepts a model_vector parameter.

Precondition:

num_state_variables must be non-negative.

DeclareForcedDiscreteUpdateEvent(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], update: Callable[[pydrake.systems.framework.Context_[AutoDiffXd], pydrake.systems.framework.DiscreteValues_[AutoDiffXd]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares a function that is called whenever a user directly calls CalcForcedDiscreteVariableUpdate(const Context&, DiscreteValues<T>*). Multiple calls to DeclareForcedDiscreteUpdateEvent() will cause multiple handlers to be called upon a call to CalcForcedDiscreteVariableUpdate(); these handlers will be called with the same const Context in arbitrary order. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyDiscreteVariableUpdates(const Context<T>&,
DiscreteValues<T>*);

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_forced_events “Declare forced events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

DeclareForcedPublishEvent(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], publish: Callable[[pydrake.systems.framework.Context_[AutoDiffXd]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares a function that is called whenever a user directly calls ForcedPublish(const Context&). Multiple calls to DeclareForcedPublishEvent() will cause multiple handlers to be called upon a call to ForcedPublish(); these handlers which will be called with the same const Context in arbitrary order. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyPublish(const Context<T>&) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_forced_events “Declare forced events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

publish must not be null.

DeclareForcedUnrestrictedUpdateEvent(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], update: Callable[[pydrake.systems.framework.Context_[AutoDiffXd], pydrake.systems.framework.State_[AutoDiffXd]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares a function that is called whenever a user directly calls CalcForcedUnrestrictedUpdate(const Context&, State<T>*). Multiple calls to DeclareForcedUnrestrictedUpdateEvent() will cause multiple handlers to be called upon a call to CalcForcedUnrestrictedUpdate(); these handlers which will be called with the same const Context in arbitrary order.The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUnrestrictedUpdates(const Context<T>&,
State<T>*);

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_forced_events “Declare forced events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

DeclareInitializationDiscreteUpdateEvent(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], update: Callable[[pydrake.systems.framework.Context_[AutoDiffXd], pydrake.systems.framework.DiscreteValues_[AutoDiffXd]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that a DiscreteUpdate event should occur at initialization and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUpdate(const Context<T>&,
DiscreteValues<T>*) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_initialization_events “Declare initialization events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

See also

DeclareInitializationPublishEvent()

See also

DeclareInitializationUnrestrictedUpdateEvent()

See also

DeclareInitializationEvent()

DeclareInitializationEvent(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], event: pydrake.systems.framework.Event_[AutoDiffXd]) → None

(Advanced) Declares that a particular Event object should be dispatched at initialization. This is the most general form for declaring initialization events and most users should use one of the other methods in this group instead.

See also

DeclareInitializationPublishEvent()

See also

DeclareInitializationDiscreteUpdateEvent()

See also

DeclareInitializationUnrestrictedUpdateEvent()

See declare_initialization_events “Declare initialization events” for more information.

Depending on the type of event, on initialization it will be passed to the Publish, DiscreteUpdate, or UnrestrictedUpdate event dispatcher. If the event object contains a handler function, Drake’s default dispatchers will invoke that handler. If not, then no further action is taken. Thus an event with no handler has no effect unless its dispatcher has been overridden. We strongly recommend that you do not override the dispatcher and instead do supply a handler.

The given event object is deep-copied (cloned), and the copy is stored internally so you do not need to keep the object around after this call.

Precondition:

event’s associated trigger type must be TriggerType::kUnknown or already set to TriggerType::kInitialization.

DeclareInitializationPublishEvent(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], publish: Callable[[pydrake.systems.framework.Context_[AutoDiffXd]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that a Publish event should occur at initialization and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyPublish(const Context<T>&) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_initialization_events “Declare initialization events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

publish must not be null.

See also

DeclareInitializationDiscreteUpdateEvent()

See also

DeclareInitializationUnrestrictedUpdateEvent()

See also

DeclareInitializationEvent()

DeclareInitializationUnrestrictedUpdateEvent(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], update: Callable[[pydrake.systems.framework.Context_[AutoDiffXd], pydrake.systems.framework.State_[AutoDiffXd]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that an UnrestrictedUpdate event should occur at initialization and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUpdate(const Context<T>&,
State<T>*) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_initialization_events “Declare initialization events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

See also

DeclareInitializationPublishEvent()

See also

DeclareInitializationDiscreteUpdateEvent()

See also

DeclareInitializationEvent()

DeclareNumericParameter(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], model_vector: pydrake.systems.framework.BasicVector_[AutoDiffXd]) → int

Declares a numeric parameter using the given model_vector. LeafSystem’s default implementation of SetDefaultParameters() will reset parameters to their model vectors. If the model_vector declares any VectorBase::GetElementBounds() constraints, they will be re-declared as inequality constraints on this system (see DeclareInequalityConstraint()). Returns the index of the new parameter.

DeclarePeriodicDiscreteUpdateEvent(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], period_sec: float, offset_sec: float, update: Callable[[pydrake.systems.framework.Context_[AutoDiffXd], pydrake.systems.framework.DiscreteValues_[AutoDiffXd]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that a DiscreteUpdate event should occur periodically and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUpdate(const Context<T>&,
DiscreteValues<T>*) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_periodic_events “Declare periodic events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

See also

DeclarePeriodicPublishEvent()

See also

DeclarePeriodicUnrestrictedUpdateEvent()

See also

DeclarePeriodicEvent()

DeclarePeriodicEvent(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], period_sec: float, offset_sec: float, event: pydrake.systems.framework.Event_[AutoDiffXd]) → None

(Advanced) Declares that a particular Event object should be dispatched periodically. This is the most general form for declaring periodic events and most users should use one of the other methods in this group instead.

See also

DeclarePeriodicPublishEvent()

See also

DeclarePeriodicDiscreteUpdateEvent()

See also

DeclarePeriodicUnrestrictedUpdateEvent()

See declare_periodic_events “Declare periodic events” for more information.

Depending on the type of event, when triggered it will be passed to the Publish, DiscreteUpdate, or UnrestrictedUpdate event dispatcher. If the event object contains a handler function, Drake’s default dispatchers will invoke that handler. If not, then no further action is taken. Thus an event with no handler has no effect unless its dispatcher has been overridden. We strongly recommend that you do not override the dispatcher and instead do supply a handler.

The given event object is deep-copied (cloned), and the copy is stored internally so you do not need to keep the object around after this call.

Precondition:

event’s associated trigger type must be TriggerType::kUnknown or already set to TriggerType::kPeriodic.

DeclarePeriodicPublishEvent(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], period_sec: float, offset_sec: float, publish: Callable[[pydrake.systems.framework.Context_[AutoDiffXd]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that a Publish event should occur periodically and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyPublish(const Context<T>&) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_periodic_events “Declare periodic events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

publish must not be null.

See also

DeclarePeriodicDiscreteUpdateEvent()

See also

DeclarePeriodicUnrestrictedUpdateEvent()

See also

DeclarePeriodicEvent()

DeclarePeriodicUnrestrictedUpdateEvent(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], period_sec: float, offset_sec: float, update: Callable[[pydrake.systems.framework.Context_[AutoDiffXd], pydrake.systems.framework.State_[AutoDiffXd]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that an UnrestrictedUpdate event should occur periodically and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUpdate(const Context<T>&, State<T>*) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_periodic_events “Declare periodic events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

See also

DeclarePeriodicPublishEvent()

See also

DeclarePeriodicDiscreteUpdateEvent()

See also

DeclarePeriodicEvent()

DeclarePerStepDiscreteUpdateEvent(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], update: Callable[[pydrake.systems.framework.Context_[AutoDiffXd], pydrake.systems.framework.DiscreteValues_[AutoDiffXd]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that a DiscreteUpdate event should occur at the start of every trajectory-advancing step and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUpdate(const Context<T>&,
DiscreteValues<T>*) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_per-step_events “Declare per-step events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

See also

DeclarePerStepPublishEvent()

See also

DeclarePerStepUnrestrictedUpdateEvent()

See also

DeclarePerStepEvent()

DeclarePerStepEvent(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], event: pydrake.systems.framework.Event_[AutoDiffXd]) → None

(Advanced) Declares that a particular Event object should be dispatched at every trajectory-advancing step. Publish events are dispatched at the end of initialization and at the end of each step. Discrete- and unrestricted update events are dispatched at the start of each step. This is the most general form for declaring per-step events and most users should use one of the other methods in this group instead.

See also

DeclarePerStepPublishEvent()

See also

DeclarePerStepDiscreteUpdateEvent()

See also

DeclarePerStepUnrestrictedUpdateEvent()

See declare_per-step_events “Declare per-step events” for more information.

Depending on the type of event, at each step it will be passed to the Publish, DiscreteUpdate, or UnrestrictedUpdate event dispatcher. If the event object contains a handler function, Drake’s default dispatchers will invoke that handler. If not, then no further action is taken. Thus an event with no handler has no effect unless its dispatcher has been overridden. We strongly recommend that you do not override the dispatcher and instead do supply a handler.

The given event object is deep-copied (cloned), and the copy is stored internally so you do not need to keep the object around after this call.

Precondition:

event’s associated trigger type must be TriggerType::kUnknown or already set to TriggerType::kPerStep.

DeclarePerStepPublishEvent(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], publish: Callable[[pydrake.systems.framework.Context_[AutoDiffXd]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that a Publish event should occur at initialization and at the end of every trajectory-advancing step and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyPublish(const Context<T>&) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

Warning

These per-step publish events are independent of the Simulator’s optional “publish every time step” and “publish at initialization” features. Generally if you are declaring per-step publish events yourself you should turn off those Simulation options.

See declare_per-step_events “Declare per-step events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

publish must not be null.

See also

DeclarePerStepDiscreteUpdateEvent()

See also

DeclarePerStepUnrestrictedUpdateEvent()

See also

DeclarePerStepEvent()

See also

Simulator::set_publish_at_initialization()

See also

Simulator::set_publish_every_time_step()

DeclarePerStepUnrestrictedUpdateEvent(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], update: Callable[[pydrake.systems.framework.Context_[AutoDiffXd], pydrake.systems.framework.State_[AutoDiffXd]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that an UnrestrictedUpdate event should occur at the start of every trajectory-advancing step and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUpdate(const Context<T>&,
State<T>*) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_per-step_events “Declare per-step events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

See also

DeclarePerStepPublishEvent()

See also

DeclarePerStepDiscreteUpdateEvent()

See also

DeclarePerStepEvent()

DeclareStateOutputPort(*args, **kwargs)

Overloaded function.

1. DeclareStateOutputPort(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], name: Union[str, pydrake.systems.framework.UseDefaultName], state_index: pydrake.systems.framework.ContinuousStateIndex) -> pydrake.systems.framework.LeafOutputPort_[AutoDiffXd]

Declares a vector-valued output port whose value is the continuous state of this system.

Parameter state_index:

must be ContinuousStateIndex(0) for now, since LeafSystem only supports a single continuous state group at the moment.

2. DeclareStateOutputPort(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], name: Union[str, pydrake.systems.framework.UseDefaultName], state_index: pydrake.systems.framework.DiscreteStateIndex) -> pydrake.systems.framework.LeafOutputPort_[AutoDiffXd]

Declares a vector-valued output port whose value is the given discrete state group of this system.

3. DeclareStateOutputPort(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], name: Union[str, pydrake.systems.framework.UseDefaultName], state_index: pydrake.systems.framework.AbstractStateIndex) -> pydrake.systems.framework.LeafOutputPort_[AutoDiffXd]

Declares an abstract-valued output port whose value is the given abstract state of this system.

DeclareVectorInputPort(*args, **kwargs)

Overloaded function.

1. DeclareVectorInputPort(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], name: str, model_vector: pydrake.systems.framework.BasicVector_[AutoDiffXd], random_type: Optional[pydrake.common.RandomDistribution] = None) -> pydrake.systems.framework.InputPort_[AutoDiffXd]

Declares a vector-valued input port using the given model_vector. This is the best way to declare LeafSystem input ports that require subclasses of BasicVector. The port’s size and type will be the same as model_vector. If the port is intended to model a random noise or disturbance input, random_type can (optionally) be used to label it as such. If the model_vector declares any VectorBase::GetElementBounds() constraints, they will be re-declared as inequality constraints on this system (see DeclareInequalityConstraint()).

See also

System::DeclareInputPort() for more information.

2. DeclareVectorInputPort(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], name: str, size: int, random_type: Optional[pydrake.common.RandomDistribution] = None) -> pydrake.systems.framework.InputPort_[AutoDiffXd]

Declares a vector-valued input port with type BasicVector and size size. If the port is intended to model a random noise or disturbance input, random_type can (optionally) be used to label it as such.

See also

System::DeclareInputPort() for more information.

DeclareVectorOutputPort(*args, **kwargs)

Overloaded function.

1. DeclareVectorOutputPort(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], name: str, model_value: pydrake.systems.framework.BasicVector_[AutoDiffXd], calc: Callable[[pydrake.systems.framework.Context_[AutoDiffXd], pydrake.systems.framework.BasicVector_[AutoDiffXd]], None], prerequisites_of_calc: set[pydrake.systems.framework.DependencyTicket] = {DependencyTicket(15)}) -> pydrake.systems.framework.OutputPort_[AutoDiffXd]

(Advanced) Declares a vector-valued output port using the given model_vector and a function for calculating the port’s value at runtime. The port’s size will be model_vector.size(), and the default allocator for the port will be model_vector.Clone(). Note that this takes the calculator function in its most generic form; if you have a member function available use one of the other signatures.

See also

LeafOutputPort::CalcVectorCallback

2. DeclareVectorOutputPort(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], name: str, size: int, calc: Callable[[pydrake.systems.framework.Context_[AutoDiffXd], pydrake.systems.framework.BasicVector_[AutoDiffXd]], None], prerequisites_of_calc: set[pydrake.systems.framework.DependencyTicket] = {DependencyTicket(15)}) -> pydrake.systems.framework.OutputPort_[AutoDiffXd]

(Advanced) Declares a vector-valued output port with type BasicVector<T> and size size, using the drake::dummy_value<T>, which is NaN when T = double. vector_calc_function is a function for calculating the port’s value at runtime. Note that this takes the calculator function in its most generic form; if you have a member function available use one of the other signatures.

See also

LeafOutputPort::CalcVectorCallback

DoCalcTimeDerivatives(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], arg0: pydrake.systems.framework.Context_[AutoDiffXd], arg1: pydrake.systems.framework.ContinuousState_[AutoDiffXd]) → None

MakeWitnessFunction(*args, **kwargs)

Overloaded function.

1. MakeWitnessFunction(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], description: str, direction_type: pydrake.systems.framework.WitnessFunctionDirection, calc: Callable[[pydrake.systems.framework.Context_[AutoDiffXd]], Optional[pydrake.autodiffutils.AutoDiffXd]]) -> pydrake.systems.framework.WitnessFunction_[AutoDiffXd]

Constructs the witness function with the given description (used primarily for debugging and logging), direction type, and calculator function; and with no event object.

Note

In order for the witness function to be used, you MUST overload System::DoGetWitnessFunctions().

2. MakeWitnessFunction(self: pydrake.systems.framework.LeafSystem_[AutoDiffXd], description: str, direction_type: pydrake.systems.framework.WitnessFunctionDirection, calc: Callable[[pydrake.systems.framework.Context_[AutoDiffXd]], pydrake.autodiffutils.AutoDiffXd], e: pydrake.systems.framework.Event_[AutoDiffXd]) -> pydrake.systems.framework.WitnessFunction_[AutoDiffXd]

Constructs the witness function with the given description (used primarily for debugging and logging), direction type, and calculator function, and with an object corresponding to the event that is to be dispatched when this witness function triggers. Example types of event objects are publish, discrete variable update, unrestricted update events. A clone of the event will be owned by the newly constructed WitnessFunction.

Note

In order for the witness function to be used, you MUST overload System::DoGetWitnessFunctions().

class pydrake.systems.framework.LeafSystem_[Expression]

Bases: pydrake.systems.framework.System_[Expression]

A superclass template that extends System with some convenience utilities that are not applicable to Diagrams.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.LeafSystem_[Expression]) -> None

Default constructor that declares no inputs, outputs, state, parameters, events, nor scalar-type conversion support (AutoDiff, etc.). To enable AutoDiff support, use the SystemScalarConverter-based constructor.

2. __init__(self: pydrake.systems.framework.LeafSystem_[Expression], converter: pydrake.systems.framework.SystemScalarConverter) -> None

Constructor that declares no inputs, outputs, state, parameters, or events, but allows subclasses to declare scalar-type conversion support (AutoDiff, etc.).

The scalar-type conversion support will use converter. To enable scalar-type conversion support, pass a SystemTypeTag<S>{} where S must be the exact class of this being constructed.

See system_scalar_conversion for detailed background and examples related to scalar-type conversion support.

DeclareAbstractInputPort(self: pydrake.systems.framework.LeafSystem_[Expression], name: str, model_value: pydrake.common.value.AbstractValue) → pydrake.systems.framework.InputPort_[Expression]

Declares an abstract-valued input port using the given model_value. This is the best way to declare LeafSystem abstract input ports.

Any port connected to this input, and any call to FixValue for this input, must provide for values whose type matches this model_value.

See also

System::DeclareInputPort() for more information.

DeclareAbstractOutputPort(self: pydrake.systems.framework.LeafSystem_[Expression], name: str, alloc: Callable[[], pydrake.common.value.AbstractValue], calc: Callable[[pydrake.systems.framework.Context_[Expression], pydrake.common.value.AbstractValue], None], prerequisites_of_calc: set[pydrake.systems.framework.DependencyTicket] = {DependencyTicket(15)}) → pydrake.systems.framework.OutputPort_[Expression]

(Advanced) Declares an abstract-valued output port using the given allocator and calculator functions provided in their most generic forms. If you have a member function available use one of the other signatures.

See also

LeafOutputPort::AllocCallback, LeafOutputPort::CalcCallback

DeclareAbstractParameter(self: pydrake.systems.framework.LeafSystem_[Expression], model_value: pydrake.common.value.AbstractValue) → int

Declares an abstract parameter using the given model_value. LeafSystem’s default implementation of SetDefaultParameters() will reset parameters to their model values. Returns the index of the new parameter.

DeclareAbstractState(self: pydrake.systems.framework.LeafSystem_[Expression], model_value: pydrake.common.value.AbstractValue) → pydrake.systems.framework.AbstractStateIndex

Declares an abstract state variable and provides a model value for it. A Context obtained with CreateDefaultContext() will contain this abstract state variable initially set to a clone of the model_value given here. The actual concrete type is always preserved.

Parameter model_value:

The abstract state model value to be cloned as needed.

Returns

index of the declared abstract state variable.

DeclareContinuousState(*args, **kwargs)

Overloaded function.

1. DeclareContinuousState(self: pydrake.systems.framework.LeafSystem_[Expression], num_state_variables: int) -> pydrake.systems.framework.ContinuousStateIndex

Declares that this System should reserve continuous state with num_state_variables state variables, which have no second-order structure.

Returns

index of the declared state (currently always zero).

2. DeclareContinuousState(self: pydrake.systems.framework.LeafSystem_[Expression], num_q: int, num_v: int, num_z: int) -> pydrake.systems.framework.ContinuousStateIndex

Declares that this System should reserve continuous state with num_q generalized positions, num_v generalized velocities, and num_z miscellaneous state variables.

Returns

index of the declared state (currently always zero).

3. DeclareContinuousState(self: pydrake.systems.framework.LeafSystem_[Expression], model_vector: pydrake.systems.framework.BasicVector_[Expression]) -> pydrake.systems.framework.ContinuousStateIndex

Declares that this System should reserve continuous state with model_vector.size() miscellaneous state variables, stored in a vector cloned from model_vector.

Returns

index of the declared state (currently always zero).

4. DeclareContinuousState(self: pydrake.systems.framework.LeafSystem_[Expression], model_vector: pydrake.systems.framework.BasicVector_[Expression], num_q: int, num_v: int, num_z: int) -> pydrake.systems.framework.ContinuousStateIndex

Declares that this System should reserve continuous state with num_q generalized positions, num_v generalized velocities, and num_z miscellaneous state variables, stored in a vector cloned from model_vector. Aborts if model_vector has the wrong size. If the model_vector declares any VectorBase::GetElementBounds() constraints, they will be re-declared as inequality constraints on this system (see DeclareInequalityConstraint()).

Returns

index of the declared state (currently always zero).

DeclareDiscreteState(*args, **kwargs)

Overloaded function.

1. DeclareDiscreteState(self: pydrake.systems.framework.LeafSystem_[Expression], model_vector: pydrake.systems.framework.BasicVector_[Expression]) -> pydrake.systems.framework.DiscreteStateIndex

Declares a discrete state group with model_vector.size() state variables, stored in a vector cloned from model_vector (preserving the concrete type and value).

2. DeclareDiscreteState(self: pydrake.systems.framework.LeafSystem_[Expression], vector: numpy.ndarray[object[m, 1]]) -> pydrake.systems.framework.DiscreteStateIndex

Declares a discrete state group with vector.size() state variables, stored in a BasicVector initialized with the contents of vector.

3. DeclareDiscreteState(self: pydrake.systems.framework.LeafSystem_[Expression], num_state_variables: int) -> pydrake.systems.framework.DiscreteStateIndex

Declares a discrete state group with num_state_variables state variables, stored in a BasicVector initialized to be all-zero. If you want non-zero initial values, use an alternate DeclareDiscreteState() signature that accepts a model_vector parameter.

Precondition:

num_state_variables must be non-negative.

DeclareForcedDiscreteUpdateEvent(self: pydrake.systems.framework.LeafSystem_[Expression], update: Callable[[pydrake.systems.framework.Context_[Expression], pydrake.systems.framework.DiscreteValues_[Expression]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares a function that is called whenever a user directly calls CalcForcedDiscreteVariableUpdate(const Context&, DiscreteValues<T>*). Multiple calls to DeclareForcedDiscreteUpdateEvent() will cause multiple handlers to be called upon a call to CalcForcedDiscreteVariableUpdate(); these handlers will be called with the same const Context in arbitrary order. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyDiscreteVariableUpdates(const Context<T>&,
DiscreteValues<T>*);

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_forced_events “Declare forced events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

DeclareForcedPublishEvent(self: pydrake.systems.framework.LeafSystem_[Expression], publish: Callable[[pydrake.systems.framework.Context_[Expression]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares a function that is called whenever a user directly calls ForcedPublish(const Context&). Multiple calls to DeclareForcedPublishEvent() will cause multiple handlers to be called upon a call to ForcedPublish(); these handlers which will be called with the same const Context in arbitrary order. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyPublish(const Context<T>&) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_forced_events “Declare forced events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

publish must not be null.

DeclareForcedUnrestrictedUpdateEvent(self: pydrake.systems.framework.LeafSystem_[Expression], update: Callable[[pydrake.systems.framework.Context_[Expression], pydrake.systems.framework.State_[Expression]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares a function that is called whenever a user directly calls CalcForcedUnrestrictedUpdate(const Context&, State<T>*). Multiple calls to DeclareForcedUnrestrictedUpdateEvent() will cause multiple handlers to be called upon a call to CalcForcedUnrestrictedUpdate(); these handlers which will be called with the same const Context in arbitrary order.The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUnrestrictedUpdates(const Context<T>&,
State<T>*);

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_forced_events “Declare forced events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

DeclareInitializationDiscreteUpdateEvent(self: pydrake.systems.framework.LeafSystem_[Expression], update: Callable[[pydrake.systems.framework.Context_[Expression], pydrake.systems.framework.DiscreteValues_[Expression]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that a DiscreteUpdate event should occur at initialization and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUpdate(const Context<T>&,
DiscreteValues<T>*) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_initialization_events “Declare initialization events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

See also

DeclareInitializationPublishEvent()

See also

DeclareInitializationUnrestrictedUpdateEvent()

See also

DeclareInitializationEvent()

DeclareInitializationEvent(self: pydrake.systems.framework.LeafSystem_[Expression], event: pydrake.systems.framework.Event_[Expression]) → None

(Advanced) Declares that a particular Event object should be dispatched at initialization. This is the most general form for declaring initialization events and most users should use one of the other methods in this group instead.

See also

DeclareInitializationPublishEvent()

See also

DeclareInitializationDiscreteUpdateEvent()

See also

DeclareInitializationUnrestrictedUpdateEvent()

See declare_initialization_events “Declare initialization events” for more information.

Depending on the type of event, on initialization it will be passed to the Publish, DiscreteUpdate, or UnrestrictedUpdate event dispatcher. If the event object contains a handler function, Drake’s default dispatchers will invoke that handler. If not, then no further action is taken. Thus an event with no handler has no effect unless its dispatcher has been overridden. We strongly recommend that you do not override the dispatcher and instead do supply a handler.

The given event object is deep-copied (cloned), and the copy is stored internally so you do not need to keep the object around after this call.

Precondition:

event’s associated trigger type must be TriggerType::kUnknown or already set to TriggerType::kInitialization.

DeclareInitializationPublishEvent(self: pydrake.systems.framework.LeafSystem_[Expression], publish: Callable[[pydrake.systems.framework.Context_[Expression]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that a Publish event should occur at initialization and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyPublish(const Context<T>&) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_initialization_events “Declare initialization events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

publish must not be null.

See also

DeclareInitializationDiscreteUpdateEvent()

See also

DeclareInitializationUnrestrictedUpdateEvent()

See also

DeclareInitializationEvent()

DeclareInitializationUnrestrictedUpdateEvent(self: pydrake.systems.framework.LeafSystem_[Expression], update: Callable[[pydrake.systems.framework.Context_[Expression], pydrake.systems.framework.State_[Expression]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that an UnrestrictedUpdate event should occur at initialization and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUpdate(const Context<T>&,
State<T>*) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_initialization_events “Declare initialization events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

See also

DeclareInitializationPublishEvent()

See also

DeclareInitializationDiscreteUpdateEvent()

See also

DeclareInitializationEvent()

DeclareNumericParameter(self: pydrake.systems.framework.LeafSystem_[Expression], model_vector: pydrake.systems.framework.BasicVector_[Expression]) → int

Declares a numeric parameter using the given model_vector. LeafSystem’s default implementation of SetDefaultParameters() will reset parameters to their model vectors. If the model_vector declares any VectorBase::GetElementBounds() constraints, they will be re-declared as inequality constraints on this system (see DeclareInequalityConstraint()). Returns the index of the new parameter.

DeclarePeriodicDiscreteUpdateEvent(self: pydrake.systems.framework.LeafSystem_[Expression], period_sec: float, offset_sec: float, update: Callable[[pydrake.systems.framework.Context_[Expression], pydrake.systems.framework.DiscreteValues_[Expression]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that a DiscreteUpdate event should occur periodically and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUpdate(const Context<T>&,
DiscreteValues<T>*) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_periodic_events “Declare periodic events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

See also

DeclarePeriodicPublishEvent()

See also

DeclarePeriodicUnrestrictedUpdateEvent()

See also

DeclarePeriodicEvent()

DeclarePeriodicEvent(self: pydrake.systems.framework.LeafSystem_[Expression], period_sec: float, offset_sec: float, event: pydrake.systems.framework.Event_[Expression]) → None

(Advanced) Declares that a particular Event object should be dispatched periodically. This is the most general form for declaring periodic events and most users should use one of the other methods in this group instead.

See also

DeclarePeriodicPublishEvent()

See also

DeclarePeriodicDiscreteUpdateEvent()

See also

DeclarePeriodicUnrestrictedUpdateEvent()

See declare_periodic_events “Declare periodic events” for more information.

Depending on the type of event, when triggered it will be passed to the Publish, DiscreteUpdate, or UnrestrictedUpdate event dispatcher. If the event object contains a handler function, Drake’s default dispatchers will invoke that handler. If not, then no further action is taken. Thus an event with no handler has no effect unless its dispatcher has been overridden. We strongly recommend that you do not override the dispatcher and instead do supply a handler.

The given event object is deep-copied (cloned), and the copy is stored internally so you do not need to keep the object around after this call.

Precondition:

event’s associated trigger type must be TriggerType::kUnknown or already set to TriggerType::kPeriodic.

DeclarePeriodicPublishEvent(self: pydrake.systems.framework.LeafSystem_[Expression], period_sec: float, offset_sec: float, publish: Callable[[pydrake.systems.framework.Context_[Expression]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that a Publish event should occur periodically and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyPublish(const Context<T>&) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_periodic_events “Declare periodic events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

publish must not be null.

See also

DeclarePeriodicDiscreteUpdateEvent()

See also

DeclarePeriodicUnrestrictedUpdateEvent()

See also

DeclarePeriodicEvent()

DeclarePeriodicUnrestrictedUpdateEvent(self: pydrake.systems.framework.LeafSystem_[Expression], period_sec: float, offset_sec: float, update: Callable[[pydrake.systems.framework.Context_[Expression], pydrake.systems.framework.State_[Expression]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that an UnrestrictedUpdate event should occur periodically and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUpdate(const Context<T>&, State<T>*) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_periodic_events “Declare periodic events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

See also

DeclarePeriodicPublishEvent()

See also

DeclarePeriodicDiscreteUpdateEvent()

See also

DeclarePeriodicEvent()

DeclarePerStepDiscreteUpdateEvent(self: pydrake.systems.framework.LeafSystem_[Expression], update: Callable[[pydrake.systems.framework.Context_[Expression], pydrake.systems.framework.DiscreteValues_[Expression]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that a DiscreteUpdate event should occur at the start of every trajectory-advancing step and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUpdate(const Context<T>&,
DiscreteValues<T>*) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_per-step_events “Declare per-step events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

See also

DeclarePerStepPublishEvent()

See also

DeclarePerStepUnrestrictedUpdateEvent()

See also

DeclarePerStepEvent()

DeclarePerStepEvent(self: pydrake.systems.framework.LeafSystem_[Expression], event: pydrake.systems.framework.Event_[Expression]) → None

(Advanced) Declares that a particular Event object should be dispatched at every trajectory-advancing step. Publish events are dispatched at the end of initialization and at the end of each step. Discrete- and unrestricted update events are dispatched at the start of each step. This is the most general form for declaring per-step events and most users should use one of the other methods in this group instead.

See also

DeclarePerStepPublishEvent()

See also

DeclarePerStepDiscreteUpdateEvent()

See also

DeclarePerStepUnrestrictedUpdateEvent()

See declare_per-step_events “Declare per-step events” for more information.

Depending on the type of event, at each step it will be passed to the Publish, DiscreteUpdate, or UnrestrictedUpdate event dispatcher. If the event object contains a handler function, Drake’s default dispatchers will invoke that handler. If not, then no further action is taken. Thus an event with no handler has no effect unless its dispatcher has been overridden. We strongly recommend that you do not override the dispatcher and instead do supply a handler.

The given event object is deep-copied (cloned), and the copy is stored internally so you do not need to keep the object around after this call.

Precondition:

event’s associated trigger type must be TriggerType::kUnknown or already set to TriggerType::kPerStep.

DeclarePerStepPublishEvent(self: pydrake.systems.framework.LeafSystem_[Expression], publish: Callable[[pydrake.systems.framework.Context_[Expression]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that a Publish event should occur at initialization and at the end of every trajectory-advancing step and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyPublish(const Context<T>&) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

Warning

These per-step publish events are independent of the Simulator’s optional “publish every time step” and “publish at initialization” features. Generally if you are declaring per-step publish events yourself you should turn off those Simulation options.

See declare_per-step_events “Declare per-step events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

publish must not be null.

See also

DeclarePerStepDiscreteUpdateEvent()

See also

DeclarePerStepUnrestrictedUpdateEvent()

See also

DeclarePerStepEvent()

See also

Simulator::set_publish_at_initialization()

See also

Simulator::set_publish_every_time_step()

DeclarePerStepUnrestrictedUpdateEvent(self: pydrake.systems.framework.LeafSystem_[Expression], update: Callable[[pydrake.systems.framework.Context_[Expression], pydrake.systems.framework.State_[Expression]], Optional[pydrake.systems.framework.EventStatus]]) → None

Declares that an UnrestrictedUpdate event should occur at the start of every trajectory-advancing step and that it should invoke the given event handler method. The handler should be a class member function (method) with this signature:

Click to expand C++ code...

EventStatus MySystem::MyUpdate(const Context<T>&,
State<T>*) const;

where MySystem is a class derived from LeafSystem<T> and the method name is arbitrary.

See declare_per-step_events “Declare per-step events” for more information.

Precondition:

this must be dynamic_cast-able to MySystem.

Precondition:

update must not be null.

See also

DeclarePerStepPublishEvent()

See also

DeclarePerStepDiscreteUpdateEvent()

See also

DeclarePerStepEvent()

DeclareStateOutputPort(*args, **kwargs)

Overloaded function.

1. DeclareStateOutputPort(self: pydrake.systems.framework.LeafSystem_[Expression], name: Union[str, pydrake.systems.framework.UseDefaultName], state_index: pydrake.systems.framework.ContinuousStateIndex) -> pydrake.systems.framework.LeafOutputPort_[Expression]

Declares a vector-valued output port whose value is the continuous state of this system.

Parameter state_index:

must be ContinuousStateIndex(0) for now, since LeafSystem only supports a single continuous state group at the moment.

2. DeclareStateOutputPort(self: pydrake.systems.framework.LeafSystem_[Expression], name: Union[str, pydrake.systems.framework.UseDefaultName], state_index: pydrake.systems.framework.DiscreteStateIndex) -> pydrake.systems.framework.LeafOutputPort_[Expression]

Declares a vector-valued output port whose value is the given discrete state group of this system.

3. DeclareStateOutputPort(self: pydrake.systems.framework.LeafSystem_[Expression], name: Union[str, pydrake.systems.framework.UseDefaultName], state_index: pydrake.systems.framework.AbstractStateIndex) -> pydrake.systems.framework.LeafOutputPort_[Expression]

Declares an abstract-valued output port whose value is the given abstract state of this system.

DeclareVectorInputPort(*args, **kwargs)

Overloaded function.

1. DeclareVectorInputPort(self: pydrake.systems.framework.LeafSystem_[Expression], name: str, model_vector: pydrake.systems.framework.BasicVector_[Expression], random_type: Optional[pydrake.common.RandomDistribution] = None) -> pydrake.systems.framework.InputPort_[Expression]

Declares a vector-valued input port using the given model_vector. This is the best way to declare LeafSystem input ports that require subclasses of BasicVector. The port’s size and type will be the same as model_vector. If the port is intended to model a random noise or disturbance input, random_type can (optionally) be used to label it as such. If the model_vector declares any VectorBase::GetElementBounds() constraints, they will be re-declared as inequality constraints on this system (see DeclareInequalityConstraint()).

See also

System::DeclareInputPort() for more information.

2. DeclareVectorInputPort(self: pydrake.systems.framework.LeafSystem_[Expression], name: str, size: int, random_type: Optional[pydrake.common.RandomDistribution] = None) -> pydrake.systems.framework.InputPort_[Expression]

Declares a vector-valued input port with type BasicVector and size size. If the port is intended to model a random noise or disturbance input, random_type can (optionally) be used to label it as such.

See also

System::DeclareInputPort() for more information.

DeclareVectorOutputPort(*args, **kwargs)

Overloaded function.

1. DeclareVectorOutputPort(self: pydrake.systems.framework.LeafSystem_[Expression], name: str, model_value: pydrake.systems.framework.BasicVector_[Expression], calc: Callable[[pydrake.systems.framework.Context_[Expression], pydrake.systems.framework.BasicVector_[Expression]], None], prerequisites_of_calc: set[pydrake.systems.framework.DependencyTicket] = {DependencyTicket(15)}) -> pydrake.systems.framework.OutputPort_[Expression]

(Advanced) Declares a vector-valued output port using the given model_vector and a function for calculating the port’s value at runtime. The port’s size will be model_vector.size(), and the default allocator for the port will be model_vector.Clone(). Note that this takes the calculator function in its most generic form; if you have a member function available use one of the other signatures.

See also

LeafOutputPort::CalcVectorCallback

2. DeclareVectorOutputPort(self: pydrake.systems.framework.LeafSystem_[Expression], name: str, size: int, calc: Callable[[pydrake.systems.framework.Context_[Expression], pydrake.systems.framework.BasicVector_[Expression]], None], prerequisites_of_calc: set[pydrake.systems.framework.DependencyTicket] = {DependencyTicket(15)}) -> pydrake.systems.framework.OutputPort_[Expression]

(Advanced) Declares a vector-valued output port with type BasicVector<T> and size size, using the drake::dummy_value<T>, which is NaN when T = double. vector_calc_function is a function for calculating the port’s value at runtime. Note that this takes the calculator function in its most generic form; if you have a member function available use one of the other signatures.

See also

LeafOutputPort::CalcVectorCallback

DoCalcTimeDerivatives(self: pydrake.systems.framework.LeafSystem_[Expression], arg0: pydrake.systems.framework.Context_[Expression], arg1: pydrake.systems.framework.ContinuousState_[Expression]) → None

MakeWitnessFunction(*args, **kwargs)

Overloaded function.

1. MakeWitnessFunction(self: pydrake.systems.framework.LeafSystem_[Expression], description: str, direction_type: pydrake.systems.framework.WitnessFunctionDirection, calc: Callable[[pydrake.systems.framework.Context_[Expression]], Optional[pydrake.symbolic.Expression]]) -> pydrake.systems.framework.WitnessFunction_[Expression]

Constructs the witness function with the given description (used primarily for debugging and logging), direction type, and calculator function; and with no event object.

Note

In order for the witness function to be used, you MUST overload System::DoGetWitnessFunctions().

2. MakeWitnessFunction(self: pydrake.systems.framework.LeafSystem_[Expression], description: str, direction_type: pydrake.systems.framework.WitnessFunctionDirection, calc: Callable[[pydrake.systems.framework.Context_[Expression]], pydrake.symbolic.Expression], e: pydrake.systems.framework.Event_[Expression]) -> pydrake.systems.framework.WitnessFunction_[Expression]

Constructs the witness function with the given description (used primarily for debugging and logging), direction type, and calculator function, and with an object corresponding to the event that is to be dispatched when this witness function triggers. Example types of event objects are publish, discrete variable update, unrestricted update events. A clone of the event will be owned by the newly constructed WitnessFunction.

Note

In order for the witness function to be used, you MUST overload System::DoGetWitnessFunctions().

class pydrake.systems.framework.NumericParameterIndex

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.NumericParameterIndex) -> None

Default constructor; the result is an invalid index. This only exists to serve applications which require a default constructor.

2. __init__(self: pydrake.systems.framework.NumericParameterIndex, arg0: int) -> None

Construction from a non-negative int value. The value must lie in the range of [0, 2³¹). Constructor only promises to test validity in Debug build.

is_valid(self: pydrake.systems.framework.NumericParameterIndex) → bool

Reports if the index is valid–the only operation on an invalid index that doesn’t throw an exception in Debug builds.

class pydrake.systems.framework.OutputPort

An OutputPort belongs to a System and represents the properties of one of that System’s output ports. OutputPort objects are assigned OutputPortIndex values in the order they are declared; these are unique within a single System.

An output port can be considered a “window” into a System that permits controlled exposure of one of the values contained in that System’s Context at run time. Input ports of other subsystems may be connected to an output port to construct system diagrams with carefully managed interdependencies.

The exposed value may be the result of an output computation, or it may simply expose some other value contained in the Context, such as the values of state variables. The Context handles caching of output port values and tracks dependencies to ensure that the values are valid with respect to their prerequisites. Leaf systems provide for the production of output port values, by computation or forwarding from other values within the associated leaf context. A diagram’s output ports, on the other hand, are exported from output ports of its contained subsystems.

An output port’s value is always stored as an AbstractValue, but we also provide special handling for output ports known to have numeric (vector) values. Vector-valued ports may specify a particular vector length, or may leave that to be determined at runtime.

OutputPort objects support three important operations:

• Allocate() returns an object that can hold the port’s value.

• Calc() unconditionally computes the port’s value.

• Eval() updates a cached value if necessary.

Note

This class is templated; see OutputPort_ for the list of instantiations.

__init__(*args, **kwargs)

Allocate(self: pydrake.systems.framework.OutputPort) → pydrake.common.value.AbstractValue

Allocates a concrete object suitable for holding the value to be exposed by this output port, and returns that as an AbstractValue. The returned object will never be null. If Drake assertions are enabled (typically only in Debug builds), validates for a vector-valued port that the returned AbstractValue is actually a BasicVector-derived type and that it has an acceptable size.

Note

If this is a vector-valued port, the underlying type is Value<BasicVector<T>>; downcast to BasicVector<T> before downcasting to the specific BasicVector subclass.

Eval(self: pydrake.systems.framework.OutputPort, arg0: pydrake.systems.framework.Context) → object

EvalAbstract(self: pydrake.systems.framework.OutputPort, context: pydrake.systems.framework.Context) → object

(Advanced.) Returns the value of this output port, typed as an AbstractValue. Most users should call Eval() instead. This method is only needed when the result will be passed into some other API that only accepts an AbstractValue.

EvalBasicVector(self: pydrake.systems.framework.OutputPort, context: pydrake.systems.framework.Context) → object

(Advanced.) Returns the value of this output port, typed as a BasicVector. Most users should call Eval() instead. This method is only needed when the result will be passed into some other API that only accepts a BasicVector.

get_data_type(self: pydrake.systems.framework.OutputPort) → pydrake.systems.framework.PortDataType

Returns the port data type.

get_index(self: pydrake.systems.framework.OutputPort) → pydrake.systems.framework.OutputPortIndex

Returns the index of this output port within the owning System. For a Diagram, this will be the index within the Diagram, not the index within the LeafSystem whose output port was forwarded.

get_name(self: pydrake.systems.framework.OutputPort) → str

Get port name.

get_system(self: pydrake.systems.framework.OutputPort) → drake::systems::System<double>

Returns a reference to the System that owns this output port. Note that for a diagram output port this will be the diagram, not the leaf system whose output port was forwarded.

size(self: pydrake.systems.framework.OutputPort) → int

Returns the fixed size expected for a vector-valued port. Not meaningful for abstract-valued ports.

template pydrake.systems.framework.OutputPort_

Instantiations: OutputPort_[float], OutputPort_[AutoDiffXd], OutputPort_[Expression]

class pydrake.systems.framework.OutputPort_[AutoDiffXd]

An OutputPort belongs to a System and represents the properties of one of that System’s output ports. OutputPort objects are assigned OutputPortIndex values in the order they are declared; these are unique within a single System.

An output port can be considered a “window” into a System that permits controlled exposure of one of the values contained in that System’s Context at run time. Input ports of other subsystems may be connected to an output port to construct system diagrams with carefully managed interdependencies.

The exposed value may be the result of an output computation, or it may simply expose some other value contained in the Context, such as the values of state variables. The Context handles caching of output port values and tracks dependencies to ensure that the values are valid with respect to their prerequisites. Leaf systems provide for the production of output port values, by computation or forwarding from other values within the associated leaf context. A diagram’s output ports, on the other hand, are exported from output ports of its contained subsystems.

An output port’s value is always stored as an AbstractValue, but we also provide special handling for output ports known to have numeric (vector) values. Vector-valued ports may specify a particular vector length, or may leave that to be determined at runtime.

OutputPort objects support three important operations:

• Allocate() returns an object that can hold the port’s value.

• Calc() unconditionally computes the port’s value.

• Eval() updates a cached value if necessary.

__init__(*args, **kwargs)

Allocate(self: pydrake.systems.framework.OutputPort_[AutoDiffXd]) → pydrake.common.value.AbstractValue

Allocates a concrete object suitable for holding the value to be exposed by this output port, and returns that as an AbstractValue. The returned object will never be null. If Drake assertions are enabled (typically only in Debug builds), validates for a vector-valued port that the returned AbstractValue is actually a BasicVector-derived type and that it has an acceptable size.

Note

If this is a vector-valued port, the underlying type is Value<BasicVector<T>>; downcast to BasicVector<T> before downcasting to the specific BasicVector subclass.

Eval(self: pydrake.systems.framework.OutputPort_[AutoDiffXd], arg0: pydrake.systems.framework.Context_[AutoDiffXd]) → object

EvalAbstract(self: pydrake.systems.framework.OutputPort_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → object

(Advanced.) Returns the value of this output port, typed as an AbstractValue. Most users should call Eval() instead. This method is only needed when the result will be passed into some other API that only accepts an AbstractValue.

EvalBasicVector(self: pydrake.systems.framework.OutputPort_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → object

(Advanced.) Returns the value of this output port, typed as a BasicVector. Most users should call Eval() instead. This method is only needed when the result will be passed into some other API that only accepts a BasicVector.

get_data_type(self: pydrake.systems.framework.OutputPort_[AutoDiffXd]) → pydrake.systems.framework.PortDataType

Returns the port data type.

get_index(self: pydrake.systems.framework.OutputPort_[AutoDiffXd]) → pydrake.systems.framework.OutputPortIndex

Returns the index of this output port within the owning System. For a Diagram, this will be the index within the Diagram, not the index within the LeafSystem whose output port was forwarded.

get_name(self: pydrake.systems.framework.OutputPort_[AutoDiffXd]) → str

Get port name.

get_system(self: pydrake.systems.framework.OutputPort_[AutoDiffXd]) → drake::systems::System<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >

Returns a reference to the System that owns this output port. Note that for a diagram output port this will be the diagram, not the leaf system whose output port was forwarded.

size(self: pydrake.systems.framework.OutputPort_[AutoDiffXd]) → int

Returns the fixed size expected for a vector-valued port. Not meaningful for abstract-valued ports.

class pydrake.systems.framework.OutputPort_[Expression]

An OutputPort belongs to a System and represents the properties of one of that System’s output ports. OutputPort objects are assigned OutputPortIndex values in the order they are declared; these are unique within a single System.

An output port can be considered a “window” into a System that permits controlled exposure of one of the values contained in that System’s Context at run time. Input ports of other subsystems may be connected to an output port to construct system diagrams with carefully managed interdependencies.

The exposed value may be the result of an output computation, or it may simply expose some other value contained in the Context, such as the values of state variables. The Context handles caching of output port values and tracks dependencies to ensure that the values are valid with respect to their prerequisites. Leaf systems provide for the production of output port values, by computation or forwarding from other values within the associated leaf context. A diagram’s output ports, on the other hand, are exported from output ports of its contained subsystems.

An output port’s value is always stored as an AbstractValue, but we also provide special handling for output ports known to have numeric (vector) values. Vector-valued ports may specify a particular vector length, or may leave that to be determined at runtime.

OutputPort objects support three important operations:

• Allocate() returns an object that can hold the port’s value.

• Calc() unconditionally computes the port’s value.

• Eval() updates a cached value if necessary.

__init__(*args, **kwargs)

Allocate(self: pydrake.systems.framework.OutputPort_[Expression]) → pydrake.common.value.AbstractValue

Allocates a concrete object suitable for holding the value to be exposed by this output port, and returns that as an AbstractValue. The returned object will never be null. If Drake assertions are enabled (typically only in Debug builds), validates for a vector-valued port that the returned AbstractValue is actually a BasicVector-derived type and that it has an acceptable size.

Note

If this is a vector-valued port, the underlying type is Value<BasicVector<T>>; downcast to BasicVector<T> before downcasting to the specific BasicVector subclass.

Eval(self: pydrake.systems.framework.OutputPort_[Expression], arg0: pydrake.systems.framework.Context_[Expression]) → object

EvalAbstract(self: pydrake.systems.framework.OutputPort_[Expression], context: pydrake.systems.framework.Context_[Expression]) → object

(Advanced.) Returns the value of this output port, typed as an AbstractValue. Most users should call Eval() instead. This method is only needed when the result will be passed into some other API that only accepts an AbstractValue.

EvalBasicVector(self: pydrake.systems.framework.OutputPort_[Expression], context: pydrake.systems.framework.Context_[Expression]) → object

(Advanced.) Returns the value of this output port, typed as a BasicVector. Most users should call Eval() instead. This method is only needed when the result will be passed into some other API that only accepts a BasicVector.

get_data_type(self: pydrake.systems.framework.OutputPort_[Expression]) → pydrake.systems.framework.PortDataType

Returns the port data type.

get_index(self: pydrake.systems.framework.OutputPort_[Expression]) → pydrake.systems.framework.OutputPortIndex

Returns the index of this output port within the owning System. For a Diagram, this will be the index within the Diagram, not the index within the LeafSystem whose output port was forwarded.

get_name(self: pydrake.systems.framework.OutputPort_[Expression]) → str

Get port name.

get_system(self: pydrake.systems.framework.OutputPort_[Expression]) → drake::systems::System<drake::symbolic::Expression>

Returns a reference to the System that owns this output port. Note that for a diagram output port this will be the diagram, not the leaf system whose output port was forwarded.

size(self: pydrake.systems.framework.OutputPort_[Expression]) → int

Returns the fixed size expected for a vector-valued port. Not meaningful for abstract-valued ports.

class pydrake.systems.framework.OutputPortIndex

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.OutputPortIndex) -> None

Default constructor; the result is an invalid index. This only exists to serve applications which require a default constructor.

2. __init__(self: pydrake.systems.framework.OutputPortIndex, arg0: int) -> None

Construction from a non-negative int value. The value must lie in the range of [0, 2³¹). Constructor only promises to test validity in Debug build.

is_valid(self: pydrake.systems.framework.OutputPortIndex) → bool

Reports if the index is valid–the only operation on an invalid index that doesn’t throw an exception in Debug builds.

class pydrake.systems.framework.OutputPortSelection

Members:

kNoOutput

kUseFirstOutputIfItExists

__init__(self: pydrake.systems.framework.OutputPortSelection, value: int) → None

kNoOutput = <OutputPortSelection.kNoOutput: -1>

kUseFirstOutputIfItExists = <OutputPortSelection.kUseFirstOutputIfItExists: -2>

property name

property value

class pydrake.systems.framework.Parameters

Parameters is a container for variables that parameterize a System so that it can represent a family of related models. Parameters are members of the Context. Parameters are not Inputs because they do not flow from upstream Systems, and they are not State because the System does not define update functions for them. If Parameters are modified, they are modified by application-specific logic, extrinsic to the System framework and to the flow of simulation time.

The Parameters include both vector-valued and abstract-valued elements.

Note

This class is templated; see Parameters_ for the list of instantiations.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.Parameters) -> None

Constructs an empty Parameters.

2. __init__(self: pydrake.systems.framework.Parameters, numeric: list[pydrake.systems.framework.BasicVector], abstract: list[pydrake.common.value.AbstractValue]) -> None

Constructs Parameters both numeric and abstract.

3. __init__(self: pydrake.systems.framework.Parameters, numeric: list[pydrake.systems.framework.BasicVector]) -> None

Constructs Parameters that are purely numeric.

4. __init__(self: pydrake.systems.framework.Parameters, abstract: list[pydrake.common.value.AbstractValue]) -> None

Constructs Parameters that are purely abstract.

5. __init__(self: pydrake.systems.framework.Parameters, vec: pydrake.systems.framework.BasicVector) -> None

Constructs Parameters in the common case where the parameters consist of exactly one numeric vector.

6. __init__(self: pydrake.systems.framework.Parameters, value: pydrake.common.value.AbstractValue) -> None

Constructs Parameters in the common case where the parameters consist of exactly one abstract value.

Clone(self: pydrake.systems.framework.Parameters) → pydrake.systems.framework.Parameters

get_abstract_parameter(self: pydrake.systems.framework.Parameters, index: int) → pydrake.common.value.AbstractValue

Returns the abstract-valued parameter at index. Asserts if the index is out of bounds.

get_abstract_parameters(self: pydrake.systems.framework.Parameters) → pydrake.systems.framework.AbstractValues

get_mutable_abstract_parameter(self: pydrake.systems.framework.Parameters, index: int) → pydrake.common.value.AbstractValue

Returns the abstract-valued parameter at index. Asserts if the index is out of bounds.

get_mutable_numeric_parameter(self: pydrake.systems.framework.Parameters, index: int) → pydrake.systems.framework.BasicVector

Returns the vector-valued parameter at index. Asserts if the index is out of bounds.

get_numeric_parameter(self: pydrake.systems.framework.Parameters, index: int) → pydrake.systems.framework.BasicVector

Returns the vector-valued parameter at index. Asserts if the index is out of bounds.

get_numeric_parameters(self: pydrake.systems.framework.Parameters) → pydrake.systems.framework.DiscreteValues

num_abstract_parameters(self: pydrake.systems.framework.Parameters) → int

num_numeric_parameter_groups(self: pydrake.systems.framework.Parameters) → int

set_abstract_parameters(self: pydrake.systems.framework.Parameters, abstract_params: pydrake.systems.framework.AbstractValues) → None

set_numeric_parameters(self: pydrake.systems.framework.Parameters, numeric_params: pydrake.systems.framework.DiscreteValues) → None

SetFrom(self: pydrake.systems.framework.Parameters, arg0: pydrake.systems.framework.Parameters) → None

Initializes this object from other.

template pydrake.systems.framework.Parameters_

Instantiations: Parameters_[float], Parameters_[AutoDiffXd], Parameters_[Expression]

class pydrake.systems.framework.Parameters_[AutoDiffXd]

Parameters is a container for variables that parameterize a System so that it can represent a family of related models. Parameters are members of the Context. Parameters are not Inputs because they do not flow from upstream Systems, and they are not State because the System does not define update functions for them. If Parameters are modified, they are modified by application-specific logic, extrinsic to the System framework and to the flow of simulation time.

The Parameters include both vector-valued and abstract-valued elements.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.Parameters_[AutoDiffXd]) -> None

Constructs an empty Parameters.

2. __init__(self: pydrake.systems.framework.Parameters_[AutoDiffXd], numeric: list[pydrake.systems.framework.BasicVector_[AutoDiffXd]], abstract: list[pydrake.common.value.AbstractValue]) -> None

Constructs Parameters both numeric and abstract.

3. __init__(self: pydrake.systems.framework.Parameters_[AutoDiffXd], numeric: list[pydrake.systems.framework.BasicVector_[AutoDiffXd]]) -> None

Constructs Parameters that are purely numeric.

4. __init__(self: pydrake.systems.framework.Parameters_[AutoDiffXd], abstract: list[pydrake.common.value.AbstractValue]) -> None

Constructs Parameters that are purely abstract.

5. __init__(self: pydrake.systems.framework.Parameters_[AutoDiffXd], vec: pydrake.systems.framework.BasicVector_[AutoDiffXd]) -> None

Constructs Parameters in the common case where the parameters consist of exactly one numeric vector.

6. __init__(self: pydrake.systems.framework.Parameters_[AutoDiffXd], value: pydrake.common.value.AbstractValue) -> None

Constructs Parameters in the common case where the parameters consist of exactly one abstract value.

Clone(self: pydrake.systems.framework.Parameters_[AutoDiffXd]) → pydrake.systems.framework.Parameters_[AutoDiffXd]

get_abstract_parameter(self: pydrake.systems.framework.Parameters_[AutoDiffXd], index: int) → pydrake.common.value.AbstractValue

Returns the abstract-valued parameter at index. Asserts if the index is out of bounds.

get_abstract_parameters(self: pydrake.systems.framework.Parameters_[AutoDiffXd]) → pydrake.systems.framework.AbstractValues

get_mutable_abstract_parameter(self: pydrake.systems.framework.Parameters_[AutoDiffXd], index: int) → pydrake.common.value.AbstractValue

Returns the abstract-valued parameter at index. Asserts if the index is out of bounds.

get_mutable_numeric_parameter(self: pydrake.systems.framework.Parameters_[AutoDiffXd], index: int) → pydrake.systems.framework.BasicVector_[AutoDiffXd]

Returns the vector-valued parameter at index. Asserts if the index is out of bounds.

get_numeric_parameter(self: pydrake.systems.framework.Parameters_[AutoDiffXd], index: int) → pydrake.systems.framework.BasicVector_[AutoDiffXd]

Returns the vector-valued parameter at index. Asserts if the index is out of bounds.

get_numeric_parameters(self: pydrake.systems.framework.Parameters_[AutoDiffXd]) → pydrake.systems.framework.DiscreteValues_[AutoDiffXd]

num_abstract_parameters(self: pydrake.systems.framework.Parameters_[AutoDiffXd]) → int

num_numeric_parameter_groups(self: pydrake.systems.framework.Parameters_[AutoDiffXd]) → int

set_abstract_parameters(self: pydrake.systems.framework.Parameters_[AutoDiffXd], abstract_params: pydrake.systems.framework.AbstractValues) → None

set_numeric_parameters(self: pydrake.systems.framework.Parameters_[AutoDiffXd], numeric_params: pydrake.systems.framework.DiscreteValues_[AutoDiffXd]) → None

SetFrom(self: pydrake.systems.framework.Parameters_[AutoDiffXd], arg0: pydrake.systems.framework.Parameters) → None

Initializes this object from other.

class pydrake.systems.framework.Parameters_[Expression]

Parameters is a container for variables that parameterize a System so that it can represent a family of related models. Parameters are members of the Context. Parameters are not Inputs because they do not flow from upstream Systems, and they are not State because the System does not define update functions for them. If Parameters are modified, they are modified by application-specific logic, extrinsic to the System framework and to the flow of simulation time.

The Parameters include both vector-valued and abstract-valued elements.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.Parameters_[Expression]) -> None

Constructs an empty Parameters.

2. __init__(self: pydrake.systems.framework.Parameters_[Expression], numeric: list[pydrake.systems.framework.BasicVector_[Expression]], abstract: list[pydrake.common.value.AbstractValue]) -> None

Constructs Parameters both numeric and abstract.

3. __init__(self: pydrake.systems.framework.Parameters_[Expression], numeric: list[pydrake.systems.framework.BasicVector_[Expression]]) -> None

Constructs Parameters that are purely numeric.

4. __init__(self: pydrake.systems.framework.Parameters_[Expression], abstract: list[pydrake.common.value.AbstractValue]) -> None

Constructs Parameters that are purely abstract.

5. __init__(self: pydrake.systems.framework.Parameters_[Expression], vec: pydrake.systems.framework.BasicVector_[Expression]) -> None

Constructs Parameters in the common case where the parameters consist of exactly one numeric vector.

6. __init__(self: pydrake.systems.framework.Parameters_[Expression], value: pydrake.common.value.AbstractValue) -> None

Constructs Parameters in the common case where the parameters consist of exactly one abstract value.

Clone(self: pydrake.systems.framework.Parameters_[Expression]) → pydrake.systems.framework.Parameters_[Expression]

get_abstract_parameter(self: pydrake.systems.framework.Parameters_[Expression], index: int) → pydrake.common.value.AbstractValue

Returns the abstract-valued parameter at index. Asserts if the index is out of bounds.

get_abstract_parameters(self: pydrake.systems.framework.Parameters_[Expression]) → pydrake.systems.framework.AbstractValues

get_mutable_abstract_parameter(self: pydrake.systems.framework.Parameters_[Expression], index: int) → pydrake.common.value.AbstractValue

Returns the abstract-valued parameter at index. Asserts if the index is out of bounds.

get_mutable_numeric_parameter(self: pydrake.systems.framework.Parameters_[Expression], index: int) → pydrake.systems.framework.BasicVector_[Expression]

Returns the vector-valued parameter at index. Asserts if the index is out of bounds.

get_numeric_parameter(self: pydrake.systems.framework.Parameters_[Expression], index: int) → pydrake.systems.framework.BasicVector_[Expression]

Returns the vector-valued parameter at index. Asserts if the index is out of bounds.

get_numeric_parameters(self: pydrake.systems.framework.Parameters_[Expression]) → pydrake.systems.framework.DiscreteValues_[Expression]

num_abstract_parameters(self: pydrake.systems.framework.Parameters_[Expression]) → int

num_numeric_parameter_groups(self: pydrake.systems.framework.Parameters_[Expression]) → int

set_abstract_parameters(self: pydrake.systems.framework.Parameters_[Expression], abstract_params: pydrake.systems.framework.AbstractValues) → None

set_numeric_parameters(self: pydrake.systems.framework.Parameters_[Expression], numeric_params: pydrake.systems.framework.DiscreteValues_[Expression]) → None

SetFrom(self: pydrake.systems.framework.Parameters_[Expression], arg0: pydrake.systems.framework.Parameters) → None

Initializes this object from other.

class pydrake.systems.framework.PeriodicEventData

An event data variant describing an event that recurs on a fixed period. The events are triggered at time = offset_sec + i * period_sec, where i is a non-negative integer.

__init__(*args, **kwargs)

offset_sec(self: pydrake.systems.framework.PeriodicEventData) → float

Gets the time after zero when this event should first occur.

period_sec(self: pydrake.systems.framework.PeriodicEventData) → float

Gets the period with which this event should recur.

class pydrake.systems.framework.PortDataType

Members:

kVectorValued

kAbstractValued

__init__(self: pydrake.systems.framework.PortDataType, value: int) → None

kAbstractValued = <PortDataType.kAbstractValued: 1>

kVectorValued = <PortDataType.kVectorValued: 0>

property name

property value

class pydrake.systems.framework.PublishEvent

Bases: pydrake.systems.framework.Event

This class represents a publish event. It has an optional callback function to do custom handling of this event.

See also

System::Publish for more details.

See also

LeafSystem for more convenient interfaces to publish events via the Declare*PublishEvent() methods.

Note

This class is templated; see PublishEvent_ for the list of instantiations.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.PublishEvent, callback: Callable[[pydrake.systems.framework.Context, pydrake.systems.framework.PublishEvent], Optional[pydrake.systems.framework.EventStatus]]) -> None

Constructs a PublishEvent with the given callback function.

2. __init__(self: pydrake.systems.framework.PublishEvent, system_callback: Callable[[drake::systems::System<double>, pydrake.systems.framework.Context, pydrake.systems.framework.PublishEvent], Optional[pydrake.systems.framework.EventStatus]]) -> None

Constructs a PublishEvent with the given callback function.

3. __init__(self: pydrake.systems.framework.PublishEvent, trigger_type: pydrake.systems.framework.TriggerType, callback: Callable[[pydrake.systems.framework.Context, pydrake.systems.framework.PublishEvent], Optional[pydrake.systems.framework.EventStatus]]) -> None

Users should not be calling these

4. __init__(self: pydrake.systems.framework.PublishEvent, trigger_type: pydrake.systems.framework.TriggerType, system_callback: Callable[[drake::systems::System<double>, pydrake.systems.framework.Context, pydrake.systems.framework.PublishEvent], Optional[pydrake.systems.framework.EventStatus]]) -> None

Users should not be calling these

template pydrake.systems.framework.PublishEvent_

Instantiations: PublishEvent_[float], PublishEvent_[AutoDiffXd], PublishEvent_[Expression]

class pydrake.systems.framework.PublishEvent_[AutoDiffXd]

Bases: pydrake.systems.framework.Event_[AutoDiffXd]

This class represents a publish event. It has an optional callback function to do custom handling of this event.

See also

System::Publish for more details.

See also

LeafSystem for more convenient interfaces to publish events via the Declare*PublishEvent() methods.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.PublishEvent_[AutoDiffXd], callback: Callable[[pydrake.systems.framework.Context_[AutoDiffXd], pydrake.systems.framework.PublishEvent_[AutoDiffXd]], Optional[pydrake.systems.framework.EventStatus]]) -> None

Constructs a PublishEvent with the given callback function.

2. __init__(self: pydrake.systems.framework.PublishEvent_[AutoDiffXd], system_callback: Callable[[drake::systems::System<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >, pydrake.systems.framework.Context_[AutoDiffXd], pydrake.systems.framework.PublishEvent_[AutoDiffXd]], Optional[pydrake.systems.framework.EventStatus]]) -> None

Constructs a PublishEvent with the given callback function.

3. __init__(self: pydrake.systems.framework.PublishEvent_[AutoDiffXd], trigger_type: pydrake.systems.framework.TriggerType, callback: Callable[[pydrake.systems.framework.Context_[AutoDiffXd], pydrake.systems.framework.PublishEvent_[AutoDiffXd]], Optional[pydrake.systems.framework.EventStatus]]) -> None

Users should not be calling these

4. __init__(self: pydrake.systems.framework.PublishEvent_[AutoDiffXd], trigger_type: pydrake.systems.framework.TriggerType, system_callback: Callable[[drake::systems::System<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >, pydrake.systems.framework.Context_[AutoDiffXd], pydrake.systems.framework.PublishEvent_[AutoDiffXd]], Optional[pydrake.systems.framework.EventStatus]]) -> None

Users should not be calling these

class pydrake.systems.framework.PublishEvent_[Expression]

Bases: pydrake.systems.framework.Event_[Expression]

This class represents a publish event. It has an optional callback function to do custom handling of this event.

See also

System::Publish for more details.

See also

LeafSystem for more convenient interfaces to publish events via the Declare*PublishEvent() methods.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.PublishEvent_[Expression], callback: Callable[[pydrake.systems.framework.Context_[Expression], pydrake.systems.framework.PublishEvent_[Expression]], Optional[pydrake.systems.framework.EventStatus]]) -> None

Constructs a PublishEvent with the given callback function.

2. __init__(self: pydrake.systems.framework.PublishEvent_[Expression], system_callback: Callable[[drake::systems::System<drake::symbolic::Expression>, pydrake.systems.framework.Context_[Expression], pydrake.systems.framework.PublishEvent_[Expression]], Optional[pydrake.systems.framework.EventStatus]]) -> None

Constructs a PublishEvent with the given callback function.

3. __init__(self: pydrake.systems.framework.PublishEvent_[Expression], trigger_type: pydrake.systems.framework.TriggerType, callback: Callable[[pydrake.systems.framework.Context_[Expression], pydrake.systems.framework.PublishEvent_[Expression]], Optional[pydrake.systems.framework.EventStatus]]) -> None

Users should not be calling these

4. __init__(self: pydrake.systems.framework.PublishEvent_[Expression], trigger_type: pydrake.systems.framework.TriggerType, system_callback: Callable[[drake::systems::System<drake::symbolic::Expression>, pydrake.systems.framework.Context_[Expression], pydrake.systems.framework.PublishEvent_[Expression]], Optional[pydrake.systems.framework.EventStatus]]) -> None

Users should not be calling these

class pydrake.systems.framework.State

%State is a container for all the data comprising the complete state of a particular System at a particular moment. Any field in State may be empty if it is not applicable to the System in question. A System may not maintain state in any place other than a State object.

A State x contains three types of state variables:

• Continuous state xc

• Discrete state xd

• Abstract state xa

Note

This class is templated; see State_ for the list of instantiations.

__init__(self: pydrake.systems.framework.State) → None

get_abstract_state(*args, **kwargs)

Overloaded function.

1. get_abstract_state(self: pydrake.systems.framework.State) -> pydrake.systems.framework.AbstractValues

Returns a const pointer to the abstract component of the state at index. Asserts if index doesn’t exist.

2. get_abstract_state(self: pydrake.systems.framework.State, index: int) -> pydrake.common.value.AbstractValue

Returns a const pointer to the abstract component of the state at index. Asserts if index doesn’t exist.

get_continuous_state(self: pydrake.systems.framework.State) → pydrake.systems.framework.ContinuousState

get_discrete_state(self: pydrake.systems.framework.State) → pydrake.systems.framework.DiscreteValues

get_mutable_abstract_state(*args, **kwargs)

Overloaded function.

1. get_mutable_abstract_state(self: pydrake.systems.framework.State) -> pydrake.systems.framework.AbstractValues

Returns a mutable reference to the abstract component of the state, which may be of size zero.

2. get_mutable_abstract_state(self: pydrake.systems.framework.State, index: int) -> pydrake.common.value.AbstractValue

Returns a mutable pointer to element index of the abstract state. Asserts if index doesn’t exist.

get_mutable_continuous_state(self: pydrake.systems.framework.State) → pydrake.systems.framework.ContinuousState

get_mutable_discrete_state(*args, **kwargs)

Overloaded function.

1. get_mutable_discrete_state(self: pydrake.systems.framework.State) -> pydrake.systems.framework.DiscreteValues

2. get_mutable_discrete_state(self: pydrake.systems.framework.State, index: int) -> pydrake.systems.framework.BasicVector

template pydrake.systems.framework.State_

Instantiations: State_[float], State_[AutoDiffXd], State_[Expression]

class pydrake.systems.framework.State_[AutoDiffXd]

%State is a container for all the data comprising the complete state of a particular System at a particular moment. Any field in State may be empty if it is not applicable to the System in question. A System may not maintain state in any place other than a State object.

A State x contains three types of state variables:

• Continuous state xc

• Discrete state xd

• Abstract state xa

__init__(self: pydrake.systems.framework.State_[AutoDiffXd]) → None

get_abstract_state(*args, **kwargs)

Overloaded function.

1. get_abstract_state(self: pydrake.systems.framework.State_[AutoDiffXd]) -> pydrake.systems.framework.AbstractValues

Returns a const pointer to the abstract component of the state at index. Asserts if index doesn’t exist.

2. get_abstract_state(self: pydrake.systems.framework.State_[AutoDiffXd], index: int) -> pydrake.common.value.AbstractValue

Returns a const pointer to the abstract component of the state at index. Asserts if index doesn’t exist.

get_continuous_state(self: pydrake.systems.framework.State_[AutoDiffXd]) → pydrake.systems.framework.ContinuousState_[AutoDiffXd]

get_discrete_state(self: pydrake.systems.framework.State_[AutoDiffXd]) → pydrake.systems.framework.DiscreteValues_[AutoDiffXd]

get_mutable_abstract_state(*args, **kwargs)

Overloaded function.

1. get_mutable_abstract_state(self: pydrake.systems.framework.State_[AutoDiffXd]) -> pydrake.systems.framework.AbstractValues

Returns a mutable reference to the abstract component of the state, which may be of size zero.

2. get_mutable_abstract_state(self: pydrake.systems.framework.State_[AutoDiffXd], index: int) -> pydrake.common.value.AbstractValue

Returns a mutable pointer to element index of the abstract state. Asserts if index doesn’t exist.

get_mutable_continuous_state(self: pydrake.systems.framework.State_[AutoDiffXd]) → pydrake.systems.framework.ContinuousState_[AutoDiffXd]

get_mutable_discrete_state(*args, **kwargs)

Overloaded function.

1. get_mutable_discrete_state(self: pydrake.systems.framework.State_[AutoDiffXd]) -> pydrake.systems.framework.DiscreteValues_[AutoDiffXd]

2. get_mutable_discrete_state(self: pydrake.systems.framework.State_[AutoDiffXd], index: int) -> pydrake.systems.framework.BasicVector_[AutoDiffXd]

class pydrake.systems.framework.State_[Expression]

%State is a container for all the data comprising the complete state of a particular System at a particular moment. Any field in State may be empty if it is not applicable to the System in question. A System may not maintain state in any place other than a State object.

A State x contains three types of state variables:

• Continuous state xc

• Discrete state xd

• Abstract state xa

__init__(self: pydrake.systems.framework.State_[Expression]) → None

get_abstract_state(*args, **kwargs)

Overloaded function.

1. get_abstract_state(self: pydrake.systems.framework.State_[Expression]) -> pydrake.systems.framework.AbstractValues

Returns a const pointer to the abstract component of the state at index. Asserts if index doesn’t exist.

2. get_abstract_state(self: pydrake.systems.framework.State_[Expression], index: int) -> pydrake.common.value.AbstractValue

Returns a const pointer to the abstract component of the state at index. Asserts if index doesn’t exist.

get_continuous_state(self: pydrake.systems.framework.State_[Expression]) → pydrake.systems.framework.ContinuousState_[Expression]

get_discrete_state(self: pydrake.systems.framework.State_[Expression]) → pydrake.systems.framework.DiscreteValues_[Expression]

get_mutable_abstract_state(*args, **kwargs)

Overloaded function.

1. get_mutable_abstract_state(self: pydrake.systems.framework.State_[Expression]) -> pydrake.systems.framework.AbstractValues

Returns a mutable reference to the abstract component of the state, which may be of size zero.

2. get_mutable_abstract_state(self: pydrake.systems.framework.State_[Expression], index: int) -> pydrake.common.value.AbstractValue

Returns a mutable pointer to element index of the abstract state. Asserts if index doesn’t exist.

get_mutable_continuous_state(self: pydrake.systems.framework.State_[Expression]) → pydrake.systems.framework.ContinuousState_[Expression]

get_mutable_discrete_state(*args, **kwargs)

Overloaded function.

1. get_mutable_discrete_state(self: pydrake.systems.framework.State_[Expression]) -> pydrake.systems.framework.DiscreteValues_[Expression]

2. get_mutable_discrete_state(self: pydrake.systems.framework.State_[Expression], index: int) -> pydrake.systems.framework.BasicVector_[Expression]

class pydrake.systems.framework.SubsystemIndex

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.SubsystemIndex) -> None

Default constructor; the result is an invalid index. This only exists to serve applications which require a default constructor.

2. __init__(self: pydrake.systems.framework.SubsystemIndex, arg0: int) -> None

Construction from a non-negative int value. The value must lie in the range of [0, 2³¹). Constructor only promises to test validity in Debug build.

is_valid(self: pydrake.systems.framework.SubsystemIndex) → bool

Reports if the index is valid–the only operation on an invalid index that doesn’t throw an exception in Debug builds.

class pydrake.systems.framework.Subvector

Bases: pydrake.systems.framework.VectorBase

Subvector is a concrete class template that implements VectorBase by providing a sliced view of a VectorBase.

Note

This class is templated; see Subvector_ for the list of instantiations.

__init__(*args, **kwargs)

template pydrake.systems.framework.Subvector_

Instantiations: Subvector_[float], Subvector_[AutoDiffXd], Subvector_[Expression]

class pydrake.systems.framework.Subvector_[AutoDiffXd]

Bases: pydrake.systems.framework.VectorBase_[AutoDiffXd]

Subvector is a concrete class template that implements VectorBase by providing a sliced view of a VectorBase.

__init__(*args, **kwargs)

class pydrake.systems.framework.Subvector_[Expression]

Bases: pydrake.systems.framework.VectorBase_[Expression]

Subvector is a concrete class template that implements VectorBase by providing a sliced view of a VectorBase.

__init__(*args, **kwargs)

class pydrake.systems.framework.Supervector

Bases: pydrake.systems.framework.VectorBase

Supervector is a concrete class template that implements VectorBase by concatenating multiple VectorBases, which it does not own.

Note

This class is templated; see Supervector_ for the list of instantiations.

__init__(*args, **kwargs)

template pydrake.systems.framework.Supervector_

Instantiations: Supervector_[float], Supervector_[AutoDiffXd], Supervector_[Expression]

class pydrake.systems.framework.Supervector_[AutoDiffXd]

Bases: pydrake.systems.framework.VectorBase_[AutoDiffXd]

Supervector is a concrete class template that implements VectorBase by concatenating multiple VectorBases, which it does not own.

__init__(*args, **kwargs)

class pydrake.systems.framework.Supervector_[Expression]

Bases: pydrake.systems.framework.VectorBase_[Expression]

Supervector is a concrete class template that implements VectorBase by concatenating multiple VectorBases, which it does not own.

__init__(*args, **kwargs)

class pydrake.systems.framework.System

Bases: pydrake.systems.framework.SystemBase

Base class for all System functionality that is dependent on the templatized scalar type T for input, state, parameters, and outputs.

Note

This class is templated; see System_ for the list of instantiations.

__init__(*args, **kwargs)

Accept(self: pydrake.systems.framework.System, v: pydrake.systems.framework.SystemVisitor) → None

Implements a visitor pattern.

See also

SystemVisitor<T>.

AllocateContext(self: pydrake.systems.framework.System) → pydrake.systems.framework.Context

Returns a Context<T> suitable for use with this System<T>.

AllocateDiscreteVariables(self: pydrake.systems.framework.System) → pydrake.systems.framework.DiscreteValues

Returns a DiscreteValues of the same dimensions as the discrete_state allocated in CreateDefaultContext. The simulator will provide this state as the output argument to Update.

AllocateImplicitTimeDerivativesResidual(self: pydrake.systems.framework.System) → numpy.ndarray[numpy.float64[m, 1]]

Returns an Eigen VectorX suitable for use as the output argument to the CalcImplicitTimeDerivativesResidual() method. The returned VectorX will have size implicit_time_derivatives_residual_size() with the elements uninitialized. This is just a convenience method – you are free to use any properly-sized mutable Eigen object as the residual vector.

AllocateInputAbstract(self: pydrake.systems.framework.System, input_port: pydrake.systems.framework.InputPort) → pydrake.common.value.AbstractValue

Given an input port, allocates the abstract storage. The input_port must match a port declared via DeclareInputPort.

AllocateInputVector(self: pydrake.systems.framework.System, input_port: pydrake.systems.framework.InputPort) → pydrake.systems.framework.BasicVector

Given an input port, allocates the vector storage. The input_port must match a port declared via DeclareInputPort.

AllocateOutput(self: pydrake.systems.framework.System) → pydrake.systems.framework.SystemOutput

Returns a container that can hold the values of all of this System’s output ports. It is sized with the number of output ports and uses each output port’s allocation method to provide an object of the right type for that port.

AllocateTimeDerivatives(self: pydrake.systems.framework.System) → pydrake.systems.framework.ContinuousState

Returns a ContinuousState of the same size as the continuous_state allocated in CreateDefaultContext. The simulator will provide this state as the output argument to EvalTimeDerivatives.

CalcConservativePower(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context) → float

Calculates and returns the conservative power represented by the current contents of the given context. Prefer EvalConservativePower() to avoid unnecessary recalculation.

See also

EvalConservativePower() for more information.

CalcForcedDiscreteVariableUpdate(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context, discrete_state: pydrake.systems.framework.DiscreteValues) → None

(Advanced) Manually triggers any DiscreteUpdateEvent that has trigger type kForced. Invokes the discrete event dispatcher on this System with the given Context providing the initial values for the discrete variables. The updated values of the discrete variables are written to the discrete_state output argument; no change is made to the Context.

The default dispatcher will invoke the handlers (if any) associated with each force-triggered event.

Note

There will always be at least one force-triggered event, though with no associated handler. By default that will do nothing when triggered, but that behavior can be changed by overriding the dispatcher (not recommended).

Raises

• RuntimeError if it invokes an event handler that returns status –

• indicating failure. –

See also

CalcDiscreteVariableUpdate(), CalcForcedUnrestrictedUpdate()

CalcForcedUnrestrictedUpdate(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context, state: pydrake.systems.framework.State) → None

(Advanced) Manually triggers any UnrestrictedUpdateEvent that has trigger type kForced. Invokes the unrestricted event dispatcher on this System with the given Context providing the initial values for the state variables. The updated values of the state variables are written to the state output argument; no change is made to the Context.

The default dispatcher will invoke the handlers (if any) associated with each force-triggered event.

Note

There will always be at least one force-triggered event, though with no associated handler. By default that will do nothing when triggered, but that behavior can be changed by overriding the dispatcher (not recommended).

Raises

• RuntimeError if it invokes an event handler that returns status –

• indicating failure. –

See also

CalcUnrestrictedUpdate()

CalcImplicitTimeDerivativesResidual(*args, **kwargs)

Overloaded function.

1. CalcImplicitTimeDerivativesResidual(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context, proposed_derivatives: pydrake.systems.framework.ContinuousState, residual: Optional[numpy.ndarray[numpy.float64[m, 1], flags.writeable]]) -> None

Evaluates the implicit form of the System equations and returns the residual.

The explicit and implicit forms of the System equations are

1. ẋ꜀ = fₑ(𝓒) explicit (2) 0 = fᵢ(𝓒; ẋ꜀) implicit

where 𝓒 = {a, p, t, x, u} is the current value of the given Context from which accuracy a, parameters p, time t, state x (={x꜀ xd xₐ}) and input values u are obtained. Substituting (1) into (2) shows that the following condition must always hold:

3. fᵢ(𝓒; fₑ(𝓒)) = 0 always true

When fᵢ(𝓒; ẋ꜀ₚ) is evaluated with a proposed time derivative ẋ꜀ₚ that differs from ẋ꜀ the result will be non-zero; we call that the residual of the implicit equation. Given a Context and proposed time derivative ẋ꜀ₚ, this method returns the residual r such that

4. r = fᵢ(𝓒; ẋ꜀ₚ).

The returned r will typically be the same length as x꜀ although that is not required. And even if r and x꜀ are the same size, there will not necessarily be any elementwise correspondence between them. (That is, you should not assume that r[i] is the “residual” of ẋ꜀ₚ[i].) For a Diagram, r is the concatenation of residuals from each of the subsystems, in order of subsystem index within the Diagram.

A default implementation fᵢ⁽ᵈᵉᶠ⁾ for the implicit form is always provided and makes use of the explicit form as follows:

5. fᵢ⁽ᵈᵉᶠ⁾(𝓒; ẋ꜀ₚ) ≜ ẋ꜀ₚ − fₑ(𝓒)

which satisfies condition (3) by construction. (Note that the default implementation requires the residual to have the same size as x꜀.) Substantial efficiency gains can often be obtained by replacing the default function with a customized implementation. Override DoCalcImplicitTimeDerivativesResidual() to replace the default implementation with a better one.

Parameter context:

The source for time, state, inputs, etc. to be used in calculating the residual.

Parameter proposed_derivatives:

The proposed value ẋ꜀ₚ for the time derivatives of x꜀.

Parameter residual:

The result r of evaluating the implicit function. Can be any mutable Eigen vector object of size implicit_time_derivatives_residual_size().

Precondition:

proposed_derivatives is compatible with this System.

Precondition:

residual is of size implicit_time_derivatives_residual_size().

See also

SystemBase::implicit_time_derivatives_residual_size()

See also

LeafSystem::DeclareImplicitTimeDerivativesResidualSize()

See also

DoCalcImplicitTimeDerivativesResidual()

See also

CalcTimeDerivatives()

2. CalcImplicitTimeDerivativesResidual(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context, proposed_derivatives: pydrake.systems.framework.ContinuousState) -> numpy.ndarray[numpy.float64[m, 1]]

Evaluates the implicit form of the System equations and returns the residual.

The explicit and implicit forms of the System equations are

1. ẋ꜀ = fₑ(𝓒) explicit (2) 0 = fᵢ(𝓒; ẋ꜀) implicit

where 𝓒 = {a, p, t, x, u} is the current value of the given Context from which accuracy a, parameters p, time t, state x (={x꜀ xd xₐ}) and input values u are obtained. Substituting (1) into (2) shows that the following condition must always hold:

3. fᵢ(𝓒; fₑ(𝓒)) = 0 always true

When fᵢ(𝓒; ẋ꜀ₚ) is evaluated with a proposed time derivative ẋ꜀ₚ that differs from ẋ꜀ the result will be non-zero; we call that the residual of the implicit equation. Given a Context and proposed time derivative ẋ꜀ₚ, this method returns the residual r such that

4. r = fᵢ(𝓒; ẋ꜀ₚ).

The returned r will typically be the same length as x꜀ although that is not required. And even if r and x꜀ are the same size, there will not necessarily be any elementwise correspondence between them. (That is, you should not assume that r[i] is the “residual” of ẋ꜀ₚ[i].) For a Diagram, r is the concatenation of residuals from each of the subsystems, in order of subsystem index within the Diagram.

A default implementation fᵢ⁽ᵈᵉᶠ⁾ for the implicit form is always provided and makes use of the explicit form as follows:

5. fᵢ⁽ᵈᵉᶠ⁾(𝓒; ẋ꜀ₚ) ≜ ẋ꜀ₚ − fₑ(𝓒)

which satisfies condition (3) by construction. (Note that the default implementation requires the residual to have the same size as x꜀.) Substantial efficiency gains can often be obtained by replacing the default function with a customized implementation. Override DoCalcImplicitTimeDerivativesResidual() to replace the default implementation with a better one.

Parameter context:

The source for time, state, inputs, etc. to be used in calculating the residual.

Parameter proposed_derivatives:

The proposed value ẋ꜀ₚ for the time derivatives of x꜀.

Parameter residual:

The result r of evaluating the implicit function. Can be any mutable Eigen vector object of size implicit_time_derivatives_residual_size().

Precondition:

proposed_derivatives is compatible with this System.

Precondition:

residual is of size implicit_time_derivatives_residual_size().

See also

SystemBase::implicit_time_derivatives_residual_size()

See also

LeafSystem::DeclareImplicitTimeDerivativesResidualSize()

See also

DoCalcImplicitTimeDerivativesResidual()

See also

CalcTimeDerivatives()

CalcKineticEnergy(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context) → float

Calculates and returns the kinetic energy represented by the current configuration and velocity provided in context. Prefer EvalKineticEnergy() to avoid unnecessary recalculation.

See also

EvalKineticEnergy() for more information.

CalcNonConservativePower(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context) → float

Calculates and returns the non-conservative power represented by the current contents of the given context. Prefer EvalNonConservativePower() to avoid unnecessary recalculation.

See also

EvalNonConservativePower() for more information.

CalcOutput(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context, outputs: pydrake.systems.framework.SystemOutput) → None

Utility method that computes for every output port i the value y(i) that should result from the current contents of the given Context. Note that individual output port values can be calculated using get_output_port(i).Calc(); this method invokes that for each output port in index order. The result may depend on time and the current values of input ports, parameters, and state variables. The result is written to outputs which must already have been allocated to have the right number of entries of the right types.

CalcPotentialEnergy(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context) → float

Calculates and returns the potential energy represented by the current configuration provided in context. Prefer EvalPotentialEnergy() to avoid unnecessary recalculation.

See also

EvalPotentialEnergy() for more information.

CalcTimeDerivatives(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context, derivatives: pydrake.systems.framework.ContinuousState) → None

Calculates the time derivatives ẋ꜀ of the continuous state x꜀ into a given output argument. Prefer EvalTimeDerivatives() instead to avoid unnecessary recomputation.

This method solves the System equations in explicit form:

ẋ꜀ = fₑ(𝓒)

where 𝓒 = {a, p, t, x, u} is the current value of the given Context from which accuracy a, parameters p, time t, state x (={x꜀ xd xₐ}) and input values u are obtained.

Parameter context:

The source for time, state, inputs, etc. defining the point at which the derivatives should be calculated.

Parameter derivatives:

The time derivatives ẋ꜀. Must be the same size as the continuous state vector in context.

See also

EvalTimeDerivatives() for more information.

See also

CalcImplicitTimeDerivativesResidual() for the implicit form of these equations.

Clone(self: pydrake.systems.framework.System) → pydrake.systems.framework.System

Creates a deep copy of this system.

Even though the cloned system is functionally identical, any contexts created for this system are not compatible with the cloned system, and vice versa.

See also

Context::SetTimeStateAndParametersFrom() for how to copy context data between clones.

Warning

This implementation is somewhat incomplete at the moment. Many systems will not be able to be cloned, and will throw an exception instead. To be cloned, at minimum a system must support scalar conversion. See system_scalar_conversion.

The result is never nullptr.

CreateDefaultContext(self: pydrake.systems.framework.System) → pydrake.systems.framework.Context

This convenience method allocates a context using AllocateContext() and sets its default values using SetDefaultContext().

DeclareInputPort(self: pydrake.systems.framework.System, name: Union[str, pydrake.systems.framework.UseDefaultName], type: pydrake.systems.framework.PortDataType, size: int, random_type: Optional[pydrake.common.RandomDistribution] = None) → pydrake.systems.framework.InputPort

Adds a port with the specified type and size to the input topology.

Input port names must be unique for this system (passing in a duplicate name will throw RuntimeError). If name is given as kUseDefaultName, then a default value of e.g. “u2”, where 2 is the input number will be provided. An empty name is not permitted.

If the port is intended to model a random noise or disturbance input, random_type can (optionally) be used to label it as such; doing so enables algorithms for design and analysis (e.g. state estimation) to reason explicitly about randomness at the system level. All random input ports are assumed to be statistically independent.

Precondition:

name must not be empty.

Raises

RuntimeError for a duplicate port name. –

Returns

the declared port.

EvalAbstractInput(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context, port_index: int) → pydrake.common.value.AbstractValue

Returns the value of the input port with the given port_index as an AbstractValue, which is permitted for ports of any type. Causes the value to become up to date first if necessary, delegating to our parent Diagram. Returns a pointer to the port’s value, or nullptr if the port is not connected. If you know the actual type, use one of the more-specific signatures.

Precondition:

port_index selects an existing input port of this System.

See also

InputPort::Eval() (preferred)

EvalKineticEnergy(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context) → float

Returns a reference to the cached value of the kinetic energy (KE), evaluating first if necessary using CalcKineticEnergy().

By definition here, kinetic energy depends only on “configuration” and “velocity” (e.g. angular and translational velocity) of moving masses which includes a subset of the state variables, and parameters that affect configuration, velocities, or mass properties. The calculated value may also be affected by the accuracy value supplied in the Context. KE cannot depend explicitly on time (∂KE/∂t = 0) or input port values (∂KE/∂u = 0).

Non-physical systems where KE is not meaningful will return KE = 0.

Parameter context:

The Context whose configuration and velocity variables may be used to evaluate kinetic energy.

Returns KE:

The kinetic energy in joules (J) represented by the configuration and velocity given in context.

See also

CalcKineticEnergy()

EvalPotentialEnergy(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context) → float

Returns a reference to the cached value of the potential energy (PE), evaluating first if necessary using CalcPotentialEnergy().

By definition here, potential energy depends only on “configuration” (e.g. orientation and position), which includes a subset of the state variables, and parameters that affect configuration or conservative forces (such as lengths and masses). The calculated value may also be affected by the accuracy value supplied in the Context. PE cannot depend explicitly on time (∂PE/∂t = 0), velocities (∂PE/∂v = 0), or input port values (∂PE/∂u = 0).

Non-physical systems where PE is not meaningful will return PE = 0.

Parameter context:

The Context whose configuration variables may be used to evaluate potential energy.

Returns PE:

The potential energy in joules (J) represented by the configuration given in context.

See also

CalcPotentialEnergy()

EvalTimeDerivatives(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context) → pydrake.systems.framework.ContinuousState

Returns a reference to the cached value of the continuous state variable time derivatives, evaluating first if necessary using CalcTimeDerivatives().

This method returns the time derivatives ẋ꜀ of the continuous state x꜀. The referenced return object will correspond elementwise with the continuous state in the given Context. Thus, if the state in the Context has second-order structure x꜀ = [q v z], that same structure applies to the derivatives so we will have ẋ꜀ = [q̇ ̇v̇ ż].

Parameter context:

The Context whose time, input port, parameter, state, and accuracy values may be used to evaluate the derivatives.

Returns xcdot:

Time derivatives ẋ꜀ of x꜀ returned as a reference to an object of the same type and size as context’s continuous state.

See also

BatchEvalTimeDerivatives() for a batch version of this method.

See also

CalcTimeDerivatives(), CalcImplicitTimeDerivativesResidual(), get_time_derivatives_cache_entry()

EvalUniquePeriodicDiscreteUpdate(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context) → pydrake.systems.framework.DiscreteValues

If this System contains a unique periodic timing for discrete update events, this function executes the handlers for those periodic events to determine what their effect would be. Returns a reference to the discrete variable cache entry containing what values the discrete variables would have if these periodic events were triggered.

Note that this function does not change the value of the discrete variables in the supplied Context. However, you can apply the result to the Context like this:

Click to expand C++ code...

const DiscreteValues<T>& updated =
system.EvalUniquePeriodicDiscreteUpdate(context);
context.SetDiscreteState(updated);

You can write the updated values to a different Context than the one you used to calculate the update; the requirement is only that the discrete state in the destination has the same structure (number of groups and size of each group).

You can use GetUniquePeriodicDiscreteUpdateAttribute() to check whether you can call EvalUniquePeriodicDiscreteUpdate() safely, and to find the unique periodic timing information (offset and period).

Warning

Even if we find a unique discrete update timing as described above, there may also be unrestricted updates performed with that timing or other timings. (Unrestricted updates can modify any state variables including discrete variables.) Also, there may be trigger types other than periodic that can modify discrete variables. This function does not attempt to look for any of those; they are simply ignored. If you are concerned with those, you can use GetPerStepEvents(), GetInitializationEvents(), and GetPeriodicEvents() to get a more comprehensive picture of the event landscape.

Parameter context:

The Context containing the current System state and the mutable cache space into which the result is written. The current state is not modified, though the cache entry may be updated.

Returns

A reference to the DiscreteValues cache space in context containing the result of applying the discrete update event handlers to the current discrete variable values.

Note

The referenced cache entry is recalculated if anything in the given Context has changed since last calculation. Subsequent calls just return the already-calculated value.

Raises

• RuntimeError if there is not exactly one periodic timing in this –

• System (which may be a Diagram) that triggers discrete update –

• events. –

• RuntimeError if it invokes an event handler that returns status –

• indicating failure. –

@par Implementation If recalculation is needed, copies the current discrete state values into preallocated context cache space. Applies the discrete update event handlers (in an unspecified order) to the cache copy, possibly updating it. Returns a reference to the possibly-updated cache space.

See also

BatchEvalUniquePeriodicDiscreteUpdate() for a batch version of this method.

See also

GetUniquePeriodicDiscreteUpdateAttribute(), GetPeriodicEvents()

EvalVectorInput(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context, port_index: int) → pydrake.systems.framework.BasicVector

Returns the value of the vector-valued input port with the given port_index as a BasicVector or a specific subclass Vec derived from BasicVector. Causes the value to become up to date first if necessary. See EvalAbstractInput() for more information.

The result is returned as a pointer to the input port’s value of type Vec<T> or nullptr if the port is not connected.

Precondition:

port_index selects an existing input port of this System.

Precondition:

the port must have been declared to be vector-valued.

Precondition:

the port’s value must be of type Vec<T>.

Template parameter Vec:

The template type of the input vector, which must be a subclass of BasicVector.

ExecuteForcedEvents(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context, publish: bool = True) → None

This method triggers all of the forced events registered with this System (which might be a Diagram). Ordering and status return handling mimic the Simulator: unrestricted events are processed first, then discrete update events, then publish events. “Reached termination” status returns are ignored.

An option is provided to suppress publish events. This can be useful, for example, to update state in a Diagram without triggering a visualization.

Parameter context:

The Context supplied to the handlers and modified in place on return.

Raises

• RuntimeError if it invokes an event handler that returns status –

• indicating failure. –

ExecuteInitializationEvents(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context) → None

This method triggers all of the initialization events returned by GetInitializationEvents(). The method allocates temporary storage to perform the updates, and is intended only as a convenience method for callers who do not want to use the full Simulator workflow.

Note that this is not fully equivalent to Simulator::Initialize() because only initialization events are handled here, while Simulator::Initialize() also processes other events associated with time zero. Also, “reached termination” returns are ignored here.

Parameter context:

The Context supplied to the handlers and modified in place on return.

Raises

• RuntimeError if it invokes an event handler that returns status –

• indicating failure. –

FixInputPortsFrom(self: pydrake.systems.framework.System, other_system: pydrake.systems.framework.System, other_context: pydrake.systems.framework.Context, target_context: pydrake.systems.framework.Context) → None

Fixes all of the input ports in target_context to their current values in other_context, as evaluated by other_system.

Raises

• RuntimeError unless other_context and target_context both –

• have the same shape as this System, and the other_system. –

• Ignores disconnected inputs. –

• RuntimeError if this system's scalar type T != double and –

• other_system` has any abstract input ports whose contained typ –

• depends on scalar type. –

ForcedPublish(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context) → None

(Advanced) Manually triggers any PublishEvent that has trigger type kForced. Invokes the publish event dispatcher on this System with the given Context.

The default dispatcher will invoke the handlers (if any) associated with each force-triggered event.

Note

There will always be at least one force-triggered event, though with no associated handler (so will do nothing when triggered).

The Simulator can be configured to call this in Simulator::Initialize() and at the start of each continuous integration step. See the Simulator API for more details.

Raises

• RuntimeError if it invokes an event handler that returns status –

• indicating failure. –

See also

Publish(), CalcForcedDiscreteVariableUpdate(), CalcForcedUnrestrictedUpdate()

get_input_port(*args, **kwargs)

Overloaded function.

1. get_input_port(self: pydrake.systems.framework.System, port_index: int, warn_deprecated: bool = True) -> pydrake.systems.framework.InputPort

Returns the typed input port at index port_index.

Parameter warn_deprecated:

Whether or not to print a warning in case the port was marked as deprecated.

2. get_input_port(self: pydrake.systems.framework.System) -> pydrake.systems.framework.InputPort

Convenience method for the case of exactly one input port. This function ignores deprecated ports, unless there is only one port in which case it will return the deprecated port.

get_output_port(*args, **kwargs)

Overloaded function.

1. get_output_port(self: pydrake.systems.framework.System, port_index: int, warn_deprecated: bool = True) -> pydrake.systems.framework.OutputPort

Returns the typed output port at index port_index.

Parameter warn_deprecated:

Whether or not to print a warning in case the port was marked as deprecated.

2. get_output_port(self: pydrake.systems.framework.System) -> pydrake.systems.framework.OutputPort

Convenience method for the case of exactly one output port. This function ignores deprecated ports, unless there is only one port in which case it will return the deprecated port.

GetInputPort(self: pydrake.systems.framework.System, port_name: str) → pydrake.systems.framework.InputPort

Returns the typed input port with the unique name port_name. The current implementation performs a linear search over strings; prefer get_input_port() when performance is a concern.

Raises

RuntimeError if port_name is not found. –

GetMutableSubsystemContext(self: pydrake.systems.framework.System, subsystem: pydrake.systems.framework.System, context: pydrake.systems.framework.Context) → pydrake.systems.framework.Context

Returns a mutable reference to the subcontext that corresponds to the contained System subsystem.

Raises

RuntimeError if subsystem not contained in this System. –

Precondition:

The given context is valid for use with this System.

GetMyContextFromRoot(self: pydrake.systems.framework.System, root_context: pydrake.systems.framework.Context) → pydrake.systems.framework.Context

Returns the mutable subsystem context for this system, given a root context.

See also

GetMyContextFromRoot()

GetMyMutableContextFromRoot(self: pydrake.systems.framework.System, root_context: pydrake.systems.framework.Context) → pydrake.systems.framework.Context

Returns the mutable subsystem context for this system, given a root context.

See also

GetMyContextFromRoot()

GetOutputPort(self: pydrake.systems.framework.System, port_name: str) → pydrake.systems.framework.OutputPort

Returns the typed output port with the unique name port_name. The current implementation performs a linear search over strings; prefer get_output_port() when performance is a concern.

Raises

RuntimeError if port_name is not found. –

GetSubsystemContext(self: pydrake.systems.framework.System, subsystem: pydrake.systems.framework.System, context: pydrake.systems.framework.Context) → pydrake.systems.framework.Context

Returns a mutable reference to the subcontext that corresponds to the contained System subsystem.

Raises

RuntimeError if subsystem not contained in this System. –

Precondition:

The given context is valid for use with this System.

GetUniquePeriodicDiscreteUpdateAttribute(self: pydrake.systems.framework.System) → Optional[pydrake.systems.framework.PeriodicEventData]

Determines whether there exists a unique periodic timing (offset and period) that triggers one or more discrete update events (and, if so, returns that unique periodic timing). Thus, this method can be used (1) as a test to determine whether a system’s dynamics are at least partially governed by difference equations, and (2) to obtain the difference equation update times. Use EvalUniquePeriodicDiscreteUpdate() if you want to determine the actual effects of triggering these events.

Warning

Even if we find a unique discrete update timing as described above, there may also be unrestricted updates performed with that timing or other timings. (Unrestricted updates can modify any state variables including discrete variables.) Also, there may be trigger types other than periodic that can modify discrete variables. This function does not attempt to look for any of those; they are simply ignored. If you are concerned with those, you can use GetPerStepEvents(), GetInitializationEvents(), and GetPeriodicEvents() to get a more comprehensive picture of the event landscape.

Returns

optional<PeriodicEventData> Contains the unique periodic trigger timing if it exists, otherwise nullopt.

See also

EvalUniquePeriodicDiscreteUpdate(), IsDifferenceEquationSystem()

GetWitnessFunctions(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context) → list[pydrake.systems.framework.WitnessFunction]

Derived classes can override this method to provide witness functions active for the given state. The default implementation does nothing. On entry to this function, the context will have already been validated and the vector of witness functions will have been validated to be both empty and non-null. Note: The above is for the C++ documentation. For Python, use witnesses = GetWitnessFunctions(context)

HasAnyDirectFeedthrough(self: pydrake.systems.framework.System) → bool

Returns True if any of the inputs to the system might be directly fed through to any of its outputs and False otherwise.

HasDirectFeedthrough(*args, **kwargs)

Overloaded function.

1. HasDirectFeedthrough(self: pydrake.systems.framework.System, output_port: int) -> bool

Returns true if there might be direct-feedthrough from any input port to the given output_port, and false otherwise.

2. HasDirectFeedthrough(self: pydrake.systems.framework.System, input_port: int, output_port: int) -> bool

Returns true if there might be direct-feedthrough from the given input_port to the given output_port, and false otherwise.

HasInputPort(self: pydrake.systems.framework.System, port_name: str) → bool

Returns true iff the system has an InputPort of the given port_name.

HasOutputPort(self: pydrake.systems.framework.System, port_name: str) → bool

Returns true iff the system has an OutputPort of the given port_name.

IsDifferenceEquationSystem(self: pydrake.systems.framework.System) → tuple[bool, float]

Returns true iff the state dynamics of this system are governed exclusively by a difference equation on a single discrete state group and with a unique periodic update (having zero offset). E.g., it is amenable to analysis of the form:

x[n+1] = f(n, x[n], u[n], w[n]; p)

where t is time, x is (discrete) state, u is a vector input, w is random (disturbance) input, and p are parameters. Note that we do NOT consider the number of input ports here, because in practice many systems of interest (e.g. MultibodyPlant) have input ports that are safely treated as constant during the analysis. Consider using get_input_port_selection() to choose one.

Warning

In determining whether this system is governed as above, we do not consider unrestricted updates nor any update events that have trigger types other than periodic. See GetUniquePeriodicDiscreteUpdateAttribute() for more information.

Parameter time_period:

if non-null, then iff the function returns True, then time_period is set to the period data returned from GetUniquePeriodicDiscreteUpdateAttribute(). If the function returns False (the system is not a difference equation system), then time_period does not receive a value.

See also

GetUniquePeriodicDiscreteUpdateAttribute()

See also

EvalUniquePeriodicDiscreteUpdate()

Note: The above is for the C++ documentation. For Python, use is_diff_eq, period = IsDifferenceEquationSystem()

IsDifferentialEquationSystem(self: pydrake.systems.framework.System) → bool

Returns true iff the state dynamics of this system are governed exclusively by a differential equation. E.g., it is amenable to analysis of the form:

ẋ = f(t, x(t), u(t), w(t); p),

where t is time, x is (continuous) state, u is a vector input, w is random (disturbance) input, and p are parameters. This requires that it has no discrete nor abstract states, and no abstract input ports.

Warning

In determining whether this system is governed as above, we do not consider unrestricted updates which could potentially update the state.

SetDefaultContext(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context) → None

Sets Context fields to their default values. User code should not override.

SetRandomContext(self: pydrake.systems.framework.System, context: pydrake.systems.framework.Context, generator: pydrake.common.RandomGenerator) → None

Sets Context fields to random values. User code should not override.

ToAutoDiffXd(self: pydrake.systems.framework.System) → pydrake.systems.framework.System_[AutoDiffXd]

Creates a deep copy of this System, transmogrified to use the autodiff scalar type, with a dynamic-sized vector of partial derivatives. The result is never nullptr.

Raises

RuntimeError if this System does not support autodiff –

See system_scalar_conversion for detailed background and examples related to scalar-type conversion support.

ToAutoDiffXdMaybe(self: pydrake.systems.framework.System) → pydrake.systems.framework.System_[AutoDiffXd]

Creates a deep copy of this system exactly like ToAutoDiffXd(), but returns nullptr if this System does not support autodiff, instead of throwing an exception.

template ToScalarType

Instantiations: ToScalarType[float], ToScalarType[AutoDiffXd], ToScalarType[Expression]

ToScalarType[AutoDiffXd](self: pydrake.systems.framework.System) → pydrake.systems.framework.System_[AutoDiffXd]

Creates a deep copy of this System, transmogrified to use the scalar type selected by a template parameter. The result is never nullptr.

Raises

RuntimeError if this System does not support the destination type. –

Template parameter U:

The destination scalar type. For a list of supported types, see the default_scalars “default scalars”.

See system_scalar_conversion for detailed background and examples related to scalar-type conversion support.

ToScalarType[Expression](self: pydrake.systems.framework.System) → pydrake.systems.framework.System_[Expression]

Creates a deep copy of this System, transmogrified to use the scalar type selected by a template parameter. The result is never nullptr.

Raises

RuntimeError if this System does not support the destination type. –

Template parameter U:

The destination scalar type. For a list of supported types, see the default_scalars “default scalars”.

See system_scalar_conversion for detailed background and examples related to scalar-type conversion support.

ToScalarType[float](self: pydrake.systems.framework.System) → pydrake.systems.framework.System

Creates a deep copy of this System, transmogrified to use the scalar type selected by a template parameter. The result is never nullptr.

Raises

RuntimeError if this System does not support the destination type. –

Template parameter U:

The destination scalar type. For a list of supported types, see the default_scalars “default scalars”.

See system_scalar_conversion for detailed background and examples related to scalar-type conversion support.

template ToScalarTypeMaybe

Instantiations: ToScalarTypeMaybe[float], ToScalarTypeMaybe[AutoDiffXd], ToScalarTypeMaybe[Expression]

ToScalarTypeMaybe[AutoDiffXd](self: pydrake.systems.framework.System) → pydrake.systems.framework.System_[AutoDiffXd]

Creates a deep copy of this system exactly like ToScalarType(), but returns nullptr if this System does not support the destination type, instead of throwing an exception.

Template parameter U:

The destination scalar type. For a list of supported types, see the default_scalars “default scalars”.

ToScalarTypeMaybe[Expression](self: pydrake.systems.framework.System) → pydrake.systems.framework.System_[Expression]

Creates a deep copy of this system exactly like ToScalarType(), but returns nullptr if this System does not support the destination type, instead of throwing an exception.

Template parameter U:

The destination scalar type. For a list of supported types, see the default_scalars “default scalars”.

ToScalarTypeMaybe[float](self: pydrake.systems.framework.System) → pydrake.systems.framework.System

Creates a deep copy of this system exactly like ToScalarType(), but returns nullptr if this System does not support the destination type, instead of throwing an exception.

Template parameter U:

The destination scalar type. For a list of supported types, see the default_scalars “default scalars”.

ToSymbolic(self: pydrake.systems.framework.System) → pydrake.systems.framework.System_[Expression]

Creates a deep copy of this System, transmogrified to use the symbolic scalar type. The result is never nullptr.

Raises

RuntimeError if this System does not support symbolic –

See system_scalar_conversion for detailed background and examples related to scalar-type conversion support.

ToSymbolicMaybe(self: pydrake.systems.framework.System) → pydrake.systems.framework.System_[Expression]

Creates a deep copy of this system exactly like ToSymbolic(), but returns nullptr if this System does not support symbolic, instead of throwing an exception.

template pydrake.systems.framework.System_

Instantiations: System_[float], System_[AutoDiffXd], System_[Expression]

class pydrake.systems.framework.System_[AutoDiffXd]

Bases: pydrake.systems.framework.SystemBase

Base class for all System functionality that is dependent on the templatized scalar type T for input, state, parameters, and outputs.

__init__(*args, **kwargs)

Accept(self: pydrake.systems.framework.System_[AutoDiffXd], v: pydrake.systems.framework.SystemVisitor_[AutoDiffXd]) → None

Implements a visitor pattern.

See also

SystemVisitor<T>.

AllocateContext(self: pydrake.systems.framework.System_[AutoDiffXd]) → pydrake.systems.framework.Context_[AutoDiffXd]

Returns a Context<T> suitable for use with this System<T>.

AllocateDiscreteVariables(self: pydrake.systems.framework.System_[AutoDiffXd]) → pydrake.systems.framework.DiscreteValues_[AutoDiffXd]

Returns a DiscreteValues of the same dimensions as the discrete_state allocated in CreateDefaultContext. The simulator will provide this state as the output argument to Update.

AllocateImplicitTimeDerivativesResidual(self: pydrake.systems.framework.System_[AutoDiffXd]) → numpy.ndarray[object[m, 1]]

Returns an Eigen VectorX suitable for use as the output argument to the CalcImplicitTimeDerivativesResidual() method. The returned VectorX will have size implicit_time_derivatives_residual_size() with the elements uninitialized. This is just a convenience method – you are free to use any properly-sized mutable Eigen object as the residual vector.

AllocateInputAbstract(self: pydrake.systems.framework.System_[AutoDiffXd], input_port: pydrake.systems.framework.InputPort_[AutoDiffXd]) → pydrake.common.value.AbstractValue

Given an input port, allocates the abstract storage. The input_port must match a port declared via DeclareInputPort.

AllocateInputVector(self: pydrake.systems.framework.System_[AutoDiffXd], input_port: pydrake.systems.framework.InputPort_[AutoDiffXd]) → pydrake.systems.framework.BasicVector_[AutoDiffXd]

Given an input port, allocates the vector storage. The input_port must match a port declared via DeclareInputPort.

AllocateOutput(self: pydrake.systems.framework.System_[AutoDiffXd]) → pydrake.systems.framework.SystemOutput_[AutoDiffXd]

Returns a container that can hold the values of all of this System’s output ports. It is sized with the number of output ports and uses each output port’s allocation method to provide an object of the right type for that port.

AllocateTimeDerivatives(self: pydrake.systems.framework.System_[AutoDiffXd]) → pydrake.systems.framework.ContinuousState_[AutoDiffXd]

Returns a ContinuousState of the same size as the continuous_state allocated in CreateDefaultContext. The simulator will provide this state as the output argument to EvalTimeDerivatives.

CalcConservativePower(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.autodiffutils.AutoDiffXd

Calculates and returns the conservative power represented by the current contents of the given context. Prefer EvalConservativePower() to avoid unnecessary recalculation.

See also

EvalConservativePower() for more information.

CalcForcedDiscreteVariableUpdate(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], discrete_state: pydrake.systems.framework.DiscreteValues_[AutoDiffXd]) → None

(Advanced) Manually triggers any DiscreteUpdateEvent that has trigger type kForced. Invokes the discrete event dispatcher on this System with the given Context providing the initial values for the discrete variables. The updated values of the discrete variables are written to the discrete_state output argument; no change is made to the Context.

The default dispatcher will invoke the handlers (if any) associated with each force-triggered event.

Note

There will always be at least one force-triggered event, though with no associated handler. By default that will do nothing when triggered, but that behavior can be changed by overriding the dispatcher (not recommended).

Raises

• RuntimeError if it invokes an event handler that returns status –

• indicating failure. –

See also

CalcDiscreteVariableUpdate(), CalcForcedUnrestrictedUpdate()

CalcForcedUnrestrictedUpdate(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], state: pydrake.systems.framework.State_[AutoDiffXd]) → None

(Advanced) Manually triggers any UnrestrictedUpdateEvent that has trigger type kForced. Invokes the unrestricted event dispatcher on this System with the given Context providing the initial values for the state variables. The updated values of the state variables are written to the state output argument; no change is made to the Context.

The default dispatcher will invoke the handlers (if any) associated with each force-triggered event.

Note

There will always be at least one force-triggered event, though with no associated handler. By default that will do nothing when triggered, but that behavior can be changed by overriding the dispatcher (not recommended).

Raises

• RuntimeError if it invokes an event handler that returns status –

• indicating failure. –

See also

CalcUnrestrictedUpdate()

CalcImplicitTimeDerivativesResidual(*args, **kwargs)

Overloaded function.

1. CalcImplicitTimeDerivativesResidual(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], proposed_derivatives: pydrake.systems.framework.ContinuousState_[AutoDiffXd], residual: Optional[numpy.ndarray[object[m, 1], flags.writeable]]) -> None

Evaluates the implicit form of the System equations and returns the residual.

The explicit and implicit forms of the System equations are

1. ẋ꜀ = fₑ(𝓒) explicit (2) 0 = fᵢ(𝓒; ẋ꜀) implicit

where 𝓒 = {a, p, t, x, u} is the current value of the given Context from which accuracy a, parameters p, time t, state x (={x꜀ xd xₐ}) and input values u are obtained. Substituting (1) into (2) shows that the following condition must always hold:

3. fᵢ(𝓒; fₑ(𝓒)) = 0 always true

When fᵢ(𝓒; ẋ꜀ₚ) is evaluated with a proposed time derivative ẋ꜀ₚ that differs from ẋ꜀ the result will be non-zero; we call that the residual of the implicit equation. Given a Context and proposed time derivative ẋ꜀ₚ, this method returns the residual r such that

4. r = fᵢ(𝓒; ẋ꜀ₚ).

The returned r will typically be the same length as x꜀ although that is not required. And even if r and x꜀ are the same size, there will not necessarily be any elementwise correspondence between them. (That is, you should not assume that r[i] is the “residual” of ẋ꜀ₚ[i].) For a Diagram, r is the concatenation of residuals from each of the subsystems, in order of subsystem index within the Diagram.

A default implementation fᵢ⁽ᵈᵉᶠ⁾ for the implicit form is always provided and makes use of the explicit form as follows:

5. fᵢ⁽ᵈᵉᶠ⁾(𝓒; ẋ꜀ₚ) ≜ ẋ꜀ₚ − fₑ(𝓒)

which satisfies condition (3) by construction. (Note that the default implementation requires the residual to have the same size as x꜀.) Substantial efficiency gains can often be obtained by replacing the default function with a customized implementation. Override DoCalcImplicitTimeDerivativesResidual() to replace the default implementation with a better one.

Parameter context:

The source for time, state, inputs, etc. to be used in calculating the residual.

Parameter proposed_derivatives:

The proposed value ẋ꜀ₚ for the time derivatives of x꜀.

Parameter residual:

The result r of evaluating the implicit function. Can be any mutable Eigen vector object of size implicit_time_derivatives_residual_size().

Precondition:

proposed_derivatives is compatible with this System.

Precondition:

residual is of size implicit_time_derivatives_residual_size().

See also

SystemBase::implicit_time_derivatives_residual_size()

See also

LeafSystem::DeclareImplicitTimeDerivativesResidualSize()

See also

DoCalcImplicitTimeDerivativesResidual()

See also

CalcTimeDerivatives()

2. CalcImplicitTimeDerivativesResidual(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], proposed_derivatives: pydrake.systems.framework.ContinuousState_[AutoDiffXd]) -> numpy.ndarray[object[m, 1]]

Evaluates the implicit form of the System equations and returns the residual.

The explicit and implicit forms of the System equations are

1. ẋ꜀ = fₑ(𝓒) explicit (2) 0 = fᵢ(𝓒; ẋ꜀) implicit

where 𝓒 = {a, p, t, x, u} is the current value of the given Context from which accuracy a, parameters p, time t, state x (={x꜀ xd xₐ}) and input values u are obtained. Substituting (1) into (2) shows that the following condition must always hold:

3. fᵢ(𝓒; fₑ(𝓒)) = 0 always true

When fᵢ(𝓒; ẋ꜀ₚ) is evaluated with a proposed time derivative ẋ꜀ₚ that differs from ẋ꜀ the result will be non-zero; we call that the residual of the implicit equation. Given a Context and proposed time derivative ẋ꜀ₚ, this method returns the residual r such that

4. r = fᵢ(𝓒; ẋ꜀ₚ).

The returned r will typically be the same length as x꜀ although that is not required. And even if r and x꜀ are the same size, there will not necessarily be any elementwise correspondence between them. (That is, you should not assume that r[i] is the “residual” of ẋ꜀ₚ[i].) For a Diagram, r is the concatenation of residuals from each of the subsystems, in order of subsystem index within the Diagram.

A default implementation fᵢ⁽ᵈᵉᶠ⁾ for the implicit form is always provided and makes use of the explicit form as follows:

5. fᵢ⁽ᵈᵉᶠ⁾(𝓒; ẋ꜀ₚ) ≜ ẋ꜀ₚ − fₑ(𝓒)

which satisfies condition (3) by construction. (Note that the default implementation requires the residual to have the same size as x꜀.) Substantial efficiency gains can often be obtained by replacing the default function with a customized implementation. Override DoCalcImplicitTimeDerivativesResidual() to replace the default implementation with a better one.

Parameter context:

The source for time, state, inputs, etc. to be used in calculating the residual.

Parameter proposed_derivatives:

The proposed value ẋ꜀ₚ for the time derivatives of x꜀.

Parameter residual:

The result r of evaluating the implicit function. Can be any mutable Eigen vector object of size implicit_time_derivatives_residual_size().

Precondition:

proposed_derivatives is compatible with this System.

Precondition:

residual is of size implicit_time_derivatives_residual_size().

See also

SystemBase::implicit_time_derivatives_residual_size()

See also

LeafSystem::DeclareImplicitTimeDerivativesResidualSize()

See also

DoCalcImplicitTimeDerivativesResidual()

See also

CalcTimeDerivatives()

CalcKineticEnergy(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.autodiffutils.AutoDiffXd

Calculates and returns the kinetic energy represented by the current configuration and velocity provided in context. Prefer EvalKineticEnergy() to avoid unnecessary recalculation.

See also

EvalKineticEnergy() for more information.

CalcNonConservativePower(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.autodiffutils.AutoDiffXd

Calculates and returns the non-conservative power represented by the current contents of the given context. Prefer EvalNonConservativePower() to avoid unnecessary recalculation.

See also

EvalNonConservativePower() for more information.

CalcOutput(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], outputs: pydrake.systems.framework.SystemOutput_[AutoDiffXd]) → None

Utility method that computes for every output port i the value y(i) that should result from the current contents of the given Context. Note that individual output port values can be calculated using get_output_port(i).Calc(); this method invokes that for each output port in index order. The result may depend on time and the current values of input ports, parameters, and state variables. The result is written to outputs which must already have been allocated to have the right number of entries of the right types.

CalcPotentialEnergy(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.autodiffutils.AutoDiffXd

Calculates and returns the potential energy represented by the current configuration provided in context. Prefer EvalPotentialEnergy() to avoid unnecessary recalculation.

See also

EvalPotentialEnergy() for more information.

CalcTimeDerivatives(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], derivatives: pydrake.systems.framework.ContinuousState_[AutoDiffXd]) → None

Calculates the time derivatives ẋ꜀ of the continuous state x꜀ into a given output argument. Prefer EvalTimeDerivatives() instead to avoid unnecessary recomputation.

This method solves the System equations in explicit form:

ẋ꜀ = fₑ(𝓒)

where 𝓒 = {a, p, t, x, u} is the current value of the given Context from which accuracy a, parameters p, time t, state x (={x꜀ xd xₐ}) and input values u are obtained.

Parameter context:

The source for time, state, inputs, etc. defining the point at which the derivatives should be calculated.

Parameter derivatives:

The time derivatives ẋ꜀. Must be the same size as the continuous state vector in context.

See also

EvalTimeDerivatives() for more information.

See also

CalcImplicitTimeDerivativesResidual() for the implicit form of these equations.

Clone(self: pydrake.systems.framework.System_[AutoDiffXd]) → pydrake.systems.framework.System_[AutoDiffXd]

Creates a deep copy of this system.

Even though the cloned system is functionally identical, any contexts created for this system are not compatible with the cloned system, and vice versa.

See also

Context::SetTimeStateAndParametersFrom() for how to copy context data between clones.

Warning

This implementation is somewhat incomplete at the moment. Many systems will not be able to be cloned, and will throw an exception instead. To be cloned, at minimum a system must support scalar conversion. See system_scalar_conversion.

The result is never nullptr.

CreateDefaultContext(self: pydrake.systems.framework.System_[AutoDiffXd]) → pydrake.systems.framework.Context_[AutoDiffXd]

This convenience method allocates a context using AllocateContext() and sets its default values using SetDefaultContext().

DeclareInputPort(self: pydrake.systems.framework.System_[AutoDiffXd], name: Union[str, pydrake.systems.framework.UseDefaultName], type: pydrake.systems.framework.PortDataType, size: int, random_type: Optional[pydrake.common.RandomDistribution] = None) → pydrake.systems.framework.InputPort_[AutoDiffXd]

Adds a port with the specified type and size to the input topology.

Input port names must be unique for this system (passing in a duplicate name will throw RuntimeError). If name is given as kUseDefaultName, then a default value of e.g. “u2”, where 2 is the input number will be provided. An empty name is not permitted.

If the port is intended to model a random noise or disturbance input, random_type can (optionally) be used to label it as such; doing so enables algorithms for design and analysis (e.g. state estimation) to reason explicitly about randomness at the system level. All random input ports are assumed to be statistically independent.

Precondition:

name must not be empty.

Raises

RuntimeError for a duplicate port name. –

Returns

the declared port.

EvalAbstractInput(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], port_index: int) → pydrake.common.value.AbstractValue

Returns the value of the input port with the given port_index as an AbstractValue, which is permitted for ports of any type. Causes the value to become up to date first if necessary, delegating to our parent Diagram. Returns a pointer to the port’s value, or nullptr if the port is not connected. If you know the actual type, use one of the more-specific signatures.

Precondition:

port_index selects an existing input port of this System.

See also

InputPort::Eval() (preferred)

EvalKineticEnergy(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.autodiffutils.AutoDiffXd

Returns a reference to the cached value of the kinetic energy (KE), evaluating first if necessary using CalcKineticEnergy().

By definition here, kinetic energy depends only on “configuration” and “velocity” (e.g. angular and translational velocity) of moving masses which includes a subset of the state variables, and parameters that affect configuration, velocities, or mass properties. The calculated value may also be affected by the accuracy value supplied in the Context. KE cannot depend explicitly on time (∂KE/∂t = 0) or input port values (∂KE/∂u = 0).

Non-physical systems where KE is not meaningful will return KE = 0.

Parameter context:

The Context whose configuration and velocity variables may be used to evaluate kinetic energy.

Returns KE:

The kinetic energy in joules (J) represented by the configuration and velocity given in context.

See also

CalcKineticEnergy()

EvalPotentialEnergy(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.autodiffutils.AutoDiffXd

Returns a reference to the cached value of the potential energy (PE), evaluating first if necessary using CalcPotentialEnergy().

By definition here, potential energy depends only on “configuration” (e.g. orientation and position), which includes a subset of the state variables, and parameters that affect configuration or conservative forces (such as lengths and masses). The calculated value may also be affected by the accuracy value supplied in the Context. PE cannot depend explicitly on time (∂PE/∂t = 0), velocities (∂PE/∂v = 0), or input port values (∂PE/∂u = 0).

Non-physical systems where PE is not meaningful will return PE = 0.

Parameter context:

The Context whose configuration variables may be used to evaluate potential energy.

Returns PE:

The potential energy in joules (J) represented by the configuration given in context.

See also

CalcPotentialEnergy()

EvalTimeDerivatives(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.systems.framework.ContinuousState_[AutoDiffXd]

Returns a reference to the cached value of the continuous state variable time derivatives, evaluating first if necessary using CalcTimeDerivatives().

This method returns the time derivatives ẋ꜀ of the continuous state x꜀. The referenced return object will correspond elementwise with the continuous state in the given Context. Thus, if the state in the Context has second-order structure x꜀ = [q v z], that same structure applies to the derivatives so we will have ẋ꜀ = [q̇ ̇v̇ ż].

Parameter context:

The Context whose time, input port, parameter, state, and accuracy values may be used to evaluate the derivatives.

Returns xcdot:

Time derivatives ẋ꜀ of x꜀ returned as a reference to an object of the same type and size as context’s continuous state.

See also

BatchEvalTimeDerivatives() for a batch version of this method.

See also

CalcTimeDerivatives(), CalcImplicitTimeDerivativesResidual(), get_time_derivatives_cache_entry()

EvalUniquePeriodicDiscreteUpdate(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.systems.framework.DiscreteValues_[AutoDiffXd]

If this System contains a unique periodic timing for discrete update events, this function executes the handlers for those periodic events to determine what their effect would be. Returns a reference to the discrete variable cache entry containing what values the discrete variables would have if these periodic events were triggered.

Note that this function does not change the value of the discrete variables in the supplied Context. However, you can apply the result to the Context like this:

Click to expand C++ code...

const DiscreteValues<T>& updated =
system.EvalUniquePeriodicDiscreteUpdate(context);
context.SetDiscreteState(updated);

You can write the updated values to a different Context than the one you used to calculate the update; the requirement is only that the discrete state in the destination has the same structure (number of groups and size of each group).

You can use GetUniquePeriodicDiscreteUpdateAttribute() to check whether you can call EvalUniquePeriodicDiscreteUpdate() safely, and to find the unique periodic timing information (offset and period).

Warning

Even if we find a unique discrete update timing as described above, there may also be unrestricted updates performed with that timing or other timings. (Unrestricted updates can modify any state variables including discrete variables.) Also, there may be trigger types other than periodic that can modify discrete variables. This function does not attempt to look for any of those; they are simply ignored. If you are concerned with those, you can use GetPerStepEvents(), GetInitializationEvents(), and GetPeriodicEvents() to get a more comprehensive picture of the event landscape.

Parameter context:

The Context containing the current System state and the mutable cache space into which the result is written. The current state is not modified, though the cache entry may be updated.

Returns

A reference to the DiscreteValues cache space in context containing the result of applying the discrete update event handlers to the current discrete variable values.

Note

The referenced cache entry is recalculated if anything in the given Context has changed since last calculation. Subsequent calls just return the already-calculated value.

Raises

• RuntimeError if there is not exactly one periodic timing in this –

• System (which may be a Diagram) that triggers discrete update –

• events. –

• RuntimeError if it invokes an event handler that returns status –

• indicating failure. –

@par Implementation If recalculation is needed, copies the current discrete state values into preallocated context cache space. Applies the discrete update event handlers (in an unspecified order) to the cache copy, possibly updating it. Returns a reference to the possibly-updated cache space.

See also

BatchEvalUniquePeriodicDiscreteUpdate() for a batch version of this method.

See also

GetUniquePeriodicDiscreteUpdateAttribute(), GetPeriodicEvents()

EvalVectorInput(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], port_index: int) → pydrake.systems.framework.BasicVector_[AutoDiffXd]

Returns the value of the vector-valued input port with the given port_index as a BasicVector or a specific subclass Vec derived from BasicVector. Causes the value to become up to date first if necessary. See EvalAbstractInput() for more information.

The result is returned as a pointer to the input port’s value of type Vec<T> or nullptr if the port is not connected.

Precondition:

port_index selects an existing input port of this System.

Precondition:

the port must have been declared to be vector-valued.

Precondition:

the port’s value must be of type Vec<T>.

Template parameter Vec:

The template type of the input vector, which must be a subclass of BasicVector.

ExecuteForcedEvents(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], publish: bool = True) → None

This method triggers all of the forced events registered with this System (which might be a Diagram). Ordering and status return handling mimic the Simulator: unrestricted events are processed first, then discrete update events, then publish events. “Reached termination” status returns are ignored.

An option is provided to suppress publish events. This can be useful, for example, to update state in a Diagram without triggering a visualization.

Parameter context:

The Context supplied to the handlers and modified in place on return.

Raises

• RuntimeError if it invokes an event handler that returns status –

• indicating failure. –

ExecuteInitializationEvents(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → None

This method triggers all of the initialization events returned by GetInitializationEvents(). The method allocates temporary storage to perform the updates, and is intended only as a convenience method for callers who do not want to use the full Simulator workflow.

Note that this is not fully equivalent to Simulator::Initialize() because only initialization events are handled here, while Simulator::Initialize() also processes other events associated with time zero. Also, “reached termination” returns are ignored here.

Parameter context:

The Context supplied to the handlers and modified in place on return.

Raises

• RuntimeError if it invokes an event handler that returns status –

• indicating failure. –

FixInputPortsFrom(self: pydrake.systems.framework.System_[AutoDiffXd], other_system: pydrake.systems.framework.System, other_context: pydrake.systems.framework.Context, target_context: pydrake.systems.framework.Context_[AutoDiffXd]) → None

Fixes all of the input ports in target_context to their current values in other_context, as evaluated by other_system.

Raises

• RuntimeError unless other_context and target_context both –

• have the same shape as this System, and the other_system. –

• Ignores disconnected inputs. –

• RuntimeError if this system's scalar type T != double and –

• other_system` has any abstract input ports whose contained typ –

• depends on scalar type. –

ForcedPublish(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → None

(Advanced) Manually triggers any PublishEvent that has trigger type kForced. Invokes the publish event dispatcher on this System with the given Context.

The default dispatcher will invoke the handlers (if any) associated with each force-triggered event.

Note

There will always be at least one force-triggered event, though with no associated handler (so will do nothing when triggered).

The Simulator can be configured to call this in Simulator::Initialize() and at the start of each continuous integration step. See the Simulator API for more details.

Raises

• RuntimeError if it invokes an event handler that returns status –

• indicating failure. –

See also

Publish(), CalcForcedDiscreteVariableUpdate(), CalcForcedUnrestrictedUpdate()

get_input_port(*args, **kwargs)

Overloaded function.

1. get_input_port(self: pydrake.systems.framework.System_[AutoDiffXd], port_index: int, warn_deprecated: bool = True) -> pydrake.systems.framework.InputPort_[AutoDiffXd]

Returns the typed input port at index port_index.

Parameter warn_deprecated:

Whether or not to print a warning in case the port was marked as deprecated.

2. get_input_port(self: pydrake.systems.framework.System_[AutoDiffXd]) -> pydrake.systems.framework.InputPort_[AutoDiffXd]

Convenience method for the case of exactly one input port. This function ignores deprecated ports, unless there is only one port in which case it will return the deprecated port.

get_output_port(*args, **kwargs)

Overloaded function.

1. get_output_port(self: pydrake.systems.framework.System_[AutoDiffXd], port_index: int, warn_deprecated: bool = True) -> pydrake.systems.framework.OutputPort_[AutoDiffXd]

Returns the typed output port at index port_index.

Parameter warn_deprecated:

Whether or not to print a warning in case the port was marked as deprecated.

2. get_output_port(self: pydrake.systems.framework.System_[AutoDiffXd]) -> pydrake.systems.framework.OutputPort_[AutoDiffXd]

Convenience method for the case of exactly one output port. This function ignores deprecated ports, unless there is only one port in which case it will return the deprecated port.

GetInputPort(self: pydrake.systems.framework.System_[AutoDiffXd], port_name: str) → pydrake.systems.framework.InputPort_[AutoDiffXd]

Returns the typed input port with the unique name port_name. The current implementation performs a linear search over strings; prefer get_input_port() when performance is a concern.

Raises

RuntimeError if port_name is not found. –

GetMutableSubsystemContext(self: pydrake.systems.framework.System_[AutoDiffXd], subsystem: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.systems.framework.Context_[AutoDiffXd]

Returns a mutable reference to the subcontext that corresponds to the contained System subsystem.

Raises

RuntimeError if subsystem not contained in this System. –

Precondition:

The given context is valid for use with this System.

GetMyContextFromRoot(self: pydrake.systems.framework.System_[AutoDiffXd], root_context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.systems.framework.Context_[AutoDiffXd]

Returns the mutable subsystem context for this system, given a root context.

See also

GetMyContextFromRoot()

GetMyMutableContextFromRoot(self: pydrake.systems.framework.System_[AutoDiffXd], root_context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.systems.framework.Context_[AutoDiffXd]

Returns the mutable subsystem context for this system, given a root context.

See also

GetMyContextFromRoot()

GetOutputPort(self: pydrake.systems.framework.System_[AutoDiffXd], port_name: str) → pydrake.systems.framework.OutputPort_[AutoDiffXd]

Returns the typed output port with the unique name port_name. The current implementation performs a linear search over strings; prefer get_output_port() when performance is a concern.

Raises

RuntimeError if port_name is not found. –

GetSubsystemContext(self: pydrake.systems.framework.System_[AutoDiffXd], subsystem: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → pydrake.systems.framework.Context_[AutoDiffXd]

Returns a mutable reference to the subcontext that corresponds to the contained System subsystem.

Raises

RuntimeError if subsystem not contained in this System. –

Precondition:

The given context is valid for use with this System.

GetUniquePeriodicDiscreteUpdateAttribute(self: pydrake.systems.framework.System_[AutoDiffXd]) → Optional[pydrake.systems.framework.PeriodicEventData]

Determines whether there exists a unique periodic timing (offset and period) that triggers one or more discrete update events (and, if so, returns that unique periodic timing). Thus, this method can be used (1) as a test to determine whether a system’s dynamics are at least partially governed by difference equations, and (2) to obtain the difference equation update times. Use EvalUniquePeriodicDiscreteUpdate() if you want to determine the actual effects of triggering these events.

Warning

Even if we find a unique discrete update timing as described above, there may also be unrestricted updates performed with that timing or other timings. (Unrestricted updates can modify any state variables including discrete variables.) Also, there may be trigger types other than periodic that can modify discrete variables. This function does not attempt to look for any of those; they are simply ignored. If you are concerned with those, you can use GetPerStepEvents(), GetInitializationEvents(), and GetPeriodicEvents() to get a more comprehensive picture of the event landscape.

Returns

optional<PeriodicEventData> Contains the unique periodic trigger timing if it exists, otherwise nullopt.

See also

EvalUniquePeriodicDiscreteUpdate(), IsDifferenceEquationSystem()

GetWitnessFunctions(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → list[pydrake.systems.framework.WitnessFunction_[AutoDiffXd]]

Derived classes can override this method to provide witness functions active for the given state. The default implementation does nothing. On entry to this function, the context will have already been validated and the vector of witness functions will have been validated to be both empty and non-null. Note: The above is for the C++ documentation. For Python, use witnesses = GetWitnessFunctions(context)

HasAnyDirectFeedthrough(self: pydrake.systems.framework.System_[AutoDiffXd]) → bool

Returns True if any of the inputs to the system might be directly fed through to any of its outputs and False otherwise.

HasDirectFeedthrough(*args, **kwargs)

Overloaded function.

1. HasDirectFeedthrough(self: pydrake.systems.framework.System_[AutoDiffXd], output_port: int) -> bool

Returns true if there might be direct-feedthrough from any input port to the given output_port, and false otherwise.

2. HasDirectFeedthrough(self: pydrake.systems.framework.System_[AutoDiffXd], input_port: int, output_port: int) -> bool

Returns true if there might be direct-feedthrough from the given input_port to the given output_port, and false otherwise.

HasInputPort(self: pydrake.systems.framework.System_[AutoDiffXd], port_name: str) → bool

Returns true iff the system has an InputPort of the given port_name.

HasOutputPort(self: pydrake.systems.framework.System_[AutoDiffXd], port_name: str) → bool

Returns true iff the system has an OutputPort of the given port_name.

IsDifferenceEquationSystem(self: pydrake.systems.framework.System_[AutoDiffXd]) → tuple[bool, float]

Returns true iff the state dynamics of this system are governed exclusively by a difference equation on a single discrete state group and with a unique periodic update (having zero offset). E.g., it is amenable to analysis of the form:

x[n+1] = f(n, x[n], u[n], w[n]; p)

where t is time, x is (discrete) state, u is a vector input, w is random (disturbance) input, and p are parameters. Note that we do NOT consider the number of input ports here, because in practice many systems of interest (e.g. MultibodyPlant) have input ports that are safely treated as constant during the analysis. Consider using get_input_port_selection() to choose one.

Warning

In determining whether this system is governed as above, we do not consider unrestricted updates nor any update events that have trigger types other than periodic. See GetUniquePeriodicDiscreteUpdateAttribute() for more information.

Parameter time_period:

if non-null, then iff the function returns True, then time_period is set to the period data returned from GetUniquePeriodicDiscreteUpdateAttribute(). If the function returns False (the system is not a difference equation system), then time_period does not receive a value.

See also

GetUniquePeriodicDiscreteUpdateAttribute()

See also

EvalUniquePeriodicDiscreteUpdate()

Note: The above is for the C++ documentation. For Python, use is_diff_eq, period = IsDifferenceEquationSystem()

IsDifferentialEquationSystem(self: pydrake.systems.framework.System_[AutoDiffXd]) → bool

Returns true iff the state dynamics of this system are governed exclusively by a differential equation. E.g., it is amenable to analysis of the form:

ẋ = f(t, x(t), u(t), w(t); p),

where t is time, x is (continuous) state, u is a vector input, w is random (disturbance) input, and p are parameters. This requires that it has no discrete nor abstract states, and no abstract input ports.

Warning

In determining whether this system is governed as above, we do not consider unrestricted updates which could potentially update the state.

SetDefaultContext(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd]) → None

Sets Context fields to their default values. User code should not override.

SetRandomContext(self: pydrake.systems.framework.System_[AutoDiffXd], context: pydrake.systems.framework.Context_[AutoDiffXd], generator: pydrake.common.RandomGenerator) → None

Sets Context fields to random values. User code should not override.

ToAutoDiffXd(self: pydrake.systems.framework.System_[AutoDiffXd]) → pydrake.systems.framework.System_[AutoDiffXd]

Creates a deep copy of this System, transmogrified to use the autodiff scalar type, with a dynamic-sized vector of partial derivatives. The result is never nullptr.

Raises

RuntimeError if this System does not support autodiff –

See system_scalar_conversion for detailed background and examples related to scalar-type conversion support.

ToAutoDiffXdMaybe(self: pydrake.systems.framework.System_[AutoDiffXd]) → pydrake.systems.framework.System_[AutoDiffXd]

Creates a deep copy of this system exactly like ToAutoDiffXd(), but returns nullptr if this System does not support autodiff, instead of throwing an exception.

template ToScalarType

Instantiations: ToScalarType[float], ToScalarType[AutoDiffXd], ToScalarType[Expression]

ToScalarType[AutoDiffXd](self: pydrake.systems.framework.System_[AutoDiffXd]) → pydrake.systems.framework.System_[AutoDiffXd]

Creates a deep copy of this System, transmogrified to use the scalar type selected by a template parameter. The result is never nullptr.

Raises

RuntimeError if this System does not support the destination type. –

Template parameter U:

The destination scalar type. For a list of supported types, see the default_scalars “default scalars”.

See system_scalar_conversion for detailed background and examples related to scalar-type conversion support.

ToScalarType[Expression](self: pydrake.systems.framework.System_[AutoDiffXd]) → pydrake.systems.framework.System_[Expression]

Creates a deep copy of this System, transmogrified to use the scalar type selected by a template parameter. The result is never nullptr.

Raises

RuntimeError if this System does not support the destination type. –

Template parameter U:

The destination scalar type. For a list of supported types, see the default_scalars “default scalars”.

See system_scalar_conversion for detailed background and examples related to scalar-type conversion support.

ToScalarType[float](self: pydrake.systems.framework.System_[AutoDiffXd]) → pydrake.systems.framework.System

Creates a deep copy of this System, transmogrified to use the scalar type selected by a template parameter. The result is never nullptr.

Raises

RuntimeError if this System does not support the destination type. –

Template parameter U:

The destination scalar type. For a list of supported types, see the default_scalars “default scalars”.

See system_scalar_conversion for detailed background and examples related to scalar-type conversion support.

template ToScalarTypeMaybe

Instantiations: ToScalarTypeMaybe[float], ToScalarTypeMaybe[AutoDiffXd], ToScalarTypeMaybe[Expression]

ToScalarTypeMaybe[AutoDiffXd](self: pydrake.systems.framework.System_[AutoDiffXd]) → pydrake.systems.framework.System_[AutoDiffXd]

Creates a deep copy of this system exactly like ToScalarType(), but returns nullptr if this System does not support the destination type, instead of throwing an exception.

Template parameter U:

The destination scalar type. For a list of supported types, see the default_scalars “default scalars”.

ToScalarTypeMaybe[Expression](self: pydrake.systems.framework.System_[AutoDiffXd]) → pydrake.systems.framework.System_[Expression]

Creates a deep copy of this system exactly like ToScalarType(), but returns nullptr if this System does not support the destination type, instead of throwing an exception.

Template parameter U:

The destination scalar type. For a list of supported types, see the default_scalars “default scalars”.

ToScalarTypeMaybe[float](self: pydrake.systems.framework.System_[AutoDiffXd]) → pydrake.systems.framework.System

Creates a deep copy of this system exactly like ToScalarType(), but returns nullptr if this System does not support the destination type, instead of throwing an exception.

Template parameter U:

The destination scalar type. For a list of supported types, see the default_scalars “default scalars”.

ToSymbolic(self: pydrake.systems.framework.System_[AutoDiffXd]) → pydrake.systems.framework.System_[Expression]

Creates a deep copy of this System, transmogrified to use the symbolic scalar type. The result is never nullptr.

Raises

RuntimeError if this System does not support symbolic –

See system_scalar_conversion for detailed background and examples related to scalar-type conversion support.

ToSymbolicMaybe(self: pydrake.systems.framework.System_[AutoDiffXd]) → pydrake.systems.framework.System_[Expression]

Creates a deep copy of this system exactly like ToSymbolic(), but returns nullptr if this System does not support symbolic, instead of throwing an exception.

class pydrake.systems.framework.System_[Expression]

Bases: pydrake.systems.framework.SystemBase

Base class for all System functionality that is dependent on the templatized scalar type T for input, state, parameters, and outputs.

__init__(*args, **kwargs)

Accept(self: pydrake.systems.framework.System_[Expression], v: pydrake.systems.framework.SystemVisitor_[Expression]) → None

Implements a visitor pattern.

See also

SystemVisitor<T>.

AllocateContext(self: pydrake.systems.framework.System_[Expression]) → pydrake.systems.framework.Context_[Expression]

Returns a Context<T> suitable for use with this System<T>.

AllocateDiscreteVariables(self: pydrake.systems.framework.System_[Expression]) → pydrake.systems.framework.DiscreteValues_[Expression]

Returns a DiscreteValues of the same dimensions as the discrete_state allocated in CreateDefaultContext. The simulator will provide this state as the output argument to Update.

AllocateImplicitTimeDerivativesResidual(self: pydrake.systems.framework.System_[Expression]) → numpy.ndarray[object[m, 1]]

Returns an Eigen VectorX suitable for use as the output argument to the CalcImplicitTimeDerivativesResidual() method. The returned VectorX will have size implicit_time_derivatives_residual_size() with the elements uninitialized. This is just a convenience method – you are free to use any properly-sized mutable Eigen object as the residual vector.

AllocateInputAbstract(self: pydrake.systems.framework.System_[Expression], input_port: pydrake.systems.framework.InputPort_[Expression]) → pydrake.common.value.AbstractValue

Given an input port, allocates the abstract storage. The input_port must match a port declared via DeclareInputPort.

AllocateInputVector(self: pydrake.systems.framework.System_[Expression], input_port: pydrake.systems.framework.InputPort_[Expression]) → pydrake.systems.framework.BasicVector_[Expression]

Given an input port, allocates the vector storage. The input_port must match a port declared via DeclareInputPort.

AllocateOutput(self: pydrake.systems.framework.System_[Expression]) → pydrake.systems.framework.SystemOutput_[Expression]

Returns a container that can hold the values of all of this System’s output ports. It is sized with the number of output ports and uses each output port’s allocation method to provide an object of the right type for that port.

AllocateTimeDerivatives(self: pydrake.systems.framework.System_[Expression]) → pydrake.systems.framework.ContinuousState_[Expression]

Returns a ContinuousState of the same size as the continuous_state allocated in CreateDefaultContext. The simulator will provide this state as the output argument to EvalTimeDerivatives.

CalcConservativePower(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.symbolic.Expression

Calculates and returns the conservative power represented by the current contents of the given context. Prefer EvalConservativePower() to avoid unnecessary recalculation.

See also

EvalConservativePower() for more information.

CalcForcedDiscreteVariableUpdate(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression], discrete_state: pydrake.systems.framework.DiscreteValues_[Expression]) → None

(Advanced) Manually triggers any DiscreteUpdateEvent that has trigger type kForced. Invokes the discrete event dispatcher on this System with the given Context providing the initial values for the discrete variables. The updated values of the discrete variables are written to the discrete_state output argument; no change is made to the Context.

The default dispatcher will invoke the handlers (if any) associated with each force-triggered event.

Note

There will always be at least one force-triggered event, though with no associated handler. By default that will do nothing when triggered, but that behavior can be changed by overriding the dispatcher (not recommended).

Raises

• RuntimeError if it invokes an event handler that returns status –

• indicating failure. –

See also

CalcDiscreteVariableUpdate(), CalcForcedUnrestrictedUpdate()

CalcForcedUnrestrictedUpdate(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression], state: pydrake.systems.framework.State_[Expression]) → None

(Advanced) Manually triggers any UnrestrictedUpdateEvent that has trigger type kForced. Invokes the unrestricted event dispatcher on this System with the given Context providing the initial values for the state variables. The updated values of the state variables are written to the state output argument; no change is made to the Context.

The default dispatcher will invoke the handlers (if any) associated with each force-triggered event.

Note

There will always be at least one force-triggered event, though with no associated handler. By default that will do nothing when triggered, but that behavior can be changed by overriding the dispatcher (not recommended).

Raises

• RuntimeError if it invokes an event handler that returns status –

• indicating failure. –

See also

CalcUnrestrictedUpdate()

CalcImplicitTimeDerivativesResidual(*args, **kwargs)

Overloaded function.

1. CalcImplicitTimeDerivativesResidual(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression], proposed_derivatives: pydrake.systems.framework.ContinuousState_[Expression], residual: Optional[numpy.ndarray[object[m, 1], flags.writeable]]) -> None

Evaluates the implicit form of the System equations and returns the residual.

The explicit and implicit forms of the System equations are

1. ẋ꜀ = fₑ(𝓒) explicit (2) 0 = fᵢ(𝓒; ẋ꜀) implicit

where 𝓒 = {a, p, t, x, u} is the current value of the given Context from which accuracy a, parameters p, time t, state x (={x꜀ xd xₐ}) and input values u are obtained. Substituting (1) into (2) shows that the following condition must always hold:

3. fᵢ(𝓒; fₑ(𝓒)) = 0 always true

When fᵢ(𝓒; ẋ꜀ₚ) is evaluated with a proposed time derivative ẋ꜀ₚ that differs from ẋ꜀ the result will be non-zero; we call that the residual of the implicit equation. Given a Context and proposed time derivative ẋ꜀ₚ, this method returns the residual r such that

4. r = fᵢ(𝓒; ẋ꜀ₚ).

The returned r will typically be the same length as x꜀ although that is not required. And even if r and x꜀ are the same size, there will not necessarily be any elementwise correspondence between them. (That is, you should not assume that r[i] is the “residual” of ẋ꜀ₚ[i].) For a Diagram, r is the concatenation of residuals from each of the subsystems, in order of subsystem index within the Diagram.

A default implementation fᵢ⁽ᵈᵉᶠ⁾ for the implicit form is always provided and makes use of the explicit form as follows:

5. fᵢ⁽ᵈᵉᶠ⁾(𝓒; ẋ꜀ₚ) ≜ ẋ꜀ₚ − fₑ(𝓒)

which satisfies condition (3) by construction. (Note that the default implementation requires the residual to have the same size as x꜀.) Substantial efficiency gains can often be obtained by replacing the default function with a customized implementation. Override DoCalcImplicitTimeDerivativesResidual() to replace the default implementation with a better one.

Parameter context:

The source for time, state, inputs, etc. to be used in calculating the residual.

Parameter proposed_derivatives:

The proposed value ẋ꜀ₚ for the time derivatives of x꜀.

Parameter residual:

The result r of evaluating the implicit function. Can be any mutable Eigen vector object of size implicit_time_derivatives_residual_size().

Precondition:

proposed_derivatives is compatible with this System.

Precondition:

residual is of size implicit_time_derivatives_residual_size().

See also

SystemBase::implicit_time_derivatives_residual_size()

See also

LeafSystem::DeclareImplicitTimeDerivativesResidualSize()

See also

DoCalcImplicitTimeDerivativesResidual()

See also

CalcTimeDerivatives()

2. CalcImplicitTimeDerivativesResidual(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression], proposed_derivatives: pydrake.systems.framework.ContinuousState_[Expression]) -> numpy.ndarray[object[m, 1]]

Evaluates the implicit form of the System equations and returns the residual.

The explicit and implicit forms of the System equations are

1. ẋ꜀ = fₑ(𝓒) explicit (2) 0 = fᵢ(𝓒; ẋ꜀) implicit

where 𝓒 = {a, p, t, x, u} is the current value of the given Context from which accuracy a, parameters p, time t, state x (={x꜀ xd xₐ}) and input values u are obtained. Substituting (1) into (2) shows that the following condition must always hold:

3. fᵢ(𝓒; fₑ(𝓒)) = 0 always true

When fᵢ(𝓒; ẋ꜀ₚ) is evaluated with a proposed time derivative ẋ꜀ₚ that differs from ẋ꜀ the result will be non-zero; we call that the residual of the implicit equation. Given a Context and proposed time derivative ẋ꜀ₚ, this method returns the residual r such that

4. r = fᵢ(𝓒; ẋ꜀ₚ).

The returned r will typically be the same length as x꜀ although that is not required. And even if r and x꜀ are the same size, there will not necessarily be any elementwise correspondence between them. (That is, you should not assume that r[i] is the “residual” of ẋ꜀ₚ[i].) For a Diagram, r is the concatenation of residuals from each of the subsystems, in order of subsystem index within the Diagram.

A default implementation fᵢ⁽ᵈᵉᶠ⁾ for the implicit form is always provided and makes use of the explicit form as follows:

5. fᵢ⁽ᵈᵉᶠ⁾(𝓒; ẋ꜀ₚ) ≜ ẋ꜀ₚ − fₑ(𝓒)

which satisfies condition (3) by construction. (Note that the default implementation requires the residual to have the same size as x꜀.) Substantial efficiency gains can often be obtained by replacing the default function with a customized implementation. Override DoCalcImplicitTimeDerivativesResidual() to replace the default implementation with a better one.

Parameter context:

The source for time, state, inputs, etc. to be used in calculating the residual.

Parameter proposed_derivatives:

The proposed value ẋ꜀ₚ for the time derivatives of x꜀.

Parameter residual:

The result r of evaluating the implicit function. Can be any mutable Eigen vector object of size implicit_time_derivatives_residual_size().

Precondition:

proposed_derivatives is compatible with this System.

Precondition:

residual is of size implicit_time_derivatives_residual_size().

See also

SystemBase::implicit_time_derivatives_residual_size()

See also

LeafSystem::DeclareImplicitTimeDerivativesResidualSize()

See also

DoCalcImplicitTimeDerivativesResidual()

See also

CalcTimeDerivatives()

CalcKineticEnergy(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.symbolic.Expression

Calculates and returns the kinetic energy represented by the current configuration and velocity provided in context. Prefer EvalKineticEnergy() to avoid unnecessary recalculation.

See also

EvalKineticEnergy() for more information.

CalcNonConservativePower(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.symbolic.Expression

Calculates and returns the non-conservative power represented by the current contents of the given context. Prefer EvalNonConservativePower() to avoid unnecessary recalculation.

See also

EvalNonConservativePower() for more information.

CalcOutput(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression], outputs: pydrake.systems.framework.SystemOutput_[Expression]) → None

Utility method that computes for every output port i the value y(i) that should result from the current contents of the given Context. Note that individual output port values can be calculated using get_output_port(i).Calc(); this method invokes that for each output port in index order. The result may depend on time and the current values of input ports, parameters, and state variables. The result is written to outputs which must already have been allocated to have the right number of entries of the right types.

CalcPotentialEnergy(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.symbolic.Expression

Calculates and returns the potential energy represented by the current configuration provided in context. Prefer EvalPotentialEnergy() to avoid unnecessary recalculation.

See also

EvalPotentialEnergy() for more information.

CalcTimeDerivatives(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression], derivatives: pydrake.systems.framework.ContinuousState_[Expression]) → None

Calculates the time derivatives ẋ꜀ of the continuous state x꜀ into a given output argument. Prefer EvalTimeDerivatives() instead to avoid unnecessary recomputation.

This method solves the System equations in explicit form:

ẋ꜀ = fₑ(𝓒)

where 𝓒 = {a, p, t, x, u} is the current value of the given Context from which accuracy a, parameters p, time t, state x (={x꜀ xd xₐ}) and input values u are obtained.

Parameter context:

The source for time, state, inputs, etc. defining the point at which the derivatives should be calculated.

Parameter derivatives:

The time derivatives ẋ꜀. Must be the same size as the continuous state vector in context.

See also

EvalTimeDerivatives() for more information.

See also

CalcImplicitTimeDerivativesResidual() for the implicit form of these equations.

Clone(self: pydrake.systems.framework.System_[Expression]) → pydrake.systems.framework.System_[Expression]

Creates a deep copy of this system.

Even though the cloned system is functionally identical, any contexts created for this system are not compatible with the cloned system, and vice versa.

See also

Context::SetTimeStateAndParametersFrom() for how to copy context data between clones.

Warning

This implementation is somewhat incomplete at the moment. Many systems will not be able to be cloned, and will throw an exception instead. To be cloned, at minimum a system must support scalar conversion. See system_scalar_conversion.

The result is never nullptr.

CreateDefaultContext(self: pydrake.systems.framework.System_[Expression]) → pydrake.systems.framework.Context_[Expression]

This convenience method allocates a context using AllocateContext() and sets its default values using SetDefaultContext().

DeclareInputPort(self: pydrake.systems.framework.System_[Expression], name: Union[str, pydrake.systems.framework.UseDefaultName], type: pydrake.systems.framework.PortDataType, size: int, random_type: Optional[pydrake.common.RandomDistribution] = None) → pydrake.systems.framework.InputPort_[Expression]

Adds a port with the specified type and size to the input topology.

Input port names must be unique for this system (passing in a duplicate name will throw RuntimeError). If name is given as kUseDefaultName, then a default value of e.g. “u2”, where 2 is the input number will be provided. An empty name is not permitted.

If the port is intended to model a random noise or disturbance input, random_type can (optionally) be used to label it as such; doing so enables algorithms for design and analysis (e.g. state estimation) to reason explicitly about randomness at the system level. All random input ports are assumed to be statistically independent.

Precondition:

name must not be empty.

Raises

RuntimeError for a duplicate port name. –

Returns

the declared port.

EvalAbstractInput(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression], port_index: int) → pydrake.common.value.AbstractValue

Returns the value of the input port with the given port_index as an AbstractValue, which is permitted for ports of any type. Causes the value to become up to date first if necessary, delegating to our parent Diagram. Returns a pointer to the port’s value, or nullptr if the port is not connected. If you know the actual type, use one of the more-specific signatures.

Precondition:

port_index selects an existing input port of this System.

See also

InputPort::Eval() (preferred)

EvalKineticEnergy(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.symbolic.Expression

Returns a reference to the cached value of the kinetic energy (KE), evaluating first if necessary using CalcKineticEnergy().

By definition here, kinetic energy depends only on “configuration” and “velocity” (e.g. angular and translational velocity) of moving masses which includes a subset of the state variables, and parameters that affect configuration, velocities, or mass properties. The calculated value may also be affected by the accuracy value supplied in the Context. KE cannot depend explicitly on time (∂KE/∂t = 0) or input port values (∂KE/∂u = 0).

Non-physical systems where KE is not meaningful will return KE = 0.

Parameter context:

The Context whose configuration and velocity variables may be used to evaluate kinetic energy.

Returns KE:

The kinetic energy in joules (J) represented by the configuration and velocity given in context.

See also

CalcKineticEnergy()

EvalPotentialEnergy(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.symbolic.Expression

Returns a reference to the cached value of the potential energy (PE), evaluating first if necessary using CalcPotentialEnergy().

By definition here, potential energy depends only on “configuration” (e.g. orientation and position), which includes a subset of the state variables, and parameters that affect configuration or conservative forces (such as lengths and masses). The calculated value may also be affected by the accuracy value supplied in the Context. PE cannot depend explicitly on time (∂PE/∂t = 0), velocities (∂PE/∂v = 0), or input port values (∂PE/∂u = 0).

Non-physical systems where PE is not meaningful will return PE = 0.

Parameter context:

The Context whose configuration variables may be used to evaluate potential energy.

Returns PE:

The potential energy in joules (J) represented by the configuration given in context.

See also

CalcPotentialEnergy()

EvalTimeDerivatives(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.systems.framework.ContinuousState_[Expression]

Returns a reference to the cached value of the continuous state variable time derivatives, evaluating first if necessary using CalcTimeDerivatives().

This method returns the time derivatives ẋ꜀ of the continuous state x꜀. The referenced return object will correspond elementwise with the continuous state in the given Context. Thus, if the state in the Context has second-order structure x꜀ = [q v z], that same structure applies to the derivatives so we will have ẋ꜀ = [q̇ ̇v̇ ż].

Parameter context:

The Context whose time, input port, parameter, state, and accuracy values may be used to evaluate the derivatives.

Returns xcdot:

Time derivatives ẋ꜀ of x꜀ returned as a reference to an object of the same type and size as context’s continuous state.

See also

BatchEvalTimeDerivatives() for a batch version of this method.

See also

CalcTimeDerivatives(), CalcImplicitTimeDerivativesResidual(), get_time_derivatives_cache_entry()

EvalUniquePeriodicDiscreteUpdate(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.systems.framework.DiscreteValues_[Expression]

If this System contains a unique periodic timing for discrete update events, this function executes the handlers for those periodic events to determine what their effect would be. Returns a reference to the discrete variable cache entry containing what values the discrete variables would have if these periodic events were triggered.

Note that this function does not change the value of the discrete variables in the supplied Context. However, you can apply the result to the Context like this:

Click to expand C++ code...

const DiscreteValues<T>& updated =
system.EvalUniquePeriodicDiscreteUpdate(context);
context.SetDiscreteState(updated);

You can write the updated values to a different Context than the one you used to calculate the update; the requirement is only that the discrete state in the destination has the same structure (number of groups and size of each group).

You can use GetUniquePeriodicDiscreteUpdateAttribute() to check whether you can call EvalUniquePeriodicDiscreteUpdate() safely, and to find the unique periodic timing information (offset and period).

Warning

Even if we find a unique discrete update timing as described above, there may also be unrestricted updates performed with that timing or other timings. (Unrestricted updates can modify any state variables including discrete variables.) Also, there may be trigger types other than periodic that can modify discrete variables. This function does not attempt to look for any of those; they are simply ignored. If you are concerned with those, you can use GetPerStepEvents(), GetInitializationEvents(), and GetPeriodicEvents() to get a more comprehensive picture of the event landscape.

Parameter context:

The Context containing the current System state and the mutable cache space into which the result is written. The current state is not modified, though the cache entry may be updated.

Returns

A reference to the DiscreteValues cache space in context containing the result of applying the discrete update event handlers to the current discrete variable values.

Note

The referenced cache entry is recalculated if anything in the given Context has changed since last calculation. Subsequent calls just return the already-calculated value.

Raises

• RuntimeError if there is not exactly one periodic timing in this –

• System (which may be a Diagram) that triggers discrete update –

• events. –

• RuntimeError if it invokes an event handler that returns status –

• indicating failure. –

@par Implementation If recalculation is needed, copies the current discrete state values into preallocated context cache space. Applies the discrete update event handlers (in an unspecified order) to the cache copy, possibly updating it. Returns a reference to the possibly-updated cache space.

See also

BatchEvalUniquePeriodicDiscreteUpdate() for a batch version of this method.

See also

GetUniquePeriodicDiscreteUpdateAttribute(), GetPeriodicEvents()

EvalVectorInput(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression], port_index: int) → pydrake.systems.framework.BasicVector_[Expression]

Returns the value of the vector-valued input port with the given port_index as a BasicVector or a specific subclass Vec derived from BasicVector. Causes the value to become up to date first if necessary. See EvalAbstractInput() for more information.

The result is returned as a pointer to the input port’s value of type Vec<T> or nullptr if the port is not connected.

Precondition:

port_index selects an existing input port of this System.

Precondition:

the port must have been declared to be vector-valued.

Precondition:

the port’s value must be of type Vec<T>.

Template parameter Vec:

The template type of the input vector, which must be a subclass of BasicVector.

ExecuteForcedEvents(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression], publish: bool = True) → None

This method triggers all of the forced events registered with this System (which might be a Diagram). Ordering and status return handling mimic the Simulator: unrestricted events are processed first, then discrete update events, then publish events. “Reached termination” status returns are ignored.

An option is provided to suppress publish events. This can be useful, for example, to update state in a Diagram without triggering a visualization.

Parameter context:

The Context supplied to the handlers and modified in place on return.

Raises

• RuntimeError if it invokes an event handler that returns status –

• indicating failure. –

ExecuteInitializationEvents(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression]) → None

This method triggers all of the initialization events returned by GetInitializationEvents(). The method allocates temporary storage to perform the updates, and is intended only as a convenience method for callers who do not want to use the full Simulator workflow.

Note that this is not fully equivalent to Simulator::Initialize() because only initialization events are handled here, while Simulator::Initialize() also processes other events associated with time zero. Also, “reached termination” returns are ignored here.

Parameter context:

The Context supplied to the handlers and modified in place on return.

Raises

• RuntimeError if it invokes an event handler that returns status –

• indicating failure. –

FixInputPortsFrom(self: pydrake.systems.framework.System_[Expression], other_system: pydrake.systems.framework.System, other_context: pydrake.systems.framework.Context, target_context: pydrake.systems.framework.Context_[Expression]) → None

Fixes all of the input ports in target_context to their current values in other_context, as evaluated by other_system.

Raises

• RuntimeError unless other_context and target_context both –

• have the same shape as this System, and the other_system. –

• Ignores disconnected inputs. –

• RuntimeError if this system's scalar type T != double and –

• other_system` has any abstract input ports whose contained typ –

• depends on scalar type. –

ForcedPublish(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression]) → None

(Advanced) Manually triggers any PublishEvent that has trigger type kForced. Invokes the publish event dispatcher on this System with the given Context.

The default dispatcher will invoke the handlers (if any) associated with each force-triggered event.

Note

There will always be at least one force-triggered event, though with no associated handler (so will do nothing when triggered).

The Simulator can be configured to call this in Simulator::Initialize() and at the start of each continuous integration step. See the Simulator API for more details.

Raises

• RuntimeError if it invokes an event handler that returns status –

• indicating failure. –

See also

Publish(), CalcForcedDiscreteVariableUpdate(), CalcForcedUnrestrictedUpdate()

get_input_port(*args, **kwargs)

Overloaded function.

1. get_input_port(self: pydrake.systems.framework.System_[Expression], port_index: int, warn_deprecated: bool = True) -> pydrake.systems.framework.InputPort_[Expression]

Returns the typed input port at index port_index.

Parameter warn_deprecated:

Whether or not to print a warning in case the port was marked as deprecated.

2. get_input_port(self: pydrake.systems.framework.System_[Expression]) -> pydrake.systems.framework.InputPort_[Expression]

Convenience method for the case of exactly one input port. This function ignores deprecated ports, unless there is only one port in which case it will return the deprecated port.

get_output_port(*args, **kwargs)

Overloaded function.

1. get_output_port(self: pydrake.systems.framework.System_[Expression], port_index: int, warn_deprecated: bool = True) -> pydrake.systems.framework.OutputPort_[Expression]

Returns the typed output port at index port_index.

Parameter warn_deprecated:

Whether or not to print a warning in case the port was marked as deprecated.

2. get_output_port(self: pydrake.systems.framework.System_[Expression]) -> pydrake.systems.framework.OutputPort_[Expression]

Convenience method for the case of exactly one output port. This function ignores deprecated ports, unless there is only one port in which case it will return the deprecated port.

GetInputPort(self: pydrake.systems.framework.System_[Expression], port_name: str) → pydrake.systems.framework.InputPort_[Expression]

Returns the typed input port with the unique name port_name. The current implementation performs a linear search over strings; prefer get_input_port() when performance is a concern.

Raises

RuntimeError if port_name is not found. –

GetMutableSubsystemContext(self: pydrake.systems.framework.System_[Expression], subsystem: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.systems.framework.Context_[Expression]

Returns a mutable reference to the subcontext that corresponds to the contained System subsystem.

Raises

RuntimeError if subsystem not contained in this System. –

Precondition:

The given context is valid for use with this System.

GetMyContextFromRoot(self: pydrake.systems.framework.System_[Expression], root_context: pydrake.systems.framework.Context_[Expression]) → pydrake.systems.framework.Context_[Expression]

Returns the mutable subsystem context for this system, given a root context.

See also

GetMyContextFromRoot()

GetMyMutableContextFromRoot(self: pydrake.systems.framework.System_[Expression], root_context: pydrake.systems.framework.Context_[Expression]) → pydrake.systems.framework.Context_[Expression]

Returns the mutable subsystem context for this system, given a root context.

See also

GetMyContextFromRoot()

GetOutputPort(self: pydrake.systems.framework.System_[Expression], port_name: str) → pydrake.systems.framework.OutputPort_[Expression]

Returns the typed output port with the unique name port_name. The current implementation performs a linear search over strings; prefer get_output_port() when performance is a concern.

Raises

RuntimeError if port_name is not found. –

GetSubsystemContext(self: pydrake.systems.framework.System_[Expression], subsystem: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression]) → pydrake.systems.framework.Context_[Expression]

Returns a mutable reference to the subcontext that corresponds to the contained System subsystem.

Raises

RuntimeError if subsystem not contained in this System. –

Precondition:

The given context is valid for use with this System.

GetUniquePeriodicDiscreteUpdateAttribute(self: pydrake.systems.framework.System_[Expression]) → Optional[pydrake.systems.framework.PeriodicEventData]

Determines whether there exists a unique periodic timing (offset and period) that triggers one or more discrete update events (and, if so, returns that unique periodic timing). Thus, this method can be used (1) as a test to determine whether a system’s dynamics are at least partially governed by difference equations, and (2) to obtain the difference equation update times. Use EvalUniquePeriodicDiscreteUpdate() if you want to determine the actual effects of triggering these events.

Warning

Even if we find a unique discrete update timing as described above, there may also be unrestricted updates performed with that timing or other timings. (Unrestricted updates can modify any state variables including discrete variables.) Also, there may be trigger types other than periodic that can modify discrete variables. This function does not attempt to look for any of those; they are simply ignored. If you are concerned with those, you can use GetPerStepEvents(), GetInitializationEvents(), and GetPeriodicEvents() to get a more comprehensive picture of the event landscape.

Returns

optional<PeriodicEventData> Contains the unique periodic trigger timing if it exists, otherwise nullopt.

See also

EvalUniquePeriodicDiscreteUpdate(), IsDifferenceEquationSystem()

GetWitnessFunctions(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression]) → list[pydrake.systems.framework.WitnessFunction_[Expression]]

Derived classes can override this method to provide witness functions active for the given state. The default implementation does nothing. On entry to this function, the context will have already been validated and the vector of witness functions will have been validated to be both empty and non-null. Note: The above is for the C++ documentation. For Python, use witnesses = GetWitnessFunctions(context)

HasAnyDirectFeedthrough(self: pydrake.systems.framework.System_[Expression]) → bool

Returns True if any of the inputs to the system might be directly fed through to any of its outputs and False otherwise.

HasDirectFeedthrough(*args, **kwargs)

Overloaded function.

1. HasDirectFeedthrough(self: pydrake.systems.framework.System_[Expression], output_port: int) -> bool

Returns true if there might be direct-feedthrough from any input port to the given output_port, and false otherwise.

2. HasDirectFeedthrough(self: pydrake.systems.framework.System_[Expression], input_port: int, output_port: int) -> bool

Returns true if there might be direct-feedthrough from the given input_port to the given output_port, and false otherwise.

HasInputPort(self: pydrake.systems.framework.System_[Expression], port_name: str) → bool

Returns true iff the system has an InputPort of the given port_name.

HasOutputPort(self: pydrake.systems.framework.System_[Expression], port_name: str) → bool

Returns true iff the system has an OutputPort of the given port_name.

IsDifferenceEquationSystem(self: pydrake.systems.framework.System_[Expression]) → tuple[bool, float]

Returns true iff the state dynamics of this system are governed exclusively by a difference equation on a single discrete state group and with a unique periodic update (having zero offset). E.g., it is amenable to analysis of the form:

x[n+1] = f(n, x[n], u[n], w[n]; p)

where t is time, x is (discrete) state, u is a vector input, w is random (disturbance) input, and p are parameters. Note that we do NOT consider the number of input ports here, because in practice many systems of interest (e.g. MultibodyPlant) have input ports that are safely treated as constant during the analysis. Consider using get_input_port_selection() to choose one.

Warning

In determining whether this system is governed as above, we do not consider unrestricted updates nor any update events that have trigger types other than periodic. See GetUniquePeriodicDiscreteUpdateAttribute() for more information.

Parameter time_period:

if non-null, then iff the function returns True, then time_period is set to the period data returned from GetUniquePeriodicDiscreteUpdateAttribute(). If the function returns False (the system is not a difference equation system), then time_period does not receive a value.

See also

GetUniquePeriodicDiscreteUpdateAttribute()

See also

EvalUniquePeriodicDiscreteUpdate()

Note: The above is for the C++ documentation. For Python, use is_diff_eq, period = IsDifferenceEquationSystem()

IsDifferentialEquationSystem(self: pydrake.systems.framework.System_[Expression]) → bool

Returns true iff the state dynamics of this system are governed exclusively by a differential equation. E.g., it is amenable to analysis of the form:

ẋ = f(t, x(t), u(t), w(t); p),

where t is time, x is (continuous) state, u is a vector input, w is random (disturbance) input, and p are parameters. This requires that it has no discrete nor abstract states, and no abstract input ports.

Warning

In determining whether this system is governed as above, we do not consider unrestricted updates which could potentially update the state.

SetDefaultContext(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression]) → None

Sets Context fields to their default values. User code should not override.

SetRandomContext(self: pydrake.systems.framework.System_[Expression], context: pydrake.systems.framework.Context_[Expression], generator: pydrake.common.RandomGenerator) → None

Sets Context fields to random values. User code should not override.

ToAutoDiffXd(self: pydrake.systems.framework.System_[Expression]) → pydrake.systems.framework.System_[AutoDiffXd]

Creates a deep copy of this System, transmogrified to use the autodiff scalar type, with a dynamic-sized vector of partial derivatives. The result is never nullptr.

Raises

RuntimeError if this System does not support autodiff –

See system_scalar_conversion for detailed background and examples related to scalar-type conversion support.

ToAutoDiffXdMaybe(self: pydrake.systems.framework.System_[Expression]) → pydrake.systems.framework.System_[AutoDiffXd]

Creates a deep copy of this system exactly like ToAutoDiffXd(), but returns nullptr if this System does not support autodiff, instead of throwing an exception.

template ToScalarType

Instantiations: ToScalarType[float], ToScalarType[AutoDiffXd], ToScalarType[Expression]

ToScalarType[AutoDiffXd](self: pydrake.systems.framework.System_[Expression]) → pydrake.systems.framework.System_[AutoDiffXd]

Creates a deep copy of this System, transmogrified to use the scalar type selected by a template parameter. The result is never nullptr.

Raises

RuntimeError if this System does not support the destination type. –

Template parameter U:

The destination scalar type. For a list of supported types, see the default_scalars “default scalars”.

See system_scalar_conversion for detailed background and examples related to scalar-type conversion support.

ToScalarType[Expression](self: pydrake.systems.framework.System_[Expression]) → pydrake.systems.framework.System_[Expression]

Creates a deep copy of this System, transmogrified to use the scalar type selected by a template parameter. The result is never nullptr.

Raises

RuntimeError if this System does not support the destination type. –

Template parameter U:

The destination scalar type. For a list of supported types, see the default_scalars “default scalars”.

See system_scalar_conversion for detailed background and examples related to scalar-type conversion support.

ToScalarType[float](self: pydrake.systems.framework.System_[Expression]) → pydrake.systems.framework.System

Creates a deep copy of this System, transmogrified to use the scalar type selected by a template parameter. The result is never nullptr.

Raises

RuntimeError if this System does not support the destination type. –

Template parameter U:

The destination scalar type. For a list of supported types, see the default_scalars “default scalars”.

See system_scalar_conversion for detailed background and examples related to scalar-type conversion support.

template ToScalarTypeMaybe

Instantiations: ToScalarTypeMaybe[float], ToScalarTypeMaybe[AutoDiffXd], ToScalarTypeMaybe[Expression]

ToScalarTypeMaybe[AutoDiffXd](self: pydrake.systems.framework.System_[Expression]) → pydrake.systems.framework.System_[AutoDiffXd]

Creates a deep copy of this system exactly like ToScalarType(), but returns nullptr if this System does not support the destination type, instead of throwing an exception.

Template parameter U:

The destination scalar type. For a list of supported types, see the default_scalars “default scalars”.

ToScalarTypeMaybe[Expression](self: pydrake.systems.framework.System_[Expression]) → pydrake.systems.framework.System_[Expression]

Creates a deep copy of this system exactly like ToScalarType(), but returns nullptr if this System does not support the destination type, instead of throwing an exception.

Template parameter U:

The destination scalar type. For a list of supported types, see the default_scalars “default scalars”.

ToScalarTypeMaybe[float](self: pydrake.systems.framework.System_[Expression]) → pydrake.systems.framework.System

Creates a deep copy of this system exactly like ToScalarType(), but returns nullptr if this System does not support the destination type, instead of throwing an exception.

Template parameter U:

The destination scalar type. For a list of supported types, see the default_scalars “default scalars”.

ToSymbolic(self: pydrake.systems.framework.System_[Expression]) → pydrake.systems.framework.System_[Expression]

Creates a deep copy of this System, transmogrified to use the symbolic scalar type. The result is never nullptr.

Raises

RuntimeError if this System does not support symbolic –

See system_scalar_conversion for detailed background and examples related to scalar-type conversion support.

ToSymbolicMaybe(self: pydrake.systems.framework.System_[Expression]) → pydrake.systems.framework.System_[Expression]

Creates a deep copy of this system exactly like ToSymbolic(), but returns nullptr if this System does not support symbolic, instead of throwing an exception.

class pydrake.systems.framework.SystemBase

Provides non-templatized functionality shared by the templatized System classes.

Terminology: in general a Drake System is a tree structure composed of “subsystems”, which are themselves System objects. The corresponding Context is a parallel tree structure composed of “subcontexts”, which are themselves Context objects. There is a one-to-one correspondence between subsystems and subcontexts. Within a given System (Context), its child subsystems (subcontexts) are indexed using a SubsystemIndex; there is no separate SubcontextIndex since the numbering must be identical.

__init__(*args, **kwargs)

abstract_parameter_ticket(self: pydrake.systems.framework.SystemBase, index: pydrake.systems.framework.AbstractParameterIndex) → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on a particular abstract parameter paᵢ.

See also

pa_ticket() to obtain a ticket for all abstract parameters.

abstract_state_ticket(self: pydrake.systems.framework.SystemBase, index: pydrake.systems.framework.AbstractStateIndex) → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on a particular abstract state variable xaᵢ.

See also

xa_ticket() to obtain a ticket for all abstract variables.

static accuracy_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on the accuracy setting in the Context. This is the same ticket for all systems and refers to the same accuracy value.

static all_input_ports_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on all input ports u of this system.

See also

input_port_ticket() to obtain a ticket for just one input port.

static all_parameters_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on all parameters p in this system, including numeric parameters pn, and abstract parameters pa.

static all_sources_except_input_ports_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on every possible independent source value except input ports. This can be helpful in avoiding the incorrect appearance of algebraic loops in a Diagram (those always involve apparent input port dependencies). For an output port, use this ticket plus tickets for just the input ports on which the output computation actually depends. The sources included in this ticket are: time, accuracy, state, and parameters. Note that dependencies on cache entries are not included here. Usually that won’t matter since cache entries typically depend on at least one of time, accuracy, state, or parameters so will be invalidated for the same reason the current computation is. However, for a computation that depends on a cache entry that depends only on input ports, be sure that you have included those input ports in the dependency list, or include a direct dependency on the cache entry.

See also

input_port_ticket() to obtain a ticket for an input port.

See also

cache_entry_ticket() to obtain a ticket for a cache entry.

See also

all_sources_ticket() to also include all input ports as dependencies.

static all_sources_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on every possible independent source value, including time, accuracy, state, input ports, and parameters (but not cache entries). This is the default dependency for computations that have not specified anything more refined. It is equivalent to the set {all_sources_except_input_ports_ticket(), all_input_ports_ticket()}.

See also

cache_entry_ticket() to obtain a ticket for a cache entry.

static all_state_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on all state variables x in this system, including continuous variables xc, discrete (numeric) variables xd, and abstract state variables xa. This does not imply dependence on time, accuracy, parameters, or inputs; those must be specified separately. If you mean to express dependence on all possible value sources, use all_sources_ticket() instead.

cache_entry_ticket(self: pydrake.systems.framework.SystemBase, index: pydrake.systems.framework.CacheIndex) → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on the cache entry indicated by index. Note that cache entries are not included in the all_sources ticket so must be listed separately.

Precondition:

index selects an existing cache entry in this System.

static configuration_ticket() → pydrake.systems.framework.DependencyTicket

DeclareCacheEntry(self: pydrake.systems.framework.SystemBase, description: str, value_producer: pydrake.systems.framework.ValueProducer, prerequisites_of_calc: set[pydrake.systems.framework.DependencyTicket] = {DependencyTicket(15)}) → pydrake.systems.framework.CacheEntry

Declares a new CacheEntry in this System using the most generic form of the calculation function. Prefer one of the more convenient signatures below if you can. The new cache entry is assigned a unique CacheIndex and DependencyTicket, which can be obtained from the returned CacheEntry.

Parameter description:

A human-readable description of this cache entry, most useful for debugging and documentation. Not interpreted in any way by Drake; it is retained by the cache entry and used to generate the description for the corresponding CacheEntryValue in the Context.

Parameter value_producer:

Provides the computation that maps from a given Context to the current value that this cache entry should have, as well as a way to allocate storage prior to the computation.

Parameter prerequisites_of_calc:

Provides the DependencyTicket list containing a ticket for every Context value on which calc_function may depend when it computes its result. Defaults to {all_sources_ticket()} if unspecified. If the cache value is truly independent of the Context (rare!) say so explicitly by providing the list {nothing_ticket()}; an explicitly empty list {} is forbidden.

Returns

a reference to the newly-created CacheEntry.

Raises

RuntimeError if given an explicitly empty prerequisite list. –

discrete_state_ticket(self: pydrake.systems.framework.SystemBase, index: pydrake.systems.framework.DiscreteStateIndex) → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on a particular discrete state variable xdᵢ (may be a vector). (We sometimes refer to this as a “discrete variable group”.)

See also

xd_ticket() to obtain a ticket for all discrete variables.

DoGetGraphvizFragment(self: pydrake.systems.framework.SystemBase, arg0: pydrake.systems.framework.SystemBase.GraphvizFragmentParams) → pydrake.systems.framework.SystemBase.GraphvizFragment

The NVI implementation of GetGraphvizFragment() for subclasses to override if desired. The default behavior should be sufficient in most cases.

get_cache_entry(self: pydrake.systems.framework.SystemBase, index: pydrake.systems.framework.CacheIndex) → pydrake.systems.framework.CacheEntry

Returns a reference to a CacheEntry given its index.

get_name(self: pydrake.systems.framework.SystemBase) → str

Returns the name last supplied to set_name(), if any. Diagrams built with DiagramBuilder will always have a default name for every contained subsystem for which no user-provided name is available. Systems created by copying with a scalar type change have the same name as the source system. An empty string is returned if no name has been set.

GetGraphvizFragment(self: pydrake.systems.framework.SystemBase, max_depth: Optional[int] = None, options: dict[str, str] = {}) → pydrake.systems.framework.SystemBase.GraphvizFragment

(Advanced) Like GetGraphvizString() but does not wrap the string in a digraph { … }. This is useful when merging the fragment into another graph, and is how Diagram obtains the Graphviz content for its subsystems. The parameters are identical to GetGraphvizString(). The return value contains additional metadata beyond the Graphviz content, to better support merging.

GetGraphvizString(self: pydrake.systems.framework.SystemBase, max_depth: Optional[int] = None, options: dict[str, str] = {}) → str

Returns a Graphviz string describing this System. To render the string, use the Graphviz tool, dot.

Notes about the display conventions:

• The nodes of the graph are systems, and the solid edges are connections

between system input and output ports.

• The class name of a System is shown in Bold atop the node.

• Under the class name, if a System has been given a name via set_name(),

it will be displayed as name=....

• Systems can elect to display additional properties besides their name;

see GraphvizFragmentParams::header_lines for implementation details.

• A Diagram’s input ports are shown with a

<span style=”border:2px solid blue;border-radius:4px”>blue border</span> and output ports are shown with a <span style=”border:2px solid green;border-radius:4px”>green border</span>.

• Zero-sized ports are <span style=”color:grey”>greyed out</span>.

• Deprecated ports are <strike>struck through</strike> and flagged with a

headstone emoji (🪦) after their name.

Parameter max_depth:

Sets a limit to the depth of nested diagrams to visualize. Use zero to render a diagram as a single system block.

Parameter options:

Arbitrary strings to request alterations to the output. Options that are unknown will be silently skipped. These options are often bespoke flags that are only understood by particular systems, but Drake has one built-in flag that is generally applicable: "split". When set to "I/O", the system will be added as two nodes with all inputs on one node and all outputs on the other; this is useful for systems that might otherwise cause problematic visual cycles.

Options are applied only to this immediate system; they are not inherited by the subsystems of a Diagram. To specify an option for a Diagram’s subsystem, prefix the option name with the subsystem’s path, e.g., use "plant/split"="I/O" to set the "split" option on the subsystem named "plant".

GetSystemName(self: pydrake.systems.framework.SystemBase) → str

Returns a human-readable name for this system, for use in messages and logging. This will be the same as returned by get_name(), unless that would be an empty string. In that case we return a non-unique placeholder name, currently just “_” (a lone underscore).

GetSystemPathname(self: pydrake.systems.framework.SystemBase) → str

Generates and returns a human-readable full path name of this subsystem, for use in messages and logging. The name starts from the root System, with “::” delimiters between parent and child subsystems, with the individual subsystems represented by their names as returned by GetSystemName().

GetSystemType(self: pydrake.systems.framework.SystemBase) → str

Returns the most-derived type of this concrete System object as a human-readable string suitable for use in error messages. The format is as generated by NiceTypeName and will include namespace qualification if present.

See also

NiceTypeName for more specifics.

class GraphvizFragment

(Advanced) The return type of GetGraphvizFragment().

__init__(*args, **kwargs)

property fragments

The Graphviz content for this System. The fragments must be a valid Graphviz figure when concatenated and then wrapped in a digraph { … } or subgraph { … } stanza. During concatenation, no extra newlines or any other kind of whitespace should be inserted. (This is a list of strings, rather than a single string, to avoid redundant string concatenation until the last moment when we return the final GetGraphvizString().)

property input_ports

The Graphviz IDs for this System’s input ports, to be used for adding Graphviz edges. The i’th element is the ID for get_input_port(i). For a typical LeafSystem these will look like “s123:u0”, “s123:u1”, … but for diagrams and other special cases they might vary.

property output_ports

The Graphviz IDs for this System’s output ports, to be used for adding Graphviz edges. The i’th element is the ID for get_output_port(i). For a typical LeafSystem these will look like “s123:y0”, “s123:y1”, … but for diagrams and other special cases they might vary.

class GraphvizFragmentParams

(Advanced) The arguments to the protected method DoGetGraphvizFragment(). This struct typically is only used by subclasses of LeafSystem that need to customize their Graphviz representation. These parameters constitute a polite request; a user’s System’s implementation of DoGetGraphvizFragment() is not strictly required to honor any of these parameters, but generally should attempt to honor as many as possible.

__init__(*args, **kwargs)

property header_lines

The header line(s) to use for this Graphviz node’s table. The strings in header_lines should not contain newlines; those are added automatically, along with ``

`` breaks between lines.

property max_depth

As per GetGraphvizString().

property node_id

The Graphviz ID to use for this node.

property options

As per GetGraphvizString().

implicit_time_derivatives_residual_size(self: pydrake.systems.framework.SystemBase) → int

Returns the size of the implicit time derivatives residual vector. By default this is the same as num_continuous_states() but a LeafSystem can change it during construction via LeafSystem::DeclareImplicitTimeDerivativesResidualSize().

input_port_ticket(self: pydrake.systems.framework.SystemBase, index: pydrake.systems.framework.InputPortIndex) → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on input port uᵢ indicated by index.

Precondition:

index selects an existing input port of this System.

static ke_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket for the cache entry that holds the kinetic energy calculation.

See also

System::EvalKineticEnergy()

static kinematics_ticket() → pydrake.systems.framework.DependencyTicket

static nothing_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating that a computation does not depend on any source value; that is, it is a constant. If this appears in a prerequisite list, it must be the only entry.

num_abstract_parameters(self: pydrake.systems.framework.SystemBase) → int

Returns the number of declared abstract parameters.

num_abstract_states(self: pydrake.systems.framework.SystemBase) → int

Returns the number of declared abstract state variables.

num_continuous_states(self: pydrake.systems.framework.SystemBase) → int

Returns the number of declared continuous state variables.

num_discrete_state_groups(self: pydrake.systems.framework.SystemBase) → int

Returns the number of declared discrete state groups (each group is a vector-valued discrete state variable).

num_input_ports(self: pydrake.systems.framework.SystemBase) → int

Returns the number of input ports currently allocated in this System. These are indexed from 0 to num_input_ports()-1.

num_numeric_parameter_groups(self: pydrake.systems.framework.SystemBase) → int

Returns the number of declared numeric parameters (each of these is a vector-valued parameter).

num_output_ports(self: pydrake.systems.framework.SystemBase) → int

Returns the number of output ports currently allocated in this System. These are indexed from 0 to num_output_ports()-1.

numeric_parameter_ticket(self: pydrake.systems.framework.SystemBase, index: pydrake.systems.framework.NumericParameterIndex) → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on a particular numeric parameter pnᵢ (may be a vector).

See also

pn_ticket() to obtain a ticket for all numeric parameters.

static pa_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on all of the abstract parameters pa in the current Context.

See also

abstract_parameter_ticket() to obtain a ticket for just one abstract parameter.

static pc_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket for the cache entry that holds the conservative power calculation.

See also

System::EvalConservativePower()

static pe_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket for the cache entry that holds the potential energy calculation.

See also

System::EvalPotentialEnergy()

static pn_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on all of the numerical parameters in the current Context.

See also

numeric_parameter_ticket() to obtain a ticket for just one numeric parameter.

static pnc_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket for the cache entry that holds the non-conservative power calculation.

See also

System::EvalNonConservativePower()

static q_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating that a computation depends on configuration state variables q. There is no ticket representing just one of the state variables qᵢ.

set_name(self: pydrake.systems.framework.SystemBase, name: str) → None

Sets the name of the system. Do not use the path delimiter character ‘:’ in the name. When creating a Diagram, names of sibling subsystems should be unique. DiagramBuilder uses this method to assign a unique default name if none is provided.

static time_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on time. This is the same ticket for all systems and refers to the same time value.

static v_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on velocity state variables v. This does not also indicate a dependence on configuration variables q – you must list that explicitly or use kinematics_ticket() instead. There is no ticket representing just one of the state variables vᵢ.

ValidateContext(self: pydrake.systems.framework.SystemBase, context: pydrake.systems.framework.ContextBase) → None

Checks whether the given context was created for this system.

Note

This method is sufficiently fast for performance sensitive code.

Raises

RuntimeError if the System Ids don't match. –

static xa_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on all of the abstract state variables in the current Context.

See also

abstract_state_ticket() to obtain a ticket for just one abstract state variable.

static xc_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on all of the continuous state variables q, v, or z.

static xcdot_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket for the cache entry that holds time derivatives of the continuous variables.

See also

EvalTimeDerivatives()

static xd_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on all of the numerical discrete state variables, in any discrete variable group.

See also

discrete_state_ticket() to obtain a ticket for just one discrete state variable.

static z_ticket() → pydrake.systems.framework.DependencyTicket

Returns a ticket indicating dependence on any or all of the miscellaneous continuous state variables z. There is no ticket representing just one of the state variables zᵢ.

class pydrake.systems.framework.SystemOutput

Conveniently stores a snapshot of the values of every output port of a System. There is framework support for allocating the right types and filling them in but otherwise this is not used internally. Note that there is never any live connection between a SystemOutput object and the System whose output values it has captured.

A SystemOutput<T> object can only be obtained using System<T>::AllocateOutput() or by copying an existing SystemOutput object.

Note

This class is templated; see SystemOutput_ for the list of instantiations.

__init__(*args, **kwargs)

get_data(self: pydrake.systems.framework.SystemOutput, arg0: int) → pydrake.common.value.AbstractValue

Returns the last-saved value of output port index as an AbstractValue. This works for any output port regardless of it actual type.

get_vector_data(self: pydrake.systems.framework.SystemOutput, arg0: int) → pydrake.systems.framework.BasicVector

Returns the last-saved value of output port index as a BasicVector<T>, although the actual concrete type is preserved from the actual output port.

Raises

RuntimeError if the port is not vector-valued. –

num_ports(self: pydrake.systems.framework.SystemOutput) → int

Returns the number of output ports specified for this SystemOutput during allocation.

template pydrake.systems.framework.SystemOutput_

Instantiations: SystemOutput_[float], SystemOutput_[AutoDiffXd], SystemOutput_[Expression]

class pydrake.systems.framework.SystemOutput_[AutoDiffXd]

Conveniently stores a snapshot of the values of every output port of a System. There is framework support for allocating the right types and filling them in but otherwise this is not used internally. Note that there is never any live connection between a SystemOutput object and the System whose output values it has captured.

A SystemOutput<T> object can only be obtained using System<T>::AllocateOutput() or by copying an existing SystemOutput object.

__init__(*args, **kwargs)

get_data(self: pydrake.systems.framework.SystemOutput_[AutoDiffXd], arg0: int) → pydrake.common.value.AbstractValue

Returns the last-saved value of output port index as an AbstractValue. This works for any output port regardless of it actual type.

get_vector_data(self: pydrake.systems.framework.SystemOutput_[AutoDiffXd], arg0: int) → pydrake.systems.framework.BasicVector_[AutoDiffXd]

Returns the last-saved value of output port index as a BasicVector<T>, although the actual concrete type is preserved from the actual output port.

Raises

RuntimeError if the port is not vector-valued. –

num_ports(self: pydrake.systems.framework.SystemOutput_[AutoDiffXd]) → int

Returns the number of output ports specified for this SystemOutput during allocation.

class pydrake.systems.framework.SystemOutput_[Expression]

Conveniently stores a snapshot of the values of every output port of a System. There is framework support for allocating the right types and filling them in but otherwise this is not used internally. Note that there is never any live connection between a SystemOutput object and the System whose output values it has captured.

A SystemOutput<T> object can only be obtained using System<T>::AllocateOutput() or by copying an existing SystemOutput object.

__init__(*args, **kwargs)

get_data(self: pydrake.systems.framework.SystemOutput_[Expression], arg0: int) → pydrake.common.value.AbstractValue

Returns the last-saved value of output port index as an AbstractValue. This works for any output port regardless of it actual type.

get_vector_data(self: pydrake.systems.framework.SystemOutput_[Expression], arg0: int) → pydrake.systems.framework.BasicVector_[Expression]

Returns the last-saved value of output port index as a BasicVector<T>, although the actual concrete type is preserved from the actual output port.

Raises

RuntimeError if the port is not vector-valued. –

num_ports(self: pydrake.systems.framework.SystemOutput_[Expression]) → int

Returns the number of output ports specified for this SystemOutput during allocation.

class pydrake.systems.framework.SystemScalarConverter

__init__(self: pydrake.systems.framework.SystemScalarConverter) → None

template IsConvertible

Instantiations: IsConvertible[AutoDiffXd,float], IsConvertible[Expression,float], IsConvertible[float,AutoDiffXd], IsConvertible[Expression,AutoDiffXd], IsConvertible[float,Expression], IsConvertible[AutoDiffXd,Expression]

IsConvertible[AutoDiffXd,Expression](self: pydrake.systems.framework.SystemScalarConverter) → bool

Returns true iff this object can convert a System<U> into a System<T>, i.e., whether Convert() will return non-null.

IsConvertible[AutoDiffXd,float](self: pydrake.systems.framework.SystemScalarConverter) → bool

Returns true iff this object can convert a System<U> into a System<T>, i.e., whether Convert() will return non-null.

IsConvertible[Expression,AutoDiffXd](self: pydrake.systems.framework.SystemScalarConverter) → bool

Returns true iff this object can convert a System<U> into a System<T>, i.e., whether Convert() will return non-null.

IsConvertible[Expression,float](self: pydrake.systems.framework.SystemScalarConverter) → bool

Returns true iff this object can convert a System<U> into a System<T>, i.e., whether Convert() will return non-null.

IsConvertible[float,AutoDiffXd](self: pydrake.systems.framework.SystemScalarConverter) → bool

Returns true iff this object can convert a System<U> into a System<T>, i.e., whether Convert() will return non-null.

IsConvertible[float,Expression](self: pydrake.systems.framework.SystemScalarConverter) → bool

Returns true iff this object can convert a System<U> into a System<T>, i.e., whether Convert() will return non-null.

SupportedConversionPairs = ((<class 'pydrake.autodiffutils.AutoDiffXd'>, <class 'float'>), (<class 'pydrake.symbolic.Expression'>, <class 'float'>), (<class 'float'>, <class 'pydrake.autodiffutils.AutoDiffXd'>), (<class 'pydrake.symbolic.Expression'>, <class 'pydrake.autodiffutils.AutoDiffXd'>), (<class 'float'>, <class 'pydrake.symbolic.Expression'>), (<class 'pydrake.autodiffutils.AutoDiffXd'>, <class 'pydrake.symbolic.Expression'>))

SupportedScalars = (<class 'float'>, <class 'pydrake.autodiffutils.AutoDiffXd'>, <class 'pydrake.symbolic.Expression'>)

class pydrake.systems.framework.SystemVisitor

Provides a “Visitor Pattern” for System and Diagram. Rather than adding more virtual methods to the System base class, or performing a dynamic_cast to test if a System is a Diagram, you may use the visitor pattern enabled by this class, e.g.:

Click to expand C++ code...

template <typename T>
class MySystemVisitor : public SystemVisitor {
...
}

MySystemVisitor<T> visitor;
system.Accept(visitor);

will call the correct Visit overload.

Note

This method does not recurse through the subsystems of a Diagram, but that is easy to do: just call Diagram::GetSystems() in your visitor and then call Accept on the subsystems.

Note

This class is templated; see SystemVisitor_ for the list of instantiations.

__init__(self: pydrake.systems.framework.SystemVisitor) → None

VisitDiagram(self: pydrake.systems.framework.SystemVisitor, diagram: pydrake.systems.framework.Diagram) → None

This method will be called by System<T>::accept() if the System is a Diagram<T>.

VisitSystem(self: pydrake.systems.framework.SystemVisitor, system: pydrake.systems.framework.System) → None

This method will be called by System<T>::accept() if the System is not a Diagram<T>.

template pydrake.systems.framework.SystemVisitor_

Instantiations: SystemVisitor_[float], SystemVisitor_[AutoDiffXd], SystemVisitor_[Expression]

class pydrake.systems.framework.SystemVisitor_[AutoDiffXd]

Provides a “Visitor Pattern” for System and Diagram. Rather than adding more virtual methods to the System base class, or performing a dynamic_cast to test if a System is a Diagram, you may use the visitor pattern enabled by this class, e.g.:

Click to expand C++ code...

template <typename T>
class MySystemVisitor : public SystemVisitor {
...
}

MySystemVisitor<T> visitor;
system.Accept(visitor);

will call the correct Visit overload.

Note

This method does not recurse through the subsystems of a Diagram, but that is easy to do: just call Diagram::GetSystems() in your visitor and then call Accept on the subsystems.

__init__(self: pydrake.systems.framework.SystemVisitor_[AutoDiffXd]) → None

VisitDiagram(self: pydrake.systems.framework.SystemVisitor_[AutoDiffXd], diagram: pydrake.systems.framework.Diagram_[AutoDiffXd]) → None

This method will be called by System<T>::accept() if the System is a Diagram<T>.

VisitSystem(self: pydrake.systems.framework.SystemVisitor_[AutoDiffXd], system: pydrake.systems.framework.System_[AutoDiffXd]) → None

This method will be called by System<T>::accept() if the System is not a Diagram<T>.

class pydrake.systems.framework.SystemVisitor_[Expression]

Provides a “Visitor Pattern” for System and Diagram. Rather than adding more virtual methods to the System base class, or performing a dynamic_cast to test if a System is a Diagram, you may use the visitor pattern enabled by this class, e.g.:

Click to expand C++ code...

template <typename T>
class MySystemVisitor : public SystemVisitor {
...
}

MySystemVisitor<T> visitor;
system.Accept(visitor);

will call the correct Visit overload.

Note

This method does not recurse through the subsystems of a Diagram, but that is easy to do: just call Diagram::GetSystems() in your visitor and then call Accept on the subsystems.

__init__(self: pydrake.systems.framework.SystemVisitor_[Expression]) → None

VisitDiagram(self: pydrake.systems.framework.SystemVisitor_[Expression], diagram: pydrake.systems.framework.Diagram_[Expression]) → None

This method will be called by System<T>::accept() if the System is a Diagram<T>.

VisitSystem(self: pydrake.systems.framework.SystemVisitor_[Expression], system: pydrake.systems.framework.System_[Expression]) → None

This method will be called by System<T>::accept() if the System is not a Diagram<T>.

class pydrake.systems.framework.TriggerType

Predefined types of triggers for events. Used at run time to determine why the associated event has occurred.

Members:

kUnknown :

kInitialization : This trigger indicates that an associated event is triggered at system

initialization.

kForced : This trigger indicates that an associated event is triggered by

directly calling the corresponding public system API for event handling (e.g. Publish(context)).

kTimed : This trigger indicates that an associated event is triggered by the

system proceeding to a single, arbitrary time. Timed events are commonly created in System::CalcNextUpdateTime().

kPeriodic : This type indicates that an associated event is triggered by the

system proceeding to a time t ∈ {tᵢ = t₀ + p * i} for some period p, time offset t₀, and i is a non-negative integer.

See also

PeriodicEventData. Periodic events are commonly created in System::CalcNextUpdateTime().

kPerStep : This trigger indicates that an associated event is triggered whenever

a solver takes a step. A solver is an abstract construct that controls or tracks the time and state evolution of a System. A simulator is a solver- it advances time a finite duration by integrating a system, modifying its state accordingly- as is a process that receives some numeric state from IPC that is then used to, e.g., update abstract state. Steps may occur at irregular time intervals: a step typically coincides with a point in time where it is advantageous to poll for events, like immediately after an integrator has advanced time and state.

Per-step events are most commonly created in System::GetPerStepEvents(). A very common use of such per-step events is to update a discrete or abstract state variable that changes whenever the continuous state advances; examples are computing the “min” or “max” of some state variable, recording a signal in a delay buffer, or publishing. Per-step events are also useful to implement feedback controllers interfaced with physical devices; the controller can be implemented in the event handler, and the “step” would correspond to receiving sensory data from the hardware.

kWitness : This trigger indicates that an associated event is triggered by the

zero crossing of a witness function.

See also

WitnessTriggeredEventData.

__init__(self: pydrake.systems.framework.TriggerType, value: int) → None

kForced = <TriggerType.kForced: 2>

kInitialization = <TriggerType.kInitialization: 1>

kPeriodic = <TriggerType.kPeriodic: 4>

kPerStep = <TriggerType.kPerStep: 5>

kTimed = <TriggerType.kTimed: 3>

kUnknown = <TriggerType.kUnknown: 0>

kWitness = <TriggerType.kWitness: 6>

property name

property value

class pydrake.systems.framework.UnrestrictedUpdateEvent

Bases: pydrake.systems.framework.Event

This class represents an unrestricted update event. It has an optional callback function to do custom handling of this event, and that can write updates to a mutable, non-null State object.

See also

LeafSystem for more convenient interfaces to unrestricted update events via the Declare*UnrestrictedUpdateEvent() methods.

Note

This class is templated; see UnrestrictedUpdateEvent_ for the list of instantiations.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.UnrestrictedUpdateEvent, callback: Callable[[pydrake.systems.framework.Context, pydrake.systems.framework.UnrestrictedUpdateEvent, pydrake.systems.framework.State], Optional[pydrake.systems.framework.EventStatus]]) -> None

Constructs an UnrestrictedUpdateEvent with the given callback function.

2. __init__(self: pydrake.systems.framework.UnrestrictedUpdateEvent, system_callback: Callable[[drake::systems::System<double>, pydrake.systems.framework.Context, pydrake.systems.framework.UnrestrictedUpdateEvent, pydrake.systems.framework.State], Optional[pydrake.systems.framework.EventStatus]]) -> None

Constructs an UnrestrictedUpdateEvent with the given callback function.

template pydrake.systems.framework.UnrestrictedUpdateEvent_

Instantiations: UnrestrictedUpdateEvent_[float], UnrestrictedUpdateEvent_[AutoDiffXd], UnrestrictedUpdateEvent_[Expression]

class pydrake.systems.framework.UnrestrictedUpdateEvent_[AutoDiffXd]

Bases: pydrake.systems.framework.Event_[AutoDiffXd]

This class represents an unrestricted update event. It has an optional callback function to do custom handling of this event, and that can write updates to a mutable, non-null State object.

See also

LeafSystem for more convenient interfaces to unrestricted update events via the Declare*UnrestrictedUpdateEvent() methods.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.UnrestrictedUpdateEvent_[AutoDiffXd], callback: Callable[[pydrake.systems.framework.Context_[AutoDiffXd], pydrake.systems.framework.UnrestrictedUpdateEvent_[AutoDiffXd], pydrake.systems.framework.State_[AutoDiffXd]], Optional[pydrake.systems.framework.EventStatus]]) -> None

Constructs an UnrestrictedUpdateEvent with the given callback function.

2. __init__(self: pydrake.systems.framework.UnrestrictedUpdateEvent_[AutoDiffXd], system_callback: Callable[[drake::systems::System<Eigen::AutoDiffScalar<Eigen::Matrix<double, -1, 1, 0, -1, 1> > >, pydrake.systems.framework.Context_[AutoDiffXd], pydrake.systems.framework.UnrestrictedUpdateEvent_[AutoDiffXd], pydrake.systems.framework.State_[AutoDiffXd]], Optional[pydrake.systems.framework.EventStatus]]) -> None

Constructs an UnrestrictedUpdateEvent with the given callback function.

class pydrake.systems.framework.UnrestrictedUpdateEvent_[Expression]

Bases: pydrake.systems.framework.Event_[Expression]

This class represents an unrestricted update event. It has an optional callback function to do custom handling of this event, and that can write updates to a mutable, non-null State object.

See also

LeafSystem for more convenient interfaces to unrestricted update events via the Declare*UnrestrictedUpdateEvent() methods.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: pydrake.systems.framework.UnrestrictedUpdateEvent_[Expression], callback: Callable[[pydrake.systems.framework.Context_[Expression], pydrake.systems.framework.UnrestrictedUpdateEvent_[Expression], pydrake.systems.framework.State_[Expression]], Optional[pydrake.systems.framework.EventStatus]]) -> None

Constructs an UnrestrictedUpdateEvent with the given callback function.

2. __init__(self: pydrake.systems.framework.UnrestrictedUpdateEvent_[Expression], system_callback: Callable[[drake::systems::System<drake::symbolic::Expression>, pydrake.systems.framework.Context_[Expression], pydrake.systems.framework.UnrestrictedUpdateEvent_[Expression], pydrake.systems.framework.State_[Expression]], Optional[pydrake.systems.framework.EventStatus]]) -> None

Constructs an UnrestrictedUpdateEvent with the given callback function.

class pydrake.systems.framework.UseDefaultName

(Advanced.) Tag type that indicates a system or port should use a default name, instead of a user-provided name. Most users will use the kUseDefaultName constant, without ever having to mention this type.

__init__(*args, **kwargs)

class pydrake.systems.framework.ValueProducer

ValueProducer computes an AbstractValue output based on a ContextBase input. This is commonly used for declaring output ports and cache entries.

It provides two functions for that purpose: - Allocate() returns new storage that is suitably typed to hold the output. - Calc() takes a context as input and writes to an output pointer.

For example, given this example calculator lambda:

Click to expand C++ code...

std::function calc = [](const Context<T>& context, std::string* output) {
output = std::to_string(context.get_time());
};

We can capture it into a producer and then call it:

Click to expand C++ code...

ValueProducer producer(calc);
std::unique_ptr<AbstractValue> storage = producer.Allocate();
const LeafContext<T> context;
producer.Calc(context, storage.get());
EXPECT_THAT(storage->get_value<std::string>(), ::testing::StartsWith("0.0"));

Sugar is provided to create ValueProducer objects from function pointers that operate on un-erased types, so that the user can ignore the details of type erasure and Context<T> downcasting. Refer to the ValueProducer_constructors “Constructor overloads” for details.

__init__(self: pydrake.systems.framework.ValueProducer, allocate: Callable[[], pydrake.common.value.AbstractValue], calc: Callable[[pydrake.systems.framework.ContextBase, pydrake.common.value.AbstractValue], None]) → None

Overload (5d). Refer to the ValueProducer_constructors “Constructor overloads” for details.

static NoopCalc(arg0: pydrake.systems.framework.ContextBase, arg1: pydrake.common.value.AbstractValue) → None

This static function is provided for users who need an empty CalcCallback. Passing &ValueProducer::NoopCalc as ValueProducer’s last constructor argument will create a function that does not compute anything, but can still allocate.

class pydrake.systems.framework.VectorBase

VectorBase is an abstract base class that real-valued signals between Systems and real-valued System state vectors must implement. Classes that inherit from VectorBase will typically provide names for the elements of the vector, and may also provide other computations for the convenience of Systems handling the signal. The vector is always a column vector. It may or may not be contiguous in memory. Contiguous subclasses should typically inherit from BasicVector, not from VectorBase directly.

Note

This class is templated; see VectorBase_ for the list of instantiations.

__init__(*args, **kwargs)

CopyToVector(self: pydrake.systems.framework.VectorBase) → numpy.ndarray[numpy.float64[m, 1]]

Copies this entire VectorBase into a contiguous Eigen Vector.

Implementations should ensure this operation is O(N) in the size of the value and allocates only the O(N) memory that it returns.

GetAtIndex(self: pydrake.systems.framework.VectorBase, index: int) → float

Returns the element at the given index in the vector.

Raises

• RuntimeError if the index is >= size() or negative. Consider –

• operator[]() instead if bounds-checking is unwanted. –

PlusEqScaled(self: pydrake.systems.framework.VectorBase, scale: float, rhs: pydrake.systems.framework.VectorBase) → pydrake.systems.framework.VectorBase

Add in scaled vector rhs to this vector.

Raises

RuntimeError if rhs is a different size than this. –

SetAtIndex(self: pydrake.systems.framework.VectorBase, index: int, value: float) → None

Replaces the state at the given index with the value.

Raises

• RuntimeError if the index is >= size() Consider operator[]() –

• instead if bounds-checking is unwanted. –

SetFrom(self: pydrake.systems.framework.VectorBase, value: pydrake.systems.framework.VectorBase) → None

Replaces the entire vector with the contents of value.

Raises

RuntimeError if value is not a column vector with size() rows. –

Implementations should ensure this operation is O(N) in the size of the value and allocates no memory.

SetFromVector(self: pydrake.systems.framework.VectorBase, value: numpy.ndarray[numpy.float64[m, 1]]) → None

Replaces the entire vector with the contents of value.

Raises

RuntimeError if value is not a column vector with size() rows. –

Implementations should ensure this operation is O(N) in the size of the value and allocates no memory.

SetZero(self: pydrake.systems.framework.VectorBase) → None

Sets all elements of this vector to zero.

size(self: pydrake.systems.framework.VectorBase) → int

Returns the number of elements in the vector.

Implementations should ensure this operation is O(1) and allocates no memory.

template pydrake.systems.framework.VectorBase_

Instantiations: VectorBase_[float], VectorBase_[AutoDiffXd], VectorBase_[Expression]

class pydrake.systems.framework.VectorBase_[AutoDiffXd]

VectorBase is an abstract base class that real-valued signals between Systems and real-valued System state vectors must implement. Classes that inherit from VectorBase will typically provide names for the elements of the vector, and may also provide other computations for the convenience of Systems handling the signal. The vector is always a column vector. It may or may not be contiguous in memory. Contiguous subclasses should typically inherit from BasicVector, not from VectorBase directly.

__init__(*args, **kwargs)

CopyToVector(self: pydrake.systems.framework.VectorBase_[AutoDiffXd]) → numpy.ndarray[object[m, 1]]

Copies this entire VectorBase into a contiguous Eigen Vector.

Implementations should ensure this operation is O(N) in the size of the value and allocates only the O(N) memory that it returns.

GetAtIndex(self: pydrake.systems.framework.VectorBase_[AutoDiffXd], index: int) → pydrake.autodiffutils.AutoDiffXd

Returns the element at the given index in the vector.

Raises

• RuntimeError if the index is >= size() or negative. Consider –

• operator[]() instead if bounds-checking is unwanted. –

PlusEqScaled(self: pydrake.systems.framework.VectorBase_[AutoDiffXd], scale: pydrake.autodiffutils.AutoDiffXd, rhs: pydrake.systems.framework.VectorBase_[AutoDiffXd]) → pydrake.systems.framework.VectorBase_[AutoDiffXd]

Add in scaled vector rhs to this vector.

Raises

RuntimeError if rhs is a different size than this. –

SetAtIndex(self: pydrake.systems.framework.VectorBase_[AutoDiffXd], index: int, value: pydrake.autodiffutils.AutoDiffXd) → None

Replaces the state at the given index with the value.

Raises

• RuntimeError if the index is >= size() Consider operator[]() –

• instead if bounds-checking is unwanted. –

SetFrom(self: pydrake.systems.framework.VectorBase_[AutoDiffXd], value: pydrake.systems.framework.VectorBase_[AutoDiffXd]) → None

Replaces the entire vector with the contents of value.

Raises

RuntimeError if value is not a column vector with size() rows. –

Implementations should ensure this operation is O(N) in the size of the value and allocates no memory.

SetFromVector(self: pydrake.systems.framework.VectorBase_[AutoDiffXd], value: numpy.ndarray[object[m, 1]]) → None

Replaces the entire vector with the contents of value.

Raises

RuntimeError if value is not a column vector with size() rows. –

Implementations should ensure this operation is O(N) in the size of the value and allocates no memory.

SetZero(self: pydrake.systems.framework.VectorBase_[AutoDiffXd]) → None

Sets all elements of this vector to zero.

size(self: pydrake.systems.framework.VectorBase_[AutoDiffXd]) → int

Returns the number of elements in the vector.

Implementations should ensure this operation is O(1) and allocates no memory.

class pydrake.systems.framework.VectorBase_[Expression]

VectorBase is an abstract base class that real-valued signals between Systems and real-valued System state vectors must implement. Classes that inherit from VectorBase will typically provide names for the elements of the vector, and may also provide other computations for the convenience of Systems handling the signal. The vector is always a column vector. It may or may not be contiguous in memory. Contiguous subclasses should typically inherit from BasicVector, not from VectorBase directly.

__init__(*args, **kwargs)

CopyToVector(self: pydrake.systems.framework.VectorBase_[Expression]) → numpy.ndarray[object[m, 1]]

Copies this entire VectorBase into a contiguous Eigen Vector.

Implementations should ensure this operation is O(N) in the size of the value and allocates only the O(N) memory that it returns.

GetAtIndex(self: pydrake.systems.framework.VectorBase_[Expression], index: int) → pydrake.symbolic.Expression

Returns the element at the given index in the vector.

Raises

• RuntimeError if the index is >= size() or negative. Consider –

• operator[]() instead if bounds-checking is unwanted. –

PlusEqScaled(self: pydrake.systems.framework.VectorBase_[Expression], scale: pydrake.symbolic.Expression, rhs: pydrake.systems.framework.VectorBase_[Expression]) → pydrake.systems.framework.VectorBase_[Expression]

Add in scaled vector rhs to this vector.

Raises

RuntimeError if rhs is a different size than this. –

SetAtIndex(self: pydrake.systems.framework.VectorBase_[Expression], index: int, value: pydrake.symbolic.Expression) → None

Replaces the state at the given index with the value.

Raises

• RuntimeError if the index is >= size() Consider operator[]() –

• instead if bounds-checking is unwanted. –

SetFrom(self: pydrake.systems.framework.VectorBase_[Expression], value: pydrake.systems.framework.VectorBase_[Expression]) → None

Replaces the entire vector with the contents of value.

Raises

RuntimeError if value is not a column vector with size() rows. –

Implementations should ensure this operation is O(N) in the size of the value and allocates no memory.

SetFromVector(self: pydrake.systems.framework.VectorBase_[Expression], value: numpy.ndarray[object[m, 1]]) → None

Replaces the entire vector with the contents of value.

Raises

RuntimeError if value is not a column vector with size() rows. –

Implementations should ensure this operation is O(N) in the size of the value and allocates no memory.

SetZero(self: pydrake.systems.framework.VectorBase_[Expression]) → None

Sets all elements of this vector to zero.

size(self: pydrake.systems.framework.VectorBase_[Expression]) → int

Returns the number of elements in the vector.

Implementations should ensure this operation is O(1) and allocates no memory.

class pydrake.systems.framework.VectorSystem

Bases: pydrake.systems.framework.LeafSystem

A base class that specializes LeafSystem for use with only zero or one vector input ports, and only zero or one vector output ports.

u0→

VectorSystem

→ y0

By default, this base class does not declare any state; subclasses may optionally declare continuous or discrete state, but not both; subclasses may not declare abstract state.

Note

This class is templated; see VectorSystem_ for the list of instantiations.

__init__(self: pydrake.systems.framework.VectorSystem, input_size: int, output_size: int, direct_feedthrough: Optional[bool]) → None

Creates a system with one input port and one output port of the given sizes, when the sizes are non-zero. Either size can be zero, in which case no input (or output) port is created.

The direct_feedthrough specifies whether the input port direct feeds through to the output port. (See SystemBase::GetDirectFeedthroughs().) When nullopt, assumes true (the output is direct feedthrough). When false, the DoCalcVectorOutput input will be empty (zero-sized).

Does not declare scalar-type conversion support (AutoDiff, etc.). To enable AutoDiff support, use the SystemScalarConverter-based constructor. (For that, see system_scalar_conversion at the example titled “Example using drake::systems::VectorSystem as the base class”.)

template pydrake.systems.framework.VectorSystem_

Instantiations: VectorSystem_[float], VectorSystem_[AutoDiffXd], VectorSystem_[Expression]

class pydrake.systems.framework.VectorSystem_[AutoDiffXd]

Bases: pydrake.systems.framework.LeafSystem_[AutoDiffXd]

A base class that specializes LeafSystem for use with only zero or one vector input ports, and only zero or one vector output ports.

u0→

VectorSystem

→ y0

By default, this base class does not declare any state; subclasses may optionally declare continuous or discrete state, but not both; subclasses may not declare abstract state.

__init__(self: pydrake.systems.framework.VectorSystem_[AutoDiffXd], input_size: int, output_size: int, direct_feedthrough: Optional[bool]) → None

Creates a system with one input port and one output port of the given sizes, when the sizes are non-zero. Either size can be zero, in which case no input (or output) port is created.

The direct_feedthrough specifies whether the input port direct feeds through to the output port. (See SystemBase::GetDirectFeedthroughs().) When nullopt, assumes true (the output is direct feedthrough). When false, the DoCalcVectorOutput input will be empty (zero-sized).

Does not declare scalar-type conversion support (AutoDiff, etc.). To enable AutoDiff support, use the SystemScalarConverter-based constructor. (For that, see system_scalar_conversion at the example titled “Example using drake::systems::VectorSystem as the base class”.)

class pydrake.systems.framework.VectorSystem_[Expression]

Bases: pydrake.systems.framework.LeafSystem_[Expression]

A base class that specializes LeafSystem for use with only zero or one vector input ports, and only zero or one vector output ports.

u0→

VectorSystem

→ y0

By default, this base class does not declare any state; subclasses may optionally declare continuous or discrete state, but not both; subclasses may not declare abstract state.

__init__(self: pydrake.systems.framework.VectorSystem_[Expression], input_size: int, output_size: int, direct_feedthrough: Optional[bool]) → None

Creates a system with one input port and one output port of the given sizes, when the sizes are non-zero. Either size can be zero, in which case no input (or output) port is created.

The direct_feedthrough specifies whether the input port direct feeds through to the output port. (See SystemBase::GetDirectFeedthroughs().) When nullopt, assumes true (the output is direct feedthrough). When false, the DoCalcVectorOutput input will be empty (zero-sized).

Does not declare scalar-type conversion support (AutoDiff, etc.). To enable AutoDiff support, use the SystemScalarConverter-based constructor. (For that, see system_scalar_conversion at the example titled “Example using drake::systems::VectorSystem as the base class”.)

class pydrake.systems.framework.WitnessFunction

Class that stores a function that is able to help determine the time and state at which a step of the initial value problem integration of a System should end, which may be done for any number of purposes, including publishing or state reinitialization (i.e., event handling). System authors declare witness functions through LeafSystem::MakeWitnessFunction().

For the ensuing discussion, consider two times (t₀ and t₁ > t₀) and states corresponding to those times (x(t₀) and x(t₁)). A witness function, w(t, x), “triggers” only when it crosses zero at a time t* where t₀ < t* ≤ t₁. Note the half-open interval. For an example of a witness function, consider the “signed distance” (i.e., Euclidean distance when bodies are disjoint and minimum translational distance when bodies intersect) between two rigid bodies; this witness function can be used to determine both the time of impact for rigid bodies and their states at that time of impact.

Precision in the definition of the witness function is necessary, because we want the witness function to trigger only once if, for example, w(t₀, x(t₀)) ≠ 0, w(t₁, x(t₁)) = 0, and w(t₂, x(t₂)) ≠ 0, for some t₂ > t₁. In other words, if the witness function is evaluated over the intervals [t₀, t₁] and [t₁, t₂], meaning that the zero occurs precisely at an interval endpoint, the witness function should trigger once. Similarly, the witness function should trigger exactly once if w(t₀, x(t₀)) ≠ 0, w(t*, x(t*)) = 0, and w(t₁, x(t₁)) = 0, for t* ∈ (t₀, t₁). We can define the trigger condition formally over interval [t₀, t₁] using the function:

Click to expand C++ code...

T(w, t₀, x(t₀), t₁) =   1   if w(t₀, x(t₀)) ≠ 0 and
                               w(t₀, x(t₀))⋅w(t₁, x(t₁)) ≤ 0
                        0   if w(t₀, x(t₀)) = 0 or
                               w(t₀, x(t₀))⋅w(t₁, x(t₁)) > 0

We wish for the witness function to trigger if the trigger function evaluates to one. The trigger function can be further modified, if desired, to incorporate the constraint that the witness function should trigger only when crossing from positive values to negative values, or vice versa.

A good witness function should not cross zero repeatedly over a small interval of time (relative to the maximum designated integration step size) or over small changes in state; when a witness function has been “bracketed” over an interval of time (i.e., it changes sign), that witness function will ideally cross zero only once in that interval.

A witness function trigger time is isolated only to a small interval of time (as described in Simulator). The disadvantage of this scheme is that it always requires the length of the interval to be reduced to the requisite length and that each function evaluation (which requires numerical integration) is extraordinarily expensive. If, for example, the (slow) bisection algorithm were used to isolate the time interval, the number of integrations necessary to cut the interval from a length of ℓ to a length of ε will be log₂(ℓ / ε). Bisection is just one of several possible algorithms for isolating the time interval, though it’s a reliable choice and always converges linearly.

Note

This class is templated; see WitnessFunction_ for the list of instantiations.

__init__(*args, **kwargs)

template pydrake.systems.framework.WitnessFunction_

Instantiations: WitnessFunction_[float], WitnessFunction_[AutoDiffXd], WitnessFunction_[Expression]

class pydrake.systems.framework.WitnessFunction_[AutoDiffXd]

Class that stores a function that is able to help determine the time and state at which a step of the initial value problem integration of a System should end, which may be done for any number of purposes, including publishing or state reinitialization (i.e., event handling). System authors declare witness functions through LeafSystem::MakeWitnessFunction().

For the ensuing discussion, consider two times (t₀ and t₁ > t₀) and states corresponding to those times (x(t₀) and x(t₁)). A witness function, w(t, x), “triggers” only when it crosses zero at a time t* where t₀ < t* ≤ t₁. Note the half-open interval. For an example of a witness function, consider the “signed distance” (i.e., Euclidean distance when bodies are disjoint and minimum translational distance when bodies intersect) between two rigid bodies; this witness function can be used to determine both the time of impact for rigid bodies and their states at that time of impact.

Precision in the definition of the witness function is necessary, because we want the witness function to trigger only once if, for example, w(t₀, x(t₀)) ≠ 0, w(t₁, x(t₁)) = 0, and w(t₂, x(t₂)) ≠ 0, for some t₂ > t₁. In other words, if the witness function is evaluated over the intervals [t₀, t₁] and [t₁, t₂], meaning that the zero occurs precisely at an interval endpoint, the witness function should trigger once. Similarly, the witness function should trigger exactly once if w(t₀, x(t₀)) ≠ 0, w(t*, x(t*)) = 0, and w(t₁, x(t₁)) = 0, for t* ∈ (t₀, t₁). We can define the trigger condition formally over interval [t₀, t₁] using the function:

Click to expand C++ code...

T(w, t₀, x(t₀), t₁) =   1   if w(t₀, x(t₀)) ≠ 0 and
                               w(t₀, x(t₀))⋅w(t₁, x(t₁)) ≤ 0
                        0   if w(t₀, x(t₀)) = 0 or
                               w(t₀, x(t₀))⋅w(t₁, x(t₁)) > 0

We wish for the witness function to trigger if the trigger function evaluates to one. The trigger function can be further modified, if desired, to incorporate the constraint that the witness function should trigger only when crossing from positive values to negative values, or vice versa.

A good witness function should not cross zero repeatedly over a small interval of time (relative to the maximum designated integration step size) or over small changes in state; when a witness function has been “bracketed” over an interval of time (i.e., it changes sign), that witness function will ideally cross zero only once in that interval.

A witness function trigger time is isolated only to a small interval of time (as described in Simulator). The disadvantage of this scheme is that it always requires the length of the interval to be reduced to the requisite length and that each function evaluation (which requires numerical integration) is extraordinarily expensive. If, for example, the (slow) bisection algorithm were used to isolate the time interval, the number of integrations necessary to cut the interval from a length of ℓ to a length of ε will be log₂(ℓ / ε). Bisection is just one of several possible algorithms for isolating the time interval, though it’s a reliable choice and always converges linearly.

__init__(*args, **kwargs)

class pydrake.systems.framework.WitnessFunction_[Expression]

Class that stores a function that is able to help determine the time and state at which a step of the initial value problem integration of a System should end, which may be done for any number of purposes, including publishing or state reinitialization (i.e., event handling). System authors declare witness functions through LeafSystem::MakeWitnessFunction().

For the ensuing discussion, consider two times (t₀ and t₁ > t₀) and states corresponding to those times (x(t₀) and x(t₁)). A witness function, w(t, x), “triggers” only when it crosses zero at a time t* where t₀ < t* ≤ t₁. Note the half-open interval. For an example of a witness function, consider the “signed distance” (i.e., Euclidean distance when bodies are disjoint and minimum translational distance when bodies intersect) between two rigid bodies; this witness function can be used to determine both the time of impact for rigid bodies and their states at that time of impact.

Precision in the definition of the witness function is necessary, because we want the witness function to trigger only once if, for example, w(t₀, x(t₀)) ≠ 0, w(t₁, x(t₁)) = 0, and w(t₂, x(t₂)) ≠ 0, for some t₂ > t₁. In other words, if the witness function is evaluated over the intervals [t₀, t₁] and [t₁, t₂], meaning that the zero occurs precisely at an interval endpoint, the witness function should trigger once. Similarly, the witness function should trigger exactly once if w(t₀, x(t₀)) ≠ 0, w(t*, x(t*)) = 0, and w(t₁, x(t₁)) = 0, for t* ∈ (t₀, t₁). We can define the trigger condition formally over interval [t₀, t₁] using the function:

Click to expand C++ code...

T(w, t₀, x(t₀), t₁) =   1   if w(t₀, x(t₀)) ≠ 0 and
                               w(t₀, x(t₀))⋅w(t₁, x(t₁)) ≤ 0
                        0   if w(t₀, x(t₀)) = 0 or
                               w(t₀, x(t₀))⋅w(t₁, x(t₁)) > 0

We wish for the witness function to trigger if the trigger function evaluates to one. The trigger function can be further modified, if desired, to incorporate the constraint that the witness function should trigger only when crossing from positive values to negative values, or vice versa.

A good witness function should not cross zero repeatedly over a small interval of time (relative to the maximum designated integration step size) or over small changes in state; when a witness function has been “bracketed” over an interval of time (i.e., it changes sign), that witness function will ideally cross zero only once in that interval.

A witness function trigger time is isolated only to a small interval of time (as described in Simulator). The disadvantage of this scheme is that it always requires the length of the interval to be reduced to the requisite length and that each function evaluation (which requires numerical integration) is extraordinarily expensive. If, for example, the (slow) bisection algorithm were used to isolate the time interval, the number of integrations necessary to cut the interval from a length of ℓ to a length of ε will be log₂(ℓ / ε). Bisection is just one of several possible algorithms for isolating the time interval, though it’s a reliable choice and always converges linearly.

__init__(*args, **kwargs)

class pydrake.systems.framework.WitnessFunctionDirection

Members:

kNone : This witness function will never be triggered.

kPositiveThenNonPositive : Witness function triggers when the function crosses or touches zero

after an initial positive evaluation.

kNegativeThenNonNegative : Witness function triggers when the function crosses or touches zero

after an initial negative evaluation.

kCrossesZero : Witness function triggers any time the function crosses/touches

zero, except when the witness function evaluates to zero at the beginning of the interval. Conceptually equivalent to kPositiveThenNonNegative OR kNegativeThenNonNegative.

__init__(self: pydrake.systems.framework.WitnessFunctionDirection, value: int) → None

kCrossesZero = <WitnessFunctionDirection.kCrossesZero: 3>

kNegativeThenNonNegative = <WitnessFunctionDirection.kNegativeThenNonNegative: 2>

kNone = <WitnessFunctionDirection.kNone: 0>

kPositiveThenNonPositive = <WitnessFunctionDirection.kPositiveThenNonPositive: 1>

property name

property value