A run-time YASK data container. More...

#include <yk_var_api.hpp>

Classes
class	yk_reduction_result
	Class returned from reduce_elements_in_slice(). More...

Public Types
typedef std::shared_ptr< yk_reduction_result >	yk_reduction_result_ptr
	Shared pointer to yk_reduction_result.

Public Member Functions
virtual const std::string &	get_name () const =0
	Get the name of the var.

virtual int	get_num_dims () const =0
	Get the number of dimensions used in this var.

virtual string_vec	get_dim_names () const =0
	Get all the dimensions in this var.

virtual int	get_num_domain_dims () const =0
	Get the number of domain dimensions used in this var.

virtual bool	is_dim_used (const std::string &dim) const =0
	Determine whether specified dimension exists in this var.

virtual bool	is_fixed_size () const =0
	Determine whether this var is not automatically resized based on the solution.

virtual idx_t	get_first_local_index (const std::string &dim) const =0
	Get the first valid index in this rank in the specified dimension.

virtual idx_t_vec	get_first_local_index_vec () const =0
	Get the first valid index in this rank in all dimensions in this var.

virtual idx_t	get_last_local_index (const std::string &dim) const =0
	Get the last index in this rank in the specified dimension.

virtual idx_t_vec	get_last_local_index_vec () const =0
	Get the last valid index in this rank in all dimensions in this var.

virtual idx_t	get_alloc_size (const std::string &dim) const =0
	Get the number of elements allocated in the specified dimension.

virtual idx_t_vec	get_alloc_size_vec () const =0
	Get the number of elements allocated in all dimensions in this var.

virtual idx_t	get_first_valid_step_index () const =0
	Get the first valid index in the step dimension.

virtual idx_t	get_last_valid_step_index () const =0
	Get the last valid index in the step dimension.

virtual idx_t	get_rank_domain_size (const std::string &dim) const =0
	Get the domain size for this rank in the specified dimension.

virtual idx_t_vec	get_rank_domain_size_vec () const =0
	Get the domain size for this rank in all domain dimensions in this var.

virtual idx_t	get_first_rank_domain_index (const std::string &dim) const =0
	Get the first index of the sub-domain in this rank in the specified dimension.

virtual idx_t_vec	get_first_rank_domain_index_vec () const =0
	Get the first index of the sub-domain in this rank in all domain dimensions in this var.

virtual idx_t	get_last_rank_domain_index (const std::string &dim) const =0
	Get the last index of the sub-domain in this rank in the specified dimension.

virtual idx_t_vec	get_last_rank_domain_index_vec () const =0
	Get the last index of the sub-domain in this rank in all domain dimensions in this var.

virtual idx_t	get_left_halo_size (const std::string &dim) const =0
	Get the left halo size in the specified dimension.

virtual idx_t	get_right_halo_size (const std::string &dim) const =0
	Get the right halo size in the specified dimension.

virtual idx_t	get_first_rank_halo_index (const std::string &dim) const =0
	Get the first index of the left halo in this rank in the specified dimension.

virtual idx_t_vec	get_first_rank_halo_index_vec () const =0
	Get the first index of the left halo in this rank in all domain dimensions in this var.

virtual idx_t	get_last_rank_halo_index (const std::string &dim) const =0
	Get the last index of the right halo in this rank in the specified dimension.

virtual idx_t_vec	get_last_rank_halo_index_vec () const =0
	Get the last index of the right halo in this rank in all domain dimensions in this var.

virtual idx_t	get_left_pad_size (const std::string &dim) const =0
	Get the actual left padding in the specified dimension.

virtual idx_t	get_right_pad_size (const std::string &dim) const =0
	Get the actual right padding in the specified dimension.

virtual idx_t	get_left_extra_pad_size (const std::string &dim) const =0
	Get the actual extra left padding in the specified dimension.

virtual idx_t	get_right_extra_pad_size (const std::string &dim) const =0
	Get the actual extra right padding in the specified dimension.

virtual idx_t	get_first_misc_index (const std::string &dim) const =0
	Get the first index of a specified miscellaneous dimension.

virtual idx_t	get_last_misc_index (const std::string &dim) const =0
	Get the last index of a specified miscellaneous dimension.

virtual bool	are_indices_local (const idx_t_vec &indices) const =0
	Determine whether the given indices refer to an accessible element in this rank.

virtual bool	are_indices_local (const idx_t_init_list &indices) const =0
	Determine whether the given indices refer to an accessible element in this rank.

virtual double	get_element (const idx_t_vec &indices) const =0
	Read the value of one element in this var.

virtual double	get_element (const idx_t_init_list &indices) const =0
	Read the value of one element in this var.

virtual idx_t	set_element (double val, const idx_t_vec &indices, bool strict_indices=true)=0
	Set the value of one element in this var.

virtual idx_t	set_element (double val, const idx_t_init_list &indices, bool strict_indices=true)=0
	Set the value of one element in this var.

virtual idx_t	get_elements_in_slice (float *buffer_ptr, size_t buffer_size, const idx_t_vec &first_indices, const idx_t_vec &last_indices) const =0
	Copy elements within specified subset of this var into a `float` buffer.

virtual idx_t	get_elements_in_slice (double *buffer_ptr, size_t buffer_size, const idx_t_vec &first_indices, const idx_t_vec &last_indices) const =0
	Copy elements within specified subset of this var into a `double` buffer.

virtual idx_t	add_to_element (double val, const idx_t_vec &indices, bool strict_indices=true)=0
	Atomically add to the value of one var element.

virtual idx_t	add_to_element (double val, const idx_t_init_list &indices, bool strict_indices=true)=0
	Atomically add to the value of one var element.

virtual void	set_all_elements_same (double val)=0
	Initialize all var elements to the same value.

virtual idx_t	set_elements_in_slice_same (double val, const idx_t_vec &first_indices, const idx_t_vec &last_indices, bool strict_indices=true)=0
	Initialize var elements within specified subset of the var to the same value.

virtual idx_t	set_elements_in_slice (const float *buffer_ptr, size_t buffer_size, const idx_t_vec &first_indices, const idx_t_vec &last_indices)=0
	Set elements within specified subset of the var from values in a `float` buffer.

virtual idx_t	set_elements_in_slice (const double *buffer_ptr, size_t buffer_size, const idx_t_vec &first_indices, const idx_t_vec &last_indices)=0
	Set elements within specified subset of the var from values in a `double` buffer.

virtual yk_reduction_result_ptr	reduce_elements_in_slice (int reduction_mask, const idx_t_vec &first_indices, const idx_t_vec &last_indices, bool strict_indices=true)=0
	Perform requested reductions over elements within specified subset of the var.

virtual std::string	format_indices (const idx_t_vec &indices) const =0
	Format the indices for human-readable display.

virtual std::string	format_indices (const idx_t_init_list &indices) const =0
	Format the indices for human-readable display.

virtual int	get_halo_exchange_l1_norm () const =0
	[Advanced] Get the maximum L1-norm of a neighbor rank for halo exchange.

virtual void	set_halo_exchange_l1_norm (int norm)=0
	[Advanced] Set the maximum L1-norm of a neighbor rank for halo exchange.

virtual bool	is_dynamic_step_alloc () const =0
	[Advanced] Get whether the allocation of the step dimension of this var can be modified at run-time.

virtual bool	set_numa_preferred (int numa_node)=0
	[Advanced] Set the default preferred NUMA node on which to allocate data.

virtual int	get_numa_preferred () const =0
	[Advanced] Get the default preferred NUMA node on which to allocate data.

virtual void	set_left_min_pad_size (const std::string &dim, idx_t size)=0
	[Advanced] Set the minimum left padding in the specified dimension.

