DSFactory.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.analysis.differentiation;
import java.io.Serializable;
import org.hipparchus.Field;
import org.hipparchus.exception.LocalizedCoreFormats;
import org.hipparchus.exception.MathIllegalArgumentException;
import org.hipparchus.util.FastMath;
/** Factory for {@link DerivativeStructure}.
* <p>This class is a factory for {@link DerivativeStructure} instances.</p>
* <p>Instances of this class are guaranteed to be immutable.</p>
* @see DerivativeStructure
* @since 1.1
*/
public class DSFactory implements Serializable {
/** Serializable UID. */
private static final long serialVersionUID = 20161222L;
/** Compiler for the current dimensions. */
private final transient DSCompiler compiler;
/** Field the {@link DerivativeStructure} instances belong to. */
private final transient DSField derivativeField;
/** Simple constructor.
* @param parameters number of free parameters
* @param order derivation order
*/
public DSFactory(final int parameters, final int order) {
this.compiler = DSCompiler.getCompiler(parameters, order);
this.derivativeField = new DSField(constant(0.0), constant(1.0), constant(FastMath.PI));
}
/** Get the {@link Field} the {@link DerivativeStructure} instances belong to.
* @return {@link Field} the {@link DerivativeStructure} instances belong to
*/
public DSField getDerivativeField() {
return derivativeField;
}
/** Build a {@link DerivativeStructure} representing a constant value.
* @param value value of the constant
* @return a {@link DerivativeStructure} representing a constant value
*/
public DerivativeStructure constant(double value) {
final DerivativeStructure ds = new DerivativeStructure(this);
ds.setDerivativeComponent(0, value);
return ds;
}
/** Build a {@link DerivativeStructure} representing a variable.
* <p>Instances built using this method are considered
* to be the free variables with respect to which differentials
* are computed. As such, their differential with respect to
* themselves is +1.</p>
* @param index index of the variable (from 0 to
* {@link #getCompiler()}.{@link DSCompiler#getFreeParameters() getFreeParameters()} - 1)
* @param value value of the variable
* @exception MathIllegalArgumentException if index if greater or
* equal to {@link #getCompiler()}.{@link DSCompiler#getFreeParameters() getFreeParameters()}.
* @return a {@link DerivativeStructure} representing a variable
*/
public DerivativeStructure variable(final int index, final double value)
throws MathIllegalArgumentException {
if (index >= getCompiler().getFreeParameters()) {
throw new MathIllegalArgumentException(LocalizedCoreFormats.NUMBER_TOO_LARGE_BOUND_EXCLUDED,
index, getCompiler().getFreeParameters());
}
final DerivativeStructure ds = new DerivativeStructure(this);
ds.setDerivativeComponent(0, value);
if (getCompiler().getOrder() > 0) {
// the derivative of the variable with respect to itself is 1.
ds.setDerivativeComponent(DSCompiler.getCompiler(index, getCompiler().getOrder()).getSize(), 1.0);
}
return ds;
}
/** Build a {@link DerivativeStructure} from all its derivatives.
* @param derivatives derivatives sorted according to
* {@link DSCompiler#getPartialDerivativeIndex(int...)}
* @return a {@link DerivativeStructure} with specified derivatives
* @exception MathIllegalArgumentException if derivatives array does not match the
* {@link DSCompiler#getSize() size} expected by the compiler
* @exception MathIllegalArgumentException if order is too large
* @see DerivativeStructure#getAllDerivatives()
*/
@SafeVarargs
public final DerivativeStructure build(final double ... derivatives)
throws MathIllegalArgumentException {
if (derivatives.length != compiler.getSize()) {
throw new MathIllegalArgumentException(LocalizedCoreFormats.DIMENSIONS_MISMATCH,
derivatives.length, compiler.getSize());
}
return new DerivativeStructure(this, derivatives);
}
/** Build a {@link DerivativeStructure} with an uninitialized array.
* <p>This method is intended only for DerivativeStructure internal use.</p>
* @return a {@link DerivativeStructure} with an uninitialized array
*/
DerivativeStructure build() {
return new DerivativeStructure(this);
}
/** Get the compiler for the current dimensions.
* @return compiler for the current dimensions
*/
public DSCompiler getCompiler() {
return compiler;
}
/** Check rules set compatibility.
* @param factory other factory field to check against instance
* @exception MathIllegalArgumentException if number of free parameters or orders are inconsistent
*/
void checkCompatibility(final DSFactory factory) throws MathIllegalArgumentException {
compiler.checkCompatibility(factory.compiler);
}
/**
* Replace the instance with a data transfer object for serialization.
* @return data transfer object that will be serialized
*/
private Object writeReplace() {
return new DataTransferObject(compiler.getFreeParameters(), compiler.getOrder());
}
/** Internal class used only for serialization. */
private static class DataTransferObject implements Serializable {
/** Serializable UID. */
private static final long serialVersionUID = 20161222L;
/** Number of variables.
* @serial
*/
private final int variables;
/** Derivation order.
* @serial
*/
private final int order;
/** Simple constructor.
* @param variables number of variables
* @param order derivation order
*/
DataTransferObject(final int variables, final int order) {
this.variables = variables;
this.order = order;
}
/** Replace the deserialized data transfer object with a {@link DSFactory}.
* @return replacement {@link DSFactory}
*/
private Object readResolve() {
return new DSFactory(variables, order);
}
}
/** Field for {link DerivativeStructure} instances.
*/
public static class DSField implements Field<DerivativeStructure> {
/** Constant function evaluating to 0.0. */
private final DerivativeStructure zero;
/** Constant function evaluating to 1.0. */
private final DerivativeStructure one;
/** Constant function evaluating to π. */
private final DerivativeStructure pi;
/** Simple constructor.
* @param zero constant function evaluating to 0.0
* @param one constant function evaluating to 1.0
* @param pi constant function evaluating to π
*/
DSField(final DerivativeStructure zero, final DerivativeStructure one, final DerivativeStructure pi) {
this.zero = zero;
this.one = one;
this.pi = pi;
}
/** {@inheritDoc} */
@Override
public DerivativeStructure getZero() {
return zero;
}
/** {@inheritDoc} */
@Override
public DerivativeStructure getOne() {
return one;
}
/** Get the Archimedes constant π.
* <p>
* Archimedes constant is the ratio of a circle's circumference to its diameter.
* </p>
* @return Archimedes constant π
* @since 2.0
*/
public DerivativeStructure getPi() {
return pi;
}
/** {@inheritDoc} */
@Override
public Class<DerivativeStructure> getRuntimeClass() {
return DerivativeStructure.class;
}
/** {@inheritDoc} */
@Override
public boolean equals(final Object other) {
if (this == other) {
return true;
} else if (other instanceof DSField) {
DSFactory lhsFactory = zero.getFactory();
DSFactory rhsFactory = ((DSField) other).zero.getFactory();
return lhsFactory.compiler == rhsFactory.compiler;
} else {
return false;
}
}
/** {@inheritDoc} */
@Override
public int hashCode() {
final DSCompiler compiler = zero.getFactory().getCompiler();
return 0x9943b886 ^ (compiler.getFreeParameters() << 16 & compiler.getOrder());
}
}
}