Add Sphinx setup #24

.gitignore

@@ -13,4 +13,5 @@ examples/3D_Electrostatic_Capacitance/LaTeX_Source/main.run.xml
 examples/3D_Electrostatic_Capacitance/LaTeX_Source/main.synctex.gz
 *.toc
 *.bbl
-.coverage
+.coverage
+doc/_build

doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/conf.py

@@ -0,0 +1,66 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../"))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "pyelmer"
+copyright = "2023, pyelmer developers"
+author = "pyelmer developers"
+
+# The full version, including alpha/beta/rc tags
+import pyelmer
+
+version = pyelmer.__version__
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon"]
+# Napoleon settings
+napoleon_google_docstring = True
+napoleon_include_init_with_doc = True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+try:
+    import sphinx_rtd_theme
+
+    html_theme = "sphinx_rtd_theme"
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+except ImportError:
+    html_theme = "alabaster"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]

doc/elmer.rst

@@ -0,0 +1,10 @@
+elmer module
+============
+
+This module is the heart of pyelmer. It implements the objects used to
+construct the sif-file.
+
+.. automodule:: pyelmer.elmer
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/elmerkw.rst

@@ -0,0 +1,10 @@
+elmerkw module
+==============
+
+This module is an extension of the elmer module. It provides some
+keywords ready-to-use. Unfortunately, it is far from being complete.
+
+.. automodule:: pyelmer.elmerkw
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/execute.rst

@@ -0,0 +1,10 @@
+execute module
+==============
+
+This module provides function for execution of ElmerGrid, ElmerSolver
+and compilation own elmer f90 modules.
+
+.. automodule:: pyelmer.execute
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/index.rst

@@ -0,0 +1,15 @@
+Welcome to pyelmers's documentation!
+====================================
+
+An introduction on how to use pyelmer can be found on the GitHub page
+https://github.com/nemocrys/pyelmer#pyelmer. This documentation
+gives a detailed overview of pyelmer's different modules.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   elmer
+   elmerkw
+   execute
+   post

doc/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

doc/post.rst

@@ -0,0 +1,8 @@
+post module
+===========
+
+This module provides some utility functions for postprocessing.
+
+.. automodule:: pyelmer.post
+   :members:
+

doc/requirements.txt

@@ -0,0 +1,6 @@
+gmsh
+pyyaml
+matplotlib
+numpy
+objectgmsh
+pandas

pyelmer/elmer.py

@@ -164,10 +164,10 @@ def __init__(self, simulation, name, body_ids=None, data=None):
         else:
             self.data = data
         # optional parameters
-        self.equation = None
-        self.initial_condition = None
-        self.material = None
-        self.body_force = None
+        self.equation = None  #: optional reference to an Equation object
+        self.initial_condition = None  #: optional reference to an InitialCondition object 
+        self.material = None  #: optional reference to a Material object
+        self.body_force = None  #: optional reference to a BodyForce object
 
     def get_data(self):
         """Generate dictionary with data for sif-file."""

pyelmer/elmerkw.py

