sqq 0.1.0__tar.gz

sqq-0.1.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: sqq
+Version: 0.1.0
+Summary: Shell Quant Qualifier for water-shell topology analysis in MD trajectories.
+Author-email: pimooni <pimooni@gmail.com>
+Project-URL: Homepage, https://github.com/pimooni/sqq
+Project-URL: Repository, https://github.com/pimooni/sqq
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: openpyxl
+Requires-Dist: pyyaml
+Requires-Dist: tqdm
+Requires-Dist: MDAnalysis
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: networkx; extra == "dev"
+
+# SQQ
+
+**SQQ (Shell Quant Qualifier)** is a Python program for identifying and quantifying water-shell topologies in molecular dynamics trajectories.
+
+It analyzes water, ice, and hydrate-like structures from MD frames by building a water network, finding rings, cups (half-cages), closed cages, guest occupancy, F3/F4 order metrics, and ice-like waters.
+
+## Install
+
+Development install from this directory:
+
+```powershell
+pip install -e .
+```
+
+After installation, use the unified command:
+
+```powershell
+sqq init -o config.yaml
+sqq analyze -i ./gro -c config.yaml -o ./result_sqq
+```
+
+During local development without installation:
+
+```powershell
+python -m sqq init -o config.yaml
+python -m sqq analyze -i ./gro -c config.yaml -o ./result_sqq
+```
+
+## Quick Start
+
+Single GRO file:
+
+```powershell
+sqq analyze -i test1.gro -c config.yaml -o ./result_sqq
+```
+
+Directory of GRO frames:
+
+```powershell
+sqq analyze -i ./gro --pattern "*.gro" -c config.yaml -o ./result_sqq
+```
+
+Parallel standalone GRO/XYZ frames:
+
+```powershell
+sqq analyze -i ./gro --n-jobs 4 -c config.yaml -o ./result_sqq
+```
+
+XTC/TRR trajectory with a topology/structure file:
+
+```powershell
+sqq analyze -i traj.xtc --top topol.gro -c config.yaml -o ./result_sqq
+```
+
+## Important Defaults
+
+```yaml
+input:
+  xtc_stride: 1
+
+graph:
+  bond_mode: auto
+  oo_cutoff_nm: 0.35
+  hbond_distance_nm: 0.35
+  hbond_angle_deg: 30.0
+  pair_file: null
+  pair_id: resid
+
+ring:
+  sizes: [5, 6]
+  primitive: true
+  chordless: true
+
+cup:
+  mode: general
+  enabled: true
+  base_sizes: auto
+  side_sizes: auto
+
+cage:
+  enabled: true
+  ring_sizes: [5, 6]
+  target_types: [512, 51262, 51263, 51264]
+  output_other: false
+  other_max_faces: 20
+  search_mode: grow
+  seed_mode: ring
+  occupancy_mode: polyhedron
+
+order:
+  focus_waters: []
+
+parallel:
+  n_jobs: auto
+
+output:
+  write_gro: true
+  write_tsv: false
+  write_vmd: false
+  write_xlsx_summary: true
+```
+
+Configuration priority:
+
+```text
+built-in defaults < config.yaml < command-line options
+```
+
+## Output
+
+SQQ writes HA-style per-frame folders plus global summaries:
+
+```text
+result_sqq/
+  summary.xlsx
+  run_config.yaml
+  test1/
+    test1_info.md
+    test1_ring5.gro
+    test1_ring6.gro
+    test1_cup5_55555.gro
+    test1_512.gro
+    test1_512_empty.gro
+    test1_512_occupied.gro
+    test1_ice.gro
+```
+
+Ring and cup outputs are free objects after cage ownership is removed. Cage GRO files include cage waters, CNT center atoms, and assigned guest molecules. Summary tables include per-cage-type empty/occupied/multi/guest columns and readable cage-isomer breakdowns.
+Optional `*_membership.tsv` and `*_f3f4.tsv` files can be enabled with `output.write_tsv: true`.
+
+## Implemented Analysis
+
+- GRO and XYZ input in the source tree; XTC/TRR input through MDAnalysis when installed.
+- Orthorhombic minimum-image PBC.
+- Water and guest selection by residue and atom names.
+- Shared water graph for ring, cup, cage, F3/F4, and ice metrics.
+- `bond_mode=auto/hbond/oo/pairs`; `pairs` reads a user-provided water-neighbor file.
+- Non-recursive DFS ring search for primitive/chordless rings.
+- Ring search supports 4/5/6/7-member rings, but defaults to `[5, 6]`.
+- General cup search from base rings and side-ring closure; by default cup base/side ring sizes follow `ring.sizes`, so `[4, 5, 6]` searches 4/5/6 cups and `[4, 5, 6, 7]` searches 4/5/6/7 cups.
+- Default cage search by ring-face grow mode from ring seeds: grow connected face patches along open boundary edges, then validate a closed polyhedron by edge degree and Euler characteristic. Cage search supports 4/5/6-member faces through `cage.ring_sizes`, but defaults to `[5, 6]`; 7-member faces are intentionally not used for cage detection.
+- Optional `cage.output_other: true` adds Euler-compatible 4/5/6 unconventional cage targets up to `cage.other_max_faces`; the default only searches `512`, `51262`, `51263`, and `51264`.
+- Optional `cage.search_mode=pair` for HA/GRADE-style cup-pair comparison only.
+- Default guest occupancy by `cage.occupancy_mode=polyhedron`, using an oriented solid-angle point-in-polyhedron test; `center` and `auto` modes are available for comparison/fallback.
+- Cage isomer labels describe adjacent 6-ring face patterns, such as `6adj`, `6chain3`, `6star3`, or `6tri3+single`, instead of opaque `iso01` names.
+- VMD helper colors: `512` blue, `51262` green, `51263` orange, `51264` red; ring centers use R4 gray, R5 purple, R6 tan, and R7 black.
+- F3/F4 order metrics using the shared water graph and the reference-script formulas, including optional `order.focus_waters` averages.
+- CHILL-style ice output: total ice-like waters, ice-I-like waters, and interfacial/intermediate ice waters.
+- Explicit frame-level parallel execution for independent `.gro`/`.xyz` files via `--n-jobs N`.
+
+## Main Parameters
+
+| Parameter | Purpose |
+| --- | --- |
+| `water.resnames` | Water molecule residue names |
+| `water.oxygen_names` | Oxygen atom names used as water graph nodes |
+| `water.hydrogen_names` | Hydrogen atom names used for hydrogen-bond geometry |
+| `guest.resnames` | Guest molecule residue names |
+| `graph.bond_mode` | `auto`, `hbond`, `oo`, or `pairs` |
+| `graph.pair_file` | Pair file used when `bond_mode=pairs`; each non-comment line has two ids |
+| `graph.pair_id` | How pair ids are interpreted: `resid`, `oxygen_index`, or `atomid` |
+| `ring.sizes` | Ring sizes to search; default `[5, 6]` |
+| `cup.base_sizes`, `cup.side_sizes` | `auto` by default, meaning use `ring.sizes`; set explicit lists to restrict cup search |
+| `cage.ring_sizes` | Ring-face sizes allowed in cage search; default `[5, 6]`, optional `[4, 5, 6]` |
+| `cage.output_other` | Enable unconventional 4/5/6 cage targets; default `false` |
+| `cage.other_max_faces` | Maximum face count for generated unconventional cage targets; default `20` |
+| `cage.search_mode` | `grow` by default; `pair` for comparison/debugging |
+| `cage.seed_mode` | `ring` by default for speed; `cup` starts grow from detected cups, `auto` uses cup seeds when cups exist and falls back to ring |
+| `cage.occupancy_mode` | `polyhedron` by default; `center` and `auto` are also available |
+| `input.xtc_stride` | Read every Nth XTC/TRR frame |
+| `order.focus_waters` | Residue ids whose mean F3/F4 should also be reported |
+| `parallel.n_jobs` / `--n-jobs` | Parallel worker count for independent `.gro`/`.xyz` files; default `auto` runs serially |
+| `output.write_gro` | Write structure files for visualization |
+
+## Current Limits
+
+- CHILL-style ice classification is implemented as a topology/coordination classifier; separate atomistic Ih/Ic stacking assignment can be refined later if needed.
+- Only orthorhombic boxes are supported in the implemented PBC path.
+
+
+
+
+
+
+
+
+
+
+
+

