caskade 0.0.1__tar.gz

caskade-0.0.1/.github/workflows/cd.yml

@@ -0,0 +1,99 @@
+name: CD
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+      - dev
+  release:
+    types:
+      - published
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  FORCE_COLOR: 3
+
+jobs:
+  dist:
+    name: Distribution build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Build sdist and wheel
+        run: pipx run build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          path: dist
+
+      - name: Check products
+        run: pipx run twine check dist/*
+
+  test-built-dist:
+    needs: [dist]
+    name: Test built distribution
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/setup-python@v5
+        name: Install Python
+        with:
+          python-version: "3.10"
+      - uses: actions/download-artifact@v4
+        with:
+          name: artifact
+          path: dist
+      - name: List contents of built dist
+        run: |
+          ls -ltrh
+          ls -ltrh dist
+      - name: Publish to Test PyPI
+        uses: pypa/gh-action-pypi-publish@v1.10.3
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          verbose: true
+          skip-existing: true
+      - name: Check pypi packages
+        run: |
+          sleep 3
+          python -m pip install --upgrade pip
+
+          echo "=== Testing wheel file ==="
+          # Install wheel to get dependencies and check import
+          python -m pip install --extra-index-url https://test.pypi.org/simple --upgrade --pre caskade
+          python -c "import caskade; print(caskade.__version__); caskade.test()"
+          echo "=== Done testing wheel file ==="
+
+          echo "=== Testing source tar file ==="
+          # Install tar gz and check import
+          python -m pip uninstall --yes caskade
+          python -m pip install --extra-index-url https://test.pypi.org/simple --upgrade --pre --no-binary=:all: caskade
+          python -c "import caskade; print(caskade.__version__); caskade.test()"
+          echo "=== Done testing source tar file ==="
+
+  publish:
+    needs: [dist, test-built-dist]
+    name: Publish to PyPI
+    environment: pypi
+    permissions:
+      id-token: write
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release' && github.event.action == 'published'
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: artifact
+          path: dist
+
+      - uses: pypa/gh-action-pypi-publish@v1.10.3
+        if: startsWith(github.ref, 'refs/tags')

caskade-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,83 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: CI
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+      - dev
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  FORCE_COLOR: 3
+  PROJECT_NAME: "caskade"
+
+jobs:
+  build:
+    runs-on: ${{matrix.os}}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11"]
+        os: [ubuntu-latest, windows-latest, macOS-latest]
+
+    steps:
+      - name: Checkout caskade
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+
+      - name: Record State
+        run: |
+          pwd
+          echo github.ref is: ${{ github.ref }}
+          echo GITHUB_SHA is: $GITHUB_SHA
+          echo github.event_name is: ${{ github.event_name }}
+          echo github workspace: ${{ github.workspace }}
+          pip --version
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest pytest-cov torch wheel pydantic
+
+      # We only want to install this on one run, because otherwise we'll have
+      # duplicate annotations.
+      - name: Install error reporter
+        if: ${{ matrix.python-version == '3.10' }}
+        run: |
+          python -m pip install pytest-github-actions-annotate-failures
+
+      - name: Install caskade
+        run: |
+          pip install -e ".[dev]"
+          pip show ${{ env.PROJECT_NAME }}
+
+      - name: Test with pytest
+        run: |
+          pytest -vvv --cov=${{ env.PROJECT_NAME }} --cov-report=xml --cov-report=term tests/
+
+      - name: Upload coverage reports to Codecov with GitHub Action
+        if:
+          ${{ matrix.python-version == '3.10' && matrix.os == 'ubuntu-latest'}}
+        uses: codecov/codecov-action@v4
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+        with:
+          files: ./coverage.xml
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: true

caskade-0.0.1/.gitignore

@@ -0,0 +1,162 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

caskade-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Connor Stone, PhD
+
+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.

caskade-0.0.1/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.3
+Name: caskade
+Version: 0.0.1
+Summary: Package for building scientific simulators, with dynamic arguments arranged in a directed acyclic graph.
+Project-URL: Homepage, https://github.com/ConnorStoneAstro/caskade
+Project-URL: Documentation, https://github.com/ConnorStoneAstro/caskade
+Project-URL: Repository, https://github.com/ConnorStoneAstro/caskade
+Project-URL: Issues, https://github.com/ConnorStoneAstro/caskade/issues
+Author-email: Connor Stone <connorstone628@gmail.com>, Alexandre Adam <alexandre.adam@mila.quebec>
+License: MIT License
+        
+        Copyright (c) 2024 Connor Stone, PhD
+        
+        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.
+License-File: LICENSE
+Keywords: DAG,caskade,differentiable programming,pytorch,scientific python
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: torch
+Provides-Extra: dev
+Requires-Dist: pre-commit<4,>=3.6; extra == 'dev'
+Requires-Dist: pytest-cov<5,>=4.1; extra == 'dev'
+Requires-Dist: pytest-mock<4,>=3.12; extra == 'dev'
+Requires-Dist: pytest<9,>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# caskade
+
+Build scientific simulators, treating them as a directed acyclic graph. Handles
+argument passing for complex nested simulators.
+
+## Install
+
+``` bash
+pip install caskade
+```
+
+## Usage
+
+Make a `Module` object which may have some `Param`s. Define a `forward` method
+using the decorator.
+
+``` python
+from caskade import Module, Param, forward
+
+class MySim(Module):
+    def __init__(self, a, b=None):
+        super().__init__()
+        self.a = a
+        self.b = Param("b", b)
+
+    @forward
+    def myfun(self, x, b=None):
+        return x + self.a + b
+```
+
+We may now create instances of the simulator and pass the dynamic parameters.
+
+``` python
+import torch
+
+sim = MySim(1.0)
+
+params = [torch.tensor(2.0)]
+
+print(sim.myfun(3.0, params=params))
+```
+
+Which will print `6` by automatically filling `b` with the value from `params`.
+
+### Why do this?
+
+The above example is not very impressive, the real power comes from the fact
+that `Module` objects can be nested arbitrarily making a much more complicated
+analysis graph. Further, the `Param` objects can be linked or have other complex
+relationships. All of the complexity of the nested structure and argument
+passing is abstracted away so that at the top one need only pass a list of
+tensors for each parameter, a single large 1d tensor, or a dictionary with the
+same structure as the graph.

caskade-0.0.1/README.md

@@ -0,0 +1,53 @@
+# caskade
+
+Build scientific simulators, treating them as a directed acyclic graph. Handles
+argument passing for complex nested simulators.
+
+## Install
+
+``` bash
+pip install caskade
+```
+
+## Usage
+
+Make a `Module` object which may have some `Param`s. Define a `forward` method
+using the decorator.
+
+``` python
+from caskade import Module, Param, forward
+
+class MySim(Module):
+    def __init__(self, a, b=None):
+        super().__init__()
+        self.a = a
+        self.b = Param("b", b)
+
+    @forward
+    def myfun(self, x, b=None):
+        return x + self.a + b
+```
+
+We may now create instances of the simulator and pass the dynamic parameters.
+
+``` python
+import torch
+
+sim = MySim(1.0)
+
+params = [torch.tensor(2.0)]
+
+print(sim.myfun(3.0, params=params))
+```
+
+Which will print `6` by automatically filling `b` with the value from `params`.
+
+### Why do this?
+
+The above example is not very impressive, the real power comes from the fact
+that `Module` objects can be nested arbitrarily making a much more complicated
+analysis graph. Further, the `Param` objects can be linked or have other complex
+relationships. All of the complexity of the nested structure and argument
+passing is abstracted away so that at the top one need only pass a list of
+tensors for each parameter, a single large 1d tensor, or a dictionary with the
+same structure as the graph.

caskade-0.0.1/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling", "hatch-requirements-txt", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "caskade"
+dynamic = [
+        "dependencies",
+        "version"
+]
+authors = [
+  { name="Connor Stone", email="connorstone628@gmail.com" },
+  { name="Alexandre Adam", email="alexandre.adam@mila.quebec" },
+]
+description = "Package for building scientific simulators, with dynamic arguments arranged in a directed acyclic graph."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {file = "LICENSE"}
+keywords = [
+        "caskade",
+        "DAG",
+        "scientific python",
+        "differentiable programming",
+        "pytorch"
+]
+classifiers=[
+        "Development Status :: 1 - Planning",
+        "Intended Audience :: Science/Research",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3"
+]
+
+[project.urls]
+Homepage = "https://github.com/ConnorStoneAstro/caskade"
+Documentation = "https://github.com/ConnorStoneAstro/caskade"
+Repository = "https://github.com/ConnorStoneAstro/caskade"
+Issues = "https://github.com/ConnorStoneAstro/caskade/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0,<9",
+    "pytest-cov>=4.1,<5",
+    "pytest-mock>=3.12,<4",
+    "pre-commit>=3.6,<4",
+]
+
+[tool.hatch.metadata.hooks.requirements_txt]
+files = ["requirements.txt"]
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/caskade/_version.py"
+
+[tool.hatch.version.raw-options]
+local_scheme = "no-local-version"
+
+[tool.ruff]
+line-length = 100
+
+[tool.pytest.ini_options]
+norecursedirs = "tests/utils"

caskade-0.0.1/requirements.txt

@@ -0,0 +1 @@
+torch

caskade-0.0.1/src/caskade/__init__.py

@@ -0,0 +1,14 @@
+from ._version import version as VERSION  # noqa
+
+from .base import Node
+from .context import ActiveContext
+from .decorators import forward
+from .module import Module
+from .param import Param, LiveParam
+from .tests import test
+
+
+__version__ = VERSION
+__author__ = "Connor and Alexandre"
+
+__all__ = ("Node", "Module", "Param", "LiveParam", "ActiveContext", "forward")

caskade-0.0.1/src/caskade/_version.py

@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.0.1'
+__version_tuple__ = version_tuple = (0, 0, 1)

caskade-0.0.1/src/caskade/base.py

@@ -0,0 +1,132 @@
+from typing import Optional
+
+import torch
+
+
+class Node:
+    """
+    Base graph node class for caskade objects.
+
+    The `Node` object is the base class for all caskade objects. It is used to
+    construct the directed acyclic graph (DAG). The primary function of the
+    `Node` object is to manage the parent-child relationships between nodes in
+    the graph. There is limited functionality for the `Node` object, though it
+    implements the base versions of the `active` state and `to` /
+    `update_dynamic_params` methods. The `active` state is used to communicate
+    through the graph that the simulator is currently running. The `to` method
+    is used to move and/or cast the values of the parameter. The
+    `update_dynamic_params` method is used by `Module` objects to keep track of
+    all dynamic `Param` objects below them in the graph.
+
+    Examples
+    --------
+    ``` python
+    n1 = Node("node1")
+    n2 = Node("node2")
+    n1.link("subnode", n2) # link n2 as a child of n1, may use any str as the key
+    n1.unlink("subnode") # alternately n1.unlink(n2) to unlink by object
+    """
+
+    def __init__(self, name):
+        assert isinstance(name, str), f"{self.__class__.__name__} name must be a string"
+        assert "|" not in name, f"{self.__class__.__name__} cannot contain '|'"
+        self._name = name
+        self._children = {}
+        self._parents = set()
+        self._active = False
+        self._type = "node"
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def children(self) -> dict:
+        return self._children
+
+    @property
+    def parents(self) -> set:
+        return self._parents
+
+    def link(self, key, child):
+        # Avoid double linking to the same object
+        if key in self.children:
+            raise ValueError(f"Child key {key} already linked to parent {self.name}")
+        for ownchild in self.children.values():
+            if ownchild == child:
+                raise ValueError(f"Child {child.name} already linked to parent {self.name}")
+
+        self._children[key] = child
+        child._parents.add(self)
+        self.update_dynamic_params()
+
+    def unlink(self, key):
+        if isinstance(key, Node):
+            for node in self.children:
+                if self.children[node] == key:
+                    key = node
+                    break
+        self._children[key]._parents.remove(self)
+        self._children[key].update_dynamic_params()
+        del self._children[key]
+        self.update_dynamic_params()
+
+    def topological_ordering(self, with_type=None) -> tuple:
+        ordering = [self]
+        for node in self.children.values():
+            for subnode in node.topological_ordering():
+                if subnode not in ordering:
+                    ordering.append(subnode)
+        if with_type is None:
+            return tuple(ordering)
+        return tuple(filter(lambda n: n._type == with_type, ordering))
+
+    def update_dynamic_params(self):
+        for parent in self.parents:
+            parent.update_dynamic_params()
+
+    @property
+    def active(self) -> bool:
+        return self._active
+
+    @active.setter
+    def active(self, value):
+        # Avoid unnecessary updates
+        if self._active == value:
+            return
+
+        # Set self active level
+        self._active = value
+
+        # Propagate active level to children
+        for child in self._children.values():
+            child.active = value
+
+    def to(self, device: Optional[torch.device] = None, dtype: Optional[torch.dtype] = None):
+        """
+        Moves and/or casts the PyTorch values of the Node.
+
+        Parameters
+        ----------
+        device: (Optional[torch.device], optional)
+            The device to move the values to. Defaults to None.
+        dtype: (Optional[torch.dtype], optional)
+            The desired data type. Defaults to None.
+        """
+
+        for child in self.children.values():
+            child.to(device=device, dtype=dtype)
+
+    def graph_dict(self) -> dict:
+        graph = {
+            f"{self.name}|{self._type}": {},
+        }
+        for node in self.children.values():
+            graph[f"{self.name}|{self._type}"].update(node.graph_dict())
+        return graph
+
+    def __str__(self) -> str:
+        return str(self.graph_dict())
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.name})"

caskade-0.0.1/src/caskade/context.py

@@ -0,0 +1,21 @@
+from typing import Union, Mapping, Sequence
+
+from torch import Tensor
+
+from .module import Module
+
+
+class ActiveContext:
+    def __init__(
+        self, module: Module, params: Union[Sequence[Tensor], Mapping[str, Tensor], Tensor]
+    ):
+        self.module = module
+        self.params = params
+
+    def __enter__(self):
+        self.module.active = True
+        self.module.fill_params(self.params)
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.module.clear_params()
+        self.module.active = False

caskade-0.0.1/src/caskade/decorators.py

@@ -0,0 +1,50 @@
+import inspect
+import functools
+
+from .context import ActiveContext
+
+
+def forward(method):
+    """
+    Decorator to define a forward method for a module.
+
+    Parameters
+    ----------
+    method: (Callable)
+        The forward method to be decorated.
+
+    Returns
+    -------
+    Callable
+        The decorated forward method.
+    """
+
+    # Get kwargs from function signature
+    method_kwargs = []
+    for arg in inspect.signature(method).parameters.values():
+        if arg.default is not arg.empty:
+            method_kwargs.append(arg.name)
+
+    @functools.wraps(method)
+    def wrapped(self, *args, **kwargs):
+        if self.active:
+            kwargs.update(self.fill_kwargs(method_kwargs))
+            return method(self, *args, **kwargs)
+
+        # Extract params from the arguments
+        if len(self.dynamic_params) == 0:
+            params = {}
+        elif "params" in kwargs:
+            params = kwargs.pop("params")
+        elif args:
+            params = args.pop(0)
+        else:
+            raise ValueError(
+                f"Params must be provided for dynamic modules. Expected {len(self.dynamic_params)} params."
+            )
+
+        with ActiveContext(self, params):
+            kwargs.update(self.fill_kwargs(method_kwargs))
+            return method(self, *args, **kwargs)
+
+    return wrapped

caskade-0.0.1/src/caskade/module.py

@@ -0,0 +1,99 @@
+from typing import Sequence, Mapping
+
+from torch import Tensor
+
+from .base import Node
+from .param import Param, LiveParam
+
+
+class Module(Node):
+
+    def __init__(self, name):
+        super().__init__(name=name)
+        self.dynamic_params = ()
+        self.live_params = ()
+        self._type = "module"
+        self._batch = False
+
+    @property
+    def batch(self) -> bool:
+        return self._batch
+
+    @batch.setter
+    def batch(self, value):
+        assert isinstance(value, bool)
+        self._batch = value
+
+    def update_dynamic_params(self):
+        super().update_dynamic_params()
+        self.dynamic_params = tuple(self.topological_ordering("dynamic"))
+        self.live_params = tuple(self.topological_ordering("live"))
+
+    def fill_params(self, params):
+        assert self.active, "Module must be active to fill params"
+
+        if isinstance(params, Tensor):
+            if self.batch:
+                B = params.shape[0]
+            pos = 0
+            for param in self.dynamic_params:
+                try:
+                    size = param.shape.numel()
+                except AttributeError:
+                    raise ValueError(
+                        f"Param {param.name} has no shape. dynamic parameters must have a shape to use Tensor input."
+                    )
+                if self.batch:
+                    param.value = params[:, pos : pos + size].view((B,) + param.shape)
+                    pos += size * B
+                else:
+                    param.value = params[pos : pos + size].view(param.shape)
+                    pos += size
+        elif isinstance(params, Sequence):
+            if len(params) == len(self.dynamic_params):
+                for param, value in zip(self.dynamic_params, params):
+                    param.value = value
+            else:
+                raise ValueError(
+                    f"Input params length ({len(params)}) does not match dynamic params length ({len(self.dynamic_params)})"
+                )
+        elif isinstance(params, Mapping):
+            for key in params:
+                if key in self.children:
+                    if isinstance(self.children[key], Param):
+                        self.children[key].value = params[key]
+                    elif isinstance(self.children[key], Module):
+                        self.children[key].fill_params(params[key])
+                    else:
+                        raise ValueError(f"Key {key} type {type(self.children[key])} not supported")
+                else:
+                    raise ValueError(f"Key {key} not found in {self.name} children")
+        else:
+            raise ValueError(
+                f"Input params type {type(params)} not supported. Should be Tensor, Sequence or Mapping."
+            )
+
+    def clear_params(self):
+        assert self.active, "Module must be active to clear params"
+
+        for param in self.dynamic_params:
+            param.value = None
+
+        for param in self.live_params:
+            param.value = LiveParam
+
+    def fill_kwargs(self, keys) -> dict[str, Tensor]:
+        return {key: getattr(self, key).value for key in keys}
+
+    def __setattr__(self, key, value):
+        try:
+            if key in self.children and isinstance(self.children[key], Param):
+                self.children[key].value = value
+                return
+            if isinstance(value, Node):
+                self.link(key, value)
+                self.update_dynamic_params()
+
+            super().__setattr__(key, value)
+        except AttributeError:
+            super().__setattr__(key, value)

caskade-0.0.1/src/caskade/param.py

@@ -0,0 +1,147 @@
+from typing import Optional, Union, Callable
+
+import torch
+from torch import Tensor
+
+from .base import Node
+
+__all__ = ("Param", "LiveParam")
+
+
+class LiveParamBase:
+    """Placeholder to identify a parameter as live updating. Like `None` there
+    exists only one instance of this class."""
+
+    pass
+
+
+LiveParam = LiveParamBase()
+
+
+class Param(Node):
+    """
+    Node to represent a parameter in the graph.
+
+    The `Param` object is used to represent a parameter in the graph. During
+    runtime this will represent a tensor value which can be used in various
+    calculations. The `Param` object can be set to a constant value (`value`);
+    `None` meaning the value is to be provided at runtime (`dynamic`);
+    `LiveParam` meaning the value will be computed internally in the simulator
+    during runtime (`live`); another `Param` object meaning it will take on that
+    value at runtime (`pointer`); or a function of other `Param` objects to be
+    computed at runtime (`function`). These options allow users to flexibly set
+    the behavior of the simulator.
+
+    Examples
+    --------
+    ``` python
+    p1 = Param("test", (1.0, 2.0)) # constant value, length 2 vector
+    p2 = Param("test", None, (2,2)) # dynamic 2x2 matrix value
+    p3 = Param("test", LiveParam) # live updating value
+    p4 = Param("test", p1) # pointer to another parameter
+    p5 = Param("test", lambda p: p.children["other"].value * 2) # function of another parameter
+    p5.link("other", p2) # link the other parameter needed for the function
+    ```
+
+    Parameters
+    ----------
+    name: (str)
+        The name of the parameter.
+    value: (Optional[Union[Tensor, float, int]], optional)
+        The value of the parameter. Defaults to None meaning dynamic.
+    shape: (Optional[tuple[int, ...]], optional)
+        The shape of the parameter. Defaults to () meaning scalar.
+    """
+
+    def __init__(
+        self,
+        name,
+        value: Optional[Union[Tensor, float, int]] = None,
+        shape: Optional[tuple[int, ...]] = (),
+    ):
+        super().__init__(name=name)
+        if value is None:
+            if shape is None:
+                raise ValueError("Either value or shape must be provided")
+            if not isinstance(shape, tuple):
+                raise ValueError("Shape must be a tuple")
+            self.shape = shape
+        elif not isinstance(value, (Param, Callable, LiveParamBase)):
+            value = torch.as_tensor(value)
+            assert (
+                shape == () or shape == value.shape
+            ), f"Shape {shape} does not match value shape {value.shape}"
+        self.value = value
+
+    @property
+    def dynamic(self) -> bool:
+        return self._type == "dynamic"
+
+    @property
+    def live(self) -> bool:
+        return self._type == "live"
+
+    @property
+    def shape(self) -> tuple:
+        return self._shape
+
+    @shape.setter
+    def shape(self, shape):
+        if self._type in ["pointer", "function"]:
+            raise RuntimeError("Cannot set shape of parameter with type 'pointer' or 'function'")
+        self._shape = shape
+
+    @property
+    def value(self) -> Union[Tensor, None]:
+        if self._type == "pointer":
+            return self._value.value
+        if self._type == "function":
+            return self._value(self)
+        return self._value
+
+    @value.setter
+    def value(self, value):
+        # While active, update silently
+        if self.active:
+            if self.dynamic or self.live:
+                self._value = value
+                return
+            raise RuntimeError(f"Cannot set value of non-live parameter {self.name} while active")
+
+        # unlink if pointer to avoid floating references
+        if self._type == "pointer":
+            self.unlink(self._value)
+
+        if value is None:
+            self._type = "dynamic"
+        elif isinstance(value, LiveParamBase):
+            self._type = "live"
+        elif isinstance(value, Param):
+            self._type = "pointer"
+            self.link(value.name, value)
+            self._shape = None
+        elif callable(value):
+            self._type = "function"
+            self._shape = None
+        else:
+            self._type = "value"
+            value = torch.as_tensor(value)
+            self.shape = value.shape
+
+        self._value = value
+        self.update_dynamic_params()
+
+    def to(self, device: Optional[torch.device] = None, dtype: Optional[torch.dtype] = None):
+        """
+        Moves and/or casts the values of the parameter.
+
+        Parameters
+        ----------
+        device: (Optional[torch.device], optional)
+            The device to move the values to. Defaults to None.
+        dtype: (Optional[torch.dtype], optional)
+            The desired data type. Defaults to None.
+        """
+        super().to(device=device, dtype=dtype)
+        if self._type == "value":
+            self._value = self._value.to(device=device, dtype=dtype)

caskade-0.0.1/src/caskade/tests.py

@@ -0,0 +1,47 @@
+import torch
+
+from caskade import Module, Param, forward, LiveParam
+
+__all__ = ("test",)
+
+
+def _test_full_integration():
+
+    class TestSim(Module):
+        def __init__(self, a, b, c, c_shape, m1):
+            super().__init__("test_sim")
+            self.a = a
+            self.b = Param("b", b)
+            self.c = Param("c", c, c_shape)
+            self.m1 = m1
+
+        @forward
+        def testfun(self, x, b=None):
+            self.c.value = b + x
+            y = self.m1()
+            return x + self.a + b + y
+
+    class TestSubSim(Module):
+        def __init__(self, d, e, f):
+            super().__init__("test_sub_sim")
+            self.d = Param("d", d)
+            self.e = Param("e", e)
+            self.f = Param("f", f)
+
+        @forward
+        def __call__(self, d=None, e=None, f=None):
+            return d + e + f
+
+    sub1 = TestSubSim(d=1.0, e=lambda s: s.children["flink"].value, f=None)
+    sub1.e.link("flink", sub1.f)
+    main1 = TestSim(a=2.0, b=None, c=LiveParam, c_shape=(), m1=sub1)
+    sub1.f = main1.c
+
+    b_value = torch.tensor(3.0)
+    res = main1.testfun(1.0, params=[b_value])
+    assert res.item() == 15.0
+
+
+def test():
+    _test_full_integration()
+    print("Success!")

caskade-0.0.1/tests/test_base.py

@@ -0,0 +1,105 @@
+from caskade import Node
+
+import pytest
+
+
+def test_creation():
+    node = Node("test")
+    assert node._name == "test"
+    assert node._children == {}
+    assert node._parents == set()
+    assert node._active == False
+    assert node._type == "node"
+
+    with pytest.raises(AttributeError):
+        node.name = "newname"
+
+
+def test_link():
+    node1 = Node("node1")
+    node2 = Node("node2")
+    node1.link("subnode", node2)
+
+    assert "subnode" in node1._children
+    assert node1._children["subnode"] == node2
+    assert node1._parents == set()
+    assert node2._parents == set([node1])
+
+    str(node1)
+    repr(node1)
+
+    node1.unlink(node2)
+    assert "subnode" not in node1._children
+    assert node2._parents == set()
+    assert node1._parents == set()
+
+
+def test_topological_ordering():
+    node1 = Node("node1")
+    node2 = Node("node2")
+    node3 = Node("node3")
+    node4 = Node("node4")
+    node5 = Node("node5")
+    node6 = Node("node6")
+
+    node1.link("subnode1", node2)
+    node1.link("subnode2", node3)
+    node2.link("subnode3", node4)
+    node2.link("subnode4", node5)
+    node3.link("subnode5", node6)
+
+    ordering = node1.topological_ordering()
+    assert ordering == (node1, node2, node4, node5, node3, node6)
+
+    ordering = node1.topological_ordering(with_type="node")
+    assert ordering == (node1, node2, node4, node5, node3, node6)
+
+    ordering = node1.topological_ordering(with_type="dynamic")
+    assert ordering == ()
+
+    node1.unlink("subnode1")
+    ordering = node1.topological_ordering()
+    assert ordering == (node1, node3, node6)
+
+    node1.unlink("subnode2")
+    ordering = node1.topological_ordering()
+    assert ordering == (node1,)
+
+
+def test_active():
+    node1 = Node("node1")
+    node2 = Node("node2")
+    node3 = Node("node3")
+    node4 = Node("node4")
+    node5 = Node("node5")
+    node6 = Node("node6")
+
+    node1.link("subnode1", node2)
+    node1.link("subnode2", node3)
+    node2.link("subnode3", node4)
+    node2.link("subnode4", node5)
+    node3.link("subnode5", node6)
+
+    node1.active = True
+    assert node1.active == True
+    assert node2.active == True
+    assert node3.active == True
+    assert node4.active == True
+    assert node5.active == True
+    assert node6.active == True
+
+    node2.active = False
+    assert node1.active == True
+    assert node2.active == False
+    assert node3.active == True
+    assert node4.active == False
+    assert node5.active == False
+    assert node6.active == True
+
+    node1.active = False
+    assert node1.active == False
+    assert node2.active == False
+    assert node3.active == False
+    assert node4.active == False
+    assert node5.active == False
+    assert node6.active == False

caskade-0.0.1/tests/test_integration.py

@@ -0,0 +1,40 @@
+import torch
+
+from caskade import Module, Param, forward, LiveParam
+
+
+def test_full_integration():
+
+    class TestSim(Module):
+        def __init__(self, a, b, c, c_shape, m1):
+            super().__init__("test_sim")
+            self.a = a
+            self.b = Param("b", b)
+            self.c = Param("c", c, c_shape)
+            self.m1 = m1
+
+        @forward
+        def testfun(self, x, b=None):
+            self.c.value = b + x
+            y = self.m1()
+            return x + self.a + b + y
+
+    class TestSubSim(Module):
+        def __init__(self, d, e, f):
+            super().__init__("test_sub_sim")
+            self.d = Param("d", d)
+            self.e = Param("e", e)
+            self.f = Param("f", f)
+
+        @forward
+        def __call__(self, d=None, e=None, f=None):
+            return d + e + f
+
+    sub1 = TestSubSim(d=1.0, e=lambda s: s.children["flink"].value, f=None)
+    sub1.e.link("flink", sub1.f)
+    main1 = TestSim(a=2.0, b=None, c=LiveParam, c_shape=(), m1=sub1)
+    sub1.f = main1.c
+
+    b_value = torch.tensor(3.0)
+    res = main1.testfun(1.0, params=[b_value])
+    assert res.item() == 15.0

caskade-0.0.1/tests/test_module.py

@@ -0,0 +1 @@
+from caskade import Module

caskade-0.0.1/tests/test_param.py

@@ -0,0 +1,71 @@
+import pytest
+import torch
+
+from caskade import Param, LiveParam
+
+
+def test_live_param():
+    lp1 = LiveParam
+    lp2 = LiveParam
+
+    assert lp1 is lp2, "LiveParam is not a singleton"
+
+
+def test_param_creation():
+
+    p1 = Param("test")
+    assert p1.name == "test"
+    assert p1.dynamic
+    assert not p1.live
+    assert p1.value is None
+
+    p2 = Param("test", 1.0)
+    assert p2.name == "test"
+    assert p2.value.item() == 1.0
+    p3 = Param("test", torch.ones((1, 2, 3)))
+    with pytest.raises(RuntimeError):
+        p3.active = True
+        p3.value = 1.0
+
+    with pytest.raises(AssertionError):
+        p4 = Param("test", 1.0, shape=(1, 2, 3))
+
+    p5 = Param("test", p3)
+    with pytest.raises(RuntimeError):
+        p5.shape = (1, 2, 3)
+
+    p6 = Param("test", lambda p: p.children["other"].value * 2)
+    p6.link("other", p2)
+    with pytest.raises(RuntimeError):
+        p6.shape = (1, 2, 3)
+
+
+def test_value_setter():
+
+    # dynamic
+    p = Param("test")
+    assert p._type == "dynamic"
+
+    # value
+    p.value = 1.0
+    assert p._type == "value"
+    assert p.value.item() == 1.0
+
+    p = Param("testshape", shape=(2,))
+    p.value = [1.0, 2.0]
+
+    # pointer
+    other = Param("testother", 2.0)
+    p.value = other
+    assert p._type == "pointer"
+    assert p.shape is None
+
+    # function
+    p.value = lambda p: p.children["other"].value * 2
+    p.link("other", other)
+    assert p._type == "function"
+    assert p.value.item() == 4.0
+
+    # live
+    p.value = LiveParam
+    assert p._type == "live"