virtual void	set_right_min_pad_size (const std::string &dim, idx_t size)=0
	[Advanced] Set the minimum right padding in the specified dimension.

virtual void	set_min_pad_size (const std::string &dim, idx_t size)=0
	[Advanced] Set the minimum padding in the specified dimension.

virtual void	set_left_halo_size (const std::string &dim, idx_t size)=0
	[Advanced] Set the left halo size in the specified dimension.

virtual void	set_right_halo_size (const std::string &dim, idx_t size)=0
	[Advanced] Set the right halo size in the specified dimension.

virtual void	set_halo_size (const std::string &dim, idx_t size)=0
	[Advanced] Set the left and right halo sizes in the specified dimension.

virtual void	set_alloc_size (const std::string &dim, idx_t size)=0
	[Advanced] Set the number of elements to allocate in the specified dimension.

virtual void	set_first_misc_index (const std::string &dim, idx_t idx)=0
	[Advanced] Set the first index of a specified miscellaneous dimension.

virtual bool	is_storage_allocated () const =0
	[Advanced] Determine whether storage has been allocated.

virtual idx_t	get_num_storage_bytes () const =0
	[Advanced] Determine size of raw storage in bytes.

virtual idx_t	get_num_storage_elements () const =0
	[Advanced] Determine size of raw storage in elements.

virtual void	alloc_storage ()=0
	[Advanced] Explicitly allocate data-storage memory for this var.

virtual void	release_storage ()=0
	[Advanced] Explicitly release any allocated data-storage for this var.

virtual bool	is_storage_layout_identical (const yk_var_ptr other) const =0
	[Advanced] Determines whether storage layout is the same as another var.

virtual void	fuse_vars (yk_var_ptr source)=0
	[Advanced] Merge this var with another var.

virtual void *	get_raw_storage_buffer ()=0
	[Advanced] Get pointer to raw data storage buffer.

virtual YASK_DEPRECATED idx_t	get_elements_in_slice (void *buffer_ptr, const idx_t_vec &first_indices, const idx_t_vec &last_indices) const =0
	[Deprecated] Use the `float` or `double` version.

virtual YASK_DEPRECATED idx_t	set_elements_in_slice (const void *buffer_ptr, const idx_t_vec &first_indices, const idx_t_vec &last_indices)=0
	[Deprecated] Use the `float` or `double` version.

virtual YASK_DEPRECATED idx_t	get_first_rank_alloc_index (const std::string &dim) const
	[Deprecated] Use get_first_local_index().

virtual YASK_DEPRECATED idx_t	get_last_rank_alloc_index (const std::string &dim) const
	[Deprecated] Use get_last_local_index().

Static Public Attributes
static constexpr int	yk_sum_reduction = 0x01
	Bitmask for sum reduction.

static constexpr int	yk_sum_squares_reduction = 0x02
	Bitmask for sum-of-squares reduction.

static constexpr int	yk_product_reduction = 0x04
	Bitmask for product reduction.

static constexpr int	yk_max_reduction = 0x08
	Bitmask for maximum-value reduction.

static constexpr int	yk_min_reduction = 0x10
	Bitmask for minimum-value reduction.

Detailed Description

A run-time YASK data container.

A run-time YASK variable is a generic term for any n-dimensional array. A 0-dim var is a scalar, a 1-dim var is an array, etc. A run-time variable actually contains data, unlike yc_var, a compile-time variable.

Typically, access to each var is obtained via yk_solution::get_var(). You may also use yk_solution::new_var() or yk_solution::new_fixed_size_var() if you need a var that is not part of the pre-defined solution.

Var Dimensions

Each dimension of a YASK var is one of the following:

The step dimension, typically time (t), as returned from yk_solution::get_step_dim_name().
A domain dimension, typically a spatial dimension such as x or y, as returned from yk_solution::get_domain_dim_names().
A miscellaneous dimension, which is any dimension that is not a step or domain dimension. These may be returned via yk_solution::get_misc_dim_names() if they were defined in the YASK compiler, or they may be any other name that is not a step or domain dimension.

Step Dimensions

The step dimension, as defined during YASK compilation, is the dimension in which the simulation proceeds, often "t" for time. In the step dimension, there is no fixed first or last index. However, there is a finite allocation size, which is the number of values in the step dimension that are stored in memory. The valid indices in the step dimension are always consecutive and change based on what was last written to the var.

For example: If a var A has an allocation size of two (2) in the t step dimension, its initial valid t indices are 0 and 1. Calling A->get_element({0, x}) or A->get_element({1, x}) would return a value from A assuming x is a valid index, but A->get_element({2, x}) would cause a run-time exception. Let's say the YASK solution defines A(t+1, x) EQUALS (A(t, x) + A(t, x+1))/2. Calling yk_solution::run_solution(1) means that A(2, x) would be defined for all x in the domain because t+1 == 2 on the left-hand-side of the equation. Thus, the new valid t indices in A would be 1 and 2, and A(0, x) is no longer stored in memory because the allocation size is only 2. Then, calling A->get_element({1, x}) or A->get_element({2, x}) would succeed and A->get_element({0, x}) would fail.

Calling APIs that set values in a var such as set_element() will also update the valid step index range. The current valid indices in the step dimension can be retrieved via yk_var::get_first_valid_step_index() and yk_var::get_last_valid_step_index().

If yk_solution::set_step_wrap(true) is called, any invalid value of a step index provided to an API will silently "wrap-around" to a valid value by effectively adding or subtracing multiples of the allocation size as needed. For example, if the valid step indices are 7 and 8 for a given var, the indices 0 and 1 will wrap-around to 8 and 7, respectively. This is not recommended for general use because it can hide off-by-one-type errors. However, it may be useful for applications that need to access a var using absolute rather than logical step indices.

Domain Dimensions

A domain dimension typically corresponds to a physical spatial dimension, but it can be any dimension that is used for "domain decomposition" in the solution. The indices in the domain dimensions that correspond to spatial dimensions (e.g., "x" and "y") often denote locations in the implicit "grid" of the problem domain.

In each domain dimension, the number of elements allocated in a given var include the following components:

The domain is the elements to which the stencils are applied.
The left padding is all the accessible elements before the domain and includes the left halo.
The right padding is all the accessible elements after the domain and includes the right halo.
The left halo is the elements just before the domain which must be copied between preceding ranks during halo exchanges. The left halo is contained within the left padding.
The right halo is the elements just after the domain which must be copied between following ranks during halo exchanges. The right halo is contained within the right padding.
The extra left padding is the elements before the domain and left halo and thus does not include the left halo.
The extra right padding is the elements after the domain and right halo and thus does not include the right halo.
The allocation includes the left padding, domain, and right padding.

Domain sizes specified via yk_solution::set_rank_domain_size() apply to each MPI rank. Visually, in each of the domain dimensions, these sizes are related as follows in each rank:

extra left padding	left halo	domain	right halo	extra right padding
left padding			right padding
allocation

If MPI is not enabled, a rank's domain is equivalent to the entire problem size. If MPI is enabled, the domains of the ranks are logically abutted to create the overall problem domain in each dimension:

extra left padding of rank A	halo of rank A	domain of rank A	domain of rank B	...	domain of rank Z	halo of rank Z	extra right padding of rank Z
left padding of rank A		overall problem domain				right padding of rank Z

Halos and paddings between ranks also exist, but are not shown in the above diagram. The halos overlap the domains of adjacent ranks. For example, the left halo of rank B in the diagram would overlap the domain of rank A. Data in these overlapped areas are exchanged as needed during stencil application to maintain a consistent values as if there was only one rank.

Miscellaneous Dimensions

