Dev

.gitignore

@@ -165,4 +165,6 @@ cython_debug/
 # HDF5 files
 **.h5
 
-**settings.json
+**settings.json
+test_graph
+test_graph_dict

docs/source/_toc.yml

@@ -12,6 +12,18 @@ chapters:
   - file: contributing
   - file: license
   - file: modules
+    sections:
+      - file: api/module
+      - file: api/param
+      - file: api/decorators
+      - file: api/context
+      - file: api/collections
+      - file: api/memo
+      - file: api/exceptions
+      - file: api/warnings
+      - file: api/utilities
+      - file: api/node
+      - file: api/backend
   # - file: frequently_asked_questions
   # - file: citation
   # - file: glossary

docs/source/api/backend.rst

@@ -0,0 +1,7 @@
+Backend
+=======
+
+.. autoclass:: caskade.backend.Backend
+   :members:
+
+.. autodata:: caskade.backend.backend

docs/source/api/collections.rst

@@ -0,0 +1,14 @@
+Collections
+===========
+
+.. autoclass:: caskade.NodeCollection
+   :members:
+   :show-inheritance:
+
+.. autoclass:: caskade.NodeList
+   :members:
+   :show-inheritance:
+
+.. autoclass:: caskade.NodeTuple
+   :members:
+   :show-inheritance:

docs/source/api/context.rst

@@ -0,0 +1,11 @@
+Context Managers
+================
+
+.. autoclass:: caskade.ActiveContext
+   :members:
+
+.. autoclass:: caskade.ValidContext
+   :members:
+
+.. autoclass:: caskade.OverrideParam
+   :members:

docs/source/api/decorators.rst

@@ -0,0 +1,8 @@
+Decorators
+==========
+
+.. autofunction:: caskade.forward
+
+.. autoclass:: caskade.active_cache
+   :members:
+   :show-inheritance:

docs/source/api/exceptions.rst

@@ -0,0 +1,38 @@
+Exceptions
+==========
+
+.. autoclass:: caskade.CaskadeException
+   :show-inheritance:
+
+.. autoclass:: caskade.GraphError
+   :show-inheritance:
+
+.. autoclass:: caskade.BackendError
+   :show-inheritance:
+
+.. autoclass:: caskade.LinkToAttributeError
+   :show-inheritance:
+
+.. autoclass:: caskade.NodeConfigurationError
+   :show-inheritance:
+
+.. autoclass:: caskade.ParamConfigurationError
+   :show-inheritance:
+
+.. autoclass:: caskade.ParamTypeError
+   :show-inheritance:
+
+.. autoclass:: caskade.ActiveStateError
+   :show-inheritance:
+
+.. autoclass:: caskade.FillParamsError
+   :show-inheritance:
+
+.. autoclass:: caskade.FillParamsArrayError
+   :show-inheritance:
+
+.. autoclass:: caskade.FillParamsSequenceError
+   :show-inheritance:
+
+.. autoclass:: caskade.FillParamsMappingError
+   :show-inheritance:

docs/source/api/memo.rst

@@ -0,0 +1,5 @@
+Graph Communication
+===================
+
+.. autoclass:: caskade.Memo
+   :members:

docs/source/api/module.rst

@@ -0,0 +1,6 @@
+Module
+======
+
+.. autoclass:: caskade.Module
+   :members:
+   :show-inheritance:

docs/source/api/node.rst

@@ -0,0 +1,6 @@
+Node
+====
+
+.. autoclass:: caskade.Node
+   :members:
+   :show-inheritance:

docs/source/api/param.rst

@@ -0,0 +1,6 @@
+Param
+=====
+
+.. autoclass:: caskade.Param
+   :members:
+   :show-inheritance:

docs/source/api/utilities.rst

@@ -0,0 +1,7 @@
+Utilities & Testing
+===================
+
+.. automodule:: caskade.utils
+   :members:
+
+.. autofunction:: caskade.test

docs/source/api/warnings.rst

