sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1577592 - in /sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter: MatrixParameters.java TensorParameters.java
Date Fri, 14 Mar 2014 16:04:43 GMT
Author: desruisseaux
Date: Fri Mar 14 16:04:43 2014
New Revision: 1577592

URL: http://svn.apache.org/r1577592
Log:
Renamed MatrixParameters as TensorParameters, which describe better what the class is.

Added:
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/TensorParameters.java
      - copied, changed from r1577388, sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/MatrixParameters.java
Removed:
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/MatrixParameters.java

Copied: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/TensorParameters.java
(from r1577388, sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/MatrixParameters.java)
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/TensorParameters.java?p2=sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/TensorParameters.java&p1=sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/MatrixParameters.java&r1=1577388&r2=1577592&rev=1577592&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/MatrixParameters.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/TensorParameters.java
[UTF-8] Fri Mar 14 16:04:43 2014
@@ -43,18 +43,28 @@ import org.apache.sis.util.resources.Err
 
 /**
  * Creates parameter groups from tensors (usually matrices), and conversely.
- * Each group of parameters contains the following elements:
+ * Matrices are handled as a special case of tensors (<cite>second-order</cite>
tensors).
  *
+ * <p>Each group of parameters contains the following elements:</p>
  * <ul>
  *   <li>A mandatory parameter for the number of rows ({@code "num_row"} in WKT 1).</li>
  *   <li>A mandatory parameter for the number of columns ({@code "num_col"} in WKT
1).</li>
- *   <li>(<i>etc.</i> in third-order or higher-order tensors).</li>
- *   <li>A maximum of {@code num_row} × {@code num_col} × … optional parameters
for the matrix element values.
- *       Parameter names depend on the formatting convention. If a parameter is omitted,
then its default value
- *       is 1 for parameters on the diagonal and 0 for all other parameters.</li>
+ *   <li>(<i>etc.</i> for third-order or higher-order tensors).</li>
+ *   <li>A maximum of {@code num_row} × {@code num_col} × … optional parameters
for the matrix or tensor element values.
+ *       Parameter names depend on the formatting convention.</li>
  * </ul>
  *
- * The parameters format is typically like below:
+ * For all matrix or tensor elements, the default value is 1 for elements on the diagonal
(where all indices have
+ * the same value) and 0 for all other elements. Those default values defines an <cite>identity
matrix</cite>,
+ * or <cite>Kroenecker delta tensor</cite>.
+ *
+ * <p><b>Parameters are not an efficient storage format for large tensors.</b>
+ * Parameters are used only for small or sparse matrices/tensors to be specified in coordinate
operations or
+ * processing libraries. In particular, those parameters integrate well in <cite>Well
Known Text</cite> (WKT) format.
+ * For a more efficient matrix storage, see {@link org.apache.sis.referencing.operation.matrix.MatrixSIS}.</p>
+ *
+ * {@section Formatting}
+ * The parameters format for a matrix is typically like below:
  *
  * {@preformat wkt
  *   Parameter["num_row", 3],
@@ -71,21 +81,21 @@ import org.apache.sis.util.resources.Err
  *
  * Those groups are extensible, i.e. the number of <code>"elt_<var>row</var>_<var>col</var>"</code>
parameters
  * depends on the {@code "num_row"} and {@code "num_col"} parameter values. For this reason,
the descriptor of
- * matrix parameters is not immutable.
+ * matrix or tensor parameters is not immutable.
  *
  * @author  Martin Desruisseaux (IRD, Geomatys)
  * @since   0.4 (derived from geotk-2.0)
  * @version 0.4
  * @module
  */
