State objects

State objects#

This page is an introduction to the states module. For the different state objects, go to Objects.

State Data-Structure#

C4dynamics offers versatile data-structures for managing state variables.

Users from a range of disciplines, particularly those involving mathematical modeling, simulations, and dynamic systems, can define a state with any desired variables, for example:

Control Systems

  • Pendulum

  • \(X = [\theta, \omega]^T\)

  • Angle, angular velocity.

  • s = c4d.state(theta = 10 * c4d.d2r, omega = 0)

Navigation

  • Strapdown navigation system

  • \(X = [x, y, z, v_x, v_y, v_z, q_0, q_1, q_2, q_3, b_{ax}, b_{ay}, b_{az}]^T\)

  • Position, velocity, quaternions, biases.

  • s = c4d.state(x = 0, y = 0, z = 0, vx = 0, vy = 0, vz = 0, q0 = 0, q1 = 0, q2 = 0, q3 = 0, bax = 0, bay = 0, baz = 0)

Computer Vision

  • Objects tracker

  • \(X = [x, y, w, h]^T\)

  • Center pixel, bounding box size.

  • s = c4d.state(x = 960, y = 540, w = 20, h = 10)

Aerospace

  • Aircraft

  • \(X = [x, y, z, v_x, v_y, v_z, \varphi, \theta, \psi, p, q, r]^T\)

  • Position, velocity, angles, angular velocities.

  • s = c4d.state(x = 0, y = 0, z = 0, vx = 0, vy = 0, vz = 0, phi = 0, theta = 0, psi = 0, p = 0, q = 0, r = 0)

Autonomous Systems

  • Self-driving car

  • \(X = [x, y, z, \theta, \omega]^T\)

  • Position and velocity, heading and angular velocity.

  • s = c4d.state(x = 0, y = 0, v = 0, theta = 0, omega = 0)

Robotics

  • Robot arm

  • \(X = [\theta_1, \theta_2, \omega_1, \omega_2]^T\)

  • Joint angles, angular velocities.

  • s = c4d.state(theta1 = 0, theta2 = 0, omega1 = 0, omega2 = 0)

And many others.

These data-structures encapsulate the variables into a state vector \(X\) (a numpy array), allows for seamless execution of vector operations on the state, enabling efficient and intuitive manipulations of the state data.

Operations#

Operations on state vectors are categorized into two main types: mathematical operations and data management operations.

The mathematical operations involve direct manipulation of the state vectors using mathematical methods. These operations include multiplication, addition, and normalization, and can be performed by standard numpy methods.

The data management operations involve managing the state vector data, such as storing and retrieving states at different times or handling time series data. To perform these operations, c4dynamics provides a variety of methods under the state object.

The following tables summarize the mathematical and data management operations on a state vector.

Let an arbitrary state vector with variables \(x = 1, y = 0, z = 0\):

Import c4dynamics:

>>> import c4dynamics as c4d

>>> s = c4d.state(x = 1, y = 0, z = 0)
>>> print(s)
[ x  y  z ]
>>> s.X   
[1  0  0]
Mathematical Operations#

Operation

Example

Scalar Multiplication
>>> s.X * 2
[2  0  0]

Matrix Multiplication
>>> R = c4d.rotmat.dcm321(psi = c4d.pi / 2)
>>> s.X @ R
[0  1  0]

Norm Calculation
>>> np.linalg.norm(s.X)
1

Addition/Subtraction
>>> s.X + [-1, 0, 0]
[0  0  0]

Dot Product
>>> s.X @ s.X
1

Normalization
>>> s.X / np.linalg.norm(s.X)
[1  0  0]
Data Management Operations#

Operation

Example

Store the current state

>>> s.store()

Store with time-stamp

>>> s.store(t = 0)

Store the state in a for-loop
>>> for t in np.linspace(0, 1, 3):
...   s.X = np.random.rand(3)
...   s.store(t)

Get the stored data
>>> s.data()
[[0     0.37  0.76  0.20]
[0.5    0.93  0.28  0.59]
[1      0.79  0.39  0.33]]

Get the time-series of the data
>>> s.data('t')
[0  0.5  1]

Get data of a variable
>>> s.data('x')[1]
[0.37  0.93  0.79]

Get time-series and data of a variable
>>> time, y_data = s.data('y')
>>> time
[0  0.5  1]
>>> y_data
[0.76  0.28  0.39]

Get the state at a given time
>>> s.timestate(t = 0.5)
[0.93  0.28  0.59]

Plot the histories of a variable
>>> s.plot('z')
…

State Construction#

A state instance is created by calling the state constructor with pairs of variables that compose the state and their initial conditions. For example, a state of two variables, \(var1\) and \(var2\), is created by:

>>> s = c4d.state(var1 = 0, var2 = 0)

The list of the variables that form the state is given by print(s).

>>> print(s)
[ var1  var2 ]

Initial conditions

The variables must be passed with initial values. These values may be retrieved later by calling state.X0:

>>> s.X0  
[0  0]

When the initial values are not known at the stage of constructing the state object, it’s possible to pass zeros and override them later by direct assignment of the state variable with a 0 suffix, s.var10 = 100, s.var20 = 200. See more at state.X0.

Adding variables

Adding state variables outside the constructor is possible by using addvars(**kwargs), where kwargs represent the pairs of variables and their initial conditions as calling the state constructor:

>>> s.addvars(var3 = 0)
>>> print(s)
[ var1  var2  var3 ]

Parameters

All the variables that passed to the state constructor are considered state variables, and only these variables. Parameters, i.e. data attributes that are added to the object outside the constructor (the __init__ method), as in:

>>> s.parameter = 0

are considered part of the object attributes, but are not part of the object state:

>>> print(s)
[ var1  var2  var3 ]

Predefined states

Another way to create a state instance is by using one of the pre-defined objects from the states library. These state objects may be useful as they are optimized for particular tasks.

Objects#

State

The state class.

States library

A collection of predefined states.
Contents