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 or Timeseries 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 an MX object representing the constraint function f, lower bound m, and upper bound M. 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 initialize-transcribe-solve-finalize 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.

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 ensemble-member-independent symbol representing a model variable.

Parameters:ensemble_member – The ensemble member index. This index may only be used to supply member-dependent bounds.
Returns:A list of triples (f, m, M), with an MX object representing the path constraint function f, lower bound m, and upper bound M. The bounds may be numbers or Timeseries 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 ensemble-member-independent 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:

  1. That the base_folder contains subfolders input, output, and model, containing input data, output data, and the model, respectively.
  2. When using CSVLookupTableMixin, that the base folder contains a subfolder lookup_tables.
  3. When using ModelicaMixin, that the base folder contains a subfolder model.
  4. 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.