-public class MatrixParameters implements Serializable {
+public class TensorParameters implements Serializable {
     /**
      * Serial number for inter-operability with different versions.
      */
     private static final long serialVersionUID = -7386537348359343836L;
 
     /**
-     * Parses and creates parameters names matching the
+     * Parses and creates parameters names for matrices matching the
      * <a href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/doc-files/WKT.html">Well
Known Text</a>
      * version 1 (WKT 1) convention.
      *
@@ -97,7 +107,7 @@ public class MatrixParameters implements
      *
      * <div class="note"><b>Example:</b> {@code "elt_2_1"} is the element
name for the value at line 2 and row 1.</div>
      */
-    public static final MatrixParameters WKT1;
+    public static final TensorParameters WKT1;
     static {
         /*
          * Note: the upper limit given in the operation parameters is arbitrary. A high
@@ -115,36 +125,45 @@ public class MatrixParameters implements
         numRow = new DefaultParameterDescriptor<>(properties, Integer.class, valueDomain,
null, defaultSize, true);
         properties.put(ReferenceIdentifier.CODE_KEY, "num_col");
         numCol = new DefaultParameterDescriptor<>(properties, Integer.class, valueDomain,
null, defaultSize, true);
-        WKT1 = new MatrixParameters("elt_", "_", numRow, numCol);
+        WKT1 = new TensorParameters("elt_", "_", numRow, numCol);
     }
 
     /**
      * The height and weight of the matrix of {@link #parameters} to cache. Descriptors
      * for row or column indices greater than or equal to this value will not be cached.
+     * A small value is sufficient since matrix sizes are usually the maximum number of
+     * CRS dimensions (usually 4) plus one.
+     */
+    private static final int CACHE_SIZE = 5;
+
+    /**
+     * Maximal cache rank. Memory required by the cache will be {@code pow(CACHE_SIZE, CACHE_RANK)},
+     * so that value is better to be small.
      */
-    private static final int CACHE_SIZE = 8;
+    private static final int CACHE_RANK = 3;
 
     /**
-     * The parameters that define the number of rows and columns.
+     * The parameters that define the number of rows, columns or other dimensions.
      * In WKT1, the parameter names are {@code "num_row"} and {@code "num_col"} respectively.
+     *
+     * <p>The length of this array determine the tensor {@linkplain #rank() rank}.</p>
      */
-    private final ParameterDescriptor<Integer>[] size;
+    private final ParameterDescriptor<Integer>[] dimensions;
 
     /**
-     * The cached descriptors for each elements in a matrix. Descriptors do not depend on
matrix element values.
+     * The cached descriptors for each elements in a tensor. Descriptors do not depend on
tensor element values.
      * Consequently, the same descriptors can be reused for all {@link MatrixParameterValues}
instances.
      */
-    @SuppressWarnings({"unchecked","rawtypes"})
-    private final transient ParameterDescriptor<Double>[] parameters = new ParameterDescriptor[CACHE_SIZE
* CACHE_SIZE];
+    private final transient ParameterDescriptor<Double>[] parameters;
 
     /**
-     * The prefix of parameter names for matrix elements.
+     * The prefix of parameter names for tensor elements.
      * This is {@code "elt_"} in WKT 1.
      */
     protected final String prefix;
 
     /**
-     * The separator between row and column in parameter names for matrix elements.
+     * The separator between row and column in parameter names for tensor elements.
      * This is {@code "_"} in WKT 1.
      */
     protected final String separator;
@@ -152,26 +171,61 @@ public class MatrixParameters implements
     /**
      * Constructs a descriptors provider.
      *
-     * @param prefix     The prefix to insert in front of parameter name for each matrix
elements.
-     * @param separator  The separator between the row and the column index in parameter
names.
-     * @param size       The parameter for the number of rows and columns, usually in an
array of length 2.
+     * @param prefix     The prefix to insert in front of parameter name for each tensor
elements.
+     * @param separator  The separator between dimension (row, column, …) indices in parameter
names.
+     * @param dimensions The parameter for the size of each dimension, usually in an array
of length 2.
      *                   Length may be different if the caller wants to generalize usage
of this class to tensors.
      */
     @SafeVarargs
     @SuppressWarnings({"unchecked", "rawtypes"})
-    public MatrixParameters(final String prefix, final String separator, final ParameterDescriptor<Integer>...
size) {
-        ArgumentChecks.ensureNonNull("prefix",    prefix);
-        ArgumentChecks.ensureNonNull("separator", separator);
-        ArgumentChecks.ensureNonNull("size",      size);
-        if (size.length == 0) {
-            throw new IllegalArgumentException(Errors.format(Errors.Keys.EmptyArgument_1,
"size"));
-        }
-        this.prefix    = prefix;
-        this.separator = separator;
-        this.size      = new ParameterDescriptor[size.length];
-        for (int i=0; i<size.length; i++) {
-            ArgumentChecks.ensureNonNullElement("size", i, this.size[i] = size[i]);
+    public TensorParameters(final String prefix, final String separator, final ParameterDescriptor<Integer>...
dimensions) {
+        ArgumentChecks.ensureNonNull("prefix",     prefix);
+        ArgumentChecks.ensureNonNull("separator",  separator);
+        ArgumentChecks.ensureNonNull("dimensions", dimensions);
+        if (dimensions.length == 0) {
+            throw new IllegalArgumentException(Errors.format(Errors.Keys.EmptyArgument_1,
"dimensions"));
+        }
+        this.prefix     = prefix;
+        this.separator  = separator;
+        this.dimensions = new ParameterDescriptor[dimensions.length];
+        for (int i=0; i<dimensions.length; i++) {
+            ArgumentChecks.ensureNonNullElement("dimensions", i, this.dimensions[i] = dimensions[i]);
         }
+        parameters = createCache(dimensions.length);
+    }
+
+    /**
+     * Creates an initially empty {@link #parameters} array. This method is invoked by constructor
+     * and on deserialization.
+     */
+    @SuppressWarnings({"unchecked", "rawtypes"})
+    private static ParameterDescriptor<Double>[] createCache(int rank) {
+        if (rank > CACHE_RANK) {
+            rank = CACHE_RANK;
+        }
+        int length = 1;
+        while (--rank >= 0) {
+            length *= CACHE_SIZE;
+        }
+        return new ParameterDescriptor[length];
+    }
+
+    /**
+     * Returns the rank of the tensor objects for which this instance will create parameters.
+     * The rank determines the type of objects represented by the parameter:
+     *
+     * <table class="sis">
+     *   <tr><th>Rank</th> <th>Type</th></tr>
+     *   <tr><td>0</td>    <td>scalar</td></tr>
+     *   <tr><td>1</td>    <td>vector</td></tr>
+     *   <tr><td>2</td>    <td>matrix</td></tr>
+     *   <tr><td><var>k</var></td><td>rank <var>k</var>
tensor</td></tr>
+     * </table>
+     *
+     * @return The rank of the tensors for which to create parameters.
+     */
+    public final int rank() {
+        return dimensions.length;
     }
 
     /**
@@ -180,15 +234,12 @@ public class MatrixParameters implements
      * parsable by the {@link #parseElementName(String)} method.
      *
      * {@section Default implementation}
-     * The default implementation requires an {@code indices} array having the same length
than the {@code size} array
-     * specified at construction time. That length is usually 2, where {@code indices[0]}
is the <var>row</var> index
-     * and {@code indices[1]} is the <var>column</var> index. Then this method
builds a name with the "{@link #prefix}
-     * + <var>row</var> + {@link #separator} + <var>column</var>
+ …" pattern (e.g. {@code "elt_0_0"}).
+     * The default implementation requires an {@code indices} array having a length equals
to the {@linkplain #rank()
+     * rank}. That length is usually 2, where {@code indices[0]} is the <var>row</var>
index and {@code indices[1]} is
+     * the <var>column</var> index. Then this method builds a name with the “{@link
#prefix} + <var>row</var> +
+     * {@link #separator} + <var>column</var> + …” pattern (e.g. {@code "elt_0_0"}).
      * Finally this method creates a descriptor for an optional parameter of that name.
      *
-     * <div class="note"><b>Note:</b> matrices can been seen as a special
case of tensors with indices arrays
-     * of length 2 (i.e. <cite>second-order</cite> tensor).</div>
-     *
      * {@section Subclassing}
      * If a subclass overrides this method for creating parameters with different names,
then that subclass shall
      * also override {@link #parseElementName(String)} for parsing those names.
@@ -200,9 +251,9 @@ public class MatrixParameters implements
      * @see #parseElementName(String)
      */
     protected ParameterDescriptor<Double> createElementDescriptor(final int[] indices)
throws IllegalArgumentException {
-        if (indices.length != size.length) {
+        if (indices.length != dimensions.length) {
             throw new IllegalArgumentException(Errors.format(
-                    Errors.Keys.UnexpectedArrayLength_2, size.length, indices.length));
+                    Errors.Keys.UnexpectedArrayLength_2, dimensions.length, indices.length));
         }
         final StringBuilder name = new StringBuilder();
         String s = prefix;
@@ -216,7 +267,7 @@ public class MatrixParameters implements
         }
         final Map<String,Object> properties = new HashMap<>(4);
         properties.put(ReferenceIdentifier.CODE_KEY, name.toString());
-        properties.put(ReferenceIdentifier.AUTHORITY_KEY, size[0].getName().getAuthority());
+        properties.put(ReferenceIdentifier.AUTHORITY_KEY, dimensions[0].getName().getAuthority());
         return new DefaultParameterDescriptor<>(properties, Double.class, null, null,
isDiagonal ? 1.0 : 0.0, false);
     }
 
@@ -260,7 +311,7 @@ public class MatrixParameters implements
     /**
      * Returns {@code true} if all array elements starting at index 2 are 0.
      * Used only in order to determine if we can cache a descriptor, because
-     * we limit the cache to a two-dimensional plane.
+     * we limit the cache to a two-rank case.
      */
     private static boolean zeroTail(final int[] indices) {
         for (int i=2; i<indices.length; i++) {
@@ -276,8 +327,8 @@ public class MatrixParameters implements
      * This method is the converse of {@link #createElementDescriptor(int[])}.
      *
      * {@section Default implementation}
-     * The default implementation expects a name matching the "{@link #prefix} + <var>row</var>
+ {@link #separator} +
-     * <var>column</var> + …" pattern and returns an array containing the <var>row</var>,
<var>column</var> and other
+     * The default implementation expects a name matching the “{@link #prefix} + <var>row</var>
+ {@link #separator} +
+     * <var>column</var> + …” pattern and returns an array containing the
<var>row</var>, <var>column</var> and other
      * indices, in that order.
      *
      * @param  name The parameter name to parse.
@@ -290,7 +341,7 @@ public class MatrixParameters implements
         if (!name.regionMatches(true, 0, prefix, 0, s)) {
             return null;
         }
-        final int[] indices = new int[size.length];
+        final int[] indices = new int[dimensions.length];
         final int last = indices.length - 1;
         for (int i=0; i<last; i++) {
             final int split = name.indexOf(separator, s);
@@ -308,7 +359,7 @@ public class MatrixParameters implements
      * Returns the descriptor in this group for the specified name.
      *
      * @param  name The case insensitive name of the parameter to search for.
-     * @param  actualSize The current values of parameters that define the matrix (or tensor)
size.
+     * @param  actualSize The current values of parameters that define the matrix (or tensor)
dimensions.
      * @return The parameter for the given name.
      * @throws ParameterNotFoundException if there is no parameter for the given name.
      */
@@ -332,7 +383,7 @@ public class MatrixParameters implements
          * Verify if the requested parameters is one of those that
          * specify the matrix/tensor size ("num_row" or "num_col").
          */
-        for (final ParameterDescriptor<Integer> param : size) {
+        for (final ParameterDescriptor<Integer> param : dimensions) {
             if (IdentifiedObjects.isHeuristicMatchForName(param, name)) {
                 return param;
             }
@@ -347,7 +398,7 @@ public class MatrixParameters implements
      * Returns {@code true} if the given indices are not out-of-bounds.
      *
      * @param indices    The indices parsed from a parameter name.
-     * @param actualSize The current values of parameters that define the matrix (or tensor)
size.
+     * @param actualSize The current values of parameters that define the matrix (or tensor)
dimensions.
      */
     private static boolean isInBounds(final int[] indices, final int[] actualSize) {
         for (int i=0; i<indices.length; i++) {
@@ -360,28 +411,28 @@ public class MatrixParameters implements
     }
 
     /**
-     * Returns all parameters in this group for a tensor of the specified size.
+     * Returns all parameters in this group for a tensor of the specified dimensions.
      *
-     * @param  actualSize The current values of parameters that define the matrix (or tensor)
size.
+     * @param  actualSize The current values of parameters that define the matrix (or tensor)
dimensions.
      *         It is caller's responsibility to ensure that this array does not contain negative
values.
      * @return The matrix parameters, including all elements.
      */
     final List<GeneralParameterDescriptor> descriptors(final int[] actualSize) {
-        final int dimension = size.length; // 2 for a matrix, may be higher for a tensor.
+        final int rank = dimensions.length; // 2 for a matrix, may be higher for a tensor.
         int length = actualSize[0];
-        for (int i=1; i<dimension; i++) {
+        for (int i=1; i<rank; i++) {
             length *= actualSize[i];
         }
-        final GeneralParameterDescriptor[] parameters = new GeneralParameterDescriptor[dimension
+ length];
-        System.arraycopy(size, 0, parameters, 0, dimension);
-        final int[] indices = new int[dimension];
+        final GeneralParameterDescriptor[] parameters = new GeneralParameterDescriptor[rank
+ length];
+        System.arraycopy(dimensions, 0, parameters, 0, rank);
+        final int[] indices = new int[rank];
         /*
          * Iterates on all possible index values. Indes on the right side (usually the column
index)
          * will vary faster, and index on the left side (usually the row index) will vary
slowest.
          */
         for (int i=0; i<length; i++) {
-            parameters[dimension + i] = descriptor(indices);
-            for (int j=dimension; --j >= 0;) {
+            parameters[rank + i] = descriptor(indices);
+            for (int j=rank; --j >= 0;) {
                 if (++indices[j] < actualSize[j]) {
                     break;
                 }
@@ -404,8 +455,8 @@ public class MatrixParameters implements
 //  }
 
     /**
-     * Constructs a matrix from a group of parameters. This operation is allowed only if
this
-     * {@code MatrixParameters} has been created with a {@code size} array of length 2.
+     * Constructs a matrix from a group of parameters.
+     * This operation is allowed only for tensor of {@linkplain #rank() rank} 2.
      *
      * @param  parameters The group of parameters.
      * @return A matrix constructed from the specified group of parameters.
@@ -413,7 +464,7 @@ public class MatrixParameters implements
      */
     public Matrix getMatrix(final ParameterValueGroup parameters) throws InvalidParameterNameException
{
         ArgumentChecks.ensureNonNull("parameters", parameters);
-        if (size.length != 2) {
+        if (dimensions.length != 2) {
             throw new IllegalStateException();
         }
 //      if (parameters instanceof MatrixParameterValues) {
@@ -421,8 +472,8 @@ public class MatrixParameters implements
 //          return ((MatrixParameterValues) parameters).getMatrix();
 //      }
         // Fallback on the general case (others implementations)
-        final ParameterValue<?> numRow = parameters.parameter(size[0].getName().getCode());
-        final ParameterValue<?> numCol = parameters.parameter(size[1].getName().getCode());
+        final ParameterValue<?> numRow = parameters.parameter(dimensions[0].getName().getCode());
+        final ParameterValue<?> numCol = parameters.parameter(dimensions[1].getName().getCode());
         final Matrix matrix = Matrices.createDiagonal(numRow.intValue(), numCol.intValue());
         final List<GeneralParameterValue> values = parameters.values();
         if (values != null) {



Mime
View raw message