[Docs] Optimization Application documentation

applications/OptimizationApplication/python_scripts/algorithms/algorithm.py

@@ -4,26 +4,64 @@
 from KratosMultiphysics.OptimizationApplication.utilities.helper_utilities import CallOnAll
 
 class Algorithm(ABC):
+    """Base class for algorithm.
+
+    Algorithm works purely in the control space. Hence, the ResponseRoutine which
+    the algorithm is associated with should convert all physical space gradients to
+    control space and control space designs to physical space designs.
+
+    The purpose of the algorithm is to solve a minimization problem. Hence, the used
+    ResponseRoutine should standardize the values and gradients it computes accordingly.
+
+    Algorithm should create one MasterControl from all the require controls, and share
+    it among all the ResponseRoutines.
+
+    Once it received the objective/constraint values and their gradients, the algorithm
+    will compute the new design and request new objective/constraints values and their
+    gradients until the specified convergence criteria is met.
+    """
     def __init__(self, optimization_problem: OptimizationProblem) -> None:
         self._optimization_problem = optimization_problem
 
     @abstractmethod
     def Initialize(self) -> None:
+        """Initializes the algorithm, ResponseRoutines and MasterControl.
+        """
         pass
 
     @abstractmethod
     def Check(self) -> None:
+        """Checks algorithm, ResponseRoutines and MasterControl.
+        """
         pass
 
     @abstractmethod
     def Finalize(self) -> None:
+        """Finalizes algorithm ResponseRoutines and MasterControl.
+        """
         pass
 
     @abstractmethod
     def Solve(self) -> bool:
+        """Solves the optimization problem.
+
+        This method will have a loop which iterates until the specified
+        convergence for the given optimization problem.
+
+        Returns:
+            bool: Convergence status. True for converged, False for non-converged.
+        """
         pass
 
     def GetProcessesOrder(self) -> 'list[str]':
+        """The order of execution of the process categories.
+
+        This defines the order of execution of the processes defined under "processes"
+        in either "kratos_process" or "optimization_data_processes".
+
+        Returns:
+            list[str]: List of strings for process categories.
+        """
         return ["auxiliary_processes", "output_processes"]
 
     def CallOnAllProcesses(self, process_types: 'list[str]', *args, **kwargs):

applications/OptimizationApplication/python_scripts/execution_policies/execution_policy.py

@@ -2,6 +2,13 @@
 import KratosMultiphysics as Kratos
 
 class ExecutionPolicy(ABC):
+    """Base class for execution policy
+
+    This represents the base class for the execution policy which
+    can be used to execute primal analysis to obtain response function
+    values and their gradients.
+
+    """
     def __init__(self, execution_policy_name: str) -> None:
         self.__name = execution_policy_name
 
@@ -22,8 +29,18 @@ def Finalize(self) -> None:
 
     @abstractmethod
     def GetAnalysisModelPart(self) -> Kratos.ModelPart:
+        """Returns the analysis model part.
+
+        Each execution policy will be using a domain to compute the primal model part.
+        This method should return that domain as a Kratos::ModelPart.
+
+        Returns:
+            Kratos.ModelPart: Domain used to compute the primal solution.
+        """
         pass
 
     @abstractmethod
     def Execute(self) -> None:
+        """Solves the associated primal problem.
+        """
         pass

docs/pages/Applications/Optimization_Application/Algorithms/Gradient_Projection.md

@@ -0,0 +1,7 @@
+---
+title: Gradient Projection
+keywords: 
+tags: [gradient_projection.md]
+sidebar: optimization_application
+summary: 
+---

docs/pages/Applications/Optimization_Application/Algorithms/Overview.md

@@ -0,0 +1,7 @@
+---
+title: Overview
+keywords: 
+tags: [Overview.md]
+sidebar: optimization_application
+summary: 
+---

docs/pages/Applications/Optimization_Application/Algorithms/Steepest_Descent.md

@@ -0,0 +1,7 @@
+---
+title: Steepest Descent
+keywords: 
+tags: [steepest_descent.md]
+sidebar: optimization_application
+summary: 
+---

docs/pages/Applications/Optimization_Application/Algorithms/menu_info.json

@@ -0,0 +1,5 @@
+{
+    "custom_entries": [
+        "Overview.md"
+    ]
+}

