Extend FEM Module: Difference between revisions

From FreeCAD Documentation
(Added some explanation and highlighted some parts in the text.)
No edit summary
(22 intermediate revisions by 5 users not shown)
Line 1: Line 1:
<languages/>
<languages/>
<translate>
<translate>

<!--T:1-->
<!--T:1-->
{{TutorialInfo
{{TutorialInfo
|Topic=
|Topic=FEM
|Level=
|Level=Intermediate
|Time=
|Time=1 hour
|Author=[[User:M42kus|M42kus]]
|Author=[[User:M42kus|M42kus]]
|FCVersion=
|FCVersion=0.17
|Files=
}}
}}


Line 29: Line 29:


<!--T:6-->
<!--T:6-->
The build system must be modified regardless of which objects shall be added o the FEM workbench. Every python module (file) must be registered. The FEM workbench even requires every new python module to be registered twice. Once in {{incode|Mod/Fem/CMakeLists.txt}} and a second time in {{incode|Mod/Fem/App/CMakeLists.txt}}. This is true regardless of the type of the python module (GUI or non-GUI). Where exactly the module must be inserted depends on the role of the module. Solver, equations and constraints all use different lists. Searching for similar files and inserting the new file in the same list works most of the time.
The build system must be modified regardless of which objects shall be added o the FEM workbench. Every python module (file) must be registered. The FEM workbench requires every new python module to be registered in {{incode|Mod/Fem/CMakeLists.txt}}. This is true regardless of the type of the python module (GUI or non-GUI). Where exactly the module must be inserted depends on the role of the module. Solver, equations and constraints all use different lists. Searching for similar files and inserting the new file in the same list works most of the time.


<!--T:7-->
<!--T:7-->
As an '''example''' lets add a new constraint called ''''pressure''' which is related to the '''flow equation'''. So, '''FlowPressure''' will widely used as <name> for this constraint. A new constraint requires at least the following new modules:
As an '''example''' lets add a new constraint called {{incode|pressure}} which is related to the '''flow equation'''. So, '''FlowPressure''' will widely used as <name> for this constraint. A new constraint requires at least the following new modules:
* {{incode|FemConstraint<name>.py}},
* {{incode|constraint_<name>.py}}
* {{incode|ViewProviderFemConstraint<name>.py}} and
* {{incode|view_constraint_<name>.py}}
* {{incode|CommandFemConstraint<name>.py}}.
* {{incode|CommandFemConstraint<name>.py}} (may be unnecessary)
These three files must be added to {{incode|Mod/Fem/CMakeLists.txt}} as well as {{incode|Mod/Fem/App/CMakeLists.txt}}. All inserted lines of code are indicated by a starting '''+'''.
These three files must be added to {{incode|Mod/Fem/CMakeLists.txt}} as well as {{incode|Mod/Fem/App/CMakeLists.txt}}. All inserted lines of code are indicated by a starting '''+'''.


</translate>
</translate>
'''Mod/Fem/CMakeLists.txt'''
{{FileName|Mod/Fem/CMakeLists.txt}}