In each miscellaneous dimension, there is no padding or halos. There is a fixed allocation size, and each index must be between its first and last valid value. The valid miscellaneous indices may be retrieved via yk_var::get_first_misc_index() and yk_var::get_last_misc_index().

Other Details

Elements

All sizes are expressed in numbers of elements. Each element may be a 4-byte (single precision) or 8-byte (double precision) floating-point value as returned by yk_solution::get_element_bytes().

Data Storage

Initially, a var is not assigned any allocated storage. This is done to allow modification of domain, padding, and other allocation sizes before allocation. Once the allocation sizes have been set in all dimensions, the data storage itself may be allocated. This can be done in any of the following ways:

Storage for all vars without data storage will be automatically allocated when yk_solution::prepare_solution() is called.
Storage for a specific var may be allocated before calling yk_solution::prepare_solution() via yk_var::alloc_storage().
[Advanced] A var may be merged with another var with existing storage via yk_var::fuse_vars().

Member Function Documentation

◆ get_name()

virtual const std::string & yask::yk_var::get_name ( ) const

pure virtual

Get the name of the var.

Returns: String containing name provided via yc_solution::new_var(), yk_solution::new_var(), or yk_solution::new_fixed_size_var()..

Note: Recall that scratch vars created via yc_solution::new_scratch_var() are temporary variables and thus are not accessible via the kernel APIs.

◆ get_num_dims()

virtual int yask::yk_var::get_num_dims ( ) const

pure virtual

Get the number of dimensions used in this var.

This may include domain, step, and/or miscellaneous dimensions.

Returns: Number of dimensions declared in the stencil code or created via yc_solution::new_var(), yk_solution::new_var(), or yk_solution::new_fixed_size_var().

◆ get_dim_names()

virtual string_vec yask::yk_var::get_dim_names ( ) const

pure virtual

Get all the dimensions in this var.

This may include domain, step, and/or miscellaneous dimensions.

Returns: List of names of all the dimensions.

◆ get_num_domain_dims()

virtual int yask::yk_var::get_num_domain_dims ( ) const

pure virtual

Get the number of domain dimensions used in this var.

Returns: Number of domain dimensions declared in the stencil code or created via yc_solution::new_var(), yk_solution::new_var(), or yk_solution::new_fixed_size_var().

◆ is_dim_used()

virtual bool yask::yk_var::is_dim_used ( const std::string & dim ) const

pure virtual

Determine whether specified dimension exists in this var.

Returns: true if dimension exists (including step-dimension), false otherwise.

◆ is_fixed_size()

virtual bool yask::yk_var::is_fixed_size ( ) const

pure virtual

Determine whether this var is not automatically resized based on the solution.

Returns: true if this var was created via yk_solution::new_fixed_size_var() or false otherwise.

◆ get_first_local_index()

virtual idx_t yask::yk_var::get_first_local_index ( const std::string & dim ) const

pure virtual

Get the first valid index in this rank in the specified dimension.

This is a convenience function that provides the first possible index in any var dimension regardless of the dimension type. If dim is a domain dimension, returns the first accessible index in the left padding area. It is equivalent to get_first_misc_index(dim) for a misc dimension, and get_first_valid_step_index() for the step dimension.

Note: This function should be called only after calling prepare_solution() because prepare_solution() assigns this rank's position in the problem domain. If called before prepare_solution(), zero (0) will be returned.

Returns: the first valid index.

Parameters

[in] dim Name of dimension to get. Must be one of the names from get_dim_names().

◆ get_first_local_index_vec()

virtual idx_t_vec yask::yk_var::get_first_local_index_vec ( ) const

pure virtual

Get the first valid index in this rank in all dimensions in this var.

See get_first_local_index().

Returns: vector of first valid indices.

◆ get_last_local_index()

virtual idx_t yask::yk_var::get_last_local_index ( const std::string & dim ) const

pure virtual

Get the last index in this rank in the specified dimension.

This is a convenience function that provides the last possible index in any var dimension regardless of the dimension type. If dim is a domain dimension, returns the last accessible index in the right padding area. It is equivalent to get_last_misc_index(dim) for a misc dimension, and get_last_valid_step_index() for the step dimension.

Note: This function should be called only after calling prepare_solution() because prepare_solution() assigns this rank's position in the problem domain. If called before prepare_solution(), zero (0) will be returned.

Returns: the last valid index.

Parameters

[in] dim Name of dimension to get. Must be one of the names from get_dim_names().

◆ get_last_local_index_vec()

virtual idx_t_vec yask::yk_var::get_last_local_index_vec ( ) const

pure virtual

Get the last valid index in this rank in all dimensions in this var.

See get_last_local_index().

Returns: vector of last valid indices.

◆ get_alloc_size()

virtual idx_t yask::yk_var::get_alloc_size ( const std::string & dim ) const

pure virtual

Get the number of elements allocated in the specified dimension.

For the domain dimensions, this includes the rank-domain and padding sizes. See the "Detailed Description" for yk_var for information on var sizes. For any dimension dim, get_alloc_size(dim) == get_last_local_index(dim) - get_first_local_index(dim) + 1;

Returns: allocation size in number of elements (not bytes).

Parameters

[in] dim Name of dimension to get. Must be one of the names from get_dim_names().

◆ get_alloc_size_vec()

virtual idx_t_vec yask::yk_var::get_alloc_size_vec ( ) const

pure virtual

Get the number of elements allocated in all dimensions in this var.

See get_alloc_size().

Returns: vector of allocation sizes in number of elements (not bytes).

◆ get_first_valid_step_index()

virtual idx_t yask::yk_var::get_first_valid_step_index ( ) const

pure virtual

Get the first valid index in the step dimension.

The valid step indices in a var are updated by calling yk_solution::run_solution() or one of the element-setting API functions. Equivalient to get_first_local_index(dim), where dim is the step dimension. This var must use the step index.

Returns: the first index in the step dimension that can be used in one of the element-getting API functions.

◆ get_last_valid_step_index()

virtual idx_t yask::yk_var::get_last_valid_step_index ( ) const

pure virtual

Get the last valid index in the step dimension.

The valid step indices in a var are updated by calling yk_solution::run_solution() or one of the element-setting API functions. Equivalient to get_last_local_index(dim), where dim is the step dimension. This var must use the step index.

Returns: the last index in the step dimension that can be used in one of the element-getting API functions.

◆ get_rank_domain_size()

virtual idx_t yask::yk_var::get_rank_domain_size ( const std::string & dim ) const

pure virtual

Get the domain size for this rank in the specified dimension.

Note: This function should be called only after calling prepare_solution() because prepare_solution() assigns this rank's size. If called before prepare_solution(), zero (0) will be returned.

Returns: The same value as yk_solution::get_rank_domain_size() if is_fixed_size() returns false or the fixed sized provided via yk_solution::new_fixed_size_var() otherwise.

Parameters

[in] dim Name of dimension to get. Must be one of the names from get_dim_names() and also yk_solution::get_domain_dim_names().

◆ get_rank_domain_size_vec()

virtual idx_t_vec yask::yk_var::get_rank_domain_size_vec ( ) const

pure virtual

Get the domain size for this rank in all domain dimensions in this var.

See get_rank_domain_size().

Returns: vector of values, one for each domain dimension in this var.

◆ get_first_rank_domain_index()

virtual idx_t yask::yk_var::get_first_rank_domain_index ( const std::string & dim ) const

pure virtual

Get the first index of the sub-domain in this rank in the specified dimension.

Does not include indices of padding area.

Note: This function should be called only after calling prepare_solution() because prepare_solution() assigns this rank's position in the problem domain. If called before prepare_solution(), zero (0) will be returned.

Returns: The same value as yk_solution::get_first_rank_domain_index() if is_fixed_size() returns false or zero (0) otherwise.

Parameters

