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    /** This class converts second order differential equations to first
021     * order ones.
022     *
023     * <p>This class is a wrapper around a {@link
024     * SecondOrderDifferentialEquations} which allow to use a {@link
025     * FirstOrderIntegrator} to integrate it.</p>
026     *
027     * <p>The transformation is done by changing the n dimension state
028     * vector to a 2n dimension vector, where the first n components are
029     * the initial state variables and the n last components are their
030     * first time derivative. The first time derivative of this state
031     * vector then really contains both the first and second time
032     * derivative of the initial state vector, which can be handled by the
033     * underlying second order equations set.</p>
034     *
035     * <p>One should be aware that the data is duplicated during the
036     * transformation process and that for each call to {@link
037     * #computeDerivatives computeDerivatives}, this wrapper does copy 4n
038     * scalars : 2n before the call to {@link
039     * SecondOrderDifferentialEquations#computeSecondDerivatives
040     * computeSecondDerivatives} in order to dispatch the y state vector
041     * into z and zDot, and 2n after the call to gather zDot and zDDot
042     * into yDot. Since the underlying problem by itself perhaps also
043     * needs to copy data and dispatch the arrays into domain objects,
044     * this has an impact on both memory and CPU usage. The only way to
045     * avoid this duplication is to perform the transformation at the
046     * problem level, i.e. to implement the problem as a first order one
047     * and then avoid using this class.</p>
048     *
049     * @see FirstOrderIntegrator
050     * @see FirstOrderDifferentialEquations
051     * @see SecondOrderDifferentialEquations
052     * @version $Revision: 786881 $ $Date: 2009-06-20 14:53:08 -0400 (Sat, 20 Jun 2009) $
053     * @since 1.2
054     */
055    
056    public class FirstOrderConverter implements FirstOrderDifferentialEquations {
057    
058      /** Simple constructor.
059       * Build a converter around a second order equations set.
060       * @param equations second order equations set to convert
061       */
062      public FirstOrderConverter (final SecondOrderDifferentialEquations equations) {
063          this.equations = equations;
064          dimension      = equations.getDimension();
065          z              = new double[dimension];
066          zDot           = new double[dimension];
067          zDDot          = new double[dimension];
068      }
069    
070      /** Get the dimension of the problem.
071       * <p>The dimension of the first order problem is twice the
072       * dimension of the underlying second order problem.</p>
073       * @return dimension of the problem
074       */
075      public int getDimension() {
076        return 2 * dimension;
077      }
078    
079      /** Get the current time derivative of the state vector.
080       * @param t current value of the independent <I>time</I> variable
081       * @param y array containing the current value of the state vector
082       * @param yDot placeholder array where to put the time derivative of the state vector
083       * @throws DerivativeException this exception is propagated to the caller if the
084       * underlying user function triggers one
085       */
086      public void computeDerivatives(final double t, final double[] y, final double[] yDot)
087          throws DerivativeException {
088    
089        // split the state vector in two
090        System.arraycopy(y, 0,         z,    0, dimension);
091        System.arraycopy(y, dimension, zDot, 0, dimension);
092    
093        // apply the underlying equations set
094        equations.computeSecondDerivatives(t, z, zDot, zDDot);
095    
096        // build the result state derivative
097        System.arraycopy(zDot,  0, yDot, 0,         dimension);
098        System.arraycopy(zDDot, 0, yDot, dimension, dimension);
099        
100      }
101    
102      /** Underlying second order equations set. */
103      private SecondOrderDifferentialEquations equations;
104    
105      /** second order problem dimension. */
106      private int dimension;
107    
108      /** state vector. */
109      private double[] z;
110    
111      /** first time derivative of the state vector. */
112      private double[] zDot;
113    
114      /** second time derivative of the state vector. */
115      private double[] zDDot;
116    
117    }