DFM experiments

.github/workflows/pythonpackage.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:      
       matrix:
-        python-version: [3.6, 3.7, 3.8]
+        python-version: ["3.10", "3.12"]
 
     steps:
     - uses: actions/checkout@v2

.readthedocs.yaml

@@ -1,16 +1,17 @@
-# Required
+# .readthedocs.yml
 version: 2
 
-# Build documentation in the docs/ directory with Sphinx
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
 sphinx:
-   configuration: docs/source/conf.py
+  configuration: docs/source/conf.py
 
-# Optionally build your docs in additional formats such as PDF
 formats:
-   - pdf
+  - pdf
 
-# Optionally set the version of Python and requirements required to build your docs
 python:
-   version: 3.8
-   install:
+  install:
     - requirements: docs/requirements.txt

README.rst

@@ -1,63 +1,93 @@
-
 MLMC
-----
+====
 
 .. image:: https://github.com/GeoMop/MLMC/workflows/package/badge.svg
     :target: https://github.com/GeoMop/MLMC/actions
 .. image:: https://img.shields.io/pypi/v/mlmc.svg
     :target: https://pypi.org/project/mlmc/
 .. image:: https://img.shields.io/pypi/pyversions/mlmc.svg
     :target: https://pypi.org/project/mlmc/
+.. image:: https://img.shields.io/badge/License-GPLv3-blue.svg
+    :target: https://www.gnu.org/licenses/gpl-3.0.html
 
-MLMC provides tools for the multilevel Monte Carlo method.
-
-mlmc package includes:
 
-- samples scheduling
-- estimation of generalized moment functions
-- probability density function approximation
-- advanced post-processing with Quantity structure
+**MLMC** is a Python library implementing the **Multilevel Monte Carlo (MLMC)** method.
+It provides tools for sampling, moment estimation, statistical post-processing, and more.
 
+Originally developed as part of the `GeoMop <http://geomop.github.io/>`_ project.
 
-It is meant as part of the `GeoMop  <http://geomop.github.io/>`_ project in particular Analysis component.
+Features
+--------
 
+* Sample scheduling
+* Estimation of generalized moments
+* Advanced post-processing with the ``Quantity`` structure
+* Approximation of probability density functions using the maximum entropy method
+* Bootstrap and regression-based variance estimation
+* Diagnostic tools (e.g., consistency checks)
 
 Installation
-----------------------------------
-Package can be installed via pip.
+------------
+
+The package is available on PyPI and can be installed with pip:
 
-.. code-block::
+.. code-block:: bash
 
     pip install mlmc
 
+To install the latest development version:
+
+.. code-block:: bash
+
+    git clone https://github.com/GeoMop/MLMC.git
+    cd MLMC
+    pip install -e .
 
 Documentation
 -------------
-You can find the documentation including tutorials under https://mlmc.readthedocs.io/
+
+Full documentation, including tutorials, is available at:
+`https://mlmc.readthedocs.io/ <https://mlmc.readthedocs.io/>`_
+
+Topics covered include:
+
+* Basic MLMC workflow and examples
+* Definition and composition of ``Quantity`` objects
+* Moment and covariance estimation
+* Probability density function reconstruction
 
 
 Development
 -----------
 
-Provided that you want to contribute, create a pull request and make sure you run `tox` before. Tox
-installs necessary requirements as well as the developed package itself into clear virtual environment
-and call pytest to search in the `test` folder for tests to execute.
+Contributions are welcome!
+To contribute, please fork the repository and create a pull request.
+
+Before submitting, make sure all tests pass by running ``tox``:
+
+.. code-block:: bash
 
+    pip install tox
+    tox
+
+``tox`` creates a clean virtual environment, installs all dependencies,
+runs unit tests via ``pytest``, and checks that the package installs correctly.
 
 Requirements
 ------------
-- `NumPy  <https://pypi.org/project/numpy/>`_
-- `SciPy  <https://pypi.org/project/scipy/>`_
-- `h5py  <https://pypi.org/project/h5py/>`_
-- `attrs  <https://pypi.org/project/attrs/>`_
-- `ruamel.yaml  <https://pypi.org/project/ruamel.yaml/>`_
-- `gstools  <https://pypi.org/project/gstools/>`_
-- `memoization  <https://pypi.org/project/memoization/>`_
-- `sklearn  <https://pypi.org/project/sklearn/>`_
 
+MLMC depends on the following Python packages:
 
-Licence
--------
-* Free software: GPL 3.0  License
+* `NumPy <https://pypi.org/project/numpy/>`_
+* `SciPy <https://pypi.org/project/scipy/>`_
+* `h5py <https://pypi.org/project/h5py/>`_
+* `attrs <https://pypi.org/project/attrs/>`_
+* `ruamel.yaml <https://pypi.org/project/ruamel.yaml/>`_
+* `gstools <https://pypi.org/project/gstools/>`_
+* `memoization <https://pypi.org/project/memoization/>`_
+* `scikit-learn <https://pypi.org/project/scikit-learn/>`_
 
