001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 package org.apache.commons.math.ode;
019
020 import org.apache.commons.math.ode.DerivativeException;
021
022 /** This class converts second order differential equations to first
023 * order ones.
024 *
025 * <p>This class is a wrapper around a {@link
026 * SecondOrderDifferentialEquations} which allow to use a {@link
027 * FirstOrderIntegrator} to integrate it.</p>
028 *
029 * <p>The transformation is done by changing the n dimension state
030 * vector to a 2n dimension vector, where the first n components are
031 * the initial state variables and the n last components are their
032 * first time derivative. The first time derivative of this state
033 * vector then really contains both the first and second time
034 * derivative of the initial state vector, which can be handled by the
035 * underlying second order equations set.</p>
036 *
037 * <p>One should be aware that the data is duplicated during the
038 * transformation process and that for each call to {@link
039 * #computeDerivatives computeDerivatives}, this wrapper does copy 4n
040 * scalars : 2n before the call to {@link
041 * SecondOrderDifferentialEquations#computeSecondDerivatives
042 * computeSecondDerivatives} in order to dispatch the y state vector
043 * into z and zDot, and 2n after the call to gather zDot and zDDot
044 * into yDot. Since the underlying problem by itself perhaps also
045 * needs to copy data and dispatch the arrays into domain objects,
046 * this has an impact on both memory and CPU usage. The only way to
047 * avoid this duplication is to perform the transformation at the
048 * problem level, i.e. to implement the problem as a first order one
049 * and then avoid using this class.</p>
050 *
051 * @see FirstOrderIntegrator
052 * @see FirstOrderDifferentialEquations
053 * @see SecondOrderDifferentialEquations
054 * @version $Revision: 1073158 $ $Date: 2011-02-21 22:46:52 +0100 (lun. 21 f??vr. 2011) $
055 * @since 1.2
056 */
057
058 public class FirstOrderConverter implements FirstOrderDifferentialEquations {
059
060 /** Underlying second order equations set. */
061 private final SecondOrderDifferentialEquations equations;
062
063 /** second order problem dimension. */
064 private final int dimension;
065
066 /** state vector. */
067 private final double[] z;
068
069 /** first time derivative of the state vector. */
070 private final double[] zDot;
071
072 /** second time derivative of the state vector. */
073 private final double[] zDDot;
074
075 /** Simple constructor.
076 * Build a converter around a second order equations set.
077 * @param equations second order equations set to convert
078 */
079 public FirstOrderConverter (final SecondOrderDifferentialEquations equations) {
080 this.equations = equations;
081 dimension = equations.getDimension();
082 z = new double[dimension];
083 zDot = new double[dimension];
084 zDDot = new double[dimension];
085 }
086
087 /** Get the dimension of the problem.
088 * <p>The dimension of the first order problem is twice the
089 * dimension of the underlying second order problem.</p>
090 * @return dimension of the problem
091 */
092 public int getDimension() {
093 return 2 * dimension;
094 }
095
096 /** Get the current time derivative of the state vector.
097 * @param t current value of the independent <I>time</I> variable
098 * @param y array containing the current value of the state vector
099 * @param yDot placeholder array where to put the time derivative of the state vector
100 * @throws DerivativeException this exception is propagated to the caller if the
101 * underlying user function triggers one
102 */
103 public void computeDerivatives(final double t, final double[] y, final double[] yDot)
104 throws DerivativeException {
105
106 // split the state vector in two
107 System.arraycopy(y, 0, z, 0, dimension);
108 System.arraycopy(y, dimension, zDot, 0, dimension);
109
110 // apply the underlying equations set
111 equations.computeSecondDerivatives(t, z, zDot, zDDot);
112
113 // build the result state derivative
114 System.arraycopy(zDot, 0, yDot, 0, dimension);
115 System.arraycopy(zDDot, 0, yDot, dimension, dimension);
116
117 }
118
119 }