sqq-0.1.0/README.md

@@ -0,0 +1,190 @@
+# SQQ
+
+**SQQ (Shell Quant Qualifier)** is a Python program for identifying and quantifying water-shell topologies in molecular dynamics trajectories.
+
+It analyzes water, ice, and hydrate-like structures from MD frames by building a water network, finding rings, cups (half-cages), closed cages, guest occupancy, F3/F4 order metrics, and ice-like waters.
+
+## Install
+
+Development install from this directory:
+
+```powershell
+pip install -e .
+```
+
+After installation, use the unified command:
+
+```powershell
+sqq init -o config.yaml
+sqq analyze -i ./gro -c config.yaml -o ./result_sqq
+```
+
+During local development without installation:
+
+```powershell
+python -m sqq init -o config.yaml
+python -m sqq analyze -i ./gro -c config.yaml -o ./result_sqq
+```
+
+## Quick Start
+
+Single GRO file:
+
+```powershell
+sqq analyze -i test1.gro -c config.yaml -o ./result_sqq
+```
+
+Directory of GRO frames:
+
+```powershell
+sqq analyze -i ./gro --pattern "*.gro" -c config.yaml -o ./result_sqq
+```
+
+Parallel standalone GRO/XYZ frames:
+
+```powershell
+sqq analyze -i ./gro --n-jobs 4 -c config.yaml -o ./result_sqq
+```
+
+XTC/TRR trajectory with a topology/structure file:
+
+```powershell
+sqq analyze -i traj.xtc --top topol.gro -c config.yaml -o ./result_sqq
+```
+
+## Important Defaults
+
+```yaml
+input:
+  xtc_stride: 1
+
+graph:
+  bond_mode: auto
+  oo_cutoff_nm: 0.35
+  hbond_distance_nm: 0.35
+  hbond_angle_deg: 30.0
+  pair_file: null
+  pair_id: resid
+
+ring:
+  sizes: [5, 6]
+  primitive: true
+  chordless: true
+
+cup:
+  mode: general
+  enabled: true
+  base_sizes: auto
+  side_sizes: auto
+
+cage:
+  enabled: true
+  ring_sizes: [5, 6]
+  target_types: [512, 51262, 51263, 51264]
+  output_other: false
+  other_max_faces: 20
+  search_mode: grow
+  seed_mode: ring
+  occupancy_mode: polyhedron
+
+order:
+  focus_waters: []
+
+parallel:
+  n_jobs: auto
+
+output:
+  write_gro: true
+  write_tsv: false
+  write_vmd: false
+  write_xlsx_summary: true
+```
+
+Configuration priority:
+
+```text
+built-in defaults < config.yaml < command-line options
+```
+
+## Output
+
+SQQ writes HA-style per-frame folders plus global summaries:
+
+```text
+result_sqq/
+  summary.xlsx
+  run_config.yaml
+  test1/
+    test1_info.md
+    test1_ring5.gro
+    test1_ring6.gro
+    test1_cup5_55555.gro
+    test1_512.gro
+    test1_512_empty.gro
+    test1_512_occupied.gro
+    test1_ice.gro
+```
+
+Ring and cup outputs are free objects after cage ownership is removed. Cage GRO files include cage waters, CNT center atoms, and assigned guest molecules. Summary tables include per-cage-type empty/occupied/multi/guest columns and readable cage-isomer breakdowns.
+Optional `*_membership.tsv` and `*_f3f4.tsv` files can be enabled with `output.write_tsv: true`.
+
+## Implemented Analysis
+
+- GRO and XYZ input in the source tree; XTC/TRR input through MDAnalysis when installed.
+- Orthorhombic minimum-image PBC.
+- Water and guest selection by residue and atom names.
+- Shared water graph for ring, cup, cage, F3/F4, and ice metrics.
+- `bond_mode=auto/hbond/oo/pairs`; `pairs` reads a user-provided water-neighbor file.
+- Non-recursive DFS ring search for primitive/chordless rings.
+- Ring search supports 4/5/6/7-member rings, but defaults to `[5, 6]`.
+- General cup search from base rings and side-ring closure; by default cup base/side ring sizes follow `ring.sizes`, so `[4, 5, 6]` searches 4/5/6 cups and `[4, 5, 6, 7]` searches 4/5/6/7 cups.
+- Default cage search by ring-face grow mode from ring seeds: grow connected face patches along open boundary edges, then validate a closed polyhedron by edge degree and Euler characteristic. Cage search supports 4/5/6-member faces through `cage.ring_sizes`, but defaults to `[5, 6]`; 7-member faces are intentionally not used for cage detection.
+- Optional `cage.output_other: true` adds Euler-compatible 4/5/6 unconventional cage targets up to `cage.other_max_faces`; the default only searches `512`, `51262`, `51263`, and `51264`.
+- Optional `cage.search_mode=pair` for HA/GRADE-style cup-pair comparison only.
+- Default guest occupancy by `cage.occupancy_mode=polyhedron`, using an oriented solid-angle point-in-polyhedron test; `center` and `auto` modes are available for comparison/fallback.
+- Cage isomer labels describe adjacent 6-ring face patterns, such as `6adj`, `6chain3`, `6star3`, or `6tri3+single`, instead of opaque `iso01` names.
+- VMD helper colors: `512` blue, `51262` green, `51263` orange, `51264` red; ring centers use R4 gray, R5 purple, R6 tan, and R7 black.
+- F3/F4 order metrics using the shared water graph and the reference-script formulas, including optional `order.focus_waters` averages.
+- CHILL-style ice output: total ice-like waters, ice-I-like waters, and interfacial/intermediate ice waters.
+- Explicit frame-level parallel execution for independent `.gro`/`.xyz` files via `--n-jobs N`.
+
+## Main Parameters
+
+| Parameter | Purpose |
+| --- | --- |
+| `water.resnames` | Water molecule residue names |
+| `water.oxygen_names` | Oxygen atom names used as water graph nodes |
+| `water.hydrogen_names` | Hydrogen atom names used for hydrogen-bond geometry |
+| `guest.resnames` | Guest molecule residue names |
+| `graph.bond_mode` | `auto`, `hbond`, `oo`, or `pairs` |
+| `graph.pair_file` | Pair file used when `bond_mode=pairs`; each non-comment line has two ids |
+| `graph.pair_id` | How pair ids are interpreted: `resid`, `oxygen_index`, or `atomid` |
+| `ring.sizes` | Ring sizes to search; default `[5, 6]` |
+| `cup.base_sizes`, `cup.side_sizes` | `auto` by default, meaning use `ring.sizes`; set explicit lists to restrict cup search |
+| `cage.ring_sizes` | Ring-face sizes allowed in cage search; default `[5, 6]`, optional `[4, 5, 6]` |
+| `cage.output_other` | Enable unconventional 4/5/6 cage targets; default `false` |
+| `cage.other_max_faces` | Maximum face count for generated unconventional cage targets; default `20` |
+| `cage.search_mode` | `grow` by default; `pair` for comparison/debugging |
+| `cage.seed_mode` | `ring` by default for speed; `cup` starts grow from detected cups, `auto` uses cup seeds when cups exist and falls back to ring |
+| `cage.occupancy_mode` | `polyhedron` by default; `center` and `auto` are also available |
+| `input.xtc_stride` | Read every Nth XTC/TRR frame |
+| `order.focus_waters` | Residue ids whose mean F3/F4 should also be reported |
+| `parallel.n_jobs` / `--n-jobs` | Parallel worker count for independent `.gro`/`.xyz` files; default `auto` runs serially |
+| `output.write_gro` | Write structure files for visualization |
+
+## Current Limits
+
+- CHILL-style ice classification is implemented as a topology/coordination classifier; separate atomistic Ih/Ic stacking assignment can be refined later if needed.
+- Only orthorhombic boxes are supported in the implemented PBC path.
+
+
+
+
+
+
+
+
+
+
+
+

