oraql-atoms 0.1.0__tar.gz

oraql_atoms-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+__marimo__/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+.DS_Store
+third_party/papers/
+docs/notes/*.bbl

oraql_atoms-0.1.0/LICENSE

@@ -0,0 +1,204 @@
+                                 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 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 The oraql-stack Authors.
+
+   For a list of copyright holders, see the AUTHORS file at the root of
+   this repository.
+
+   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.

oraql_atoms-0.1.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.5
+Name: oraql-atoms
+Version: 0.1.0
+Summary: Neutral-atom device profiles (L1) and pulse-level noise models with Pauli twirling (L2)
+Project-URL: Repository, https://github.com/oraql-stack/oraql-stack
+Project-URL: Documentation, https://github.com/oraql-stack/oraql-stack/blob/main/docs/modularity.md
+Author: The oraql-stack Authors
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.12
+Requires-Dist: numpy>=2.2
+Requires-Dist: scipy>=1.18
+Provides-Extra: atomic-data
+Requires-Dist: arc-alkali-rydberg-calculator>=3.10; extra == 'atomic-data'
+Requires-Dist: pulser-core>=1.9; extra == 'atomic-data'
+Description-Content-Type: text/markdown
+
+# oraql-atoms
+
+Neutral-atom device profiles (L1) and pulse-level noise models with Pauli twirling (L2).
+
+L1: published device profiles with units and provenance (`oraql.physical`). L2: a four-level atom Lindblad model of the native gates, twirled to Pauli and loss channels, and calibration updates (`oraql.pulse`). Produces `PhysicalParameters` and `CalibrationRecord` documents.
+
+Import as `oraql.physical, oraql.pulse`. Part of [oraql-stack](https://github.com/oraql-stack/oraql-stack), a layered software stack for neutral-atom quantum computers; the packages exchange only the contract documents of `oraql-contracts` and share one version. Apache-2.0.

oraql_atoms-0.1.0/README.md

@@ -0,0 +1,7 @@
+# oraql-atoms
+
+Neutral-atom device profiles (L1) and pulse-level noise models with Pauli twirling (L2).
+
+L1: published device profiles with units and provenance (`oraql.physical`). L2: a four-level atom Lindblad model of the native gates, twirled to Pauli and loss channels, and calibration updates (`oraql.pulse`). Produces `PhysicalParameters` and `CalibrationRecord` documents.
+
+Import as `oraql.physical, oraql.pulse`. Part of [oraql-stack](https://github.com/oraql-stack/oraql-stack), a layered software stack for neutral-atom quantum computers; the packages exchange only the contract documents of `oraql-contracts` and share one version. Apache-2.0.

oraql_atoms-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "oraql-atoms"
+version = "0.1.0"     # one version for every oraql package (docs/releasing.md)
+description = "Neutral-atom device profiles (L1) and pulse-level noise models with Pauli twirling (L2)"
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+authors = [{ name = "The oraql-stack Authors" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "numpy>=2.2",
+    "scipy>=1.18",
+]
+
+[project.optional-dependencies]
+# only to regenerate oraql/physical/data/atomic_data.json
+atomic-data = ["ARC-Alkali-Rydberg-Calculator>=3.10", "pulser-core>=1.9"]
+
+[project.urls]
+Repository = "https://github.com/oraql-stack/oraql-stack"
+Documentation = "https://github.com/oraql-stack/oraql-stack/blob/main/docs/modularity.md"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/oraql"]       # PEP 420 namespace: no oraql/__init__.py

oraql_atoms-0.1.0/src/oraql/physical/atomic_data.py

@@ -0,0 +1,76 @@
+"""Atomic data from ARC (survey row 15) for the Rydberg and intermediate states of every L1 profile.
+
+`python -m oraql.physical.atomic_data` writes oraql/physical/data/atomic_data.json (package data, read by oraql.physical.profiles for `computed` entries)
+and design/atomic_data.log (ARC value next to the cited value). ARC is only needed to regenerate the JSON.
+Sign convention: ARC returns C6 with V(R) = -C6/R^6; we store C6 with V(R) = +C6/R^6 (repulsive > 0).
+"""
+from __future__ import annotations
+import json
+from importlib.resources import files
+
+DATA = files("oraql.physical") / "data" / "atomic_data.json"
+
+# state per profile: atom class, Rydberg (n, l, j, mj), intermediate (n, l, j), temperature
+STATES = {
+    "Rb87_53S": dict(atom="Rubidium87", ryd=(53, 0, 0.5, 0.5), inter=(6, 1, 1.5), T=300.0),
+    "Cs133_69S": dict(atom="Caesium", ryd=(69, 0, 0.5, -0.5), inter=(7, 1, 0.5), T=300.0),
+}
+
+# cited value to compare with: (quantity, value, source)
+CITED = {
+    "Rb87_53S": {"c6_ghz_um6": (28.8, "arXiv:2304.05420 p.10, derived from V(2 um) = 450 MHz"),
+                 "rydberg_lifetime_us": (88.0, "arXiv:2304.05420 Ext. Data Fig. 3a, measured T1 minus 1013 scattering"),
+                 "rydberg_lifetime_rad_us": (170.0, "arXiv:2304.05420 Ext. Data Fig. 3a, rescaled to n=53"),
+                 "intermediate_lifetime_ns": (110.0, "arXiv:2304.05420 Ext. Data Fig. 3a, value used in simulation")},
+    "Cs133_69S": {"c6_ghz_um6": (10.3e-3 * 6 ** 6, "arXiv:2408.08288 p.5, derived from V = 10.3 MHz at 6 um")},
+}
+
+
+def compute() -> dict:
+    import arc
+    from arc import PairStateInteractions
+    out = {"arc_version": arc.__version__, "states": {}}
+    for key, s in STATES.items():
+        atom = getattr(arc, s["atom"])()
+        n, l, j, mj = s["ryd"]
+        ni, li, ji = s["inter"]
+        c6 = PairStateInteractions(atom, n, l, j, n, l, j, mj, mj).getC6perturbatively(0, 0, 5, 25e9)
+        d = {
+            "c6_ghz_um6": {"value": -float(c6), "method": f"ARC {arc.__version__} PairStateInteractions({s['atom']},{n},{l},{j},{n},{l},{j},{mj},{mj}).getC6perturbatively(0,0,5,25e9), sign flipped to V=+C6/r^6"},
+            "rydberg_lifetime_us": {"value": atom.getStateLifetime(n, l, j, temperature=s["T"], includeLevelsUpTo=n + 30) * 1e6,
+                                    "method": f"ARC {arc.__version__} {s['atom']}.getStateLifetime({n},{l},{j},temperature={s['T']:g},includeLevelsUpTo={n + 30})"},
+            "rydberg_lifetime_rad_us": {"value": atom.getStateLifetime(n, l, j, temperature=0) * 1e6,
+                                        "method": f"ARC {arc.__version__} {s['atom']}.getStateLifetime({n},{l},{j},temperature=0)"},
+            "intermediate_lifetime_ns": {"value": atom.getStateLifetime(ni, li, ji) * 1e9,
+                                         "method": f"ARC {arc.__version__} {s['atom']}.getStateLifetime({ni},{li},{ji})"},
+        }
+        out["states"][key] = d
+    out["pulser"] = pulser_c6(arc)
+    return out
+
+
+def pulser_c6(arc) -> list[dict]:
+    """Pulser device C6 (interaction_coeff, rad/us um^6) against ARC for the same Rb nS state."""
+    try:
+        import importlib.metadata as md
+        from pulser.devices import AnalogDevice, DigitalAnalogDevice
+        from arc import PairStateInteractions
+    except ImportError:
+        return []
+    rows = []
+    for dev in (AnalogDevice, DigitalAnalogDevice):
+        n = dev.rydberg_level
+        c6_arc = -PairStateInteractions(arc.Rubidium87(), n, 0, 0.5, n, 0, 0.5, 0.5, 0.5).getC6perturbatively(0, 0, 5, 25e9)
+        c6_p = dev.interaction_coeff / (2 * 3.141592653589793) / 1e3      # rad/us um^6 -> GHz um^6
+        rows.append({"device": f"pulser-core {md.version('pulser-core')} {dev.name}", "n": n, "c6_pulser_ghz_um6": c6_p,
+                     "c6_arc_ghz_um6": float(c6_arc), "min_atom_distance_um": dev.min_atom_distance})
+    return rows
+
+
+def load() -> dict:
+    return json.loads(DATA.read_text())
+
+
+def value(state: str, qty: str) -> tuple[float, str]:
+    e = load()["states"][state][qty]
+    return e["value"], e["method"]

oraql_atoms-0.1.0/src/oraql/physical/data/atomic_data.json

@@ -0,0 +1,57 @@
+{
+ "arc_version": "3.10.2",
+ "states": {
+  "Rb87_53S": {
+   "c6_ghz_um6": {
+    "value": 31.269203001890368,
+    "method": "ARC 3.10.2 PairStateInteractions(Rubidium87,53,0,0.5,53,0,0.5,0.5,0.5).getC6perturbatively(0,0,5,25e9), sign flipped to V=+C6/r^6"
+   },
+   "rydberg_lifetime_us": {
+    "value": 72.5936324889618,
+    "method": "ARC 3.10.2 Rubidium87.getStateLifetime(53,0,0.5,temperature=300,includeLevelsUpTo=83)"
+   },
+   "rydberg_lifetime_rad_us": {
+    "value": 155.04886242543142,
+    "method": "ARC 3.10.2 Rubidium87.getStateLifetime(53,0,0.5,temperature=0)"
+   },
+   "intermediate_lifetime_ns": {
+    "value": 118.14274517914511,
+    "method": "ARC 3.10.2 Rubidium87.getStateLifetime(6,1,1.5)"
+   }
+  },
+  "Cs133_69S": {
+   "c6_ghz_um6": {
+    "value": 538.0115284047206,
+    "method": "ARC 3.10.2 PairStateInteractions(Caesium,69,0,0.5,69,0,0.5,-0.5,-0.5).getC6perturbatively(0,0,5,25e9), sign flipped to V=+C6/r^6"
+   },
+   "rydberg_lifetime_us": {
+    "value": 134.3744320195675,
+    "method": "ARC 3.10.2 Caesium.getStateLifetime(69,0,0.5,temperature=300,includeLevelsUpTo=99)"
+   },
+   "rydberg_lifetime_rad_us": {
+    "value": 328.6203010400251,
+    "method": "ARC 3.10.2 Caesium.getStateLifetime(69,0,0.5,temperature=0)"
+   },
+   "intermediate_lifetime_ns": {
+    "value": 154.36819436296378,
+    "method": "ARC 3.10.2 Caesium.getStateLifetime(7,1,0.5)"
+   }
+  }
+ },
+ "pulser": [
+  {
+   "device": "pulser-core 1.9.1 AnalogDevice",
+   "n": 60,
+   "c6_pulser_ghz_um6": 137.78409798144378,
+   "c6_arc_ghz_um6": 138.88273417699025,
+   "min_atom_distance_um": 5
+  },
+  {
+   "device": "pulser-core 1.9.1 DigitalAnalogDevice",
+   "n": 70,
+   "c6_pulser_ghz_um6": 862.6450223912011,
+   "c6_arc_ghz_um6": 862.7244161203786,
+   "min_atom_distance_um": 4
+  }
+ ]
+}

oraql_atoms-0.1.0/src/oraql/physical/physical.py

@@ -0,0 +1,213 @@
+"""L1 physical parameter store: named device profiles with units and provenance.
+
+Profiles live in packages/oraql-atoms/src/oraql/physical/profiles/ (one module per published device). Every entry has a unit and a source in
+{citation, computed, assumed, calibrated}. `load(profile)` returns an immutable `Params`; every function takes it as
+`params` (None: the default profile, rb87_evered2023). There is no module state: a calibration update returns a new
+`Params` (`Params.replace`, `oraql.pulse.calibration.apply_updates`).
+`python -m oraql.physical.physical` checks every profile, prints the C6/r^6 evaluation and writes
+packages/oraql-contracts/src/oraql/contracts/data/schemas/examples/PhysicalParameters_<profile>.json (the default also as PhysicalParameters_rb87.json).
+"""
+from __future__ import annotations
+import dataclasses, functools, json, math, hashlib
+from oraql.physical.profiles._entry import P
+from oraql.physical import profiles as _profiles
+
+# names the twirl, calibration and scheduler read; every profile must define all of them
+CORE = [
+    "hyperfine_splitting_mhz", "atom_mass_amu", "rydberg_n",
+    "c6_ghz_um6", "gate_spacing_um", "rabi_two_photon_mhz", "rabi_lower_mhz", "rabi_upper_mhz", "intermediate_detuning_ghz",
+    "t2_ground_us", "t2star_ground_us", "t1_ground_us", "t2star_rydberg_us", "rydberg_lifetime_us", "intermediate_lifetime_ns",
+    "rabi_rel_sigma", "laser_linewidth_khz",
+    "rydberg_branch_loss", "rydberg_branch_to_1", "rydberg_branch_to_0",
+    "intermediate_branch_loss", "intermediate_branch_to_1", "intermediate_branch_to_0", "leak_trapped_fraction", "leak_reads_one",
+    "rydberg_branch_bbr_fraction", "rydberg_ejection_us",
+    "trap_lifetime_s", "trap_depth_mk",
+    "atom_temperature_uk", "move_duration_us", "move_loss_prob", "move_heating_quanta", "move_heating_kappa", "reset_recools_motion", "feedforward_latency_us",
+    "position_sigma_um",
+    "global_pulse_duration_us", "local_pulse_duration_us", "single_qubit_depol_error", "raman_scattering_error",
+    "readout_duration_us", "readout_fidelity", "readout_flip_0to1", "readout_flip_1to0", "readout_loss_prob", "reset_error",
+    "local_imaging_dephasing", "cz_fidelity_measured",
+]
+SOURCES = ("citation", "computed", "assumed", "calibrated")
+
+PROFILES = {m.PROFILE_ID: m for m in _profiles.MODULES}
+DEFAULT = _profiles.DEFAULT
+TABLES = {pid: m.table() for pid, m in PROFILES.items()}
+
+
+
+@dataclasses.dataclass(frozen=True, eq=False)
+class Params:
+    """One profile's parameter entries. Immutable: `replace` and `calibrated` return new objects. Equal and hashable by
+    profile id and values, so it can key caches."""
+    profile_id: str
+    entries: tuple
+    species: str = ""
+
+    def __post_init__(self):
+        object.__setattr__(self, "_by", {p.name: p for p in self.entries})
+
+    def get(self, name: str) -> float:
+        return self._by[name].value
+
+    def entry(self, name: str) -> P:
+        return dataclasses.replace(self._by[name])
+
+    def replace(self, source: str | None = None, **values) -> "Params":
+        """Copy with `values` ({name: value}) changed; `source` also sets their source (e.g. "calibrated")."""
+        unknown = set(values) - set(self._by)
+        if unknown:
+            raise KeyError(f"not in profile {self.profile_id}: {sorted(unknown)}")
+        new = tuple(dataclasses.replace(p, value=values[p.name], **({"source": source} if source else {})) if p.name in values else p
+                    for p in self.entries)
+        return Params(self.profile_id, new, self.species)
+
+    def key(self) -> tuple:
+        return (self.profile_id,) + tuple((p.name, p.value, p.source) for p in self.entries)
+
+    def __eq__(self, other):
+        return isinstance(other, Params) and self.key() == other.key()
+
+    def __hash__(self):
+        return hash(self.key())
+
+
+@functools.cache
+def _load(profile: str) -> Params:
+    return Params(profile, tuple(dataclasses.replace(p) for p in TABLES[profile]), PROFILES[profile].SPECIES)
+
+
+DERIVED = ("blockade_radius_um",)          # in PhysicalParameters documents, computed from the entries, never read back
+ADDED = ("leak_trapped_fraction", "leak_reads_one",     # CORE names added after 0.1.0; from_document fills them in
+         "rydberg_branch_bbr_fraction", "rydberg_ejection_us")
+
+
+def from_document(doc: dict) -> Params:
+    """Parameters from a PhysicalParameters document (e.g. a lab's measured values under its own profile id). Every
+    CORE name must be present; derived entries are skipped. Validate the document against its schema first
+    (oraql.contracts.schema)."""
+    fields = {f.name for f in dataclasses.fields(P)}
+    entries = tuple(P(**{k: v for k, v in e.items() if k in fields}) for e in doc["parameters"] if e["name"] not in DERIVED)
+    have = {e.name for e in entries}
+    if any(n not in have for n in ADDED):              # documents written before these names existed
+        base = next((pid for pid, m in PROFILES.items() if m.SPECIES == doc.get("species")), DEFAULT)
+        entries += tuple(dataclasses.replace(load(base).entry(n), source="assumed",
+                                             note=f"absent from the document; value of profile {base}")
+                         for n in ADDED if n not in have)
+    missing = [n for n in CORE if n not in {e.name for e in entries}]
+    if missing:
+        raise KeyError(f"PhysicalParameters document {doc.get('profile_id')!r} lacks {missing}")
+    return Params(doc["profile_id"], entries, doc.get("species", ""))
+
+
+def load(profile: str | None = None) -> Params:
+    """Parameters of `profile` (default DEFAULT)."""
+    return _load(profile or DEFAULT)
+
+
+def resolve(params: Params | str | None) -> Params:
+    """`params` as a Params: None is the default profile, a string a profile id."""
+    return params if isinstance(params, Params) else load(params)
+
+
+def get(name: str, params: Params | None = None) -> float:
+    return resolve(params).get(name)
+
+
+# ---------------------------------------------------------------- derived quantities
+def interaction_mhz(r_um: float, c6_ghz_um6: float | None = None, params: Params | None = None) -> float:
+    """V(r)/2pi = C6/2pi / r^6 in MHz (C6 given in GHz um^6)."""
+    c6 = get("c6_ghz_um6", params) if c6_ghz_um6 is None else c6_ghz_um6
+    return c6 * 1e3 / r_um ** 6
+
+
+def blockade_radius_um(c6_ghz_um6: float | None = None, omega_mhz: float | None = None, params: Params | None = None) -> float:
+    """R_b = (C6/Omega)^(1/6), definition V(R_b) = Omega."""
+    c6 = get("c6_ghz_um6", params) if c6_ghz_um6 is None else c6_ghz_um6
+    om = get("rabi_two_photon_mhz", params) if omega_mhz is None else omega_mhz
+    return (c6 * 1e3 / om) ** (1 / 6)
+
+
+def rates(params: Params | None = None) -> dict:
+    """Effective rates in 1/us derived from the profile (used by oraql.pulse.twirl)."""
+    get = resolve(params).get
+    d = {}
+    d["gamma_r"] = 1.0 / get("rydberg_lifetime_us")
+    d["gamma_phi_r"] = 1.0 / get("t2star_rydberg_us")          # exponential stand-in for quasi-static noise
+    tau_e = get("intermediate_lifetime_ns") * 1e-3
+    D = get("intermediate_detuning_ghz") * 1e3
+    d["gamma_sc_1"] = (get("rabi_lower_mhz") / (2 * D)) ** 2 / tau_e   # bright-state admixture x Gamma_e, 1/us
+    d["gamma_sc_r"] = (get("rabi_upper_mhz") / (2 * D)) ** 2 / tau_e
+    d["gamma_phi_g"] = 1.0 / get("t2_ground_us")
+    d["gamma_1_g"] = 1.0 / get("t1_ground_us")
+    d["gamma_laser"] = 2 * math.pi * get("laser_linewidth_khz") * 1e-3   # white frequency noise, FWHM -> |r> dephasing rate
+    d["omega_rad_us"] = 2 * math.pi * get("rabi_two_photon_mhz")
+    d["V_rad_us"] = 2 * math.pi * interaction_mhz(get("gate_spacing_um"), get("c6_ghz_um6"))
+    return d
+
+
+def _entry(p: P) -> dict:
+    e = {"name": p.name, "value": p.value, "unit": p.unit, "source": p.source}
+    for k in ("citation", "method", "locator", "note"):
+        if getattr(p, k):
+            e[k] = getattr(p, k)
+    if p.valid_lo is not None: e["valid_lo"] = p.valid_lo
+    if p.valid_hi is not None: e["valid_hi"] = p.valid_hi
+    return e
+
+
+def to_document(sites=None, params: Params | str | None = None) -> dict:
+    """The `PhysicalParameters` contract document of `params` (a Params, a profile id or None for the default)."""
+    pr = resolve(params)
+    s = pr.get("gate_spacing_um")
+    sites = sites or [{"id": 0, "x": 0.0, "y": 0.0, "zone": "entangling", "trap": "tweezer_array"},
+                      {"id": 1, "x": s, "y": 0.0, "zone": "entangling", "trap": "tweezer_array"}]
+    ents = [_entry(p) for p in pr.entries]
+    rb = P("blockade_radius_um", round(blockade_radius_um(params=pr), 4), "um", "computed", note="derived, never stored: V(R_b) = Omega",
+           valid_lo=1, valid_hi=20, method="oraql.physical.physical.blockade_radius_um: (C6/Omega)^(1/6)")
+    ents.append(_entry(rb))
+    return {"schema_version": "0.1.0", "profile_id": pr.profile_id, "species": pr.species or (PROFILES[pr.profile_id].SPECIES if pr.profile_id in PROFILES else ""), "sites": sites, "parameters": ents}
+
+
+def doc_hash(doc: dict) -> str:
+    return hashlib.sha256(json.dumps(doc, sort_keys=True).encode()).hexdigest()
+
+
+def counts(profile: str | None = None) -> dict:
+    t = TABLES[profile or DEFAULT]
+    return {s: sum(p.source == s for p in t) for s in SOURCES} | {"entries": len(t)}
+
+
+def markdown_table(profile: str | None = None) -> str:
+    """One row per entry of to_document(), including the derived blockade radius."""
+    rows = ["| Name | Value | Unit | Source | Citation or method, locator, note |", "|---|---|---|---|---|"]
+    for e in to_document(params=profile)["parameters"]:
+        ref = e.get("citation", "") if e["source"] == "citation" else e.get("method", "")
+        loc = f" ({e['locator']})" if e.get("locator") else ""
+        c = (ref + loc + (". " if ref and e.get("note") else "") + e.get("note", "")).replace("|", "/")
+        rows.append(f"| `{e['name']}` | {e['value']:g} | {e['unit']} | {e['source']} | {c} |")
+    return "\n".join(rows)
+
+
+def check(profile: str) -> list[str]:
+    """Rule checks for one profile; returns failure messages (empty = pass)."""
+    bad = []
+    t = TABLES[profile]
+    names = [p.name for p in t]
+    bad += [f"missing core name {n}" for n in CORE if n not in names]
+    bad += [f"unexpected name {n}" for n in names if n not in CORE]
+    bad += [f"duplicate name {n}" for n in set(names) if names.count(n) > 1]
+    for p in t:
+        if not p.unit: bad.append(f"{p.name}: no unit")
+        if p.source not in SOURCES: bad.append(f"{p.name}: source {p.source}")
+        if p.source == "citation" and not p.citation: bad.append(f"{p.name}: citation missing")
+        if p.source == "computed" and not p.method: bad.append(f"{p.name}: method missing")
+        if p.source == "assumed" and not p.note: bad.append(f"{p.name}: assumed without a reason")
+        if p.valid_lo is not None and not (p.valid_lo <= p.value <= p.valid_hi): bad.append(f"{p.name}: {p.value} outside [{p.valid_lo}, {p.valid_hi}]")
+    get = load(profile).get
+    for pre in ("rydberg", "intermediate"):
+        s = sum(get(f"{pre}_branch_{k}") for k in ("loss", "to_1", "to_0"))
+        if abs(s - 1) > 1e-3: bad.append(f"{pre} branching sums to {s}")
+    f = get("readout_fidelity"); fl = get("readout_flip_0to1") + get("readout_flip_1to0")
+    if abs((1 - f) - fl) > 1e-6: bad.append(f"readout flips {fl} != 1 - F = {1 - f}")
+    return bad

oraql_atoms-0.1.0/src/oraql/physical/profiles/__init__.py

@@ -0,0 +1,5 @@
+"""Named L1 device profiles. Each module defines PROFILE_ID, SPECIES, TITLE, REFERENCES and table()."""
+from oraql.physical.profiles import rb87_evered2023, rb87_bluvstein2024, cs133_radnaev2024
+
+MODULES = [rb87_evered2023, rb87_bluvstein2024, cs133_radnaev2024]
+DEFAULT = rb87_evered2023.PROFILE_ID