{{code|code=
<pre>INSTALL(
SET(FemObjects_SRCS
FILES
PyObjects/__init__.py
femobjects/__init__.py
femobjects/base_fempythonobject.py
PyObjects/_FemConstraintSelfWeight.py
femobjects/constraint_bodyheatsource.py
PyObjects/_FemConstraintBodyHeatFlux.py
femobjects/constraint_electrostaticpotential.py
PyObjects/_FemConstraintFlowVelocity.py
femobjects/constraint_flowvelocity.py
+ PyObjects/_FemConstraintFlowPressure.py
femobjects/constraint_initialflowvelocity.py
PyObjects/_FemElementFluid1D.py
+ femobjects/constraint_initialflowpressure.py
PyObjects/_FemElementGeometry1D.py
femobjects/constraint_selfweight.py
PyObjects/_FemElementGeometry2D.py
...
...
femobjects/solver_ccxtools.py
DESTINATION
Mod/Fem/PyObjects
)
)
...

SET(FemGuiViewProvider_SRCS
INSTALL(
femviewprovider/__init__.py
FILES
femviewprovider/view_base_femconstraint.py
PyGui/FemCommands.py
femviewprovider/view_base_femobject.py
PyGui/__init__.py
femviewprovider/view_constraint_bodyheatsource.py
PyGui/_CommandFemSolverElmer.py
femviewprovider/view_constraint_electrostaticpotential.py
PyGui/_CommandFemEquation.py
femviewprovider/view_constraint_flowvelocity.py
PyGui/_CommandFemConstraintBodyHeatFlux.py
+ femviewprovider/view_constraint_flowpressure.py
PyGui/_CommandFemConstraintFlowVelocity.py
femviewprovider/view_constraint_initialflowvelocity.py
+ PyGui/_CommandFemConstraintFlowPressure.py
femviewprovider/view_constraint_selfweight.py
PyGui/_CommandFemAnalysis.py
...
PyGui/_CommandFemElementFluid1D.py
femviewprovider/view_solver_ccxtools.py
PyGui/_CommandFemElementGeometry1D.py
...
PyGui/_ViewProviderFemConstraintSelfWeight.py
PyGui/_ViewProviderFemConstraintBodyHeatFlux.py
PyGui/_ViewProviderFemConstraintFlowVelocity.py
+ PyGui/_ViewProviderFemConstraintFlowPressure.py
PyGui/_ViewProviderFemElementFluid1D.py
PyGui/_ViewProviderFemElementGeometry1D.py
PyGui/_ViewProviderFemElementGeometry2D.py
...
DESTINATION
Mod/Fem/PyGui
)</pre>
'''Mod/Fem/App/CMakeLists.txt'''

<pre>SET(FemObjectsScripts_SRCS
PyObjects/__init__.py
PyObjects/_FemConstraintSelfWeight.py
PyObjects/_FemConstraintBodyHeatFlux.py
PyObjects/_FemConstraintFlowVelocity.py
+ PyObjects/_FemConstraintFlowPressure.py
PyObjects/_FemElementFluid1D.py
PyObjects/_FemElementGeometry1D.py
PyObjects/_FemElementGeometry2D.py
PyObjects/_FemMaterialMechanicalNonlinear.py
PyObjects/_FemMeshBoundaryLayer.py
PyObjects/_FemMeshGmsh.py
PyObjects/_FemMeshGroup.py
PyObjects/_FemMeshResult.py
PyObjects/_FemMeshRegion.py
PyObjects/_FemResultMechanical.py
PyObjects/_FemSolverCalculix.py
PyObjects/_FemMaterial.py
)
)
}}

SET(FemGuiScripts_SRCS
PyGui/FemCommands.py
PyGui/__init__.py
PyGui/_CommandFemAnalysis.py
PyGui/_CommandFemConstraintSelfWeight.py
PyGui/_CommandFemConstraintBodyHeatFlux.py
PyGui/_CommandFemConstraintFlowVelocity.py
+ PyGui/_CommandFemConstraintFlowPressure.py
PyGui/_CommandFemElementFluid1D.py
PyGui/_CommandFemElementGeometry1D.py
...
PyGui/_ViewProviderFemConstraintBodyHeatFlux.py
PyGui/_ViewProviderFemConstraintFlowVelocity.py
+ PyGui/_ViewProviderFemConstraintFlowPressure.py
PyGui/_ViewProviderFemElementFluid1D.py
PyGui/_ViewProviderFemElementGeometry1D.py
PyGui/_ViewProviderFemElementGeometry2D.py
...
)</pre>

<translate>
<translate>


Line 127: Line 74:


<!--T:9-->
<!--T:9-->
For organizing the python code the FEM module uses a similar approach to that used for the C++ code throughout FreeCAD. The module is split into two packages. PyObjects, which contains all non-gui like python proxies for document objects and PyGui containing everything gui related like python proxies for view provider, task panels, .ui files and commands.
For organizing the python code the FEM module uses the following approach. The module is split into the following packages:
* {{incode|femobjects}}, which contains all non-GUI like python proxies for document objects and
* {{incode|femviewproviders}} containing everything GUI related like python proxies for view provider
* C++ based task panels are stored in '{{incode|Gui}}',
* icons can be found in '{{incode|Gui/Resources/icons/}}',
* .ui files are stored in '{{incode|Gui/Resources/ui/}}' commands.


