multiple-integrate 2.0.0__tar.gz → 2.1.0__tar.gz

{multiple_integrate-2.0.0 → multiple_integrate-2.1.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: multiple-integrate
-Version: 2.0.0
+Version: 2.1.0
 Summary: Symbolic multiple integration for Python
 Project-URL: Homepage, https://github.com/BhuvaneshBhatt/multiple_integrate
-Project-URL: Documentation, https://BhuvaneshBhatt.github.io/multiple_integrate
+Project-URL: Documentation, https://multiple-integrate.readthedocs.io/
 Project-URL: Source, https://github.com/BhuvaneshBhatt/multiple_integrate
 Project-URL: Issue Tracker, https://github.com/BhuvaneshBhatt/multiple_integrate/issues
 Project-URL: Changelog, https://github.com/BhuvaneshBhatt/multiple_integrate/blob/main/docs/changelog.md
@@ -16,34 +16,35 @@ Classifier: Intended Audience :: Education
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.11
+Requires-Python: >=3.10
 Requires-Dist: sympy>=1.12
 Provides-Extra: all
 Requires-Dist: ipykernel>=6.0; extra == 'all'
 Requires-Dist: jupyter>=1.0; extra == 'all'
 Requires-Dist: matplotlib>=3.7; extra == 'all'
-Requires-Dist: mkdocs-material>=9.5; extra == 'all'
-Requires-Dist: mkdocs>=1.5; extra == 'all'
 Requires-Dist: mypy>=1.10; extra == 'all'
+Requires-Dist: myst-parser<5,>=4; extra == 'all'
 Requires-Dist: notebook>=7.0; extra == 'all'
-Requires-Dist: pymdown-extensions>=10.7; extra == 'all'
 Requires-Dist: pytest-timeout>=2.2; extra == 'all'
 Requires-Dist: pytest>=8; extra == 'all'
 Requires-Dist: ruff>=0.4; extra == 'all'
+Requires-Dist: sphinx-rtd-theme<4,>=3; extra == 'all'
+Requires-Dist: sphinx<9,>=8; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pytest-timeout>=2.2; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Provides-Extra: docs
-Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
-Requires-Dist: mkdocs>=1.5; extra == 'docs'
-Requires-Dist: pymdown-extensions>=10.7; extra == 'docs'
+Requires-Dist: myst-parser<5,>=4; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme<4,>=3; extra == 'docs'
+Requires-Dist: sphinx<9,>=8; extra == 'docs'
 Provides-Extra: notebook
 Requires-Dist: ipykernel>=6.0; extra == 'notebook'
 Requires-Dist: jupyter>=1.0; extra == 'notebook'
@@ -126,11 +127,32 @@ So a triangular integral should be written as
 multiple_integrate(1, (y, 0, 1 - x), (x, 0, 1))
 ```
 
-not with the structural outer-to-inner ordering used, for example, by Mathematica. The same convention is used by
-`region_from_ranges(...)` when regions are recognized from dependent bounds.
+not with the structural outer-to-inner ordering used, for example, by Mathematica. The same convention is used by `multiple_integrate`; standalone `region_from_ranges(...)` can also inspect an explicitly requested structural order for geometric classification.
 
 This matters especially for triangular, disk, and ball examples with dependent bounds: write the tuples in the same order you would pass them to `sympy.integrate`.
 
+When bounds contain symbolic parameters, specialized geometric formulas are used only when their orientation can be established from the supplied assumptions. This preserves the signed semantics of iterated integration.
+
+## Assumptions
+
+Parameter assumptions can be supplied with ordinary SymPy relations or ``Q`` predicates:
+
+```python
+import sympy as sp
+from multiple_integrate import multiple_integrate
+
+x, a = sp.symbols("x a", real=True)
+
+multiple_integrate(
+    sp.exp(-a*x),
+    (x, 0, sp.oo),
+    assumptions={a > 0},
+)
+# 1/a
+```
+
+A single condition such as ``assumptions=a > 0`` is also accepted, as are lists, tuples, sets, and SymPy predicates such as ``Q.positive(a)``. Contradictory assumptions raise ``ValueError``.
+
 ---
 
 ## Representative multiple-integral examples
@@ -276,21 +298,25 @@ Here the inner function is `g(x, y) = x + y`. Its level sets in the first quadra
 
 ## Region model
 
-The solver now normalizes input bounds into explicit region objects before applying several structural shortcuts.
+The solver normalizes input bounds into explicit region objects before applying structural shortcuts.
 
-Current region support includes:
+Region support includes:
 
 - `BoxRegion` for product domains with independent bounds
 - `IteratedRegion` for general nested bounds
 - `SimplexRegion` for standard simplex-style regions
 - `AffineSimplexRegion` for affine images of standard simplices
 - `GraphRegion` for simple affine graph-bounded 2D regions
-- `DiskRegion` for standard centered disks
-- `BallRegion` for standard centered balls
-- `EllipsoidRegion` for axis-aligned centered ellipsoids
+- `DiskRegion` for centered or translated axis-aligned disks
+- `BallRegion` for centered or translated axis-aligned balls
+- `EllipsoidRegion` for centered or translated axis-aligned ellipsoids
 - `AnnulusRegion` for centered annuli
 - `SphericalShellRegion` for centered spherical shells
-- `UnionRegion` for finite unions of supported regions
+- `UnionRegion` for finite disjoint unions of supported regions with matching ordered variables
+
+Region constructors validate structural invariants such as distinct SymPy variables, compatible dimensions, nonnegative radii, positive ellipsoid semi-axes, and consistent nested dependencies. `UnionRegion` has additive **disjoint-union** semantics: pieces must share the same ordered variables and be disjoint up to measure-zero boundaries. Obvious overlaps among supported concentric radial pieces are rejected; if symbolic overlap cannot be decided, callers remain responsible for the disjointness claim.
+
+Translated disks, balls, and axis-aligned ellipsoids are recognized directly from shifted Cartesian bounds. Their `center` coordinates are stored in the same order as `region.variables`, and polynomial/radial shortcuts operate relative to that center.
 
 This improves:
 
@@ -336,7 +362,7 @@ However, it is still **not** a full symbolic region engine. In particular, it do
 
 - general geometric region rewriting
 - automatic order reversal for arbitrary dependent bounds
-- a full region algebra comparable to symbolic `Region` objects
+- a full region algebra
 - unrestricted automatic polar/spherical coordinate changes
 - arbitrary semialgebraic cell decomposition
 
@@ -391,6 +417,6 @@ GPL-3.0-or-later
 
 ---
 
-## Current limitations
+## Limitations
 
-Recent additions include exact simplex / Dirichlet formulas and the coordinate-change layer for selected disks, balls, shells, and ellipsoids, butthe package still does **not** attempt completely general geometric rewriting or arbitrary symbolic substitutions. It is best viewed as a recognition-driven exact integrator for structured families.
+The package includes exact simplex / Dirichlet formulas and coordinate changes for selected disks, balls, shells, and ellipsoids, but it does **not** attempt completely general geometric rewriting or arbitrary symbolic substitutions. It is best viewed as a recognition-driven exact integrator for structured families.

{multiple_integrate-2.0.0 → multiple_integrate-2.1.0}/README.md

@@ -67,11 +67,32 @@ So a triangular integral should be written as
 multiple_integrate(1, (y, 0, 1 - x), (x, 0, 1))
 ```
 
-not with the structural outer-to-inner ordering used, for example, by Mathematica. The same convention is used by
-`region_from_ranges(...)` when regions are recognized from dependent bounds.
+not with the structural outer-to-inner ordering used, for example, by Mathematica. The same convention is used by `multiple_integrate`; standalone `region_from_ranges(...)` can also inspect an explicitly requested structural order for geometric classification.
 
 This matters especially for triangular, disk, and ball examples with dependent bounds: write the tuples in the same order you would pass them to `sympy.integrate`.
 
+When bounds contain symbolic parameters, specialized geometric formulas are used only when their orientation can be established from the supplied assumptions. This preserves the signed semantics of iterated integration.
+
+## Assumptions
+
+Parameter assumptions can be supplied with ordinary SymPy relations or ``Q`` predicates:
+
+```python
+import sympy as sp
+from multiple_integrate import multiple_integrate
+
+x, a = sp.symbols("x a", real=True)
+
+multiple_integrate(
+    sp.exp(-a*x),
+    (x, 0, sp.oo),
+    assumptions={a > 0},
+)
+# 1/a
+```
+
+A single condition such as ``assumptions=a > 0`` is also accepted, as are lists, tuples, sets, and SymPy predicates such as ``Q.positive(a)``. Contradictory assumptions raise ``ValueError``.
+
 ---
 
 ## Representative multiple-integral examples
@@ -217,21 +238,25 @@ Here the inner function is `g(x, y) = x + y`. Its level sets in the first quadra
 
 ## Region model
 
-The solver now normalizes input bounds into explicit region objects before applying several structural shortcuts.
+The solver normalizes input bounds into explicit region objects before applying structural shortcuts.
 
-Current region support includes:
+Region support includes:
 
 - `BoxRegion` for product domains with independent bounds
 - `IteratedRegion` for general nested bounds
 - `SimplexRegion` for standard simplex-style regions
 - `AffineSimplexRegion` for affine images of standard simplices
 - `GraphRegion` for simple affine graph-bounded 2D regions
-- `DiskRegion` for standard centered disks
-- `BallRegion` for standard centered balls
-- `EllipsoidRegion` for axis-aligned centered ellipsoids
+- `DiskRegion` for centered or translated axis-aligned disks
+- `BallRegion` for centered or translated axis-aligned balls
+- `EllipsoidRegion` for centered or translated axis-aligned ellipsoids
 - `AnnulusRegion` for centered annuli
 - `SphericalShellRegion` for centered spherical shells
-- `UnionRegion` for finite unions of supported regions
+- `UnionRegion` for finite disjoint unions of supported regions with matching ordered variables
+
+Region constructors validate structural invariants such as distinct SymPy variables, compatible dimensions, nonnegative radii, positive ellipsoid semi-axes, and consistent nested dependencies. `UnionRegion` has additive **disjoint-union** semantics: pieces must share the same ordered variables and be disjoint up to measure-zero boundaries. Obvious overlaps among supported concentric radial pieces are rejected; if symbolic overlap cannot be decided, callers remain responsible for the disjointness claim.
+
+Translated disks, balls, and axis-aligned ellipsoids are recognized directly from shifted Cartesian bounds. Their `center` coordinates are stored in the same order as `region.variables`, and polynomial/radial shortcuts operate relative to that center.
 
 This improves:
 
@@ -277,7 +302,7 @@ However, it is still **not** a full symbolic region engine. In particular, it do
 
 - general geometric region rewriting
 - automatic order reversal for arbitrary dependent bounds
-- a full region algebra comparable to symbolic `Region` objects
+- a full region algebra
 - unrestricted automatic polar/spherical coordinate changes
 - arbitrary semialgebraic cell decomposition
 
@@ -332,6 +357,6 @@ GPL-3.0-or-later
 
 ---
 
-## Current limitations
+## Limitations
 
-Recent additions include exact simplex / Dirichlet formulas and the coordinate-change layer for selected disks, balls, shells, and ellipsoids, butthe package still does **not** attempt completely general geometric rewriting or arbitrary symbolic substitutions. It is best viewed as a recognition-driven exact integrator for structured families.
+The package includes exact simplex / Dirichlet formulas and coordinate changes for selected disks, balls, shells, and ellipsoids, but it does **not** attempt completely general geometric rewriting or arbitrary symbolic substitutions. It is best viewed as a recognition-driven exact integrator for structured families.

multiple_integrate-2.1.0/docs/Makefile

@@ -0,0 +1,12 @@
+SPHINXOPTS    ?= -W
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+.PHONY: html clean
+
+html:
+	$(SPHINXBUILD) $(SPHINXOPTS) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html"
+
+clean:
+	rm -rf "$(BUILDDIR)"

multiple_integrate-2.1.0/docs/api/core.rst

@@ -0,0 +1,12 @@
+Core integration engine
+=======================
+
+The supported top-level entry point is
+:func:`multiple_integrate.multiple_integrate`. This page also exposes
+implementation data structures documented in ``core.py`` for contributors and
+advanced users.
+
+.. automodule:: multiple_integrate.core
+   :members:
+   :show-inheritance:
+   :member-order: bysource

multiple_integrate-2.1.0/docs/api/index.rst

@@ -0,0 +1,15 @@
+API reference
+=============
+
+This reference is generated from docstrings in ``src/multiple_integrate``.
+
+The package-root page documents the supported public surface. The module pages
+provide fuller technical detail for region objects, classification helpers, and
+core integration data structures.
+
+.. toctree::
+   :maxdepth: 2
+
+   public
+   regions
+   core

multiple_integrate-2.1.0/docs/api/public.rst

@@ -0,0 +1,8 @@
+Public package API
+==================
+
+.. automodule:: multiple_integrate
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :member-order: bysource

multiple_integrate-2.1.0/docs/api/regions.rst

@@ -0,0 +1,7 @@
+Regions and classification
+==========================
+
+.. automodule:: multiple_integrate.regions
+   :members:
+   :show-inheritance:
+   :member-order: bysource

{multiple_integrate-2.0.0 → multiple_integrate-2.1.0}/docs/api.md

@@ -1,6 +1,6 @@
 # API Reference
 
-This page documents the public API and the main internal data structures used by the current `src/multiple_integrate/` package.
+This page documents the public API and the main internal data structures used by `src/multiple_integrate/`.
 
 ---
 
@@ -13,7 +13,6 @@ def multiple_integrate(
     f: sympy.Expr,
     *ranges,
     assumptions=None,
-    generate_conditions: bool = False,
     principal_value: bool = False,
 ) -> sympy.Expr
 ```
@@ -26,9 +25,8 @@ Symbolically evaluate a definite or multiple integral.
 |---|---|---|
 | `f` | `sympy.Expr` | Integrand as a SymPy expression. |
 | `*ranges` | `tuple(symbol, lower, upper)` | Integration ranges in **inner-first iterated order**, matching `sympy.integrate`. |
-| `assumptions` | `dict`, optional | Extra assumptions forwarded to selected SymPy calls. |
-| `generate_conditions` | `bool` | Request conditional output from SymPy in supported fallback calls. |
-| `principal_value` | `bool` | Request Cauchy principal value in supported fallback calls. |
+| `assumptions` | SymPy Boolean condition or iterable, optional | Mathematical assumptions such as `a > 0`, `{a > 0, b != 0}`, or `{Q.positive(a)}`. Conditions are normalized to SymPy predicates and used by convergence checks and symbolic refinement. |
+| `principal_value` | `bool` | Request a one-dimensional Cauchy principal value. Multidimensional principal values are currently rejected explicitly. |
 
 **Returns**
 
@@ -38,7 +36,8 @@ A `sympy.Expr`. On some unsupported inputs the result may remain an unevaluated
 
 - The first range tuple is the **innermost** integral.
 - The solver may use region-aware exact formulas, coordinate changes, symmetry reductions, decomposition-based methods, or raw SymPy fallback.
-- The package performs some structured-path safety checks, but it does **not** attempt complete general convergence analysis for arbitrary integrals.
+- Symmetry shortcuts are disabled when an interior singularity may make ordinary and principal-value integration differ.
+- The package still does **not** attempt complete general convergence analysis for arbitrary multidimensional integrals.
 
 **Example**
 
@@ -109,26 +108,12 @@ These live in `src/multiple_integrate/regions.py`.
 
 ---
 
-## Decomposition support
+## Internal decomposition support
 
-### `Decomposition`
+The composition-analysis helper is internal. ``_IntegrandDecomposition`` stores
+``f_outer``, ``g_inner``, and ``is_polynomial`` for strategy dispatch, but it is
+not exported from ``multiple_integrate`` and is not part of the public API.
 
-```python
-class Decomposition:
-    f_outer: Callable
-    g_inner: sympy.Expr
-    is_polynomial: bool
-```
-
-A lightweight container describing an integrand decomposition of the form
-
-\[
-F(x_1,\dots,x_n) = f(g(x_1,\dots,x_n)).
-\]
-
-This still matters internally for several non-region-specific heuristics, but it is no longer the only organizing idea in the solver.
-
----
 
 ## Coordinate transforms
 
@@ -164,10 +149,10 @@ This is currently used for selected coordinate changes such as:
 Contains:
 
 - `multiple_integrate`
-- `Decomposition`
+- `_IntegrandDecomposition` (internal)
 - `CoordinateTransform`
 - decomposition helpers
-- planner / fallback logic
+- method selection and iterated fallback
 - selected exact family solvers
 
 ### `multiple_integrate.regions`

multiple_integrate-2.1.0/docs/concepts/ranges-and-regions.rst

@@ -0,0 +1,136 @@
+Nested ranges and region classification
+=======================================
+
+The range convention
+--------------------
+
+MultipleIntegrate uses the same iterated-integral ordering as
+``sympy.integrate``: the **first range is integrated first**, so it is the
+innermost integral.
+
+For example,
+
+.. math::
+
+   \int_0^1 \int_0^{1-x} f(x,y)\,dy\,dx
+
+is written as:
+
+.. code-block:: python
+
+   multiple_integrate(
+       f,
+       (y, 0, 1 - x),
+       (x, 0, 1),
+   )
+
+The upper bound of ``y`` may depend on ``x`` because ``x`` remains free while
+the inner ``y`` integral is evaluated. Reversing those tuples without deriving
+new bounds generally describes a different iterated integral.
+
+Ranges as geometry
+------------------
+
+A list of nested ranges describes more than an evaluation order: it also
+describes a geometric domain. ``region_from_ranges`` analyzes that structure
+and returns the most specific region type it can justify.
+
+Conceptually, classification proceeds from informative geometric patterns
+toward a generic fallback:
+
+.. code-block:: text
+
+   nested ranges
+       |
+       +-- independent constant bounds --------> BoxRegion
+       |
+       +-- standard simplex bounds ------------> SimplexRegion
+       |
+       +-- affine simplex bounds --------------> AffineSimplexRegion
+       |
+       +-- circular / spherical bounds --------> DiskRegion / BallRegion
+       |
+       +-- unequal quadratic semi-axes --------> EllipsoidRegion
+       |
+       +-- dependent graph bounds -------------> GraphRegion
+       |
+       `-- otherwise --------------------------> IteratedRegion
+
+Classification is deliberately conservative. A specialized region should be
+returned only when the bounds establish the corresponding geometry. This
+matters because specialized objects can provide exact volume, moment, radial,
+symmetry, or change-of-variables shortcuts.
+
+Structural orientation versus public ordering
+----------------------------------------------
+
+Geometric recognition is often easiest when bounds are inspected
+outer-to-inner, whereas the public API follows SymPy's inner-first convention.
+The classifier may therefore inspect plausible structural orientations
+internally. Once a region is recognized, its stored ranges are canonicalized
+back to the package's public inner-first convention.
+
+Users should continue to supply ranges exactly as they would to
+``sympy.integrate``.
+
+Why classification matters
+--------------------------
+
+Region recognition can replace a difficult symbolic iterated integral with an
+exact formula. Specialized paths include:
+
+* constant volume for boxes, disks, balls, ellipsoids, annuli, spherical
+  shells, and simplices;
+* polynomial moments on several structured regions;
+* cancellation of odd terms on reflection-invariant domains;
+* polar or spherical changes of variables for suitable radial integrands;
+* affine normalization of an affine simplex to a standard simplex;
+* selected graph-region order reversal.
+
+If no specialized path applies, ``multiple_integrate`` retains a general
+iterated SymPy integration fallback. Region recognition is therefore an
+optimization and reasoning layer rather than a requirement for every valid
+integral.
+
+Inspecting a classification
+---------------------------
+
+.. code-block:: python
+
+   import sympy as sp
+   from multiple_integrate import region_from_ranges
+
+   x, y = sp.symbols("x y", real=True)
+
+   ranges = [
+       (y, 0, 1 - x),
+       (x, 0, 1),
+   ]
+
+   region = region_from_ranges(ranges)
+
+   print(type(region).__name__)
+   print(region.variables)
+   print(region.normalized_ranges())
+   print(region.constant_volume())
+
+The region classes and classification functions are documented in
+:doc:`../api/regions`.
+
+Translated quadrics
+-------------------
+
+Disk, ball, and axis-aligned ellipsoid recognition also accepts coordinate shifts.
+For example, bounds equivalent to ``(x-cx)**2 + (y-cy)**2 <= R**2`` produce a
+``DiskRegion`` with a nonzero ``center``.  The center tuple follows the same variable
+ordering as ``region.variables``. Polynomial moments and radial shortcuts translate to
+the stored center before applying the standard centered formulas.
+
+Union semantics
+---------------
+
+``UnionRegion`` represents an additive disjoint decomposition, not a general
+inclusion-exclusion set union. Pieces must use the same ordered variables and be
+disjoint up to measure-zero boundaries. The constructor rejects overlaps it can prove
+for supported concentric radial pieces; when symbolic overlap is undecidable, the
+caller is responsible for supplying disjoint pieces.

multiple_integrate-2.1.0/docs/conf.py

@@ -0,0 +1,49 @@
+"""Sphinx configuration for the MultipleIntegrate documentation."""
+
+from __future__ import annotations
+
+project = "MultipleIntegrate"
+author = "Bhuvanesh Bhatt"
+copyright = "2026, Bhuvanesh Bhatt"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "myst_parser",
+]
+
+autosummary_generate = True
+autodoc_member_order = "bysource"
+autodoc_typehints = "description"
+
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+master_doc = "index"
+
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+]
+
+html_theme = "sphinx_rtd_theme"
+html_title = "MultipleIntegrate"
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "sympy": ("https://docs.sympy.org/latest/", None),
+}
+
+myst_enable_extensions = [
+    "dollarmath",
+    "colon_fence",
+]