docs/pages/Applications/Optimization_Application/Controls/Overview.md

@@ -0,0 +1,7 @@
+---
+title: Overview
+keywords: 
+tags: [Overview.md]
+sidebar: optimization_application
+summary: 
+---

docs/pages/Applications/Optimization_Application/Controls/Shell_Thickness_Control.md

@@ -0,0 +1,7 @@
+---
+title: Shell Thickness Control
+keywords: 
+tags: [Shell_Thickness_Control.md]
+sidebar: optimization_application
+summary: 
+---

docs/pages/Applications/Optimization_Application/Controls/Vertex_Morphing_Shape_Control.md

@@ -0,0 +1,94 @@
+---
+title: Vertex Morphing Shape Control
+keywords: 
+tags: [Vertex_Morphing_Shape_Control.md]
+sidebar: optimization_application
+summary: 
+---
+
+## Introduction
+
+```VertexMorphingShapeControl``` is used to control the shape of a specified domain (given by a model part). This control can use either [Explicit Vertex Morphing](../Filtering/Explicit_Vertex_Morphing.html) or Implicit Vertex Morphing as the filtering method. Therefore, the physical space gradients will be transformed to smoothened vertex morphed control space gradients.
+
+This has an inbuilt mesh motion solver to solve for the mesh once the shape is changed. Therefore, it requires to have mesh motion settings as well.
+
+## Json settings
+
+### Explicit vertex morphing
+Following json snippet illustrates one use case of explicit vertex morphing
+```json
+{
+    "name": "explicit_shape_control",
+    "type": "shape.vertex_morphing_shape_control",
+    "module" : "KratosMultiphysics.OptimizationApplication.controls",
+    "settings":{
+        "controlled_model_part_names": [],
+        "filter_settings": {
+            "type" : "surface_explicit",
+            "filter_function_type" : "linear",
+            "damping_function_type" : "sigmoidal",
+            "radius": 0.000000000001,
+            "max_nodes_in_filter_radius": 1000
+        },
+        "mesh_motion_settings" : {},
+        "output_all_fields": false,
+        "fixed_model_parts": {},
+    }
+}
+```
+
+| Option | Allowed values |
+| ------------- | ------------- |
+| name | A unique string name |
+| type  | "shape.vertex_morphing_shape_control"  |
+| module  | "KratosMultiphysics.OptimizationApplication.model_part_controllers"  |
+| controlled_model_part_names | List of model part names of which the shape should be controlled. |
+| filter_settings::type | "surface_explicit" |
+| filter_settings::filter_function_type | Types of filter functions to be used. ["gaussian"](../Filtering/Explicit_Vertex_Morphing.html#gaussian-filter-function), ["linear"](../Filtering/Explicit_Vertex_Morphing.html#linear-filter-function), ["constant"](../Filtering/Explicit_Vertex_Morphing.html#constant-filter-function), ["cosine"](../Filtering/Explicit_Vertex_Morphing.html#cosine-filter-function), ["quartic"](../Filtering/Explicit_Vertex_Morphing.html#quartic-filter-function) are supported.|
+| filter_settings::damping_function_type | Type of the damping function to be used. ["gaussian"](../Filtering/Explicit_Vertex_Morphing.md#gaussian-filter-function-1), ["linear"](../Filtering/Explicit_Vertex_Morphing.md#linear-filter-function-1), ["constant"](../Filtering/Explicit_Vertex_Morphing.md#constant-filter-function-1), ["cosine"](../Filtering/Explicit_Vertex_Morphing.md#constant-filter-function-1), ["quartic"](../Filtering/Explicit_Vertex_Morphing.md#quartic-filter-function-1) "sigmoidal" are supported. |
+| filter_settings::radius| Filter radius |
+| filter_settings::max_nodes_in_filter_radius| Number of max nodes to be found in the filter radius. This specifies maximum number of neighbours will be searched for. If the radii is higher, or mesh is refined, then this number should be increased. |
+| mesh_motion_settings | Mesh motion solver settings |
+| output_all_fields | Output intermediate results also to the ```OptimizationProblem``` data container. |
+| fixed_model_parts | List of model part names to be dampened |
+
+### Implicit vertex morphing
+Following json snippet illustrates one use case of explicit vertex morphing
+```json
+{
+    "name": "implicit_shape_control",
+    "type": "shape.vertex_morphing_shape_control",
+    "module" : "KratosMultiphysics.OptimizationApplication.controls",
+    "settings":{
+        "controlled_model_part_names": [],
+            "filter_settings": {
+                "type" : "bulk_surface_implicit",
+                "radius": 0.000000000001,
+                "linear_solver_settings" : {}
+            },
+            "mesh_motion_settings" : {},
+            "output_all_fields": false,
+            "fixed_model_parts": {},
+    }
+}
+```
+
+| Option | Allowed values |
+| ------------- | ------------- |
+| name | A unique string name |
+| type  | "shape.vertex_morphing_shape_control"  |
+| module  | "KratosMultiphysics.OptimizationApplication.model_part_controllers"  |
+| controlled_model_part_names | List of model part names of which the shape should be controlled. |
+| filter_settings::type | "bulk_surface_implicit" |
+| filter_settings::radius| Filter radius |
+| filter_settings::linear_solver_settings | Linear solver to be used in the implicit vertex morphing solver |
+| mesh_motion_settings | Mesh motion solver settings |
+| output_all_fields | Output intermediate results also to the ```OptimizationProblem``` data container. |
+| fixed_model_parts | List of model part names to be dampened |
+
+## Source files
+* [Doxygen](TODO) TODO
+* [applications/OptimizationApplication/python_scripts/controls/shape/vertex_morphing_shape_control.py](https://github.com/KratosMultiphysics/Kratos/blob/master/applications/OptimizationApplication/python_scripts/controls/shape/vertex_morphing_shape_control.py)
+* [applications/OptimizationApplication/python_scripts/filtering/helmholtz_analysis.py](https://github.com/KratosMultiphysics/Kratos/blob/master/applications/OptimizationApplication/python_scripts/filtering/helmholtz_analysis.py)
+
+

docs/pages/Applications/Optimization_Application/Controls/menu_info.json

@@ -0,0 +1,5 @@
+{
+    "custom_entries": [
+        "Overview.md"
+    ]
+}

docs/pages/Applications/Optimization_Application/Execution_Policies/Independent_Analysis_Execution_Policy.md

@@ -0,0 +1,38 @@
+---
+title: Independent Analysis Execution Policy
+keywords: 
+tags: [independent, execution policy, optimization]
+sidebar: optimization_application
+summary: 
+---
+
+## Introduction
+
+```IndependentAnalysisExecutionPolicy``` is used to execute a primal analysis which needs to be independent from the model parts of the origin. But they both share the same ```Kratos::Model```.
+
+## Json settings
+Following json-snippet illustrates an example use case
+```json
+{
+    "type": "independent_analysis_execution_policy",
+    "module": "KratosMultiphysics.OptimizationApplication.execution_policies",
+    "settings": {
+        "analysis_module"         : "KratosMultiphysics",
+        "analysis_type"           : "",
+        "analysis_model_part_name": "",
+        "analysis_settings"       : {}
+    }
+}
+```
+
+| Option | Allowed values |
+| ------------- | ------------- |
+| type  | "independent_analysis_execution_policy"  |
+| module  | "KratosMultiphysics.OptimizationApplication.model_part_controllers" |
+| analysis_module | Where to find the module for `analysis_type`. |
+| analysis_type | Analysis type to used to solve the primal analysis. |
+| analysis_settings | Settings for the analysis |
+
+## Source files
+* [Doxygen](TODO) TODO
+* [applications/OptimizationApplication/python_scripts/execution_policies/independent_analysis_execution_policy.py](https://github.com/KratosMultiphysics/Kratos/blob/master/applications/OptimizationApplication/python_scripts/execution_policies/independent_analysis_execution_policy.py)

docs/pages/Applications/Optimization_Application/Execution_Policies/Kratos_Analysis_Execution_Policy.md

@@ -0,0 +1,55 @@
+---
+title: Kratos Analysis Execution Policy
+keywords: 
+tags: [kratos, execution policy, optimization]
+sidebar: optimization_application
+summary: 
+---
+
+## Introduction
+
+```KratosAnalysisExecutionPolicy``` is used to execute a primal analysis which may or not need to be independent from the model parts of the origin. But they both share the same ```Kratos::Model```.
+
+In this execution policy, when ```Execute``` method is called, following variables in the specified model parts are made to zero.
+* STEP
+* TIME
+* DELTA_TIME
+
+## Json settings
+Following json-snippet illustrates an example use case
+```json
+{
+    "type": "independent_analysis_execution_policy",
+    "module": "KratosMultiphysics.OptimizationApplication.execution_policies",
+    "settings": {
+        "model_part_names" : [],
+        "analysis_module"  : "KratosMultiphysics",
+        "analysis_type"    : "",
+        "analysis_settings": {},
+        "analysis_output_settings": {
+                    "nodal_solution_step_data_variables": [],
+                    "nodal_data_value_variables"        : [],
+                    "element_data_value_variables"      : [],
+                    "condition_data_value_variables"    : []
+        }
+    }
+}
+```
+
+| Option | Allowed values |
+| ------------- | ------------- |
+| type  | "independent_analysis_execution_policy"  |
+| module  | "KratosMultiphysics.OptimizationApplication.model_part_controllers" |
+| model_part_names | Model part names to be used for outputting data and resetting variables. |
+| analysis_module | Where to find the module for `analysis_type`. |
+| analysis_type | Analysis type to used to solve the primal analysis. |
+| analysis_settings | Settings for the analysis |
+| analysis_output_settings | Output settings for variables in the model parts listed in `model_part_names`. An [OptimizationProblemVtuOutputProcess](../Processes/Optimization_Problem_Vtu_Output_Process.html) needs to be used to write these fields to files. |
+| nodal_solution_step_data_variables | List of nodal solution step variable names |
+| nodal_data_value_variables | List of nodal non-historical variable names |
+| element_data_value_variables | Element data value variable names |
+| condition_data_value_variables | Condition data value variable names |
+
+## Source files
+* [Doxygen](TODO) TODO
+* [applications/OptimizationApplication/python_scripts/execution_policies/kratos_analysis_execution_policy.py](https://github.com/KratosMultiphysics/Kratos/blob/master/applications/OptimizationApplication/python_scripts/execution_policies/kratos_analysis_execution_policy.py)

docs/pages/Applications/Optimization_Application/Execution_Policies/Overview.md

@@ -0,0 +1,7 @@
+---
+title: Overview
+keywords: 
+tags: [Overview.md]
+sidebar: optimization_application
+summary: 
+---

docs/pages/Applications/Optimization_Application/Execution_Policies/Stepping_Analysis_Execution_Policy.md

@@ -0,0 +1,44 @@
+---
+title: Stepping Analysis Execution Policy
+keywords: 
+tags: [stepping kratos, execution policy, optimization]
+sidebar: optimization_application
+summary: 
+---
+
+## Introduction
+
+```SteppingAnalysisExecutionPolicy``` is used to execute a primal analysis which may or not need to be independent from the model parts of the origin. But they both share the same ```Kratos::Model```.
+
+In this execution policy, when ```Execute``` method is called, following variables in the specified model parts are made to zero before and thereafter, original values are restored after running the primal analysis.
+* STEP
+* TIME
+* DELTA_TIME
+
+## Json settings
+Following json-snippet illustrates an example use case
+```json
+{
+    "type": "independent_analysis_execution_policy",
+    "module": "KratosMultiphysics.OptimizationApplication.execution_policies",
+    "settings": {
+        "model_part_names" : [],
+        "analysis_module"  : "KratosMultiphysics",
+        "analysis_type"    : "",
+        "analysis_settings": {}
+    }
+}
+```
+
+| Option | Allowed values |
+| ------------- | ------------- |
+| type  | "independent_analysis_execution_policy"  |
+| module  | "KratosMultiphysics.OptimizationApplication.model_part_controllers" |
+| model_part_names | Model part names to be used for outputting data and resetting variables. |
+| analysis_module | Where to find the module for `analysis_type`. |
+| analysis_type | Analysis type to used to solve the primal analysis. |
+| analysis_settings | Settings for the analysis |
+
+## Source files
+* [Doxygen](TODO) TODO
+* [applications/OptimizationApplication/python_scripts/execution_policies/stepping_analysis_execution_policy.py](https://github.com/KratosMultiphysics/Kratos/blob/master/applications/OptimizationApplication/python_scripts/execution_policies/stepping_analysis_execution_policy.py)