BernalAtlas

Exact ideal orientation distributions for fixed hydrogen-bond (HB) fragments.

Given an undirected reference graph (vertices = molecules, edges = H-bonds), BernalAtlas enumerates ice-rule orientations, classifies them up to graph automorphism (optionally identifying mirror images), and reports the ideal weight of each canonical pattern.

Requirements

• Python >=3.13, excluding 3.14.1 (same exclusion as NetworkX 3.6.x)
• Poetry (recommended)

Install

git clone https://github.com/vitroid/BernalAtlas.git
cd BernalAtlas
poetry install

Quick start

Compute statistics from a graph YAML and write JSON under data/:

poetry run python stat.py compute graphs/hexagon.yaml -o data/hexagon.json
poetry run python stat.py show data/hexagon.json

Or generate several built-in examples at once:

make data

dodecahedral is slow; generate it separately:

make data/dodecahedral.json

Parallel classification

poetry run python stat.py compute graphs/adamantane.yaml -o data/adamantane.json --workers 0

--workers 0 uses all CPU cores.

Graph YAML

Each file under graphs/ defines a reference fragment.

Required

• name — label used in output JSON

Edges (one of)

• edges — ordered list [[u, v], ...]. Edge order is the bit-string index order: reference direction u→v is bit 0, reverse is 1.
• networkx_graph — built-in NetworkX name (currently dodecahedral)

Optional

• identify_mirror_images — true/false (default false)

Example (graphs/hexagon.yaml):

name: hexagon
edges:
  - [0, 1]
  - [1, 2]
  - [2, 3]
  - [3, 4]
  - [4, 5]
  - [5, 0]

Library usage

from bernalatlas import analyze_edges, compute_from_spec, load_graph_spec

spec = load_graph_spec("graphs/hexagon.yaml")
result = analyze_edges(
    spec["edges"],
    name=spec["name"],
    identify_mirror_images=spec["identify_mirror_images"],
)
print(result.name, result.num_patterns, result.total_weight)

Or run the full YAML → document pipeline:

from bernalatlas import compute_from_spec

doc = compute_from_spec("graphs/hexagon.yaml")

Output JSON

Results are schema version 1 documents with:

• reference_graph — nodes, edges, and the ordered edge list
• analysis_options — e.g. identify_mirror_images
• statistics — valid-state count, spatial automorphisms, and per-pattern fields (canonical_id, bit_string, multiplicity, flow_nodes, frequency, weight_fraction)

Generated JSON under data/ is gitignored; recreate with make data or stat.py compute.

Included graphs

Spec	Notes
hexagon	6-cycle
chain7	linear chain
adamantane	adamantane-like cluster
small_barrelan	small barrelan
wurtzitane	wurtzitane-like cluster
dodecahedral	NetworkX dodecahedral graph (expensive)

License

MIT — see LICENSE.