API¶
direct_collocation.py¶
- class opty.direct_collocation.ConstraintCollocator(equations_of_motion, state_symbols, num_collocation_nodes, node_time_interval, known_parameter_map={}, known_trajectory_map={}, instance_constraints=None, time_symbol=None, tmp_dir=None, integration_method='backward euler', parallel=False)[source]¶
This class is responsible for generating the constraint function and the sparse Jacobian of the constraint function using direct collocation methods for a non-linear programming problem where the essential constraints are defined from the equations of motion of the system.
Notes
N : number of collocation nodes
n : number of states
m : number of input trajectories
p : number of parameters
q : number of unknown input trajectories
r : number of unknown parameters
o : number of instance constraints
nN + qN + r : number of free variables
n(N - 1) + o : number of constraints
Instantiates a ConstraintCollocator object.
- Parameters
equations_of_motion (sympy.Matrix, shape(n, 1)) – A column matrix of SymPy expressions defining the right hand side of the equations of motion when the left hand side is zero, e.g. 0 = x’(t) - f(x(t), u(t), p) or 0 = f(x’(t), x(t), u(t), p). These should be in first order form but not necessairly explicit.
state_symbols (iterable) – An iterable containing all of the SymPy functions of time which represent the states in the equations of motion.
num_collocation_nodes (integer) – The number of collocation nodes, N. All known trajectory arrays should be of this length.
node_time_interval (float) – The time interval between collocation nodes.
known_parameter_map (dictionary, optional) – A dictionary that maps the SymPy symbols representing the known constant parameters to floats. Any parameters in the equations of motion not provided in this dictionary will become free optimization variables.
known_trajectory_map (dictionary, optional) – A dictionary that maps the non-state SymPy functions of time to ndarrays of floats of shape(N,). Any time varying parameters in the equations of motion not provided in this dictionary will become free trajectories optimization variables.
instance_constraints (iterable of SymPy expressions, optional) – These expressions are for constraints on the states at specific time points. They can be expressions with any state instance and any of the known parameters found in the equations of motion. All states should be evaluated at a specific instant of time. For example, the constraint x(0) = 5.0 would be specified as x(0) - 5.0 and the constraint x(0) = x(5.0) would be specified as x(0) - x(5.0). Unknown parameters and time varying parameters other than the states are currently not supported.
time_symbol (SymPy Symbol, optional) – The symbol representating time in the equations of motion. If not given, it is assumed to be the default stored in dynamicsymbols._t.
tmp_dir (string, optional) – If you want to see the generated Cython and C code for the constraint and constraint Jacobian evaluations, pass in a path to a directory here.
integration_method (string, optional) – The integration method to use, either backward euler or midpoint.
parallel (boolean, optional) – If true and openmp is installed, constraints and the Jacobian of the constraints will be executed across multiple threads. This is only useful when the equations of motion have an extremely large number of operations.
- generate_constraint_function()[source]¶
Returns a function which evaluates the constraints given the array of free optimization variables.
- generate_jacobian_function()[source]¶
Returns a function which evaluates the Jacobian of the constraints given the array of free optimization variables.
- jacobian_indices()[source]¶
Returns the row and column indices for the non-zero values in the constraint Jacobian.
- Returns
jac_row_idxs (ndarray, shape(2*n + q + r,)) – The row indices for the non-zero values in the Jacobian.
jac_col_idxs (ndarray, shape(n,)) – The column indices for the non-zero values in the Jacobian.
- class opty.direct_collocation.Problem(obj, obj_grad, *args, **kwargs)[source]¶
This class allows the user to instantiate a problem object with the essential data required to solve a direct collocation optinal control or parameter identification problem.
- Parameters
obj (function) – Returns the value of the objective function given the free vector.
obj_grad (function) – Returns the gradient of the objective function given the free vector.
equations_of_motion (sympy.Matrix, shape(n, 1)) – A column matrix of SymPy expressions defining the right hand side of the equations of motion when the left hand side is zero, e.g. 0 = x’(t) - f(x(t), u(t), p) or 0 = f(x’(t), x(t), u(t), p). These should be in first order form but not necessairly explicit.
state_symbols (iterable) – An iterable containing all of the SymPy functions of time which represent the states in the equations of motion.
num_collocation_nodes (integer) – The number of collocation nodes, N. All known trajectory arrays should be of this length.
node_time_interval (float) – The time interval between collocation nodes.
known_parameter_map (dictionary, optional) – A dictionary that maps the SymPy symbols representing the known constant parameters to floats. Any parameters in the equations of motion not provided in this dictionary will become free optimization variables.
known_trajectory_map (dictionary, optional) – A dictionary that maps the non-state SymPy functions of time to ndarrays of floats of shape(N,). Any time varying parameters in the equations of motion not provided in this dictionary will become free trajectories optimization variables.
instance_constraints (iterable of SymPy expressions, optional) – These expressions are for constraints on the states at specific time points. They can be expressions with any state instance and any of the known parameters found in the equations of motion. All states should be evaluated at a specific instant of time. For example, the constraint x(0) = 5.0 would be specified as x(0) - 5.0 and the constraint x(0) = x(5.0) would be specified as x(0) - x(5.0). Unknown parameters and time varying parameters other than the states are currently not supported.
time_symbol (SymPy Symbol, optional) – The symbol representating time in the equations of motion. If not given, it is assumed to be the default stored in dynamicsymbols._t.
tmp_dir (string, optional) – If you want to see the generated Cython and C code for the constraint and constraint Jacobian evaluations, pass in a path to a directory here.
integration_method (string, optional) – The integration method to use, either backward euler or midpoint.
parallel (boolean, optional) – If true and openmp is installed, constraints and the Jacobian of the constraints will be executed across multiple threads. This is only useful when the equations of motion have an extremely large number of operations.
bounds (dictionary, optional) – This dictionary should contain a mapping from any of the symbolic states, unknown trajectories, or unknown parameters to a 2-tuple of floats, the first being the lower bound and the second the upper bound for that free variable, e.g.
{x(t): (-1.0, 5.0)}
.
- addOption()¶
Add a keyword/value option pair to the problem. See the Ipopt documentaion for details on available options.
- Parameters
keyword (string) – Option name.
val (string, int, or float) – Value of the option. The type of val should match the option definition as described in the Ipopt documentation.
- Returns
- Return type
None
- close()¶
Deallcate memory resources used by the Ipopt package. Called implicitly by the ‘problem’ class destructor.
- Parameters
None –
- Returns
- Return type
None
- constraints(free)[source]¶
Returns the value of the constraint functions given a solution to the problem.
- Parameters
free (ndarray, (n*N + q*N + r, )) – A solution to the optimization problem in the canonical form.
- Returns
constraints_val – The value of the constraint function.
- Return type
ndarray, shape(n*(N - 1) + o)
Notes
N : number of collocation nodes
n : number of unknown state trajectories
q : number of unknown input trajectories
r : number of unknown parameters
o : number of instance constraints
- gradient(free)[source]¶
Returns the value of the gradient of the objective function given a solution to the problem.
- Parameters
free (ndarray, (n*N + q*N + r, )) – A solution to the optimization problem in the canonical form.
- Returns
gradient_val – The value of the gradient of the objective function.
- Return type
ndarray, shape(n*N + q*N + r, 1)
Notes
N : number of collocation nodes
n : number of unknown state trajectories
q : number of unknown input trajectories
r : number of unknown parameters
- intermediate(*args)[source]¶
This method is called at every optimization iteration. Not for pubic use.
- jacobian(free)[source]¶
Returns the non-zero values of the Jacobian of the constraint function.
- Returns
- Return type
jac_vals = ndarray, shape()
- jacobianstructure()[source]¶
Returns the sparsity structur of the Jacobian of the constraint function.
- Returns
jac_row_idxs (ndarray, shape(2*n + q + r,)) – The row indices for the non-zero values in the Jacobian.
jac_col_idxs (ndarray, shape(n,)) – The column indices for the non-zero values in the Jacobian.
- objective(free)[source]¶
Returns the value of the objective function given a solution to the problem.
- Parameters
free (ndarray, (n*N + q*N + r, )) – A solution to the optimization problem in the canonical form.
- Returns
obj_val – The value of the objective function.
- Return type
float
Notes
N : number of collocation nodes
n : number of unknown state trajectories
q : number of unknown input trajectories
r : number of unknown parameters
- plot_constraint_violations(vector)[source]¶
Returns an axis with the state constraint violations plotted versus node number and the instance constraints as a bar graph.
- Parameters
vector (ndarray, (n*N + q*N + r, )) – The initial guess, solution, or any other vector that is in the canonical form.
- Returns
axes – A matplotlib axes with the constraint violations plotted.
- Return type
ndarray of AxesSubplot
Notes
N : number of collocation nodes
n : number of unknown state trajectories
q : number of unknown input trajectories
r : number of unknown parameters
- plot_objective_value()[source]¶
Returns an axis with the objective value plotted versus the optimization iteration. solve() must be run first.
- plot_trajectories(vector, axes=None)[source]¶
Returns the axes for two plots. The first plot displays the state trajectories versuse time and the second plot displays the input trjaectories versus time.
- Parameters
vector (ndarray, (n*N + q*N + r, )) – The initial guess, solution, or any other vector that is in the canonical form.
axes (ndarray of AxesSubplot, shape(n + m, )) – An array of matplotlib axes to plot to.
- Returns
axes – A matplotlib axes with the state and input trajectories plotted.
- Return type
ndarray of AxesSubplot
Notes
N : number of collocation nodes
n : number of unknown state trajectories
m : number of input trajectories
q : number of unknown input trajectories
r : number of unknown parameters
- setProblemScaling()¶
Optional function for setting scaling parameters for the problem. To use the scaling parameters set the option ‘nlp_scaling_method’ to ‘user-scaling’.
- Parameters
obj_scaling (float) – Determines, how Ipopt should internally scale the objective function. For example, if this number is chosen to be 10, then Ipopt solves internally an optimization problem that has 10 times the value of the original objective. In particular, if this value is negative, then Ipopt will maximize the objective function instead of minimizing it.
x_scaling (array-like, shape(n, )) – The scaling factors for the variables. If None, no scaling is done.
g_scaling (array-like, shape(m, )) – The scaling factors for the constrains. If None, no scaling is done.
- Returns
- Return type
None
- solve()¶
Returns the optimal solution and an info dictionary. Solves the posed optimization problem starting at point x.
- Parameters
x (array-like, shape(n, )) – Initial guess.
- Returns
x (array, shape(n, )) – Optimal solution.
info (dictionary) –
- ‘x’: ndarray, shape(n, )
optimal solution
- ’g’: ndarray, shape(m, )
constraints at the optimal solution
- ’obj_val’: float
objective value at optimal solution
- ’mult_g’: ndarray, shape(m, )
final values of the constraint multipliers
- ’mult_x_L’: ndarray, shape(n, )
bound multipliers at the solution
- ’mult_x_U’: ndarray, shape(n, )
bound multipliers at the solution
- ’status’: integer
gives the status of the algorithm
- ’status_msg’: string
gives the status of the algorithm as a message
parameter_identification.py¶
- opty.parameter_identification.objective_function(free, num_dis_points, num_states, dis_period, time_measured, y_measured)[source]¶
Returns the norm of the difference in the measured and simulated output.
- Parameters
free (ndarray, shape(n*N + q*N + r,)) – The flattened state array with n states at N time points, q input trajectories and N time points, and the r free model constants.
num_dis_points (integer) – The number of model discretization points.
num_states (integer) – The number of system states.
dis_period (float) – The discretization time interval.
y_measured (ndarray, shape(M, o)) – The measured trajectories of the o output variables at each sampled time instance.
- Returns
cost – The cost value.
- Return type
float
Notes
This assumes that the states are ordered:
[coord1, …, coordn, speed1, …, speedn]
y_measured is interpolated at the discretization time points and compared to the model output at the discretization time points.
- opty.parameter_identification.objective_function_gradient(free, num_dis_points, num_states, dis_period, time_measured, y_measured)[source]¶
Returns the gradient of the objective function with respect to the free parameters.
- Parameters
free (ndarray, shape(n*N + q*N + r,)) – The flattened state array with n states at N time points, q input trajectories and N time points, and the r free model constants.
num_dis_points (integer) – The number of model discretization points.
num_states (integer) – The number of system states.
dis_period (float) – The discretization time interval.
y_measured (ndarray, shape(M, o)) – The measured trajectories of the o output variables at each sampled time instance.
- Returns
gradient – The gradient of the cost function with respect to the free parameters.
- Return type
ndarray, shape(n*N + q*N + r,)
Warning
This is currently only valid if the model outputs (and measurements) are simply the states. The chain rule will be needed if the function output_equations() is more than a simple selection.
- opty.parameter_identification.output_equations(x)[source]¶
Returns the outputs of the system. For now just the an array of the generalized coordinates.
- Parameters
x (ndarray, shape(N, n)) – The trajectories of the system states.
- Returns
y – The trajectories of the generalized coordinates.
- Return type
ndarray, shape(N, o)
Notes
The order of the states is assumed to be:
[coord_1, …, coord_{n/2}, speed_1, …, speed_{n/2}]
[q_1, …, q_{n/2}, u_1, …., u_{n/2}]
As this is what generate_ode_function creates.
utils.py¶
- opty.utils.controllable(a, b)[source]¶
Returns true if the system is controllable and false if not.
- Parameters
a (array_like, shape(n,n)) – The state matrix.
b (array_like, shape(n,r)) – The input matrix.
- Returns
controllable
- Return type
boolean
- opty.utils.f_minus_ma(mass_matrix, forcing_vector, states)[source]¶
Returns Fr + Fr* from the mass_matrix and forcing vector.
- opty.utils.openmp_installed()[source]¶
Returns true if openmp is installed, false if not.
Modified from: https://stackoverflow.com/questions/16549893/programatically-testing-for-openmp-support-from-a-python-setup-script
- opty.utils.parse_free(free, n, q, N)[source]¶
Parses the free parameters vector and returns it’s components.
- Parameters
free (ndarray, shape(n*N + q*N + r)) – The free parameters of the system.
n (integer) – The number of states.
q (integer) – The number of free specified inputs.
N (integer) – The number of time steps.
- Returns
states (ndarray, shape(n, N)) – The array of n states through N time steps.
specified_values (ndarray, shape(r, N) or shape(N,), or None) – The array of r specified inputs through N time steps.
constant_values (ndarray, shape(q,)) – The array of q constants.
- opty.utils.state_derivatives(states)[source]¶
Returns functions of time which represent the time derivatives of the states.
- opty.utils.substitute_matrix(matrix, row_idxs, col_idxs, sub_matrix)[source]¶
Returns the matrix with the values given by the row and column indices with those in the sub-matrix.
- Parameters
matrix (ndarray, shape(n, m)) – A matrix (i.e. 2D array).
row_idxs (array_like, shape(p<=n,)) – The row indices which designate which entries should be replaced by the sub matrix entries.
col_idxs (array_like, shape(q<=m,)) – The column indices which designate which entries should be replaced by the sub matrix entries.
sub_matrix (ndarray, shape(p, q)) – A matrix of values to substitute into the specified rows and columns.
Notes
This makes a copy of the sub_matrix, so if it is large it may be slower than a more optimal implementation.
Examples
>>> a = np.zeros((3, 4)) >>> sub = np.arange(4).reshape((2, 2)) >>> substitute_matrix(a, [1, 2], [0, 2], sub) array([[ 0., 0., 0., 0.], [ 0., 0., 1., 0.], [ 2., 0., 3., 0.]])
- opty.utils.sum_of_sines(sigma, frequencies, time)[source]¶
Returns a sum of sines centered at zero along with its first and second derivatives.
- Parameters
sigma (float) – The desired standard deviation of the series.
frequencies (iterable of floats) – The frequencies of the sin curves to be included in the sum.
time (array_like, shape(n,)) – The montonically increasing time vector.
- Returns
sines (ndarray, shape(n,)) – A sum of sines.
sines_prime (ndarray, shape(n,)) – The first derivative of the sum of sines.
sines_double_prime (ndarray, shape(n,)) – The second derivative of the sum of sines.
- opty.utils.ufuncify_matrix(args, expr, const=None, tmp_dir=None, parallel=False)[source]¶
Returns a function that evaluates a matrix of expressions in a tight loop.
- Parameters
args (iterable of sympy.Symbol) – A list of all symbols in expr in the desired order for the output function.
expr (sympy.Matrix) – A matrix of expressions.
const (tuple, optional) – This should include any of the symbols in args that should be constant with respect to the loop.
tmp_dir (string, optional) – The path to a directory in which to store the generated files. If None then the files will be not be retained after the function is compiled.
parallel (boolean, optional) – If True and openmp is installed, the generated code will be parallelized across threads. This is only useful when expr are extremely large.