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.
|
| ~SystemBase () override |
|
void | set_name (const std::string &name) |
| Sets the name of the system. More...
|
|
const std::string & | get_name () const |
| Returns the name last supplied to set_name(), if any. More...
|
|
const std::string & | GetSystemName () const final |
| Returns a human-readable name for this system, for use in messages and logging. More...
|
|
std::string | GetSystemPathname () const final |
| Generates and returns a human-readable full path name of this subsystem, for use in messages and logging. More...
|
|
std::string | GetSystemType () const final |
| Returns the most-derived type of this concrete System object as a human-readable string suitable for use in error messages. More...
|
|
std::unique_ptr< ContextBase > | AllocateContext () const |
| Returns a Context suitable for use with this System. More...
|
|
template<class MySystem , class MyContext , typename ValueType > |
CacheEntry & | DeclareCacheEntry (std::string description, ValueType(MySystem::*make)() const, void(MySystem::*calc)(const MyContext &, ValueType *) const, std::set< DependencyTicket > prerequisites_of_calc) |
|
template<class MySystem , class MyContext , typename ValueType > |
CacheEntry & | DeclareCacheEntry (std::string description, const ValueType &model_value, ValueType(MySystem::*calc)(const MyContext &) const, std::set< DependencyTicket > prerequisites_of_calc) |
|
template<class MySystem , class MyContext , typename ValueType > |
CacheEntry & | DeclareCacheEntry (std::string description, ValueType(MySystem::*calc)(const MyContext &) const, std::set< DependencyTicket > prerequisites_of_calc) |
|
|
These methods provide scalar type-independent evaluation of a System input port in a particular Context.
If necessary, they first cause the port's value to become up to date, then they return a reference to the now-up-to-date value in the given Context.
Specified preconditions for these methods operate as follows: The preconditions will be checked in Debug builds but some or all might not be checked in Release builds for performance reasons. If we do check, and a precondition is violated, an std::logic_error will be thrown with a helpful message.
- See also
- System::EvalVectorInput(), System::EvalEigenVectorInput() for scalar type-specific input port access.
|
const AbstractValue * | EvalAbstractInput (const ContextBase &context, int port_index) const |
| Returns the value of the input port with the given port_index as an AbstractValue, which is permitted for ports of any type. More...
|
|
template<typename V > |
const V * | EvalInputValue (const ContextBase &context, int port_index) const |
| Returns the value of an abstract-valued input port with the given port_index as a value of known type V . More...
|
|
int | num_input_ports () const |
| Returns the number of input ports currently allocated in this System. More...
|
|
int | num_output_ports () const |
| Returns the number of output ports currently allocated in this System. More...
|
|
const InputPortBase & | get_input_port_base (InputPortIndex port_index) const |
| Returns a reference to an InputPort given its port_index . More...
|
|
const OutputPortBase & | get_output_port_base (OutputPortIndex port_index) const |
| Returns a reference to an OutputPort given its port_index . More...
|
|
int | num_total_inputs () const |
| Returns the total dimension of all of the vector-valued input ports (as if they were muxed). More...
|
|
int | num_total_outputs () const |
| Returns the total dimension of all of the vector-valued output ports (as if they were muxed). More...
|
|
virtual std::multimap< int, int > | GetDirectFeedthroughs () const =0 |
| Reports all direct feedthroughs from input ports to output ports. More...
|
|
int | num_cache_entries () const |
| Returns the number nc of cache entries currently allocated in this System. More...
|
|
const CacheEntry & | get_cache_entry (CacheIndex index) const |
| Returns a reference to a CacheEntry given its index . More...
|
|
CacheEntry & | get_mutable_cache_entry (CacheIndex index) |
| (Advanced) Returns a mutable reference to a CacheEntry given its index . More...
|
|
virtual | ~SystemMessageInterface ()=default |
|
|
Methods in this section are used by derived classes to declare cache entries for their own internal computations. (Other cache entries are provided automatically for well-known computations such as output ports and time derivatives.) Cache entries may contain values of any type, however the type for any particular cache entry is fixed after first allocation. Every cache entry must have an allocator function Allocate() and a calculator function Calc() . Allocate() returns an object suitable for holding a value of the cache entry. Calc() uses the contents of a given Context to produce the cache entry's value, which is placed in an object of the type returned by Allocate() .
- Warning
- These methods are currently specified as
public access, but will be demoted to protected access on or after 2021-10-01.
Prerequisites
Correct runtime caching behavior depends critically on understanding the dependencies of the cache entry's Calc() function (we call those "prerequisites"). If none of the prerequisites has changed since the last time Calc() was invoked to set the cache entry's value, then we don't need to perform a potentially expensive recalculation. On the other hand, if any of the prerequisites has changed then the current value is invalid and must not be used without first recomputing.
Currently it is not possible for Drake to infer prerequisites accurately and automatically from inspection of the Calc() implementation. Therefore, if you don't say otherwise, Drake will assume Calc() is dependent on all value sources in the Context, including time, state, input ports, parameters, and accuracy. That means the cache entry's value will be considered invalid if any of those sources has changed since the last time the value was calculated. That is safe, but can result in more computation than necessary. If you know that your Calc() method has fewer prerequisites, you may say so by providing an explicit list in the prerequisites_of_calc parameter. Every possible prerequisite has a DependencyTicket ("ticket"), and the list should consist of tickets. For example, if your calculator depends only on time (e.g. Calc(context) is sin(context.get_time()) ) then you would specify prerequisites_of_calc={time_ticket()} here. See Dependency tickets for a list of the possible tickets and what they mean.
- Warning
- It is critical that the prerequisite list you supply be accurate, or at least conservative, for correct functioning of the caching system. Drake cannot currently detect that a
Calc() function accesses an undeclared prerequisite. Even assuming you have correctly listed the prerequisites, you should include a prominent comment in every Calc() implementation noting that if the implementation is changed then the prerequisite list must be updated correspondingly.
A technique you can use to ensure that prerequisites have been properly specified is to make use of the Context's DisableCaching() method, which causes cache values to be recalculated unconditionally. You should get identical results with caching enabled or disabled, with speed being the only difference. You can also disable caching for individual cache entries in a Context, or specify that individual cache entries should be disabled by default when they are first allocated. - See also
- ContextBase::DisableCaching()
-
CacheEntry::disable_caching()
-
CacheEntry::disable_caching_by_default()
-
LeafOutputPort::disable_caching_by_default()
Which signature to use?
Although the allocator and calculator functions ultimately satisfy generic function signatures defined by a ValueProducer, we provide a variety of DeclareCacheEntry() signatures here for convenient specification, with mapping to the generic form handled invisibly. In particular, allocators are most easily defined by providing a model value that can be used to construct an allocator that copies the model when a new value object is needed. Alternatively a method can be provided that constructs a value object when invoked (those methods are conventionally, but not necessarily, named MakeSomething() where Something is replaced by the cache entry value type).
Because cache entry values are ultimately stored in AbstractValue objects, the underlying types must be suitable. That means the type must be copy constructible or cloneable. For methods below that are not given an explicit model value or construction ("make") method, the underlying type must also be default constructible. - See also
- maliput::drake::Value for more about abstract values.
|
CacheEntry & | DeclareCacheEntry (std::string description, std::function< std::unique_ptr< AbstractValue >()> alloc_function, std::function< void(const ContextBase &, AbstractValue *)> calc_function, std::set< DependencyTicket > prerequisites_of_calc={all_sources_ticket()}) |
|
template<class MySystem , class MyContext , typename ValueType > |
| DRAKE_DEPRECATED ("2021-11-01", "This overload for DeclareCacheEntry is rarely the best choice; it is" " unusual for allocation to actually require a boutique callback rather" " than just a Clone of a model_value. We found that most uses of this" " overload hindered readability, because other overloads would often do" " the job more directly. If no existing overload works, you may wrap a" " ValueProducer around your existing make method and call the primary" " DeclareCacheEntry overload that takes a ValueProducer, instead.") CacheEntry &DeclareCacheEntry(std |
|
template<class MySystem , class MyContext , typename ValueType > |
CacheEntry & | DeclareCacheEntry (std::string description, const ValueType &model_value, void(MySystem::*calc)(const MyContext &, ValueType *) const, std::set< DependencyTicket > prerequisites_of_calc={all_sources_ticket()}) |
| Declares a cache entry by specifying a model value of concrete type ValueType and a calculator function that is a class member function (method) with signature: More...
|
|
template<class MySystem , class MyContext , typename ValueType > |
| DRAKE_DEPRECATED ("2021-11-01", "This overload for DeclareCacheEntry is dispreferred because it might" " not reuse heap storage from one calculation to the next, and so is" " typically less efficient than the other overloads. A better option" " is to change the ValueType returned by-value to be an output pointer" " instead, and return void. If that is not possible, you may wrap a" " ValueProducer around your existing method and call the primary" " DeclareCacheEntry overload that takes a ValueProducer, instead.") CacheEntry &DeclareCacheEntry(std |
|
template<class MySystem , class MyContext , typename ValueType > |
CacheEntry & | DeclareCacheEntry (std::string description, void(MySystem::*calc)(const MyContext &, ValueType *) const, std::set< DependencyTicket > prerequisites_of_calc={all_sources_ticket()}) |
| Declares a cache entry by specifying only a calculator function that is a class member function (method) with signature: More...
|
|
template<class MySystem , class MyContext , typename ValueType > |
| DRAKE_DEPRECATED ("2021-11-01", "This overload for DeclareCacheEntry is dispreferred because it might" " not reuse heap storage from one calculation to the next, and so is" " typically less efficient than the other overloads. A better option" " is to change the ValueType returned by-value to be an output pointer" " instead, and return void. If that is not possible, you may wrap a" " ValueProducer around your existing method and call the primary" " DeclareCacheEntry overload that takes a ValueProducer, instead.") CacheEntry &DeclareCacheEntry(std |
|
CacheEntry & | DeclareCacheEntry (std::string description, ValueProducer value_producer, std::set< DependencyTicket > prerequisites_of_calc={all_sources_ticket()}) |
| Declares a new CacheEntry in this System using the most generic form of the calculation function. More...
|
|
|
Use these tickets to declare well-known sources as prerequisites of a downstream computation such as an output port, derivative, update, or cache entry. The ticket numbers for the built-in sources are the same for all systems. For time and accuracy they refer to the same global resource; otherwise they refer to the specified sources within the referencing system.
A dependency ticket for a more specific resource (a particular input or output port, a discrete variable group, abstract state variable, a parameter, or a cache entry) is allocated and stored with the resource when it is declared. Usually the tickets are obtained directly from the resource but you can recover them with methods here knowing only the resource index.
|
DependencyTicket | discrete_state_ticket (DiscreteStateIndex index) const |
| Returns a ticket indicating dependence on a particular discrete state variable xdᵢ (may be a vector). More...
|
|
DependencyTicket | abstract_state_ticket (AbstractStateIndex index) const |
| Returns a ticket indicating dependence on a particular abstract state variable xaᵢ. More...
|
|
DependencyTicket | numeric_parameter_ticket (NumericParameterIndex index) const |
| Returns a ticket indicating dependence on a particular numeric parameter pnᵢ (may be a vector). More...
|
|
DependencyTicket | abstract_parameter_ticket (AbstractParameterIndex index) const |
| Returns a ticket indicating dependence on a particular abstract parameter paᵢ. More...
|
|
DependencyTicket | input_port_ticket (InputPortIndex index) const |
| Returns a ticket indicating dependence on input port uᵢ indicated by index . More...
|
|
DependencyTicket | cache_entry_ticket (CacheIndex index) const |
| Returns a ticket indicating dependence on the cache entry indicated by index . More...
|
|
DependencyTicket | output_port_ticket (OutputPortIndex index) const |
| (Internal use only) Returns a ticket indicating dependence on the output port indicated by index . More...
|
|
int | num_continuous_states () const |
| Returns the number of declared continuous state variables. More...
|
|
int | num_discrete_state_groups () const |
| Returns the number of declared discrete state groups (each group is a vector-valued discrete state variable). More...
|
|
int | num_abstract_states () const |
| Returns the number of declared abstract state variables. More...
|
|
int | num_numeric_parameter_groups () const |
| Returns the number of declared numeric parameters (each of these is a vector-valued parameter). More...
|
|
int | num_abstract_parameters () const |
| Returns the number of declared abstract parameters. More...
|
|
int | implicit_time_derivatives_residual_size () const |
| Returns the size of the implicit time derivatives residual vector. More...
|
|
void | ValidateContext (const ContextBase &context) const final |
| Checks whether the given context was created for this system. More...
|
|
void | ValidateContext (const ContextBase *context) const |
| Checks whether the given context was created for this system. More...
|
|
template<class Clazz > |
void | ValidateCreatedForThisSystem (const Clazz &object) const |
| Checks whether the given object was created for this system. More...
|
|
| SystemBase ()=default |
| (Internal use only). More...
|
|
void | AddInputPort (std::unique_ptr< InputPortBase > port) |
| (Internal use only) Adds an already-constructed input port to this System. More...
|
|
void | AddOutputPort (std::unique_ptr< OutputPortBase > port) |
| (Internal use only) Adds an already-constructed output port to this System. More...
|
|
std::string | NextInputPortName (std::variant< std::string, UseDefaultName > given_name) const |
| (Internal use only) Returns a name for the next input port, using the given name if it isn't kUseDefaultName, otherwise making up a name like "u3" from the next available input port index. More...
|
|
std::string | NextOutputPortName (std::variant< std::string, UseDefaultName > given_name) const |
| (Internal use only) Returns a name for the next output port, using the given name if it isn't kUseDefaultName, otherwise making up a name like "y3" from the next available output port index. More...
|
|
void | AddDiscreteStateGroup (DiscreteStateIndex index) |
| (Internal use only) Assigns a ticket to a new discrete variable group with the given index . More...
|
|
void | AddAbstractState (AbstractStateIndex index) |
| (Internal use only) Assigns a ticket to a new abstract state variable with the given index . More...
|
|
void | AddNumericParameter (NumericParameterIndex index) |
| (Internal use only) Assigns a ticket to a new numeric parameter with the given index . More...
|
|
void | AddAbstractParameter (AbstractParameterIndex index) |
| (Internal use only) Assigns a ticket to a new abstract parameter with the given index . More...
|
|
CacheEntry & | DeclareCacheEntryWithKnownTicket (DependencyTicket known_ticket, std::string description, ValueProducer value_producer, std::set< DependencyTicket > prerequisites_of_calc={ all_sources_ticket()}) |
| (Internal use only) This is for cache entries associated with pre-defined tickets, for example the cache entry for time derivatives. More...
|
|
const internal::SystemParentServiceInterface * | get_parent_service () const |
| Returns a pointer to the service interface of the immediately enclosing Diagram if one has been set, otherwise nullptr. More...
|
|
DependencyTicket | assign_next_dependency_ticket () |
| (Internal use only) Assigns the next unused dependency ticket number, unique only within a particular system. More...
|
|
virtual std::function< void(const AbstractValue &)> | MakeFixInputPortTypeChecker (InputPortIndex port_index) const =0 |
| (Internal use only) Given a port_index , returns a function to be called when validating Context::FixInputPort requests. More...
|
|
const AbstractValue * | EvalAbstractInputImpl (const char *func, const ContextBase &context, InputPortIndex port_index) const |
| (Internal use only) Shared code for updating an input port and returning a pointer to its abstract value, or nullptr if the port is not connected. More...
|
|
void | ThrowNegativePortIndex (const char *func, int port_index) const |
| Throws std::exception to report a negative port_index that was passed to API method func . More...
|
|
void | ThrowInputPortIndexOutOfRange (const char *func, InputPortIndex port_index) const |
| Throws std::exception to report bad input port_index that was passed to API method func . More...
|
|
void | ThrowOutputPortIndexOutOfRange (const char *func, OutputPortIndex port_index) const |
| Throws std::exception to report bad output port_index that was passed to API method func . More...
|
|
void | ThrowNotAVectorInputPort (const char *func, InputPortIndex port_index) const |
| Throws std::exception because someone misused API method func , that is only allowed for declared-vector input ports, on an abstract port whose index is given here. More...
|
|
void | ThrowInputPortHasWrongType (const char *func, InputPortIndex port_index, const std::string &expected_type, const std::string &actual_type) const |
| Throws std::exception because someone called API method func claiming the input port had some value type that was wrong. More...
|
|
void | ThrowCantEvaluateInputPort (const char *func, InputPortIndex port_index) const |
| Throws std::exception because someone called API method func , that requires this input port to be evaluatable, but the port was neither fixed nor connected. More...
|
|
const InputPortBase & | GetInputPortBaseOrThrow (const char *func, int port_index) const |
| (Internal use only) Returns the InputPortBase at index port_index , throwing std::exception we don't like the port index. More...
|
|
const OutputPortBase & | GetOutputPortBaseOrThrow (const char *func, int port_index) const |
| (Internal use only) Returns the OutputPortBase at index port_index , throwing std::exception if we don't like the port index. More...
|
|
void | ThrowValidateContextMismatch (const ContextBase &) const |
| (Internal use only) Throws std::exception with a message that the sanity check(s) given by ValidateContext have failed. More...
|
|
void | InitializeContextBase (ContextBase *context) const |
| This method must be invoked from within derived class DoAllocateContext() implementations right after the concrete Context object has been allocated. More...
|
|
virtual std::unique_ptr< ContextBase > | DoAllocateContext () const =0 |
| Derived class implementations should allocate a suitable concrete Context type, then invoke the above InitializeContextBase() method. More...
|
|
const ContextSizes & | get_context_sizes () const |
| Obtains access to the declared Context partition sizes as accumulated during LeafSystem or Diagram construction . More...
|
|
ContextSizes & | get_mutable_context_sizes () |
| Obtains mutable access to the Context sizes struct. More...
|
|
void | set_implicit_time_derivatives_residual_size (int n) |
| Allows a LeafSystem to override the default size for the implicit time derivatives residual and a Diagram to sum up the total size. More...
|
|
internal::SystemId | get_system_id () const |
| (Internal) Gets the id used to tag context data as being created by this system. More...
|
|
static DependencyTicket | nothing_ticket () |
| Returns a ticket indicating that a computation does not depend on any source value; that is, it is a constant. More...
|
|
static DependencyTicket | time_ticket () |
| Returns a ticket indicating dependence on time. More...
|
|
static DependencyTicket | accuracy_ticket () |
| Returns a ticket indicating dependence on the accuracy setting in the Context. More...
|
|
static DependencyTicket | q_ticket () |
| Returns a ticket indicating that a computation depends on configuration state variables q. More...
|
|
static DependencyTicket | v_ticket () |
| Returns a ticket indicating dependence on velocity state variables v. More...
|
|
static DependencyTicket | z_ticket () |
| Returns a ticket indicating dependence on any or all of the miscellaneous continuous state variables z. More...
|
|
static DependencyTicket | xc_ticket () |
| Returns a ticket indicating dependence on all of the continuous state variables q, v, or z. More...
|
|
static DependencyTicket | xd_ticket () |
| Returns a ticket indicating dependence on all of the numerical discrete state variables, in any discrete variable group. More...
|
|
static DependencyTicket | xa_ticket () |
| Returns a ticket indicating dependence on all of the abstract state variables in the current Context. More...
|
|
static DependencyTicket | all_state_ticket () |
| 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. More...
|
|
static DependencyTicket | pn_ticket () |
| Returns a ticket indicating dependence on all of the numerical parameters in the current Context. More...
|
|
static DependencyTicket | pa_ticket () |
| Returns a ticket indicating dependence on all of the abstract parameters pa in the current Context. More...
|
|
static DependencyTicket | all_parameters_ticket () |
| Returns a ticket indicating dependence on all parameters p in this system, including numeric parameters pn, and abstract parameters pa. More...
|
|
static DependencyTicket | all_input_ports_ticket () |
| Returns a ticket indicating dependence on all input ports u of this system. More...
|
|
static DependencyTicket | all_sources_except_input_ports_ticket () |
| Returns a ticket indicating dependence on every possible independent source value except input ports. More...
|
|
static DependencyTicket | all_sources_ticket () |
| Returns a ticket indicating dependence on every possible independent source value, including time, accuracy, state, input ports, and parameters (but not cache entries). More...
|
|
static DependencyTicket | configuration_ticket () |
| Returns a ticket indicating dependence on all source values that may affect configuration-dependent computations. More...
|
|
static DependencyTicket | kinematics_ticket () |
| Returns a ticket indicating dependence on all source values that may affect configuration- or velocity-dependent computations. More...
|
|
static DependencyTicket | xcdot_ticket () |
| Returns a ticket for the cache entry that holds time derivatives of the continuous variables. More...
|
|
static DependencyTicket | pe_ticket () |
| Returns a ticket for the cache entry that holds the potential energy calculation. More...
|
|
static DependencyTicket | ke_ticket () |
| Returns a ticket for the cache entry that holds the kinetic energy calculation. More...
|
|
static DependencyTicket | pc_ticket () |
| Returns a ticket for the cache entry that holds the conservative power calculation. More...
|
|
static DependencyTicket | pnc_ticket () |
| Returns a ticket for the cache entry that holds the non-conservative power calculation. More...
|
|
static void | set_parent_service (SystemBase *child, const internal::SystemParentServiceInterface *parent_service) |
| (Internal use only) Declares that parent_service is the service interface of the Diagram that owns this subsystem. More...
|
|
static void | ThrowInputPortHasWrongType (const char *func, const std::string &system_pathname, InputPortIndex, const std::string &port_name, const std::string &expected_type, const std::string &actual_type) |
| Throws std::exception because someone called API method func claiming the input port had some value type that was wrong. More...
|
|
static void | ThrowUnsupportedScalarConversion (const SystemBase &from, const std::string &destination_type_name) |
| (Internal use only) Throws a std::exception for unsupported scalar type conversions. More...
|
|
static const ContextSizes & | get_context_sizes (const SystemBase &system) |
| Allows Diagram to access protected get_context_sizes() recursively on its subsystems. More...
|
|