API:IData

From Wiketomica
Jump to: navigation, search
API Home Participants API Discussion Demos Downloads Documentation Contact Us Acknowledgements

Reason for existence

We expect one of the primary reasons for communicating through the API is to pass some sort of numerical data. While we might always be able to express numerical data as an array of double-precision floating point numbers, there is often considerable additional information about the structure of the data. Having an IData interface would allow numerical data to be passed around without losing the structural information.

Proposed Interface

We propose an IData interface containing methods for setting and getting the numerical values wrapped by the object along with basic mathematical operations.

IData {

    /**
     * Deep-copies the data from the given object to this one.
     * 
     * @throws ClassCastException
     *             if the given data object is not of a type that can be copied
     *             to this one.
     */
    void E(in IData data);
    
    /**
     * Plus-equals (+=) operation.
     */
    void PE(in IData y);

    /**
     * Minus-equals (-=) operation.
     */
    void ME(in IData y);

    /**
     * Times-equals (*=) operation.
     */
    void TE(in IData y);

    /**
     * Divide-equals (/=) operation.
     */
    void DE(in IData y);

    /**
     * Equals (=) operation, sets all values in data equal to the given value.
     */
    void E(in double y);

    /**
     * Plus-equals (+=) operation, adding given value to all values in data.
     */
    void PE(in double y);

    /**
     * Times-equals (*=) operation, multiplying all values in data by given
     * value.
     */
    void TE(in double y);

    /**
     * Maps the function on all data values, replace each with the value given
     * by the function applied to it.
     */
    void map(in Function function);

    /**
     * Returns the number of values held by the data instance.
     */
    readonly attribute unsigned int length;

    /**
     * Returns the i-th data value.
     * 
     * @param i
     *            index of the desired data value
     * @return the data value
     * @throws IllegalArgumentException
     *             if i >= length
     */
    double getValue(in unsigned int i);

    /**
     * Fills the given array with the values held by this Data instance.
     * 
     * @throws IllegalArgumentException
     *             if the length of the array is not equal to length
     */
    void assignTo(in unsigned int aLength, [array, size_is(aLength)] in array);

    /**
     * Returns true if any data value is NaN (not a number),
     * or false if all data values are valid numbers.
     */
    boolean isNaN();
}

Rationale

The proposed interface allows components to receive numerical data and perform basic manipulations without the components being aware of the underlying structure of the contained data.

Use

We expect IDataSources to create and return IData objects, to be passed on through IDataPipes and finally to IDataSinks. Along with the IData, the IDataSource would also create and return an IDataInfo object containing additional information about the IData. IDataPipes would likely process the data, perhaps sending on a different instance of IData so as not to alter the IDataSource's copy.

Examples of concrete classes implementing the IData interface in Etomica include DataDouble (a scalar double), DataDoubleArray (a double array), DataGroup (a wrapper for multiple data objects, potentially heterogeneous), DataTable (a collection of DataDoubleArray "columns"), and DataFunction (DataDoubleArray representing y values, x values held by the corresponding DataInfoFunction object).

Notes

The mathematical operations (and isNaN) exist in Etomica's top-level Data interface primarily to allow arbitrary numerical data to be averaged. It's unclear that this constitutes a compelling reason to include them in the API.