PyTracerLab 0.2.0__tar.gz

pytracerlab-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install deps (pkg + dev tools)
+        run: |
+          python -m pip install -U pip
+          pip install -e .[dev]
+      - name: Run pre-commit
+        run: pre-commit run --all-files
+      - name: Run tests
+        run: pytest -q

pytracerlab-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,38 @@
+name: Docs
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install doc deps
+        run: |
+          python -m pip install -U pip
+          # Either install dev extras...
+          # pip install -e .[dev]
+          # ...or install only what's needed for docs:
+          pip install sphinx myst-parser furo sphinx-design myst-nb
+
+      - name: Generate API stubs (sphinx-apidoc)
+        run: |
+          python -m sphinx.ext.apidoc -o docs/api src/PyTracerLab -f -e
+
+      - name: Build HTML
+        run: |
+          sphinx-build -b html -W -E docs docs/_build/html
+
+      - name: Publish to gh-pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/_build/html

pytracerlab-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,117 @@
+name: Release
+on:
+  push:
+    tags:
+      - 'v*'
+  # optional but handy:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: python -m pip install -U pip build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - name: Inspect METADATA/PKG-INFO
+        run: |
+          python - << 'PY'
+          import glob, zipfile, tarfile
+          whl = sorted(glob.glob('dist/*.whl'))[-1]
+          with zipfile.ZipFile(whl) as zf:
+              meta = [n for n in zf.namelist() if n.endswith('METADATA')][0]
+              text = zf.read(meta).decode('utf-8', errors='replace')
+              print("---- WHEEL METADATA ----")
+              print("\n".join([l for l in text.splitlines()
+                               if l.startswith(('Metadata-Version','Name:','Version:',
+                                                'Summary:','Description-Content-Type',
+                                                'Classifier','Requires-Python'))]))
+              print("\nHas Description section? ", "\n\n" in text)
+
+          sdist = sorted(glob.glob('dist/*.tar.gz'))[-1]
+          import tarfile
+          with tarfile.open(sdist, 'r:gz') as tf:
+              member = [m for m in tf.getmembers() if m.name.endswith('PKG-INFO')][0]
+              text = tf.extractfile(member).read().decode('utf-8', errors='replace')
+              print("\n---- SDIST PKG-INFO ----")
+              print("\n".join([l for l in text.splitlines()
+                               if l.startswith(('Metadata-Version','Name:','Version:',
+                                                'Summary:','Description-Content-Type',
+                                                'Classifier','Requires-Python'))]))
+              print("\nHas Description section? ", "\n\n" in text)
+          PY
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  pyinstaller-windows:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install package + PyInstaller
+        run: |
+          python -m pip install -U pip
+          pip install pyinstaller .
+      - name: Build EXE (one-file)
+        run: pyinstaller --noconfirm --onefile --windowed --name PyTracerLab -p src --hidden-import=scipy.signal --hidden-import=scipy.optimize src/PyTracerLab/__main__.py
+      - name: (Optional) add tag to filename
+        if: startsWith(github.ref, 'refs/tags/')
+        shell: pwsh
+        run: |
+          Rename-Item dist\PyTracerLab.exe "PyTracerLab-${{ github.ref_name }}.exe"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: PyTracerLab-win
+          path: dist\*.exe
+
+  pypi-publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - name: Publish to PyPI via OIDC
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+
+  github-release:
+    needs: [build, pyinstaller-windows]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: actions/download-artifact@v4
+        with:
+          name: PyTracerLab-win
+          path: dist
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+            dist/*.exe
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

pytracerlab-0.2.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.env
+
+# Build artifacts
+build/
+dist/
+*.spec
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Locally built docs
+docs/_build/

pytracerlab-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+repos:
+  - repo: local
+    hooks:
+      - id: black
+        name: black
+        entry: python -m black
+        language: system
+        types: [python]
+
+      - id: ruff
+        name: ruff
+        entry: python -m ruff check
+        language: system
+        args: [--fix]
+        types: [python]
+
+      - id: end-of-file-fixer
+        name: end-of-file-fixer
+        entry: python -m pre_commit_hooks.end_of_file_fixer
+        language: system
+        types: [text]
+
+      - id: trailing-whitespace
+        name: trailing-whitespace
+        entry: python -m pre_commit_hooks.trailing_whitespace_fixer
+        language: system
+        types: [text]

pytracerlab-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 M. G. Rudolph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytracerlab-0.2.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: PyTracerLab
+Version: 0.2.0
+Summary: Lumped parameter groundwater age simulations with a simple user interface - in Python
+Author: Max G. Rudolph
+License: MIT
+Project-URL: Homepage, https://github.com/iGW-TU-Dresden/PyTracerLab
+Project-URL: Documentation, https://iGW-TU-Dresden.github.io/PyTracerLab/
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: scipy>=1.10
+Requires-Dist: PyQt5>=5.15
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pre-commit-hooks; extra == "dev"
+Requires-Dist: mkdocs-material; extra == "dev"
+Requires-Dist: mkdocstrings[python]; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+Requires-Dist: furo; extra == "dev"
+Requires-Dist: myst-parser; extra == "dev"
+Requires-Dist: sphinx-autodoc-typehints; extra == "dev"
+Dynamic: license-file

pytracerlab-0.2.0/docs/api/PyTracerLab.gui.app.rst

@@ -0,0 +1,7 @@
+PyTracerLab.gui.app module
+==========================
+
+.. automodule:: PyTracerLab.gui.app
+   :members:
+   :show-inheritance:
+   :undoc-members:

pytracerlab-0.2.0/docs/api/PyTracerLab.gui.controller.rst

@@ -0,0 +1,7 @@
+PyTracerLab.gui.controller module
+=================================
+
+.. automodule:: PyTracerLab.gui.controller
+   :members:
+   :show-inheritance:
+   :undoc-members:

pytracerlab-0.2.0/docs/api/PyTracerLab.gui.database.rst

@@ -0,0 +1,7 @@
+PyTracerLab.gui.database module
+===============================
+
+.. automodule:: PyTracerLab.gui.database
+   :members:
+   :show-inheritance:
+   :undoc-members:

pytracerlab-0.2.0/docs/api/PyTracerLab.gui.main_window.rst

@@ -0,0 +1,7 @@
+PyTracerLab.gui.main\_window module
+===================================
+
+.. automodule:: PyTracerLab.gui.main_window
+   :members:
+   :show-inheritance:
+   :undoc-members:

pytracerlab-0.2.0/docs/api/PyTracerLab.gui.rst

@@ -0,0 +1,22 @@
+PyTracerLab.gui package
+=======================
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   PyTracerLab.gui.app
+   PyTracerLab.gui.controller
+   PyTracerLab.gui.database
+   PyTracerLab.gui.main_window
+   PyTracerLab.gui.state
+
+Module contents
+---------------
+
+.. automodule:: PyTracerLab.gui
+   :members:
+   :show-inheritance:
+   :undoc-members:

pytracerlab-0.2.0/docs/api/PyTracerLab.gui.state.rst

@@ -0,0 +1,7 @@
+PyTracerLab.gui.state module
+============================
+
+.. automodule:: PyTracerLab.gui.state
+   :members:
+   :show-inheritance:
+   :undoc-members:

pytracerlab-0.2.0/docs/api/PyTracerLab.model.model.rst

@@ -0,0 +1,7 @@
+PyTracerLab.model.model module
+==============================
+
+.. automodule:: PyTracerLab.model.model
+   :members:
+   :show-inheritance:
+   :undoc-members:

pytracerlab-0.2.0/docs/api/PyTracerLab.model.registry.rst

@@ -0,0 +1,7 @@
+PyTracerLab.model.registry module
+=================================
+
+.. automodule:: PyTracerLab.model.registry
+   :members:
+   :show-inheritance:
+   :undoc-members:

pytracerlab-0.2.0/docs/api/PyTracerLab.model.rst

@@ -0,0 +1,21 @@
+PyTracerLab.model package
+=========================
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   PyTracerLab.model.model
+   PyTracerLab.model.registry
+   PyTracerLab.model.solver
+   PyTracerLab.model.units
+
+Module contents
+---------------
+
+.. automodule:: PyTracerLab.model
+   :members:
+   :show-inheritance:
+   :undoc-members:

pytracerlab-0.2.0/docs/api/PyTracerLab.model.solver.rst

@@ -0,0 +1,7 @@
+PyTracerLab.model.solver module
+===============================
+
+.. automodule:: PyTracerLab.model.solver
+   :members:
+   :show-inheritance:
+   :undoc-members:

pytracerlab-0.2.0/docs/api/PyTracerLab.model.units.rst

@@ -0,0 +1,7 @@
+PyTracerLab.model.units module
+==============================
+
+.. automodule:: PyTracerLab.model.units
+   :members:
+   :show-inheritance:
+   :undoc-members:

pytracerlab-0.2.0/docs/api/PyTracerLab.rst

@@ -0,0 +1,19 @@
+PyTracerLab package
+===================
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   PyTracerLab.gui
+   PyTracerLab.model
+
+Module contents
+---------------
+
+.. automodule:: PyTracerLab
+   :members:
+   :show-inheritance:
+   :undoc-members:

pytracerlab-0.2.0/docs/api/modules.rst

@@ -0,0 +1,7 @@
+PyTracerLab
+===========
+
+.. toctree::
+   :maxdepth: 4
+
+   PyTracerLab

pytracerlab-0.2.0/docs/conf.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+
+os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
+
+project = "PyTracerLab"
+author = "Max G. Rudolph"
+
+extensions = [
+    "myst_nb",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "sphinx_design",
+]
+
+# notebook execution (safe default for CI)
+nb_execution_mode = "off"  # "cache" or "auto" for execution enabled
+nb_execution_timeout = 300
+
+# mock heavy deps during doc builds
+autodoc_mock_imports = ["PyQt5", "numpy", "scipy", "matplotlib"]
+
+autosummary_generate = True
+autodoc_default_options = {"members": True, "undoc-members": False, "show-inheritance": False}
+
+napoleon_google_docstring = False  # True if using Google style
+napoleon_numpy_docstring = True  # True if using NumPy style
+# Render class attribute docs from "Attributes" sections as plain ivar fields
+# (prevents duplicate attribute targets alongside autodoc's member listing)
+napoleon_use_ivar = True
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "fieldlist",
+    "attrs_inline",
+    "attrs_block",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**/.ipynb_checkpoints"]
+
+html_theme = "furo"
+html_static_path = ["_static"]
+html_logo = "_static/logo.png"
+html_title = "PyTracerLab Documentation"
+html_short_title = "PyTracerLab"
+html_show_sphinx = True
+html_show_copyright = True
+
+# html_theme_options = {
+#     "use_edit_page_button": True,
+#     "header_links_before_dropdown": 6,
+#     "icon_links": [
+#         {
+#             "name": "GitHub",
+#             "url": "https://github.com/iGW-TU-Dresden/PyTracerLab",
+#             "icon": "fab fa-github-square",
+#             "type": "fontawesome",
+#         }
+#     ],
+# }
+
+# use None for inventories (Sphinx 8+)
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+}
+
+# do not document re-exported names (prevents duplicate objects)
+autosummary_imported_members = False
+
+# Disambiguate short type names in NumPy-style docstrings
+napoleon_type_aliases = {
+    "Unit": "PyTracerLab.model.units.Unit",
+    "Model": "PyTracerLab.model.Model",  # prefer public alias to avoid ambiguity
+    "Solver": "PyTracerLab.model.solver.Solver",
+}

pytracerlab-0.2.0/docs/development/devguide.md

@@ -0,0 +1,16 @@
+# Development
+
+Here we discuss how PyTracerLab is structured internally and how new functionality (especially to the GUI) can be added easily.
+
+## PyTracerLab Structure
+
+PyTracerLab has to principal parts: the `model` sub-package and the `gui` sub-package. This structure is depicted in Figure 1. The `model` sub-package contains the main functions for the model; it can be used as a regular python package and includes, i.a., modules to create and run lumped parameter models using various model units, and to optimize model parameters. The `gui` sub-package contains the main functions for the GUI; it creates an interface to various parts of the `model` sub-package and enables non-technical users to load data, create and run models, to optimize model parameters, and to view and export results.
+
+```{figure} package_scheme.png
+
+Figure 1: The pricipal structure of the PyTracerLab package and its main parts. Main modules are written in bold; main mechanisms and connections are represented via arrows.
+```
+
+## Adding New Functionality
+
+The addition of new functionality is best illustrated looking at the general structure of PyTracerLab.

pytracerlab-0.2.0/docs/development/index.md

@@ -0,0 +1,9 @@
+# Development
+
+```{toctree}
+:maxdepth: 2
+:caption: Guides
+:hidden:
+
+devguide
+```