{multiple_integrate-2.0.0 → multiple_integrate-2.1.0}/docs/contributing.md

@@ -1,6 +1,6 @@
 # Contributing
 
-This guide explains the current project layout and the main ideas to keep in mind when extending MultipleIntegrate.
+This guide explains the project layout and the main ideas to keep in mind when extending MultipleIntegrate.
 
 ---
 
@@ -28,9 +28,9 @@ docs/
 
 ---
 
-## Current architectural picture
+## Architecture
 
-The package is no longer just a single decomposition-first engine. The current flow is closer to:
+The package uses the following layered flow:
 
 ```text
 multiple_integrate(expr, *ranges)
@@ -77,7 +77,7 @@ Typical tasks:
 
 If a class of integrals has a stable closed form, prefer implementing that directly rather than relying on generic SymPy definite integration.
 
-Current examples include:
+Examples include:
 
 - simplex / Dirichlet formulas
 - selected disk / ball / shell formulas
@@ -95,13 +95,13 @@ When extending this area, focus on transformations that are:
 
 ### 4. Decomposition-based methods
 
-`Decomposition` and its helpers still matter for monotone, piecewise-monotone, separable, and selected layer-cake style methods.
+`_IntegrandDecomposition` and its helpers still matter for monotone, piecewise-monotone, separable, and selected layer-cake style methods.
 
-This is a useful extension area, but it should now be thought of as one family inside the broader solver.
+This is a useful extension area, but it is best treated as one family inside the broader solver.
 
 ---
 
-## Adding a new capability
+## Adding a capability
 
 A good pattern is:
 

multiple_integrate-2.1.0/docs/decomposition.md

@@ -0,0 +1,39 @@
+# Integrand composition analysis
+
+MultipleIntegrate analyzes some integrands as a composition
+
+$$
+F(x_1,\ldots,x_n)=f(g(x_1,\ldots,x_n)).
+$$
+
+The private `_IntegrandDecomposition` container stores the outer callable `f_outer`, the inner expression `g_inner`, and whether `g_inner` is polynomial in the integration variables. This representation is used only by the planner.
+
+## Recognized structures
+
+### Polynomial inner expressions
+
+A polynomial integrand can use the identity outer function, with the polynomial itself as `g_inner`. This representation enables linear pushforward, quadratic full-space, simplex, and polynomial level-set formulas.
+
+### Single-argument functions
+
+Expressions such as `exp(g)`, `sin(g)`, `cos(g)`, and `log(g)` are represented by replacing the function argument with a fresh dummy variable. For example, `exp(x**2 + y)` becomes an outer function `exp(t)` and inner expression `x**2 + y`.
+
+### Powers with integration-independent exponents
+
+An expression such as `(x**2 + 1)**(3/2)` is represented by the outer function `t**(3/2)` and inner expression `x**2 + 1`.
+
+### Constant factor and addend peeling
+
+Integration-independent factors and addends are separated before recursively analyzing the variable-dependent expression. For example, `3*sin(x)` can be represented with inner expression `x` and outer function `3*sin(t)`.
+
+### Single active variables
+
+Any expression depending on exactly one integration variable can use the identity outer function. This supports monotone and piecewise-monotone change-of-variable methods for expressions such as `tan(x)`, `1/x`, and `x*log(x)`.
+
+## When composition analysis declines
+
+A multivariable expression that has no supported compositional structure is left to separability checks, region-specific formulas, or ordinary iterated integration. Declining a decomposition is intentional: the planner should not force an artificial `f(g)` representation when doing so would obscure variable dependence or make a structural method unsound.
+
+## Polynomial flag
+
+The `is_polynomial` flag determines whether polynomial-only formulas are eligible. Non-polynomial inner expressions skip coefficient extraction and polynomial geometry tests, then proceed directly to methods that support general symbolic inner functions.