[in] dim Name of dimension to get. Must be one of the names from get_dim_names() and also yk_solution::get_domain_dim_names().

◆ get_first_rank_domain_index_vec()

virtual idx_t_vec yask::yk_var::get_first_rank_domain_index_vec ( ) const

pure virtual

Get the first index of the sub-domain in this rank in all domain dimensions in this var.

See get_first_rank_domain_index().

Returns: vector of values, one for each domain dimension in this var.

◆ get_last_rank_domain_index()

virtual idx_t yask::yk_var::get_last_rank_domain_index ( const std::string & dim ) const

pure virtual

Get the last index of the sub-domain in this rank in the specified dimension.

Does not include indices of padding area.

Note: This function should be called only after calling prepare_solution() because prepare_solution() assigns this rank's position in the problem domain. If called before prepare_solution(), zero (0) will be returned.

Returns: The same value as yk_solution::get_last_rank_domain_index() if is_fixed_size() returns false or one less than the fixed sized provided via yk_solution::new_fixed_size_var() otherwise.

Parameters

[in] dim Name of dimension to get. Must be one of the names from get_dim_names() and also yk_solution::get_domain_dim_names().

◆ get_last_rank_domain_index_vec()

virtual idx_t_vec yask::yk_var::get_last_rank_domain_index_vec ( ) const

pure virtual

Get the last index of the sub-domain in this rank in all domain dimensions in this var.

See get_last_rank_domain_index().

Returns: vector of values, one for each domain dimension in this var.

◆ get_left_halo_size()

virtual idx_t yask::yk_var::get_left_halo_size ( const std::string & dim ) const

pure virtual

Get the left halo size in the specified dimension.

This value is typically set by the stencil compiler.

Returns: Elements in halo in given dimension before the domain.

Parameters

[in] dim Name of dimension to get. Must be one of the names from get_dim_names() and also yk_solution::get_domain_dim_names().

◆ get_right_halo_size()

virtual idx_t yask::yk_var::get_right_halo_size ( const std::string & dim ) const

pure virtual

Get the right halo size in the specified dimension.

This value is typically set by the stencil compiler.

Returns: Elements in halo in given dimension after the domain.

Parameters

[in] dim Name of dimension to get. Must be one of the names from get_dim_names() and also yk_solution::get_domain_dim_names().

◆ get_first_rank_halo_index()

virtual idx_t yask::yk_var::get_first_rank_halo_index ( const std::string & dim ) const

pure virtual

Get the first index of the left halo in this rank in the specified dimension.

Note: This function should be called only after calling prepare_solution() because prepare_solution() assigns this rank's position in the problem domain. If called before prepare_solution(), zero (0) will be returned.

Returns: The first index of left halo in this rank or the same value as yk_var::get_first_rank_domain_index() if the left halo has zero size.

Parameters

[in] dim Name of dimension to get. Must be one of the names from get_dim_names() and also yk_solution::get_domain_dim_names().

◆ get_first_rank_halo_index_vec()

virtual idx_t_vec yask::yk_var::get_first_rank_halo_index_vec ( ) const

pure virtual

Get the first index of the left halo in this rank in all domain dimensions in this var.

See get_first_rank_halo_index().

Returns: vector of values, one for each domain dimension in this var.

◆ get_last_rank_halo_index()

virtual idx_t yask::yk_var::get_last_rank_halo_index ( const std::string & dim ) const

pure virtual

Get the last index of the right halo in this rank in the specified dimension.

Note: This function should be called only after calling prepare_solution() because prepare_solution() assigns this rank's position in the problem domain. If called before prepare_solution(), zero (0) will be returned.

Returns: The last index of right halo in this rank or the same value as yk_var::get_last_rank_domain_index() if the right halo has zero size.

Parameters

[in] dim Name of dimension to get. Must be one of the names from get_dim_names() and also yk_solution::get_domain_dim_names().

◆ get_last_rank_halo_index_vec()

virtual idx_t_vec yask::yk_var::get_last_rank_halo_index_vec ( ) const

pure virtual

Get the last index of the right halo in this rank in all domain dimensions in this var.

See get_last_rank_halo_index().

Returns: vector of values, one for each domain dimension in this var.

◆ get_left_pad_size()

virtual idx_t yask::yk_var::get_left_pad_size ( const std::string & dim ) const

pure virtual

Get the actual left padding in the specified dimension.

The left padding is the memory allocated before the domain in a given dimension. The left padding size includes the left halo size. The value may be slightly larger than that provided via set_left_min_pad_size(), etc. due to rounding.

Returns: Elements in left padding in given dimension.

Parameters

[in] dim Name of dimension to get. Must be one of the names from get_dim_names() and also yk_solution::get_domain_dim_names().

◆ get_right_pad_size()

virtual idx_t yask::yk_var::get_right_pad_size ( const std::string & dim ) const

pure virtual

Get the actual right padding in the specified dimension.

The right padding is the memory allocated after the domain in a given dimension. The right padding size includes the right halo size. The value may be slightly larger than that provided via set_right_min_pad_size(), etc. due to rounding.

Returns: Elements in right padding in given dimension.

Parameters

[in] dim Name of dimension to get. Must be one of the names from get_dim_names() and also yk_solution::get_domain_dim_names().

◆ get_left_extra_pad_size()

virtual idx_t yask::yk_var::get_left_extra_pad_size ( const std::string & dim ) const

pure virtual

Get the actual extra left padding in the specified dimension.

The extra padding size is the left padding size minus the left halo size.

Returns: Elements in padding in given dimension before the left halo area.

Parameters

[in] dim Name of dimension to get. Must be one of the names from get_dim_names() and also yk_solution::get_domain_dim_names().

◆ get_right_extra_pad_size()

virtual idx_t yask::yk_var::get_right_extra_pad_size ( const std::string & dim ) const

pure virtual

Get the actual extra right padding in the specified dimension.

The extra padding size is the right padding size minus the right halo size.

Returns: Elements in padding in given dimension after the right halo area.

Parameters

[in] dim Name of dimension to get. Must be one of the names from get_dim_names() and also yk_solution::get_domain_dim_names().

◆ get_first_misc_index()

virtual idx_t yask::yk_var::get_first_misc_index ( const std::string & dim ) const

pure virtual

Get the first index of a specified miscellaneous dimension.

Equivalent to get_first_local_index(dim), where dim is a misc dimension.

Returns: the first valid index in a non-step and non-domain dimension.

Parameters

[in] dim Name of dimension to get. Must be one of the names from yk_solution::get_misc_dim_names().

◆ get_last_misc_index()

virtual idx_t yask::yk_var::get_last_misc_index ( const std::string & dim ) const

pure virtual

Get the last index of a specified miscellaneous dimension.

Equivalent to get_last_local_index(dim), where dim is a misc dimension.

Returns: the last valid index in a non-step and non-domain dimension.

Parameters

[in] dim Name of dimension to get. Must be one of the names from get_dim_names() and also yk_solution::get_misc_dim_names().

◆ are_indices_local() [1/2]

virtual bool yask::yk_var::are_indices_local ( const idx_t_vec & indices ) const

pure virtual

Determine whether the given indices refer to an accessible element in this rank.

Provide indices in a list in the same order returned by get_dim_names() for this var. Domain index values are relative to the overall problem domain.

Returns: true if index values fall within the range returned by get_first_local_index(dim) and get_last_local_index(dim) for each dimension dim in the var; false otherwise.

Parameters

[in] indices List of indices, one for each var dimension.

◆ are_indices_local() [2/2]

virtual bool yask::yk_var::are_indices_local ( const idx_t_init_list & indices ) const

pure virtual

Determine whether the given indices refer to an accessible element in this rank.

See are_indices_local().

