Updating the Wiki-pages for FEM equations, solvers, BCs

[HoWil]

looks like:

Code: Select all

PyGui/_CommandFemEquation.py

now is

Code: Select all

femcommands/commands.py

[bernd]

I got access to the Wiki too specifically for this: too much is still ToDo in the wiki. But I'll need guidance. I'll write "as I go" and with some details but given my not too deep understanding of underlying structures in FreeCAD I'll necessarily make mistakes or be too vague. My objective will be to get the ball rolling on the documentation. If you give me your blessing I'll start pumping words. If you prefer a more structured approach don't hesitate to say so.

It would be really great if you would help in documentation. Just go ahead. Just ask here if you have any questions. If you would like to make new pages might be best to disscuss it here first. Furthermore it would be good if you post here if you made bigger changes. If you have questions not related to FEM ask in the wiki forum.

[bernd]

looks like:

Code: Select all

PyGui/_CommandFemEquation.py

now is

Code: Select all

femcommands/commands.py

yes, all command modules where moved in one module commands.py

https://github.com/FreeCAD/FreeCAD/comm ... e515a7L208

[HoWil]

I first make a backup here. I know that there is a history in the wiki but I want it so .

Code: Select all

<languages/>
<translate>
<!--T:1-->
{{TutorialInfo
|Topic= 
|Level= 
|Time= 
|Author=[[User:M42kus|M42kus]]
|FCVersion=
|Files=
}}

<!--T:2-->
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.

<!--T:3-->
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:

<!--T:4-->
* Python scripting in FreeCAD.
** [[Python_scripting_tutorial|FreeCAD Scripting Tutorial]]
** [[FreeCAD_Scripting_Basics|FreeCAD Scripting Basics]]
* Extending FreeCAD with Python.
** [[Scripted_objects|Scripted Objects]]
* A solid understanding of the solver for which new objects shall be added (e.g. CalculiX or Elmer) is important.
* A little knowledge about build systems, especially cmake (build system used by FreeCAD).

== Build System (cmake) == <!--T:5-->

<!--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 Mod/Fem/CMakeLists.txt and a second time in 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.

<!--T:7-->
As an example lets add a new constraint pressure. A new constraint requires at least the following new modules: FemConstraint<name>.py, ViewProviderFemConstraint<name>.py, CommandFemConstraint<name>.py. These three files must be added to CMakeLists.txt as well as App/CMakeLists.txt.

</translate>
'''Mod/Fem/CMakeLists.txt'''

<pre>INSTALL(
    FILES
        PyObjects/__init__.py
        PyObjects/_FemConstraintSelfWeight.py
        PyObjects/_FemConstraintBodyHeatFlux.py
        PyObjects/_FemConstraintFlowVelocity.py
+       PyObjects/_FemConstraintFlowPressure.py
        PyObjects/_FemElementFluid1D.py
        PyObjects/_FemElementGeometry1D.py
        PyObjects/_FemElementGeometry2D.py
        ...
    DESTINATION
        Mod/Fem/PyObjects
)

INSTALL(
    FILES
        PyGui/FemCommands.py
        PyGui/__init__.py
        PyGui/_CommandFemSolverElmer.py
        PyGui/_CommandFemEquation.py
        PyGui/_CommandFemConstraintBodyHeatFlux.py
        PyGui/_CommandFemConstraintFlowVelocity.py
+       PyGui/_CommandFemConstraintFlowPressure.py
        PyGui/_CommandFemAnalysis.py
        PyGui/_CommandFemElementFluid1D.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>
== Source Organization == <!--T:8-->

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

<!--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:
</translate>
<pre>.FemSolver
.FemSolver.Elmer
.FemSolver.Elmer.Equations
.FemSolver.Calculix
.FemSolver.Calculix.Equations
.FemSolver.Z88
.FemSolver.Z88.Equations</pre>

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

<!--T:12-->
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.

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

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

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

<!--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:

<!--T:17-->
* ElmerSolver
** Elasticity
** Heat
** Flow

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

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

<!--T:20-->
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|Add FEM Equation Tutorial]].

== Constraints == <!--T:21-->

<!--T:22-->
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.

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

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

{{clear}}

[HoWil]

Am I right, that there are no more changes needed in 'Mod/Fem/App/CMakeLists.txt'
as described in 'Build System (cmake)' on https://wiki.freecadweb.org/Extend_FEM_Module

