[Doc] Add core processes

docs/pages/Kratos/For_Developers/Kratos_Structure/Kernel_Application_Approach.md

@@ -6,32 +6,34 @@ sidebar: kratos_for_developers
 summary: 
 ---
 
+## Overview
+
 Kratos is designed as a framework for building multi-disciplinary finite element programs. Generality in design and implementation is the first requirement. Flexibility and extensibility are another key points in this design, enabling the developers to implement very different formulations and algorithms involving in the solution of multi-disciplinary problems. Kratos as a library must provide a good level of reusability in its provided tools. The key point here is to help users develop easily and fastly their own finite element code using generic components provided by Kratos, or any other applications. Important requirements are good performance and memory efficiency. This features are necessary for enabling applications implemented using Kratos, to deal with industrial multi-disciplinary problems. Finally it has to provide different levels of users' (LINK to who may use kratos) contributions to the Kratos system, and match their requirements and difficulties in the way they extend it. Developers may want to just make a plug-in extension, create an application over it, or using IO scripts to make Kratos perform a certain algorithm. Experts of different fields are given a unique framework to work on in order to create multi-disciplinary finite element applications.
 
 An object-oriented structure has been designed to maximize the reusability and extensibility of the code. This structure is based on finite element methodology and many objects are designed to represent the basic finite element concepts. In this way the structure becomes easily understandable for developers with a finite element method background. In this design Vector, Matrix, and Quadrature representing the basic numerical concepts. Node, Element, Condition, and Dof are defined directly form finite element concepts. Model, Mesh, and Properties are from the practical methodology used in finite element modeling complemented by ModelPart, and SpatialContainer, for organizing better all data necessary for analysis. IO, LinearSolver, Process, and Strategy represent the different steps of a finite element program flow. Finally Kernel and Application are defined for library management and its interface definition.
 
