Code coupling in Kraken

Basics of signalling

When the solver is executed from command line by Cerberus, the solver should read its own input, initialize the specified signalling mode via the specified greeting protocol.

After the greeting and its own basic initialization, the solver should wait for further signals from Cerberus.

After each order received from Cerberus, the solver should fullfill the order and wait for further signals from Cerberus.

All numerical values will be passed as double precision integers or double precision floats.

Basic "function calls"

When the solvers have completed their previous order and are waiting for the next signal from Cerberus, Cerberus will initiate the communication with a single integer indicating which "function call" should be processed.

The function calls that should be supported by the solvers are:

• terminate
• giveInputFieldTemplates
• giveOutputFieldTemplates
• giveFieldData
• takeFieldData
• giveOutputVariableDefs
• giveOutputVariableData
• giveInputVariableDefs
• takeVariableData
• solveSteadyState
• returnPresentTime (in the future)
• suggestTimeStep (in the future)
• setTimeStep (in the future)
• solveTimeStep (in the future)
• validateTimeStep (in the future)
• abortTimeStep (in the future)

Each of these function calls corresponds to a certain integer, that are listed in some centrally located header (or some such) files for C and Fortran.

The following sections will go through the signalling for each of the function calls

terminate

When Cerberus sends the signal for a solver to terminate. The solver simply exits gracefully. Final results can be collected, processed and printed out. Memory should be freed, and the process should be terminated in the end.

No further signalling takes place after the C->S signal to terminate.

giveInputFieldTemplates

The solver should communicate, which sorts of fields it is expecting to receive from Cerberus. The communication syntax is as follows:

Direction	Name	Size and type	Content
S->C	NF	1*integer	Number of fields to be provided
The following repeats NF times:
S->C	Lname	1*integer	Length of field name in char excluding terminating character
S->C		Lname*char	Name of the field
S->C		5*integer	Unit of the field in an OpenFOAMish array (see Field unit array)
S->C		1*float	Multiplier used to convert from the base unit type specified by the unit array to the actual unit used by the solver.
S->C		1*integer	Type of the mesh that the field is on (see Mesh types).
S->C		<depends on mesh>	Mesh data, see subsection Mesh types
S->C		1*integer	Indexing flag: 0 if solver uses the default indexing of the mesh. 1 if solver uses some other indexing.
[S->C]		[number of cells in the mesh]	Only if indexing flag was given as 1 (use custom indexing): Indexing information

After the solver has finished sending data to Cerberus, it should wait for further signals from Cerberus.

giveOutputFieldTemplates

The solver should communicate, which sorts of fields it is expecting to provide to Cerberus. The communication syntax is as follows:

Direction	Name	Size and type	Content
S->C	NF	1*integer	Number of fields to be provided
The following repeats NF times:
S->C	Lname	1*integer	Length of field name in char excluding terminating character
S->C		Lname*char	Name of the field
S->C		5*integer	Unit of the field in an OpenFOAMish array (see Field unit array)
S->C		1*float	Multiplier used to convert from the base unit type specified by the unit array to the actual unit used by the solver: (SI unit) * (multiplier) = solver unit
S->C		1*integer	Type of the mesh that the field is on (see Mesh types).
S->C		<depends on mesh>	Mesh data, see subsection Mesh types
S->C		1*integer	Indexing flag: 0 if solver uses the default indexing of the mesh. 1 if solver uses some other indexing.
[S->C]		[number of cells in the mesh]	Only if indexing flag was given as 1 (use custom indexing): Indexing information

After the solver has finished sending data to Cerberus, it should wait for further signals from Cerberus.

giveFieldData

The solver should provide the data for the field requested by Cerberus.

The communication syntax is as follows:

Direction	Name	Size and type	Content
C->S	Lname	1*integer	Length of name of field to be passed (in char excluding terminating character).
C->S		Lname*char	Name of the field to be passed
S->C	NV	1*integer	Number of values to be passed.
S->C		NV*float	The values for the field.

After the solver has finished passing data to Cerberus, it should wait for further signals from Cerberus.

takeFieldData

The solver should receive the data for the field indicated by Cerberus.

The communication syntax is as follows:

Direction	Name	Size and type	Content
C->S	Lname	1*integer	Length of name of field to be passed (in char excluding terminating character).
C->S		Lname*char	Name of the field to be passed
C->S	NV	1*integer	Number of values to be passed.
C->S		NV*float	The values for the field.

After the solver has finished receiving data from Cerberus, it should wait for further signals from Cerberus.

giveOutputVariableDefs

The solver should communicate names of the variables it is expecting to provide to Cerberus. The communication syntax is as follows:

Direction	Name	Size and type	Content
S->C	NV	1*integer	Number of variable definitions to be provided
The following repeats NV times:
S->C	Lname	1*integer	Length of name of variable to be passed (in char excluding terminating character).
S->C		Lname*char	Name of the variable to be passed
S->C		1*integer	Statistics flag: 1 if solver will provide mean values along with relative errors (Seprent). 0 if solver will only provide values (deterministic solvers).
S->C		1*integer	Number of values to be passed.

