otwin 0.2.0__tar.gz

otwin-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.egg-info/
+build/
+dist/
+*.tar.gz
+.venv/
+venv/
+.coverage
+htmlcov/

otwin-0.2.0/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+All notable changes to this project are recorded here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Until version 1.0.0 the public API may change between minor versions. Pin an
+exact version in anything you depend on.
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.2.0] — 2026-08-13
+
+First consolidated release. Thirteen separate packages were merged into one
+distribution named `otwin`, and the result was audited before publication.
+
+### Added
+
+- **One package instead of thirteen.** `otwin` now contains the whole
+  modelling, estimation and validation stack. The module layout follows the six
+  data-processing blocks of ISO 13374: `otwin.io` (data acquisition),
+  `otwin.signal` (data manipulation), `otwin.estimate` (state detection),
+  `otwin.model` (health assessment), `otwin.forecast` (prognostic assessment)
+  and `otwin.advise` (advisory generation).
+- **Field connectors.** SunSpec Modbus (models 1, 701, 702, 704, 713, 802, 803,
+  804, 805) and generic Modbus TCP/RTU, both read-only, both with a simulator
+  that drives the identical decode path so the library can be developed and
+  tested without hardware.
+- **Validity envelopes** (`otwin.advise`). A forecast request outside the
+  operating range the model was identified over, or beyond the horizon it was
+  validated to, returns a refusal with a reason rather than a number.
+- **Leakage-free forecast validation** (`otwin.forecast.protocol`). Held-out
+  targets are not reachable from the model under evaluation; the split is
+  out-of-sample and a reference forecaster is compulsory rather than optional.
+- **Structure-preserving integration.** Implicit midpoint with an analytic
+  Jacobian, `I - (dt/2)(J - R)grad^2 H`, factorised once and reused. Roughly
+  140x faster than the previous `fsolve` path at n = 50, with the energy bound
+  held to 1e-9.
+- **Type information for downstream users.** The package ships a PEP 561
+  `py.typed` marker, so a project that installs `otwin` and runs mypy gets its
+  own call sites checked.
+- **Supply-chain hardening.** Every GitHub Action pinned to a commit SHA;
+  CodeQL with the extended query pack; OpenSSF Scorecard publishing results;
+  Dependabot.
+
+### Fixed
+
+Four defects, each found by a test written against the behaviour rather than
+against the implementation, and each now covered by a regression test verified
+to fail on the previous code.
+
+- **Forecast evaluation could see the held-out data.** `protocol.py` passed the
+  test window to `model.predict()` at two separate call sites, so a reported
+  skill score measured interpolation rather than forecasting. The test targets
+  are no longer an argument to the function that asks the model for a
+  prediction.
+- **An unrecorded operating range admitted any operating point.**
+  `advise/envelope.py` skipped the state check entirely when `state_bounds` was
+  `None`, so a twin with no identified range returned a clean verdict for a
+  state of charge of 1e12. An absent range is now a refusal, matching the rule
+  the horizon check already followed.
+- **Resampling ran past the last measurement.** `signal/condition.py` built its
+  grid up to half a step beyond the final sample and `coverage()` reported the
+  invented point as measured. The grid now stops at the last whole step.
+- **A corrupt SunSpec scale factor destroyed the whole sample.**
+  `io/sunspec.py` computed `10.0 ** exponent` unguarded and outside the
+  per-model error handling, so one bad `sunssf` register raised `OverflowError`
+  out of `read()` and lost every other model on the chain. The exponent is now
+  range-checked against the SunSpec specification and the affected points
+  degrade through the existing quality ladder.
+- **State of charge was lost when one of two views went dark.**
+  `SunSpecSource.soc()` chose between models 713 and 802 on publication order
+  and then refused if that one read bad — even with the other answering
+  cleanly. Candidates are now ranked by readability first, so the model
+  preference breaks ties rather than overriding them.
+- **The learned-model path named a package that does not exist.**
+  `model/phnn.py` instructed users to `pip install otwin-learn[torch]`, left
+  over from the pre-merge distributions. It now names the real extra,
+  `otwin[nn]`, checked in CI against the metadata pip itself reads.
+
+### Changed
+
+- The source distribution no longer carries the README artwork. Every image is
+  referenced by absolute URL, so the 2.1 MB of PNGs were downloaded by everyone
+  installing from source and displayed to nobody. sdist 3.07 MB to 0.83 MB.
+- `dev` extra no longer pulls PyTorch. Two test modules need it and both skip
+  cleanly without it; use `pip install -e ".[dev,nn]"` to run them.
+
+### Verification
+
+489 tests, 92 % statement coverage, mypy clean across 39 modules, ruff clean.
+`otwin.io.sunspec`, `otwin.io.source`, `otwin.io.loader`, `otwin.advise` and
+`otwin.signal` are at 100 %. The distribution is additionally tested as
+installed — built as a wheel and imported in a container that has never seen
+this repository.
+
+### Known limitations
+
+- Python only. Julia and MATLAB implementations are open contributor positions.
+- Connectors are read-only. Closed-loop actuation is deliberately out of scope.
+- No production deployment on an operating asset is known to the maintainer.
+
+[Unreleased]: https://github.com/otwin-core/otwin/compare/v0.2.0...HEAD
+[0.2.0]: https://github.comit/otwin-core/otwin/releases/tag/v0.2.0