Parameters

[in] indices List of indices, one for each var dimension.

◆ get_element() [1/2]

virtual double yask::yk_var::get_element ( const idx_t_vec & indices ) const

pure virtual

Read the value of one element in this var.

Provide indices in a list in the same order listed when the var was defined, i,e., the order returned by get_dim_names(). Indices are relative to the overall problem domain.

Note: The return value is a double-precision floating-point value; it will be converted to double-precision for single-precision vars.; do not use this API to get many contiguous values; get_elements_in_slice() is much more efficient.

Returns: value in var at given indices.

Exceptions

yask_exception	if storage has not been allocated.
yask_exception	if are_indices_local(indices) would return `false`.

Parameters

[in] indices List of indices, one for each var dimension.

◆ get_element() [2/2]

virtual double yask::yk_var::get_element ( const idx_t_init_list & indices ) const

pure virtual

Read the value of one element in this var.

See get_element(const idx_t_vec& indices).

Returns: value in var at given indices.

Exceptions

yask_exception	if storage has not been allocated.
yask_exception	if are_indices_local(indices) would return `false`.

Parameters

[in] indices List of indices, one for each var dimension.

◆ set_element() [1/2]

virtual idx_t yask::yk_var::set_element	(	double	val,
		const idx_t_vec &	indices,
		bool	strict_indices = `true`
	)

pure virtual

Set the value of one element in this var.

Provide indices in a list in the same order returned by get_dim_names(). Indices are relative to the overall problem domain. If the var uses the step dimension, the value of the step index will be used to update the current valid step indices in the var. If strict_indices is false and any non-step index values are invalid as defined by are_indices_local(), the API will have no effect and return zero (0).

Note: The parameter value is a double-precision floating-point value, but it will be converted to single-precision for single-precision vars.; do not use this API to set many contiguous values; set_elements_in_slice() is much more efficient.

Returns: Number of elements set, which will be one (1) if the indices are valid and zero (0) if they are not.

Exceptions

yask_exception	if storage has not been allocated.
yask_exception	if `strict_indices` is `true` and are_indices_local(indices) would return `false`.

Parameters

[in]	val	Element in var will be set to this.
[in]	indices	List of indices, one for each var dimension.
[in]	strict_indices	If true, indices must be within the allocated range in this rank. If false, indices outside of domain and padding result in no change to var.

◆ set_element() [2/2]

virtual idx_t yask::yk_var::set_element	(	double	val,
		const idx_t_init_list &	indices,
		bool	strict_indices = `true`
	)

pure virtual

Set the value of one element in this var.

See set_element(double val, const idx_t_vec& indices, bool strict_indices).

Returns: Number of elements set.

Exceptions

yask_exception	if storage has not been allocated.
yask_exception	if `strict_indices` is `true` and are_indices_local(indices) would return `false`.

Parameters

[in]	val	Element in var will be set to this.
[in]	indices	List of indices, one for each var dimension.
[in]	strict_indices	If true, indices must be within the allocated range in this rank. If false, indices outside of domain and padding result in no change to var.

◆ get_elements_in_slice() [1/3]

virtual idx_t yask::yk_var::get_elements_in_slice	(	float *	buffer_ptr,
		size_t	buffer_size,
		const idx_t_vec &	first_indices,
		const idx_t_vec &	last_indices
	)		const

pure virtual

Copy elements within specified subset of this var into a float buffer.

Reads all elements from first_indices to last_indices in each dimension and writes them to consecutive memory locations in the buffer. Indices in the buffer progress in row-major order, i.e., traditional C-language layout, using the order of dimensions when the var was declared. In other words, the last index is "unit-stride" in the buffer.

The buffer pointed to must contain at least the number of floats as the total number of elements in the specified slice. Thus, the buffer must be a simple flat array of data, not containing pointers; for example, for a 2-D YASK var created via MAKE_VAR(A, x, y), the buffer could be declared as float A[xsize*ysize] or float A[xsize][ysize], but not as float** A.

Provide indices in two lists in the same order used during var declaration. Indices are relative to the overall problem domain.

Note: if this is a double-precision solution, each value will be converted to a float, and precision will be lost. The float* version is also more efficient.

Returns: Number of elements read.

Exceptions

yask_exception	if the index values do not fall between the values returned by get_first_local_index() and get_last_local_index(), inclusive.
yask_exception	if storage has not been allocated.
yask_exception	if `buffer_size` is less than the number of values that would be read.

Parameters

[out]	buffer_ptr	Pointer to buffer where values will be written.
[in]	buffer_size	Number of `float` elements in `buffer_ptr` array
[in]	first_indices	List of initial indices, one for each var dimension.
[in]	last_indices	List of final indices, one for each var dimension.

◆ get_elements_in_slice() [2/3]

virtual idx_t yask::yk_var::get_elements_in_slice	(	double *	buffer_ptr,
		size_t	buffer_size,
		const idx_t_vec &	first_indices,
		const idx_t_vec &	last_indices
	)		const

pure virtual

Copy elements within specified subset of this var into a double buffer.

Reads all elements from first_indices to last_indices in each dimension and writes them to consecutive memory locations in the buffer. Indices in the buffer progress in row-major order, i.e., traditional C-language layout, using the order of dimensions when the var was declared. In other words, the last index is "unit-stride" in the buffer.

The buffer pointed to must contain at least the number of doubles as the total number of elements in the specified slice. Thus, the buffer must be a simple flat array of data, not containing pointers; for example, for a 2-D YASK var created via MAKE_VAR(A, x, y), the buffer could be declared as double A[xsize*ysize] or double A[xsize][ysize], but not as double** A.

Provide indices in two lists in the same order used during var declaration. Indices are relative to the overall problem domain.

Note: if this is a single-precision solution, each value will be converted to a double. The double* version is more efficient.

Returns: Number of elements read.

Exceptions

yask_exception	if the index values do not fall between the values returned by get_first_local_index() and get_last_local_index(), inclusive.
yask_exception	if storage has not been allocated.
yask_exception	if `buffer_size` is less than the number of values that would be read.

Parameters

[out]	buffer_ptr	Pointer to buffer where values will be written.
[in]	buffer_size	Number of `double` elements in `buffer_ptr` array
[in]	first_indices	List of initial indices, one for each var dimension.
[in]	last_indices	List of final indices, one for each var dimension.

◆ add_to_element() [1/2]

virtual idx_t yask::yk_var::add_to_element	(	double	val,
		const idx_t_vec &	indices,
		bool	strict_indices = `true`
	)

pure virtual

Atomically add to the value of one var element.

Provide indices in a list in the same order returned by get_dim_names(). Indices are relative to the overall problem domain. Index values must fall between the values returned by get_first_local_index() and get_last_local_index(), inclusive. Updates are OpenMP atomic, meaning that this function can be called by several OpenMP threads without causing a race condition. If storage has not been allocated for this var, this will have no effect and return zero (0) if strict_indices is false.

Note: The parameter value is a double-precision floating-point value, but it will be converted to single-precision if this is a single-precision solution.

Returns: Number of elements updated.

Exceptions

yask_exception if strict_indices is true and any non-step index values are invalid or storage has not been allocated.

Parameters

[in]	val	This value will be added to element in var.
[in]	indices	List of indices, one for each var dimension.
[in]	strict_indices	If true, indices must be within domain or padding. If false, indices outside of domain and padding result in no change to var.

◆ add_to_element() [2/2]

virtual idx_t yask::yk_var::add_to_element	(	double	val,
		const idx_t_init_list &	indices,
		bool	strict_indices = `true`
	)

pure virtual

Atomically add to the value of one var element.

See add_to_element().

Returns: Number of elements set.

Parameters

