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. Note for developers
3. PythonSolver
   1. PythonSolver: Overview
   2. PythonSolver: Responsibilities and provided Functionalities
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).

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.

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
• 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

PythonSolver: Responsibilities and provided Functionalities

The implementation of the PythonSolver can be found here. It shall be referred to the implementation for an exact description of what the individual functions are doing, see their docstrings.

The responsibility of the PythonSolver is to solve the physical problem. This also involves the coupling of two or more PythonSolvers. I.e. and FSISolver would have a Fluid and a Structural solver as well as the data exchange (mapping) and the coupling logic.

The AnalysisStage Object is designed to solve an entire Simulation. This means that it sets up the Boundary conditions, IO, reading of the ModelPart and Materials, controlling the time-stepping etc. It does not know abt how to solve the physical problem. This is the task of the PythonSolver. This class implements everything that is related to solve the physical problem, e.g. it constructs Strategy, BuilderAndSolver,... Everything else (e.g. reading the ModelPart) is excluded form the Solver and part of the AnalysisStage.

Furthermore, it knows abt which Variables and DOFs it needs and adds them to the ModelPart It does NOT read the ModelPart, this is task of the AnalysisStage. After the ModelPart is read, the solver might need to perform some operations on it (e.g. create the ComputingModelPart), this is done with PrepareModelPartForSolver.

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()