/*
 *  JavaSMT is an API wrapper for a collection of SMT solvers.
 *  This file is part of JavaSMT.
 *
 *  Copyright (C) 2007-2016  Dirk Beyer
 *  All rights reserved.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package org.sosy_lab.java_smt.api;

import java.util.Optional;
import org.sosy_lab.common.rationals.Rational;

/** Interface for optimization modulo SMT. */
public interface OptimizationProverEnvironment extends BasicProverEnvironment<Void>, AutoCloseable {

  /**
   * Add the maximization <code>objective</code>.
   *
   * <p><b>Note: {@code push/pop} may be used for switching objectives</b>
   *
   * @return Objective handle, to be used for retrieving the value.
   */
  int maximize(Formula objective);

  /**
   * Add minimization <code>objective</code>.
   *
   * <p><b>Note: {@code push/pop} may be used for switching objectives</b>
   *
   * @return Objective handle, to be used for retrieving the value.
   */
  int minimize(Formula objective);

  /**
   * Optimize the objective function subject to the previously imposed constraints.
   *
   * @return Status of the optimization problem.
   */
  OptStatus check() throws InterruptedException, SolverException;

  /**
   * @param epsilon Value to substitute for the {@code epsilon}.
   * @return Upper approximation of the optimized value, or absent optional if the objective is
   *     unbounded.
   */
  Optional<Rational> upper(int handle, Rational epsilon);

  /**
   * @param epsilon Value to substitute for the {@code epsilon}.
   * @return Lower approximation of the optimized value, or absent optional if the objective is
   *     unbounded.
   */
  Optional<Rational> lower(int handle, Rational epsilon);

  /** Status of the optimization problem. */
  enum OptStatus {

    /** The solution was found (may be unbounded). */
    OPT,

    /** The set of constraints is unsatisfiable. */
    UNSAT,

    /** The result is unknown. */
    UNDEF
  }
}

@@ -2206,24 +2206,829 @@
  epsilon);%0A%0A
+  /**%0A   * %7B@inheritDoc%7D%0A   *%0A   * %3Cp%3EPlease note that the prover is allowed to use standard numbers for any real variable in the%0A   * model after a sat-query returned %7B@link OptStatus#OPT%7D. For integer formulas, we expect the%0A   * optimal assignment.%0A   *%0A   * %3Cp%3E%3Cb%3EExample 1%3C/b%3E: For the constraint 'x%3C10' with a real x, the upper bound of x is%0A   * '10-epsilon' (epsilon can even be set to zero). The model can return the assignment x=9. To get%0A   * an optimal assignment, query the solver with an additional constraint 'x == 10-epsilon'.%0A   *%0A   * %3Cp%3E%3Cb%3EExample 2%3C/b%3E: For the constraint 'x%3C10' with a integer x, the upper bound of x is '9'%0A   * (epsilon is irrelevant here and can be zero). The model returns the optimal assignment x=9.%0A   */%0A  @Override%0A  Model getModel() throws SolverException;%0A%0A
   /** Status

improve documentation.