Charge Boundary Routing I
build_charge_ladders.py
README

Purpose
-------

This script generates numeric CSV ladder files from the verified Phase 1
canonical corpus.

Input:

    data/derived/charge_boundary_phase1_combined.csv

Outputs:

    ladders/
        layerA_external_charge_ladder_*.csv
        layerB_fractional_charge_ladder_*.csv
        layerC_composite_closure_ladder_*.csv
        layerD_boundary_absence_ladder_*.csv
        ABCD_charge_boundary_ladder_*.csv

    ladders/one_column/
        one-column versions of every ladder file for easy chamber upload

    ladders/diagnostics/
        charge_ladder_generation_summary.json
        charge_ladder_generation_report.txt


Where to Place the Script
-------------------------

Place the script here:

    charge_boundary_routing_i/
    └── scripts/
        └── build_charge_ladders.py


How to Run
----------

From the project root:

    cd "path\to\charge_boundary_routing_i"
    python scripts\build_charge_ladders.py


Expected Input State
--------------------

Before running this script, the verified corpus must already exist:

    data/derived/charge_boundary_phase1_combined.csv

That file is generated by:

    scripts/build_phase1_verified_corpus.py


Generated Encodings
-------------------

For each layer and for the combined ABCD corpus, the script creates six ladder encodings:

1. signed_charge

    Uses Q/e directly where numeric.

    Examples:
        -1
        -2/3
        -1/3
         0
        +1/3
        +2/3
        +1

    Best first use:
        raw electric-charge lattice tests.

2. absolute_charge

    Uses |Q/e|.

    Best first use:
        neutral / fractional / unit / double-unit closure comparison
        independent of sign.

3. closure_class_code

    Encodes UNNS closure class as an ordered numeric code.

    Code map:
        FREE_NEUTRAL_CLOSURE                   = 0
        FREE_INTEGER_CLOSURE                   = 1
        INTERNAL_FRACTIONAL_COORDINATE         = 2
        COMPOSITE_NEUTRAL_CLOSURE              = 3
        COMPOSITE_INTEGER_CLOSURE              = 4
        TERMINAL_FREE_FRACTIONAL               = 5
        UNRESOLVED_DUAL_BOUNDARY               = 6
        CONSTRAINED_NEUTRALITY_BOUNDARY        = 7
        CONSTRAINED_CHARGE_VIOLATION_BOUNDARY  = 8

4. route_class_code

    Encodes UNNS route class.

    Code map:
        EXTERNAL_CLOSURE          = 0
        CONFINED_ROUTE            = 1
        COMPOSITE_CLOSURE         = 2
        BOUNDARY_ABSENCE          = 3
        DUAL_BOUNDARY_CANDIDATE   = 4
        BOUNDARY_CONSTRAINT       = 5

5. boundary_route_coordinate

    Encodes a provisional route-topology coordinate.

    This is not a direct physical observable. It is a structural coordinate for
    testing charge-boundary routing.

6. closure_state_code

    Encodes whether a row is closed, internally fractional, not closed,
    constrained, or unresolved.

    Code map:
        closed               = 0
        internal_fractional  = 1
        not_closed           = 2
        constrained          = 3
        unresolved           = 4


Which Files Go Into STRUC-PERC-I / STRUC-I?
-------------------------------------------

Use files from:

    ladders/one_column/

These contain only:

    value

and are easiest to upload into the chambers.

Recommended first tests:

    ladders/one_column/ABCD_charge_boundary_ladder_signed_charge.csv
    ladders/one_column/ABCD_charge_boundary_ladder_absolute_charge.csv
    ladders/one_column/ABCD_charge_boundary_ladder_boundary_route_coordinate.csv
    ladders/one_column/layerC_composite_closure_ladder_signed_charge.csv


Full CSV vs One-Column CSV
--------------------------

The full ladder files in:

    ladders/

preserve provenance columns:

    value
    object_id
    layer
    pdg_name
    symbol
    category
    Q_over_e
    closure_class
    route_class
    encoding
    source_file
    notes

These are useful for audit and interpretation.

The one-column files in:

    ladders/one_column/

are simplified chamber input files.

Do not delete the full files. They explain what each numeric value came from.


Important Interpretation Warning
--------------------------------

These ladder files are numeric structural encodings of the canonical corpus.

They are not:
    - raw PDG tables;
    - new particle data;
    - proof of a charge law;
    - final physics output.

They are exploratory inputs for STRUC-PERC-I and STRUC-I.

The correct interpretation is:

    canonical corpus table
    -> numeric ladder encoding
    -> chamber test
    -> structural result
    -> route-boundary interpretation


Next Step After Generation
--------------------------

After the ladders are generated:

1. Run STRUC-PERC-I first.
2. Save outputs to:

       results/struc_perc_i/

3. Run STRUC-I second.
4. Save outputs to:

       results/struc_i/

5. Compare layer behavior:
       A external closures
       B confined fractional coordinates
       C composite closures
       D boundary absences

6. Only after that proceed to alpha / bridge tests.
