<!-- GENERATED by tools/generators/pybindEmitter.py from definitions/ - do not edit -->
(sec-mbs-systemdata)=
# SystemData

A data structure of a MainSystem which mainly allows access to states and details of items (objects, nodes, loads, etc.). In particular access is given to system coordinates in all configurations, object and node coordinates, as well as to local-to-global (LTG) coordinate indices. Here, ODE2 represents second order differential equations (and coordinates), ODE1 for first order ODEs, AE represents algebraic equations, and Data is used for data (=history) variables that represent contact states or plastic deformation which is no classical state. The SystemData structure allows advanced access to this data, which HAS TO BE USED WITH CARE, as unexpected results and system crash might happen.


```python
import exudyn as exu               #EXUDYN package including C++ core part
from exudyn.itemInterface import * #conversion of data to exudyn dictionaries
SC = exu.SystemContainer()         #container of systems
mbs = SC.AddSystem()               #add a new system to work with
nMP = mbs.AddNode(NodePoint(referenceCoordinates=[0,0,0]))
mbs.AddObject(ObjectMassPoint(mass=10, nodeNumber=nMP ))
mMP = mbs.AddMarker(MarkerNodePosition(nodeNumber = nMP))
mbs.AddLoad(Force(markerNumber = mMP, loadVector=[2,0,5]))
mbs.Assemble()
mbs.SolveDynamic(exu.SimulationSettings())

#obtain current ODE2 system vector including reference values:
uTotal = mbs.systemData.GetODE2CoordinatesTotal()

#obtain current ODE2 system vector without reference values
#  (e.g., after static simulation finished):
u = mbs.systemData.GetODE2Coordinates()
#set initial ODE2 vector for next simulation (only coordinates!):
mbs.systemData.SetODE2Coordinates(coordinates=u,
               configuration=exu.ConfigurationType.Initial)

#faster access with reference access (copy=False):
uReference = mbs.systemData.GetODE2Coordinates(copy=False)
u2 = uReference[2]
#we can also modify data, but this may be dangerous!
uReference[2] += 1
print('u2 =', u2, ', now:', mbs.systemData.GetODE2Coordinates()[2])
#NOTE: reference access is possible throughout simulation and may
#      allow faster user functions, but is potentially dangerous
#      to erroneous behavior: for safety, compare with copy=True results!

#print detailed information on items:
mbs.systemData.Info()
#print LTG lists for objects and loads:
mbs.systemData.InfoLTG()
```

```text
u2 = 0.24999999999999897 , now: 1.249999999999999
node0:
    {'nodeType': 'Point', 'referenceCoordinates': array([0., 0., 0.]), 'initialCoordinates': array([0., 0., 0.]), 'initialVelocities': array([0., 0., 0.]), 'name': 'node0', 'Vshow': True, 'VdrawSize': -1.0, 'Vcolor': [-1.0, -1.0, -1.0, -1.0]}
object0:
    {'objectType': 'MassPoint', 'mass': 10.0, 'nodeNumber': 0, 'name': 'object0', 'Vshow': True, 'VgraphicsData': [{'graphicsData': '<not requested>'}]}
marker0:
    {'markerType': 'NodePosition', 'nodeNumber': 0, 'name': 'marker0', 'Vshow': True}
load0:
    {'loadType': 'ForceVector', 'markerNumber': 0, 'loadVector': array([2., 0., 5.]), 'bodyFixed': False, 'loadVectorUserFunction': 0, 'name': 'load0', 'Vshow': True}
object 0 ODE2 LTG=[0,1,2]
object 0 ODE1 LTG=[]
object 0 AE LTG  =[]
object 0 Data LTG=[]
```

```{container} notebookorigin
`python/Notebooks/reference/mainSystem.ipynb`
```


The class **MainSystemData** has the following **functions and structures**:

- **`NumberOfLoads()`**: return number of loads in system

  *Example*:

  ```python
  print(mbs.systemData.NumberOfLoads())
  ```

- **`NumberOfMarkers()`**: return number of markers in system

  *Example*:

  ```python
  print(mbs.systemData.NumberOfMarkers())
  ```

- **`NumberOfNodes()`**: return number of nodes in system

  *Example*:

  ```python
  print(mbs.systemData.NumberOfNodes())
  ```

- **`NumberOfObjects()`**: return number of objects in system

  *Example*:

  ```python
  print(mbs.systemData.NumberOfObjects())
  ```

