{
"cells": [
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"tags": [
"active-ipynb",
"remove-input",
"remove-output"
]
},
"outputs": [],
"source": [
"# This cell is mandatory in all Dymos documentation notebooks.\n",
"missing_packages = []\n",
"try:\n",
" import openmdao.api as om\n",
"except ImportError:\n",
" if 'google.colab' in str(get_ipython()):\n",
" !python -m pip install openmdao[notebooks]\n",
" else:\n",
" missing_packages.append('openmdao')\n",
"try:\n",
" import dymos as dm\n",
"except ImportError:\n",
" if 'google.colab' in str(get_ipython()):\n",
" !python -m pip install dymos\n",
" else:\n",
" missing_packages.append('dymos')\n",
"try:\n",
" import pyoptsparse\n",
"except ImportError:\n",
" if 'google.colab' in str(get_ipython()):\n",
" !pip install -q condacolab\n",
" import condacolab\n",
" condacolab.install_miniconda()\n",
" !conda install -c conda-forge pyoptsparse\n",
" else:\n",
" missing_packages.append('pyoptsparse')\n",
"if missing_packages:\n",
" raise EnvironmentError('This notebook requires the following packages '\n",
" 'please install them and restart this notebook\\'s runtime: {\",\".join(missing_packages)}')"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": []
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Constraints\n",
"\n",
"Now that we've shown how to add degrees of freedom to a system with variables in the form of\n",
"time, states, and controls, we need to look at how to constrain the system. In optimal control,\n",
"constraints typically come in two flavors: boundary constraints and path constraints.\n",
"\n",
"As OpenMDAO components, outputs of Dymos Phases can be constrained using OpenMDAO's `add_constraint` method, but Dymos Phases provide their own methods to make defining these constraints somewhat simpler.\n",
"\n",
"## Boundary Constraints\n",
"\n",
"Boundary constraints are constraints on a variable value at the start or end of a phase. There\n",
"are a few different ways to impose these in Dymos, each with slightly different behavior.\n",
"\n",
"Let's consider that we want to solve for the elevation angle that results in the maximum possible\n",
"range flown by a cannonball. In this situation we have some set of initial conditions that are\n",
"fixed.\n",
"\n",
"\\begin{align}\n",
" t_0 &= 0 \\, \\mathrm{s} \\\\\n",
" x_0 &= 0 \\, \\mathrm{m} \\\\\n",
" y_0 &= 0 \\, \\mathrm{m} \\\\\n",
" v_0 &= 100 \\, \\frac{\\mathrm{m}}{\\mathrm{s}}\n",
"\\end{align}\n",
"\n",
"The first, most obvious way to constrain fixed values is to remove them from the optimization problem altogether.\n",
"\n",
"For time, this is done using the `fix_initial` or `fix_duration` arguments to `set_time_options`.\n",
"This also allows `t_initial` and `t_duration` to be provided from an external source via connection, if so desired.\n",
"\n",
"For states and controls, the situation is slightly different.\n",
"Rather than providing initial and final values, similar to the way time is handled, the implicit simulation techniques must\n",
"be provided state values at the state discretization nodes and control values at *all* nodes.\n",
"Instead, for states and controls, the user specifies `fix_initial=True` or `fix_final=True`.\n",
"\n",
"Removing constrained values from the optimization has the following pros and cons.\n",
"On the pro side, we're making the optimization problem smaller by omitting them.\n",
"On the con side, the optimizer has absolutely no freedom to move these values around even a little.\n",
"This can sometimes lead to failure modes that aren't necessarily obvious, especially to new users.\n",
"\n",
"The following example solves the brachistochrone problem by omitting the initial time and initial state, as well as the final position state from the optimization.\n",
"\n",
"The second method for bounding initial/final time, states, or controls is to leave them in the\n",
"optimization problem but to constrain only their initial or final values. For time, this is\n",
"accomplished with the options `initial_bounds` and `duration_bounds`. Each of these takes a tuple\n",
"of `(lower, upper)` values that the optimizer must obey when providing new variable values. Note\n",
"that since states and controls may be vector valued, lower and upper may themselves be iterable.\n",
"To *pin* the value of a state, time, or control to a value just set lower and upper to the same\n",
"value.\n",
"\n",
"As for the pros and cons of this technique, its largely similar to that for the first technique,\n",
"but it's somewhat optimizer dependent. Some optimizers *may* allow bounds on design variables to\n",
"be violated slightly (to some small tolerance). In theory this could alleviate some of the issues\n",
"with omitting a design variable altogether, but in practice that's unlikely.\n",
"\n",
"The first two options work by imposing bounds (or by not providing a variable to the optimizer\n",
"altogether). The third option is to pose bound constraints as actual constraints on the NLP.\n",
"This is accomplished with the `add_boundary_constraint` method on Phases.\n",
"\n",
"The downside of this technique is that it makes the NLP problem larger, though not by much. On\n",
"the plus side, this method allows the user to constrain any output within the ODE. If the user\n",
"needs to constrain an auxiliary output, this is the only option. It may also behave somewhat better\n",
"in certain circumstances. Depending on scaling, the NLP may ensure that collocation defects are\n",
"satisfied before forcing an infeasible boundary constraint to be satisfied, for instance.\n",
"\n",
"In conclusion, while using `fix_initial=True` for problems with fixed initial conditions is not a bad solution, the generality of `add_boundary_constraint`, especially for terminal constraints that risk being over-constrained, makes it a good first-choice in those situations.\n",
"In forward-shooting phases (`solve_segments='forward'`) only the initial values of the states are design variables for the optimizer.\n",
"As such, simple bounds on final state values are not possible in those situations, and `add_boundary_constraint` must be used instead.\n",
"\n",
"## Path Constraints\n",
"\n",
"The second class of constraints supported by Dymos are *path* constraints, so called because they are imposed throughout the entire phase.\n",
"Like bound constraints, path constraints can be imposed on design variables using simple bounds.\n",
"This is accomplished using the `lower` and `upper` arguments to `add_state`, `add_control`, and `add_parameter`.\n",
"(Since time is monotonically increasing or decreasing the notion of a path constraint is irrelevant for it).\n",
"\n",
"For vector-valued states and controls, lower/upper should be dimensioned the same as state or control.\n",
"If given as a scalar, it will be applied to all values in the state or control.\n",
"\n",
"```{Note}\n",
"Bounds on states in Gauss-Lobatto Phases are **not** equivalent to path constraints.\n",
"The values of states in Gauss-Lobatto phases are provided at only the state-transcription nodes and then interpolated to the collocation nodes.\n",
"Therefore, the bounds will have no impact on these interpolated values which therefore may not satisfy the bounds, as one might expect.\n",
"``` \n",
"\n",
"Phases also support the `add_path_constraint` method, which imposes path constraints as constraints in the NLP problem.\n",
"As with `add_boundary_constraint`, the `add_path_constraint` method is the only option for path constraining an output of the ODE.\n",
"\n",
"The downside of path constraints is that they add a considerable number of constraints to the NLP problem and thus may negatively impact performance, although this is generally minor for many problems.\n",
"\n",
"## Constraining Expressions\n",
"\n",
"Constraints may be defined using mathematical expressions of the form `y=f(x)` to be evaluated. Here `x` may be vector combination of time, states, controls, parameters, or any outputs of the ODE. The variable `y` is added to the timeseries outputs of the phase and the desired constraint is applied to it.\n",
"\n",
"Consider, again, the example of maximizing the range flown by a cannonball. But now, rather than a constraint on the initial velocity, we wish to apply a constraint to the initial normalized kinetic energy.\n",
"\n",
"\\begin{align}\n",
" ke &= 0.5 * v^2 \\\\\n",
" ke_0 &= 5000 \\, \\frac{\\mathrm{m^2}}{\\mathrm{s^2}}\n",
"\\end{align}\n",
"\n",
"The first way to achieve this is to add kinetic energy as a state in the model. This state may then be constrained either using `fix_initial=True` or `add_boundary_constraint(‘ke’, loc=’initial’ , equals=5000)`.\n",
"\n",
"The second method to add this constraint is to add the constraint using an expression. This may be done as `add_boundary_constraint(‘ke=0.5*v**2, loc=’initial’, equals=5000)`.\n",
"\n",
"The advantage to the latter method is that no changes are required to the previous model, simply modifying the `add_boundary_constraint` statement is sufficient. The disadvantage is that the derivatives of the constraints are evaluated using complex step rather than analytical expressions. This may negatively impact performance, but the effect should be minor for most problems.\n",
"\n",
"## Implementation Detail - Constraint Aliasing\n",
"\n",
"As of OpenMDAO Version 3.17.0, multiple constraints are allowed to exist on the same output as long as they use different indices and are provided different aliases.\n",
"In Dymos, this allows us to always apply multiple constraints (initial, final, or path constraints) to the timeseries outputs of the phase.\n",
"To allow boundary and path constraints to potentially be applied to the same timeseries outputs, they are provided the following aliases:\n",
"\n",
"An initial boundary constraint on the name `'alpha'` will be given the alias `f'{path_to_phase}.initial_boundary_constraints->alpha`. \n",
"\n",
"A final boundary constraint on the name `'alpha'` will be given the alias `f'{path_to_phase}.final_boundary_constraints->alpha`.\n",
"\n",
"A path constraint on the name `'alpha'` will be given the alias `f'{path_to_phase}.path_constraints->alpha`. \n",
"\n",
"The use of the `->` in this case is intended to remind the user that this is not the actual path to the variable being constrained.\n",
"\n",
"## Constraint Linearity\n",
"\n",
"OpenMDAO will treat all boundary and path consraints as nonlinear unless the user provides the argument `linear=True` to `add_boundary_constraint` or `add_path_constraint`.\n",
"Note that it is the responsibility of the user to understand the inner workings of Dymos and their model well enough to know if the constraint may be treated as linear.\n",
"Specifying an output that is actually a nonlinear function of the design variables as a linear constraint will almost certainly result of the failure of the optimization due to incorrect derivatives.\n",
"The derivatives of linear constraints are computed once and cached by OpenMDAO for the remainder of the optimization.\n"
]
}
],
"metadata": {
"jupytext": {
"cell_metadata_filter": "-all",
"notebook_metadata_filter": "-all",
"text_representation": {
"extension": ".md",
"format_name": "markdown"
}
},
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.9.7"
}
},
"nbformat": 4,
"nbformat_minor": 4
}