The Solution Object

The yapss.Solution class stores the solution to an optimal control problem. An instance of this class contains detailed information about the optimal decision variables, Lagrange multipliers, and additional data relevant to the problem.

For example, consider the Goddard rocket problem with a trajectory that includes a singular arc, requiring a three-phase solution. You can solve this problem and obtain a Solution object with the following Python code:

>>> from yapss.examples.goddard_problem_3_phase import setup
>>> problem = setup()
>>> problem.ipopt_options.print_level = 0  # Suppress output
>>> problem.ipopt_options.sb = "yes"       # Silent mode
>>> problem.ipopt_options.tol = 1e-8       # Set solver tolerance
>>> solution = problem.solve()
>>> solution
<yapss._private.solution.Solution: 'Goddard Rocket Problem with Singular Arc'>

Representation of Solution Objects

The repr() output of a Solution object confirms that it is an instance of Solution and displays the problem name.

The str() representation provides additional information, including the Ipopt status code and message (indicating the success of the optimization) and the objective value at the optimal solution:

>>> print(solution)
<yapss._private.solution.Solution> object
    Name: Goddard Rocket Problem with Singular Arc
    Ipopt Status Code: 0
    Status Message: Optimal Solution Found
    Objective Value: 18550.87...

Structure of a `Solution` Instance

The Solution object contains various attributes stored in a relatively flat structure, each representing a key element of the solution:

name (str): The name of the optimal control problem.
problem (Problem): A deep copy of the original problem definition.
objective (float): The value of the objective function at the optimal solution.
parameter (np.ndarray): An array of the optimal parameter values.
discrete (np.ndarray): An array of the discrete constraint functions, evaluated at the optimal solution.
discrete_multiplier (np.ndarray): Lagrange multipliers corresponding to the discrete constraint functions.
phase (yapss.SolutionPhases): A tuple of SolutionPhase objects, each containing information specific to a phase in the solution.
nlp_info (yapss.NLPInfo): A data class container with information returned from the Ipopt NLP solver.

Attributes of a `SolutionPhase` Instance

The phase attribute is a tuple of SolutionPhase objects, one for each phase in the optimal control problem. Each SolutionPhase object includes:

index (int): The phase index, useful for functions that further process phase solutions (e.g., plotting).
time (np.ndarray): An array of time values at interpolation points, where only the state trajectory is evaluated.
time_c (np.ndarray): An array of time values at collocation points, where dynamics and path constraints are enforced. If LGL collocation points are used, time and time_c match, simplifying post-processing.
initial_time, final_time (float): The initial and final time of the phase (time[0] and time[-1]).
duration (float): The phase duration, time[-1] - time[0].
state (np.ndarray): Optimal state values at interpolation points.
initial_state, final_state (np.ndarray): Initial and final state of the phase, state[:, 0] and state[:, -1].
control (np.ndarray): Optimal control values at collocation points.

Results of user-defined functions (dynamics, path, etc.) are stored in each SolutionPhase:

dynamics (np.ndarray): Values of the dynamics function, which represents the time derivatives of state variables, evaluated at collocation points.
path (np.ndarray): Values of the path constraint function at collocation points.
integrand (np.ndarray): Values of the integrand function, evaluated at collocation points.
integral (float): Value of the integral function at the optimal solution.

Lagrange multipliers for constraints are also stored:

costate (np.ndarray): Optimal costate values at collocation points.
path_multiplier (np.ndarray): Lagrange multipliers for the path constraint function.
duration_multiplier (float): Lagrange multiplier associated with the duration constraint.
integral_multiplier (float): Lagrange multiplier associated with the integral constraint, enforcing equality of integrals over each phase.

The Hamiltonian function, derived from dynamics, integrand, and integral multipliers, is also available:

hamiltonian (np.ndarray): Values of the Hamiltonian function, evaluated at collocation points.

Information from Ipopt Solver

The nlp_info attribute provides detailed information from the Ipopt solver, including:

