diff --git a/include/yc_node_api.hpp b/include/yc_node_api.hpp index b0c62fc7..1897054e 100644 --- a/include/yc_node_api.hpp +++ b/include/yc_node_api.hpp @@ -765,40 +765,40 @@ namespace yask { /// Operator version of yc_node_factory::new_negation_node(). yc_number_node_ptr operator-(yc_number_node_ptr rhs); - //@{ + ///@{ /// Operator version of yc_node_factory::new_addition_node(). yc_number_node_ptr operator+(yc_number_node_ptr lhs, yc_number_node_ptr rhs); yc_number_node_ptr operator+(double lhs, yc_number_node_ptr rhs); yc_number_node_ptr operator+(yc_number_node_ptr lhs, double rhs); - //@} + ///@} - //@{ + ///@{ /// Operator version of yc_node_factory::new_division_node(). yc_number_node_ptr operator/(yc_number_node_ptr lhs, yc_number_node_ptr rhs); yc_number_node_ptr operator/(double lhs, yc_number_node_ptr rhs); yc_number_node_ptr operator/(yc_number_node_ptr lhs, double rhs); - //@} + ///@} - //@{ + ///@{ /// Operator version of yc_node_factory::new_mod_node(). yc_number_node_ptr operator%(yc_number_node_ptr lhs, yc_number_node_ptr rhs); yc_number_node_ptr operator%(double lhs, yc_number_node_ptr rhs); yc_number_node_ptr operator%(yc_number_node_ptr lhs, double rhs); - //@} + ///@} - //@{ + ///@{ /// Operator version of yc_node_factory::new_multiplication_node(). yc_number_node_ptr operator*(yc_number_node_ptr lhs, yc_number_node_ptr rhs); yc_number_node_ptr operator*(double lhs, yc_number_node_ptr rhs); yc_number_node_ptr operator*(yc_number_node_ptr lhs, double rhs); - //@} + ///@} - //@{ + ///@{ /// Operator version of yc_node_factory::new_subtraction_node(). yc_number_node_ptr operator-(yc_number_node_ptr lhs, yc_number_node_ptr rhs); yc_number_node_ptr operator-(double lhs, yc_number_node_ptr rhs); yc_number_node_ptr operator-(yc_number_node_ptr lhs, double rhs); - //@} + ///@} /// Operator version of yc_node_factory::new_not_node(). /** For Python, use `rhs.yc_not()` */ @@ -817,53 +817,53 @@ namespace yask { // pointer comparisons, which would result in bools rather than YASK // nodes in expressions like 'x >= fac.new_first_domain_index(x) + 5'. - //@{ + ///@{ /// Operator version of yc_node_factory::new_equals_node(). yc_bool_node_ptr operator==(yc_number_node_ptr lhs, yc_number_node_ptr rhs); yc_bool_node_ptr operator==(yc_index_node_ptr lhs, yc_number_node_ptr rhs); yc_bool_node_ptr operator==(yc_number_node_ptr lhs, yc_index_node_ptr rhs); yc_bool_node_ptr operator==(yc_index_node_ptr lhs, yc_index_node_ptr rhs); - //@} + ///@} - //@{ + ///@{ /// Operator version of yc_node_factory::new_greater_than_node(). yc_bool_node_ptr operator>(yc_number_node_ptr lhs, yc_number_node_ptr rhs); yc_bool_node_ptr operator>(yc_index_node_ptr lhs, yc_number_node_ptr rhs); yc_bool_node_ptr operator>(yc_number_node_ptr lhs, yc_index_node_ptr rhs); yc_bool_node_ptr operator>(yc_index_node_ptr lhs, yc_index_node_ptr rhs); - //@} + ///@} - //@{ + ///@{ /// Operator version of yc_node_factory::new_less_than_node(). yc_bool_node_ptr operator<(yc_number_node_ptr lhs, yc_number_node_ptr rhs); yc_bool_node_ptr operator<(yc_index_node_ptr lhs, yc_number_node_ptr rhs); yc_bool_node_ptr operator<(yc_number_node_ptr lhs, yc_index_node_ptr rhs); yc_bool_node_ptr operator<(yc_index_node_ptr lhs, yc_index_node_ptr rhs); - //@} + ///@} - //@{ + ///@{ /// Operator version of yc_node_factory::new_not_equals_node(). yc_bool_node_ptr operator!=(yc_number_node_ptr lhs, yc_number_node_ptr rhs); yc_bool_node_ptr operator!=(yc_index_node_ptr lhs, yc_number_node_ptr rhs); yc_bool_node_ptr operator!=(yc_number_node_ptr lhs, yc_index_node_ptr rhs); yc_bool_node_ptr operator!=(yc_index_node_ptr lhs, yc_index_node_ptr rhs); - //@} + ///@} - //@{ + ///@{ /// Operator version of yc_node_factory::new_not_greater_than_node(). yc_bool_node_ptr operator<=(yc_number_node_ptr lhs, yc_number_node_ptr rhs); yc_bool_node_ptr operator<=(yc_index_node_ptr lhs, yc_number_node_ptr rhs); yc_bool_node_ptr operator<=(yc_number_node_ptr lhs, yc_index_node_ptr rhs); yc_bool_node_ptr operator<=(yc_index_node_ptr lhs, yc_index_node_ptr rhs); - //@} + ///@} - //@{ + ///@{ /// Operator version of yc_node_factory::new_not_less_than_node(). yc_bool_node_ptr operator>=(const yc_number_node_ptr lhs, const yc_number_node_ptr rhs); yc_bool_node_ptr operator>=(yc_index_node_ptr lhs, yc_number_node_ptr rhs); yc_bool_node_ptr operator>=(yc_number_node_ptr lhs, yc_index_node_ptr rhs); yc_bool_node_ptr operator>=(yc_index_node_ptr lhs, yc_index_node_ptr rhs); - //@} + ///@} #endif diff --git a/include/yk_grid_api.hpp b/include/yk_grid_api.hpp index de99d234..6fc7c7b2 100644 --- a/include/yk_grid_api.hpp +++ b/include/yk_grid_api.hpp @@ -53,21 +53,21 @@ namespace yask { You may also use yk_solution::new_grid() or yk_solution::new_fixed_size_grid() if you need a grid that is not part of the pre-defined solution. - Grid Dimensions - =============== + # Grid Dimensions # + Each dimension of a grid is one of the following: - - The *step* dimension, typically time ("t"), + - 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", + - 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 - -------------- + ## Step Dimensions # + The step dimension, as defined during YASK compilation, - is the dimension in which the simulation proceeds. + 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 @@ -104,13 +104,17 @@ namespace yask { applications that need to access a grid using absolute rather than logical step indices. - Domain Dimensions - -------------- + ## 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. + In each domain dimension, grid sizes include the following components: - The *domain* is the elements to which the stencils are applied. - - The *left padding* is all the elements before the domain and includes the left halo. - - The *right padding* is all the elements before the domain and includes the right halo. + - 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 @@ -146,25 +150,25 @@ namespace yask { 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 - -------------- + ## 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_grid::get_first_misc_index() and yk_grid::get_last_misc_index(). - Other Details - =========== - Elements - ----------- + # 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 - ----------- + ## Data Storage # + Initially, a grid is not assigned any allocated storage. This is done to allow modification of domain, padding, and other allocation sizes before allocation. @@ -992,9 +996,9 @@ namespace yask { effect the same changes. Storage implications: + - Any pre-existing storage in this grid will be released. - The storage of the this grid will become allocated or unallocated depending on that of the source grid. - Any pre-existing storage in this grid will be released. - After fusing, calling release_storage() on this grid or the `source` grid will apply to both. @@ -1002,8 +1006,9 @@ namespace yask { properly, if this grid is used in a kernel, the dimensions and fold-lengths of the `source` grid must be identical or an exception will the thrown. If the `source` grid is a fixed-size - grid, the storage, local domain sizes, halos, etc. of the grid - are set to be compatible with the solution. Otherwise, + grid, the storage, local domain sizes, halos, etc. of the grid + must be set to be compatible with the solution before + calling yk_solution::prepare_solution(). Otherwise, yk_solution::prepare_solution() will throw an exception. See allocation options and more information about grid sizes