package petsc;

/**
 * Distributed arrays ( DAs), which are used in conjunction with PETSc 
 * vectors, are intended for use with logically regular rectangular grids when
 * communication of nonlocal data is needed before certain local computations 
 * can occur. PETSc distributed arrays are designed only for the case in which
 * data can be thought of as being stored in a standard multidimensional 
 * array; thus, DAs are not intended for parallelizing unstructured grid 
 * problems, etc. DAs are intended for communicating vector (field) 
 * information; they are not intended for storing matrices.     
 */
final public class DA
    extends PetscObject
    implements Constants, InsertMode, NormType 
{
  public static final int NONPERIODIC = 0;
  public static final int XPERIODIC = 1;
  public static final int YPERIODIC = 2;
  public static final int XYPERIODIC = 3;

  public static final int STENCIL_STAR = 0;
  public static final int STENCIL_BOX = 1;

  /**
   * creates a 1-d distributed array.
   * @param comm the communicator to use (Comm.self or Comm.world)
   * @param wrap the type of periodicity the array should have, if any.
   * This is a constant from the set {DA_NONPERIODIC, DA_XPERIODIC, 
   * DA_YPERIODIC, DA_XYPERIODIC}.
   * @param M the global dimension of the array
   * @param dof number of degrees of freedom per node
   * @param s stencil width
   * @param lc array containing the number of nodes in the X direction on
   * each processor, or null. If non-null, this array must be the same length
   * as M.
   * @param error an optional reference to a PETSc error code
   * @see <a href="http://www-unix.mcs.anl.gov/petsc/docs/manualpages/DA/DACreate1d.html">
   */
  public DA(Comm comm, int wrap, int M, int dof, int s, int[] local lc,
	    int[] local error) {
    super(create1d(comm, wrap, M, dof, s, lc, error));
  }

  /**
   * creates a 2-d distributed array.
   * @param comm the communicator to use (Comm.self or Comm.world)
   * @param wrap the type of periodicity the array should have, if any.
   * This is a constant from the set {DA_NONPERIODIC, DA_XPERIODIC, 
   * DA_YPERIODIC, DA_XYPERIODIC}.
   * @param stencil_type stencil type. Use either DA_STENCIL_STAR or
   * DA_STENCIL_BOX.
   * @param M the global X-length of the array
   * @param N the global Y-length of the array
   * @param m local number of processors in the X dimension, or PETSC_DECIDE.
   * @param n local number of processes in the Y dimension, or PETSC_DECIDE.
   * @param dof number of degrees of freedom per node
   * @param s stencil width
   * @param lx array containing the number of nodes in the X direction on
   * each processor, or null. If non-null, this array must be of length M.
   * @param ly array containing the number of nodes in the X direction on
   * each processor, or null. If non-null, this array must be of length N.
   * @param error an optional reference to a PETSc error code
   * @see <a href="http://www-unix.mcs.anl.gov/petsc/docs/manualpages/DA/DACreate2d.html">
   */
  public DA(Comm comm, int wrap, int stencil_type, int M, int N, int m, int n,
	    int dof, int s, int[] local lx, int[] local ly, int[] local error)
  {
    super(create2d(comm, wrap, stencil_type, M, N, m, n, dof, s, lx, ly, 
		   error));
  }
  
  /**
   * Create a parallel global PETSc vector from a DA object. For a clearer 
   * explanation, look at the following Web page:
   * @see http://www-unix.mcs.anl.gov/petsc/docs/manual/manual.html/#Node27
   * @param error an optional reference to a PETSc error code
   * @see <a href="http://www-unix.mcs.anl.gov/petsc/docs/manualpages/DA/DACreateGlobalVector.html">
   */
  public local Vec local createGlobalVector(int[] local error) {
    Opaque local opaque = createGlobalVectorRaw(error);
    return new Vec(opaque);
  }

  /**
   * Create a parallel local PETSc vector from a DA object. For a clearer 
   * explanation, look at the following Web page:
   * @see http://www-unix.mcs.anl.gov/petsc/docs/manual/manual.html/#Node27
   * @param error an optional reference to a PETSc error code
   * @see <a href="http://www-unix.mcs.anl.gov/petsc/docs/manualpages/DA/DACreateLocalVector.html">
   */
  public local Vec local createLocalVector(int[] local error) {
    Opaque local opaque = createLocalVectorRaw(error);
    return new Vec(opaque);
  }

  /**
   * Gets the extent of the local region of the grid, excluding ghost points. 
   * @param corner An array whose length must be the number of dimensions of
   * the grid. This array gets set to the coordinates of the lower-left 
   * corner of the local region, excluding ghost points.
   * @param width An array whose length must be the number of dimensions of
   * the grid. This array gets set to the width of the local grid region,
   * such that width[0] is the width in the x-dimension, width[1] is the
   * width in the y-dimension, and so on.
   * @param error an optional reference to a PETSc error code
   * @see <a href="http://www-unix.mcs.anl.gov/petsc/docs/manualpages/DA/DAGetCorners.html">
   */
  public local native void getCorners(int[] local corner,
				      int[] local width,
				      int[] local error);
    
  /**
   * Gets the extent of the local region of the grid, including ghost points.
   * @param corner An array whose length must be the number of dimensions of
   * the grid. This array gets set to the coordinates of the lower-left 
   * corner of the local region, including ghost points.
   * @param width An array whose length must be the number of dimensions of
   * the grid. This array gets set to the width of the local grid region,
   * such that width[0] is the width in the x-dimension, width[1] is the
   * width in the y-dimension, and so on.
   * @param error an optional reference to a PETSc error code
   * @see <a href="http://www-unix.mcs.anl.gov/petsc/docs/manualpages/DA/DAGetGhostCorners.html">
   */
  public local native void getGhostCorners(int[] local corner,
					   int[] local width,
					   int[] local error);

  /**
   * Gets the global node number of all local nodes, including ghost nodes.
   * @param error an optional reference to a PETSc error code
   * @see <a href="http://www-unix.mcs.anl.gov/petsc/docs/manualpages/DA/DAGetGlobalIndices.html">
   */
  public native local int[] local getGlobalIndices(int[] local error);

  /**
   * Maps values from the global vector to the local patch; the ghost 
   * points are included. Must be followed by globalToLocalEnd() to 
   * complete the exchange. 
   * @param g the global vector
   * @param insert_mode either DA.INSERT_VALUES or DA.ADD_VALUES
   * @param l the local vector
   * @param error an optional reference to a PETSc error code
   * @see <a href="http://www-unix.mcs.anl.gov/petsc/docs/manualpages/DA/DAGlobalToLocalBegin.html">
   */
  native public local void globalToLocalBegin(Vec local g, int insert_mode, 
					      Vec local l, int[] local error);

  /**
   * Completes the transformation begun by globalToLocalBegin().
   * @param g the global vector
   * @param insert_mode either DA.INSERT_VALUES or DA.ADD_VALUES
   * @param l the local vector
   * @param error an optional reference to a PETSc error code
   * @see <a href="http://www-unix.mcs.anl.gov/petsc/docs/manualpages/DA/DAGlobalToLocalEnd.html">
   */
  native public local void globalToLocalEnd(Vec local g, int insert_mode, 
					    Vec local l, int[] local error);

  /**
   * Maps values from the local patch back to the global vector. The 
   * ghost points are discarded. 
   * @param l the local vector
   * @param insert_mode either DA.INSERT_VALUES or DA.ADD_VALUES
   * @param g the global vector
   * @param error an optional reference to a PETSc error code
   * @see <a href="http://www-unix.mcs.anl.gov/petsc/docs/manualpages/DA/DALocalToGlobal.html">
   */
  native public local void localToGlobal(Vec local l, int insert_mode, 
					 Vec local g, int[] local error);

  native private local Opaque local createGlobalVectorRaw(int[] local error);
  native private local Opaque local createLocalVectorRaw(int[] local error);
  native private static Opaque local create1d(Comm comm, int wrap, int M, 
					      int dof, int s, 
					      int[] local lc,
					      int[] local error);

  native private static Opaque local create2d(Comm comm, int wrap, 
					      int stencil_type,
					      int M, int N, int m, int n, 
					      int dof, int s, int[] local lx, 
					      int[] local ly,
					      int[] local error);
}