+License
+-------
 
+* Free software: **GNU General Public License v3.0**

docs/requirements.txt

@@ -1,9 +1,18 @@
+# --- Documentation dependencies ---
+sphinx>=7.0
+sphinx-rtd-theme
+sphinx-autodoc-typehints
+sphinxcontrib-napoleon
+myst-parser
+nbsphinx
+sphinx_copybutton
+
+# --- MLMC runtime dependencies ---
 numpy
 scipy
-sklearn
+scikit-learn
 h5py>=3.1.0
-ruamel.yaml
+ruamel.yaml==0.17.26
 attrs
 gstools
-memoization
-matplotlib
+memoization

docs/source/conf.py

@@ -1,97 +1,80 @@
 # 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:
+# For a full list of configuration options see:
 # 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
 import datetime
+
+# -- Path setup --------------------------------------------------------------
+
+# Add project root to sys.path
 sys.path.insert(0, os.path.abspath("../../"))
 
 # -- Project information -----------------------------------------------------
-# General information about the project.
+
 curr_year = datetime.datetime.now().year
 project = "mlmc"
-copyright = "{}, Jan Březina, Martin Špetlík".format(curr_year)
-author = "Jan Březina, Martin Špetlík"
+copyright = f"{curr_year}, Martin Špetlík, Jan Březina"
+author = "Martin Špetlík, Jan Březina"
 
 # The full version, including alpha/beta/rc tags
-release = '1.0.1'
-
+release = "1.0.3"
 
 # -- 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.autosummary',
-    'sphinx.ext.napoleon',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.doctest',
-    'sphinx.ext.autosectionlabel'
-    ]
-
-# autosummaries from source-files
-autosummary_generate = True
-# dont show __init__ docstring
-autoclass_content = 'class'
-# sort class members
-autodoc_member_order = "groupwise"
-# autodoc_member_order = 'bysource'
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.doctest",
+    "sphinx.ext.autosectionlabel",
+    "sphinx_autodoc_typehints",
+    "myst_parser",
+    "nbsphinx",
+    "sphinx_copybutton",
+]
+
+# Autodoc settings
+autosummary_generate = True           # Generate autosummary files
+autoclass_content = "class"           # Don't repeat __init__ docstring
+autodoc_member_order = "groupwise"    # Grouped members in docs
+autodoc_typehints = "description"     # Show type hints in docstring
+
+# Napoleon settings for Google-style docstrings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_use_param = True
+napoleon_use_ivar = 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 = []
+templates_path = ["_templates"]
 
+# Exclude build files and system junk
+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.
-#
-html_theme = "sphinx_rtd_theme" #'alabaster'
+html_theme = "sphinx_rtd_theme"
 
 html_theme_options = {
-    #    'canonical_url': '',
-    #    'analytics_id': '',
     "logo_only": False,
     "display_version": True,
     "prev_next_buttons_location": "top",
-    #    'style_external_links': False,
-    #    'vcs_pageview_mode': '',
-    # Toc options
     "collapse_navigation": False,
     "sticky_navigation": True,
     "navigation_depth": 4,
     "includehidden": True,
     "titles_only": False,
 }
 
-# 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']
-
-# autodoc_default_options = {
-#     'members': True,
-#     # The ones below should be optional but work nicely together with
-#     # example_package/autodoctest/doc/source/_templates/autosummary/class.rst
-#     # and other defaults in sphinx-autodoc.
-#     'show-inheritance': True,
-#     'inherited-members': True,
-#     'no-special-members': True,
-# }
+# Optional: uncomment if you have static files like custom CSS
+# html_static_path = ["_static"]
+
+# This tells Sphinx which file is the master doc (entry point)
 master_doc = "contents"
+
+# -- Optional convenience: print path info on build --------------------------
+print(f"[conf.py] Using sys.path[0]: {sys.path[0]}")

docs/source/examples.rst

@@ -4,7 +4,10 @@ Tutorials
 
 .. automodule:: examples
 
-The following tutorials illustrates how to use mlmc package.
+This section provides step-by-step tutorials demonstrating how to use the **mlmc** package.
+
+Each tutorial builds upon the previous one — starting from sampler creation, through sample scheduling and quantity handling, to full postprocessing and probability density estimation.
+
 
 .. toctree::
    :includehidden:
@@ -16,4 +19,12 @@ The following tutorials illustrates how to use mlmc package.
    examples_postprocessing
 
 
-You can find more complex examples in :any:`examples.shooting`
+Additional Examples
+-------------------
+
+You can find more advanced and domain-specific examples (e.g., stochastic simulations or PDE-based problems) in:
+
+:mod:`examples.shooting`
+
+These examples demonstrate how to integrate MLMC with real-world simulation workflows.
+