sqq-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools >= 77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sqq"
+version = "0.1.0"
+description = "Shell Quant Qualifier for water-shell topology analysis in MD trajectories."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  { name = "pimooni", email = "pimooni@gmail.com" },
+]
+dependencies = [
+  "numpy",
+  "pandas",
+  "openpyxl",
+  "pyyaml",
+  "tqdm",
+  "MDAnalysis",
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "networkx"]
+
+[project.scripts]
+sqq = "sqq.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/pimooni/sqq"
+Repository = "https://github.com/pimooni/sqq"
+
+[tool.setuptools.package-data]
+sqq = ["example/gro/*.gro"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sqq-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sqq-0.1.0/sqq/__init__.py

@@ -0,0 +1,5 @@
+"""SQQ: Shell Quant Qualifier."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

sqq-0.1.0/sqq/__main__.py

@@ -0,0 +1,8 @@
+"""Run SQQ with `python -m sqq`."""
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    # Delegate to the same entry point used by the installed console script.
+    raise SystemExit(main())

sqq-0.1.0/sqq/cli.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+"""Command-line interface for SQQ."""
+
+import argparse
+from pathlib import Path
+
+from .config import write_default_config
+from .pipeline import analyze
+
+
+HELP_BANNER = """
++----------------------------+
+|   Shell  Quant  Qualifier  |
++----------------------------+
+
+SQQ for MD water-shell topology analysis.
+""".strip()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Create the two-command CLI: init and analyze."""
+    parser = argparse.ArgumentParser(
+        prog="sqq",
+        description=HELP_BANNER,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init_parser = subparsers.add_parser("init", help="Write a default config.yaml file.")
+    init_parser.add_argument("-o", "--output", default="config.yaml", help="Output config path.")
+
+    analyze_parser = subparsers.add_parser("analyze", help="Analyze MD frames.")
+    analyze_parser.add_argument("-i", "--input", required=True, help="Input file or directory.")
+    analyze_parser.add_argument("--pattern", help="Input pattern when --input is a directory.")
+    analyze_parser.add_argument("--top", "--topology", dest="topology", help="Topology file for xtc/trr.")
+    analyze_parser.add_argument("-c", "--config", help="YAML config file.")
+    analyze_parser.add_argument("-o", "--output", default="result_sqq", help="Output directory.")
+    analyze_parser.add_argument("--recursive", action="store_true", help="Read input directory recursively.")
+    analyze_parser.add_argument("--pairs", help="Pair file for bond_mode=pairs; each line contains two water ids.")
+    analyze_parser.add_argument("--pair-id", choices=["resid", "oxygen_index", "atomid"], help="How ids in --pairs are interpreted.")
+    analyze_parser.add_argument("--n-jobs", default=None, help="Frame-level worker count for independent GRO/XYZ files; default auto runs serially.")
+    analyze_parser.add_argument("--strict", action="store_true", help="Stop on the first failed frame.")
+    analyze_parser.add_argument("--no-gro", action="store_true", help="Disable GRO structure output.")
+    analyze_parser.add_argument("--no-xlsx", action="store_true", help="Disable summary.xlsx output.")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Dispatch the selected SQQ subcommand."""
+    args = build_parser().parse_args(argv)
+    if args.command == "init":
+        out = Path(args.output)
+        write_default_config(out)
+        print(f"Wrote default SQQ config: {out}")
+        return 0
+    if args.command == "analyze":
+        analyze(args)
+        return 0
+    raise AssertionError(f"Unhandled command: {args.command}")
+
+

sqq-0.1.0/sqq/config.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+"""Configuration defaults and YAML/JSON loading."""
+
+from copy import deepcopy
+import json
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover - exercised in minimal source-tree runs.
+    yaml = None
+
+
+# Defaults are intentionally explicit so a run can be reproduced from
+# run_config.yaml without relying on hidden command-line assumptions.
+DEFAULT_CONFIG: dict[str, Any] = {
+    "input": {
+        "pattern": "*.gro",
+        "recursive": False,
+        "first_file_time_ps": 0.0,
+        "frame_time_step_ps": 100.0,
+        "xtc_stride": 1,
+    },
+    "water": {
+        "resnames": ["SOL", "TIP", "WAT", "HOH"],
+        "oxygen_names": ["OW", "O", "OH2"],
+        "hydrogen_names": ["HW1", "HW2", "H1", "H2", "HW", "HT1", "HT2"],
+    },
+    "guest": {
+        "resnames": ["CH4", "CO2", "MET", "ETH"],
+        "center_atoms": {"CH4": ["C"], "CO2": ["C"]},
+        "center_mode": "center_atom",
+    },
+    "graph": {
+        "bond_mode": "auto",
+        "oo_cutoff_nm": 0.35,
+        "hbond_distance_nm": 0.35,
+        "hbond_angle_deg": 30.0,
+        "pair_file": None,
+        "pair_id": "resid",
+    },
+    "pbc": {
+        "box_mode": "orthorhombic",
+    },
+    "ring": {
+        "sizes": [5, 6],
+        "primitive": True,
+        "chordless": True,
+    },
+    "cup": {
+        "mode": "general",
+        "enabled": True,
+        "base_sizes": "auto",
+        "side_sizes": "auto",
+        "max_combinations_per_base": 50000,
+    },
+    "cage": {
+        "ring_sizes": [5, 6],
+        "target_types": ["512", "51262", "51263", "51264"],
+        "output_other": False,
+        "other_max_faces": 20,
+        "enabled": True,
+        "search_mode": "grow",
+        "seed_mode": "ring",
+        "max_states_per_seed": 2000,
+        "max_total_states": 250000,
+        "occupancy_mode": "polyhedron",
+        "occupancy_radius_nm": 0.5,
+    },
+    "order": {
+        "f3f4_enabled": True,
+        "focus_waters": [],
+    },
+    "ice": {
+        "enabled": True,
+        "method": "chill",
+        "min_six_rings": 2,
+        "require_four_coord_neighbors": True,
+    },
+    "output": {
+        "write_gro": True,
+        "write_tsv": False,
+        "write_vmd": False,
+        "write_xlsx_summary": True,
+        "write_empty_files": False,
+        "gro_atom_mode": "full_water",
+        "center_resname": "CNT",
+    },
+    "parallel": {
+        "n_jobs": "auto",
+    },
+    "debug": {
+        "use_networkx_checks": False,
+    },
+}
+
+
+def load_config(path: Path | None) -> dict[str, Any]:
+    """Load a config file and merge it over built-in defaults."""
+    config = deepcopy(DEFAULT_CONFIG)
+    if path is None:
+        return config
+    with path.open("r", encoding="utf-8-sig") as handle:
+        text = handle.read()
+    if yaml is not None:
+        user_config = yaml.safe_load(text) or {}
+    else:
+        # Source-tree smoke tests can run without PyYAML; installed SQQ uses YAML.
+        try:
+            user_config = json.loads(text) if text.strip() else {}
+        except json.JSONDecodeError as exc:
+            raise RuntimeError("Reading YAML config files requires PyYAML. Install with `pip install -e .`.") from exc
+    if not isinstance(user_config, dict):
+        raise ValueError(f"Config file must contain a YAML mapping: {path}")
+    return merge_config(config, user_config)
+
+
+def merge_config(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge user configuration into defaults."""
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(base.get(key), dict):
+            merge_config(base[key], value)
+        else:
+            base[key] = value
+    return base
+
+
+def write_default_config(path: Path) -> None:
+    """Write the default configuration template."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8", newline="\n") as handle:
+        dump_config(DEFAULT_CONFIG, handle)
+
+
+def dump_config(config: dict[str, Any], handle) -> None:
+    """Write YAML when available, otherwise a JSON-compatible fallback."""
+    if yaml is not None:
+        yaml.safe_dump(config, handle, allow_unicode=True, sort_keys=False)
+    else:
+        json.dump(config, handle, ensure_ascii=False, indent=2)
+        handle.write("\n")
+
+
+
+
+
+
+

sqq-0.1.0/sqq/core/__init__.py

@@ -0,0 +1 @@
+"""Core SQQ topology algorithms."""