Merge pull request #265 from bessagroup/pr/1.4.8

Pr/1.4.8

.flake8

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

.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

.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

.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

.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

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.
 

VERSION

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

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

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

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', }

docs/source/index.rst

@@ -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