cp_model.h

Go to the documentation of this file.

// Copyright 2010-2021 Google LLC
// 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.

#ifndef OR_TOOLS_SAT_CP_MODEL_H_
#define OR_TOOLS_SAT_CP_MODEL_H_

#include <cstdint>
#include <initializer_list>
#include <limits>
#include <string>
#include <utility>

#include "absl/container/flat_hash_map.h"
#include "absl/types/span.h"
#include "ortools/sat/cp_model.pb.h"
#include "ortools/sat/cp_model_solver.h"
#include "ortools/sat/cp_model_utils.h"
#include "ortools/sat/model.h"
#include "ortools/sat/sat_parameters.pb.h"
#include "ortools/util/sorted_interval_list.h"

namespace operations_research {
namespace sat {

class CpModelBuilder;
class LinearExpr;
class IntVar;

class BoolVar {
 public:
  BoolVar();

  BoolVar WithName(const std::string& name);

  std::string Name() const;

  BoolVar Not() const { return BoolVar(NegatedRef(index_), builder_); }

  bool operator==(const BoolVar& other) const {
    return other.builder_ == builder_ && other.index_ == index_;
  }

  bool operator!=(const BoolVar& other) const {
    return other.builder_ != builder_ || other.index_ != index_;
  }

  std::string DebugString() const;

  int index() const { return index_; }

 private:
  friend class CircuitConstraint;
  friend class Constraint;
  friend class CpModelBuilder;
  friend class DoubleLinearExpr;
  friend class IntVar;
  friend class IntervalVar;
  friend class MultipleCircuitConstraint;
  friend class LinearExpr;
  friend class ReservoirConstraint;
  friend bool SolutionBooleanValue(const CpSolverResponse& r, BoolVar x);

  BoolVar(int index, CpModelBuilder* builder);

  CpModelBuilder* builder_ = nullptr;
  int index_ = std::numeric_limits<int32_t>::min();
};

std::ostream& operator<<(std::ostream& os, const BoolVar& var);

BoolVar Not(BoolVar x);

class IntVar {
 public:
  IntVar();

  explicit IntVar(const BoolVar& var);

  BoolVar ToBoolVar() const;

  IntVar WithName(const std::string& name);

  std::string Name() const;

  bool operator==(const IntVar& other) const {
    return other.builder_ == builder_ && other.index_ == index_;
  }

  bool operator!=(const IntVar& other) const {
    return other.builder_ != builder_ || other.index_ != index_;
  }

  // Returns the domain of the variable.
  // Note that we keep the fully qualified return type as compilation fails with
  // gcc otherwise.
  ::operations_research::Domain Domain() const;

  std::string DebugString() const;

  int index() const { return index_; }

 private:
  friend class BoolVar;
  friend class CpModelBuilder;
  friend class CumulativeConstraint;
  friend class DoubleLinearExpr;
  friend class LinearExpr;
  friend class IntervalVar;
  friend class ReservoirConstraint;
  friend int64_t SolutionIntegerValue(const CpSolverResponse& r,
                                      const LinearExpr& expr);

  IntVar(int index, CpModelBuilder* builder);

  CpModelBuilder* builder_ = nullptr;
  int index_ = std::numeric_limits<int32_t>::min();
};

std::ostream& operator<<(std::ostream& os, const IntVar& var);

class LinearExpr {
 public:
  LinearExpr() = default;

  // NOLINTBEGIN(google-explicit-constructor)

  LinearExpr(BoolVar var);

  LinearExpr(IntVar var);

  LinearExpr(int64_t constant);

  // NOLINTEND(google-explicit-constructor)

  static LinearExpr Sum(absl::Span<const IntVar> vars);

  static LinearExpr Sum(absl::Span<const BoolVar> vars);

  static LinearExpr WeightedSum(absl::Span<const IntVar> vars,
                                absl::Span<const int64_t> coeffs);

  static LinearExpr WeightedSum(absl::Span<const BoolVar> vars,
                                absl::Span<const int64_t> coeffs);

  static LinearExpr Term(IntVar var, int64_t coefficient);

  static LinearExpr Term(BoolVar var, int64_t coefficient);

  static LinearExpr FromProto(const LinearExpressionProto& proto);

  // Operators.
  LinearExpr& operator+=(const LinearExpr& other);
  LinearExpr& operator-=(const LinearExpr& other);
  LinearExpr& operator*=(int64_t factor);

  const std::vector<int>& variables() const { return variables_; }

  const std::vector<int64_t>& coefficients() const { return coefficients_; }

  const bool IsConstant() const { return variables_.empty(); }