- **`NumberOfSensors()`**: return number of sensors in system

  *Example*:

  ```python
  print(mbs.systemData.NumberOfSensors())
  ```

- **`ODE2Size(configurationType = exu.ConfigurationType.Current)`**: get size of ODE2 coordinate vector for given configuration (only works correctly after mbs.Assemble() )

  *Example*:

  ```python
  print('ODE2 size=',mbs.systemData.ODE2Size())
  ```

- **`ODE1Size(configurationType = exu.ConfigurationType.Current)`**: get size of ODE1 coordinate vector for given configuration (only works correctly after mbs.Assemble() )

  *Example*:

  ```python
  print('ODE1 size=',mbs.systemData.ODE1Size())
  ```

- **`AEsize(configurationType = exu.ConfigurationType.Current)`**: get size of AE coordinate vector for given configuration (only works correctly after mbs.Assemble() )

  *Example*:

  ```python
  print('AE size=',mbs.systemData.AEsize())
  ```

- **`DataSize(configurationType = exu.ConfigurationType.Current)`**: get size of Data coordinate vector for given configuration (only works correctly after mbs.Assemble() )

  *Example*:

  ```python
  print('Data size=',mbs.systemData.DataSize())
  ```

- **`SystemSize(configurationType = exu.ConfigurationType.Current)`**: get size of System coordinate vector for given configuration (only works correctly after mbs.Assemble() )

  *Example*:

  ```python
  print('System size=',mbs.systemData.SystemSize())
  ```

- **`GetTime(configurationType = exu.ConfigurationType.Current)`**: get configuration dependent time.

  *Example*:

  ```python
  mbs.systemData.GetTime(exu.ConfigurationType.Initial)
  ```

- **`SetTime(newTime, configurationType = exu.ConfigurationType.Current)`**: set configuration dependent time; use this access with care, e.g., in user-defined solvers.

  *Example*:

  ```python
  mbs.systemData.SetTime(10., exu.ConfigurationType.Initial)
  ```

- **`AddODE2LoadDependencies(loadNumber, globalODE2coordinates)`**: advanced function for adding special dependencies of loads onto ODE2 coordinates, taking a list / numpy array of global ODE2 coordinates; this function needs to be called after Assemble() and needs to contain global ODE2 coordinate indices; this list only affects implicit or static solvers if timeIntegration.computeLoadsJacobian or staticSolver.computeLoadsJacobian is set to 1 (ODE2) or 2 (ODE2 and ODE2_t dependencies); if set, it may greatly improve convergence if loads with user functions depend on some system states, such as in a load with feedback control loop; the additional dependencies are not required, if doSystemWideDifferentiation=True, however the latter option being much less efficient. For more details, consider the file doublePendulum2DControl.py in the examples directory.

  *Example*:

  ```python
  mbs.systemData.AddODE2LoadDependencies(0,[0,1,2])
  #add dependency of load 5 onto node 2 coordinates:
  nodeLTG2 = mbs.systemData.GetNodeLTGODE2(2)
  mbs.systemData.AddODE2LoadDependencies(5,nodeLTG2)
  ```

- **`Info()`**: print detailed information on every item; for short information use print(mbs)

  *Example*:

  ```python
  mbs.systemData.Info()
  ```

- **`InfoLTG()`**: print LTG information of objects and load dependencies

  *Example*:

  ```python
  mbs.systemData.InfoLTG()
  ```


(sec-mbs-systemdata-coordinates)=
## SystemData: Access coordinates


This section provides access functions to global coordinate vectors. Assigning invalid values or using wrong vector size might lead to system crash and unexpected results.

The class **MainSystemData** has the following **functions and structures** regarding **coordinate access**:

- **`GetODE2CoordinatesTotal(configuration = exu.ConfigurationType.Current)`**: get ODE2 system coordinates (displacements/rotation) including reference values for given configuration (default: exu.Configuration.Current); in case of exu.ConfigurationType.Reference, it only includes reference values once and is identical to GetODE2Coordinates; note that faster access to coordinates is possibly with GetODE2Coordinates(copy=False), which is not possible with GetODE2CoordinatesTotal !

  *Example*:

  ```python
  uTotal = mbs.systemData.GetODE2CoordinatesTotal()
  #this is equivalent to:
  uTotal=mbs.systemData.GetODE2Coordinates()+mbs.systemData.GetODE2Coordinates(exu.ConfigurationType.Reference)
  ```