-[[http://kratos-wiki.cimne.upc.edu/images/5/59/ObjectsKratosintro.jpg]]
+[image](http://kratos-wiki.cimne.upc.edu/images/5/59/ObjectsKratosintro.jpg)
 
 Kratos uses a multi-layer approach in its design which reduces the dependency between different parts of program. It helps in maintenance of the code and also helps developers in understanding the code. These layers are defined in a way such as each user has to work in the smallest number of layers as possible. In this way the amount of code that each users has to be familiar with is minimized and the chance of conflict between users of different categories is reduced. The implementation difficulties needed for each layer is also tuned for the knowledge of users working in it. For example the finite element layer uses only basic to average features of C++ programming but the main developer layer use advanced language features in order to provide desired performance.
 
-[[http://kratos-wiki.cimne.upc.edu/images/2/20/LayersKratosintro.jpg]]
+[image](http://kratos-wiki.cimne.upc.edu/images/2/20/LayersKratosintro.jpg)
 
-== Basic Tools ==
+## Basic Tools
 
 Different reusable tools have been implemented to help developers in writing their applications in Kratos. Several geometries and different quadrature methods are provided and their performances are optimized. Their flexible design and general interface make them suitable for use in different applications. Their optimized performance make them appropriate not only for academic applications but also for real industrial simulations. An extensible structure for linear solvers has been designed and different common solvers have been implemented. In this design the solver encapsulates only the solving algorithms and all operations over vectors and matrices are encapsulated in space classes. In this way solvers become independent of the type of mathematical containers and can be used to solve completely different types of equations systems like symmetric, skyline, etc. This structure also allows highly optimized solvers (for just one type of matrices or vectors) to be implemented without any problem.
 
-== Variable Base Interface ==
+## Variable Base Interface
 
 A new variable base interface has been designed and implemented. All information about a concept or variable to be passed through this interface is encapsulated in the Variable class. The information about components of a variable also is encapsulated in the VariableComponent class which gives an additional flexibility to this interface. This interface is used at different levels of abstraction and proved to be very clear, flexible, and extensible. Variable provides the type of data statically and objects can use it to configure their operations for a given type of data via template implementation. This type information also prevents the use of variables in procedures that cannot handle their type of data. Each variable has a unique key which can be used as the reference key in data structures. The name of variable as an string helps routines like IO to read and write them without requiring additional parameters. Finally it provides a zero value which can be used for initializing data independent of its type in generic algorithms. Beside this information, variable provides different methods for raw memory manipulations. These methods are excellent tools for low level generic programming, specially for writing heterogeneous containers. This interface has been used successfully in different parts of Kratos. Its flexibility and extendibility is demonstrated in practice and its evident contribution to readability of the code is shown. This interface played a great role in uniforming different concepts coming from different area of analysis.
 
-== Data Structure == 
+## Data Structure
 
 New heterogeneous containers have been implemented in order to hold different types of data without any modifications. The DataValueContainer can be used to store variables of any type without even explicitly defining the list of them. This container is very flexible but uses a search mechanism to retrieve given variable's data. The VariablesListContainer only stores the variables defined in its variables list which can be have any type but its advantage is its fast indirection mechanism for finding the variables data. In Kratos these two containers are used alternatively in places where performance or flexibility are more important. Being able to store even the list of neighbor Nodes or Elements shows their flexibility in practice. An entity base data structure has been developed in Kratos. This approach gives more freedom in partitioning the domain or in creating and removing Nodes and Elements, for example in adaptive meshing. Several levels of abstraction are provided to help users group model and data information in different ways. In Kratos the Model contains the whole model, divided to different ModelParts. Each model part can have different Meshes which hold a complete set of entities in Kratos. These objects are effectively used for separating domain information or sending a single part to some process.
 
-== Finite Element Implementation == 
+## Finite Element Implementation
 
 The Element and Condition classes are designed as the extension points of Kratos. Their generic interfaces provide all information necessary for calculating their local components and also are flexible enough for handling new arguments in the future. Several processes and strategies has been developed to handle standard procedures in finite element programming. These components increase the reusability of the code and decrease the effort needed to implement new finite element application using Kratos. Some experimental work has been done to handle elemental expression using a higher level of abstraction. In this way elemental expressions can be written in C++ but with a meta language very similar to mathematical notations and then can be compiled with the rest of the code using the C++ compiler. These expressions have been successfully tested and their performance is comparable to manually implemented codes.Finally the Formulation is designed to handle nodal, edge based, or even elemental formulations in different forms of implementations. However these capabilities have not been implemented yet due to the lack of interest from developers.
 
-== Input-Output == 
+## Input-Output
 
 A flexible and extensible IO module for finite element programs has been developed. It can handle new concepts very easily while Kratos automatically adds variables to its components and IO uses these components as its list of concepts. Therefore any application built with Kratos can use IO for reading and writing its own concepts without making any change to it. However, more effort is required to extend this IO system to handle new types of data. This IO is multi-format. It can support new formats just by adding a new IO derived class an without changing any other part of IO. For example a binary format IO can be added using this feature. An interpreter is also implemented to handle Kratos data files. Its format is relatively intuitive and similar to Python scripts. The major interpreting task is given to the Python interpreter. This flexible interpreter with its object-oriented high level language can be used to implement and execute new algorithms using Kratos. In this way the implementation and maintenance cost of a new sophisticated interpreter is eliminated.

docs/pages/Kratos/For_Users/Getting_Started/Kratos_Input_Files_And_IO.md

@@ -0,0 +1,155 @@
+---
+title: Kratos Input Files and IO
+keywords: 
+tags: [Kratos-input-files-and-IO.md]
+sidebar: kratos_for_users
+summary: 
+---
+
+## Introduction
+
+In the first tutorial you have successfully used Kratos to solve a few simple problems. The GiD preprocessor was used to create the input files for Kratos. There are three different types of files that compose a Kratos case:
+* `.py`: A python script to run Kratos
+* `.json`: Contains settings for Kratos
+* `.mdpa`: Contains the model part information
+
+These files where created by the GUI and used to directly start the simulation. In this tutorial we will have a closer look at the input files and their content. Also we will use Kratos without GUI but directly from the command line.
+This is a first step in order to customize the input files for Kratos to special use cases as it will be done in the following tutorials and the more flexible usage of Kratos beyond the GUI.
+
+You can download the input files for a simple structural mechanics case [here](https://github.com/KratosMultiphysics/Documentation/tree/master/Workshops_files/Kratos_Workshop_2019/Sources/2_Kratos_input_files_and_IO).**
+
+## The Kratos python script
+The main file of a Kratos simulation is a python script. It is responsible to load the required Kratos applications and to call the main Kratos functionalities as desired by the user. 
+
+### MainKratos.py
+The main python script for Kratos is commonly named `MainKratos.py`. Let's look at the content of this file for our structural analysis example:
+
+```python
+import KratosMultiphysics
+from KratosMultiphysics.StructuralMechanicsApplication.structural_mechanics_analysis import StructuralMechanicsAnalysis
+
+if __name__ == "__main__":
+
+    with open("ProjectParameters.json", 'r') as parameter_file:
+        parameters = KratosMultiphysics.Parameters(parameter_file.read())
+
+    model = KratosMultiphysics.Model()
+    simulation = StructuralMechanicsAnalysis(model, parameters)
+    simulation.Run()
+```
+
+In the first lines, Kratos and the structural analysis are imported. Then the settings are read from the `.json` file and used to create an object of the structural analysis. In the last line, the structural simulation executed. 
+
+### Run Kratos from the command line
+Use the Kratos command prompt from your Kratos installation, navigate to the folder where your script is located and execute:
+```
+kratos MainKratos.py
+```
+_Pro Tip: If you built Kratos yourself and set the paths properly as explained in the **Building Kratos** section of the Wiki, you can directly use python to execute your script._
+
+The output of this analysis is written in two formats. The GiD post file ends with `.post.bin` and can be drag and droppen into GiD. Additionally VTK files are written to the VTK_Output folder. 
+
+### Exercise
+In order to show that the python script for Kratos indeed is just a simple python script, create a file named e.g. `my_python_script.py`. Import the Kratos core module and additionaly write some simple python commands.
+
+```python
+import math
+import KratosMultiphysics
+
+a = 3
+b = 4
+c = math.sqrt(3**2 + 4**2)
+print("-- Custom Code: c=", c, " --")
+```
+
+If you execute this script as described above you should see the following output in the terminal:
+```
+ |  /           |
+ ' /   __| _` | __|  _ \   __|
+ . \  |   (   | |   (   |\__ \
+_|\_\_|  \__,_|\__|\___/ ____/
+           Multi-Physics 7.0.0
+-- Custom Code: c= 5.0  --
+KRATOS TERMINATED CORRECTLY
+```
+The python script is a powerful tool to customize a Kratos simulation, as you will see in the next tutorials.
+
+
+## The project parameters file
+The settings for a Kratos simulation are stored in a `.json` file. JSON is an open-standard format that uses human-readable text to transmit data objects consisting of attribute–value pairs. Kratos uses a thin wrapper arround this syntax, the `Parameters` object. This section is a short version of a more detailed [description about the JSON syntax](How-to-write-a-JSON-configuration-file) and a [tutorial on how to read and use it](https://github.com/KratosMultiphysics/Kratos/wiki/Python-Script-Tutorial:-Reading-ProjectParameters).
+
+### ProjectParameters.json
+The project parameters file for Kratos is commonly named `ProjectParameters.json`. Let's look at the content of this file for our structural analysis example. It contains four main blocks:
+* `problem_data`: General settings for the Kratos run
+* `solver_settings`: Settings for the solvers, like analysis type, linear solver, etc.
+* `processes`: Processes to e.g. apply boundary conditions.  
+* `output_processes`: Settings for the output
+
+Try to change the end time of the structural case from to `5.0` seconds and run the analysis again.
+
+### Read the parameters from the .json file
+Extend your custom python script by parsing the `.json` file into a `Parameters` object:
+```python
+with open("ProjectParameters.json",'r') as parameter_file:
+    parameters = KratosMultiphysics.Parameters(parameter_file.read())
+```
+Extracting fields from the `Parameters` object works similar to a python dictionary. To get and set the value of a field, you have to use specific functions for the data type. In order to get the file name (a string) of the `.mdpa` file you need to type:
+
+```python
+model_part_file_name = parameters["solver_settings"]["model_import_settings"]["input_filename"].GetString()
+```
+
+## The Model part file
+The `.mdpa`(**M**o**d**el**Pa**rt) file contains the model information in Kratos specific syntax. It contains blocks for properties, nodes, elements and conditions and initial values. In addition the mesh entities can be grouped into sub model parts. A detailed description of the syntax is given [here](Input-data).
+
+### Read a .mdpa file
+The following exercise is a short version of a more detailed [tutorial](Python-Script-Tutorial:-Reading-ModelPart-From-Input-File).
+
+A `ModelPart` has to be created via a `Model` object, which can contain several `ModelParts`. Right after creating the empty `ModelPart`, the variables needed for the following calculations have to be added. The empty `ModelPart` is then filled using the `ModelPartIO` that reads the information from an .mdpa file. In general, the analysis object takes care of these steps, especially because it knows which variables to add.
+
+Here you will do it directly in your python script. 
+If the .mdpa file contains application dependent elements, the corresponding Kratos application has to be imported. In our structural example, the elements are from the `StructuralMechanicsApplication`. 
+
+Extend the small python script from the first part of the exercise with the following lines:
+
+```python
+import KratosMultiphysics.StructuralMechanicsApplication
+
+this_model = KratosMultiphysics.Model()
+this_model_part = this_model.CreateModelPart("MyModelPart")
+
+# Adding variables BEFORE reading the .mdpa
+this_model_part.AddNodalSolutionStepVariable(KratosMultiphysics.DISPLACEMENT)
+
+model_part_io = KratosMultiphysics.ModelPartIO("KratosWorkshop2019_high_rise_building_CSM") #path to file without ".mdpa"
+model_part_io.ReadModelPart(this_model_part)
+```
+You could also use the filename that you extracted from the ProjectParameters.json previously.
+
+_Hint: You can_ ```>>> print(this_model_part)``` _to see its content._ 
+
+## Output
+An extensive example on writing GiD output can be found [here](Python-Script-Tutorial:-Writing-Output-File). In this part of the tutorial you will create a minimal configuration of a VTK output process. 
+
+The `vtk_output` block in the ProjectParameters.json gives you an impression on the potential settings for the output. Here you will create just a minimal version of it.
+```python
+from vtk_output_process import VtkOutputProcess
+vtk_output_configuration = KratosMultiphysics.Parameters("""{
+        "model_part_name"        : \""""+this_model_part.Name+"""\",
+        "output_sub_model_parts" : false,
+        "nodal_solution_step_data_variables" : ["DISPLACEMENT"]
+    }""")
+
+vtk_output = VtkOutputProcess(this_model, vtk_output_configuration)
+```
+
+The output process is usually called at defined places inside the analysis. In order to use it, several functions need to be called in the right order.
+
+```python
+vtk_output.ExecuteInitialize()
+vtk_output.ExecuteBeforeSolutionLoop()
+vtk_output.ExecuteInitializeSolutionStep()
+vtk_output.PrintOutput()
+vtk_output.ExecuteFinalizeSolutionStep()
+vtk_output.ExecuteFinalize()
+```