State

State represents a dynamic state variable in a trajectory optimization problem. Unlike control inputs, states evolve according to dynamics constraints and can have boundary conditions specified at the initial and final time points. Like all Variables, States also support min/max bounds and initial trajectory guesses to help guide the optimization solver toward good solutions.

openscvx.symbolic.expr.state.State

Bases: Variable

State variable with boundary conditions for trajectory optimization.

State represents a dynamic state variable in a trajectory optimization problem. Unlike control inputs, states evolve according to dynamics constraints and can have boundary conditions specified at the initial and final time points. Like all Variables, States also support min/max bounds and initial trajectory guesses to help guide the optimization solver toward good solutions.

States support four types of boundary conditions:

• fixed: State value is constrained to a specific value
• free: State value is optimized within the specified bounds
• minimize: Adds a term to the objective function to minimize the state value
• maximize: Adds a term to the objective function to maximize the state value

Each element of a multi-dimensional state can have different boundary condition types, allowing for fine-grained control over the optimization.

Attributes:

Name	Type	Description
name	str	Unique name identifier for this state variable
_shape	tuple[int, ...]	Shape of the state vector (typically 1D like (3,) for 3D position)
_slice	slice | None	Internal slice information for variable indexing
_min	ndarray | None	Minimum bounds for state variables
_max	ndarray | None	Maximum bounds for state variables
_guess	ndarray | None	Initial trajectory guess
_initial	ndarray | None	Initial state values with boundary condition types
initial_type	ndarray | None	Array of boundary condition types for initial state
_final	ndarray | None	Final state values with boundary condition types
final_type	ndarray | None	Array of boundary condition types for final state

Example

Scalar time state with fixed initial time, minimize final time:

time = State("time", (1,))
time.min = [0.0]
time.max = [10.0]
time.initial = [("fixed", 0.0)]
time.final = [("minimize", 5.0)]

3D position state with mixed boundary conditions:

pos = State("pos", (3,))
pos.min = [0, 0, 10]
pos.max = [10, 10, 200]
pos.initial = [0, ("free", 1), 50]  # x fixed, y free, z fixed
pos.final = [10, ("free", 5), ("maximize", 150)]  # Maximize final altitude

final property writable

Get the final state boundary condition values.

Returns:

Type	Description
	Array of final state values (regardless of boundary condition type),
	or None if not set.

Note

Use final_type to see the boundary condition types for each element.

Example

Get final state boundary conditions:

x = State("x", (2,))
x.final = [10, ("minimize", 0)]
print(x.final)  # [10. 0.]
print(x.final_type)  # ['Fix' 'Minimize']

initial property writable

Get the initial state boundary condition values.

Returns:

Type	Description
	Array of initial state values (regardless of boundary condition type),
	or None if not set.

Note

Use initial_type to see the boundary condition types for each element.

Example

Get initial state boundary conditions:

x = State("x", (2,))
x.initial = [0, ("free", 1)]
print(x.initial)  # [0. 1.]
print(x.initial_type)  # ['Fix' 'Free']

max property writable

Get the maximum bounds for the state variables.

Returns:

Type	Description
	Array of maximum values for each state variable element.

Example

Get upper bounds:

vel = State("vel", (3,))
vel.max = [10, 10, 5]
print(vel.max)  # [10. 10. 5.]

min property writable

Get the minimum bounds for the state variables.

Returns:

Type	Description
	Array of minimum values for each state variable element.

Example

Get lower bounds:

pos = State("pos", (3,))
pos.min = [0, 0, 10]
print(pos.min)  # [0. 0. 10.]

scaling_max property writable

Get the scaling maximum bounds for the state variables.

Returns:

Type	Description
	Array of scaling maximum values for each state variable element, or None if not set.

scaling_min property writable

Get the scaling minimum bounds for the state variables.

Returns:

Type	Description
	Array of scaling minimum values for each state variable element, or None if not set.

_check_bounds_against_initial_final()

Validate that fixed boundary conditions respect min/max bounds.

This internal method is automatically called when bounds or boundary conditions are set to ensure consistency.

Raises:

Type	Description
ValueError	If any fixed initial or final value violates the min/max bounds

_hash_into(hasher: hashlib._Hash) -> None

Hash State including boundary condition types.

Extends Variable._hash_into to include the structural metadata that affects the compiled problem: boundary condition types (fixed, free, minimize, maximize). Values are not hashed as they are runtime parameters.

Parameters:

Name	Type	Description	Default
hasher	_Hash	A hashlib hash object to update	required

Boundary Conditions

States support four types of boundary conditions at initial and final time points. Each element of a multi-dimensional state can have different boundary condition types. Boundary conditions are specified using either a simple number (defaults to "fixed") or a tuple of (type, value).

BoundaryType Enum

openscvx.symbolic.expr.state.BoundaryType

Bases: str, Enum

Enumeration of boundary condition types for state variables.

This enum allows users to specify boundary conditions using plain strings while maintaining type safety internally. Boundary conditions control how the optimizer handles initial and final state values.

Attributes:

Name	Type	Description
FIXED	str	State value is fixed to a specific value
FREE	str	State value is free to be optimized within bounds
MINIMIZE	str	Objective term to minimize the state value
MAXIMIZE	str	Objective term to maximize the state value

Example

Can use either enum or string:

BoundaryType.FIXED
"fixed"  # Equivalent

Boundary Condition Types

• fixed: State value is constrained to a specific value (use plain number or tuple ("fixed", value))
• free: State value is optimized within bounds, initialized at the given value (use tuple ("free", value))
• minimize: Adds objective term to minimize the state value (use tuple ("minimize", value))
• maximize: Adds objective term to maximize the state value (use tuple ("maximize", value))