otwin-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,42 @@
+# Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in this project a harassment-free experience
+for everyone, regardless of age, body size, disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Our standards
+
+Examples of behaviour that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behaviour:
+
+- Sexualised language or imagery, and unwelcome sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behaviour may be
+reported to the project maintainer at javier@jmarin.info. All complaints will be reviewed
+and investigated promptly and fairly.
+
+Maintainers are obligated to respect the privacy and security of the reporter
+of any incident.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.0.

otwin-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing
+
+Practices follow [ColPrac](https://github.com/SciML/ColPrac).
+
+## The three most useful contributions
+
+1. **A reference case.** A physical system with a closed-form answer that no
+   current case covers, for [`otwin-spec`](https://github.com/otwin-core/otwin-spec).
+   It needs four things: the system and its parameters, an analytically known
+   result, a stated rationale for what goes wrong without the check, and a
+   **fault injection test** proving the check catches the fault it was written
+   for. The last is not optional — a check without one is untested code
+   protecting untested code.
+2. **A Julia or MATLAB implementation.** See [MAINTAINERS.md](MAINTAINERS.md).
+   Both slots are open and the definition of done is objective.
+3. **A register map.** If you run a PCS or BMS whose Modbus map is not SunSpec,
+   the map itself is useful even with no code attached.
+
+## Dependency licence policy
+
+This is a hard rule, not a preference, and it is the reason the connector layer
+looks the way it does.
+
+- **The base install carries NumPy and SciPy.** Nothing else.
+- **Nothing under a copyleft licence is ever a hard requirement.** LGPL and MPL
+  dependencies may be optional extras. GPL dependencies may not be vendored at
+  all.
+- **Three protocols are deliberately out of scope**, because in 2026 no
+  permissively licensed Python path to them exists:
+
+  | Protocol | Why not |
+  |---|---|
+  | IEC 61850 | `libiec61850` is GPL-3.0 or commercial; its SWIG bindings are explicitly unsupported by their own maintainers |
+  | IEC 60870-5-104 | `c104` is GPL-3.0, and capped at Python < 3.13 |
+  | DNP3 (IEEE 1815) | `opendnp3` was archived read-only in Sept 2022; its successor `stepfunc/dnp3` prohibits commercial and production use |
+
+  Use an out-of-process gateway (61850 → OPC UA or MQTT) and read that with a
+  supported connector. A pull request adding any of the three as a dependency
+  will be declined however good the code is.
+
+## Standards claims
+
+Sort every claim into one of four buckets and keep it there:
+
+- **Implemented and tested** — ISO 13374 architecture, SunSpec model
+  conformance, IEC 63278-1 AAS submodel export.
+- **Aligned to, stated as design intent with a mapping table** — ISO 13381-1,
+  IEEE 1856-2017, IEC 61850-7-420 Ed. 2.0.
+- **Vocabulary borrowed, stated as vocabulary** — ISA-95 / IEC 62264,
+  ISO/IEC 9646, ISO 23247, ANSI/ISA-18.2.
+- **Never claimed** — IEEE 1547 / 1547.1 compliance, ISA/IEC 62443
+  certification, UL 1741 SB. **A library cannot be IEEE 1547 compliant; a DER
+  device can.** 1547.1 Clause 6 is an interoperability test performed on
+  hardware. Say what the code supports; never say what it is certified to.
+
+One claim in the wrong bucket undoes the argument the type test exists to make.
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+`[dev]` deliberately leaves out PyTorch — it is a ~2 GB download and only two
+test modules need it. They skip cleanly without it, and `test_without_torch.py`
+exists to keep that path green. If you are working on the learned models:
+
+```bash
+pip install -e ".[dev,nn]"
+```
+
+Doctests run as part of the suite, so every example in a docstring is executed.
+
+New code needs the test that would fail without it. In particular:
+
+- A new integrator needs an **energy-conservation** test, not only an accuracy
+  test. That distinction is the point of the package.
+- A new splitter needs a **leakage** test — a demonstration that no test index
+  precedes a train index it should not.
+- A new reference forecaster needs to be **genuinely hard to beat**. A straw man
+  makes every model look good and is worse than nothing.
+- A new connector needs a **simulator** so it can be tested in CI without
+  hardware, and the simulator must drive the same decode path as the real
+  source. A test that bypasses the decoder tests nothing.
+
+## Git
+
+Never commit to `main`. Every change opens a branch and a pull request.

otwin-0.2.0/LICENSE

@@ -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 Javier Marin
+
+   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.

otwin-0.2.0/MAINTAINERS.md

@@ -0,0 +1,52 @@
+# Maintainers
+
+| Name | GitHub | Scope |
+|---|---|---|
+| Javier Marin | [@Javihaus](https://github.com/Javihaus) | Everything, for now |
+
+## Two open maintainer slots
+
+The type test in [`otwin-spec`](https://github.com/otwin-core/otwin-spec) grades
+an implementation over a subprocess boundary, so it can judge a language this
+repository knows nothing about. That makes a second-language implementation a
+self-contained piece of work with an objective definition of done: **pass the
+abstract test suite, unmodified.**
+
+### Julia — open
+
+A minimal native core, not a wrapper. Julia has better tools for this than
+Python does — `ForwardDiff` for the energy gradient, `DifferentialEquations.jl`
+for the solver — so a wrapper would be worse than the thing it wraps.
+
+Scope is roughly a thousand lines: the energy-based model (`J`, `R`, `H`, `g`,
+power balance, structure checks), an energy-consistent integrator, manifest
+read and write, and the conformance adapter. Nothing else. Evaluation,
+estimation and uncertainty stay Python-only until someone asks, and the
+implementation declares that in its conformance statement rather than implying
+parity.
+
+### MATLAB — open
+
+Same scope, same test. Pure MATLAB: File Exchange refuses any submission
+containing MEX files or compiled binaries, and a toolbox that shells out to
+Python is useless to the Simulink and Simscape users who are the reason to ship
+MATLAB at all.
+
+### What being a maintainer means here, concretely
+
+- Review pull requests that touch your area. There will not be many.
+- Have an opinion when a design decision affects it.
+- You do **not** need to write code on a schedule.
+- You do **not** need to know the rest of the ecosystem.
+- You can stop whenever you like, and we will say so gracefully in this file.
+
+Open an issue titled `Maintainer: <your name>`, or email javier@jmarin.info. A
+short yes is enough to start a conversation.
+
+## Governance
+
+There is none yet, deliberately. A steering council of one person is theatre.
+
+When this project has two or more external maintainers we will adopt the
+standard NumFOCUS template, the same one [SciML](https://sciml.ai/governance/)
+uses.

otwin-0.2.0/NOTICE

@@ -0,0 +1,7 @@
+Otwin
+Copyright 2026 Javier Marin
+
+This product includes software developed as part of the Otwin project
+(https://github.com/otwin-core).
+
+Licensed under the Apache License, Version 2.0.