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 - 1 + q: number of constraints
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

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 are extremely large.

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 are extremely large.
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 + m * M + q, )) – 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 + numinstance)

gradient(free)[source]¶

Returns the value of the gradient of the objective function given a solution to the problem.

Parameters: free (ndarray, (n * N + m * M + q, )) – 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 + m * M + q, 1)

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 + m * M + q, )) – A solution to the optimization problem in the canonical form.
Returns: obj_val – The value of the objective function.
Return type: float

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 + m * M + q, )) – 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

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 + m * M + q, )) – The initial guess, solution, or nay 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

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,)) – The flattened state array with n states at N time points and the q 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,)) – The flattened state array with n states at N time points and the q 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,)

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, r, N)[source]¶

Parses the free parameters vector and returns it’s components.

freendarray, shape(n * N + m * M + q): The free parameters of the system.
ninteger: The number of states.
rinteger: The number of free specified inputs.
Ninteger: 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.

API¶

direct_collocation.py¶

parameter_identification.py¶

utils.py¶

opty

Navigation

Related Topics