PISM, A Parallel Ice Sheet Model  stable v1.2 committed by Constantine Khrulev on 2020-02-11 20:24:05 -0900
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | Private Member Functions | List of all members
pism::IceModelVec Class Reference

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

#include <iceModelVec.hh>

+ Inheritance diagram for pism::IceModelVec:

Public Types

typedef std::shared_ptr< IceModelVecPtr
typedef std::shared_ptr< const IceModelVecConstPtr
typedef pism::AccessList AccessList

Public Member Functions

 IceModelVec ()
virtual ~IceModelVec ()
virtual bool was_created () const
 Returns true if create() was called and false otherwise. More...
IceGrid::ConstPtr grid () const
unsigned int ndims () const
 Returns the grid type of an IceModelVec. (This is the way to figure out if an IceModelVec is 2D or 3D). More...
std::vector< intshape () 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 IceModelVec. Returns 0 if ghosts are not available. More...
std::vector< doublelevels () const
virtual Range range () const
 Result: min <- min(v[j]), max <- max(v[j]). More...
double norm (int n) const
 Computes the norm of an dof==1 IceModelVec by calling PETSc VecNorm. More...
std::vector< doublenorm_all (int n) const
 Computes the norm of all components. More...
virtual void add (double alpha, const IceModelVec &x)
 Result: v <- v + alpha * x. Calls VecAXPY. More...
virtual void squareroot ()
 Result: v <- sqrt(v), elementwise. Calls VecSqrt(v). More...
virtual void shift (double alpha)
 Result: v[j] <- v[j] + alpha for all j. Calls VecShift. More...
virtual void scale (double alpha)
 Result: v <- v * alpha. Calls VecScale. More...
void copy_to_vec (petsc::DM::Ptr destination_da, Vec destination) const
 Copies v to a global vector 'destination'. Ghost points are discarded. More...
void copy_from_vec (Vec source)
 Copies data from a Vec source to this IceModelVec. Updates ghost points if necessary. More...
virtual void copy_from (const IceModelVec &source)
 Result: v <- source. Leaves metadata alone but copies values in Vec. Uses VecCopy. More...
Vec vec ()
petsc::DM::Ptr dm () const
virtual 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 IceModelVec object. More...
void set_attrs (const std::string &pism_intent, const std::string &long_name, const std::string &units, const std::string &glaciological_units, const std::string &standard_name, unsigned int component)
 Sets NetCDF attributes of an IceModelVec object. More...
virtual void read_attributes (const std::string &filename, int component=0)
 Read attributes from the corresponding variable in filename. More...
virtual void define (const File &nc, IO_Type default_type=PISM_DOUBLE) const
 Define variables corresponding to an IceModelVec in a file opened using file. More...
void read (const std::string &filename, unsigned int time)
void read (const File &nc, unsigned int time)
void write (const std::string &filename) const
void write (const File &nc) const
void regrid (const std::string &filename, RegriddingFlag flag, double default_value=0.0)
void regrid (const File &nc, RegriddingFlag flag, double default_value=0.0)
virtual void begin_access () const
 Checks if an IceModelVec is allocated and calls DAVecGetArray. More...
virtual void end_access () const
 Checks if an IceModelVec is allocated and calls DAVecRestoreArray. More...
virtual void update_ghosts ()
 Updates ghost points. More...
virtual void update_ghosts (IceModelVec &destination) const
 Scatters ghost points to IceModelVec destination. More...
petsc::Vec::Ptr allocate_proc0_copy () const
void put_on_proc0 (Vec onp0) const
 Puts a local IceModelVec2S on processor 0. More...
void get_from_proc0 (Vec onp0)
 Gets a local IceModelVec2 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_time_independent (bool flag)
 Set the time independent flag for all variables corresponding to this IceModelVec instance. More...
void dump (const char filename[]) const
 Dumps a variable to a file, overwriting this file's contents (for debugging). More...
uint64_t fletcher64 () const
std::string checksum () const
void print_checksum (const char *prefix="") const
- Public Member Functions inherited from pism::PetscAccessible
virtual ~PetscAccessible ()

Protected Member Functions

void global_to_local (petsc::DM::Ptr dm, Vec source, Vec destination) const
virtual void read_impl (const File &nc, unsigned int time)
 Reads appropriate NetCDF variable(s) into an IceModelVec. More...
virtual void regrid_impl (const File &nc, RegriddingFlag flag, double default_value=0.0)
 Gets an IceModelVec from a file file, interpolating onto the current grid. More...
virtual void write_impl (const File &nc) const
 Writes an IceModelVec to a NetCDF file. More...
virtual void checkCompatibility (const char *function, const IceModelVec &other) const
 Checks if two IceModelVecs have compatible sizes, dimensions and numbers of degrees of freedom. More...
void check_array_indices (int i, int j, unsigned int k) const
 Check the array indices and warn if they are out of range. More...
void reset_attrs (unsigned int N)
 Resets most IceModelVec attributes. More...
NormType int_to_normtype (int input) const
void get_dof (petsc::DM::Ptr da_result, Vec result, unsigned int n, unsigned int count=1) const
void set_dof (petsc::DM::Ptr da_source, Vec source, unsigned int n, unsigned int count=1)
void put_on_proc0 (Vec parallel, Vec onp0) const
void get_from_proc0 (Vec onp0, Vec parallel)

Protected Attributes

bool m_report_range
 If true, report range when regridding. More...
std::vector< doublem_zlevels
petsc::Vec m_v
 Internal storage. More...
std::string m_name
std::vector< SpatialVariableMetadatam_metadata
 stores metadata (NetCDF variable attributes) More...
IceGrid::ConstPtr m_grid
unsigned int m_dof
 number of "degrees of freedom" per grid point More...
unsigned int m_da_stencil_width
 stencil width supported by the DA More...
bool m_has_ghosts
 m_has_ghosts == true means "has ghosts" More...
petsc::DM::Ptr m_da
 distributed mesh manager (DM) More...
bool m_begin_end_access_use_dof
std::map< std::string, petsc::Viewer::Ptrm_map_viewers
void * m_array
int m_access_counter
int m_state_counter
 Internal IceModelVec "revision number". More...
InterpolationType m_interpolation_type

Private Member Functions

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

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

Creating an IceModelVec... object does not allocate memory for storing it (some IceModelVecs serve as "references" and don't have their own storage). To complete IceModelVec... creation, use the "create()" method:

IceModelVec2S var;
ierr = var.create(grid, "var_name", WITH_GHOSTS); CHKERRQ(ierr);
// var is ready to use

("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;
IceModelVec2S 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());

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) {

IceModelVec::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 215 of file iceModelVec.hh.

The documentation for this class was generated from the following files:
Definition: IO_Flags.hh:41
Definition: iceModelVec.hh:46
IceGrid::ConstPtr grid() const
Definition: iceModelVec.cc:79