Devel

.github/workflows/regression-tests.yml

@@ -1,6 +1,4 @@
-# This workflow will install and then lint the code with Flake8 and Pylint.
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
-
+# This workflow will run some regression tests.
 name: Regression Tests
 
 on:
@@ -10,11 +8,12 @@ on:
     branches: '*'
 
 jobs:
+
   Pytest:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-      # Add multiple Python versions here to run tests on new(er) versions.
+        # Add multiple Python versions here to run tests on new(er) versions.
         python-version: ["3.10"]
     steps:
     - uses: actions/checkout@v3
@@ -26,34 +25,90 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         # Install with -e (in editable mode) to allow the tracking of the test coverage
-        pip install -e .
+        pip install -e .[test]
     - name: Analyse the code with pytest
       run: |
         # Run the actual testing
-        pytest -v --cov=panelaero --junitxml=testresult.xml
+        pytest -v --basetemp=./tmp --cov=panelaero --junitxml=testresult.xml
         # Create some reports
         coverage report
         coverage xml -o coverage.xml
         # Put the html into a 2nd-level sub-folder and use 1st-level subfolder for uploading to maintain folder
-        coverage html --directory ./coverage/coverage
-    - name: Upload HTML coverage report as an artifact
-      uses: actions/upload-artifact@v3
+        coverage html --directory ./coverage
+    - name: Upload test restults and coverage as an artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: test results and coverage
+        path: |
+          testresult.xml
+          coverage.xml
+          coverage
+        if-no-files-found: ignore
+
+  Jupyter:
+    # Building the Jupyter book is not really a regression test. However, it has to be in this workflow due to the handling of 
+    # the artifacts.
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # Select Python version to be used for compiling here.
+        python-version: ["3.10"]
+    # Step 1 to make GUIs work, see https://pytest-qt.readthedocs.io/en/latest/troubleshooting.html
+    env:
+      DISPLAY: ':99.0'
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
       with:
-        name: coverage
-        path: ./coverage
+        python-version: ${{ matrix.python-version }}
+    # Step 2 to make GUIs work
+    - uses: tlambert03/setup-qt-libs@v1
+    - name: Install dependencies
+      run: |
+        # Step 3 to make GUIs work
+        /sbin/start-stop-daemon --start --quiet --pidfile /tmp/custom_xvfb_99.pid --make-pidfile --background --exec /usr/bin/Xvfb -- :99 -screen 0 1920x1200x24 -ac +extension GLX
+        python -m pip install --upgrade pip
+        # Install the package itself to make sure that all imports work.
+        pip install .[tutorials]
+    - name: Assemble the tutorials to a jupyter book and build htlm pages
+      run: |
+        jupyter-book build ./doc/tutorials
+        # Put the html into a 2nd-level sub-folder and use 1st-level subfolder for uploading
+        mkdir ./doc/html
+        mv ./doc/tutorials/_build/html ./doc/html/tutorials
+    - name: Upload Jupyter book as an artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: tutorials
+        path: ./doc/html
         if-no-files-found: ignore
-    - name: Upload HTML coverage report for pages
+
+  combine-pages:
+    runs-on: ubuntu-latest
+    # Add a dependency to the build job
+    needs: [Jupyter, Pytest]
+    steps:
+    - uses: actions/download-artifact@v4
+      with:
+        merge-multiple: true
+    - name: See what we've got and merge artifacts
+      run: |
+        ls -la
+        mkdir pages
+        mv ./tutorials ./pages/tutorials
+        mv ./coverage ./pages/coverage
+    - name: Upload artifact for pages
       # This is not a normal artifact but one that can be deployed to the GitHub pages in the next step
       uses: actions/upload-pages-artifact@v3
       with:
-        name: github-pages # This name may not be changed according to the documentation
-        path: ./coverage
+        name: github-pages  # This name may not be changed according to the documentation
+        path: ./pages  # There must be only one path
         if-no-files-found: ignore
-
+    
   deploy-pages:
     # Add a dependency to the build job
-    needs: Pytest
-
+    needs: combine-pages
     # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
     permissions:
       pages: write      # to deploy to Pages

.gitignore

@@ -0,0 +1,3 @@
+*.pyc
+.pytest_cache/
+Panel_Aero.egg-info/

.gitlab-ci.yml

@@ -7,8 +7,8 @@ stages:
   - deploy
 
 .virtenv: &virtualenv