- **`GetODE2Coordinates(configuration = exu.ConfigurationType.Current, copy = True)`**: get ODE2 system coordinates (displacements/rotations) for given configuration (default: exu.Configuration.Current)

  *Example*:

  ```python
  uCurrent = mbs.systemData.GetODE2Coordinates()
  ```

- **`SetODE2Coordinates(coordinates, configuration = exu.ConfigurationType.Current)`**: set ODE2 system coordinates (displacements/rotations) for given configuration (default: exu.Configuration.Current); invalid vector size may lead to system crash!

  *Example*:

  ```python
  mbs.systemData.SetODE2Coordinates(uCurrent)
  ```

- **`GetODE2Coordinates_t(configuration = exu.ConfigurationType.Current, copy = True)`**: get ODE2 system coordinates (velocities) for given configuration (default: exu.Configuration.Current)

  *Example*:

  ```python
  vCurrent = mbs.systemData.GetODE2Coordinates_t()
  ```

- **`SetODE2Coordinates_t(coordinates, configuration = exu.ConfigurationType.Current)`**: set ODE2 system coordinates (velocities) for given configuration (default: exu.Configuration.Current); invalid vector size may lead to system crash!

  *Example*:

  ```python
  mbs.systemData.SetODE2Coordinates_t(vCurrent)
  ```

- **`GetODE2Coordinates_tt(configuration = exu.ConfigurationType.Current, copy = True)`**: get ODE2 system coordinates (accelerations) for given configuration (default: exu.Configuration.Current)

  *Example*:

  ```python
  vCurrent = mbs.systemData.GetODE2Coordinates_tt()
  ```

- **`SetODE2Coordinates_tt(coordinates, configuration = exu.ConfigurationType.Current)`**: set ODE2 system coordinates (accelerations) for given configuration (default: exu.Configuration.Current); invalid vector size may lead to system crash!

  *Example*:

  ```python
  mbs.systemData.SetODE2Coordinates_tt(aCurrent)
  ```

- **`GetODE1Coordinates(configuration = exu.ConfigurationType.Current, copy = True)`**: get ODE1 system coordinates (displacements) for given configuration (default: exu.Configuration.Current)

  *Example*:

  ```python
  qCurrent = mbs.systemData.GetODE1Coordinates()
  ```

- **`SetODE1Coordinates(coordinates, configuration = exu.ConfigurationType.Current)`**: set ODE1 system coordinates (velocities) for given configuration (default: exu.Configuration.Current); invalid vector size may lead to system crash!

  *Example*:

  ```python
  mbs.systemData.SetODE1Coordinates_t(qCurrent)
  ```

- **`GetODE1Coordinates_t(configuration = exu.ConfigurationType.Current, copy = True)`**: get ODE1 system coordinates (velocities) for given configuration (default: exu.Configuration.Current)

  *Example*:

  ```python
  qCurrent = mbs.systemData.GetODE1Coordinates_t()
  ```

- **`SetODE1Coordinates_t(coordinates, configuration = exu.ConfigurationType.Current)`**: set ODE1 system coordinates (displacements) for given configuration (default: exu.Configuration.Current); invalid vector size may lead to system crash!

  *Example*:

  ```python
  mbs.systemData.SetODE1Coordinates(qCurrent)
  ```

- **`GetAECoordinates(configuration = exu.ConfigurationType.Current, copy = True)`**: get algebraic equations (AE) system coordinates for given configuration (default: exu.Configuration.Current)

  *Example*:

  ```python
  lambdaCurrent = mbs.systemData.GetAECoordinates()
  ```

- **`SetAECoordinates(coordinates, configuration = exu.ConfigurationType.Current)`**: set algebraic equations (AE) system coordinates for given configuration (default: exu.Configuration.Current); invalid vector size may lead to system crash!

  *Example*:

  ```python
  mbs.systemData.SetAECoordinates(lambdaCurrent)
  ```

- **`GetDataCoordinates(configuration = exu.ConfigurationType.Current, copy = True)`**: get system data coordinates for given configuration (default: exu.Configuration.Current)

  *Example*:

  ```python
  dataCurrent = mbs.systemData.GetDataCoordinates()
  ```

- **`SetDataCoordinates(coordinates, configuration = exu.ConfigurationType.Current)`**: set system data coordinates for given configuration (default: exu.Configuration.Current); invalid vector size may lead to system crash!

  *Example*:

  ```python
  mbs.systemData.SetDataCoordinates(dataCurrent)
  ```