<!--T:10-->
<!--T:10-->
One package doesn't follow this pattern: FemSolver. It has its place on the same level as PyObjects and PyGui (src/Mod/Fem/FemSolver). The package contains solver and equation related packages and modules and it is organized the following way:
One package doesn't follow this pattern: {{incode|femsolver}}. It has its place on the same level as {{incode|femobjects}} and {{incode|femguiobjects}} ({{incode|src/Mod/Fem/femsolver}}). The package contains solver and equation related packages and modules and it is organized the following way:
</translate>
<pre>.FemSolver
.FemSolver.Elmer
.FemSolver.Elmer.Equations
.FemSolver.Calculix
.FemSolver.Calculix.Equations
.FemSolver.Z88
.FemSolver.Z88.Equations</pre>


</translate>
<pre>
.femsolver
.femsolver.elmer
.femsolver.elmer.equations
.femsolver.calculix
.femsolver.calculix.equations
.femsolver.z88
.femsolver.z88.equations
</pre>
<translate>
<translate>

== Solver == <!--T:11-->
== Solver == <!--T:11-->


<!--T:12-->
<!--T:12-->
In FreeCAD a solver can be split into two parts:
In FreeCAD a solver can be split into two parts. One is the document object used by the user to interact with the solver. Though it solver parameter can be set and it is also used to control the solving process. The other one are the so called tasks of a solver. The solving process is split into those tasks, namely: check, prepare, solve and results. Those do the actual work of exporting the analysis into a format understood by the solver executable, starting the executable and loading the results back into FreeCAD.
* One is the document object used by the user to interact with the solver. Though it solver parameter can be set and it is also used to control the solving process.
* The other one are the so called tasks of a solver. The solving process is split into those tasks, namely: ''check, prepare, solve and results''. Those do the actual work of exporting the analysis into a format understood by the solver executable, starting the executable and loading the results back into FreeCAD.


<!--T:13-->
<!--T:13-->
Most files related to a solver reside in a sub-package of the FemSolver package (e.g. FemSolver.Elmer). The following list enumerates all files related to the implementation of a solver. Those are the files that need to be copied and modified to add support for a new solver to FreeCAD.
Most files related to a solver reside in a sub-package of the {{incode|femsolver}} package (e.g. for Elmer its in {{incode|femsolver/elmer}}). The following list enumerates all files related to the implementation of a solver. Those are the files that need to be copied and modified to add support for a new solver to FreeCAD. The given example is taken from the solver implementation of Elmer.


<!--T:14-->
<!--T:14-->
* '''FemSolver/Elmer/Object.py:''' Document object visible in the tree-view. Implemented in python via a document proxy and view proxy.
* '''femsolver/elmer/solver.py:''' Document object visible in the tree-view. Implemented in python via a document proxy and view proxy.
* '''FemSolver/Elmer/Tasks.py:''' Module containing one task class per task required for a solver implementation. Those tasks divide the process of solving a analysis into the following steps: check, prepare, solve, results.
* '''femsolver/elmer/tasks.py:''' Module containing one task class per task required for a solver implementation. Those tasks divide the process of solving a analysis into the following steps: check, prepare, solve, results.
* '''PyGui/_CommandFemElmer.py:''' Adds the solver document object to the active document. Required to access the solver object from the GUI.
* '''femcommands/commands.py:''' Adds the solver document object to the active document. Required to access the solver object from the GUI.

<!--T:25-->
There is a tutorial of adding a new solver: [[Sandbox:Add_FEM_Solver_Tutorial|Add FEM Solver Tutorial]]


== Equations == <!--T:15-->
== Equations == <!--T:15-->