  int64_t constant() const { return constant_; }

  std::string DebugString(const CpModelProto* proto = nullptr) const;

 private:
  std::vector<int> variables_;
  std::vector<int64_t> coefficients_;
  int64_t constant_ = 0;
};

std::ostream& operator<<(std::ostream& os, const LinearExpr& e);

class DoubleLinearExpr {
 public:
  DoubleLinearExpr();

  explicit DoubleLinearExpr(BoolVar var);

  explicit DoubleLinearExpr(IntVar var);

  explicit DoubleLinearExpr(double constant);

  DoubleLinearExpr& operator+=(double value);

  DoubleLinearExpr& operator+=(IntVar var);
  DoubleLinearExpr& operator+=(BoolVar var);

  DoubleLinearExpr& operator+=(const DoubleLinearExpr& expr);

  DoubleLinearExpr& AddTerm(IntVar var, double coeff);
  DoubleLinearExpr& AddTerm(BoolVar var, double coeff);

  DoubleLinearExpr& operator-=(double value);

  DoubleLinearExpr& operator-=(IntVar var);

  DoubleLinearExpr& operator-=(const DoubleLinearExpr& expr);

  DoubleLinearExpr& operator*=(double coeff);

  static DoubleLinearExpr Sum(absl::Span<const IntVar> vars);

  static DoubleLinearExpr Sum(absl::Span<const BoolVar> vars);

  static DoubleLinearExpr WeightedSum(absl::Span<const IntVar> vars,
                                      absl::Span<const double> coeffs);

  static DoubleLinearExpr WeightedSum(absl::Span<const BoolVar> vars,
                                      absl::Span<const double> coeffs);

  const std::vector<int>& variables() const { return variables_; }

  const std::vector<double>& coefficients() const { return coefficients_; }

  // Returns true if the expression has no variable.
  const bool IsConstant() const { return variables_.empty(); }

  double constant() const { return constant_; }

  std::string DebugString(const CpModelProto* proto = nullptr) const;

 private:
  std::vector<int> variables_;
  std::vector<double> coefficients_;
  double constant_ = 0;
};

std::ostream& operator<<(std::ostream& os, const DoubleLinearExpr& e);

class IntervalVar {
 public:
  IntervalVar();

  IntervalVar WithName(const std::string& name);

  std::string Name() const;

  LinearExpr StartExpr() const;

  LinearExpr SizeExpr() const;

  LinearExpr EndExpr() const;

  BoolVar PresenceBoolVar() const;

  bool operator==(const IntervalVar& other) const {
    return other.builder_ == builder_ && other.index_ == index_;
  }

  bool operator!=(const IntervalVar& other) const {
    return other.builder_ != builder_ || other.index_ != index_;
  }

  std::string DebugString() const;

  int index() const { return index_; }

 private:
  friend class CpModelBuilder;
  friend class CumulativeConstraint;
  friend class NoOverlap2DConstraint;
  friend std::ostream& operator<<(std::ostream& os, const IntervalVar& var);

  IntervalVar(int index, CpModelBuilder* builder);

  CpModelBuilder* builder_ = nullptr;
  int index_ = std::numeric_limits<int32_t>::min();
};

std::ostream& operator<<(std::ostream& os, const IntervalVar& var);

class Constraint {
 public:
  Constraint OnlyEnforceIf(absl::Span<const BoolVar> literals);

  Constraint OnlyEnforceIf(BoolVar literal);

  Constraint WithName(const std::string& name);

  const std::string& Name() const;

  const ConstraintProto& Proto() const { return *proto_; }

  ConstraintProto* MutableProto() const { return proto_; }

 protected:
  friend class CpModelBuilder;

  explicit Constraint(ConstraintProto* proto);

  ConstraintProto* proto_ = nullptr;
};

class CircuitConstraint : public Constraint {
 public:
  void AddArc(int tail, int head, BoolVar literal);

 private:
  friend class CpModelBuilder;

  using Constraint::Constraint;
};

class MultipleCircuitConstraint : public Constraint {
 public:
  void AddArc(int tail, int head, BoolVar literal);

 private:
  friend class CpModelBuilder;

  using Constraint::Constraint;
};

class TableConstraint : public Constraint {
 public:
  void AddTuple(absl::Span<const int64_t> tuple);

 private:
  friend class CpModelBuilder;

  using Constraint::Constraint;
};

class ReservoirConstraint : public Constraint {
 public:
  void AddEvent(LinearExpr time, int64_t level_change);

  void AddOptionalEvent(LinearExpr time, int64_t level_change,
                        BoolVar is_active);

