From 09751b959bb129e33d9f2176b55c7ecfa32c90b9 Mon Sep 17 00:00:00 2001 From: Cambridge Yang Date: Sun, 24 May 2026 13:10:37 -0400 Subject: [PATCH 1/3] docs: nest API symbols under section headers (heading_level 3) api.md section headers are ## (h2); mkdocstrings was rendering symbols at heading_level 2, making them siblings of the sections instead of children, so the TOC was flat. Bump to heading_level 3 -> symbols are h3 under each h2 section, members h4 under their class. --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 4098da7..ee5aa47 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -57,7 +57,7 @@ plugins: filters: ["!^_"] # hide private / dunder members show_source: false summary: true - heading_level: 2 + heading_level: 3 # section headers are ## (h2); symbols nest as h3 # Emits /llms.txt (an index for LLMs/agents, per llmstxt.org) plus a single # concatenated llms-full.txt of the whole site. - llmstxt: From 5ec815cba69ce5d89b8b1d64c08371f43ec65a2f Mon Sep 17 00:00:00 2001 From: Cambridge Yang Date: Sun, 24 May 2026 13:12:14 -0400 Subject: [PATCH 2/3] docs: clarify compile_model backends; ils_* only used by method=integral MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - method: document the real keyword set (auto/bell/single_layer/integral). The numerical inverse-Laplace path keys on "integral" (compile.py:174), not "nested" as the docstring claimed — passing "nested" at depth<=1 silently falls through to single_layer. - ils_method / ils_params: state explicitly they are used ONLY by method="integral" and ignored by the bell and single_layer backends (which assemble the density analytically). --- acopula/compile.py | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/acopula/compile.py b/acopula/compile.py index dc8722b..80e659a 100644 --- a/acopula/compile.py +++ b/acopula/compile.py @@ -366,12 +366,17 @@ def compile_model( ``model_fn`` expects. Values are used only to drive oryx's tracer; pass any sensible defaults (e.g. ``{"theta": 1.0}``). - method: Density evaluation backend. ``"bell"`` uses the - polynomial-powering scan (recommended for nested >= 2 - levels), ``"single_layer"`` is the closed-form unnested - formula, ``"nested"`` falls back to numerical integration - via the implicit-LST solver. ``"auto"`` picks ``"bell"`` - for depth > 1 else ``"single_layer"``. + method: Density-evaluation backend: + + - ``"auto"`` (default): ``"bell"`` for depth > 1, else + ``"single_layer"``. + - ``"bell"``: polynomial-powering scan (recommended for + nested copulas; the only backend that supports + ``with_censored_mask``). + - ``"single_layer"``: closed-form unnested formula (flat + copulas only). + - ``"integral"``: numerical inverse-Laplace integration — + the only backend that uses ``ils_method`` / ``ils_params``. survival: Treat marginals as survival functions ``S(t) = 1 - F(t)`` rather than CDFs. Required for the HACSurv-style joint survival likelihood. @@ -379,8 +384,13 @@ def compile_model( third ``censored_mask`` argument so callers can ``vmap`` per-observation masks. Forces ``method="bell"`` since the other backends do not support dynamic censoring. - ils_method: Implicit-LST solver for ``method="nested"``. - ils_params: Extra params for the implicit solver. + ils_method: Inverse-Laplace solver used **only** by + ``method="integral"`` — e.g. ``"cohen"`` (default), + ``"euler"``, ``"post_widder"``. **Ignored by ``"bell"`` and + ``"single_layer"``**, which assemble the density analytically + and never invert a Laplace transform. + ils_params: Extra params for that solver; likewise **only used by + ``method="integral"``** and ignored by the other backends. Returns: A :class:`CompiledModel` holding the frozen graph, flattener, From 8f970622a5cb98472b9d58dae7be0dcc6794b38d Mon Sep 17 00:00:00 2001 From: Cambridge Yang Date: Sun, 24 May 2026 13:15:15 -0400 Subject: [PATCH 3/3] docs: fix @copula docstring rendering (fenced Examples block) The decorator docstring used a 'Usage:' section (not a Google section) with an unfenced indented code block, so mkdocstrings parsed it as Markdown and the Python comment '# Can instantiate...' rendered as a stray heading. Switch to a recognized 'Examples:' section with a fenced ```python block; the code now renders as code and the bogus heading is gone. --- acopula/core.py | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/acopula/core.py b/acopula/core.py index cbed27c..eab203e 100644 --- a/acopula/core.py +++ b/acopula/core.py @@ -151,25 +151,26 @@ def __call__(self, children: Iterable[Union["Node", "Leaf", jax.Array]]) -> "Nod def copula(cls): - """Decorator to create a copula class with dataclass-like syntax. + """Class decorator for defining a copula family with dataclass-style + parameters. - Usage: + Generates an ``__init__`` from the type-annotated class attributes, + makes the class inherit from `Copula`, and registers the parameters — + while preserving every user-defined method. Instances accept positional + or keyword arguments. + + Examples: + ```python @copula class Clayton: theta: float - def generator(self, u: jax.Array) -> jax.Array: + def generator(self, u): return (1.0 + u) ** (-1.0 / self.theta) - # Can instantiate with positional or keyword arguments - c1 = Clayton(2.0) - c2 = Clayton(theta=2.0) - - This automatically: - - Makes the class inherit from Copula - - Generates an __init__ method from type annotations - - Preserves all user-defined methods - - Handles parameter registration + c1 = Clayton(2.0) # positional + c2 = Clayton(theta=2.0) # keyword + ``` """ # Get type annotations in definition order annotations = getattr(cls, "__annotations__", {})