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:Classes | |
| struct | Impl |
Public Member Functions | |
| virtual | ~Array () |
| std::shared_ptr< const Grid > | 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 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::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 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::Vec > | allocate_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... | |
| 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_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 ¶llel, petsc::Vec &onp0) const |
| void | get_from_proc0 (petsc::Vec &onp0, petsc::Vec ¶llel) 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... | |
| Array (const Array &other) | |
| Array & | operator= (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 (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
("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:
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:
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:
A note about NetCDF write performance: due to limitations of the NetCDF (classic, version 3) format, it is significantly faster to
as opposed to
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:
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.
The documentation for this class was generated from the following files:
