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:

Classes
struct	Impl

Public Types
typedef std::shared_ptr< IceModelVec >	Ptr
typedef std::shared_ptr< const IceModelVec >	ConstPtr
typedef pism::AccessList	AccessList

Public Member Functions
virtual	~IceModelVec ()
IceGrid::ConstPtr	grid () 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 IceModelVec. Returns 0 if ghosts are not available. More...
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 IceModelVec. More...
void	add (double alpha, const IceModelVec &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::Vec &	vec () const
std::shared_ptr< petsc::DM >	dm () 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 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...
void	define (const File &file, 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 &file, unsigned int time)
void	write (const std::string &filename) const
void	write (const File &file) const
void	regrid (const std::string &filename, RegriddingFlag flag, double default_value=0.0)
void	regrid (const File &file, 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...
void	update_ghosts ()
	Updates ghost points. More...
std::shared_ptr< petsc::Vec >	allocate_proc0_copy () const
void	put_on_proc0 (petsc::Vec &onp0) const
	Puts a local IceModelVec2S on processor 0. More...
void	get_from_proc0 (petsc::Vec &onp0)
	Gets a local IceModelVec2 from processor 0. More...
void	set (double c)
	Result: v[j] <- c for all j. More...
SpatialVariableMetadata &	metadata (unsigned int N=0)
	Returns a reference to the SpatialVariableMetadata object containing metadata for the compoment N. More...
const SpatialVariableMetadata &	metadata (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	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

Static Public Member Functions
template<class T >
static T::Ptr	cast (IceModelVec::Ptr input)
	dynamic_pointer_cast wrapper that checks if the cast succeeded. More...

Protected Member Functions
	IceModelVec (IceGrid::ConstPtr grid, const std::string &name, IceModelVecKind 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 IceModelVec. More...
void	regrid_impl (const File &file, RegriddingFlag flag, double default_value=0.0)
	Gets an IceModelVec from a file file, interpolating onto the current grid. More...
void	write_impl (const File &file) const
	Writes an IceModelVec to a NetCDF file. More...
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 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
Impl *	m_impl
void *	m_array

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)
IceModelVec &	operator= (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 (create)
• point-wise access (begin_access(), end_access())
• arithmetic (range(), norm(), add(), shift(), scale(), set(), ...)
• setting or reading metadata (set_attrs(), metadata())
• file input/output (read, write, regrid)
• tracking whether a field was updated (get_state_counter(), inc_state_counter())

Memory allocation

IceModelVec2S var(grid, "var_name", WITH_GHOSTS);
// 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)
var.define(...);
 
for (all variables)
var.write(...);

as opposed to

for (all variables) {
var.define(...);
var.write(...);
}

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 202 of file iceModelVec.hh.

---

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

• src/util/iceModelVec.hh
• src/util/iceModelVec.cc