Ginkgo: BatchLinOp

| Ginkgo Generated from branch based on main. Ginkgo version 1.11.0 A numerical linear algebra library targeting many-core architectures

Loading...
Searching...
No Matches
BatchLinOp
Collaboration diagram for BatchLinOp:

## Classes
class | gko::batch::BatchLinOpFactory
| A BatchLinOpFactory represents a higher order mapping which transforms one batch linear operator into another. More...
class | gko::batch::EnableBatchLinOp< ConcreteBatchLinOp, PolymorphicBase >
| The EnableBatchLinOp mixin can be used to provide sensible default implementations of the majority of the BatchLinOp and PolymorphicObject interface. More...
class | gko::batch::matrix::Csr< ValueType, IndexType >
| Csr is a general sparse matrix format that stores the column indices for each nonzero entry and a cumulative sum of the number of nonzeros in each row. More...
class | gko::batch::matrix::Dense< ValueType >
| Dense is a batch matrix format which explicitly stores all values of the matrix in each of the batches. More...
class | gko::batch::matrix::Ell< ValueType, IndexType >
| Ell is a sparse matrix format that stores the same number of nonzeros in each row, enabling coalesced accesses. More...
class | gko::batch::matrix::Identity< ValueType >
| The batch Identity matrix, which represents a batch of Identity matrices. More...
class | gko::batch::preconditioner::Jacobi< ValueType, IndexType >
| A block-Jacobi preconditioner is a block-diagonal linear operator, obtained by inverting the diagonal blocks (stored in a dense row major fashion) of the source operator. More...
class | gko::batch::solver::Bicgstab< ValueType >
| BiCGSTAB or the Bi-Conjugate Gradient-Stabilized is a Krylov subspace solver. More...
class | gko::batch::solver::Cg< ValueType >
| Cg or the Conjugate Gradient is a Krylov subspace solver. More...

## Macros
#define | GKO_ENABLE_BATCH_LIN_OP_FACTORY(_batch_lin_op, _parameters_name, _factory_name)
| This macro will generate a default implementation of a BatchLinOpFactory for the BatchLinOp subclass it is defined in.

## Typedefs
template<typename ConcreteFactory, typename ConcreteBatchLinOp, typename ParametersType, typename PolymorphicBase = BatchLinOpFactory>
using | gko::batch::EnableDefaultBatchLinOpFactory
| This is an alias for the EnableDefaultFactory mixin, which correctly sets the template parameters to enable a subclass of BatchLinOpFactory.

## Detailed Description

# Batched Linear operator as a concept

A batch linear operator (BatchLinOp) forms the base class for all batched linear algebra objects. In general, it follows the same structure as the LinOp class, but has some crucial differences which make it not strictly representable through or with the LinOp class.

A batched operator is defined as a set of independent linear operators which have no communication/information exchange between them. Therefore, any collective operations between the batches is not possible and not implemented. This allows for each batch to be computed and operated on in an embarrassingly parallel fashion.

A key difference between the LinOp and the BatchLinOp class is that the apply between BatchLinOps is no longer supported. The user can apply a BatchLinOp to a batch::MultiVector but not to any general BatchLinOp.

Therefore, the BatchLinOp serves only as a base class providing necessary core functionality from Polymorphic object and store the dimensions of the batched object.

Note
  Apply to batch::MultiVector objects are handled by the concrete LinOp and may be moved to the base BatchLinOp class in the future.

BatchLinOp

## Macro Definition Documentation

## ◆ GKO_ENABLE_BATCH_LIN_OP_FACTORY

#define GKO_ENABLE_BATCH_LIN_OP_FACTORY | ( |  | _batch_lin_op,
|  |  | _parameters_name,
|  |  | _factory_name )

This macro will generate a default implementation of a BatchLinOpFactory for the BatchLinOp subclass it is defined in.

It is required to first call the macro GKO_CREATE_FACTORY_PARAMETERS() before this one in order to instantiate the parameters type first.

The list of parameters for the factory should be defined in a code block after the macro definition, and should contain a list of GKO_FACTORY_PARAMETER_* declarations. The class should provide a constructor with signature _batch_lin_op(const _factory_name *, std::shared_ptr<const BatchLinOp>) which the factory will use a callback to construct the object.

A minimal example of a batch linear operator is the following:

