Variable

openscvx.symbolic.expr.variable.Variable

Bases: Leaf

Base class for decision variables in optimization problems.

Variable represents decision variables (free parameters) in an optimization problem. These are values that the optimizer can adjust to minimize the objective function while satisfying constraints. Variables can have bounds (min/max) and initial guesses to guide the optimization process.

Unlike Parameters (which are fixed values that can be changed between solves), Variables are optimized by the solver. In trajectory optimization, Variables typically represent discretized state or control trajectories.

Note

Variable is typically not instantiated directly. Instead, use the specialized subclasses State (for state variables with boundary conditions) or Control (for control inputs). These provide additional functionality specific to trajectory optimization.

Attributes:

Name	Type	Description
name	str	Name identifier for the variable
_shape	tuple[int, ...]	Shape of the variable as a tuple (typically 1D)
_slice	slice | None	Internal slice information for variable indexing
_min	ndarray | None	Minimum bounds for each element of the variable
_max	ndarray | None	Maximum bounds for each element of the variable
_guess	ndarray | None	Initial guess for the variable trajectory (n_points, n_vars)

Example

Typically, use State or Control instead of Variable directly:

pos = openscvx.State("pos", shape=(3,)) u = openscvx.Control("u", shape=(2,))

guess property writable

Get the initial guess for the variable trajectory.

The guess provides a starting point for the optimizer. A good initial guess can significantly improve convergence speed and help avoid local minima.

Returns:

Type	Description
	2D array of shape (n_points, n_vars) representing the variable trajectory
	over time, or None if no guess is provided.

Example

x = Variable("x", shape=(2,))

Linear interpolation from [0,0] to [10,10] over 50 points

x.guess = np.linspace([0, 0], [10, 10], 50) print(x.guess.shape) # (50, 2)

max property writable

Get the maximum bounds (upper bounds) for the variable.

Returns:

Type	Description
	Array of maximum values for each element of the variable, or None if unbounded.

Example

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

min property writable

Get the minimum bounds (lower bounds) for the variable.

Returns:

Type	Description
	Array of minimum values for each element of the variable, or None if unbounded.

Example

pos = Variable("pos", shape=(3,)) pos.min = [-10, -10, 0] print(pos.min) # [-10., -10., 0.]

_hash_into(hasher: hashlib._Hash) -> None

Hash Variable using its slice (canonical position, name-invariant).

Instead of hashing the variable name, we hash the _slice attribute which represents the variable's canonical position in the unified state/control vector. This ensures that two problems with the same structure but different variable names produce the same hash.

Parameters:

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

append(other=None, *, min=-np.inf, max=np.inf, guess=0.0)

Append a new dimension to this variable or merge with another variable.

This method extends the variable's dimension by either: 1. Appending another Variable object (concatenating their dimensions) 2. Adding a single new scalar dimension with specified bounds and guess

The bounds and guesses of both variables are concatenated appropriately.

Parameters:

Name	Type	Description	Default
other		Another Variable object to append. If None, adds a single scalar dimension with the specified min/max/guess values.	None
min		Minimum bound for the new dimension (only used if other is None). Defaults to -np.inf (unbounded below).	-inf
max		Maximum bound for the new dimension (only used if other is None). Defaults to np.inf (unbounded above).	inf
guess		Initial guess value for the new dimension (only used if other is None). Defaults to 0.0.	0.0

Example

Create a 2D variable and extend it to 3D:

pos_xy = Variable("pos", shape=(2,))
pos_xy.min = [-10, -10]
pos_xy.max = [10, 10]
pos_xy.append(min=0, max=100)  # Add z dimension
print(pos_xy.shape)  # (3,)
print(pos_xy.min)  # [-10., -10., 0.]
print(pos_xy.max)  # [10., 10., 100.]

Merge two variables:

pos = Variable("pos", shape=(3,))
vel = Variable("vel", shape=(3,))
pos.append(vel)  # Now pos has shape (6,)