HYPRE Sample SIDL File

This is a sample SIDL file from an experimental version of the hypre scalable linear solvers library.  Note that this file does not use exceptions or enumerate types.  For more information, see the 2001 SIAM Parallel Processing paper in the documentation directory of the Babel distribution..
/*
 * This is the HYPRE SIDL interface description file.  It is an example of a
 * SIDL description file.  This work was presented at the 2001 SIAM Parallel
 * Processing conference.  The authors are Andy Cleary, Jeff Painter, and Cal
 * Ribbens (from HYPRE) and Scott Kohn and Gary Kumfert (from Components).
 *
 * Questions about the syntax of this file should be directed to either Scott
 * or Gary at components@llnl.gov.
 */

/*
 * Many files will contain one or more import statements.  These import
 * statements are similar to Java in that they add the imported symbol name
 * to the default resolution path.  Since this SIDL file does not reference
 * any other packages, it does not contain an explicit version statement.
 * However, if it did want to reference the ESI specification, then it could
 * import the ESI as shown below.
 */
// import ESI;

/**
 * The <code>Hypre</code> package defines interfaces for an experimental
 * version of the HYPRE software package that used SIDL and Babel to generate
 * foreign language bindings.  Note that this is a <em>documentation</em>
 * comment.  As in Java, any symbol may be preceeded by a documentation
 * comment that is stored in the intermediate XML representation with that
 * symbol.  Babel tools automatically generate on-line documentation from
 * these comment descriptions (similar to <code>Javadoc</code>).  All SIDL
 * descriptions must begin with a <code>package</code> statement.
 */