<!--T:16-->
<!--T:16-->
An equation represents a particular physics that shall be considered when solving the analysis (e.g. Flow, Heat). Not all solver in FreeCAD support equations. Equations are represented by child objects of the corresponding solver object. In the tree-view this looks like this:
An equation represents a particular physics that shall be considered when solving the analysis (e.g. Flow, Heat). Not all solver in FreeCAD support (all) equations. Equations are represented by child objects of the corresponding solver object. In the tree-view this looks like this:


<!--T:17-->
<!--T:17-->
* elmer-solver
* ElmerSolver
** Elasticity
** elasticity
** Heat
** heat
** Flow
** flow
** electrostatics


<!--T:18-->
<!--T:18-->
Most solver specific options (max iterations, method of solving, etc) are set via the equation objects. One consequence of this is that each solver must have it's own implementation of &quot;the same&quot; equation. CalculiX would have a different Heat object that Elmer. To avoid having multiple buttons for the same physics in the GUI each solver object adds it's equations itself.
Most solver specific options (e.g. max. iterations, method of solving, etc) are set via the equation objects. One consequence of this is that each solver must have it's own implementation of &quot;the same&quot; equation. CalculiX would have a different Heat-object that Elmer. To avoid having multiple buttons for the same physics in the GUI each solver object adds it's equations itself.


<!--T:19-->
<!--T:19-->
The actual implementation can be split into the generic and the solver specific part. The generic part can be found in the FemSolver.EquationBase module. The solver specific part resides inside individual Equations sub-packages of the solver packages (e.g. FemSolver/Elmer/Equations).
The actual implementation can be split into the generic and the solver specific part. The generic part can be found in the {{incode|femsolver.equationbase}} module. The solver specific part resides inside individual Equations sub-packages of the solver packages (e.g. {{incode|femsolver/elmer/equations}}).


<!--T:20-->
<!--T:20-->
Line 181: Line 142:
<!--T:23-->
<!--T:23-->
Adding new constraints is quite straight forward. For newcomers there is a tutorial: [[Add_FEM_Constraint_Tutorial|Add FEM Constraint Tutorial]].
Adding new constraints is quite straight forward. For newcomers there is a tutorial: [[Add_FEM_Constraint_Tutorial|Add FEM Constraint Tutorial]].



