Initial API for data transfers between main program and libtrixi

[sloede]

Here are some initial thoughts for an API that would allow one to do more than just control the main time integration loop from outside. The idea is to keep this initial post updated (by anyone) with the results of the subsequent discussion.

Basic querying

Functions to get basic information from Trixi.jl.

int trixi_ndims(int handle);         // Return number of spatial dimensions
int trixi_nelements(int handle);     // Return number of elements (cells)
int trixi_polydeg(int handle);       // Return polynomial degree of DGSEM approximation
int trixi_nvariables(int handle);    // Return number of (conservative) variables
int trixi_ndofs(int handle);         // Return total number of degrees of freedom
int trixi_ndofs_element(int handle); // Return number of degrees of freedom for one element

Raw data exchange

Direct access to solution data u.

void trixi_load_u(double* u, int handle);        // Load data from Trixi.jl into `u`
void trixi_store_u(const double* u, int handle); // Store data from `u` in Trixi.jl

Block-structured data exchange

DGSEM has >> 1 degrees of freedom (DOF) per element. However, other programs might not care for our Gauss node distribution and just want equidistant data (a.k.a. finite-volume-type block-structured data), e.g., 8x8x8 cell-centered values per element. Thus we provide convenience functions that allow loading and storing in such block-structured format and do the conversion to Gauss nodes internally.

void trixi_set_blocksize(int blocksize, int handle);   // Set 1D block size
int  trixi_get_blocksize(int handle);                  // Get 1D block size
int  trixi_ndofs_block(int handle);                    // Return total #DOFs for block-structured data
void trixi_load_u_block(double* u, int handle);        // Load block-structured data from Trixi.jl
void trixi_store_u_block(const double* u, int handle); // Store block structured data in Trixi.jl

[benegee]

Current status

Basic querying

• int trixi_ndims(int handle); // Return number of spatial dimensions
• int trixi_nelements(int handle); // Return number of elements (cells) on local MPI rank
• int trixi_nelements_global(int handle); // Return global number of element (cells)
• int trixi_nvariables(int handle); // Return number of (conservative) variables
• int trixi_polydeg(int handle); // Return polynomial degree of DGSEM approximation
• int trixi_ndofs(int handle); // Return total number of degrees of freedom
• int trixi_ndofs_element(int handle); // Return number of degrees of freedom for one element

Data exchange

Pointwise

• void trixi_load_primitive_vars(int handle, int variable_id, double * data);
  Compute primitive variables and load variable with variable_id into data.
• void trixi_store_primitive_vars(int handle, int variable_id, double * data);

Piecewise constant

• void trixi_load_element_averaged_primitive_vars(int handle, int variable_id, double * data);
  Compute cell-wise averages of variable with variable_id and load into data.
• void trixi_store_cell_averages(double * data, int handle);
  Store cell-wise averages for Trixi, e.g. a velocity field for a transport problem.

DG aware

• Data would need to be interpolated to Gauss nodes. This could be done using a finer mesh, i.e. n^d finite-volume-type cells are used to set up a DG polynomial on a single cell with n^d DOFs.