PISM, A Parallel Ice Sheet Model  stable v2.1-1-g6902d5502 committed by Ed Bueler on 2023-12-20 08:38:27 -0800
Classes | Public Member Functions | Protected Member Functions | Protected Attributes | Private Member Functions | List of all members
pism::array::Array Class Reference

Abstract class for reading, writing, allocating, and accessing a DA-based PETSc Vec (2D and 3D fields) from within IceModel. More...

#include <Array.hh>

+ Inheritance diagram for pism::array::Array:


struct  Impl

Public Member Functions

virtual ~Array ()
std::shared_ptr< const Gridgrid () const
unsigned int ndims () const
 Returns the number of spatial dimensions. More...
std::vector< int > shape () const
unsigned int ndof () const
 Returns the number of degrees of freedom per grid point. More...
unsigned int stencil_width () const
 Get the stencil width of the current Array. Returns 0 if ghosts are not available. More...
const std::vector< double > & levels () const
std::array< double, 2 > range () const
 Result: min <- min(v[j]), max <- max(v[j]). More...
std::vector< double > norm (int n) const
 Computes the norm of all the components of an Array. More...
void add (double alpha, const Array &x)
 Result: v <- v + alpha * x. Calls VecAXPY. More...
void shift (double alpha)
 Result: v[j] <- v[j] + alpha for all j. Calls VecShift. More...
void scale (double alpha)
 Result: v <- v * alpha. Calls VecScale. More...
petsc::Vecvec () const
std::shared_ptr< petsc::DMdm () const
void set_name (const std::string &name)
 Sets the variable name to name. More...
const std::string & get_name () const
 Get the name of an Array object. More...
void define (const File &file, io::Type default_type) const
 Define variables corresponding to an Array in a file opened using file. More...
void read (const std::string &filename, unsigned int time)
void read (const File &file, unsigned int time)
void write (const std::string &filename) const
void write (const File &file) const
void regrid (const std::string &filename, io::Default default_value)
void regrid (const File &file, io::Default default_value)
virtual void begin_access () const
 Checks if an Array is allocated and calls DAVecGetArray. More...
virtual void end_access () const
 Checks if an Array is allocated and calls DAVecRestoreArray. More...
void update_ghosts ()
 Updates ghost points. More...
std::shared_ptr< petsc::Vecallocate_proc0_copy () const
void put_on_proc0 (petsc::Vec &onp0) const
 Puts a local array::Scalar on processor 0. More...
void get_from_proc0 (petsc::Vec &onp0)
 Gets a local Array2 from processor 0. More...
void set (double c)
 Result: v[j] <- c for all j. More...
SpatialVariableMetadatametadata (unsigned int N=0)
 Returns a reference to the SpatialVariableMetadata object containing metadata for the compoment N. More...
const SpatialVariableMetadatametadata (unsigned int N=0) const
int state_counter () const
 Get the object state counter. More...
void inc_state_counter ()
 Increment the object state counter. More...
void set_interpolation_type (InterpolationType type)
void view (std::vector< std::shared_ptr< petsc::Viewer > > viewers) const
 View a 2D vector field using existing PETSc viewers. More...
void dump (const char filename[]) const
 Dumps a variable to a file, overwriting this file's contents (for debugging). More...
uint64_t fletcher64_serial () const
uint64_t fletcher64 () const
std::string checksum (bool serial) const
void print_checksum (const char *prefix="", bool serial=false) const
- Public Member Functions inherited from pism::PetscAccessible
virtual ~PetscAccessible ()=default

Protected Member Functions

 Array (std::shared_ptr< const Grid > grid, const std::string &name, Kind ghostedp, size_t dof, size_t stencil_width, const std::vector< double > &zlevels)
void set_begin_access_use_dof (bool flag)
void read_impl (const File &file, unsigned int time)
 Reads appropriate NetCDF variable(s) into an Array. More...
