QPConstraintMatrix.java
/*
* Licensed to the Hipparchus project under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The Hipparchus project licenses this file to You 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
*
* https://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.hipparchus.optim.nonlinear.vector.constrained;
import org.hipparchus.exception.LocalizedCoreFormats;
import org.hipparchus.exception.MathIllegalArgumentException;
import org.hipparchus.linear.AbstractRealMatrix;
import org.hipparchus.linear.ArrayRealVector;
import org.hipparchus.linear.MatrixUtils;
import org.hipparchus.linear.RealMatrix;
import org.hipparchus.linear.RealVector;
/**
* Read-only, zero-copy row-oriented view of all linear constraints of a QP.
*
* <p>The represented matrix has the form:</p>
*
* <pre>
* A = [ Ae ]
* [ Ai ]
* [ Ab ]
* [ -Ab ]
* </pre>
*
* <p>where each constraint gradient is stored as a row. The class keeps only
* references to the original equality, inequality and bounded-constraint
* matrices. In particular, the upper-bound block {@code -Ab} is generated on
* demand and is never stored.</p>
*
* <p>The global row ordering is:</p>
* <ol>
* <li>equality constraints,</li>
* <li>inequality constraints,</li>
* <li>lower bounded constraints,</li>
* <li>upper bounded constraints.</li>
* </ol>
*
* <p>The matrix is intentionally read-only. Calling {@link #copy()} creates a
* physical independent matrix, but normal solver operations such as
* {@link #getEntry(int, int)}, {@link #getRowVector(int)} and
* {@link #operate(RealVector)} do not materialize the global matrix.</p>
*/
public final class QPConstraintMatrix extends AbstractRealMatrix {
/** Number of primal variables, i.e. matrix columns. */
private final int variableCount;
/** Equality matrix, one equality per row. */
private final RealMatrix equalityMatrix;
/** Inequality matrix, one inequality per row. */
private final RealMatrix inequalityMatrix;
/** Bounded-constraint matrix, one bounded expression per row. */
private final RealMatrix boundedMatrix;
/** Number of equality rows. */
private final int equalityCount;
/** Number of inequality rows. */
private final int inequalityCount;
/** Number of bounded-expression rows. */
private final int boundedCount;
/** First global row of the inequality block. */
private final int inequalityOffset;
/** First global row of the lower-bound block. */
private final int lowerBoundOffset;
/** First global row of the upper-bound block. */
private final int upperBoundOffset;
/** Total number of represented constraints. */
private final int constraintCount;
/**
* Build a row-oriented virtual QP constraint matrix.
*
* @param variableCount number of primal variables
* @param equalityMatrix equality matrix, or {@code null}
* @param inequalityMatrix inequality matrix, or {@code null}
* @param boundedMatrix bounded-expression matrix, or {@code null}
*/
public QPConstraintMatrix(final int variableCount,
final RealMatrix equalityMatrix,
final RealMatrix inequalityMatrix,
final RealMatrix boundedMatrix) {
if (variableCount < 0) {
throw new MathIllegalArgumentException(LocalizedCoreFormats.NEGATIVE_VALUE, variableCount);
}
this.variableCount = variableCount;
this.equalityMatrix = equalityMatrix;
this.inequalityMatrix = inequalityMatrix;
this.boundedMatrix = boundedMatrix;
checkColumnDimension(equalityMatrix, variableCount);
checkColumnDimension(inequalityMatrix, variableCount);
checkColumnDimension(boundedMatrix, variableCount);
this.equalityCount = equalityMatrix == null ? 0 : equalityMatrix.getRowDimension();
this.inequalityCount = inequalityMatrix == null ? 0 : inequalityMatrix.getRowDimension();
this.boundedCount = boundedMatrix == null ? 0 : boundedMatrix.getRowDimension();
this.inequalityOffset = equalityCount;
this.lowerBoundOffset = equalityCount + inequalityCount;
this.upperBoundOffset = lowerBoundOffset + boundedCount;
this.constraintCount = upperBoundOffset + boundedCount;
}
/** Validate the number of columns of a backing block.
* @param matrix constraint matrix
* @param expected expected number of columns
*/
private static void checkColumnDimension(final RealMatrix matrix,
final int expected) {
if (matrix != null && matrix.getColumnDimension() != expected) {
throw new MathIllegalArgumentException(LocalizedCoreFormats.DIMENSIONS_MISMATCH,
matrix.getColumnDimension(), expected);
}
}
/** {@inheritDoc} */
@Override
public int getRowDimension() {
return constraintCount;
}
/** {@inheritDoc} */
@Override
public int getColumnDimension() {
return variableCount;
}
/**
* Get a coefficient without constructing the global matrix.
*
* @param row global constraint index
* @param column primal-variable index
* @return coefficient A[row, column]
*/
@Override
public double getEntry(final int row, final int column) {
MatrixUtils.checkMatrixIndex(this, row, column);
if (row < inequalityOffset) {
return equalityMatrix.getEntry(row, column);
}
if (row < lowerBoundOffset) {
return inequalityMatrix.getEntry(row - inequalityOffset, column);
}
if (row < upperBoundOffset) {
return boundedMatrix.getEntry(row - lowerBoundOffset, column);
}
return -boundedMatrix.getEntry(row - upperBoundOffset, column);
}
/**
* Get a constraint gradient as a row vector.
*
* <p>The backing Hipparchus matrix already returns an independent vector.
* For an upper bound that same newly allocated vector is negated in place,
* avoiding an additional vector allocation.</p>
*
* @param row global constraint index
* @return constraint gradient
*/
@Override
public RealVector getRowVector(final int row) {
MatrixUtils.checkRowIndex(this, row);
if (row < inequalityOffset) {
return equalityMatrix.getRowVector(row);
}
if (row < lowerBoundOffset) {
return inequalityMatrix.getRowVector(row - inequalityOffset);
}
if (row < upperBoundOffset) {
return boundedMatrix.getRowVector(row - lowerBoundOffset);
}
return boundedMatrix.getRowVector(row - upperBoundOffset)
.mapMultiplyToSelf(-1.0);
}
/**
* Get a constraint gradient as an array.
*
* @param row global constraint index
* @return independent coefficient array
*/
@Override
public double[] getRow(final int row) {
MatrixUtils.checkRowIndex(this, row);
if (row < inequalityOffset) {
return equalityMatrix.getRow(row);
}
if (row < lowerBoundOffset) {
return inequalityMatrix.getRow(row - inequalityOffset);
}
if (row < upperBoundOffset) {
return boundedMatrix.getRow(row - lowerBoundOffset);
}
final double[] data = boundedMatrix.getRow(row - upperBoundOffset);
for (int i = 0; i < data.length; i++) {
data[i] = -data[i];
}
return data;
}
/**
* Evaluate all linear constraint expressions A x.
*
* <p>Each physical backing block is multiplied only once. The product of
* the bounded matrix is reused for both the lower and upper blocks, with
* opposite signs.</p>
*
* @param x primal vector
* @return A x
*/
@Override
public RealVector operate(final RealVector x) {
final double[] result = new double[constraintCount];
if (equalityCount > 0) {
copy(equalityMatrix.operate(x), result, 0, 1.0);
}
if (inequalityCount > 0) {
copy(inequalityMatrix.operate(x), result, inequalityOffset, 1.0);
}
if (boundedCount > 0) {
final RealVector boundedValue = boundedMatrix.operate(x);
copy(boundedValue, result, lowerBoundOffset, 1.0);
copy(boundedValue, result, upperBoundOffset, -1.0);
}
return new ArrayRealVector(result, false);
}
/** Copy a vector into an array, optionally changing its sign.
* @param source source vector
* @param destination destination array
* @param offset offset in destination array
* @param scale scaling factor applied to all components
*/
private static void copy(final RealVector source,
final double[] destination,
final int offset,
final double scale) {
for (int i = 0; i < source.getDimension(); i++) {
destination[offset + i] = scale * source.getEntry(i);
}
}
/**
* This view is read-only.
*/
@Override
public void setEntry(final int row, final int column, final double value) {
throw new UnsupportedOperationException("QPConstraintMatrix is read-only");
}
/**
* Create an independent physical matrix for results of generic operations.
*/
@Override
public RealMatrix createMatrix(final int rowDimension, final int columnDimension) {
return MatrixUtils.createRealMatrix(rowDimension, columnDimension);
}
/**
* Materialize an independent deep copy.
*/
@Override
public RealMatrix copy() {
final RealMatrix result = MatrixUtils.createRealMatrix(constraintCount, variableCount);
for (int row = 0; row < constraintCount; row++) {
result.setRow(row, getRow(row));
}
return result;
}
}