Basics¶

class
rtctools.optimization.timeseries.
Timeseries
¶ Bases:
object
Time series object, bundling time stamps with values.

__init__
(self, times, values)¶ Create a new time series object.
Parameters:  times – Iterable of time stamps.
 values – Iterable of values.

times
¶ Array of time stamps.

values
¶ Array of values.


class
rtctools.optimization.optimization_problem.
OptimizationProblem
¶ Bases:
object
Base class for all optimization problems.

bounds
(self)¶ Returns variable bounds as a dictionary mapping variable names to a pair of bounds. A bound may be a constant, or a time series.
Returns: A dictionary of variable names and (upper, lower)
bound pairs. The bounds may be numbers orTimeseries
objects.Example:
def bounds(self): return {'x': (1.0, 2.0), 'y': (2.0, 3.0)}

constant_inputs
(self, ensemble_member)¶ Returns a dictionary of constant inputs.
Parameters: ensemble_member – The ensemble member index. Returns: A dictionary of constant input names and time series.

constraints
(self, ensemble_member)¶ Returns a list of constraints for the given ensemble member.
Call
OptimizationProblem.state_at()
to return a symbol representing a model variable at a given time.Parameters: ensemble_member – The ensemble member index. Returns: A list of triples (f, m, M)
, with anMX
object representing the constraint functionf
, lower boundm
, and upper boundM
. The bounds must be numbers.Example:
def constraints(self, ensemble_member): t = 1.0 constraint1 = (2 * self.state_at('x', t, ensemble_member), 2.0, 4.0) constraint2 = (self.state_at('x', t, ensemble_member) + self.state_at('y', t, ensemble_member), 2.0, 3.0) return [constraint1, constraint2]

control
(self, variable)¶ Returns an
MX
symbol for the given control input, not bound to any time.Parameters: variable – Variable name. Returns: MX
symbol for given control input.Raises: KeyError

control_at
(self, variable, t, ensemble_member=0, scaled=False)¶ Returns an
MX
symbol representing the given control input at the given time.Parameters:  variable – Variable name.
 t – Time.
 ensemble_member – The ensemble member index.
 scaled – True to return the scaled variable.
Returns: MX
symbol representing the control input at the given time.Raises: KeyError

delayed_feedback
(self)¶ Returns the delayed feedback mappings. These are given as a list of triples \((x, y, \tau)\), to indicate that \(y = x(t  \tau)\).
Returns: A list of triples. Example:
def delayed_feedback(self): fb1 = ['x', 'y', 0.1] fb2 = ['x', 'z', 0.2] return [fb1, fb2]

der
(self, variable)¶ Returns an
MX
symbol for the time derivative given state, not bound to any time.Parameters: variable – Variable name. Returns: MX
symbol for given state.Raises: KeyError

der_at
(self, variable, t, ensemble_member=0)¶ Returns an expression for the time derivative of the specified variable at time t.
Parameters:  variable – Variable name.
 t – Time.
 ensemble_member – The ensemble member index.
Returns: MX
object representing the derivative.Raises: KeyError

ensemble_member_probability
(self, ensemble_member)¶ The probability of an ensemble member occurring.
Parameters: ensemble_member – The ensemble member index. Returns: The probability of an ensemble member occurring. Raises: IndexError

ensemble_size
¶ The number of ensemble members.

get_timeseries
(self, variable, ensemble_member=0)¶ Looks up a timeseries from the internal data store.
Parameters:  variable – Variable name.
 ensemble_member – The ensemble member index.
Returns: The requested time series.
Return type: Timeseries
Raises: KeyError

history
(self, ensemble_member)¶ Returns the state history. Uses the initial_state() method by default.
Parameters: ensemble_member – The ensemble member index. Returns: A dictionary of variable names and historical time series (up to and including t0).

initial_time
¶ The initial time in seconds.

integral
(self, variable, t0=None, tf=None, ensemble_member=0)¶ Returns an expression for the integral over the interval [t0, tf].
Parameters:  variable – Variable name.
 t0 – Left bound of interval. If equal to None, the initial time is used.
 tf – Right bound of interval. If equal to None, the final time is used.
 ensemble_member – The ensemble member index.
Returns: MX
object representing the integral.Raises: KeyError

interpolate
(self, t, ndarray ts, fs, f_left=np.nan, f_right=np.nan, mode=INTERPOLATION_LINEAR)¶ Linear interpolation over time.
Parameters:  t (float or vector of floats) – Time at which to evaluate the interpolant.
 ts (numpy array) – Time stamps.
 fs – Function values at time stamps ts.
 f_left – Function value left of leftmost time stamp.
 f_right – Function value right of rightmost time stamp.
 mode – Interpolation mode.
Returns: The interpolated value.

lookup_tables
(self, ensemble_member)¶ Returns a dictionary of lookup tables.
Parameters: ensemble_member – The ensemble member index. Returns: A dictionary of variable names and lookup tables.