@@ -0,0 +1,11 @@
+Warnings
+========
+
+.. autoclass:: caskade.CaskadeWarning
+   :show-inheritance:
+
+.. autoclass:: caskade.InvalidValueWarning
+   :show-inheritance:
+
+.. autoclass:: caskade.SaveStateWarning
+   :show-inheritance:

docs/source/modules.rst

@@ -1,9 +1,5 @@
-caskade docstrings
-==================
+API Reference
+=============
 
-Someday I'll make a nicely formatted interface to all this, but for now, here's
-a list of all the modules and their functions. You can just search for what you
-need here and get more detailed information.
-
-.. automodule:: caskade
-    :members:
+This section documents the public API of ``caskade``. Browse the pages
+below for detailed class and function documentation.

docs/source/notebooks/AdvancedGuide.ipynb

@@ -702,6 +702,90 @@
     "Note that the groups will automatically order themselves by sorting the group integers, so you can easily pick where each group goes in the params. You can even place groups ahead of group 0 by using negative integers."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Node Collections: `NodeList`, `NodeTuple`, and `NodeDict`\n",
+    "\n",
+    "Sometimes you want to group a subset of nodes together without wrapping them inside a new `Module`. `caskade` provides three lightweight collection types for this purpose:\n",
+    "\n",
+    "- **`NodeList`** – a mutable, ordered list of nodes (supports `append`, `insert`, `pop`, etc.)\n",
+    "- **`NodeTuple`** – an immutable, ordered tuple of nodes\n",
+    "- **`NodeDict`** – a mutable mapping of `str → node`, with attribute-style access\n",
+    "\n",
+    "All three behave like their built-in Python counterparts while also being `Node` objects themselves, so they participate fully in the caskade graph.\n",
+    "\n",
+    "When you assign a plain Python `list`, `tuple`, or `dict` of nodes as an attribute of a `Module`, `caskade` automatically converts it to the appropriate collection type:\n",
+    "\n",
+    "```python\n",
+    "self.my_params = [p1, p2, p3]         # becomes NodeList\n",
+    "self.my_params = (p1, p2, p3)         # becomes NodeTuple\n",
+    "self.my_params = {'a': p1, 'b': p2}   # becomes NodeDict\n",
+    "```\n",
+    "\n",
+    "This means you never have to construct `NodeList` / `NodeTuple` / `NodeDict` explicitly inside a `Module` — just assign the plain collection and caskade handles the rest.\n",
+    "\n",
+    "### Use cases\n",
+    "\n",
+    "- **Gibbs-style sampling** – keep one `NodeList` of the parameters you currently want to sample (dynamic) and another for the parameters you want to hold fixed (static). Calling `.to_dynamic()` / `.to_static()` on the collection flips the whole subset at once.\n",
+    "- **Selective saving / updating** – build a `NodeDict` of the parameters you care about and call `get_values()` / `set_values()` on just that subset, without touching the rest of the graph.\n",
+    "- **Quick inspection** – group modules or params of interest into a collection and iterate over them for printing, plotting, or diagnostics without restructuring the model.\n",
+    "\n",
+    "Note that `set_values` and `get_values` also work on Node collections."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Collections can be constructed directly\n",
+    "G = Gaussian(\"G\", x0=5, y0=5, q=0.5, phi=0.0, sigma=1.0, I0=1.0)\n",
+    "\n",
+    "# NodeList: mutable, ordered\n",
+    "position_params = ck.NodeList([G.x0, G.y0])\n",
+    "print(\"NodeList:\", position_params)\n",
+    "\n",
+    "# NodeTuple: immutable, ordered\n",
+    "shape_params = ck.NodeTuple((G.q, G.phi, G.sigma))\n",
+    "print(\"NodeTuple:\", shape_params)\n",
+    "\n",
+    "# NodeDict: mutable, keyed\n",
+    "named_params = ck.NodeDict({\"x0\": G.x0, \"y0\": G.y0, \"sigma\": G.sigma})\n",
+    "print(\"NodeDict:\", named_params)\n",
+    "print(\"Attribute access:\", named_params[\"x0\"])  # same as named_params.x0"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Auto-conversion when assigned to a Module attribute\n",
+    "class GaussianWithCollections(ck.Module):\n",
+    "    def __init__(self, name, submod):\n",
+    "        super().__init__(name)\n",
+    "        self.g = submod\n",
+    "        # plain list/dict – caskade converts them automatically\n",
+    "        self.position = [submod.x0, submod.y0]  # -> NodeList\n",
+    "        self.named = {\"q\": submod.q, \"phi\": submod.phi}  # -> NodeDict\n",
+    "\n",
+    "    @ck.forward\n",
+    "    def __call__(self, x, y):\n",
+    "        return self.g(x, y)\n",
+    "\n",
+    "\n",
+    "G2 = Gaussian(\"G2\", x0=5, y0=5, q=0.5, phi=0.0, sigma=1.0, I0=1.0)\n",
+    "gc = GaussianWithCollections(\"gc\", G2)\n",
+    "print(type(gc.position))  # NodeList\n",
+    "print(type(gc.named))  # NodeDict\n",
+    "gc.position.to_dynamic()  # can call collection methods\n",
+    "display(gc.graphviz())"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

