View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.math3.optim.linear;
18  
19  import java.io.IOException;
20  import java.io.ObjectInputStream;
21  import java.io.ObjectOutputStream;
22  import java.io.Serializable;
23  import org.apache.commons.math3.linear.MatrixUtils;
24  import org.apache.commons.math3.linear.RealVector;
25  import org.apache.commons.math3.linear.ArrayRealVector;
26  
27  /**
28   * A linear constraint for a linear optimization problem.
29   * <p>
30   * A linear constraint has one of the forms:
31   * <ul>
32   *   <li>c<sub>1</sub>x<sub>1</sub> + ... c<sub>n</sub>x<sub>n</sub> = v</li>
33   *   <li>c<sub>1</sub>x<sub>1</sub> + ... c<sub>n</sub>x<sub>n</sub> &lt;= v</li>
34   *   <li>c<sub>1</sub>x<sub>1</sub> + ... c<sub>n</sub>x<sub>n</sub> >= v</li>
35   *   <li>l<sub>1</sub>x<sub>1</sub> + ... l<sub>n</sub>x<sub>n</sub> + l<sub>cst</sub> =
36   *       r<sub>1</sub>x<sub>1</sub> + ... r<sub>n</sub>x<sub>n</sub> + r<sub>cst</sub></li>
37   *   <li>l<sub>1</sub>x<sub>1</sub> + ... l<sub>n</sub>x<sub>n</sub> + l<sub>cst</sub> &lt;=
38   *       r<sub>1</sub>x<sub>1</sub> + ... r<sub>n</sub>x<sub>n</sub> + r<sub>cst</sub></li>
39   *   <li>l<sub>1</sub>x<sub>1</sub> + ... l<sub>n</sub>x<sub>n</sub> + l<sub>cst</sub> >=
40   *       r<sub>1</sub>x<sub>1</sub> + ... r<sub>n</sub>x<sub>n</sub> + r<sub>cst</sub></li>
41   * </ul>
42   * The c<sub>i</sub>, l<sub>i</sub> or r<sub>i</sub> are the coefficients of the constraints, the x<sub>i</sub>
43   * are the coordinates of the current point and v is the value of the constraint.
44   * </p>
45   *
46   * @since 2.0
47   */
48  public class LinearConstraint implements Serializable {
49      /** Serializable version identifier. */
50      private static final long serialVersionUID = -764632794033034092L;
51      /** Coefficients of the constraint (left hand side). */
52      private final transient RealVector coefficients;
53      /** Relationship between left and right hand sides (=, &lt;=, >=). */
54      private final Relationship relationship;
55      /** Value of the constraint (right hand side). */
56      private final double value;
57  
58      /**
59       * Build a constraint involving a single linear equation.
60       * <p>
61       * A linear constraint with a single linear equation has one of the forms:
62       * <ul>
63       *   <li>c<sub>1</sub>x<sub>1</sub> + ... c<sub>n</sub>x<sub>n</sub> = v</li>
64       *   <li>c<sub>1</sub>x<sub>1</sub> + ... c<sub>n</sub>x<sub>n</sub> &lt;= v</li>
65       *   <li>c<sub>1</sub>x<sub>1</sub> + ... c<sub>n</sub>x<sub>n</sub> >= v</li>
66       * </ul>
67       * </p>
68       * @param coefficients The coefficients of the constraint (left hand side)
69       * @param relationship The type of (in)equality used in the constraint
70       * @param value The value of the constraint (right hand side)
71       */
72      public LinearConstraint(final double[] coefficients,
73                              final Relationship relationship,
74                              final double value) {
75          this(new ArrayRealVector(coefficients), relationship, value);
76      }
77  
78      /**
79       * Build a constraint involving a single linear equation.
80       * <p>
81       * A linear constraint with a single linear equation has one of the forms:
82       * <ul>
83       *   <li>c<sub>1</sub>x<sub>1</sub> + ... c<sub>n</sub>x<sub>n</sub> = v</li>
84       *   <li>c<sub>1</sub>x<sub>1</sub> + ... c<sub>n</sub>x<sub>n</sub> &lt;= v</li>
85       *   <li>c<sub>1</sub>x<sub>1</sub> + ... c<sub>n</sub>x<sub>n</sub> >= v</li>
86       * </ul>
87       * </p>
88       * @param coefficients The coefficients of the constraint (left hand side)
89       * @param relationship The type of (in)equality used in the constraint
90       * @param value The value of the constraint (right hand side)
91       */
92      public LinearConstraint(final RealVector coefficients,
93                              final Relationship relationship,
94                              final double value) {
95          this.coefficients = coefficients;
96          this.relationship = relationship;
97          this.value        = value;
98      }
99  
100     /**
101      * Build a constraint involving two linear equations.
102      * <p>
103      * A linear constraint with two linear equation has one of the forms:
104      * <ul>
105      *   <li>l<sub>1</sub>x<sub>1</sub> + ... l<sub>n</sub>x<sub>n</sub> + l<sub>cst</sub> =
106      *       r<sub>1</sub>x<sub>1</sub> + ... r<sub>n</sub>x<sub>n</sub> + r<sub>cst</sub></li>
107      *   <li>l<sub>1</sub>x<sub>1</sub> + ... l<sub>n</sub>x<sub>n</sub> + l<sub>cst</sub> &lt;=
108      *       r<sub>1</sub>x<sub>1</sub> + ... r<sub>n</sub>x<sub>n</sub> + r<sub>cst</sub></li>
109      *   <li>l<sub>1</sub>x<sub>1</sub> + ... l<sub>n</sub>x<sub>n</sub> + l<sub>cst</sub> >=
110      *       r<sub>1</sub>x<sub>1</sub> + ... r<sub>n</sub>x<sub>n</sub> + r<sub>cst</sub></li>
111      * </ul>
112      * </p>
113      * @param lhsCoefficients The coefficients of the linear expression on the left hand side of the constraint
114      * @param lhsConstant The constant term of the linear expression on the left hand side of the constraint
115      * @param relationship The type of (in)equality used in the constraint
116      * @param rhsCoefficients The coefficients of the linear expression on the right hand side of the constraint
117      * @param rhsConstant The constant term of the linear expression on the right hand side of the constraint
118      */
119     public LinearConstraint(final double[] lhsCoefficients, final double lhsConstant,
120                             final Relationship relationship,
121                             final double[] rhsCoefficients, final double rhsConstant) {
122         double[] sub = new double[lhsCoefficients.length];
123         for (int i = 0; i < sub.length; ++i) {
124             sub[i] = lhsCoefficients[i] - rhsCoefficients[i];
125         }
126         this.coefficients = new ArrayRealVector(sub, false);
127         this.relationship = relationship;
128         this.value        = rhsConstant - lhsConstant;
129     }
130 
131     /**
132      * Build a constraint involving two linear equations.
133      * <p>
134      * A linear constraint with two linear equation has one of the forms:
135      * <ul>
136      *   <li>l<sub>1</sub>x<sub>1</sub> + ... l<sub>n</sub>x<sub>n</sub> + l<sub>cst</sub> =
137      *       r<sub>1</sub>x<sub>1</sub> + ... r<sub>n</sub>x<sub>n</sub> + r<sub>cst</sub></li>
138      *   <li>l<sub>1</sub>x<sub>1</sub> + ... l<sub>n</sub>x<sub>n</sub> + l<sub>cst</sub> &lt;=
139      *       r<sub>1</sub>x<sub>1</sub> + ... r<sub>n</sub>x<sub>n</sub> + r<sub>cst</sub></li>
140      *   <li>l<sub>1</sub>x<sub>1</sub> + ... l<sub>n</sub>x<sub>n</sub> + l<sub>cst</sub> >=
141      *       r<sub>1</sub>x<sub>1</sub> + ... r<sub>n</sub>x<sub>n</sub> + r<sub>cst</sub></li>
142      * </ul>
143      * </p>
144      * @param lhsCoefficients The coefficients of the linear expression on the left hand side of the constraint
145      * @param lhsConstant The constant term of the linear expression on the left hand side of the constraint
146      * @param relationship The type of (in)equality used in the constraint
147      * @param rhsCoefficients The coefficients of the linear expression on the right hand side of the constraint
148      * @param rhsConstant The constant term of the linear expression on the right hand side of the constraint
149      */
150     public LinearConstraint(final RealVector lhsCoefficients, final double lhsConstant,
151                             final Relationship relationship,
152                             final RealVector rhsCoefficients, final double rhsConstant) {
153         this.coefficients = lhsCoefficients.subtract(rhsCoefficients);
154         this.relationship = relationship;
155         this.value        = rhsConstant - lhsConstant;
156     }
157 
158     /**
159      * Gets the coefficients of the constraint (left hand side).
160      *
161      * @return the coefficients of the constraint (left hand side).
162      */
163     public RealVector getCoefficients() {
164         return coefficients;
165     }
166 
167     /**
168      * Gets the relationship between left and right hand sides.
169      *
170      * @return the relationship between left and right hand sides.
171      */
172     public Relationship getRelationship() {
173         return relationship;
174     }
175 
176     /**
177      * Gets the value of the constraint (right hand side).
178      *
179      * @return the value of the constraint (right hand side).
180      */
181     public double getValue() {
182         return value;
183     }
184 
185     @Override
186     public boolean equals(Object other) {
187         if (this == other) {
188             return true;
189         }
190         if (other instanceof LinearConstraint) {
191             LinearConstraint rhs = (LinearConstraint) other;
192             return relationship == rhs.relationship &&
193                 value == rhs.value &&
194                 coefficients.equals(rhs.coefficients);
195         }
196         return false;
197     }
198 
199     @Override
200     public int hashCode() {
201         return relationship.hashCode() ^
202             Double.valueOf(value).hashCode() ^
203             coefficients.hashCode();
204     }
205 
206     /**
207      * Serialize the instance.
208      * @param oos stream where object should be written
209      * @throws IOException if object cannot be written to stream
210      */
211     private void writeObject(ObjectOutputStream oos)
212         throws IOException {
213         oos.defaultWriteObject();
214         MatrixUtils.serializeRealVector(coefficients, oos);
215     }
216 
217     /**
218      * Deserialize the instance.
219      * @param ois stream from which the object should be read
220      * @throws ClassNotFoundException if a class in the stream cannot be found
221      * @throws IOException if object cannot be read from the stream
222      */
223     private void readObject(ObjectInputStream ois)
224       throws ClassNotFoundException, IOException {
225         ois.defaultReadObject();
226         MatrixUtils.deserializeRealVector(this, "coefficients", ois);
227     }
228 }