 private:
  friend class CpModelBuilder;

  ReservoirConstraint(ConstraintProto* proto, CpModelBuilder* builder);

  CpModelBuilder* builder_;
};

class AutomatonConstraint : public Constraint {
 public:
  void AddTransition(int tail, int head, int64_t transition_label);

 private:
  friend class CpModelBuilder;

  using Constraint::Constraint;
};

class NoOverlap2DConstraint : public Constraint {
 public:
  void AddRectangle(IntervalVar x_coordinate, IntervalVar y_coordinate);

 private:
  friend class CpModelBuilder;

  using Constraint::Constraint;
};

class CumulativeConstraint : public Constraint {
 public:
  void AddDemand(IntervalVar interval, LinearExpr demand);

 private:
  friend class CpModelBuilder;

  CumulativeConstraint(ConstraintProto* proto, CpModelBuilder* builder);

  CpModelBuilder* builder_;
};

class CpModelBuilder {
 public:
  void SetName(const std::string& name);

  IntVar NewIntVar(const Domain& domain);

  BoolVar NewBoolVar();

  IntVar NewConstant(int64_t value);

  BoolVar TrueVar();

  BoolVar FalseVar();

  IntervalVar NewIntervalVar(const LinearExpr& start, const LinearExpr& size,
                             const LinearExpr& end);

  IntervalVar NewFixedSizeIntervalVar(const LinearExpr& start, int64_t size);

  IntervalVar NewOptionalIntervalVar(const LinearExpr& start,
                                     const LinearExpr& size,
                                     const LinearExpr& end, BoolVar presence);

  IntervalVar NewOptionalFixedSizeIntervalVar(const LinearExpr& start,
                                              int64_t size, BoolVar presence);

  Constraint AddBoolOr(absl::Span<const BoolVar> literals);

  Constraint AddAtLeastOne(absl::Span<const BoolVar> literals);

  Constraint AddAtMostOne(absl::Span<const BoolVar> literals);

  Constraint AddExactlyOne(absl::Span<const BoolVar> literals);

  Constraint AddBoolAnd(absl::Span<const BoolVar> literals);

  Constraint AddBoolXor(absl::Span<const BoolVar> literals);

  Constraint AddImplication(BoolVar a, BoolVar b) {
    return AddBoolOr({a.Not(), b});
  }

  Constraint AddEquality(const LinearExpr& left, const LinearExpr& right);

  Constraint AddGreaterOrEqual(const LinearExpr& left, const LinearExpr& right);

  Constraint AddGreaterThan(const LinearExpr& left, const LinearExpr& right);

  Constraint AddLessOrEqual(const LinearExpr& left, const LinearExpr& right);

  Constraint AddLessThan(const LinearExpr& left, const LinearExpr& right);

  Constraint AddLinearConstraint(const LinearExpr& expr, const Domain& domain);

  Constraint AddNotEqual(const LinearExpr& left, const LinearExpr& right);

  Constraint AddAllDifferent(absl::Span<const IntVar> vars);

  Constraint AddAllDifferent(absl::Span<const LinearExpr> exprs);

  Constraint AddAllDifferent(std::initializer_list<LinearExpr> exprs);

  Constraint AddVariableElement(IntVar index,
                                absl::Span<const IntVar> variables,
                                IntVar target);

  Constraint AddElement(IntVar index, absl::Span<const int64_t> values,
                        IntVar target);

  CircuitConstraint AddCircuitConstraint();

  MultipleCircuitConstraint AddMultipleCircuitConstraint();

  TableConstraint AddAllowedAssignments(absl::Span<const IntVar> vars);

  TableConstraint AddForbiddenAssignments(absl::Span<const IntVar> vars);

  Constraint AddInverseConstraint(absl::Span<const IntVar> variables,
                                  absl::Span<const IntVar> inverse_variables);

  ReservoirConstraint AddReservoirConstraint(int64_t min_level,
                                             int64_t max_level);

  AutomatonConstraint AddAutomaton(
      absl::Span<const IntVar> transition_variables, int starting_state,
      absl::Span<const int> final_states);

  Constraint AddMinEquality(const LinearExpr& target,
                            absl::Span<const IntVar> vars);

  Constraint AddMinEquality(const LinearExpr& target,
                            absl::Span<const LinearExpr> exprs);

  Constraint AddMinEquality(const LinearExpr& target,
                            std::initializer_list<LinearExpr> exprs);

  Constraint AddMaxEquality(const LinearExpr& target,
                            absl::Span<const IntVar> vars);

  Constraint AddMaxEquality(const LinearExpr& target,
                            absl::Span<const LinearExpr> exprs);