After the solver has finished sending data to Cerberus, it should wait for further signals from Cerberus.

giveOutputVariableData

The solver should provide the variable requested by Cerberus.

The communication syntax is as follows:

Direction	Name	Size and type	Content
C->S	Lname	1*integer	Length of name of variable to be passed (in char excluding terminating character).
C->S		Lname*char	Name of the variable to be passed
S->C		1*integer	Statistics flag: 1 if solver will provide mean values along with relative errors (Seprent). 0 if solver will only provide values (deterministic solvers).
S->C	NV	1*integer	Number of values to be passed.
S->C		NV*float	Variable values.
S->C		NV*float	Only if statistics flag was given as 1. Relative errors.

After the solver has finished passing data to Cerberus, it should wait for further signals from Cerberus.

giveInputVariableDefs

The solver should communicate names of the variables it is expecting to accept from Cerberus. The communication syntax is as follows:

Direction	Name	Size and type	Content
S->C	NV	1*integer	Number of variable definitions to be provided
The following repeats NV times:
S->C	Lname	1*integer	Length of the name of the variable to be passed (in char excluding terminating character).
S->C		Lname*char	Name of the variable to be passed
S->C		1*integer	Variable type. Supported values: 0 (transformation) and 1 (miscellaneous).
S->C		1*integer	Number of values to be passed.

After the solver has finished sending data to Cerberus, it should wait for further signals from Cerberus.

takeVariableData

The solver should receive the data for the variable indicated by Cerberus.

The communication syntax is as follows:

Direction	Name	Size and type	Content
C->S	Lname	1*integer	Length of the name of the variable to be passed (in char excluding terminating character).
C->S		Lname*char	Name of the variable to be passed
C->S		1*integer	Variable type. Currently only value of 0 (transformation) is supported.
C->S	NV	1*integer	Number of values to be passed.
C->S		NV*float	The values for the variable.

After the solver has finished receiving data from Cerberus, it should wait for further signals from Cerberus.

solveSteadyState

The solver should simply execute the next steady state solution using the current input fields.

After the solver has finished the steady state solution, it should wait for further signals from Cerberus.

returnPresentTime

The solver should return the time corresponding to the current time point as a float.

After the S->C communication of the value. The solver should wait for further signals from Cerberus.

suggestTimeStep

The solver should return a preferred length for the next time step as a float.

After the S->C communication of the value. The solver should wait for further signals from Cerberus.

setTimeStep

The solver should receive a length for the next time step as a float.

After the C->S communication of the value. The solver should wait for further signals from Cerberus.

solveTimeStep

The solver should execute the solution for the next time step. This can include some initialization and post-processing for the current solution if needed.

After the solution has completed. The solver should wait for further signals from Cerberus.

validateTimeStep

The solver should accept the previous solution as the final solution for the previous time step. The previous time step will not be calculated again.

After any necessary processing has completed. The solver should wait for further signals from Cerberus.

abortTimeStep

The solver should reload the solution from the beginning of the previously solved time step, discarding the end-of-timestep solution. The previous time step will most likely be calculated again. The solver should update its internal time to reflect this change.

After any necessary processing has completed. The solver should wait for further signals from Cerberus.

Field unit array

The field unit array consists of 5 integers (e.g.  1 -3  0  0  0 for mass density) specifying the dimension for each of the 5 SI base units for the field

No.	Property	Unit
1	Mass	kilogram (kg)
2	Length	metre (m)
3	Time	second (s)
4	Temperature	Kelvin (K)
5	Quantity	mole (mol)

This means that some of the basic fields that we might transfer will have types of

Field name	SI unit	Basic unit	Unit array
Mass density	kg/m3	kg*m-3	1 -3  0  0  0
Temperature	K	K	0  0  0  1  0
Power (integral)	W	kg*m2*s-3	1  2 -3  0  0
Power density	W/m3	kg*m-1*s-3	1 -1 -3  0  0

Mesh types

Each physical data field consists of values on a specific mesh. Whereas several mesh types should be supported by Cerberus, the individual solvers typically only need to support their own mesh types. This section describes the geometry of the different mesh types supported by Cerberus and the mesh-data (the ordered list of values exactly specifying the mesh) associated with each mesh type.

Type 1 — Structured regular Cartesian mesh

Structured regular Cartesian meshes (in Kraken) are 3D meshes that cover a cuboid volume ([x_min, x_max]*[y_min, y_max]*[z_min, z_max]) and have a fixed number of cells in the x-, y- and z-direction (N_x, N_y, N_z). The total number of cells is the product of the number of cells in each of the three coordinate directions. The size/spacing of the cells is constant, but can be different for the different directions.

The mesh data for structured Cartesian meshes is as follows

Data type/size	Data content (explanation)	Data content (example)	Notes
1*integer	Mesh type	1
	Information on mesh size
1*integer	Nx	2
1*integer	Ny	1
1*integer	Nz	4
	Information on mesh boundaries
