Common Python Interface of Applications for Users

ATTENTION, this is WORK IN PROGRESS

See current pull requests:

• https://github.com/KratosMultiphysics/Kratos/pull/2068
• https://github.com/KratosMultiphysics/Kratos/pull/2135

Overview

1. Introduction
2. AnalysisStage
   1. AnalysisStage: Overview
   2. AnalysisStage: Responsibilities and provided Functionalities
   3. AnalysisStage: Usage
3. PythonSolver
   1. PythonSolver: Overview
   2. PythonSolver: Responsibilities and provided Functionalities
   3. PythonSolver: Usage
4. Future Outlook

Introduction

Solving a problem with Kratos is divided into two Python-objects : The AnalysisStage and the PythonSolver.

The PythonSolver is responsible for everything related to the physics of the problem (e.g. how to setup the system of equations), whereas the AnalysisStage is related to everything that is not related to the physics (e.g. when and what output to write).

This means that coupling of physics is done on solver level. A coupled solver would contain the solvers of the involved physics as well as e.g. coupling logic, data exchange, ... . The coupling of things not related to physics is done in the AnalysisStage, e.g. combined output.

The PythonSolver is a member of the AnalysisStage, therefore the AnalysisStage can be seen as "outer" layer and the PythonSolver as "inner" layer.

AnalysisStage

AnalysisStage: Overview

The baseclass of the AnalysisStage is located in the KratosCore (here). It provides a set of functionalities needed to perform a simulation. Applications should derive from this object to implement things specific to the application.

In coupled simulations everything that is not related to the physics of a problem is done in the AnalysisStage. This can be e.g. special user scripting or combined output.

These derived classes replace what was formerly done in MainKratos.py. This means that also the user scripting should be in these classes: The idea is that instead of having a custom MainKratos.py the user derives a class from the AnalysisStage of the application to be used. Only the functions require modifications are being overridden, the remaining implementation is used from the baseclass. This way updates to the baseclass are automatically being used in the users custom AnalysisStage.

AnalysisStage: Responsibilities and provided Functionalities

The AnalysisStage handles everything not related to the physics of the problem. This includes e.g.

• Managing and calling the PythonSolver
• Construction and handling of the Processes
• Managing the output (post-processing in GiD/h5, saving restart, ...)

The main public functions are listed together with a brief explanation in the following. For a more detailed explanation it is referred to the docstrings of the respective functions.

• Run: this function executes the entire simulation
• Initialize: this function initializes the AnalyisStage, i.e. it performs all the operations necessary before the solution loop
• RunSolutionLoop: this function runs the solution loop
• Finalize: this function finalizes the AnalyisStage, i.e. it performs all the operations necessary after the solution loop

The main protected functions that are supposed to be used in derived classes are:

• _GetSolver : This function returns the PythonSolver. It also internally creates it if it does not exist yet
• _GetListOfProcesses : This function returns the list of processes. It also internally creates it if it does not exist yet
• _GetListOfOutputProcesses : This function returns the list of output processes. It also internally creates it if it does not exist yet

AnalysisStage: Usage

In order to use the AnalysisStage it has to be constructed with specific objects:

• KratosMultiphysics.Model: The model containing all the modelparts involved in a simulation (=> WIP)
• KratosMultiphysics.Parameters: The settings for the simulation. They are expecting that the following settings are present:
  • problem_data : general settings for the simulation
  • solver_settings : settings for the PythonSolver
  • processes : regular processes, e.g. for the boundary conditions
  • output_processes : processes that write the output