[in]	val	This value will be added to element in var.
[in]	indices	List of indices, one for each var dimension.
[in]	strict_indices	If true, indices must be within domain or padding. If false, indices outside of domain and padding result in no change to var.

◆ set_all_elements_same()

virtual void yask::yk_var::set_all_elements_same ( double val )

pure virtual

Initialize all var elements to the same value.

Sets all allocated elements, including those in the domain and padding area to the same specified value. If storage has not been allocated, this will have no effect.

Note: The parameter is a double-precision floating-point value, but it will be converted to single-precision if yk_solution::get_element_bytes() returns 4.

Parameters

[in] val All elements will be set to this.

◆ set_elements_in_slice_same()

virtual idx_t yask::yk_var::set_elements_in_slice_same	(	double	val,
		const idx_t_vec &	first_indices,
		const idx_t_vec &	last_indices,
		bool	strict_indices = `true`
	)

pure virtual

Initialize var elements within specified subset of the var to the same value.

Sets all elements from first_indices to last_indices in each dimension to the specified value. Provide indices in two lists in the same order used during var declaration. Indices are relative to the overall problem domain.

Note: The parameter is a double-precision floating-point value, but it will be converted to single-precision if this is a single-precision solution.

Returns: Number of elements set.

Exceptions

yask_exception	if storage has not been allocated.
yask_exception	if `strict_indices` is `true` and any non-step index values do not fall between the values returned by get_first_local_index() and get_last_local_index(), inclusive.

Parameters

[in]	val	All elements in the slice will be set to this.
[in]	first_indices	List of initial indices, one for each var dimension.
[in]	last_indices	List of final indices, one for each var dimension.
[in]	strict_indices	If true, indices must be within domain or padding. If false, only elements within the allocation of this var will be set, and elements outside will be ignored.

◆ set_elements_in_slice() [1/3]

virtual idx_t yask::yk_var::set_elements_in_slice	(	const float *	buffer_ptr,
		size_t	buffer_size,
		const idx_t_vec &	first_indices,
		const idx_t_vec &	last_indices
	)

pure virtual

Set elements within specified subset of the var from values in a float buffer.

Reads float values from consecutive memory locations, starting at buffer_ptr and writes them from first_indices to last_indices in each dimension. Indices in the buffer progress in row-major order, i.e., traditional C-language layout, using the order of dimensions when the var was declared. In other words, the last index is "unit-stride" in the buffer.

The buffer pointed to must contain at least the number of floats as the total number of elements in the specified slice. Thus, the buffer must be a simple flat array of data, not containing pointers; for example, for a 2-D YASK var created via MAKE_VAR(A, x, y), the buffer could be declared as float A[xsize*ysize] or float A[xsize][ysize], but not as float** A.

Provide indices in two lists in the same order used during var declaration. Indices are relative to the overall problem domain.

Note: if this is a double-precision solution, each value will be converted to a double. The double* version is more efficient.

Returns: Number of elements written.

Exceptions

yask_exception	if the index values do not fall between the values returned by get_first_local_index() and get_last_local_index(), inclusive.
yask_exception	if storage has not been allocated.
yask_exception	if `buffer_size` is less than the number of values that would be written.

Parameters

[out]	buffer_ptr	Pointer to buffer where values will be read.
[in]	buffer_size	Number of `float` elements in `buffer_ptr` array
[in]	first_indices	List of initial indices, one for each var dimension.
[in]	last_indices	List of final indices, one for each var dimension.

◆ set_elements_in_slice() [2/3]

virtual idx_t yask::yk_var::set_elements_in_slice	(	const double *	buffer_ptr,
		size_t	buffer_size,
		const idx_t_vec &	first_indices,
		const idx_t_vec &	last_indices
	)

pure virtual

Set elements within specified subset of the var from values in a double buffer.

Reads double values from consecutive memory locations, starting at buffer_ptr and writes them from first_indices to last_indices in each dimension. Indices in the buffer progress in row-major order, i.e., traditional C-language layout, using the order of dimensions when the var was declared. In other words, the last index is "unit-stride" in the buffer.

The buffer pointed to must contain at least the number of doubles as the total number of elements in the specified slice. Thus, the buffer must be a simple flat array of data, not containing pointers; for example, for a 2-D YASK var created via MAKE_VAR(A, x, y), the buffer could be declared as double A[xsize*ysize] or double A[xsize][ysize], but not as double** A.

Provide indices in two lists in the same order used during var declaration. Indices are relative to the overall problem domain.

Note: if this is a single-precision solution, each value will be converted to a float, and precision will be lost. The float* version is also more efficient.

Returns: Number of elements written.

Exceptions

yask_exception	if the index values do not fall between the values returned by get_first_local_index() and get_last_local_index(), inclusive.
yask_exception	if storage has not been allocated.
yask_exception	if `buffer_size` is less than the number of values that would be written.

Parameters

[out]	buffer_ptr	Pointer to buffer where values will be read.
[in]	buffer_size	Number of `double` elements in `buffer_ptr` array
[in]	first_indices	List of initial indices, one for each var dimension.
[in]	last_indices	List of final indices, one for each var dimension.

◆ reduce_elements_in_slice()

virtual yk_reduction_result_ptr yask::yk_var::reduce_elements_in_slice	(	int	reduction_mask,
		const idx_t_vec &	first_indices,
		const idx_t_vec &	last_indices,
		bool	strict_indices = `true`
	)

pure virtual

Perform requested reductions over elements within specified subset of the var.

Reduces all elements from first_indices to last_indices in each dimension. Provide indices in two lists in the same order used during var declaration. Indices are relative to the overall problem domain.

Set reduction_mask to the bit-wise OR of individual mask values, e.g., yk_var::yk_sum_reduction | yk_var::yk_max_reduction.

Returns: Shared pointer to reduction result.

Exceptions

yask_exception	if storage has not been allocated.
yask_exception	if `strict_indices` is `true` and any non-step index values do not fall between the values returned by get_first_local_index() and get_last_local_index(), inclusive.

Parameters

[in]	reduction_mask	Bit-wise OR of the desired reduction masks.
[in]	first_indices	List of initial indices, one for each var dimension.
[in]	last_indices	List of final indices, one for each var dimension.
[in]	strict_indices	If true, indices must be within domain or padding. If false, only elements within the allocation of this var will be evaluated, and elements outside will be ignored.

◆ format_indices() [1/2]

virtual std::string yask::yk_var::format_indices ( const idx_t_vec & indices ) const

pure virtual

Format the indices for human-readable display.

Provide indices in a list in the same order returned by get_dim_names().

Returns: A string containing the var name and the index values.

Parameters

[in] indices List of indices, one for each var dimension.

◆ format_indices() [2/2]

virtual std::string yask::yk_var::format_indices ( const idx_t_init_list & indices ) const

pure virtual

Format the indices for human-readable display.

See format_indices().

Returns: A string containing the var name and the index values.

Parameters

[in] indices List of indices, one for each var dimension.

◆ get_halo_exchange_l1_norm()

virtual int yask::yk_var::get_halo_exchange_l1_norm ( ) const

pure virtual

[Advanced] Get the maximum L1-norm of a neighbor rank for halo exchange.

This setting determines which MPI neighbors participate in a halo exchange. The L1-norm is also known as the "Manhattan distance" or "taxicab norm". In this case, the distance in each domain dimension can be only zero or one, so the sum can range from zero to the number of domain dimensions.

Examples for a domain size with 2 spatial dimensions (e.g., "x" and "y"): L1-norm = 0: no halos are exchanged for this var. L1-norm = 1: halos are exchanged between "up", "down", "left" and "right" neighbors. L1-norm = 2: halos are exchanged as above plus diagonal neighbors.