2*float	xmin, xmax	-10.0, 10.0	The outer limits of the mesh.
2*float	ymin, ymax	-5.0, 5.0	The outer limits of the mesh.
2*float	zmin, zmax	0.0, 100.0	The outer limits of the mesh.

Default indexing

x runs fastest, then y and finally z slowest.

All indices increase from minimum coordinate to maximum coordinate.

Type TBD — Structured irregular Cartesian mesh

Structured Cartesian meshes (in Kraken) are 3D meshes that cover a cuboid volume ([x_min, x_max]*[y_min, y_max]*[z_min, z_max]) and have a fixed number of cells in the x-, y- and z-direction (N_x, N_y, N_z). The total number of cells is the product of the number of cells in each of the three coordinate directions. For the irregular version, the size/spacing of the cells need not be constant.

The mesh data for structured irregular Cartesian meshes is as follows

Data type/size	Data content (explanation)	Data content (example)	Notes
1*integer	Mesh type	TBD
	Information on mesh size
1*integer	Nx	2	Number of cells in X-direction.
1*integer	Ny	1	Number of cells in Y-direction.
1*integer	Nz	4	Number of cells in Z-direction.
	Information on mesh boundaries
(Nx+1)*float	x0, x1, ..., xNx+1	-10.0, -5.0, 10.0	The cell boundaries in X-direction.
(Ny+1)*float	y0, y1, ..., yNy+1	-5.0, 5.0	The cell boundaries in Y-direction.
(Nz+1)*float	z0, z1, ..., zNz+1	0.0, 35.0, 50.0, 65.0, 100.0	The cell boundaries in Z-direction.

Default indexing

x runs fastest, then y and finally z slowest.

All indices increase from minimum coordinate to maximum coordinate.

Type 2 — Structured x-type 60 degree hexagonal mesh

A single axial layer of the x-type (pointy top) hexagonal mesh with a 60 degree angle between the basis vectors is shown here:

Type 3 — Structured y-type 60 degree hexagonal mesh

A single axial layer of the y-type (flat top) hexagonal mesh with a 60 degree angle between the basis vectors is shown here:

Type 4 — Structured x-type 120 degree hexagonal mesh

A single axial layer of the x-type (pointy top) hexagonal mesh with a 120 degree angle between the basis vectors is shown here:

Type 5 — Structured y-type 120 degree hexagonal mesh

A single axial layer of the y-type (flat top) hexagonal mesh with a 120 degree angle between the basis vectors is shown here:

Type 8 — Nested mesh

Data type/size	Data content (explanation)	Data content (example)	Notes
1*integer	Mesh type	8
1*integer	Nm	2	Number of nested meshes.
	Information on Nm nested meshes
1*integer	Mesh 1 type (top level)	1
	... The rest of the mesh 1 data.
	Mesh 2 type (second highest level)	1
	... The rest of the mesh 2 data.
	Mesh Nm type (lowest level)	1
	... The rest of the mesh Nm data.

Type 9 — List

The list mesh type does not have any clearly defined spatial structure. It may be useful for passing in data, for which the exact geometric configuration is irrelevant.

Data type/size	Data content (explanation)	Data content (example)	Notes
1*integer	Mesh type	9
1*integer	Nval	10	Number of values in the list.

Indexing array

Each of the mesh types described in the previous section have their own default indexing sometimes referred to as global indexing.

Sometimes the data accepted or provided by a solver may lie on a specific mesh type but follow an indexing that is different from this default. Consider the situation in the following figure:

The red numbers indicate the default indexing in this 2x2x1 regular Cartesian mesh. If our coupled solver would have the inverse indexing shown in white, we would have to account for that fact in the data transfer. The idea in the Cerberus coupling is to allow the coupled solvers to send and receive data in their preferred indexing, so that the coupled solvers do not have to rearrange data when sending or receiving it. This is achieved by the option to provide an indexing array as a part of a field template.

The indexing array, which needs to be sent if the indexing flag in the sent field template is set to 1 is simply an array of integers with the length of the array corresponding to the number of cells in the mesh and the contents of the array describing which solver index (white) corresponds to which global index (red). The first value of the array indicates the solver index corresponding to global index 1 and so on.

The indexing array for our 2x2 example above would thus be

4 3 2 1

The indexing array can also account for the fact that the coupled solver will not accept or provide data for specific cell index/indices. If the coupled solver would only provide data for fuel rods and the geometry for the simulation would be as follows:

In this case the coupled solver does not consider the global cell 5 to be a part of its solution domain and thus will not provide or accept field data for that cell. Global cell 5 can be left un-indexed by setting the value 0 for it in the indexing array, which would now be

8 7 6 5 0 4 3 2 1

In such cases where some mesh cells are not indexed, the number of values for the field transferred between Cerberus and the solver will be reduced. In this case only 8 values would be transferred in the giveFieldData and takeFieldData calls.

Extending the previous example from 3x3x1 to 3x3x2 the indexing array might be

8 7 6 5 0 4 3 2 1 16 15 14 13 0 12 11 10 9

assuming that the indexing of the coupled solver on the upper axial layer is similar to that in the lower axial layer shown in the previous figure.