Apache
/
commons-math
mirror of https://github.com/apache/commons-math.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Starting work on Field-based ordinary differential equations. 

The base elements are the primary equation that users must implement,
and optional secondary equations to support features like adjoint
parameters or variational equations. Some containers to hold current
state are also introduced to simplify API (these container do not exist
in the double[] version of the API).

JIRA: MATH-1288
This commit is contained in:
Luc Maisonobe 2016-01-06 12:18:50 +01:00
parent 7e1c299da2
commit 43800e3460
4 changed files with 318 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
src/main/java/org/apache/commons/math4/ode/FieldFirstOrderDifferentialEquations.java Normal file
View File

@ -0,0 +1,61 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF 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
*
* 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.apache.commons.math4.ode;
import org.apache.commons.math4.RealFieldElement;
/** This interface represents a first order differential equations set.
*
* <p>This interface should be implemented by all real first order
* differential equation problems before they can be handled by the
* integrators {@link FirstOrderIntegrator#integrate} method.</p>
*
* <p>A first order differential equations problem, as seen by an
* integrator is the time derivative <code>dY/dt</code> of a state
* vector <code>Y</code>, both being one dimensional arrays. From the
* integrator point of view, this derivative depends only on the
* current time <code>t</code> and on the state vector
* <code>Y</code>.</p>
*
* <p>For real problems, the derivative depends also on parameters
* that do not belong to the state vector (dynamical model constants
* for example). These constants are completely outside of the scope
* of this interface, the classes that implement it are allowed to
* handle them as they want.</p>
*
* @see FieldFirstOrderIntegrator
*
* @param <T> the type of the field elements
* @since 3.6
*/
public interface FieldFirstOrderDifferentialEquations<T extends RealFieldElement<T>> {
/** Get the dimension of the problem.
* @return dimension of the problem
*/
int getDimension();
/** Get the current time derivative of the state vector.
* @param t current value of the independent <I>time</I> variable
* @param y array containing the current value of the state vector
* @return time derivative of the state vector
*/
T[] computeDerivatives(T t, T[] y);
}

114
src/main/java/org/apache/commons/math4/ode/FieldODEState.java Normal file
View File

@ -0,0 +1,114 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF 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
*
* 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.apache.commons.math4.ode;
import org.apache.commons.math4.Field;
import org.apache.commons.math4.RealFieldElement;
import org.apache.commons.math4.util.MathArrays;
/** Container for time, main and secondary state vectors.
* @see FieldFirstOrderDifferentialEquations
* @see FieldSecondaryEquations
* @see FieldFirstOrderIntegrator
* @see FieldODEStateAndDerivative
* @param <T> the type of the field elements
* @since 3.6
*/
public class FieldODEState<T extends RealFieldElement<T>> {
/** Time. */
private final T time;
/** Main state at time. */
private final T[] state;
/** Secondary state at time. */
private final T[][] secondaryState;
/** Simple constructor.
* <p>Calling this constructor is equivalent to call {@link
* #FieldODEState(RealFieldElement, RealFieldElement[], RealFieldElement[][])
* FieldODEState(time, state, null).</p>
* @param time time
* @param state state at time
*/
public FieldODEState(T time, T[] state) {
this(time, state, null);
}
/** Simple constructor.
* @param time time
* @param state state at time
* @param secondaryState state at time (may be null)
*/
public FieldODEState(T time, T[] state, T[][] secondaryState) {
this.time = time;
this.state = state.clone();
this.secondaryState = copy(time.getField(), secondaryState);
}
/** Copy a two-dimensions array.
* @param field field to which elements belong
* @param original original array (may be null)
* @return copied array or null if original array was null
*/
protected T[][] copy(final Field<T> field, final T[][] original) {
// special handling of null arrays
if (original == null) {
return null;
}
// allocate the array
final T[][] copied = MathArrays.buildArray(field, original.length, original[0].length);
// copy content
for (int i = 0; i < original.length; ++i) {
System.arraycopy(original[i], 0, copied[i], 0, original[i].length);
}
return copied;
}
/** Get time.
* @return time
*/
public T getTime() {
return time;
}
/** Get main state at time.
* @return main state at time
*/
public T[] getState() {
return state.clone();
}
/** Get secondary state at time.
* @param index index of the secondary set as returned
* by {@link FieldExpandableODE#addSecondaryEquations(FieldSecondaryEquations)}
* @return secondary state at time
*/
public T[] getSecondaryState(final int index) {
return secondaryState[index].clone();
}
}