  Constraint AddMaxEquality(const LinearExpr& target,
                            std::initializer_list<LinearExpr> exprs);

  Constraint AddDivisionEquality(const LinearExpr& target,
                                 const LinearExpr& numerator,
                                 const LinearExpr& denominator);

  Constraint AddAbsEquality(const LinearExpr& target, const LinearExpr& expr);

  Constraint AddModuloEquality(const LinearExpr& target, const LinearExpr& var,
                               const LinearExpr& mod);

  Constraint AddMultiplicationEquality(const LinearExpr& target,
                                       absl::Span<const LinearExpr> exprs);

  Constraint AddMultiplicationEquality(const LinearExpr& target,
                                       absl::Span<const IntVar> vars);

  Constraint AddMultiplicationEquality(const LinearExpr& target,
                                       std::initializer_list<LinearExpr> exprs);

  Constraint AddMultiplicationEquality(const LinearExpr& target,
                                       const LinearExpr& left,
                                       const LinearExpr& right);

  Constraint AddNoOverlap(absl::Span<const IntervalVar> vars);

  NoOverlap2DConstraint AddNoOverlap2D();

  CumulativeConstraint AddCumulative(LinearExpr capacity);

  void Minimize(const LinearExpr& expr);

  void Minimize(const DoubleLinearExpr& expr);

  void Maximize(const LinearExpr& expr);

  void Maximize(const DoubleLinearExpr& expr);

  void AddDecisionStrategy(
      absl::Span<const IntVar> variables,
      DecisionStrategyProto::VariableSelectionStrategy var_strategy,
      DecisionStrategyProto::DomainReductionStrategy domain_strategy);

  void AddDecisionStrategy(
      absl::Span<const BoolVar> variables,
      DecisionStrategyProto::VariableSelectionStrategy var_strategy,
      DecisionStrategyProto::DomainReductionStrategy domain_strategy);

  void AddHint(IntVar var, int64_t value);

  void AddHint(BoolVar var, bool value);

  void ClearHints();

  void AddAssumption(BoolVar lit);

  void AddAssumptions(absl::Span<const BoolVar> literals);

  void ClearAssumptions();

  const CpModelProto& Build() const { return Proto(); }

  const CpModelProto& Proto() const { return cp_model_; }
  CpModelProto* MutableProto() { return &cp_model_; }

  void CopyFrom(const CpModelProto& model_proto);

  BoolVar GetBoolVarFromProtoIndex(int index);

  IntVar GetIntVarFromProtoIndex(int index);

  IntervalVar GetIntervalVarFromProtoIndex(int index);

 private:
  friend class CumulativeConstraint;
  friend class ReservoirConstraint;
  friend class IntervalVar;
  friend class IntVar;

  // Fills the 'expr_proto' with the linear expression represented by 'expr'.
  LinearExpressionProto LinearExprToProto(const LinearExpr& expr,
                                          bool negate = false);

  // Returns a (cached) integer variable index with a constant value.
  int IndexFromConstant(int64_t value);

  // Returns a valid integer index from a BoolVar index.
  // If the input index is a positive, it returns this index.
  // If the input index is negative, it creates a cached IntVar equal to
  // 1 - BoolVar(PositiveRef(index)), and returns the index of this new
  // variable.
  int GetOrCreateIntegerIndex(int index);

  void FillLinearTerms(const LinearExpr& left, const LinearExpr& right,
                       LinearConstraintProto* proto);

