/*
* Copyright (c) 2016 Frank Fischer <frank-fischer@shadow-soft.de>
*
* This program is free software: you can redistribute it and/or
* modify it under the terms of the GNU General Public License as
* published by the Free Software Foundation, either version 3 of the
* License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>
*/
use {Real, DVector, Minorant};
use std::error;
use std::result;
/**
* Trait for master problems without box constraints.
*
* Implementors of this trait are supposed to solve quadratic
* optimization problems of the form
*
* \\[ \min \left\\{ \hat{f}(d) + \frac{u}{2} \\| d \\|\^2 \colon d \in \mathbb{R}\^n \right\\}. \\]
*
* where $\hat{f}$ is a piecewise linear model, i.e.
*
* \\[ \hat{f}(d) = \max \\{ \ell_i(d) = c_i + \langle g_i, d \rangle \colon i=1,\dotsc,k \\} = \max \left\\{ \sum_{i=1}\^k \alpha_i \ell_i(d) \colon \alpha \in \Delta \right\\}, \\]
*
* where $\Delta := \left\\{ \alpha \in \mathbb{R}\^k \colon \sum_{i=1}\^k
* \alpha_i = 1 \right\\}$. Note, the unconstrained solver is expected
* to compute *dual* optimal solutions, i.e. the solver must compute
* optimal coefficients $\bar{\alpha}$ for the dual problem
*
* \\[ \max_{\alpha \in \Delta} \min_{d \in \mathbb{R}\^n} \sum_{i=1}\^k \alpha_i \ell_i(d) + \frac{u}{2} \\| d \\|\^2. \\]
*/
pub trait UnconstrainedMasterProblem {
/// Error type.
type Error : error::Error + 'static;
/// Unique index for a minorant.
type MinorantIndex : Copy + Eq;
/// Return a new instance of the unconstrained master problem.
fn new() -> result::Result<Self, Self::Error>
where Self: Sized;
/// Return the number of subproblems.
fn num_subproblems(&self) -> usize;
/// Set the number of subproblems (different function models.)
fn set_num_subproblems(&mut self, n: usize) -> result::Result<(), Self::Error>;
/// Return the current weight.
fn weight(&self) -> Real;
/// Set the weight of the quadratic term, must be > 0.
fn set_weight(&mut self, weight: Real);
/// Return the number of minorants of subproblem `fidx`.
fn num_minorants(&self, fidx: usize) -> usize;
/// Add a new minorant to the model.
fn add_minorant(&mut self, fidx: usize, minorant: Minorant) -> result::Result<Self::MinorantIndex, Self::Error>;
/// Solve the master problem.
fn solve(&mut self, eta: &DVector, fbound: Real, augbound: Real, relprec: Real) -> result::Result<(), Self::Error>;
/// Return the current dual optimal solution.
fn dualopt(&self) -> &DVector;
/// Return the current dual optimal solution value.
fn dualopt_cutval(&self) -> Real;
/// Return the multiplier associated with a minorant.
fn multiplier(&self, min : Self::MinorantIndex) -> Real;
/// Return the value of the current model at the given point.
fn eval_model(&self, y: &DVector) -> Real;
/// Aggregate the given minorants according to the current solution.
///
/// The (indices of the) minorants to be aggregated get invalid
/// after this operation. The function returns the index of the
/// aggregated minorant along with the coefficients of the convex
/// combination. The index of the new aggregated minorant might or
/// might not be one of indices of the original minorants.
///
/// # Error
/// The indices of the minorants `mins` must belong to subproblem `fidx`.
fn aggregate(&mut self, fidx: usize, mins: &[usize]) -> Result<(Self::MinorantIndex, DVector), Self::Error>;
/// Move the center of the master problem along $\alpha \cdot d$.
fn move_center(&mut self, alpha: Real, d: &DVector);
}