81
src/main/java/org/apache/commons/math4/ode/FieldODEStateAndDerivative.java Normal file
View File

@ -0,0 +1,81 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF 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
*
* 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.apache.commons.math4.ode;
import org.apache.commons.math4.RealFieldElement;
/** Container for time, main and secondary state vectors as well as their derivatives.
* @see FieldFirstOrderDifferentialEquations
* @see FieldSecondaryEquations
* @see FieldFirstOrderIntegrator
* @param <T> the type of the field elements
* @since 3.6
*/
public class FieldODEStateAndDerivative<T extends RealFieldElement<T>> extends FieldODEState<T> {
/** Derivative of the main state at time. */
private final T[] derivative;
/** Derivative of the secondary state at time. */
private final T[][] secondaryDerivative;
/** Simple constructor.
* <p>Calling this constructor is equivalent to call {@link
* #FieldODEStateAndDerivative(RealFieldElement, RealFieldElement[], RealFieldElement[],
* RealFieldElement[][], RealFieldElement[][]) FieldODEStateAndDerivative(time, state,
* derivative, null, null).</p>
* @param time time
* @param state state at time
* @param derivative derivative of the state at time
*/
public FieldODEStateAndDerivative(T time, T[] state, T[] derivative) {
this(time, state, derivative, null, null);
}
/** Simple constructor.
* @param time time
* @param state state at time
* @param derivative derivative of the state at time
* @param secondaryState state at time (may be null)
* @param secondaryDerivative derivative of the state at time (may be null)
*/
public FieldODEStateAndDerivative(T time, T[] state, T[] derivative, T[][] secondaryState, T[][] secondaryDerivative) {
super(time, state, secondaryState);
this.derivative = derivative.clone();
this.secondaryDerivative = copy(time.getField(), secondaryDerivative);
}
/** Get derivative of the main state at time.
* @return derivative of the main state at time
*/
public T[] getDerivative() {
return derivative.clone();
}
/** Get derivative of the secondary state at time.
* @param index index of the secondary set as returned
* by {@link FieldExpandableODE#addSecondaryEquations(FieldSecondaryEquations)}
* @return derivative of the secondary state at time
*/
public T[] getSecondaryDerivative(final int index) {
return secondaryDerivative[index].clone();
}
}

62
src/main/java/org/apache/commons/math4/ode/FieldSecondaryEquations.java Normal file
View File

@ -0,0 +1,62 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF 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
*
* 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.apache.commons.math4.ode;
import org.apache.commons.math4.RealFieldElement;
import org.apache.commons.math4.exception.DimensionMismatchException;
import org.apache.commons.math4.exception.MaxCountExceededException;
/**
* This interface allows users to add secondary differential equations to a primary
* set of differential equations.
* <p>
* In some cases users may need to integrate some problem-specific equations along
* with a primary set of differential equations. One example is optimal control where
* adjoined parameters linked to the minimized Hamiltonian must be integrated.
* </p>
* <p>
* This interface allows users to add such equations to a primary set of {@link
* FieldFirstOrderDifferentialEquations first order differential equations}
* thanks to the {@link FieldExpandableODE#addSecondaryEquations(FieldSecondaryEquations)}
* method.
* </p>
* @see FieldFirstOrderDifferentialEquations
* @see FieldExpandableODE
* @param <T> the type of the field elements
* @since 3.6
*/
public interface FieldSecondaryEquations<T extends RealFieldElement<T>> {
/** Get the dimension of the secondary state parameters.
* @return dimension of the secondary state parameters
*/
int getDimension();
/** Compute the derivatives related to the secondary state parameters.
* @param t current value of the independent <I>time</I> variable
* @param primary array containing the current value of the primary state vector
* @param primaryDot array containing the derivative of the primary state vector
* @param secondary array containing the current value of the secondary state vector
* @return derivative of the secondary state vector
* @exception MaxCountExceededException if the number of functions evaluations is exceeded
* @exception DimensionMismatchException if arrays dimensions do not match equations settings
*/
T[] computeDerivatives(T t, T[] primary, T[] primaryDot, T[] secondary)
throws MaxCountExceededException, DimensionMismatchException;
}