1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package org.apache.commons.math.ode; 19 20 /** This interface represents a first order integrator for 21 * differential equations. 22 23 * <p>The classes which are devoted to solve first order differential 24 * equations should implement this interface. The problems which can 25 * be handled should implement the {@link 26 * FirstOrderDifferentialEquations} interface.</p> 27 * 28 * @see FirstOrderDifferentialEquations 29 * @see StepHandler 30 * @see SwitchingFunction 31 * @version $Revision: 620312 $ $Date: 2008-02-10 12:28:59 -0700 (Sun, 10 Feb 2008) $ 32 * @since 1.2 33 */ 34 35 public interface FirstOrderIntegrator { 36 37 /** Get the name of the method. 38 * @return name of the method 39 */ 40 public String getName(); 41 42 /** Set the step handler for this integrator. 43 * The handler will be called by the integrator for each accepted 44 * step. 45 * @param handler handler for the accepted steps 46 */ 47 public void setStepHandler (StepHandler handler); 48 49 /** Get the step handler for this integrator. 50 * @return the step handler for this integrator 51 */ 52 public StepHandler getStepHandler(); 53 54 /** Add a switching function to the integrator. 55 * @param function switching function 56 * @param maxCheckInterval maximal time interval between switching 57 * function checks (this interval prevents missing sign changes in 58 * case the integration steps becomes very large) 59 * @param convergence convergence threshold in the event time search 60 * @param maxIterationCount upper limit of the iteration count in 61 * the event time search 62 */ 63 public void addSwitchingFunction(SwitchingFunction function, 64 double maxCheckInterval, 65 double convergence, 66 int maxIterationCount); 67 68 /** Integrate the differential equations up to the given time. 69 * <p>This method solves an Initial Value Problem (IVP).</p> 70 * <p>Since this method stores some internal state variables made 71 * available in its public interface during integration ({@link 72 * #getCurrentSignedStepsize()}), it is <em>not</em> thread-safe.</p> 73 * @param equations differential equations to integrate 74 * @param t0 initial time 75 * @param y0 initial value of the state vector at t0 76 * @param t target time for the integration 77 * (can be set to a value smaller than <code>t0</code> for backward integration) 78 * @param y placeholder where to put the state vector at each successful 79 * step (and hence at the end of integration), can be the same object as y0 80 * @throws IntegratorException if the integrator cannot perform integration 81 * @throws DerivativeException this exception is propagated to the caller if 82 * the underlying user function triggers one 83 */ 84 public void integrate (FirstOrderDifferentialEquations equations, 85 double t0, double[] y0, 86 double t, double[] y) 87 throws DerivativeException, IntegratorException; 88 89 /** Get the current value of the step start time t<sub>i</sub>. 90 * <p>This method can be called during integration (typically by 91 * the object implementing the {@link FirstOrderDifferentialEquations 92 * differential equations} problem) if the value of the current step that 93 * is attempted is needed.</p> 94 * <p>The result is undefined if the method is called outside of 95 * calls to {@link #integrate}</p> 96 * @return current value of the step start time t<sub>i</sub> 97 */ 98 public double getCurrentStepStart(); 99 100 /** Get the current signed value of the integration stepsize. 101 * <p>This method can be called during integration (typically by 102 * the object implementing the {@link FirstOrderDifferentialEquations 103 * differential equations} problem) if the signed value of the current stepsize 104 * that is tried is needed.</p> 105 * <p>The result is undefined if the method is called outside of 106 * calls to {@link #integrate}</p> 107 * @return current signed value of the stepsize 108 */ 109 public double getCurrentSignedStepsize(); 110 111 }