Resolve molecular hub vs valence-electron arity

Keep both declared relations: (center, ligand_electron_i) for the 3-structure
and (center_electron, ligand_electron) for the bond. Water again has a
degree-2 hub and a quaternion without installing (x,y,z).

Author: erinepshovel-code

research/epac/README.md

@@ -17,6 +17,8 @@ until a canonical `The-Interdependency/epac` source is created and pinned in
 - [`docs/arity.md`](docs/arity.md) — arity is declared dimensional coupling,
   not ambient dimension count. Charged oriented couplings plus degree are the
   three-dimensional structure.
+- [`docs/constraints.md`](docs/constraints.md) — standing constraints and
+  resolved contradictions for this candidate.
 - [`docs/preregistration-molecular-geometry-from-element-gonols.md`](docs/preregistration-molecular-geometry-from-element-gonols.md) —
   provisional candidate: Z=1–18 element gonols from atomic structure only, then
   affixiation of H₂, H₂O, NH₃, CH₄, CO₂ through unpaired valence electrons,

research/epac/docs/arity.md

@@ -25,10 +25,18 @@ Hydrogen-1 is one proton and no neutrons.
 At atomic scale the hub is that closed nucleus and every electron instance has
 its own `(nucleus, electron_i)` with slot charges `(Z, -1)`.
 
-Molecular scale promotes already-closed unpaired valence electrons as arity
-axes. Each bond is `(center_electron, ligand_electron)` with charges `(-1, -1)`.
-Closed atoms remain molecular participants. Nucleons and core electrons stay
-inside those atoms. Water is two valence-electron couplings, not `(O#2, H#0)`.
+Molecular scale has two declared relations:
+
+- 3-structure: hub is the closed center atom; every ligand unpaired valence
+  electron has `(center, ligand_e_i)`.
+- bond: unpaired valence electrons are arity-coupled as
+  `(center_e_i, ligand_e_i)` with charges `(-1, -1)`.
+
+Nucleons and core electrons stay inside closed atoms. Water's 3 is
+`(O#2, H0_e)` and `(O#2, H1_e)`, degree 2 on oxygen. That is not `(O#2, H#0)`
+atom-atom and not a ternary `(x,y,z)`.
+
+See `constraints.md`.
 
 Degree is required. For ambient `{x,y,z}` with couplings `(z,x)` and `(z,y)`:
 

research/epac/docs/constraints.md