The actual exchanges are further controlled by the size of the halo in each direction per get_halo_size().

Returns: L1-norm, ranging from zero to number of domain dimensions.

◆ set_halo_exchange_l1_norm()

virtual void yask::yk_var::set_halo_exchange_l1_norm ( int norm )

pure virtual

[Advanced] Set the maximum L1-norm of a neighbor rank for halo exchange.

This should only be used to override the value calculated automatically by the YASK compiler.

See also: get_halo_exchange_l1_norm().

Parameters

[in] norm Maximum L1-norm of neighbor rank with which to exchange halos.

◆ is_dynamic_step_alloc()

virtual bool yask::yk_var::is_dynamic_step_alloc ( ) const

pure virtual

[Advanced] Get whether the allocation of the step dimension of this var can be modified at run-time.

See set_alloc_size().

◆ set_numa_preferred()

virtual bool yask::yk_var::set_numa_preferred ( int numa_node )

pure virtual

[Advanced] Set the default preferred NUMA node on which to allocate data.

This value is used when allocating data for this var. Thus, the desired NUMA policy must be set before calling alloc_data() or yk_solution::prepare_solution().

Returns: true if NUMA preference was set; false if NUMA preferences are not enabled.

Parameters

[in] numa_node Preferred NUMA node. See yk_solution::set_default_numa_preferred() for other options.

◆ get_numa_preferred()

virtual int yask::yk_var::get_numa_preferred ( ) const

pure virtual

[Advanced] Get the default preferred NUMA node on which to allocate data.

Returns: Current setting of preferred NUMA node for this var.

◆ set_left_min_pad_size()

virtual void yask::yk_var::set_left_min_pad_size	(	const std::string &	dim,
		idx_t	size
	)

pure virtual

[Advanced] Set the minimum left padding in the specified dimension.

This sets the minimum number of elements in this var in the left padding area. This padding area can be used for required halo areas. This function may be useful in the unusual case where the final halo size is unknown when the storage is allocated.

Call get_left_pad_size() to determine the actual padding size for the var. See additional behavior related to setting pad size under yk_solution::set_min_pad_size(). See the "Detailed Description" for yk_var for information on var sizes.

Parameters

[in]	dim	Name of dimension to set. Must be one of the names from yk_solution::get_domain_dim_names().
[in]	size	Minimum number of elements to allocate before the domain size.

◆ set_right_min_pad_size()

virtual void yask::yk_var::set_right_min_pad_size	(	const std::string &	dim,
		idx_t	size
	)

pure virtual

[Advanced] Set the minimum right padding in the specified dimension.

This sets the minimum number of elements in this var in the right padding area. This padding area can be used for required halo areas. This function may be useful in the unusual case where the final halo size is unknown when the storage is allocated.

Call get_right_pad_size() to determine the actual padding size for the var. See additional behavior related to setting pad size under yk_solution::set_min_pad_size(). See the "Detailed Description" for yk_var for information on var sizes.

Parameters

[in]	dim	Name of dimension to set. Must be one of the names from yk_solution::get_domain_dim_names().
[in]	size	Minimum number of elements to allocate after the domain size.

◆ set_min_pad_size()

virtual void yask::yk_var::set_min_pad_size	(	const std::string &	dim,
		idx_t	size
	)

pure virtual

[Advanced] Set the minimum padding in the specified dimension.

Shorthand for calling set_left_min_pad_size() and set_right_min_pad_size().

Parameters

[in]	dim	Name of dimension to set. Must be one of the names from yk_solution::get_domain_dim_names().
[in]	size	Minimum number of elements to allocate before and after the domain size.

◆ set_left_halo_size()

virtual void yask::yk_var::set_left_halo_size	(	const std::string &	dim,
		idx_t	size
	)

pure virtual

[Advanced] Set the left halo size in the specified dimension.

This value is typically set by the stencil compiler, but this function allows you to override that value. If the left halo is set to a value larger than the left padding size, the left padding size will be automatically increase to accommodate it.

Note: After data storage has been allocated, the left halo size can only be set to a value less than or equal to the left padding size in the given dimension.

Parameters

[in]	dim	Name of dimension to get. Must be one of the names from yk_solution::get_domain_dim_names().
[in]	size	Number of elements in the left halo.

◆ set_right_halo_size()

virtual void yask::yk_var::set_right_halo_size	(	const std::string &	dim,
		idx_t	size
	)

pure virtual

[Advanced] Set the right halo size in the specified dimension.

This value is typically set by the stencil compiler, but this function allows you to override that value. If the right halo is set to a value larger than the right padding size, the right padding size will be automatically increase to accommodate it.

Note: After data storage has been allocated, the right halo size can only be set to a value less than or equal to the right padding size in the given dimension.

Parameters

[in]	dim	Name of dimension to get. Must be one of the names from yk_solution::get_domain_dim_names().
[in]	size	Number of elements in the right halo.

◆ set_halo_size()

virtual void yask::yk_var::set_halo_size	(	const std::string &	dim,
		idx_t	size
	)

pure virtual

[Advanced] Set the left and right halo sizes in the specified dimension.

Alias for set_left_halo_size(dim, size); set_right_halo_size(dim, size).

Parameters

[in]	dim	Name of dimension to get. Must be one of the names from yk_solution::get_domain_dim_names().
[in]	size	Number of elements in the halo.

◆ set_alloc_size()

virtual void yask::yk_var::set_alloc_size	(	const std::string &	dim,
		idx_t	size
	)

pure virtual

[Advanced] Set the number of elements to allocate in the specified dimension.

Setting an allocation is only allowed in the following cases. Vars created via yc_solution::new_var() are defined at YASK compile time, and vars created via yk_solution methods are defined at YASK kernel run time.

Var creation time	Var creation method	Step dim	Domain dim	Misc dim
Compile-time	yc_solution::new_var() + yc_var::set_dynamic_step_alloc (false) [1]	No	No	Yes [2]
Compile-time	yc_solution::new_var() + yc_var::set_dynamic_step_alloc (true) [1]	Yes	No	Yes [2]
Run-time	yk_solution::new_var()	Yes	No	Yes
Run-time	yk_solution::new_fixed_size_var() [3]	Yes	Yes	Yes

Note: [1] By default, variables created via yc_solution::new_var() do not allow dynamic step allocation.; [2] Misc dim allocations cannot be changed for compile-time vars if the YASK compiler was run with the "-interleave-misc" option.; [3] The term "fixed" in yk_solution::new_fixed_size_var() means that the domain size will not change automatically when its solution domain size changes. It does not mean that the sizes cannot be changed via the APIs–quite the opposite.

The allocation size cannot be changed after data storage has been allocated for this var.

Parameters

[in]	dim	Name of dimension to set. Must be a domain dimension or a misc dimension for user-created vars.
[in]	size	Number of elements to allocate.

◆ set_first_misc_index()

virtual void yask::yk_var::set_first_misc_index	(	const std::string &	dim,
		idx_t	idx
	)

pure virtual

[Advanced] Set the first index of a specified miscellaneous dimension.

Sets the first valid index in a non-step and non-domain dimension. After calling this function, the last valid index will be the first index as set by this function plus the allocation size set by set_alloc_size() minus one.

Parameters

[in]	dim	Name of dimension to get. Must be one of the names from yk_solution::get_misc_dim_names().
[in]	idx	New value for first index. May be negative.

◆ is_storage_allocated()

virtual bool yask::yk_var::is_storage_allocated ( ) const

pure virtual

[Advanced] Determine whether storage has been allocated.

Returns: true if storage has been allocated, false otherwise.

◆ get_num_storage_bytes()

virtual idx_t yask::yk_var::get_num_storage_bytes ( ) const

pure virtual

[Advanced] Determine size of raw storage in bytes.