</translate>
</translate>
[[Category:FEM{{#translation:}}]]
[[Category:FEM{{#translation:}}]]

{{clear}}

Revision as of 14:57, 3 November 2021

Tutorial
Topic
FEM
Level
Intermediate
Time to complete
1 hour
Authors
M42kus
FreeCAD version
0.17
Example files
None
See also
None

The FEM workbench already supports a lot of different constraints and a handful of solver. Despite that people often need constraints not jet supported by FreeCAD. This page is the starting point to a series of tutorials and other resources describing how to extend the FEM workbench using the existing framework. While this series can prove helpful to software developers too the idea is to allow FEM users with a bit of interest into python coding to add the stuff they need themselves.

Adding new constraints, equations or solver is mostly routine work. But doing it for the first time will not be as easy as it might seem. An understanding of the following topics will prove helpful:

Build System (cmake)

The build system must be modified regardless of which objects shall be added o the FEM workbench. Every python module (file) must be registered. The FEM workbench requires every new python module to be registered in Mod/Fem/CMakeLists.txt. This is true regardless of the type of the python module (GUI or non-GUI). Where exactly the module must be inserted depends on the role of the module. Solver, equations and constraints all use different lists. Searching for similar files and inserting the new file in the same list works most of the time.

As an example lets add a new constraint called pressure which is related to the flow equation. So, FlowPressure will widely used as <name> for this constraint. A new constraint requires at least the following new modules:

  • constraint_<name>.py
  • view_constraint_<name>.py
  • CommandFemConstraint<name>.py (may be unnecessary)

These three files must be added to Mod/Fem/CMakeLists.txt as well as Mod/Fem/App/CMakeLists.txt. All inserted lines of code are indicated by a starting +.

Mod/Fem/CMakeLists.txt

SET(FemObjects_SRCS
    femobjects/__init__.py
    femobjects/base_fempythonobject.py
    femobjects/constraint_bodyheatsource.py
    femobjects/constraint_electrostaticpotential.py
    femobjects/constraint_flowvelocity.py
    femobjects/constraint_initialflowvelocity.py
+   femobjects/constraint_initialflowpressure.py
    femobjects/constraint_selfweight.py
...
    femobjects/solver_ccxtools.py
)
...
SET(FemGuiViewProvider_SRCS
    femviewprovider/__init__.py
    femviewprovider/view_base_femconstraint.py
    femviewprovider/view_base_femobject.py
    femviewprovider/view_constraint_bodyheatsource.py
    femviewprovider/view_constraint_electrostaticpotential.py
    femviewprovider/view_constraint_flowvelocity.py
+   femviewprovider/view_constraint_flowpressure.py
    femviewprovider/view_constraint_initialflowvelocity.py
    femviewprovider/view_constraint_selfweight.py
...
    femviewprovider/view_solver_ccxtools.py
)

Source Organization

For organizing the python code the FEM module uses the following approach. The module is split into the following packages:

  • femobjects, which contains all non-GUI like python proxies for document objects and
  • femviewproviders containing everything GUI related like python proxies for view provider
  • C++ based task panels are stored in 'Gui',
  • icons can be found in 'Gui/Resources/icons/',
  • .ui files are stored in 'Gui/Resources/ui/' commands.

One package doesn't follow this pattern: femsolver. It has its place on the same level as femobjects and femguiobjects (src/Mod/Fem/femsolver). The package contains solver and equation related packages and modules and it is organized the following way:

.femsolver
.femsolver.elmer
.femsolver.elmer.equations
.femsolver.calculix
.femsolver.calculix.equations
.femsolver.z88
.femsolver.z88.equations

Solver

In FreeCAD a solver can be split into two parts:

  • One is the document object used by the user to interact with the solver. Though it solver parameter can be set and it is also used to control the solving process.
  • The other one are the so called tasks of a solver. The solving process is split into those tasks, namely: check, prepare, solve and results. Those do the actual work of exporting the analysis into a format understood by the solver executable, starting the executable and loading the results back into FreeCAD.

Most files related to a solver reside in a sub-package of the femsolver package (e.g. for Elmer its in femsolver/elmer). The following list enumerates all files related to the implementation of a solver. Those are the files that need to be copied and modified to add support for a new solver to FreeCAD. The given example is taken from the solver implementation of Elmer.

  • femsolver/elmer/solver.py: Document object visible in the tree-view. Implemented in python via a document proxy and view proxy.
  • femsolver/elmer/tasks.py: Module containing one task class per task required for a solver implementation. Those tasks divide the process of solving a analysis into the following steps: check, prepare, solve, results.
  • femcommands/commands.py: Adds the solver document object to the active document. Required to access the solver object from the GUI.

There is a tutorial of adding a new solver: Add FEM Solver Tutorial

Equations

An equation represents a particular physics that shall be considered when solving the analysis (e.g. Flow, Heat). Not all solver in FreeCAD support (all) equations. Equations are represented by child objects of the corresponding solver object. In the tree-view this looks like this:

  • elmer-solver
    • elasticity
    • heat
    • flow
    • electrostatics

Most solver specific options (e.g. max. iterations, method of solving, etc) are set via the equation objects. One consequence of this is that each solver must have it's own implementation of "the same" equation. CalculiX would have a different Heat-object that Elmer. To avoid having multiple buttons for the same physics in the GUI each solver object adds it's equations itself.

The actual implementation can be split into the generic and the solver specific part. The generic part can be found in the femsolver.equationbase module. The solver specific part resides inside individual Equations sub-packages of the solver packages (e.g. femsolver/elmer/equations).

Adding a new equations to Elmer should be very easy. For newcomers there exists a tutorial which shows how to add a new equation to Elmer by adding the existing elasticity solver to FreeCAD: Add FEM Equation Tutorial.

Constraints

Constraints define boundary conditions for the problem that shall be solved. In FreeCAD constraints aren't specific to a particular solver. A problem setup can be solved by all solver that support all conditions in the analysis.

Adding new constraints is quite straight forward. For newcomers there is a tutorial: Add FEM Constraint Tutorial.