{
"problem_data" : {
    "echo_level"    : 0
    "parallel_type" : "OpenMP" # or "MPI"
    "start_time"    : 0.0,
    "end_time"      : 1.0
},
"solver_settings" : {
...
settings for the PythonSolver
...
},
"processes" : {
    "my_processes" : [
    list of Kratos Processes
    ],
    "list_initial_processes" : [
    list of Kratos Processes
    ],
    "list_boundary_processes" : [
    list of Kratos Processes
    ],
    "list_custom_processes" : [
    list of Kratos Processes
    ]
},
"output_processes" : {
    "all_output_processes" : [
    list of Kratos Output Processes
    ]
}

---

Objects deriving from the AnalysisStage have to implement the _CreateSolver function which creates and returns the specific PythonSolver

Note: If the order in which the processes-blocks are initialized matters (if e.g. some processes would overwrite settings of other processes), then the function _GetOrderOfProcessesInitialization (resp. _GetOrderOfOutputProcessesInitialization) has to be overridden in the derived class. This function returns a list with the order in which the processes will be initialized.

As example we consider the settings above: We want the processes "list_initial_processes" to be constructed first and "list_custom_processes" to be constructed second. The order in which the other processes are initialized does not matter. In this case we have to override the _GetOrderOfProcessesInitialization function to return ["list_initial_processes", "list_custom_processes"]. With this we achieve the desired behavior.

PythonSolver

PythonSolver: Overview

The baseclass of the PythonSolver is located in the KratosCore (here). It provides a set of functionalities that are needed for solving a physical problem. Applications should derive from this object to implement the application-specific tasks.

If physics are being coupled (e.g. for Fluid-Structure Interaction) then this should be implemented on solver-level. The coupled solver used the solvers of the involved physics and does also other tasks such as coupling logic or data exchange. E.g. an FSISolver would have a fluid and a structural solver.

PythonSolver: Responsibilities and provided Functionalities

The PythonSolver is responsible for everything related to the physics of a problem. This includes e.g.

• Settings up and solving of the system of equations
• Reading and preparing the ModelPart
• Advancing in time

The main public functions are listed together with a brief explanation in the following. For a more detailed explanation it is referred to the docstrings of the respective functions.

• AddVariables : this function adds the variables needed in the solution to the ModelPart
• AddDofs : this function adds the dofs needed in the solution to the ModelPart
• PrepareModelPart : this function prepares the ModelPart to be used by the solver (e.g. create SubModelParts necessary for the solution)
• AdvanceInTime: this function advances the PythonSolver in time
• Initialize: this function initializes the PythonSolver
• Predict: this function predicts the new solution
• InitializeSolutionStep: this function prepares solving a solutionstep
• SolveSolutionStep: this function solves a solutionstep
• FinalizeSolutionStep: this function finalizes solving a solutionstep
• Finalize: this function finalizes the PythonSolver

PythonSolver: Usage

In order to use the PythonSolver it has to be constructed with specific objects:

• KratosMultiphysics.ModelPart: The modelpart to be used by the PythonSolver
• KratosMultiphysics.Parameters: The settings for the PythonSolver. They are expecting that the following settings are present:
  • echo_level : echo_level for printing informations
  • model_import_settings : settings for importing the modelpart

{
"echo_level" : 0,
"model_import_settings" : {
    "input_type"     : "mdpa" # or "rest"
    "input_filename" : "input_file_name"
}

Outlook (Kratos-Project, Multi-Stage Simulation)

Note This is a collection of ideas, to be done AFTER AnalysisStage and Solver are implemented in a first version. Please note that the following is in a very early design phase.

In the future the objects presented here can be used in a larger context, e.g. a Multi-Stage Analysis. This means that e.g. a FormFinding Analysis can be performed with doing a FSI-simulation afterwards. The above mentioned objects are already designed for this, e.g. a ModelPart can be passed from outside to the AnalysisStage, this means that it can be used in severals AnalysisStages.

The idea is that in the beginning all AnalysisStages are constructed (i.e. all necessary Variables are added to the ModelPart), then the ModelPart is being read. This can be done e.g. by a global ModelManager. For this to work the Model has to be enhanced, therefore it should be done later.

This could look like this:

import KratosMultiphysics

##construct all the stages  

Model = KratosMultiphysics.Kernel().GetModel() #if we want it to be somewhere else more than fine
list_of_analysis_stages = GenerateStages(Model, "ProjectParameters.json") #internally loads the applications needed

model_manager.Read(list_of_analysis_stages, Model)
for solver in list_of_solvers:
    solver.Initialize()
    solver.Run()
    solver.Finalize()