-  - python -m venv buildenv
-  - . buildenv/bin/activate
+  - python -m venv virtualenv
+  - source virtualenv/bin/activate
 
 build:
   # This stage only tests if the installation is possible.
@@ -31,11 +31,11 @@ test:
   script:
     - *virtualenv
     # Install with -e (in editable mode) to allow the tracking of the test coverage
-    - pip install -e .
+    - pip install -e .[test]
     - which python
     - which pytest
     # Run the actual testing
-    - pytest -v --basetemp=./test_tmp --cov-report xml:coverage.xml --cov=panelaero --junitxml=testresult.xml
+    - pytest -v --basetemp=./tmp --cov-report xml:coverage.xml --cov=panelaero --junitxml=testresult.xml
     - coverage xml -o coverage.xml
     - coverage report
     - coverage html --directory ./coverage

README.md

@@ -9,28 +9,42 @@ Voß, A., “An Implementation of the Vortex Lattice and the Doublet Lattice Met
 If you use this software for your scientific work, we kindly ask you to include a reference to this report in your publications. Thank you!
 
 # Installation & Use
-## User installation 
-To install everything as a python package, including dependencies:
+## Basic Installation 
+Install Panel Aero as a python package with core dependencies via:
 
 ```
-pip install --user git+https://github.com/DLR-AE/PanelAero.git
+pip install git+https://github.com/DLR-AE/PanelAero.git
 ```
 ## How can I use it?
-
-In Python, you can import the VLM or the DLM as shown below. For further details, please see the example section.
+In Python, you can import the VLM or the DLM as shown below. For further details, please see the Tutorials section. This is no stand-alone aerodynamic software but is intended to be integrated in other software, for example for loads and aeroelastic analyses.
 
 ```
-import panelaero.VLM as VLM
-import panelaero.DLM as DLM
+from panelaero import VLM, DLM
 ```
 
-## Developer installation 
+## Advanced Installation 
 As above, but with access to the code (keep the code where it is so that you can explore and modify):
 
 ```
 git clone https://github.com/DLR-AE/PanelAero.git
-cd ./panel-aero
-pip install --user -e . 
+cd <local_repo_path>
+pip install -e . 
+```
+
+## Tutorials & Examples
+There is a growing number of tutorials based on Jupyter notebooks. You can either have a look at the static html tutorials or use the Jupyter notebooks interactively. For the latter, start a jupyter notebook server, which will open a dashboard in your web browser. Then open one of the *.ipynb notebooks from ./doc/tutorials and walk through the tutorials step-by-step.
+
+[View html tutorials](https://dlr-ae.github.io/PanelAero/tutorials/)
+
+or
+
+```
+jupyter notebook
+```
+Any missing dependencies (probably jupyter and mayavi) can be installed with:
+
+```
+pip install -e .[tutorials]
 ```
 
 # License

doc/tutorials/_config.yml

@@ -0,0 +1,53 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: Panel Aero Tutorials
+author: Arne Voß
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: force
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: tutorials.tex
+
+# Add a bibtex file so that we can create citations
+bibtex_bibfiles:
+  - references.bib
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/DLR-AE/PanelAero  # Online location of your book
+  path_to_book: ./tutorials  # Optional path to your book, relative to the repository root
+  branch: master  # Which branch of the repository should be used when creating links (optional)
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  use_issues_button: true
+  use_repository_button: true
+
+# Set parameter to prevent that each line of the console output is displayed as a new cell.
+# From what I understood, this is because the log messages are a stream, and streams are rendered 
+# differently by Jupyter. 
+sphinx:
+  config:
+    nb_merge_streams: true
+
+# Parse and render settings
+parse:
+  myst_enable_extensions:  # default extensions to enable in the myst parser. See https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html
+    # - amsmath
+    - colon_fence
+    # - deflist
+    - dollarmath
+    # - html_admonition
+    - html_image
+    - linkify
+    # - replacements
+    # - smartquotes
+    - substitution
+    - tasklist

doc/tutorials/_toc.yml

@@ -0,0 +1,8 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: intro
+chapters:
+- file: simplewing/simplewing_steady
+- file: simplewing/simplewing_unsteady

example/plotting.py → doc/tutorials/helper_functions/plotting.py

@@ -12,7 +12,7 @@ class DetailedPlots():
     def __init__(self, model):
         self.model = model
 
-    def plot_aerogrid(self, scalars=None, colormap='plasma', value_min=None, value_max=None):
+    def plot_aerogrid(self, scalars=None, colormap='plasma', embed_in_notebook=False):
         # create the unstructured grid
         points = self.model.aerogrid['cornerpoint_grids'][:, (1, 2, 3)]
         ug = tvtk.UnstructuredGrid(points=points)
@@ -24,33 +24,31 @@ def plot_aerogrid(self, scalars=None, colormap='plasma', value_min=None, value_m
         ug.cell_data.scalars = scalars
 
         # hand over unstructured grid to mayavi
-        mlab.figure(bgcolor=(1, 1, 1))
+        if embed_in_notebook:
+            mlab.init_notebook('png')
+        mlab.figure(bgcolor=(1, 1, 1), size=(600, 450))
         src_aerogrid = mlab.pipeline.add_dataset(ug)
 
         # determine if suitable scalar data is given
         if scalars is not None:
-            # determine an upper and lower limit of the colorbar, if not given
-            if value_min is None:
-                value_min = scalars.min()
-            if value_max is None:
-                value_max = scalars.max()
             surface = mlab.pipeline.surface(src_aerogrid, opacity=1.0, line_width=0.5,
-                                            colormap=colormap, vmin=value_min, vmax=value_max)
+                                            colormap=colormap, vmin=scalars.min(), vmax=scalars.max())
             surface.actor.mapper.scalar_visibility = True
 
             surface.module_manager.scalar_lut_manager.show_legend = True
             surface.module_manager.scalar_lut_manager.data_name = ''
             surface.module_manager.scalar_lut_manager.label_text_property.color = (0, 0, 0)
-            surface.module_manager.scalar_lut_manager.label_text_property.font_family = 'times'
+            surface.module_manager.scalar_lut_manager.label_text_property.font_family = 'arial'
             surface.module_manager.scalar_lut_manager.label_text_property.bold = False
             surface.module_manager.scalar_lut_manager.label_text_property.italic = False
-            surface.module_manager.scalar_lut_manager.title_text_property.color = (0, 0, 0)
-            surface.module_manager.scalar_lut_manager.title_text_property.font_family = 'times'
-            surface.module_manager.scalar_lut_manager.title_text_property.bold = False
-            surface.module_manager.scalar_lut_manager.title_text_property.italic = False
             surface.module_manager.scalar_lut_manager.number_of_labels = 5
         else:
             surface = mlab.pipeline.surface(src_aerogrid, opacity=1.0, line_width=0.5)
             surface.actor.mapper.scalar_visibility = False
         surface.actor.property.edge_visibility = True
-        mlab.show()
+        mlab.view(azimuth=60.0, elevation=-65.0, roll=55.0)
+
+        if embed_in_notebook:
+            return surface
+        else:
+            mlab.show()

doc/tutorials/intro.md

@@ -0,0 +1,11 @@
+# Panel Aero Tutorials
+
+While the Technical Report {cite}`vos_implementation_2020` mainly describes the theoretical background, this collection of tutorials focuses on how to use the software.
+
+```{tableofcontents}
+```
+
+
+```{bibliography}
+:style: unsrt
+```

doc/tutorials/references.bib

@@ -0,0 +1,12 @@
+
+@techreport{vos_implementation_2020,
+	address = {Göttingen, Germany},
+	type = {Technical {Report}},
+	title = {An {Implementation} of the {Vortex} {Lattice} and the {Doublet} {Lattice} {Method}},
+	url = {https://elib.dlr.de/136536/},
+	number = {DLR-IB-AE-GO-2020-137},
+	institution = {Institut für Aeroelastik, Deutsches Zentrum für Luft- und Raumfahrt},
+	author = {Voß, Arne},
+	year = {2020},
+	file = {Voß - 2020 - An Implementation of the Vortex Lattice and the Do.pdf:/work/voss_ar/Literatur/Paper/Voß - 2020 - An Implementation of the Vortex Lattice and the Do.pdf:application/pdf},
+}

example/simplewing.CAERO1 → doc/tutorials/simplewing/simplewing.CAERO1

@@ -1,5 +1,5 @@
 $ This is the CAERO input card (see Nastran Quick Reference Guide) 
 $ for a simple wing with 40x10 panels.
 $------><------><------><------><------><------><------><------><------>
-CAERO1   6401001    1001       0      40      10                       1+       
+CAERO1   6401001               0      40      10                        +       
 +            0.0  -0.552     0.0     0.1     0.0  +0.552     0.0     0.1