docs/source/notebooks/BeginnersGuide.ipynb

@@ -312,6 +312,42 @@
     "As you can see, a `pointer` parameter is represented in the graph as a shaded arrow. It will now return the same value as the `x0` parameter in `secondsim`."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "link_unlink_md",
+   "metadata": {},
+   "source": [
+    "### Linking and unlinking params\n",
+    "\n",
+    "Pointer parameters can be linked to and unlinked from other nodes. ",
+    "Use `link(node)` to connect a child node, and `unlink(node)` (or a key string) to disconnect a specific child. ",
+    "Calling `unlink()` with no arguments removes **all** children at once, acting as a convenient clear."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "link_unlink_code",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "time_param = ck.Param(\"mytime\")  # a standalone param to link against\n",
+    "shared_x0 = ck.Param(\"shared_x0\", shape=(2,))\n",
+    "\n",
+    "# Link a child node using a key or by passing the node directly\n",
+    "shared_x0.link(\"mytime\", time_param)\n",
+    "print(\"Children after link:\", list(shared_x0.children))\n",
+    "\n",
+    "# Unlink a specific child by key or node reference\n",
+    "shared_x0.unlink(\"mytime\")\n",
+    "print(\"Children after unlink(key):\", list(shared_x0.children))\n",
+    "\n",
+    "# Re-link and then clear all children at once\n",
+    "shared_x0.link(\"mytime\", time_param)\n",
+    "shared_x0.unlink()  # removes all children\n",
+    "print(\"Children after unlink():\", list(shared_x0.children))"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -568,4 +604,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 2
-}
+}

src/caskade/__init__.py

@@ -1,3 +1,22 @@
+"""
+caskade - Build scientific simulators as directed acyclic graphs.
+
+Caskade provides a framework for constructing modular scientific simulators
+by composing computational steps into a directed acyclic graph (DAG). It
+handles parameter management, caching, and context-dependent evaluation.
+
+Main Public API
+---------------
+Node : Base class for building computational graph nodes.
+Module : High-level container for assembling simulator components.
+Param : Declare and manage parameters within nodes.
+forward : Decorator to define the forward computation of a node.
+active_cache : Decorator for caching intermediate results.
+NodeCollection, NodeList, NodeTuple : Collections of nodes.
+ActiveContext, ValidContext, OverrideParam : Context managers for evaluation.
+backend : Array backend abstraction (NumPy, PyTorch, etc.).
+utils : Utility functions.
+"""
 from ._version import version as VERSION  # noqa
 
 from .base import Node, Memo
@@ -6,7 +25,7 @@
 from .decorators import forward, active_cache
 from .module import Module
 from .param import Param
-from .collection import NodeCollection, NodeList, NodeTuple
+from .collection import NodeCollection, NodeList, NodeTuple, NodeDict
 from .tests import test
 from .errors import (
     CaskadeException,
@@ -39,6 +58,7 @@
     "NodeCollection",
     "NodeList",
     "NodeTuple",
+    "NodeDict",
     "ActiveContext",
     "ValidContext",
     "OverrideParam",