@@ -33,24 +33,24 @@ def __init__(self, simulation, name, geo_ids=None):
             surf_ids (list of int): Ids of boundaries in mesh.
         """
         super().__init__(simulation, name, geo_ids)
-        self.radiation = False
-        self.radiation_idealized = False
-        self.fixed_temperature = None
-        self.fixed_heatflux = None
-        self.zero_potential = False
-        self.save_scalars = False
-        self.save_line = False
-        self.smart_heater = False
-        self.smart_heater_T = 0
-        self.phase_change_steady = False
-        self.phase_change_transient = False
-        self.phase_change_vel = 0
-        self.material = None
-        self.normal_target_body = None
-        self.phase_change_body = None
-        self.heat_transfer_coefficient = 0
-        self.T_ext = 0
-        self.mesh_update = []
+        self.radiation = False  #: surface to surface radiation, defaults to False
+        self.radiation_idealized = False  #: idealized radiation (to ambient), defaults to False
+        self.fixed_temperature = None  #: fixed temperature, defaults to None
+        self.fixed_heatflux = None  #: fixed heat flux, defaults to None
+        self.zero_potential = False  #: zero potential, defaults to False
+        self.save_scalars = False    #: add save scalars flag, defaults to False
+        self.save_line = False    #: add save line flag, defaults to False
+        self.smart_heater = False  #: add smart heater flag, defaults to False
+        self.smart_heater_T = 0  #: smart heater temperature, defaults to 0
+        self.phase_change_steady = False  #: set steady phase change parameters, defaults to False
+        self.phase_change_transient = False  #: set transient phase change parameters, defaults to False
+        self.phase_change_vel = 0  #: phase change velocity, defaults to 0
+        self.material = None  #: reference to material object, defaults to None
+        self.normal_target_body = None  #: reference to normal target body, defaults to None
+        self.phase_change_body = None  #: reference to phase change body, defaults to None
+        self.heat_transfer_coefficient = 0  #: heat transfer coefficient, defaults to 0
+        self.T_ext = 0  #: external temperature, defaults to 0
+        self.mesh_update = []  #: mesh update velocity, defaults to []
 
     def get_data(self):
         """Generate dictionary with data for sif-file."""
@@ -138,13 +138,13 @@ def __init__(self, simulation, name, data=None):
             data (dict): Body force data as in sif-file.
         """
         super().__init__(simulation, name, data)
-        self.joule_heat = False
-        self.current_density = 0
-        self.heat_source = 0
-        self.integral_heat_source = 0
-        self.smart_heat_control = False
-        self.smart_heater_control_point = []
-        self.smart_heater_T = 0
+        self.joule_heat = False  #: joule heating activated, defaults to False
+        self.current_density = 0  #: fixed current density, defaults to 0
+        self.heat_source = 0  #: fixed heat source, defaults to 0
+        self.integral_heat_source = 0  #: fixed integral heat source, defaults to 0
+        self.smart_heat_control = False  #: smart heat control, defaults to False
+        self.smart_heater_control_point = [] #: control point for smart heater, defaults to []
+        self.smart_heater_T = 0  #: smart heater temperature, defaults to 0
 
     def get_data(self):
         d = super().get_data()

pyelmer/execute.py

@@ -13,7 +13,7 @@ def run_elmer_grid(sim_dir, meshfile, elmergrid=None):
     Args:
         sim_dir (str): Simulation directory
         meshfile (str): Filename of .msh file
-        elmergrid (str): ElmerGrid executable
+        elmergrid (str, optional): ElmerGrid executable
     """
     if elmergrid is None:
         # On Windows ElmerGrid.exe is not found once gmsh.initialize() was executed.
@@ -44,7 +44,7 @@ def run_elmerf90(userfile_in, userfile_out, elmerf90=None):
     Args:
         userfile_in (str) : Filename of .F90 file
         userfile_out (str) : Filename of .so file
-        elmerf90 (str): elmerf90 executable
+        elmerf90 (str, optional): elmerf90 executable
     """
     if elmerf90 is None:
         # On Windows ElmerSolver.exe is not found once gmsh.initialize() was executed.
@@ -61,7 +61,7 @@ def run_elmer_solver(sim_dir, elmersolver=None):
 
     Args:
         sim_dir (str): Simulation directory
-        elmersolver (str): ElmerSolver executable
+        elmersolver (str, optional): ElmerSolver executable
     """
     if elmersolver is None:
         # On Windows ElmerSolver.exe is not found once gmsh.initialize() was executed.

pyelmer/post.py

@@ -8,19 +8,22 @@
 
 @dataclass
 class LinearIteration:
+    """Template class for evaluation of residuals - does not work very well."""
     idx: list
     relc: list
 
 
 @dataclass
 class NonlinearIteration:
+    """Template class for evaluation of residuals - does not work very well."""
     nrm: float = 0
     relc: float = 0
     linear_iteration: LinearIteration = LinearIteration([], [])
 
 
 @dataclass
 class SteadyStateIteration:
+    """Template class for evaluation of residuals - does not work very well."""
     nonlinear_iterations: list
     nrm: float = 0
     relc: float = 0
@@ -40,6 +43,7 @@ def nonlin_nrm(self):
 
 @dataclass
 class SolverResiduals:
+    """Template class for evaluation of residuals - does not work very well."""
     steady_state_iterations: list
 
     def ss_relc(self):