org.apache.commons.math3.ode.FirstOrderFieldIntegrator Maven / Gradle / Ivy
Show all versions of commons-math3 Show documentation
/*
* 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.math3.ode;
import java.util.Collection;
import org.apache.commons.math3.RealFieldElement;
import org.apache.commons.math3.analysis.solvers.BracketedRealFieldUnivariateSolver;
import org.apache.commons.math3.exception.MaxCountExceededException;
import org.apache.commons.math3.exception.NoBracketingException;
import org.apache.commons.math3.exception.NumberIsTooSmallException;
import org.apache.commons.math3.ode.events.FieldEventHandler;
import org.apache.commons.math3.ode.sampling.FieldStepHandler;
/** This interface represents a first order integrator for
* differential equations.
* The classes which are devoted to solve first order differential
* equations should implement this interface. The problems which can
* be handled should implement the {@link
* FirstOrderDifferentialEquations} interface.
*
* @see FirstOrderFieldDifferentialEquations
* @param the type of the field elements
* @since 3.6
*/
public interface FirstOrderFieldIntegrator> {
/** Get the name of the method.
* @return name of the method
*/
String getName();
/** Add a step handler to this integrator.
* The handler will be called by the integrator for each accepted
* step.
* @param handler handler for the accepted steps
* @see #getStepHandlers()
* @see #clearStepHandlers()
*/
void addStepHandler(FieldStepHandler handler);
/** Get all the step handlers that have been added to the integrator.
* @return an unmodifiable collection of the added events handlers
* @see #addStepHandler(FieldStepHandler)
* @see #clearStepHandlers()
*/
Collection> getStepHandlers();
/** Remove all the step handlers that have been added to the integrator.
* @see #addStepHandler(FieldStepHandler)
* @see #getStepHandlers()
*/
void clearStepHandlers();
/** Add an event handler to the integrator.
*
* The default solver is a 5th order {@link
* org.apache.commons.math3.analysis.solvers.FieldBracketingNthOrderBrentSolver}.
*
* @param handler event handler
* @param maxCheckInterval maximal time interval between switching
* function checks (this interval prevents missing sign changes in
* case the integration steps becomes very large)
* @param convergence convergence threshold in the event time search
* @param maxIterationCount upper limit of the iteration count in
* the event time search events.
* @see #addEventHandler(FieldEventHandler, double, double, int,
* org.apache.commons.math3.analysis.solvers.BracketedRealFieldUnivariateSolver)
* @see #getEventHandlers()
* @see #clearEventHandlers()
*/
void addEventHandler(FieldEventHandler handler, double maxCheckInterval,
double convergence, int maxIterationCount);
/** Add an event handler to the integrator.
* @param handler event handler
* @param maxCheckInterval maximal time interval between switching
* function checks (this interval prevents missing sign changes in
* case the integration steps becomes very large)
* @param convergence convergence threshold in the event time search
* @param maxIterationCount upper limit of the iteration count in
* the event time search events.
* @param solver solver to use to locate the event
* @see #addEventHandler(FieldEventHandler, double, double, int)
* @see #getEventHandlers()
* @see #clearEventHandlers()
*/
void addEventHandler(FieldEventHandler handler, double maxCheckInterval,
double convergence, int maxIterationCount,
BracketedRealFieldUnivariateSolver solver);
/** Get all the event handlers that have been added to the integrator.
* @return an unmodifiable collection of the added events handlers
* @see #addEventHandler(FieldEventHandler, double, double, int)
* @see #clearEventHandlers()
*/
Collection > getEventHandlers();
/** Remove all the event handlers that have been added to the integrator.
* @see #addEventHandler(FieldEventHandler, double, double, int)
* @see #getEventHandlers()
*/
void clearEventHandlers();
/** Get the current value of the step start time ti.
* This method can be called during integration (typically by
* the object implementing the {@link FirstOrderDifferentialEquations
* differential equations} problem) if the value of the current step that
* is attempted is needed.
* The result is undefined if the method is called outside of
* calls to integrate.
* @return current value of the state at step start time ti
*/
FieldODEStateAndDerivative getCurrentStepStart();
/** Get the current signed value of the integration stepsize.
* This method can be called during integration (typically by
* the object implementing the {@link FirstOrderDifferentialEquations
* differential equations} problem) if the signed value of the current stepsize
* that is tried is needed.
* The result is undefined if the method is called outside of
* calls to integrate.
* @return current signed value of the stepsize
*/
T getCurrentSignedStepsize();
/** Set the maximal number of differential equations function evaluations.
* The purpose of this method is to avoid infinite loops which can occur
* for example when stringent error constraints are set or when lots of
* discrete events are triggered, thus leading to many rejected steps.
* @param maxEvaluations maximal number of function evaluations (negative
* values are silently converted to maximal integer value, thus representing
* almost unlimited evaluations)
*/
void setMaxEvaluations(int maxEvaluations);
/** Get the maximal number of functions evaluations.
* @return maximal number of functions evaluations
*/
int getMaxEvaluations();
/** Get the number of evaluations of the differential equations function.
*
* The number of evaluations corresponds to the last call to the
* integrate method. It is 0 if the method has not been called yet.
*
* @return number of evaluations of the differential equations function
*/
int getEvaluations();
/** Integrate the differential equations up to the given time.
* This method solves an Initial Value Problem (IVP).
* Since this method stores some internal state variables made
* available in its public interface during integration ({@link
* #getCurrentSignedStepsize()}), it is not thread-safe.
* @param equations differential equations to integrate
* @param initialState initial state (time, primary and secondary state vectors)
* @param finalTime target time for the integration
* (can be set to a value smaller than {@code t0} for backward integration)
* @return final state, its time will be the same as {@code finalTime} if
* integration reached its target, but may be different if some {@link
* org.apache.commons.math3.ode.events.FieldEventHandler} stops it at some point.
* @exception NumberIsTooSmallException if integration step is too small
* @exception MaxCountExceededException if the number of functions evaluations is exceeded
* @exception NoBracketingException if the location of an event cannot be bracketed
*/
FieldODEStateAndDerivative integrate(FieldExpandableODE equations,
FieldODEState initialState, T finalTime)
throws NumberIsTooSmallException, MaxCountExceededException, NoBracketingException;
}