@@ -0,0 +1,60 @@
+# EPAC constraint ledger
+
+Status: **provisional candidate**. Not org canon. Resolved means the constructor
+now obeys the listed rule. Unresolved remains `hmmm`.
+
+## Constraints that stand
+
+| Id | Constraint | Standing |
+|---|---|---|
+| C1 | `epac.public_gonol`, not `edcm.gonol` | resolved |
+| C2 | `(z,x) ≠ (x,z)` | resolved |
+| C3 | overlap is not a proof of `(x,y,z)` | resolved |
+| C4 | degree is required | resolved |
+| C5 | 3-structure = oriented couplings + charge state + degree | resolved at each scale that has a 3 |
+| C6 | representing a 3 takes 4 quaternion components; scalar is Möbius ε | resolved where a local 3 exists |
+| C7 | Hamilton product is not a coupling proof | resolved (forbidden rule) |
+| C8 | letters/abbreviations are not physics axes | resolved |
+| C9 | protons and neutrons are precursor gonols of the nucleus | resolved |
+| C10 | electrons couple to the closed nucleus; nucleons stay inside it | resolved |
+| C11 | closed gonols are atomic at the next scale; promotion is allowed | resolved |
+| C12 | molecular attachment consumes closed unpaired valence electrons, not `atomic_of` | resolved |
+| C13 | atomic s→p promotion is an atomic excited gonol, not VSEPR | resolved |
+| C14 | H₂ is a single binary and is not a 3 | resolved |
+| C15 | sealed chemistry shapes stay out of construction | resolved |
+| C16 | nothing bigger than atoms is an *input* to element construction | resolved |
+
+## Contradictions
+
+### X1 — molecular hub
+
+- C5/C6 and “every instance has `(z, x_i)` / `(z, y_j)`” require **one hub** with degree ≥ 2 to make a molecular 3.
+- “Valence electrons are arity coupled” was implemented as disjoint `(center_electron, ligand_electron)` pairs, each hub degree 1, so **no molecular 3**.
+
+**Resolution:** two declared relations, not one inferred from the other.
+
+1. **3-structure:** hub `z` is the closed center atom; instances are ligand unpaired valence electrons: `(center, ligand_e_i)`.
+2. **Bond:** unpaired valence electrons are arity-coupled to each other: `(center_e_i, ligand_e_i)`.
+
+Water: `deg(O#2)=2` on `(O#2, H0_e)` and `(O#2, H1_e)`; quaternion `(ε, 8, −1, −1)`. Bonds remain the two electron–electron couplings. Not `(x,y,z)`.
+
+### X2 — “do not reopen electrons” vs “electrons make molecules”
+
+**Resolution:** promote already-closed unpaired valence electron gonols as molecular *instances*. Do not flatten nucleons or core electrons into molecular axes.
+
+### X3 — consume atomic 3-structure vs formula-count geometry
+
+**Resolution:** composition still names which atoms. Attachment sites and charges come from closed gonols. Molecular 3 uses the closed center as hub and ligand valence electrons as instances.
+
+### X4 — internucleon `(every proton, every neutron)` vs no all-pairs authority
+
+**Unresolved / hmmm.** Bipartite `(proton, neutron)` is a declared nuclear candidate, not p–p or n–n fill, and not a selected nuclear force. Multiple proton hubs at nuclear scale is the same *shape* of question as X1 and is not closed here.
+
+## Usage
+
+After changing couplings, replay:
+
+```bash
+cd research/epac
+PYTHONPATH=".:../ucns/src" python3 -m unittest discover -s tests -q
+```

research/epac/docs/preregistration-molecular-geometry-from-element-gonols.md

@@ -31,7 +31,8 @@ proton gonols (charge +1) and neutron gonols (charge 0)
   -> close that atomic 3-structure inside the element gonol
   -> unpaired-valence electron gonols already closed inside each atom
   -> if needed, a closed promoted atomic gonol (same n s→p); no table re-lookup
-  -> declared oriented (center_electron, ligand_electron) arity-2 couplings with charges (-1, -1)
+  -> declared oriented (center_electron, ligand_electron) bond couplings with charges (-1, -1)
+  -> declared oriented (closed_center, ligand_electron_i) 3-structure; one hub, every instance
   -> molecular three-dimensional structure = those atom-instance couplings + charge states + degree
   -> each local 3 represented in 4 quaternion components (scalar ε plus the three axis charges)
   -> molecular Public Gonol (closed atoms remain atomic participants)

research/epac/epac_dimensional_arity.py

@@ -10,8 +10,11 @@
 physical instance of ``y`` has its own declared ``(z, y_j)``. A second
 occurrence is a second instance, not a reuse of the first coupling.
 ``(x_i, z)`` does not satisfy ``(z, x_i)``. Letters and abbreviations are
-not this domain. At atomic scale the instances are electrons and the hub is
-the nucleus. At molecular scale the instances are closed atom gonols.
+not this domain. At atomic scale the hub is the nucleus and the instances
+are electrons. At molecular scale the hub is the closed center atom and the
+instances are ligand unpaired valence electrons. Bond couplings between
+those valence electrons are a second declared relation, not a replacement
+hub.
 
 The three-dimensional structure is the combination of declared oriented
 couplings, their arity charge states, and degree. That span can involve three

research/epac/epac_molecular.py

@@ -1,10 +1,13 @@
-"""Molecular EPAC Public Gonols from closed valence-electron arity couplings.
+"""Molecular EPAC Public Gonols from closed atoms and valence-electron arity.
 
