001/* The integrator in the continuous domain.
002
003 Copyright (c) 1998-2015 The Regents of the University of California.
004 All rights reserved.
005 Permission is hereby granted, without written agreement and without
006 license or royalty fees, to use, copy, modify, and distribute this
007 software and its documentation for any purpose, provided that the above
008 copyright notice and the following two paragraphs appear in all copies
009 of this software.
010
011 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
012 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
013 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
014 THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
015 SUCH DAMAGE.
016
017 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
018 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
019 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
020 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
021 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
022 ENHANCEMENTS, OR MODIFICATIONS.
023
024 PT_COPYRIGHT_VERSION_2
025 COPYRIGHTENDKEY
026
027 */
028package ptolemy.domains.continuous.lib;
029
030import ptolemy.domains.continuous.kernel.ContinuousIntegrator;
031import ptolemy.kernel.CompositeEntity;
032import ptolemy.kernel.util.IllegalActionException;
033import ptolemy.kernel.util.NameDuplicationException;
034
035//////////////////////////////////////////////////////////////////////////
036//// Integrator
037
038/**
039 The integrator in the continuous domain.
040 <p>The <i>derivative</i> port receives the derivative of the state of the integrator
041 with respect to time. The <i>state</i> output port shows the state of the
042 integrator. So an ordinary differential equation (ODE),
043 dx/dt = f(x, t), can be built as follows:</p>
044 <pre>
045            +---------------+
046     dx/dt  |               |   x
047 +---------&gt;|   Integrator  |---------+-----&gt;
048 |          |               |         |
049 |          +----^-----^----+         |
050 |                                    |
051 |             |---------|            |
052 +-------------| f(x, t) |&lt;-----------+
053               |---------|
054 </pre>
055
056 <p> An integrator also has a port-parameter called <i>initialState</i>. The
057 parameter provides the initial state for integration during the initialization
058 stage of execution. If during execution an input token is provided on
059 the port, then the state of the integrator will be reset at that time
060 to the value of the token. The default value of the parameter is 0.0.</p>
061
062 <p> An integrator also has an input port named <i>impulse</i>.
063 When present, a token at the <i>impulse</i> input
064 port is interpreted as the weight of a Dirac delta function.
065 It cause an instantaneous increment or decrement to the state.
066 If both <i>impulse</i> and <i>initialState</i> have data, then
067 <i>initialState</i> dominates.</p>
068
069 <p> An integrator can generate an output (its current state) before
070 the derivative input is known, and hence can be used in feedback
071 loops like that above without creating a causality loop.
072 The <i>impulse</i> and <i>initialState</i> inputs
073 ports must be known, however, before an output can be produced.
074 The effect of data at these inputs on the output is instantaneous.</p>
075
076 <p>For different ODE solving methods, the functionality
077 of an integrator may be different. The delegation and strategy design
078 patterns are used in this class, the abstract ODESolver class, and the
079 concrete ODE solver classes. Some solver-dependent methods of integrators
080 delegate to the concrete ODE solvers.</p>
081
082 <p>An integrator can possibly have several auxiliary variables for the
083 the ODE solvers to use. The ODE solver class provides the number of
084 variables needed for that particular solver.
085 The auxiliary variables can be set and get by setAuxVariables()
086 and getAuxVariables() methods.</p>
087
088 <p>This class is based on the CTIntegrator by Jie Liu.</p>
089
090 @author Haiyang Zheng and Edward A. Lee
091 @version $Id$
092 @since Ptolemy II 6.0
093 @Pt.ProposedRating Green (hyzheng)
094 @Pt.AcceptedRating Green (eal)
095 */
096public class Integrator extends ContinuousIntegrator {
097
098    // NOTE: This is simply a wrapper for ContinuousIntegrator to make
099    // it appear in the lib package.
100
101    /** Construct an integrator.
102     *  @param container The container.
103     *  @param name The name.
104     *  @exception NameDuplicationException If the name is used by
105     *  another actor in the container.
106     *  @exception IllegalActionException If ports can not be created, or
107     *   thrown by the super class.
108     *  @see ptolemy.domains.continuous.kernel.ContinuousIntegrator
109     */
110    public Integrator(CompositeEntity container, String name)
111            throws NameDuplicationException, IllegalActionException {
112        super(container, name);
113    }
114}