001/* An actor that converts a FixToken into another FixToken with possibly
002 different precision.
003
004 Copyright (c) 1998-2014 The Regents of the University of California.
005 All rights reserved.
006 Permission is hereby granted, without written agreement and without
007 license or royalty fees, to use, copy, modify, and distribute this
008 software and its documentation for any purpose, provided that the above
009 copyright notice and the following two paragraphs appear in all copies
010 of this software.
011
012 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
013 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
014 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
015 THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
016 SUCH DAMAGE.
017
018 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
019 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
020 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
021 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
022 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
023 ENHANCEMENTS, OR MODIFICATIONS.
024
025 PT_COPYRIGHT_VERSION_2
026 COPYRIGHTENDKEY
027
028 */
029package ptolemy.actor.lib.conversions;
030
031import ptolemy.data.FixToken;
032import ptolemy.data.IntMatrixToken;
033import ptolemy.data.expr.Parameter;
034import ptolemy.data.type.BaseType;
035import ptolemy.data.type.FixType;
036import ptolemy.kernel.CompositeEntity;
037import ptolemy.kernel.util.Attribute;
038import ptolemy.kernel.util.IllegalActionException;
039import ptolemy.kernel.util.NameDuplicationException;
040import ptolemy.kernel.util.StringAttribute;
041import ptolemy.kernel.util.Workspace;
042import ptolemy.math.FixPoint;
043import ptolemy.math.FixPointQuantization;
044import ptolemy.math.Overflow;
045import ptolemy.math.Precision;
046import ptolemy.math.Rounding;
047
048///////////////////////////////////////////////////////////////////
049//// FixToFix
050
051/**
052 This actor converts a FixToken into another FixToken with a specified
053 precision. Note that this conversion may be lossy, in that the output
054 may be an approximation of the input. The approximation can be
055 constructed using a variety of rounding and overflow strategies,
056 <p>
057 The precision of the output is given by the <i>precision</i> parameter,
058 which is an integer matrix of the form [<i>m</i>, <i>n</i>], where
059 the total number of bits in the output is <i>m</i>, of which
060 <i>n</i> are integer bits. The default precision is [16, 2], which means
061 that an output has 16 bits, of which 2 bits represent the
062 integer part.
063 <p>
064 The rounding strategy is defined by the <i>rounding</i> parameter and
065 defaults to <i>nearest</i> (or <i>half_floor</i>), selecting the nearest
066 representable value. The floor value nearer to minus infinity is used
067 for values half way between representable values. Other strategies
068 such as <i>truncate</i> are described under ptolemy.math.Rounding.
069 <p>
070 The overflow strategy is defined by the <i>overflow</i> parameter and
071 defaults to <i>saturate</i> (or <i>clip</i>). Out of range values are
072 saturated to the nearest representable value. Other strategies
073 such as <i>modulo</i> are described under ptolemy.math.Overflow.
074
075 @author Bart Kienhuis, Edward A. Lee, Ed Willink
076 @version $Id$
077 @since Ptolemy II 1.0
078 @Pt.ProposedRating Green (pwhitake)
079 @Pt.AcceptedRating Green (pwhitake)
080 @see ptolemy.data.FixToken
081 @see ptolemy.math.Overflow
082 @see ptolemy.math.Precision
083 @see ptolemy.math.Rounding
084 */
085public class FixToFix extends Converter {
086    /** Construct an actor with the given container and name.
087     *  @param container The container.
088     *  @param name The name of this actor.
089     *  @exception IllegalActionException If the actor cannot be contained
090     *   by the proposed container.
091     *  @exception NameDuplicationException If the container already has an
092     *   actor with this name.
093     */
094    public FixToFix(CompositeEntity container, String name)
095            throws NameDuplicationException, IllegalActionException {
096        super(container, name);
097        input.setTypeAtMost(BaseType.UNSIZED_FIX);
098        output.setTypeEquals(BaseType.UNSIZED_FIX);
099
100        precision = new Parameter(this, "precision");
101        precision.setTypeEquals(BaseType.INT_MATRIX);
102        precision.setExpression("[16, 2]");
103
104        rounding = new StringAttribute(this, "rounding");
105        rounding.setExpression("nearest");
106
107        overflow = new StringAttribute(this, "overflow");
108        overflow.setExpression("saturate");
109    }
110
111    ///////////////////////////////////////////////////////////////////
112    ////                     ports and parameters                  ////
113
114    /** The precision of the output fix-point number, represented by an
115     integer matrix. */
116    public Parameter precision;
117
118    /** The rounding strategy used, such as "nearest" or "truncate". */
119    public StringAttribute rounding;
120
121    /** The overflow strategy used to convert a double into a fix point,
122     such as "saturate" or "to_zero". */
123    public StringAttribute overflow;
124
125    ///////////////////////////////////////////////////////////////////
126    ////                         public methods                    ////
127
128    /** Override the base class to set locally cached variables.
129     *  @param attribute The attribute that changed.
130     *  @exception IllegalActionException If the parameter value is invalid.
131     */
132    @Override
133    public void attributeChanged(Attribute attribute)
134            throws IllegalActionException {
135        if (attribute == precision) {
136            IntMatrixToken token = (IntMatrixToken) precision.getToken();
137
138            if (token.getRowCount() != 1 || token.getColumnCount() != 2) {
139                throw new IllegalActionException(this,
140                        "Invalid precision (not a 1 by 2 matrix).");
141            }
142
143            Precision precision = new Precision(token.getElementAt(0, 0),
144                    token.getElementAt(0, 1));
145            _quantization = _quantization.setPrecision(precision);
146            if (_quantization.getOverflow() == Overflow.GROW) {
147                output.setTypeEquals(BaseType.UNSIZED_FIX);
148            } else {
149                output.setTypeEquals(new FixType(_quantization.getPrecision()));
150            }
151        } else if (attribute == rounding) {
152            Rounding r = Rounding.getName(rounding.getExpression());
153            _quantization = _quantization.setRounding(r);
154        } else if (attribute == overflow) {
155            Overflow o = Overflow.forName(overflow.getExpression());
156            _quantization = _quantization.setOverflow(o);
157            if (_quantization.getOverflow() == Overflow.GROW) {
158                output.setTypeEquals(BaseType.UNSIZED_FIX);
159            } else {
160                output.setTypeEquals(new FixType(_quantization.getPrecision()));
161            }
162        } else {
163            super.attributeChanged(attribute);
164        }
165    }
166
167    /** Clone the actor into the specified workspace. This calls the
168     *  base class and then sets the value public variable in the new
169     *  object to equal the cloned parameter in that new object.
170     *  @param workspace The workspace for the new object.
171     *  @return A new actor.
172     *  @exception CloneNotSupportedException If a derived class contains
173     *   an attribute that cannot be cloned.
174     */
175    @Override
176    public Object clone(Workspace workspace) throws CloneNotSupportedException {
177        FixToFix newObject = (FixToFix) super.clone(workspace);
178
179        // Set the type constraint.
180        newObject.input.setTypeAtMost(BaseType.UNSIZED_FIX);
181
182        // The non-primitive fields of the clone must refer to objects
183        // distinct from the objects of the same name in the class.
184        // If this is not done, then there may be problems with actor
185        // oriented classes.
186        newObject._quantization = new FixPointQuantization(
187                newObject._quantization.getPrecision(),
188                newObject._quantization.getOverflow(),
189                newObject._quantization.getRounding());
190
191        return newObject;
192    }
193
194    /** Read at most one token from the input and convert it to a fixed-point
195     *  value with the precision given by the <i>precision</i> parameter,
196     *  overflow strategy given by the <i>overflow</i> parameter,
197     *  and rounding strategy given by the <i>rounding</i> parameter.
198     *  @exception IllegalActionException If there is no director.
199     */
200    @Override
201    public void fire() throws IllegalActionException {
202        super.fire();
203        FixToken in = (FixToken) input.get(0);
204        FixPoint fixValue = in.fixValue().quantize(_quantization);
205        FixToken result = new FixToken(fixValue);
206        output.send(0, result);
207    }
208
209    /** Return false if the input port has no token, otherwise return
210     *  what the superclass returns (presumably true).
211     *  @exception IllegalActionException If there is no director.
212     */
213    @Override
214    public boolean prefire() throws IllegalActionException {
215        if (!input.hasToken(0)) {
216            return false;
217        }
218
219        return super.prefire();
220    }
221
222    ///////////////////////////////////////////////////////////////////
223    ////                         private variables                 ////
224    // The quantization of the output.
225    private FixPointQuantization _quantization = new FixPointQuantization(
226            new Precision(0, 0), Overflow.SATURATE, Rounding.NEAREST);
227}