Industry Bridges¶

Eight bridges convert between Franklin's substrate outputs and the libraries industry consumers already use. Each bridge is an optional install extra; the base gaiaftcl package imports without any of them.

Bridge	Install	Module	Use case
numpy	`pip install gaiaftcl[numpy]`	`gaiaftcl.bridges.numpy_bridge`	substrate columns ↔ ndarrays
pandas	`pip install gaiaftcl[pandas]`	`gaiaftcl.bridges.pandas_bridge`	heartbeats/health/healing ↔ DataFrame
scikit-learn	`pip install gaiaftcl[sklearn]`	`gaiaftcl.bridges.sklearn_bridge`	substrate features ↔ sklearn estimators
biopython	`pip install gaiaftcl[biopython]`	`gaiaftcl.bridges.biopython_bridge`	pathway closures ↔ Bio.Seq
rdkit	`pip install gaiaftcl[rdkit]`	`gaiaftcl.bridges.rdkit_bridge`	molecule projections ↔ Chem.Mol
ase	`pip install gaiaftcl[ase]`	`gaiaftcl.bridges.ase_bridge`	lattices ↔ ase.Atoms
pymatgen	`pip install gaiaftcl[pymatgen]`	`gaiaftcl.bridges.pymatgen_bridge`	structures ↔ pymatgen.Structure
root/uproot	`pip install gaiaftcl[root]`	`gaiaftcl.bridges.root_bridge`	telemetry ↔ uproot trees

numpy¶

from gaiaftcl.bridges.numpy_bridge import (
    research_telemetry_to_array,
    projection_cells_to_array,
    heartbeat_counters_to_array,
    leading_zero_histogram,
)

research_telemetry_to_array(rows, field) -> np.ndarray Extract a numeric column from V160 telemetry rows.

projection_cells_to_array(canonical_cells_json) -> np.ndarray Parse substrate exact-Rat cells to float64. For exact-Rat preservation use fractions.Fraction instead.

heartbeat_counters_to_array(heartbeats, field='observations_count') -> np.ndarray Substrate cadence sliding-window analysis.

leading_zero_histogram(v178_rows) -> np.ndarray 65-bin histogram of V178 leading-zero counts.

pandas¶

from gaiaftcl.bridges.pandas_bridge import (
    heartbeats_to_dataframe,
    research_telemetry_to_dataframe,
    health_observations_to_dataframe,
    healing_actions_to_dataframe,
    substrate_development_to_dataframe,
    cadence_summary,
)

substrate_development_to_dataframe returns a DataFrame whose status column carries V186 vocabulary verbatim.

cadence_summary(heartbeats) returns inter-tick min/max/mean/median for sovereign heartbeat health monitoring.

scikit-learn¶

from gaiaftcl.bridges.sklearn_bridge import (
    SubstrateFeatureExtractor,
    V178LeadingZeroFeatureExtractor,
)

SubstrateFeatureExtractor is sklearn-compatible (BaseEstimator + TransformerMixin). Configurable feature field list.

V178LeadingZeroFeatureExtractor extracts (leading_zero_nibble_count, cursor_extranonce, cursor_ntime, target_inequality_satisfied) features for clustering substrate measurement windows.

biopython¶

from gaiaftcl.bridges.biopython_bridge import (
    pathway_to_seq,
    telemetry_to_seqrecords,
)

pathway_to_seq(row, alphabet="ACGT") projects a V160 row's projection-cells canonical to a Bio.Seq by argmax over 4-cell blocks. Designed for QC-014's biological pathway closure projections.

telemetry_to_seqrecords(rows) returns Bio.SeqRecord with substrate window_id as id.

rdkit¶

from gaiaftcl.bridges.rdkit_bridge import (
    smiles_canonical_to_mol,
    mol_to_substrate_projection_canonical,
    project_validated_cure_row,
)

smiles_canonical_to_mol(smiles) parses to rdkit Mol.

mol_to_substrate_projection_canonical(mol) produces canonical SMILES for replay-bit-exact projection identity.

project_validated_cure_row(row) looks for canonical_smiles / smiles / SMILES columns and parses the first available.

ase¶

from gaiaftcl.bridges.ase_bridge import (
    lattice_canonical_to_atoms,
    atoms_to_substrate_canonical,
)

Substrate lattice canonical format:

symbols=['Si','Si'];positions=[[0,0,0],[1.5,1.5,1.5]];cell=[3,3,3];pbc=[True,True,True]

atoms_to_substrate_canonical(atoms) serializes ase.Atoms back to substrate-canonical form.

pymatgen¶

from gaiaftcl.bridges.pymatgen_bridge import (
    structure_canonical_to_structure,
    structure_to_substrate_canonical,
)

structure_canonical_to_structure("Si2 (cubic Fd-3m)", lattice_a=5.43) parses substrate structure canonical to pymatgen.Structure.

structure_to_substrate_canonical(structure) serializes pymatgen.Structure to the substrate canonical form.

root / uproot¶

from gaiaftcl.bridges.root_bridge import (
    telemetry_to_uproot_tree,
    heartbeats_to_uproot_tree,
)

Convert V160 telemetry or V184 heartbeats to dict[str, np.ndarray] in uproot's tree = {col: array} recreate format:

import uproot
from gaiaftcl import FranklinClient
from gaiaftcl.bridges.root_bridge import telemetry_to_uproot_tree

with FranklinClient.connect() as franklin:
    with uproot.recreate("substrate.root") as f:
        f["telemetry"] = telemetry_to_uproot_tree(
            franklin.research_telemetry(limit=10000))

Each bridge is substrate-natural: conversions preserve the substrate's canonical form and round-trip bit-exact when the target ecosystem's representation is lossless.

Federation-cosigned

This page's source is sealed in the GaiaFTCL federation manifest — page SHA-256 e9ce52eec46954e2…, manifest witness a090592e0609adc8…, signed 2026-06-02T18:58:22Z by cell gaiaftcl-mac-cell. Verify with gaiaftcl wiki sign --all and compare wiki-all-signatures.json.