package Hypre version 0.1.0 {

   /*
    * Note that this simple description does not contain any enumerated
    * types, exception objects, or parallel method directives.  Please
    * contact the components project at components@llnl.gov for more
    * information about these SIDL features.
    */

   /**
    * Wrap up the MPI communicator type in a class.  This should probably
    * be replaced with a long or opaque data type.
    */
   class MPI_Comm {
   }

   /**
    * Define a structured stencil for a structured problem description.
    */
   class StructStencil {
      /**
       * This is an example of method documentation.  Only a few methods
       * are documented in this file.
       */
      int SetDimension (in int dim);
      int SetSize (in int size);
      int SetElement (in int index, in array<int> offset);
   }

   /**
    * Define a structured grid object.
    */
   class StructGrid {
      int SetCommunicator (in MPI_Comm comm);
      int SetDimension (in int dim);
      int SetExtents (in array<int> ilower, in array<int> iupper);
      int SetPeriodic(in array<int> periodic);
      int Assemble();
   }

//
// -------------------------- Interfaces ---------------------------
//

   interface Object {
   }

   /**
    * Note the <code>extends</code> keyword that operates as in Java.
    */
   interface Vector extends Object {
      /**
       * y <- 0 (where y=self)
       */
      int Clear ();

      /**
       * y <- x
       */
      int Copy (in Vector x);

      /**
       * create an x compatible with y
       */
      int Clone (out Vector x);

      /**
       * y <- a*y
       */
      int Scale (in double a);

      /**
       * d <- (y,x)
       */
      int Dot (in Vector x, out double d);

      /**
       * y <- a*x + y
       */
      int Axpy (in double a, in Vector x);
   }

   /**
    * <p>The purpose of a ProblemDefinitionInterface is to:</p>
    * <ul>
    * <li>present the user with a particular view of how to define
    *     a problem</li>
    * <li>construct and return a "problem object"</li>
    * </ul>
    *
    * <p>A "problem object" is an intentionally vague term that corresponds
    * to any useful object used to define a problem.  Prime examples are:</p>
    * <ul>
    * <li>a LinearOperator object, i.e., something with a matvec</li>
    * <li>a MatrixAccess object, i.e., something with a getrow</li>
    * <li>a Vector, i.e., something with a dot, axpy, ...</li>
    * </ul>
    *
    * <p>Note that the terms "Initialize" and "Assemble" are reserved here
    * for defining problem objects through a particular user interface.</p>
    */
   interface ProblemDefinitionInterface extends Object {
      int SetCommunicator (in MPI_Comm comm);
      int Initialize ();           // "get ready to accept new values"
      int Assemble ();             // "done accepting new values"
      int GetConstructedObject (out Object A);
   }

   interface StructuredGridMatrixInterface extends ProblemDefinitionInterface {
      StructuredGridMatrixInterface New();
      int SetGrid (in StructGrid grid );
      int SetStencil (in StructStencil stencil );
      int SetValues (in array<int> index,
                     in int num_stencil_indices,
                     in array<int> stencil_indices,
                     in array<double> values);
      int SetBoxValues (in array<int> ilower,
                        in array<int> iupper,
                        in int num_stencil_indices,
                        in array<int> stencil_indices,
                        in array<double> values);
      int SetNumGhost (in array<int> num_ghost);
      int SetSymmetric (in int symmetric);
   }

   interface StructuredGridVectorInterface extends ProblemDefinitionInterface {
      StructuredGridVectorInterface New();
      int SetGrid (in StructGrid grid );
      int SetStencil (in StructStencil stencil );   // really needed?
      int SetValue (in array<int> grid_index, in double value);
      int SetBoxValues (in array<int> ilower,
                        in array<int> iupper,
                        in array<double> values);
   }

   interface IJMatrixInterface extends ProblemDefinitionInterface {
      IJMatrixInterface New();
      int SetGlobalSize (in int m, in int n);
      int SetLocalSize (in int m, in int n);
      int SetRowSizes (in array<int> sizes);
      int SetDiagRowSizes (in array<int> sizes);
      int SetOffDiagRowSizes (in array<int> sizes);
      int InsertRow(in int n, in int row, in array<int> cols,
                     in array<double> values);
      int AddToRow(in int n, in int row, in array<int> cols,
                     in array<double> values);
      int InsertBlock (in int m, in int n, in array<int> rows,
                       in array<int> cols, in array<double> values);
      int AddtoBlock(in int m, in int n,
                     in array<int> rows, in array<int> cols,
                     in array<double> values);
      int GetRowPartitioning (out array<int> partitioning);
  }

  interface IJVectorInterface extends ProblemDefinitionInterface {
     IJVectorInterface New();
     int SetGlobalSize (in int n);
     int SetPartitioning (in array<int> partitioning);
     int SetLocalComponents (in int num_values,
                             in array<int> glob_vec_indices,
                             in array<int> value_indices,
                             in array<double> values);
     int AddtoLocalComponents (in int num_values,
                               in array<int> glob_vec_indices,
                               in array<int> value_indices,
                               in array<double> values);
     int SetLocalComponentsInBlock (in int glob_vec_index_start,
                                    in int glob_vec_index_stop,
                                    in array<int> value_indices,
                                    in array<double> values);
     int AddToLocalComponentsInBlock (in int glob_vec_index_start,
                                      in int glob_vec_index_stop,
                                      in array<int> value_indices,
                                      in array<double> values);
  }

  /**
   * An Operator is anything that maps one Vector to another.
   * The terms "Setup" and "Apply" are reserved for Operators.
   */
  interface Operator extends Object {
     int SetCommunicator (in MPI_Comm comm);
     int SetParameter (in string name, in double value);
     int Setup ();
     int Apply (in Vector x, out Vector y);
  }

  interface Solver extends Operator {
     Solver New();
     int SetOperator (in Object A);
     int GetResidual (out Vector r);
  }

  interface PreconditionedSolver extends Solver {
     Solver New();                     // ok to over-ride new?
     int SetPreconditioner (in Solver s);
     int GetPreconditionedResidual (out Vector r);
  }

  interface MatrixAccess extends Object {
     int GetRow (in int row,
                 out int size,
                 out array<int> col_ind,         // inout?
                 out array<double> values);
  }

//
// -------------------------- Classes ---------------------------
//

  /**
   * The <code>implements-all</code> keyword is equivalent to the Java
   * <code>implements</code> keyword except that it also implicitly defines
   * all of the methods within the specified interface.  For example, the
   * following statement means that the structured matrix class implements
   * all of the methods in the structured grid matrix interface.  This form
   * is shorthand for using <code>implements</code> and then copying all of
   * the methods form the interface body into the class body.
   */
  class StructMatrixInterface implements-all StructuredGridMatrixInterface { }
  class StructVectorInterface implements-all StructuredGridVectorInterface { }
  class StructMatrix implements-all Operator { }
  class StructVector implements-all Vector {
     static void fooit();
  }

  class ParCSRMatrixInterface implements-all IJMatrixInterface { }
  class ParCSRVectorInterface implements-all IJVectorInterface { }
  class ParCSRMatrix implements-all Operator, MatrixAccess { }
  class ParCSRVector implements-all Vector { }

  /**
   * This class implements the StructuredGrid user interface, but builds
   * an unstructured matrix behind the curtain.  It does this by using
   * an IJMatrixBuilder (e.g., ParCSRMatrixBuilder, PETScMatrixBuilder, ...)
   * specified by the user with an extra method ...
   */
  class StructToIJMatrixInterface implements-all StructuredGridMatrixInterface {
     int SetIJMatrixInterface (in IJMatrixInterface I);
  }

  class StructToIJVectorInterface implements-all StructuredGridVectorInterface {
     int SetIJVectorInterface (in IJVectorInterface I);
  }

  class StructSMG implements-all Solver { }

  class ParAMG implements-all Solver { }

  class Pilut implements-all Solver { }

  class PCG implements-all PreconditionedSolver { }

  class GMRES implements-all PreconditionedSolver { }
}