Template Class SubsystemModel

Inheritance Relationships

Base Type

Class Documentation

template<class ScalarT, typename IdxT>
class SubsystemModel : public GridKit::PowerElectronics::SystemModel<ScalarT, IdxT>

Represents a subset of a PowerElectronicsModel that can be evaluated independently.

A SubsystemModel contains a collection of existing GridKit components and nodes taken from a larger system. Variables owned by those components and nodes become internal variables of the subsystem. Variables needed by those components but owned outside the subsystem become external coupling variables.

Components normally store connection indices in the global system indexing. During subsystem allocation, these indices are temporarily replaced with a contiguous local subsystem indexing so that the subsystem can be evaluated like an independent PowerElectronicsModel.

External coupling values must be supplied before residual or Jacobian evaluation, either directly through the external-data vectors or through a forcing function.

Todo:

Find a better name for this class and its base class.

Template Parameters:

  • ScalarT – Scalar type used by the model.

  • IdxT – Index type used for variable and connection indices.

Public Functions

inline SubsystemModel()

Default constructor for the system model.

Post:

System model parameters set as default

inline SubsystemModel(bool use_jac)

Default constructor for the system model.

Post:

System model parameters set as default

inline virtual int allocate() override

Allocate the subsystem for independent evaluation.

Converts the selected components and nodes from global system indexing to local subsystem indexing, allocates storage for the subsystem’s internal variables, and creates storage for coupling variables that lie outside the subsystem.

Component pointers are then redirected to either the subsystem’s internal vectors or its external coupling-data vectors. Finally, the subsystem Jacobian structure is assembled using only entries whose row and column belong to internal subsystem variables.

Pre:

Components and nodes added to the subsystem must already be allocated by the parent system.

Post:

Component and node connection indices use local subsystem indexing, and the subsystem is ready for residual and Jacobian evaluation.

Returns:

0 on success, otherwise an error code returned during allocation.

inline int distributeExternalVectors()

Update the subsystem external state and derivative data.

If a forcing function is provided, invoke it at the current subsystem time to update the external coupling variables.

Note

The user can supply external coupling data in two ways:

  • Through a forcing function that updates getExternalDataY() and getExternalDataYP() before each evaluation. This is useful for time-dependent or streaming external data.

  • By directly updating these vectors when no forcing function is provided, as in zero-order hold (ZOH) coupling.

Post:

If a forcing function is set, y_ext_data_ and yp_ext_data_ contain the external coupling values supplied by the function.

Returns:

0 on success.

inline virtual int evaluateInternalResidual() override

Evaluate Residuals at each component then collect them.

Returns:

int 0 if successful, positive if there’s a recoverable error, negative if unrecoverable

inline virtual int evaluateJacobian() override

Creates the system Jacobian representing \(\alpha dF/dy' + dF/dy\).

Updates the CSR Jacobian values using the per-component mappings computed during allocate().

Returns:

int 0 if successful, positive if there’s a recoverable error, negative if unrecoverable

inline void addComponent(component_type *component)

Add a component to the subsystem.

Rejected while connections are in the local-indexed state, since the component’s stored connection indices would otherwise be interpreted inconsistently with the rest of the subsystem. Call release() first.

Parameters:

component – [in] Component to add.

inline void addNode(node_type *node)

Add a node to the subsystem.

Rejected while connections are in the local-indexed state, since the node’s stored connection indices would otherwise be interpreted inconsistently with the rest of the subsystem. Call release() first.

Parameters:

node – [in] Node to add.

inline void addInterface(interface_type *component)

Add a partition interface to the subsystem.

Adds the partition interface to the subsystem’s component list and keeps a separate reference to it in the interface list.

Parameters:

component – Pointer to the interface component to add.

inline int restoreGlobalConnection()

Restores the subsystem to global system indexing.

Restores the original global connection indices of all components and nodes, then clears the subsystem’s global-to-local connection map. The subsystem is marked unallocated so that its local indexing can be rebuilt when it is allocated again.

Pre:

Component and node connections may use subsystem-local indices.

Post:

Component and node connections use their original global system indices, global_to_local_map_ is empty, and the subsystem is unallocated.

Returns:

0 on success, otherwise an error code returned while restoring the global connections.