virtual void regrid_impl (const File &file, io::Default default_value)
 Gets an Array from a file file, interpolating onto the current grid. More...
void write_impl (const File &file) const
 Writes an Array to a NetCDF file. More...
void checkCompatibility (const char *function, const Array &other) const
 Checks if two Arrays have compatible sizes, dimensions and numbers of degrees of freedom. More...
void check_array_indices (int i, int j, unsigned int k) const
 Check array indices and warn if they are out of range. More...
void copy_to_vec (std::shared_ptr< petsc::DM > destination_da, petsc::Vec &destination) const
 Copies v to a global vector 'destination'. Ghost points are discarded. More...
void get_dof (std::shared_ptr< petsc::DM > da_result, petsc::Vec &result, unsigned int start, unsigned int count=1) const
void set_dof (std::shared_ptr< petsc::DM > da_source, petsc::Vec &source, unsigned int start, unsigned int count=1)
void put_on_proc0 (petsc::Vec &parallel, petsc::Vec &onp0) const
void get_from_proc0 (petsc::Vec &onp0, petsc::Vec &parallel) const

Protected Attributes

void * m_array

Private Member Functions

size_t size () const
 Return the total number of elements in the owned part of an array. More...
 Array (const Array &other)
Arrayoperator= (const Array &)

Detailed Description

Abstract class for reading, writing, allocating, and accessing a DA-based PETSc Vec (2D and 3D fields) from within IceModel.

This class represents 2D and 3D fields in PISM. Its methods common to all the derived classes can be split (roughly) into six kinds:

Memory allocation

array::Scalar var(grid, "var_name", WITH_GHOSTS);
// var is ready to use
std::shared_ptr< const Grid > grid() const
Definition: Array.cc:132
Definition: Array.hh:62

("WITH_GHOSTS" means "can be used in computations using map-plane neighbors of grid points.)

It is usually a good idea to set variable metadata right after creating it. The method set_attrs() is used throughout PISM to set commonly used attributes.

Point-wise access

PETSc performs some pointer arithmetic magic to allow convenient indexing of grid point values. Because of this one needs to surround the code using row, column or level indexes with begin_access() and end_access() calls:

double foo;
int i = 0, j = 0;
array::Scalar var;
// assume that var was allocated
ierr = var.begin_access(); CHKERRQ(ierr);
foo = var(i,j) * 2;
ierr = var.end_access(); CHKERRQ(ierr);

Please see this page for a discussion of the organization of PISM's computational grid and examples of for-loops you will probably put between begin_access() and end_access().

To ensure that ghost values are up to date add the following call before the code using ghosts:

ierr = var.update_ghosts(); CHKERRQ(ierr);

Reading and writing variables

PISM can read variables either from files with data on a grid matching the current grid (read()) or, using bilinear interpolation, from files containing data on a different (but compatible) grid (regrid()).

To write a field to a "prepared" NetCDF file, use write(). (A file is prepared if it contains all the necessary dimensions, coordinate variables and global metadata.)

If you need to "prepare" a file, do:

File file(grid.com, PISM_NETCDF3);
io::prepare_for_output(file, *grid.ctx());
Definition: IO_Flags.hh:57

A note about NetCDF write performance: due to limitations of the NetCDF (classic, version 3) format, it is significantly faster to

for (all variables)
for (all variables)

as opposed to

for (all variables) {

array::Array::define() is here so that we can use the first approach.

Tracking if a field changed

It is possible to track if a certain field changed with the help of get_state_counter() and inc_state_counter() methods.

For example, PISM's SIA code re-computes the smoothed bed only if the bed deformation code updated it:

if (bed->get_state_counter() > bed_state_counter) {
ierr = bed_smoother->preprocess_bed(...); CHKERRQ(ierr);
bed_state_counter = bed->get_state_counter();

The state counter is not updated automatically. For the code snippet above to work, a bed deformation model has to call inc_state_counter() after an update.

Definition at line 208 of file Array.hh.

The documentation for this class was generated from the following files: