Merge pull request #265 from bessagroup/pr/1.4.8

Pr/1.4.8

Author: mpvanderschelling

Diff for: .flake8

@@ -19,6 +19,7 @@ extend-exclude =
 	tests
 	.git
 	studies
+	examples
 
 # <<< UPDATE ACCORDING WITH YOUR PYTHON PROJECT
 

Diff for: .github/workflows/pr_to_main.yml

@@ -24,7 +24,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
+        version: ["3.8", "3.9", "3.10", "3.11"]
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout
@@ -54,15 +54,15 @@ jobs:
       - name: Install all dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r docs/requirements.txt
+          pip install -r requirements_dev.txt
       - name: Build documentation
         run: |
           sphinx-build -b html ./docs/source ./docs/build/html
   build-package:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
+        version: ["3.8", "3.9", "3.10", "3.11"]
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout

Diff for: .github/workflows/pr_to_pr.yml

@@ -65,7 +65,7 @@ jobs:
         run: python -m pip install -U sphinx
       - name: Install Sphinx requirements
         run: |
-          pip install -r docs/requirements.txt
+          pip install -r requirements_dev.txt
       - name: Build documentation
         run: |
           sphinx-build -b html ./docs/source ./docs/build/html

Diff for: .github/workflows/push_to_main.yml

@@ -24,7 +24,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
+        version: ["3.8", "3.9", "3.10", "3.11"]
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout
@@ -45,7 +45,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
+        version: ["3.8", "3.9", "3.10", "3.11"]
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout

Diff for: .gitignore

@@ -126,4 +126,9 @@ notebooks/tutorials/Data/
 # Exclude obj files in tests folder
 !tests/*/*.obj
 
-*.lock
+*.lock
+
+# Exclude sphinx gallery files
+docs/source/auto_examples/
+docs/source/gen_modules/
+docs/source/sg_execution_times.rst

Diff for: README.md

@@ -13,22 +13,46 @@ f3dasm
 | [**Installation**](https://f3dasm.readthedocs.io/en/latest/rst_doc_files/general/gettingstarted.html)
 | [**GitHub**](https://github.com/bessagroup/f3dasm)
 | [**PyPI**](https://pypi.org/project/f3dasm/)
-| [**Practical sessions**](https://github.com/mpvanderschelling/f3dasm_teach)
 
 ## Summary
 
-Welcome to `f3dasm`, a Python package for data-driven design and analysis of structures and materials.
+Welcome to `f3dasm`, a **f**ramework for **d**ata-**d**riven **d**esign and **a**nalysis of **s**tructures and **m**aterials.
 
+`f3dasm` introduces a general and user-friendly data-driven Python package for researchers and practitioners working on design and analysis of materials and structures. Some of the key features include:
+
+-  **Modular design** 
+    - The framework introduces flexible interfaces, allowing users to easily integrate their own models and algorithms.
+
+- **Automatic data management**
+    -  The framework automatically manages I/O processes, saving you time and effort implementing these common procedures.
+
+- **Easy parallelization**
+    - The framework manages parallelization of experiments, and is compatible with both local and high-performance cluster computing.
+
+- **Built-in defaults**
+    - The framework includes a collection of benchmark functions, optimization algorithms and sampling strategies to get you started right away!
+
+- **Hydra integration**
+    - The framework is supports the [hydra](https://hydra.cc/) configuration manager, to easily manage and run experiments.
+
+## Getting started
+
+The best way to get started is to follow the [installation instructions](https://f3dasm.readthedocs.io/en/latest/rst_doc_files/general/gettingstarted.html).
+
+## Illustrative benchmarks
+
+This package includes a collection of illustrative benchmark studies that demonstrate the capabilities of the framework. These studies are available in the `/studies` folder, and include the following studies:
+
+- Benchmarking optimization algorithms against well-known benchmark functions
+- 'Fragile Becomes Supercompressible' ([Bessa et al. (2019)](https://onlinelibrary.wiley.com/doi/full/10.1002/adma.201904845))
 
 ## Authorship
 
 * Current created and developer: [M.P. van der Schelling](https://github.com/mpvanderschelling/) ([email protected])
 
 The Bessa research group at TU Delft is small... At the moment, we have limited availability to help future users/developers adapting the code to new problems, but we will do our best to help!
 
-## Getting started
 
-The best way to get started is to follow the [installation instructions](https://f3dasm.readthedocs.io/en/latest/rst_doc_files/general/gettingstarted.html).
 
 ## Referencing
 
@@ -48,7 +72,7 @@ If you find any **issues, bugs or problems** with this template, please use the
 
 ## License
 
-Copyright 2023, Martin van der Schelling
+Copyright 2024, Martin van der Schelling
 
 All rights reserved.
 

Diff for: VERSION

@@ -1 +1 @@
-1.4.71
+1.4.8

Diff for: docs/Makefile

@@ -44,7 +44,8 @@ help:
 
 clean:
 	-rm -rf $(BUILDDIR)/*
-
+	-rm -rf $(SOURCEDIR)/auto_examples/*
+	-rm -rf $(SOURCEDIR)/gen_modules/*
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html 
 	@echo

Diff for: docs/requirements.txt

@@ -2,4 +2,5 @@ sphinx
 sphinx_rtd_theme
 sphinxcontrib-bibtex
 sphinx_autodoc_typehints
-sphinx-tabs==3.4.4
+sphinx-tabs==3.4.4
+sphinx-gallery

Diff for: docs/source/conf.py

@@ -7,6 +7,8 @@
 import os
 import sys
 
+from sphinx_gallery.sorting import FileNameSortKey
+
 # -- Search path for extensions and modules -----------------------------------
 # If extensions or Python modules are in a different directory than this file,
 # then add these directories to sys.path so that Sphinx can search for them
@@ -24,9 +26,9 @@
 
 project = 'f3dasm'
 author = 'Martin van der Schelling'
-copyright = '2022, Martin van der Schelling'
-version = '1.4.71'
-release = '1.4.71'
+copyright = '2024, Martin van der Schelling'
+version = '1.4.8'
+release = '1.4.8'
 
 
 # -- General configuration ----------------------------------------------------
@@ -43,7 +45,18 @@
               'sphinx.ext.intersphinx',
               'sphinx.ext.viewcode',
               'sphinx_autodoc_typehints',
-              'sphinx_tabs.tabs']
+              'sphinx_tabs.tabs',
+              'sphinx_gallery.gen_gallery',]
+
+sphinx_gallery_conf = {
+    'examples_dirs': ['../../examples'],   # path to your example scripts
+    'gallery_dirs': ['auto_examples'],
+    'reference_url': {'sphinx_gallery': None, },
+    'backreferences_dir': 'gen_modules/backreferences',
+    'doc_module': ('f3dasm',),
+    "filename_pattern": r"/*\.py",
+    "within_subsection_order": FileNameSortKey,
+}
 
 # Source: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-source_suffix
 source_suffix = {'.rst': 'restructuredtext', }

Diff for: docs/source/img/reaction-braking-stopping.png

@@ -7,76 +7,16 @@ f3dasm
 ======
 
 .. toctree::
-   :maxdepth: 3
-   :caption: General
+   :maxdepth: 1
    :hidden:
-   :glob:
 
-   rst_doc_files/general/gettingstarted
    rst_doc_files/general/overview
+   rst_doc_files/general/installation
+   rst_doc_files/defaults
+   auto_examples/index
+   API reference <_autosummary/f3dasm>
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Design of Experiments
    :hidden:
-   :glob:
-
-   rst_doc_files/classes/design/domain
-   rst_doc_files/classes/sampling/sampling
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Data
-   :hidden:
-   :glob:
-
-   rst_doc_files/classes/design/experimentdata
-   rst_doc_files/classes/design/experimentsample
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Data Generation
-   :hidden:
-   :glob:
-
-   rst_doc_files/classes/datageneration/datagenerator
-   rst_doc_files/classes/datageneration/functions
-   rst_doc_files/classes/datageneration/f3dasm-simulate
-
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Machine Learning
-   :hidden:
-   :glob:
-
-   rst_doc_files/classes/machinelearning/machinelearning
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Optimization
-   :hidden:
-   :glob:
-
-   rst_doc_files/classes/optimization/optimizers
-   rst_doc_files/classes/optimization/f3dasm-optimize
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Data-driven process
-   :hidden:
-   :glob:
-
-   rst_doc_files/classes/workflow/workflow
-   rst_doc_files/classes/workflow/hydra
-   rst_doc_files/classes/workflow/cluster
-
-.. toctree::
-   :name: apitoc
-   :caption: API
-   :hidden:
-
-   rst_doc_files/reference/index.rst
-   Code <_autosummary/f3dasm>
 
 .. include:: readme.rst