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. Common Applications Interface: the AnalysisStage
   1. Overview of the AnalysisStage
   2. Functionalities provided by the StageAnalysis
   3. Using the StageAnalysis in a standalone simulation
   4. Using the StageAnalysis in a coupled simulation
   5. Note for developers
2. The Python Solver
   1. BaseClass of the Solver
3. Future Outlook

Common Interface of Applications: The AnalysisStage

Overview of the AnalysisStage

The AnalysisStage is a python class located in the KratosCore, that serves as a common interface for the applications. The idea is that the applications derive from this object to implement things specific to each application. These derived classes replace the previously used MainKratos.py. This way the interface to the applications is unified.

Responsibilities of the AnalysisStage: Basically everything that is not related to the physics of a problem. Everything related to the physics of the problem is handled by the PythonSolver (see below)

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, ...)

as well as the User Scripting: Formerly the user-scripting was done directly in the MainKratos.py file. This had the disadvantage that it became outdated with internal updates of Kratos.

Now the intended use is that users derive their scripts from the AnalysisStage classes in the applications and override the functions in which they want to change/add some self-defined things. This way the user-scripts are less likely to become outdated since they only override a small portion of the entire class.

Functionalities provided by the AnalysisStage

The implementation of the AnalysisStage 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.

Python-Solvers

Functionalities provided by the PythonSolver

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

The idea is that the AnalysisStage has a Solver as a member. This way the responsibilities of each object are separated and no BLOB is created.

A draft implementation for the BaseSolver is shown in the following (following what is currently done in FLuidDynamics and StructuralMechanics):

Base Class of the Solver Object (in Kratos Core):

from __future__ import print_function, absolute_import, division  # makes KratosMultiphysics backward compatible with python 2.6 and 2.7

# Importing Kratos
import KratosMultiphysics

class BaseKratosSolver(object):
    """The base class for the python solvers in the applications
    This class knows abt the solution of the physical problem
    """
    def __init__(self, main_model_part, project_parameters):
        """The constructor of the Solver.
        It obtains the project parameters
        This function is intended to be called from the constructor
        of deriving classes:
        super(DerivedSolver, self).__init__(project_parameters)
        """
        if (type(main_model_part) != KratosMultiphysics.ModelPart):
            raise Exception("Input is expected to be provided as a Kratos ModelPart object")

        if (type(custom_settings) != KratosMultiphysics.Parameters):
            raise Exception("Input is expected to be provided as a Kratos Parameters object")

        self.main_model_part = main_model_part
        self.project_parameters = project_parameters

        self._ValidateParameters()

    #### Public functions to run the Analysis ####
    def AddVariables(self):
        pass
    def AddDofs(self):
        pass
    def GetMinimumBufferSize(self):
        pass
    def PrepareModelPartForSolver(self):
        pass
    def _ValidateParameters(self):
        pass
    def ComputeDeltaTime(self):
        pass
    def Inizialize(self):
        pass
    def GetComputingModelPart(self):
        pass
    def SetEchoLevel(self):
        pass
    def Clear(self):
        pass
    def Check(self):
        pass

    def Solve(self):
        """This function solves one step
        It can be called several times during one time-step
        This is equivalent to calling "solving_strategy.Solve()" (without "Initialize")
        This function is NOT intended to be overridden in deriving classes!
        """
        self.InitializeSolutionStep()
        self.Predict()
        self.SolveSolutionStep()
        self.FinalizeSolutionStep()

    def InitializeSolutionStep(self):
        """This function performs all the required operations that should be done
        (for each step) before solving the solution step.
        This function has to be implemented in deriving classes!
        """
        raise NotImplementedError("This function has to be implemented by derived\
            analysis classes")

    def Predict(self):
        """This function predicts the solution
        This function has to be implemented in deriving classes!
        """
        raise NotImplementedError("This function has to be implemented by derived\
            analysis classes")

    def SolveSolutionStep(self):
        """This function solves the current step
        This function has to be implemented in deriving classes!
        """
        raise NotImplementedError("This function has to be implemented by derived\
            analysis classes")

    def FinalizeSolutionStep(self):
        """This function Performs all the required operations that should be done
        (for each step) after solving the solution step.
        This function has to be implemented in deriving classes!
        """
        raise NotImplementedError("This function has to be implemented by derived\
            analysis classes")

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