struct MyBatchLinOp : public EnableBatchLinOp<MyBatchLinOp> {
GKO_ENABLE_BATCH_LIN_OP_FACTORY(MyBatchLinOp, my_parameters, Factory) {
// a factory parameter named "my_value", of type int and default
// value of 5
int GKO_FACTORY_PARAMETER_SCALAR(my_value, 5);
// a factory parameter named `my_pair` of type `std::pair<int,int>`
// and default value {5, 5}
std::pair<int, int> GKO_FACTORY_PARAMETER_VECTOR(my_pair, 5, 5);
};
// constructor needed by EnableBatchLinOp
explicit MyBatchLinOp(std::shared_ptr<const Executor> exec) {
: EnableBatchLinOp<MyBatchLinOp>(exec) {}
// constructor needed by the factory
explicit MyBatchLinOp(const Factory *factory,
std::shared_ptr<const BatchLinOp> matrix)
: EnableBatchLinOp<MyBatchLinOp>(factory->get_executor()),
matrix->get_size()),
// store factory's parameters locally
my_parameters_{factory->get_parameters()}
{
int value = my_parameters_.my_value;
// do something with value
}
GKO_ENABLE_BATCH_LIN_OP_FACTORY
#define GKO_ENABLE_BATCH_LIN_OP_FACTORY(_batch_lin_op, _parameters_name, _factory_name)
This macro will generate a default implementation of a BatchLinOpFactory for the BatchLinOp subclass ...
Definition batch_lin_op.hpp:358
GKO_FACTORY_PARAMETER_SCALAR
#define GKO_FACTORY_PARAMETER_SCALAR(_name, _default)
Creates a scalar factory parameter in the factory parameters structure.
Definition abstract_factory.hpp:445
GKO_FACTORY_PARAMETER_VECTOR
#define GKO_FACTORY_PARAMETER_VECTOR(_name,...)
Creates a vector factory parameter in the factory parameters structure.
Definition abstract_factory.hpp:461
gko::log::profile_event_category::factory
@ factory
LinOpFactory events.
Definition profiler_hook.hpp:32

MyBatchLinOp can then be created as follows:

auto exec = gko::ReferenceExecutor::create();
// create a factory with default `my_value` parameter
auto fact = MyBatchLinOp::build().on(exec);
// create a operator using the factory:
auto my_op = fact->generate(gko::batch::matrix::Identity::create(exec, 2));
std::cout << my_op->get_my_parameters().my_value; // prints 5
// create a factory with custom `my_value` parameter
auto fact = MyLinOp::build().with_my_value(0).on(exec);
// create a operator using the factory:
auto my_op = fact->generate(gko::batch::matrix::Identity::create(exec, 2));
std::cout << my_op->get_my_parameters().my_value; // prints 0
gko::batch::matrix::Identity::create
static std::unique_ptr< Identity > create(std::shared_ptr< const Executor > exec, const batch_dim< 2 > &size=batch_dim< 2 >{})
Creates an Identity matrix of the specified size.

Note
  It is possible to combine both the #GKO_CREATE_FACTORY_PARAMETER_*() macros with this one in a unique macro for class templates (not with regular classes). Splitting this into two distinct macros allows to use them in all contexts. See https://stackoverflow.com/q/50202718/9385966 for more details.

Parameters

  _batch_lin_op | concrete operator for which the factory is to be created [CRTP parameter]
  _parameters_name | name of the parameters member in the class (its type is <_parameters_name>_type, the protected member's name is <_parameters_name>_, and the public getter's name is get_<_parameters_name>())
  _factory_name | name of the generated factory type

## Typedef Documentation

## ◆ EnableDefaultBatchLinOpFactory

template<typename ConcreteFactory, typename ConcreteBatchLinOp, typename ParametersType, typename PolymorphicBase = BatchLinOpFactory>

using gko::batch::EnableDefaultBatchLinOpFactory

Initial value:
EnableDefaultFactory<ConcreteFactory, ConcreteBatchLinOp, ParametersType,
PolymorphicBase>
gko::EnableDefaultFactory
This mixin provides a default implementation of a concrete factory.
Definition abstract_factory.hpp:126

This is an alias for the EnableDefaultFactory mixin, which correctly sets the template parameters to enable a subclass of BatchLinOpFactory.

Template Parameters

  ConcreteFactory | the concrete factory which is being implemented [CRTP parameter]
  ConcreteBatchLinOp | the concrete BatchLinOp type which this factory produces, needs to have a constructor which takes a const ConcreteFactory *, and an std::shared_ptr<const BatchLinOp> as parameters.
  ParametersType | a subclass of enable_parameters_type template which defines all of the parameters of the factory
  PolymorphicBase | parent of ConcreteFactory in the polymorphic hierarchy, has to be a subclass of BatchLinOpFactory