  CpModelProto cp_model_;
  absl::flat_hash_map<int64_t, int> constant_to_index_map_;
  absl::flat_hash_map<int, int> bool_to_integer_index_map_;
};

int64_t SolutionIntegerValue(const CpSolverResponse& r, const LinearExpr& expr);

bool SolutionBooleanValue(const CpSolverResponse& r, BoolVar x);

// Returns a more readable and compact DebugString() than
// proto.variables(index).DebugString(). This is used by IntVar::DebugString()
// but also allow to get the same string from a const proto.
std::string VarDebugString(const CpModelProto& proto, int index);

// ============================================================================
// Minimal support for "natural" API to create LinearExpr.
//
// Note(user): This might be optimized further by optimizing LinearExpr for
// holding one term, or introducing an LinearTerm class, but these should mainly
// be used to construct small expressions. Revisit if we run into performance
// issues. Note that if perf become a bottleneck for a client, then probably
// directly writing the proto will be even faster.
// ============================================================================

inline LinearExpr operator-(LinearExpr expr) { return expr *= -1; }

inline LinearExpr operator+(const LinearExpr& lhs, const LinearExpr& rhs) {
  LinearExpr temp(lhs);
  temp += rhs;
  return temp;
}
inline LinearExpr operator+(LinearExpr&& lhs, const LinearExpr& rhs) {
  lhs += rhs;
  return std::move(lhs);
}
inline LinearExpr operator+(const LinearExpr& lhs, LinearExpr&& rhs) {
  rhs += lhs;
  return std::move(rhs);
}
inline LinearExpr operator+(LinearExpr&& lhs, LinearExpr&& rhs) {
  if (lhs.variables().size() < rhs.variables().size()) {
    rhs += std::move(lhs);
    return std::move(rhs);
  } else {
    lhs += std::move(rhs);
    return std::move(lhs);
  }
}

inline LinearExpr operator-(const LinearExpr& lhs, const LinearExpr& rhs) {
  LinearExpr temp(lhs);
  temp -= rhs;
  return temp;
}
inline LinearExpr operator-(LinearExpr&& lhs, const LinearExpr& rhs) {
  lhs -= rhs;
  return std::move(lhs);
}
inline LinearExpr operator-(const LinearExpr& lhs, LinearExpr&& rhs) {
  rhs *= -1;
  rhs += lhs;
  return std::move(rhs);
}
inline LinearExpr operator-(LinearExpr&& lhs, LinearExpr&& rhs) {
  lhs -= std::move(rhs);
  return std::move(lhs);
}

inline LinearExpr operator*(LinearExpr expr, int64_t factor) {
  expr *= factor;
  return expr;
}
inline LinearExpr operator*(int64_t factor, LinearExpr expr) {
  expr *= factor;
  return expr;
}

// For DoubleLinearExpr.

inline DoubleLinearExpr operator-(DoubleLinearExpr expr) {
  expr *= -1;
  return expr;
}

inline DoubleLinearExpr operator+(const DoubleLinearExpr& lhs,
                                  const DoubleLinearExpr& rhs) {
  DoubleLinearExpr temp(lhs);
  temp += rhs;
  return temp;
}
inline DoubleLinearExpr operator+(DoubleLinearExpr&& lhs,
                                  const DoubleLinearExpr& rhs) {
  lhs += rhs;
  return std::move(lhs);
}
inline DoubleLinearExpr operator+(const DoubleLinearExpr& lhs,
                                  DoubleLinearExpr&& rhs) {
  rhs += lhs;
  return std::move(rhs);
}
inline DoubleLinearExpr operator+(DoubleLinearExpr&& lhs,
                                  DoubleLinearExpr&& rhs) {
  if (lhs.variables().size() < rhs.variables().size()) {
    rhs += std::move(lhs);
    return std::move(rhs);
  } else {
    lhs += std::move(rhs);
    return std::move(lhs);
  }
}

inline DoubleLinearExpr operator+(DoubleLinearExpr expr, double rhs) {
  expr += rhs;
  return expr;
}
inline DoubleLinearExpr operator+(double lhs, DoubleLinearExpr expr) {
  expr += lhs;
  return expr;
}

inline DoubleLinearExpr operator-(const DoubleLinearExpr& lhs,
                                  const DoubleLinearExpr& rhs) {
  DoubleLinearExpr temp(lhs);
  temp -= rhs;
  return temp;
}
inline DoubleLinearExpr operator-(DoubleLinearExpr&& lhs,
                                  const DoubleLinearExpr& rhs) {
  lhs -= rhs;
  return std::move(lhs);
}
inline DoubleLinearExpr operator-(const DoubleLinearExpr& lhs,
                                  DoubleLinearExpr&& rhs) {
  rhs *= -1;
  rhs += lhs;
  return std::move(rhs);
}
inline DoubleLinearExpr operator-(DoubleLinearExpr&& lhs,
                                  DoubleLinearExpr&& rhs) {
  lhs -= std::move(rhs);
  return std::move(lhs);
}

inline DoubleLinearExpr operator-(DoubleLinearExpr epxr, double rhs) {
  epxr -= rhs;
  return epxr;
}
inline DoubleLinearExpr operator-(double lhs, DoubleLinearExpr expr) {
  expr *= -1;
  expr += lhs;
  return expr;
}

inline DoubleLinearExpr operator*(DoubleLinearExpr expr, double factor) {
  expr *= factor;
  return expr;
}

inline DoubleLinearExpr operator*(double factor, DoubleLinearExpr expr) {
  expr *= factor;
  return expr;
}

}  // namespace sat
}  // namespace operations_research

#endif  // OR_TOOLS_SAT_CP_MODEL_H_