Looks like in 'Mod/Fem/App/CMakeLists.txt' (https://github.com/FreeCAD/FreeCAD/blob ... eLists.txt) are no more python files listed; there are only .cpp and .h files listed.

[HoWil]

Code: Select all

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:
</translate>
<pre>.FemSolver
.FemSolver.Elmer
.FemSolver.Elmer.Equations
.FemSolver.Calculix
.FemSolver.Calculix.Equations
.FemSolver.Z88
.FemSolver.Z88.Equations</pre>

EDIT: Please double check:
PyObjects is now femobjects
PyGui is now femviewprovider
FemSolver is now femsolver
all solvers like Elmer, Calculix and Z88 as well as the folder Equations are written now lowercase: elmer, calculix and z88; equations

[HoWil]

On https://wiki.freecadweb.org/Add_FEM_Equation_Tutorial the following paragraph needs some corrections ...

Code: Select all

The command should be added to the _CommandFemEquation module. Just copy an existing command and adjust the icon, menu text and tool-tip in GetResources(self) and the specifier in getSpecifier(self). We will need the specifier again later in the tutorial. Don't forget to register the command at the bottom of the module file by using the addCommand(...) method.

class Flow(_Base):

    def getSpecifier(self):
        return "Flow"

    def GetResources(self):
        return {
            'Pixmap': 'fem-equation-flow',
            'MenuText': "Flow Equation",
            'ToolTip': "Add flow equation to selected solver."
        }

Gui.addCommand('FEM_AddEquationFlow', Flow())

is this now done by

Code: Select all

class _EquationFlow(CommandManager):
    "The FEM_EquationFlow command definition"

    def __init__(self):
        super(_EquationFlow, self).__init__()
        self.menuetext = "Flow equation"
        self.tooltip = "Creates a FEM equation for flow"
        self.is_active = "with_solver_elmer"
        self.do_activated = "add_obj_on_gui_selobj_noset_edit"

and EDIT replace the wrong section of ConstraintFlowVelocity with FEM_EquationFlow

Code: Select all

FreeCADGui.addCommand(
    "FEM_EquationFlow",
    _EquationFlow()
)

[bernd]

Am I right, that there are no more changes needed in 'Mod/Fem/App/CMakeLists.txt'
as described in 'Build System (cmake)' on https://wiki.freecadweb.org/Extend_FEM_Module

Looks like in 'Mod/Fem/App/CMakeLists.txt' (https://github.com/FreeCAD/FreeCAD/blob ... eLists.txt) are no more python files listed; there are only .cpp and .h files listed.

yes all Python modules where removed from there

[bernd]

On https://wiki.freecadweb.org/Add_FEM_Equation_Tutorial the following paragraph needs some corrections ...
is this now done by

Code: Select all

class _EquationFlow(CommandManager):
    "The FEM_EquationFlow command definition"

    def __init__(self):
        super(_EquationFlow, self).__init__()
        self.menuetext = "Flow equation"
        self.tooltip = "Creates a FEM equation for flow"
        self.is_active = "with_solver_elmer"
        self.do_activated = "add_obj_on_gui_selobj_noset_edit"

it depends ... if the icon in FreeCAD Gui is clicked in FreeCAD this happens: add_obj_on_gui_selobj_noset_edit from manager.py this is fine for a new equation, but may or may not for a new constraint. https://github.com/FreeCAD/FreeCAD/blob ... #L355-L369

But mainly you are right.

[johnwang]

On https://wiki.freecadweb.org/Add_FEM_Equation_Tutorial the following paragraph needs some corrections ...

Code: Select all

The command should be added to the _CommandFemEquation module. Just copy an existing command and adjust the icon, menu text and tool-tip in GetResources(self) and the specifier in getSpecifier(self). We will need the specifier again later in the tutorial. Don't forget to register the command at the bottom of the module file by using the addCommand(...) method.

class Flow(_Base):

    def getSpecifier(self):
        return "Flow"

    def GetResources(self):
        return {
            'Pixmap': 'fem-equation-flow',
            'MenuText': "Flow Equation",
            'ToolTip': "Add flow equation to selected solver."
        }

Gui.addCommand('FEM_AddEquationFlow', Flow())

is this now done by

Code: Select all

class _EquationFlow(CommandManager):
    "The FEM_EquationFlow command definition"

    def __init__(self):
        super(_EquationFlow, self).__init__()
        self.menuetext = "Flow equation"
        self.tooltip = "Creates a FEM equation for flow"
        self.is_active = "with_solver_elmer"
        self.do_activated = "add_obj_on_gui_selobj_noset_edit"

and

Code: Select all

FreeCADGui.addCommand(
    "FEM_ConstraintFlowVelocity",
    _ConstraintFlowVelocity()
)

Where the icon is specified in the new way?