entroptics 0.1.1__tar.gz

entroptics-0.1.1/LICENSE.md

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Ikailo Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

entroptics-0.1.1/NOTICE

@@ -0,0 +1,6 @@
+Entroptics
+Copyright 2026 Ikailo Inc.
+
+Portions of this software, and certain related inventions, are the
+subject of pending patent applications. For patent and commercial
+licensing inquiries: connect@ikailo.com

entroptics-0.1.1/PKG-INFO

@@ -0,0 +1,418 @@
+Metadata-Version: 2.4
+Name: entroptics
+Version: 0.1.1
+Summary: The universe, in focus.
+Author-email: Ikailo John Sessford <john@ikailo.com>
+License: 
+                                         Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+              any Contribution intentionally submitted for inclusion in the Work
+              by You to the Licensor shall be under the terms and conditions of
+              this License, without any additional terms or conditions.
+              Notwithstanding the above, nothing herein shall supersede or modify
+              the terms of any separate license agreement you may have executed
+              with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor,
+              except as required for reasonable and customary use in describing the
+              origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+              agreed to in writing, Licensor provides the Work (and each
+              Contributor provides its Contributions) on an "AS IS" BASIS,
+              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+              implied, including, without limitation, any warranties or conditions
+              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+              PARTICULAR PURPOSE. You are solely responsible for determining the
+              appropriateness of using or redistributing the Work and assume any
+              risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+              whether in tort (including negligence), contract, or otherwise,
+              unless required by applicable law (such as deliberate and grossly
+              negligent acts) or agreed to in writing, shall any Contributor be
+              liable to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages of any character arising as a
+              result of this License or out of the use or inability to use the
+              Work (including but not limited to damages for loss of goodwill,
+              work stoppage, computer failure or malfunction, or any and all
+              other commercial damages or losses), even if such Contributor
+              has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+              the Work or Derivative Works thereof, You may choose to offer,
+              and charge a fee for, acceptance of support, warranty, indemnity,
+              or other liability obligations and/or rights consistent with this
+              License. However, in accepting such obligations, You may act only
+              on Your own behalf and on Your sole responsibility, not on behalf
+              of any other Contributor, and only if You agree to indemnify,
+              defend, and hold each Contributor harmless for any liability
+              incurred by, or claims asserted against, such Contributor by reason
+              of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+           APPENDIX: How to apply the Apache License to your work.
+        
+              To apply the Apache License to your work, attach the following
+              boilerplate notice, with the fields enclosed by brackets "[]"
+              replaced with your own identifying information. (Don't include
+              the brackets!)  The text should be enclosed in the appropriate
+              comment syntax for the file format. We also recommend that a
+              file or class name and description of purpose be included on the
+              same "printed page" as the copyright notice for easier
+              identification within third-party archives.
+        
+           Copyright 2026 Ikailo Inc.
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+Project-URL: Repository, https://github.com/Agience/agience-entroptics
+Project-URL: Issues, https://github.com/Agience/agience-entroptics/issues
+Keywords: entropy,optics,aperture
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+License-File: NOTICE
+Requires-Dist: numpy>=2.0
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == "torch"
+Provides-Extra: scipy
+Requires-Dist: scipy>=1.10; extra == "scipy"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: scipy>=1.10; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: scipy>=1.10; extra == "dev"
+Requires-Dist: torch>=2.0; extra == "dev"
+Dynamic: license-file
+
+# Entroptics
+
+[![PyPI](https://img.shields.io/pypi/v/entroptics)](https://pypi.org/project/entroptics/)
+[![Python](https://img.shields.io/pypi/pyversions/entroptics)](https://pypi.org/project/entroptics/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](https://github.com/Agience/agience-entroptics/blob/main/LICENSE.md)
+[![CI](https://github.com/Agience/agience-entroptics/actions/workflows/ci.yml/badge.svg)](https://github.com/Agience/agience-entroptics/actions/workflows/ci.yml)
+[![Proofs](https://img.shields.io/badge/proofs-Lean%204%20%2F%20Mathlib-4B0082)](https://github.com/Agience/agience-entroptics/tree/main/research/lean)
+[![DOI](https://zenodo.org/badge/1293014088.svg)](https://zenodo.org/badge/latestdoi/1293014088)
+[![Sponsor](https://img.shields.io/badge/Sponsor-ikailo-EA4AAA?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ikailo)
+
+## *The universe, in focus.*
+
+**Read any 2-D signal as a finite optical aperture whose resolution is fixed by the signal's own entropy.**
+
+Entroptics (entropy + optics) treats a 2-D array `W` of shape `(T, F)`, one **ordered** axis (time / evolution) and one **feature** axis (channels / frequency), as a finite optical aperture. The signal sets its own focus from the entropy of its power marginals. Every quantity Entroptics reports is then a standard optical / wave measurement (étendue, Strehl, OTF, diffraction limit, propagation constant), and the same reads apply to any structured 2-D field: a spectrogram, a waterfall, an embedding stack, a market panel, an image.
+
+It is a small, standalone library, **numpy only** at the core (scipy and torch optional), built entirely from geometry and standard theorems. Parameter-free and domain-agnostic.
+
+## Install
+
+```bash
+pip install -e .              # core (numpy only)
+pip install -e ".[torch]"     # + GPU / torch tensors
+pip install -e ".[scipy]"     # + exact MAD constant
+pip install -e ".[dev]"       # + pytest, torch, scipy (to run the tests)
+```
+
+Requires Python ≥ 3.10 and numpy ≥ 2.0.
+
+## Two objects
+
+| | |
+|---|---|
+| **`Aperture`** | The **optics**, information *about* a structure (read-only). The single front door: batch `Aperture(W)` or streaming `Aperture(window=…).update(frame)`. Exposes the per-axis and screen-area reads, the mode spectrum, the diffraction limit, and a streaming dynamical operator for exact decay rates. |
+| **`Screen`** | The **projection**, information *within* the structure (read-only). Folds the signal onto its entropy-matched grid and reads its SVD structure, coherence, and the modes above the noise floor. A denoised view is the `extract` filter — a projection onto those resolved modes. |
+
+`ap.screen()` and `Screen(W).aperture()` cross between the two views.
+
+## Quickstart
+
+### Batch
+
+```python
+import numpy as np
+from entroptics import Aperture
+
+W = np.random.default_rng(0).standard_normal((256, 64))
+
+ap = Aperture(W)
+
+o = ap.optics()               # the full intrinsic read, as a dict (33 fields)
+ap.phi, ap.magnification      # fill fraction and its reciprocal (scale duality)
+ap.etendue, ap.space_bandwidth
+ap.strehl                     # dominant-mode coherence
+ap.T, ap.F                    # per-axis AxisRead(H, n, delta, phi, sigma)
+ap.spectral                   # contrast, attenuation α, phase β, dispersion, resolved_power, dominance
+ap.a_delta, ap.correlation_length, ap.mercer   # diffraction limit + certificate
+ap.scale_profile()            # structure vs observation window (resolution vs aperture size)
+```
+
+### The projection
+
+```python
+sc = ap.screen()
+sc.K_signal        # SVD modes standing above the noise floor
+sc.coherence       # ordered-axis structure z-score (deterministic)
+sc.footprints      # per-mode (phi_T, phi_F) localization of each resolved mode
+```
+
+### The filter
+
+Pull the resolved signal out of the field — a projection onto its own screen modes.
+
+```python
+clean, info = ap.extract()          # or: entroptics.extract(W) for the full frame
+info["K_signal"]                    # resolved modes above the floor
+info["contrast"]                    # leading singular value over the floor (σ₁ / Φ)
+info["n_kept"], info["n_dropped"]   # transient modes kept, persistent (RFI) modes dropped
+```
+
+`clean = U · diag(S̃) · Vᴴ` uses the data's own screen modes `U, Vᴴ` and the Gavish–Donoho optimal singular-value shrinkage `S̃` against the derived floor: exact recovery in the noise-free limit, idempotent, with the persistent narrowband (`φ_F ≤ φ_T`) modes dropped.
+
+### Streaming, resume, splice
+
+Feed frames from the first one and propagate; the exact-rate operator updates online.
+
+```python
+ap = Aperture(window=512)          # window bounds the optics snapshot
+for frame in signal:               # each frame an F-vector (numpy or torch)
+    ap.update(frame)
+
+ap.rates()                         # long_range (slowest) & short_range (fastest) decay
+ap.predict(frame)                  # one-step forecast A·x (A = ap.propagator_full())
+
+s = ap.state()                     # export the full operator state …
+ap2 = Aperture.from_state(s)       # … and resume exactly (bit-for-bit)
+
+whole = a.splice(b)                # a, b: two Aperture streams → the concatenated-stream operator (exact at forgetting=1)
+```
+
+## What it reads
+
+All reads are intrinsic (derived from `W` alone) and tied to a standard theorem.
+
+- **Scale**, `phi` (fill fraction) and `magnification = 1/phi`; per-axis `H_T/H_F`, `n_T/n_F`, `delta_T/delta_F` from the entropy of the power marginals.
+- **Aperture area**, `etendue = phi_F · phi_T` (a bounded 2-D area), `space_bandwidth = n_F · n_T` (resolvable spots).
+- **Coherence**, `strehl` (dominant-mode power fraction), `phi_T/phi_F`, `sigma_T/sigma_F`; `Screen.coherence` (a closed-form z-score against the exact row-permutation null).
+- **Mode spectrum**, `spectral_optics`: contrast, top-share, resolved modes, noise floor from a `null=` provider (see `entroptics.null_providers`) — the derived Marchenko–Pastur / Johnstone default (`mp`, used when `null` is unset) or the deterministic data-derived Tukey fence (pass `null=null_providers.robust`), the propagation constant γ = α + iβ (attenuation α, phase β), dispersion, `resolved_power` (the summed eigenvalue excess above the floor), and `dominance = (λ₁−1)/(F−1)` (F = correlation variables). `attenuation_interval` gives a Weyl-certified interval for α.
+- **Concentration**, `concentration`: `intensity` (σ₁²), `focus` (axial), `resultant` (directional, von Mises–Fisher).
+- **Diffraction limit**, `decay` (the OTF, an FFT-free autocorrelation), `diffraction_limit` (entropy width `a_delta = 1/2^{H(C²)}` + classical Abbe length), `mercer_certificate` (a model-free temporal-vs-spectral cross-check), `rayleigh_shape_factor` (the shape factor `g = xi * a_delta`), `fresnel_number`, `shape_factor` (the Abbe factor `a_delta / phi_F`), `decay_rate` (log-linear fit of a supplied 1-D curve).
+- **N-D fields**, `entroptics.fields`: `slabs(field, plane_axes)` / `over_planes(field, plane_axes, read=, reduce=)` reduce a higher-D field to the 2-D screen **while keeping each plane intact** (the correct reduction for feature reads, which need within-plane correlation); `pool(field, ordered_axis)` flattens sites as samples (the correct reduction for ordered reads).
+- **Dynamics**, `Aperture.rates()`: exact per-mode decay rates `α_k = −log|μ_k|` and frequencies `β_k = arg(μ_k)` from a streaming online-DMD / Koopman operator; splice-able and resumable. `Aperture.propagator_full()` / `predict(x)` expose and apply the full one-step operator `A = P_yx · P_xx⁺`.
+- **Multi-scale**, `scale_profile(W)`: structure as a function of observation window (resolution vs aperture size), `K_signal` / `coherence` / `a_delta` / `phi_T` per window, plus `resolved_window` / `dominant_window` (in ordered-axis cells).
+- **Projection**, `Screen` (`embeddings`, `footprints`, `read`) and `Aperture.tensor()` (a delay-embedded Tucker/HOSVD that exposes within-window fine structure the averaged screen loses).
+- **Filter**, `Aperture.extract()` / `entroptics.extract(W)`: the read-side denoiser — project the field onto its own resolved screen modes with Gavish–Donoho optimal singular-value shrinkage against the derived floor, dropping persistent narrowband (`phi_F <= phi_T`) interference. Returns `(clean, info)` where `clean` is a linear projection of the measured data (it synthesises nothing) and `info` carries `K_signal`, `contrast`, `coherence`, and the kept/dropped modes.
+- **Sweep**, `entroptics.sweep(W)`: fix the aperture to a bounded capacity and sweep it where the coherence gate finds structure (noise-only patches are skipped); returns per-coherent-band reads — column `span`, entropy `width`, and tail decay `tau` — in abstract, dimensionless window samples.
+
+## Unwinding a propagation channel
+
+`research/applications/cosmology.py` drives Entroptics to invert a burst's interstellar propagation and return it to the source frame. Each transform in the medium's stack carries one free parameter, fixed by **maximizing an entroptics read**:
+
+| transform | recovers | read maximized |
+|---|---|---|
+| dispersion `τ(f) = K·DM·f⁻²` | `DM` | leading-mode contrast |
+| Faraday rotation `Δψ = RM·λ²` | `RM` | derotated polarized amplitude |
+| scattering `⊛ e^{−t/τ}` | `τ_scatter` | per-band tail decay rate |
+| instrument / RFI | — | the `φ_F > φ_T` geometric filter |
+
+```python
+from cosmology import unwind
+
+r = unwind(I, freqs, dt)               # intensity → DM + scattering + RFI-cleaned source frame
+r = unwind(I, freqs, dt, Q=Q, U=U)     # + Faraday derotation and source-frame polarization
+r.source                               # dedispersed, derotated, RFI-cleaned burst
+r.dm, r.rm, r.tau_scatter, r.pol_fraction
+```
+
+The library supplies the objectives (contrast, polarized amplitude, decay rate) and `unwind` applies the known-physics inverse transforms out of band. Pass `skip={"dispersion"}` for data a stage has already been applied to (e.g. coherently-dedispersed baseband).
+
+## The theory in one line
+
+Everything hangs off one chain of standard results:
+
+> **Wiener–Khinchin** (autocorrelation ↔ power spectrum) provides the lag average → the **Fourier-optics autocorrelation theorem** (OTF = pupil autocorrelation) → **Abbe/Rayleigh** (resolution = 1 / OTF-bandwidth = 1 / correlation length).
+
+The entropy width `1/2^{H}` (with `H` the Shannon entropy of the squared decay `C²`) is the noise-robust estimator of that reciprocal correlation length. By **Mercer**, the temporal read (decay entropy) and the spectral read (the stationary correlation operator's eigenspectrum) track each other, a built-in, model-free certificate.
+
+## Backends & determinism
+
+- **One code path, numpy or torch.** Feed a numpy array → runs on CPU; feed a torch tensor → runs on its device (GPU), staying on-device; torch is imported lazily only when a tensor appears.
+- **Deterministic.** The coherence is a closed-form permutation-null z-score, so results are reproducible and bit-identical across numpy and torch (to floating-point round-off).
+- **Complex-safe** end to end (coherent field vs. incoherent intensity reads are dispatched automatically).
+
+## Axis convention
+
+Every input `W` has shape `(T, F)`:
+
+- axis-0 (rows, `_T`) is the **ordered** / evolution axis, "time" is a *role*, not literal physics;
+- axis-1 (cols, `_F`) is the **feature** / channel axis, "frequency" is likewise a role.
+
+Any 2-D array with one ordered axis works.
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+The suite (`src/tests/`) pins the full optics read as a golden contract, checks numpy↔torch parity, the mathematical invariants (étendue = φ_F·φ_T, exact decay-rate recovery, PSD autocovariance, axial-vs-directional concentration, the read-side filter's exact projection and idempotence), round-trips (tensor reconstruct, factor pack/unpack), determinism, and degenerate-input robustness.
+
+## Formal certification
+
+The governing lemmas of the theory ([`research/PAPER.pdf`](https://github.com/Agience/agience-entroptics/blob/main/research/PAPER.pdf)) are **machine-checked in Lean 4 / Mathlib** ([`research/lean/`](https://github.com/Agience/agience-entroptics/tree/main/research/lean), 30 theorems): the fill-fraction and Strehl bounds, positive-semidefiniteness of the biased autocovariance (peak-at-zero-lag OTF), the exact permutation-null mean of the coherence, the Weyl-certified attenuation interval, axial≠directional concentration, and exact decay-rate recovery + additive splicing. `lake build` compiles with **no `sorry`**, resting only on Mathlib's standard axioms.
+
+## License
+
+Apache 2.0 for the source code (copyright only). Patent rights are reserved, see [`LICENSE.md`](https://github.com/Agience/agience-entroptics/blob/main/LICENSE.md), [`PATENTS.md`](https://github.com/Agience/agience-entroptics/blob/main/PATENTS.md), and [`PLEDGE.md`](https://github.com/Agience/agience-entroptics/blob/main/PLEDGE.md). You are free to read, run, validate, reproduce, cite, and build research on this code and its proofs.
+
+## Star history
+
+[![Star History Chart](https://api.star-history.com/svg?repos=Agience/agience-entroptics&type=Date)](https://star-history.com/#Agience/agience-entroptics&Date)