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
018package org.apache.commons.math4.legacy.ode;
019
020import java.io.Serializable;
021
022import org.apache.commons.math4.legacy.exception.DimensionMismatchException;
023
024/**
025 * Class mapping the part of a complete state or derivative that pertains
026 * to a specific differential equation.
027 * <p>
028 * Instances of this class are guaranteed to be immutable.
029 * </p>
030 * @see SecondaryEquations
031 * @since 3.0
032 */
033public class EquationsMapper implements Serializable {
034
035    /** Serializable UID. */
036    private static final long serialVersionUID = 20110925L;
037
038    /** Index of the first equation element in complete state arrays. */
039    private final int firstIndex;
040
041    /** Dimension of the secondary state parameters. */
042    private final int dimension;
043
044    /** simple constructor.
045     * @param firstIndex index of the first equation element in complete state arrays
046     * @param dimension dimension of the secondary state parameters
047     */
048    public EquationsMapper(final int firstIndex, final int dimension) {
049        this.firstIndex = firstIndex;
050        this.dimension  = dimension;
051    }
052
053    /** Get the index of the first equation element in complete state arrays.
054     * @return index of the first equation element in complete state arrays
055     */
056    public int getFirstIndex() {
057        return firstIndex;
058    }
059
060    /** Get the dimension of the secondary state parameters.
061     * @return dimension of the secondary state parameters
062     */
063    public int getDimension() {
064        return dimension;
065    }
066
067    /** Extract equation data from a complete state or derivative array.
068     * @param complete complete state or derivative array from which
069     * equation data should be retrieved
070     * @param equationData placeholder where to put equation data
071     * @throws DimensionMismatchException if the dimension of the equation data does not
072     * match the mapper dimension
073     */
074    public void extractEquationData(double[] complete, double[] equationData)
075        throws DimensionMismatchException {
076        if (equationData.length != dimension) {
077            throw new DimensionMismatchException(equationData.length, dimension);
078        }
079        System.arraycopy(complete, firstIndex, equationData, 0, dimension);
080    }
081
082    /** Insert equation data into a complete state or derivative array.
083     * @param equationData equation data to be inserted into the complete array
084     * @param complete placeholder where to put equation data (only the
085     * part corresponding to the equation will be overwritten)
086     * @throws DimensionMismatchException if the dimension of the equation data does not
087     * match the mapper dimension
088     */
089    public void insertEquationData(double[] equationData, double[] complete)
090        throws DimensionMismatchException {
091        if (equationData.length != dimension) {
092            throw new DimensionMismatchException(equationData.length, dimension);
093        }
094        System.arraycopy(equationData, 0, complete, firstIndex, dimension);
095    }
096}