-Molecules are made where unpaired valence electrons couple. Each bond is a
-declared arity-2 coupling of two already-closed valence electron gonols:
-``(center_electron, ligand_electron)``. Closed atoms remain molecular
-participants; nucleons and core electrons stay inside them. The table is
-not re-queried.
+Two declared relations:
+
+- 3-structure: hub is the closed center atom; instances are ligand unpaired
+  valence electrons ``(center, ligand_e_i)``.
+- bond: those valence electrons couple as ``(center_e_i, ligand_e_i)``.
+
+Closed atoms remain molecular participants. Nucleons and core electrons stay
+inside them. The table is not re-queried.
 
 Construction uses ``epac.public_gonol``, not ``edcm.gonol``. No sealed
 molecular-shape file is opened here.
@@ -84,29 +87,43 @@ def _atom_dimension_id(gonol: ClosedPublicGonol) -> str:
     return f"{symbol_of(gonol)}#{gonol.occurrence}"
 
 
-def _declared_valence_space(
+def _declared_molecular_space(
+    *,
+    center: ClosedPublicGonol | None,
     bonds: tuple[tuple[ClosedPublicGonol, ClosedPublicGonol], ...],
 ):
-    """Arity-2 couplings of closed valence electrons. Atoms are not these axes."""
+    """Bond couplings plus, when a center exists, the molecular 3-structure.
+
+    Bonds: ``(center_electron, ligand_electron)``.
+    3-structure: ``(closed_center, ligand_electron_i)`` so one hub has every instance.
+    """
 
     ambient: list[str] = []
     charges: dict[str, int] = {}
     declarations: list[list[str]] = []
-    by_hub: dict[str, list[str]] = {}
+
+    def _add(axis_id: str, charge: int) -> None:
+        if axis_id not in charges:
+            ambient.append(axis_id)
+            charges[axis_id] = charge
+
     for hub_electron, instance_electron in bonds:
-        hub_id = hub_electron.source_id
-        instance_id = instance_electron.source_id
-        if hub_id not in charges:
-            ambient.append(hub_id)
-            charges[hub_id] = ELECTRON_CHARGE
-        if instance_id not in charges:
-            ambient.append(instance_id)
-            charges[instance_id] = ELECTRON_CHARGE
-        declarations.append([hub_id, instance_id])
-        by_hub.setdefault(hub_id, []).append(instance_id)
+        _add(hub_electron.source_id, ELECTRON_CHARGE)
+        _add(instance_electron.source_id, ELECTRON_CHARGE)
+        declarations.append([hub_electron.source_id, instance_electron.source_id])
+    ligand_ids = tuple(instance.source_id for _hub, instance in bonds)
+    if center is not None:
+        center_id = _atom_dimension_id(center)
+        _add(center_id, nuclear_charge(center))
+        for ligand_id in ligand_ids:
+            declarations.append([center_id, ligand_id])
     declared = space(ambient, declarations, charges=charges)
-    for hub_id, instance_ids in by_hub.items():
-        oriented_instance_couplings(declared, hub_id=hub_id, instance_ids=tuple(instance_ids))
+    if center is not None and ligand_ids:
+        oriented_instance_couplings(declared, hub_id=_atom_dimension_id(center), instance_ids=ligand_ids)
+    for hub_electron, instance_electron in bonds:
+        oriented_instance_couplings(
+            declared, hub_id=hub_electron.source_id, instance_ids=(instance_electron.source_id,)
+        )
     return declared
 
 
@@ -234,8 +251,13 @@ def construct_molecule(formula: str) -> MolecularConstruction:
         center_attachment_ids = tuple(electron.source_id for electron in center_electrons)
         ligand_attachment_ids = tuple(_attachment_electron_ids(item) for item in ligands)
     mobius = _mobius_coupling(bonds=bonds)
-    dimensional = _declared_valence_space(bonds)
-    instance_couplings = tuple((hub.source_id, instance.source_id) for hub, instance in bonds)
+    dimensional = _declared_molecular_space(center=center, bonds=bonds)
+    valence_electron_bonds = tuple((hub.source_id, instance.source_id) for hub, instance in bonds)
+    instance_couplings = (
+        tuple((_atom_dimension_id(center), instance.source_id) for _hub, instance in bonds)
+        if center is not None
+        else valence_electron_bonds
+    )
     geometry = geometry_from_declared_couplings(dimensional)
     receipt = construct_public_gonol(
         source_id=f"epac.molecule:{formula}",
@@ -292,6 +314,7 @@ def construct_molecule(formula: str) -> MolecularConstruction:
         "charged_structure_readout": charged_structure_readout(geometry["structure"]),
         "topology_structure_readout": topology_structure_readout(geometry["structure"]),
         "oriented_instance_couplings": instance_couplings,
+        "valence_electron_bonds": valence_electron_bonds,
     }
     return MolecularConstruction(formula=formula, receipt=receipt, invariants=invariants)
 

research/epac/tests/test_geometry_comparison_after_construction.py

@@ -28,8 +28,8 @@ def test_charged_couplings_are_the_three_dimensional_structure(self) -> None:
         carbon_dioxide = constructions["CO2"].receipt.structure
         self.assertIsNotNone(water)
         self.assertIsNotNone(carbon_dioxide)
-        self.assertEqual(water["participating_dimension_count"], 4)
-        self.assertEqual(carbon_dioxide["participating_dimension_count"], 8)
+        self.assertEqual(water["participating_dimension_count"], 5)
+        self.assertEqual(carbon_dioxide["participating_dimension_count"], 9)
         self.assertFalse(water["ternary_coupling_declared"])
         self.assertNotEqual(
             topology_structure_readout(water),
@@ -38,13 +38,13 @@ def test_charged_couplings_are_the_three_dimensional_structure(self) -> None:
         water_charged = charged_structure_readout(water)
         co2_charged = charged_structure_readout(carbon_dioxide)
         self.assertNotEqual(water_charged, co2_charged)
-        self.assertEqual(len(water_charged[0]), 2)
-        self.assertTrue(all(part[0] == 2 and part[1] == ((-1, -1), 1) for part in water_charged[0]))
+        self.assertEqual(len(water_charged[0]), 4)
+        self.assertTrue(all(part[0] == 2 for part in water_charged[0]))
+        self.assertTrue(any(part[2][0] == "O#2" for part in water_charged[0]))
         self.assertTrue(
-            all(name.startswith("epac.electron:") for part in water_charged[0] for name in part[2])
+            any(name.startswith("epac.electron:") for part in water_charged[0] for name in part[2])
         )
-        self.assertEqual(len(co2_charged[0]), 4)
-        self.assertTrue(all(part[0] == 2 and part[1] == ((-1, -1), 1) for part in co2_charged[0]))
+        self.assertEqual(len(co2_charged[0]), 8)
 
     def test_sealed_shape_comparison_uses_charged_structure(self) -> None:
         constructions = construct_declared_molecules()

research/epac/tests/test_molecular_affixiation.py

@@ -43,45 +43,45 @@ def test_unpaired_valence_and_shells_are_used(self) -> None:
     def test_declared_couplings_are_binary_and_do_not_fill_ambient(self) -> None:
         molecules = construct_declared_molecules()
         water = molecules["H2O"].invariants["dimensional_geometry"]
-        self.assertEqual(water["ambient_count"], 4)
-        self.assertEqual([c["arity"] for c in water["couplings"]], [2, 2])
+        self.assertEqual(water["ambient_count"], 5)
+        self.assertEqual(len(water["couplings"]), 4)
+        self.assertTrue(all(c["arity"] == 2 for c in water["couplings"]))
         ids = [c["declared_ids"] for c in water["couplings"]]
-        self.assertEqual(len(ids), 2)
         self.assertTrue(all(len(item) == 2 for item in ids))
-        self.assertTrue(all(name.startswith("epac.electron:") for pair in ids for name in pair))
         methane = molecules["CH4"].invariants["dimensional_geometry"]
-        self.assertEqual(methane["ambient_count"], 8)
-        self.assertEqual([c["arity"] for c in methane["couplings"]], [2, 2, 2, 2])
+        self.assertEqual(len(methane["couplings"]), 8)
         self.assertFalse(any(c["arity"] == 5 for c in methane["couplings"]))
         self.assertFalse(methane["inferred_from_ambient"])
         self.assertFalse(methane["inferred_higher_arity_from_overlap"])
-        self.assertEqual(water["structure"]["participating_dimension_count"], 4)
+        self.assertEqual(water["structure"]["participating_dimension_count"], 5)
         self.assertFalse(water["structure"]["ternary_coupling_declared"])
         self.assertFalse(water["structure"]["inferred_cartesian_embedding"])
-        self.assertEqual(water["couplings"][0]["slot_charges"], (-1, -1))
-        self.assertEqual(methane["couplings"][0]["slot_charges"], (-1, -1))
         water_receipt = molecules["H2O"].receipt
         self.assertEqual(water_receipt.constructor_id, "epac.public_gonol")
-        self.assertEqual(len(water_receipt.structure["parts"]), 2)
+        self.assertEqual(len(water_receipt.structure["parts"]), 4)
         water_instances = molecules["H2O"].invariants["oriented_instance_couplings"]
         self.assertEqual(len(water_instances), 2)
-        self.assertTrue(all(item[0].startswith("epac.electron:O#2:") for item in water_instances))
+        self.assertEqual({item[0] for item in water_instances}, {"O#2"})
         self.assertEqual(
             [item[1] for item in water_instances],
             ["epac.electron:H#0:0", "epac.electron:H#1:0"],
         )
+        self.assertEqual(len(molecules["H2O"].invariants["valence_electron_bonds"]), 2)
+        self.assertTrue(
+            all(item[0].startswith("epac.electron:O#2:") for item in molecules["H2O"].invariants["valence_electron_bonds"])
+        )
         methane_instances = molecules["CH4"].invariants["oriented_instance_couplings"]
         self.assertEqual(len(methane_instances), 4)
-        self.assertTrue(all(item[0].startswith("epac.electron:C#0:") for item in methane_instances))
+        self.assertTrue(all(item[0] == "C#0" for item in methane_instances))
         self.assertEqual(
             [item[1] for item in methane_instances],
             ["epac.electron:H#1:0", "epac.electron:H#2:0", "epac.electron:H#3:0", "epac.electron:H#4:0"],
         )
         self.assertEqual(len(molecules["H2"].invariants["oriented_instance_couplings"]), 1)
         water_ids = {name for part in water_receipt.structure["parts"] for name in part["coupling"]}
-        self.assertTrue(all(name.startswith("epac.electron:") for name in water_ids))
-        self.assertNotIn("O#2", water_ids)
+        self.assertIn("O#2", water_ids)
         self.assertNotIn("H#0", water_ids)
+        self.assertTrue(any(name.startswith("epac.electron:H#0:") for name in water_ids))
         oxygen = next(
             item
             for item in water_receipt.gonol.participants
@@ -109,11 +109,10 @@ def test_declared_couplings_are_binary_and_do_not_fill_ambient(self) -> None:
         self.assertNotIn("atomic_of", source)
         self.assertNotIn("from epac_atomic", source)
         self.assertEqual(water_receipt.structure["representation_dimension"], 4)
-        self.assertEqual(water_receipt.structure["participating_dimension_count"], 4)
-        self.assertEqual(quaternion_structure_readout(water_receipt.structure), ())
-        self.assertEqual(quaternion_structure_readout(molecules["CO2"].receipt.structure), ())
+        self.assertEqual(water_receipt.structure["participating_dimension_count"], 5)
+        water_quat = quaternion_structure_readout(water_receipt.structure)
+        self.assertTrue(any(item[1][0] == "O#2" for item in water_quat))
         self.assertEqual(quaternion_structure_readout(molecules["H2"].receipt.structure), ())
-        self.assertEqual(quaternion_structure_readout(molecules["CH4"].receipt.structure), ())
 
     def test_ucns_coupling_binds_declared_attachments(self) -> None:
         molecules = construct_declared_molecules()