ipopt_status (int): The Ipopt status code.
ipopt_status_message (str): The corresponding status message.
obj_val (float): Objective function value at the optimal solution.
x (np.ndarray): Optimal values of the NLP decision variables, combining all decision variables into a single array.
g (np.ndarray): Values of the NLP constraint functions at the optimal solution.

Lagrange multipliers associated with variable bounds and constraints:

mult_x_L, mult_x_U (np.ndarray): Lagrange multipliers for the lower and upper bounds on decision variables.
mult_g (np.ndarray): Lagrange multipliers for the NLP constraint functions.

`Solution` Class Reference

class Solution(name: str, problem: yapss.Problem, objective: float, parameter: NDArray[np.float64], parameter_multiplier: NDArray[np.float64], discrete: NDArray[np.float64], discrete_multiplier: NDArray[np.float64], phase: SolutionPhases, nlp_info: NLPInfo)[source]

Represents the solution of an optimal control problem.

A Solution object encapsulates the solution to an optimal control problem, including the optimal state, control, and parameter decision variables, the objective value, Lagrange multipliers, and related data.

Attributes:

namestr

The name of the problem being solved.

problemProblem

Deep copy of the problem definition object that includes all original user-defined settings, parameters, and configurations for the NLP problem.

objectivefloat

The optimal value of the objective function after solving the optimal control problem.

discrete_multipliernumpy.ndarray

An array of Lagrange multipliers associated with the discrete constraints.

parameternumpy.ndarray

An array of the optimal parameter values.

parameter_multipliernumpy.ndarray

An array of Lagrange multipliers associated with the parameter bounds.

phaseSolutionPhases

A sequence of SolutionPhase objects, each corresponding to a phase of the problem. Each phase contains time, state, control, and additional detailed results:

indexint: The index of the phase.
initial_timefloat: Initial time of the phase.
initial_time_multiplierfloat: Lagrange multiplier for the initial time bound.
final_timefloat: Final time of the phase.
final_time_multiplierfloat: Lagrange multiplier for the final time bound.
durationfloat: Duration of the phase.
duration_multiplierfloat: Lagrange multiplier for the duration bound.
timenumpy.ndarray: Array of interpolation time points for the phase.
time_cnumpy.ndarray: Array of collocation time points for the phase.
statenumpy.ndarray: State variable values at the interpolation time points.
controlnumpy.ndarray: Control variable values at the collocation time points.
control_multipliernumpy.ndarray: Lagrange multipliers for control variable bounds.
pathnumpy.ndarray: Path constraints values at the collocation time points.
path_multipliernumpy.ndarray: Lagrange multipliers for path constraints.
dynamicsnumpy.ndarray: Dynamics function evaluated at the collocation time points.
costatenumpy.ndarray: Costate values at the collocation time points.
integrandnumpy.ndarray: Integrand values at the collocation time points, used to evaluate the integrals used in the discrete constraints or objective function.
integralnumpy.ndarray: Array of integral values for the phase.
integral_multipliernumpy.ndarray: Lagrange multipliers for the integral constraints.
hamiltoniannumpy.ndarray: Hamiltonian values at the collocation time points.

nlp_infoNLPInfo

Information about the NLP solver status and results, including the final values of decision variables, constraint multipliers, and other information. The attributes are:

ipopt_statusint: The status code returned by Ipopt, indicating the success or failure of the optimization.
ipopt_status_messagestr: A human-readable message corresponding to the status code. In most cases, it’s the same message as that printed in the console by Ipopt.
objectivefloat: The optimal value of the objective function after solving the optimal control problem.
xnumpy.ndarray: The optimal values of the NLP decision variables.
mult_x_Lnumpy.ndarray: Lagrange multipliers associated with the lower bounds of the decision variables.
mult_x_Unumpy.ndarray: Lagrange multipliers associated with the upper bounds of the decision variables.
mult_gnumpy.ndarray: Lagrange multipliers associated with the constraints.

The Solution Object

Representation of Solution Objects

Structure of a Solution Instance

Attributes of a SolutionPhase Instance

Information from Ipopt Solver

Solution Class Reference

Structure of a `Solution` Instance

Attributes of a `SolutionPhase` Instance

`Solution` Class Reference