objective
(self, ensemble_member)¶ The objective function for the given ensemble member.
Call
OptimizationProblem.state_at()
to return a symbol representing a model variable at a given time.Parameters: ensemble_member – The ensemble member index. Returns: An MX
object representing the objective function.Example:
def objective(self, ensemble_member): # Return value of state 'x' at final time: times = self.times() return self.state_at('x', times[1], ensemble_member)

optimize
(self, preprocessing=True, postprocessing=True, log_solver_failure_as_error=True)¶ Perform one initializetranscribesolvefinalize cycle.
Parameters:  preprocessing – True to enable a call to
pre
preceding the opimization.  postprocessing – True to enable a call to
post
following the optimization.
Returns: True on success.
 preprocessing – True to enable a call to

parameters
(self, ensemble_member)¶ Returns a dictionary of parameters.
Parameters: ensemble_member – The ensemble member index. Returns: A dictionary of parameter names and values.

path_constraints
(self, ensemble_member)¶ Returns a list of path constraints. Path constraints apply to all times and ensemble members simultaneously.
Call
OptimizationProblem.state()
to return a time and ensemblememberindependent symbol representing a model variable.Parameters: ensemble_member – The ensemble member index. This index may only be used to supply memberdependent bounds. Returns: A list of triples (f, m, M)
, with anMX
object representing the path constraint functionf
, lower boundm
, and upper boundM
. The bounds may be numbers orTimeseries
objects.Example:
def path_constraints(self, ensemble_member): # 2 * x must lie between 2 and 4 for every time instance. path_constraint1 = (2 * self.state('x'), 2.0, 4.0) # x + y must lie between 2 and 3 for every time instance path_constraint2 = (self.state('x') + self.state('y'), 2.0, 3.0) return [path_constraint1, path_constraint2]

path_objective
(self, ensemble_member)¶ Returns a path objective the given ensemble member. Path objectives apply to all times and ensemble members simultaneously.
Call
OptimizationProblem.state()
to return a time and ensemblememberindependent symbol representing a model variable.Parameters: ensemble_member – The ensemble member index. This index is currently unused, and here for future use only. Returns: A MX
object representing the path objective.Example:
def path_objective(self, ensemble_member): # Minimize x(t) for all t return self.state('x')

post
(self)¶ Postprocessing logic is performed here.

pre
(self)¶ Preprocessing logic is performed here.

seed
(self, ensemble_member)¶ Seeding data. The optimization algorithm is seeded with the data returned by this method.
Parameters: ensemble_member – The ensemble member index. Returns: A dictionary of variable names and seed time series.

set_timeseries
(self, variable, timeseries, ensemble_member=0, output=True, check_consistency=True)¶ Sets a timeseries in the internal data store.
Parameters:  variable – Variable name.
 timeseries (iterable of floats, or
Timeseries
) – Time series data.  ensemble_member – The ensemble member index.
 output – Whether to include this time series in output data files.
 check_consistency – Whether to check consistency between the time stamps on the new timeseries object and any existing time stamps.

solver_options
(self)¶ Returns a dictionary of CasADi optimization problem solver options.
The default solver for continuous problems is Ipopt. The default solver for mixed integer problems is Bonmin.
Returns: A dictionary of CasADi NlpSolver
options. See the CasADi, Ipopt, and Bonmin documentation for details.

state
(self, variable)¶ Returns an
MX
symbol for the given state, not bound to any time.Parameters: variable – Variable name. Returns: MX
symbol for given state.Raises: KeyError

state_at
(self, variable, t, ensemble_member=0, scaled=False)¶ Returns an
MX
symbol representing the given variable at the given time.Parameters:  variable – Variable name.
 t – Time.
 ensemble_member – The ensemble member index.
 scaled – True to return the scaled variable.
Returns: MX
symbol representing the state at the given time.Raises: KeyError

states_in
(self, variable, t0=None, tf=None, ensemble_member=0)¶ Iterates over symbols for states in the interval [t0, tf].
Parameters:  variable – Variable name.
 t0 – Left bound of interval. If equal to None, the initial time is used.
 tf – Right bound of interval. If equal to None, the final time is used.
 ensemble_member – The ensemble member index.
Raises: KeyError

timeseries_at
(self, variable, t, ensemble_member=0)¶ Return the value of a time series at the given time.
Parameters:  variable – Variable name.
 t – Time.
 ensemble_member – The ensemble member index.
Returns: The interpolated value of the time series.
Raises: KeyError


rtctools.util.
run_optimization_problem
(optimization_problem_class, base_folder='..', log_level=logging.INFO, profile=False, profile_casadi=False)¶ Sets up and solves an optimization problem.
This function makes the following assumptions:
 That the
base_folder
contains subfoldersinput
,output
, andmodel
, containing input data, output data, and the model, respectively.  When using
CSVLookupTableMixin
, that the base folder contains a subfolderlookup_tables
.  When using
ModelicaMixin
, that the base folder contains a subfoldermodel
.  When using
ModelicaMixin
, that the toplevel Modelica model name equals the class name.
Parameters:  optimization_problem_class – Optimization problem class to solve.
 base_folder – Base folder.
 log_level – The log level to use.
 profile – Whether or not to enable profiling.
 profile_casadi – Whether or not to enable CasADi profiling.
 That the