Returns: Minimum number of bytes required for storage given the current domain size and padding settings.

◆ get_num_storage_elements()

virtual idx_t yask::yk_var::get_num_storage_elements ( ) const

pure virtual

[Advanced] Determine size of raw storage in elements.

Returns: get_num_storage_bytes() / yk_solution.get_element_bytes().

◆ alloc_storage()

virtual void yask::yk_var::alloc_storage ( )

pure virtual

[Advanced] Explicitly allocate data-storage memory for this var.

Amount of allocation is calculated based on domain, padding, and step-dimension allocation sizes. Any pre-existing storage will be released before allocation as via release_storage(). See allocation options in the "Detailed Description" for yk_var.

◆ release_storage()

virtual void yask::yk_var::release_storage ( )

pure virtual

[Advanced] Explicitly release any allocated data-storage for this var.

This will release storage allocated via any of the options described in the "Detailed Description" for yk_var.

◆ is_storage_layout_identical()

virtual bool yask::yk_var::is_storage_layout_identical ( const yk_var_ptr other ) const

pure virtual

[Advanced] Determines whether storage layout is the same as another var.

In order for the storage layout to be identical, the following must be the same:

Number of dimensions.
Name of each dimension, in the same order.
Vector folding in each dimension.
Allocation size in each dimension.
Rank (local) domain size in each domain dimension.
Padding size in each domain dimension.

The following do not have to be identical:

Halo size.

Returns: true if storage for this var has the same layout as other or false otherwise.

◆ fuse_vars()

virtual void yask::yk_var::fuse_vars ( yk_var_ptr source )

pure virtual

[Advanced] Merge this var with another var.

After calling this API, this var var will effectively become another reference to the source var. Any subsequent API applied to this var or the source var will access the same data and/or effect the same changes.

Storage implications:

Any pre-existing storage in this var will be released.
The storage of the this var will become allocated or unallocated depending on that of the source var.
After fusing, calling release_storage() on this var or the source var will apply to both.

See allocation options and more information about var sizes in the "Detailed Description" for yk_var.

Exceptions

yask_exception	if the dimensions and fold-lengths of the `source` var are not identical to `this` var.
yask_exception	if `source` var is a fixed-size var, and the storage, local domain sizes, halos, etc. of the var are not compatible with the solution before calling yk_solution::prepare_solution().

Parameters

[in] source Var to be merged with this var.

◆ get_raw_storage_buffer()

virtual void * yask::yk_var::get_raw_storage_buffer ( )

pure virtual

[Advanced] Get pointer to raw data storage buffer.

The following assumptions about the contents of data are safe:

Each FP element starts at a number of bytes from the beginning of the buffer which is a multiple of yk_solution::get_element_bytes().
All the FP elements will be located within get_num_storage_bytes() bytes from the beginning of the buffer.
A call to set_all_elements_same() will initialize all elements within get_num_storage_bytes() bytes from the beginning of the buffer.
If is_storage_layout_identical() returns true between this and some other var, any given element index applied to both vars will refer to an element at the same offset into their respective data buffers.

Thus,

You can perform element-wise unary mathematical operations on all elements of a var via its raw buffer, e.g., add some constant value to all elements.
If the layouts of two vars are identical, you can use their raw buffers to copy all data from one to the other or perform element-wise binary mathematical operations on them, e.g., add all elements from one var to another.

The following assumptions are not safe:

Any expectations regarding the relationship between an element index and that element's offset from the beginning of the buffer such as row-major or column-major layout.
All elements in the buffer are part of the rank domain or halo.
All elements in the buffer contain valid floating-point values.

Thus,

You should not perform any operations dependent on the logical indices of any element via raw buffer, e.g., matrix multiply.

Returns: Pointer to raw data storage if is_storage_allocated() returns true or NULL otherwise.

◆ get_elements_in_slice() [3/3]

virtual YASK_DEPRECATED idx_t yask::yk_var::get_elements_in_slice	(	void *	buffer_ptr,
		const idx_t_vec &	first_indices,
		const idx_t_vec &	last_indices
	)		const

pure virtual

[Deprecated] Use the float* or double* version.

Note: This version does no type conversion. The type of elements in the buffer must match the type of elements in the var.; At this time, this void* version is the only one available in the Python APIs.

Parameters

[out]	buffer_ptr	Pointer to buffer where values will be written.
[in]	first_indices	List of initial indices, one for each var dimension.
[in]	last_indices	List of final indices, one for each var dimension.

◆ set_elements_in_slice() [3/3]

virtual YASK_DEPRECATED idx_t yask::yk_var::set_elements_in_slice	(	const void *	buffer_ptr,
		const idx_t_vec &	first_indices,
		const idx_t_vec &	last_indices
	)

pure virtual

[Deprecated] Use the float* or double* version.

Note: This version does no type conversion. The type of elements in the buffer must match the type of elements in the var.; At this time, this void* version is the only one available in the Python APIs.

Parameters

[out]	buffer_ptr	Pointer to buffer where values will be read.
[in]	first_indices	List of initial indices, one for each var dimension.
[in]	last_indices	List of final indices, one for each var dimension.

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

yk_var_api.hpp

Classes

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Var Dimensions

Step Dimensions

Domain Dimensions

Miscellaneous Dimensions

Other Details

Elements

Data Storage

Member Function Documentation

◆ get_name()

◆ get_num_dims()

◆ get_dim_names()

◆ get_num_domain_dims()

◆ is_dim_used()

◆ is_fixed_size()

◆ get_first_local_index()

◆ get_first_local_index_vec()

◆ get_last_local_index()

◆ get_last_local_index_vec()

◆ get_alloc_size()

◆ get_alloc_size_vec()

◆ get_first_valid_step_index()

◆ get_last_valid_step_index()

◆ get_rank_domain_size()

◆ get_rank_domain_size_vec()

◆ get_first_rank_domain_index()

◆ get_first_rank_domain_index_vec()

◆ get_last_rank_domain_index()

◆ get_last_rank_domain_index_vec()

◆ get_left_halo_size()

◆ get_right_halo_size()

◆ get_first_rank_halo_index()

◆ get_first_rank_halo_index_vec()

◆ get_last_rank_halo_index()

◆ get_last_rank_halo_index_vec()

◆ get_left_pad_size()

◆ get_right_pad_size()

◆ get_left_extra_pad_size()

◆ get_right_extra_pad_size()

◆ get_first_misc_index()

◆ get_last_misc_index()

◆ are_indices_local() [1/2]

◆ are_indices_local() [2/2]

◆ get_element() [1/2]

◆ get_element() [2/2]

◆ set_element() [1/2]

◆ set_element() [2/2]

◆ get_elements_in_slice() [1/3]

◆ get_elements_in_slice() [2/3]

◆ add_to_element() [1/2]

◆ add_to_element() [2/2]

◆ set_all_elements_same()

◆ set_elements_in_slice_same()

◆ set_elements_in_slice() [1/3]

◆ set_elements_in_slice() [2/3]

◆ reduce_elements_in_slice()

◆ format_indices() [1/2]

◆ format_indices() [2/2]

◆ get_halo_exchange_l1_norm()

◆ set_halo_exchange_l1_norm()

◆ is_dynamic_step_alloc()

◆ set_numa_preferred()

◆ get_numa_preferred()

◆ set_left_min_pad_size()

◆ set_right_min_pad_size()

◆ set_min_pad_size()

◆ set_left_halo_size()

◆ set_right_halo_size()

◆ set_halo_size()

◆ set_alloc_size()

◆ set_first_misc_index()

◆ is_storage_allocated()

◆ get_num_storage_bytes()

◆ get_num_storage_elements()

◆ alloc_storage()

◆ release_storage()