Edit me

Overview

This page will guide the users how to configure the json for the CoSimulation.

Problem Data

The json file starts with the problem data. All the inputs in the problem data has to be identical as the other solvers used for the CoSimulation. For an example, the problem data of the FSI Mok benchmark between the json files of the Fluid Dynamics Application (ProjectParametersCFD.json), the Structural Mechanics Application (ProjectParametersCSM.json) and the CoSimulation Application (ProjectParametersCoSim.json) should be identical.

{
    "problem_data" :
    {
        "start_time" : 0.0,
        "end_time" : 25.0,
        "echo_level" : 0,
        "print_colors" : true,
        "parallel_type" : "OpenMP"
    },

Solver Settings

Coupling strategy

Users can choose the coupling strategy at the “type” field. Certain strategy gives additional settings, such as the maximum number of iteration for each time step. These addtional settings can be found at the respective page of the coupling strategy.

    "solver_settings" :
    {
        "type" : "<coupling_strategy>",
        "echo_level" : 1,
        "num_coupling_iterations" : 12,

The available names for <coupling_strategy> are listed below:

Coupling Sequence

This part of the settings dictate the communication between the solvers used in the CoSimulation. The order of the solver executed will follow the order of the items inside the "coupling_sequence" field. Each item correspond to one solver. It has the name of the solver, the input_data_list and the output_data_list. The name field correspond on a solver naming that the user created in the "solvers" part of the solver settings. More details about how the solver is defined is explained here. The data to be transfered are managed in the input_data_list and output_data_list. The input_data_list contains the data to be used for the current solver. On the other hand, the output_data_list contains the data from this solver to be sent to another solver.

Each item inside "input_data_list" contain:

"data" : variable of the input data.
"from_solver_data" : source for the input data.
"from_solver" : the solver of which source comes from.
"data_transfer_operator" : the transfer operator for the data.

Similarly, "output_data_list" contain:

"data" : variable of the output data.
"to_solver_data" : destination of the output data.
"to_solver" : the solver of the output destination.
"data_transfer_operator" : the transfer operator for the data.

Optionally, the "input_data_list" and "output_data_list" may also include:

"data_transfer_operator_options" : additional option that the user can use from the "data_transfer_operator"
"before_data_transfer_operations" : operation to be executed before the data transfer.
"after_data_transfer_operations" : operation to be executed after the data transfer.

Coupling Sequence Example

Here’s an example. The solvers used in this simulation are "fluid_solver" and "structure_solver". The Cosimulation will first execute the fluid solver, and then the structural solver. In this first example the details of the data to be transfered are managed solely inside "structure_solver". With this set-up, the structural solver will first gather the data listed in the "input_data_list". With the data naming convention made in the solvers description, the sequence are:

Run "fluid_solver" simulation.
Execute "Coupling_Operation_A".
Find a data called "fluid_solver_load" from "fluid_solver".
Execute "Data_Transfer_Operator_A" with its optional settings, namely "swap_sign" and "use_transpose" . Transfer the data into "structure_solver_load".
Execute "Coupling_Operation_B".
Run "structure_solver" simulation.
Copy "structure_solver_displacement" from the "structure_solver".
Execute "Data_Transfer_Operator_A". Transfer the data into "fluid_solver_displacement" of "fluid_solver".

*here are the details for the naming convention for the solvers used in this setup.

*here are the details of the data transfer operator used in this setup.

*here are the details of the coupling operation used in this setup.

Alternatively, the coupling sequence could be set-up like this or this. Both of them has the same meaning as the first example, but defined differently.

“coupling_sequence” setup

        "coupling_sequence":
        [
            {
                "name": "fluid_solver",
                "input_data_list"  : [],
                "output_data_list" : []
            },
            {
                "name": "structure_solver",
                "input_data_list": [
                    {
                        "data"             : "structure_solver_load",
                        "from_solver"      : "fluid_solver",
                        "from_solver_data" : "fluid_solver_load",
                        "data_transfer_operator" : "Data_Transfer_Operator_A",
                        "data_transfer_operator_options" : ["swap_sign", "use_transpose"],
                        "before_data_transfer_operations" : ["Coupling_Operation_A"],
                        "after_data_transfer_operations" : ["Coupling_Operation_B"]
                    }
                ],
                "output_data_list": [
                    {
                        "data"           : "structure_solver_displacement",
                        "to_solver"      : "fluid_solver",
                        "to_solver_data" : "fluid_solver_displacement",
                        "data_transfer_operator" : "Data_Transfer_Operator_A"
                    }
                ]
            }
        ],

“coupling_sequence” alternative 1

        "coupling_sequence":
        [
            {
                "name": "fluid_solver",
                "input_data_list"  : [],
                "output_data_list" : [
                    {
                        "data"           : "fluid_solver_load",
                        "to_solver"      : "structure_solver",
                        "to_solver_data" : "structure_solver_load",
                        "data_transfer_operator" : "Data_Transfer_Operator_A",
                        "data_transfer_operator_options" : ["swap_sign", "use_transpose"],
                        "before_data_transfer_operations" : ["Coupling_Operation_A"],
                        "after_data_transfer_operations" : ["Coupling_Operation_B"]
                    }
                ]
            },
            {
                "name": "structure_solver",
                "input_data_list": [],
                "output_data_list": [
                    {
                        "data"           : "structure_solver_displacement",
                        "to_solver"      : "fluid_solver",
                        "to_solver_data" : "fluid_solver_displacement",
                        "data_transfer_operator" : "Data_Transfer_Operator_A"
                    }
                ]
            }
        ],

“coupling_sequence” alternative 2

        "coupling_sequence":
        [
            {
                "name": "fluid_solver",
                "input_data_list"  : [
                    {
                        "data"           : "fluid_solver_displacement",
                        "from_solver"      : "structure_solver",
                        "from_solver_data" : "structure_solver_displacement",
                        "data_transfer_operator" : "Data_Transfer_Operator_A"
                    }
                ],
                "output_data_list" : [
                    {
                        "data"           : "fluid_solver_load",
                        "to_solver"      : "structure_solver",
                        "to_solver_data" : "structure_solver_load",
                        "data_transfer_operator" : "Data_Transfer_Operator_A",
                        "data_transfer_operator_options" : ["swap_sign", "use_transpose"],
                        "before_data_transfer_operations" : ["Coupling_Operation_A"],
                        "after_data_transfer_operations" : ["Coupling_Operation_B"]
                    }
                ]
            },
            {
                "name": "structure_solver",
                "input_data_list": [],
                "output_data_list": []
            }
        ],

Solvers

In this part, the user define the solvers to be used for the CoSimulation. For convenience, the user is free to assign a name for the solvers. For an example here, the fluid dynamics solver is named as "fluid_solver", and the structural mechanics solver is named as "structure_solver". The assigned names will only be used inside the json file of CoSimulation. After assigning a name, the user must declare the details of the solver. Here are the required fields:

"type" : is the solver wrapper for the application or the solver. Here are the available solver wrappers:
"solver_wrapper_settings": contain the settings for the solver wrapper, such as the name of the "input_file" for the solver’s project parameters.
"data": contain the variables of the solver. To declare a variable, the user assign a name for it and pinpoint the variable source.
- "model_part_name": the model part of which the variable is located.
- "dimension": the dimention of the variable.
- "variable_name": Kratos variable name of the solver. (not the assigned name by the user)

“solvers” example

Here is an example used for the coupling sequence described here

        "solvers" :
        {
            "fluid_solver":
            {
                "type" : "solver_wrappers.kratos.fluid_dynamics_wrapper",
                "solver_wrapper_settings" : {
                    "input_file"  : "ProjectParametersCFD"
                },
                "data" : {
                    "fluid_solver_displacement" : {
                        "model_part_name"   : "FluidModelPart.interface",
                        "dimension" : 2,
                        "variable_name" : "MESH_DISPLACEMENT"
                    },
                    "fluid_solver_load" : {
                        "model_part_name"   : "FluidModelPart.interface",
                        "dimension" : 2,
                        "variable_name" : "REACTION"
                    },
                    "fluid_solver_velocity" : {
                        "model_part_name"   : "FluidModelPart.interface",
                        "dimension" : 2,
                        "variable_name" : "VELOCITY"
                    }
                }
            },
            "structure_solver" :
            {
                "type" : "solver_wrappers.kratos.structural_mechanics_wrapper",
                "solver_wrapper_settings" : {
                    "input_file"  : "ProjectParametersCSM"
                },
                "data" : {
                    "structure_solver_displacement" : {
                        "model_part_name"   : "Structure.interface",
                        "dimension" : 2,
                        "variable_name" : "DISPLACEMENT"
                    },
                    "structure_solver_load" : {
                        "model_part_name"   : "Structure.interface",
                        "dimension" : 2,
                        "variable_name" : "POINT_LOAD"
                    }
                }
            }
        }

Convergence Criteria

The user choose the criteria for convergence here. After the type is chosen, the variable for the convergence criteria is set by selecting the solver in the “solver” field and the variable from the solver in the “data_name” field. In the example below, the displacement of the fluid solver ("fluid_solver_displacement") is used for determining the convergence.

        "convergence_criteria" : [
            {
                "type"          : "convergence_type",
                "solver"        : "fluid_solver",
                "data_name"     : "fluid_solver_displacement",
                "abs_tolerance" : 1e-6,
                "rel_tolerance" : 1e-6
            }
        ],

The available "type" are listed below:

Convergence Accelerators

The convergence of the coupling strategy such as the strong coupling can be improved by using convergence accelerator.

        "convergence_accelerators" : [
            {
                "type"      : "mvqn",
                "solver"    : "fluid",
                "data_name" : "disp"
            }
        ],

The available convergence accelerators are listed below:

Predictors

Predictors helps the solver by predicting the solution for the next timestep . It can be used both in a weak coupling and a strong coupling. The available predictors are listed below:

    "predictors" : [
        {
            "type" : "average_value_based",
            "solver"         : "fluid",
            "data_name"      : "reaction"
        }
    ],

Data Transfer Operators

Transfering data between two simulation with the same solver may be simple, but it is a different case for data transfer between two different solver. Take an FSI simulation for an example. The fluid solver would need a fine mesh, especially at the interface between the fluid domain and the structural domain. Meanwhile, structural solver don’t need a fine mesh to solve the structure. This leads to a complication at the interface, where both solver has their own mesh. To solve this, the user can transform the data before sending it to another solver.

The available data transfer operators are listed below:

Data transfer operator example