- **`GetSystemState(configuration = exu.ConfigurationType.Current)`**: get system state for given configuration (default: exu.Configuration.Current); state vectors do not include the non-state derivatives ODE1_t and ODE2_tt and the time; function is copying data - not highly efficient; format of pyList: [ODE2Coords, ODE2Coords_t, ODE1Coords, AEcoords, dataCoords]

  *Example*:

  ```python
  sysStateList = mbs.systemData.GetSystemState()
  ```

- **`SetSystemState(systemStateList, configuration = exu.ConfigurationType.Current)`**: set system data coordinates for given configuration (default: exu.Configuration.Current); invalid list of vectors / vector size may lead to system crash; write access to state vectors (but not the non-state derivatives ODE1_t and ODE2_tt and the time); function is copying data - not highly efficient; format of pyList: [ODE2Coords, ODE2Coords_t, ODE1Coords, AEcoords, dataCoords]

  *Example*:

  ```python
  mbs.systemData.SetSystemState(sysStateList, configuration = exu.ConfigurationType.Initial)
  ```

- **`GetSystemStateDict(configuration = exu.ConfigurationType.Current, reference = False)`**: get dictionary with copies of (or references to) system states for given configuration (default: exu.Configuration.Current), with at least the following quantities: ODE1Coords, ODE1Coords_t, ODE2Coords, ODE2Coords_t, ODE2Coords_tt, AECoords, dataCoords; we can obtain copies OR references to vectors without copying, meaning that these vectors then have read-write properties and have to be treated carefully! The dictionary's contents are subject to changes in the future; if reference=False, data is copied

  *Example*:

  ```python
  d = mbs.systemData.GetSystemStateDict()
  ```


(sec-systemdata-objectltg)=
## SystemData: Get object LTG coordinate mappings


This section provides access functions the {ref}`LTG <LTG>`-lists for every object (body, constraint, ...) in the system. For details on the {ref}`LTG <LTG>` mapping, see [](#sec-overview-ltgmapping).

The class **MainSystemData** has the following **functions and structures** regarding **object LTG coordinate mappings**:

- **`GetObjectLTGODE2(objectNumber)`**: get object local-to-global coordinate mapping (list of global coordinate indices) for ODE2 coordinates; only available after Assemble()

  *Example*:

  ```python
  ltgObject4 = mbs.systemData.GetObjectLTGODE2(4)
  ```

- **`GetObjectLTGODE1(objectNumber)`**: get object local-to-global coordinate mapping (list of global coordinate indices) for ODE1 coordinates; only available after Assemble()

  *Example*:

  ```python
  ltgObject4 = mbs.systemData.GetObjectLTGODE1(4)
  ```

- **`GetObjectLTGAE(objectNumber)`**: get object local-to-global coordinate mapping (list of global coordinate indices) for algebraic equations (AE) coordinates; only available after Assemble()

  *Example*:

  ```python
  ltgObject4 = mbs.systemData.GetObjectLTGAE(4)
  ```

- **`GetObjectLTGData(objectNumber)`**: get object local-to-global coordinate mapping (list of global coordinate indices) for data coordinates; only available after Assemble()

  *Example*:

  ```python
  ltgObject4 = mbs.systemData.GetObjectLTGData(4)
  ```

- **`GetNodeLTGODE2(nodeNumber)`**: get node local-to-global coordinate mapping (list of global coordinate indices) for ODE2 coordinates; only available after Assemble()

  *Example*:

  ```python
  ltgNode4 = mbs.systemData.GetNodeLTGODE2(4)
  ```

- **`GetNodeLTGODE1(nodeNumber)`**: get node local-to-global coordinate mapping (list of global coordinate indices) for ODE1 coordinates; only available after Assemble()

  *Example*:

  ```python
  ltgNode4 = mbs.systemData.GetNodeLTGODE1(4)
  ```

- **`GetNodeLTGAE(nodeNumber)`**: get node local-to-global coordinate mapping (list of global coordinate indices) for AE coordinates; only available after Assemble()

  *Example*:

  ```python
  ltgNode4 = mbs.systemData.GetNodeLTGAE(4)
  ```

- **`GetNodeLTGData(nodeNumber)`**: get node local-to-global coordinate mapping (list of global coordinate indices) for Data coordinates; only available after Assemble()

  *Example*:

  ```python
  ltgNode4 = mbs.systemData.GetNodeLTGData(4)
  ```