libqdx 0.8.0__tar.gz

libqdx-0.8.0/.github/workflows/python.yml

@@ -0,0 +1,102 @@
+name: Python
+
+on:
+  push:
+    branches: ["master"]
+    paths:
+      - "py/**"
+      - "src/**"
+      - "Cargo.toml"
+      - "Cargo.lock"
+  pull_request:
+    branches: ["master"]
+    paths:
+      - "py/**"
+      - "src/**"
+      - "Cargo.toml"
+      - "Cargo.lock"
+
+env:
+  CARGO_TERM_COLOR: always
+  CARGO_NET_GIT_FETCH_WITH_CLI: true
+
+permissions:
+  contents: read
+
+jobs:
+  # Build wheels for Linux, macOS, and Windows
+  build:
+    name: ${{ matrix.platform.target }} / py${{ matrix.python-version }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+        platform:
+          - runner: ubuntu-latest
+            os: linux
+            target: x86_64-unknown-linux-gnu
+          - runner: macos-latest
+            os: macos
+            target: aarch64-apple-darwin
+          - runner: windows-latest
+            os: windows
+            target: x86_64-pc-windows-msvc
+    runs-on: ${{ matrix.platform.runner }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        if: matrix.platform.os != 'linux'
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Build wheels (Linux)
+        if: matrix.platform.os == 'linux'
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --manifest-path py/Cargo.toml -i python${{ matrix.python-version }}
+          manylinux: auto
+      - name: Build wheels (macOS/Windows)
+        if: matrix.platform.os != 'linux'
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --manifest-path py/Cargo.toml -i python
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.platform.target }}-py${{ matrix.python-version }}
+          path: dist
+
+  # Build source distribution
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist --manifest-path py/Cargo.toml
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-sdist
+          path: dist
+
+  # Publish to PyPI on push to master (only if py/ or src/ changed)
+  publish:
+    needs: [build, sdist]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    environment:
+      name: pypi
+      url: https://pypi.org/p/libqdx
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          merge-multiple: true
+          path: dist
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

libqdx-0.8.0/.github/workflows/rust.yml

@@ -0,0 +1,28 @@
+name: Rust
+
+on:
+  push:
+    branches: ["master"]
+  pull_request:
+    branches: ["master"]
+
+env:
+  CARGO_TERM_COLOR: always
+  CARGO_NET_GIT_FETCH_WITH_CLI: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - run: rustup toolchain install beta --profile minimal
+      - uses: Swatinem/rust-cache@v2
+      - name: Build
+        run: cargo clippy
+      - name: format
+        run: cargo fmt --check
+      - name: Build
+        run: cargo build --verbose
+      - name: Run tests
+        run: cargo test --verbose

libqdx-0.8.0/.gitignore

@@ -0,0 +1,5 @@
+**/target
+.direnv
+.envrc
+.env
+test_cache/

libqdx-0.8.0/AGENTS.md

@@ -0,0 +1,86 @@
+# AGENTS.md — AI Coding Context for libqdx
+
+## Project Overview
+
+**libqdx** is a Rust library for molecular structure representation and conversion. It provides the core data structures and parsers for the QDX ecosystem.
+
+### Key Concepts
+
+- **TRC** (Topology, Residues, Chains): The central data structure combining molecular topology (atoms, bonds), residue assignments, and chain information (including secondary structure).
+- **Topology**: Atoms, bonds, coordinates, charges, etc.
+- **Residues**: Mapping of atoms to residues (amino acids, ligands, etc.).
+- **Chains**: Chain assignments, labels, alpha helices, beta sheets.
+
+### Use Cases
+
+TRCs are used to store molecular systems for **Tengu modules**, where Tengu is QDX's job runner backend. A module is a specific program or capability that can be run on Tengu. One of the main modules does protein preparation and leverages the protein-specific capabilities like `perceive_bonds`, `perceive_formal_charges`. This library should serve as a general-purpose toolkit for manipulating molecules in the context of supplementing and completing the capabilities required by Tengu modules and the platform in general. Some of these capabilities are (or are planned to be) exported to our Python and TypeScript libraries.
+
+### Supported Formats
+
+- **PDB** (`src/convert/pdb.rs`): Fixed-width column format. Parser uses 0-indexed column ranges.
+- **mmCIF** (`src/convert/mmcif.rs`): Key-value and loop-based format. Data can appear as loops (multiple records) or single key-value pairs (one record) — both must be handled.
+- **SDF** (`src/convert/sdf.rs`): Structure-data format for small molecules.
+- **XYZ** (`src/convert/xyz.rs`): Simple coordinate format.
+
+## Architecture
+
+```
+src/
+  lib.rs            # Re-exports, public API
+  trc.rs            # TRC struct definition
+  topology.rs       # Topology (atoms, bonds, coordinates)
+  residue.rs        # Residue definitions
+  chain.rs          # Chains, AlphaHelices, BetaSheets, HelixClass, StrandSense
+  convert/
+    mod.rs          # Conversion module
+    pdb.rs          # PDB parser/writer (~2000 lines)
+    mmcif.rs        # mmCIF parser (~1400 lines)
+    parity.rs       # Cross-format comparison diagnostics
+    sdf.rs          # SDF parser
+    xyz.rs          # XYZ parser
+  version.rs        # SchemaVersion (data format version, separate from crate version)
+tests/
+  convert.rs        # Integration tests: PDB/mmCIF parity tests, roundtrip tests
+  data/             # Test data files (PDB, mmCIF, JSON snapshots)
+```
+
+## Conventions
+
+### Code Style
+- Rust edition 2024.
+- `cargo fmt` is enforced (runs automatically as a hook or by the user).
+- Helper functions are placed **above** their call sites.
+- Prefer extracting local variables over inline expressions in struct literals for readability.
+- No unnecessary abstractions — three similar lines are better than a premature helper.
+
+### mmCIF Parsing Patterns
+- `get_loop_data(block, category)` returns `Option<(&[String], &[Vec<String>])>` for loop-format data.
+- `get_single_data(block, field)` returns `Option<&str>` for single key-value pair data.
+- **Both formats must be handled** for any mmCIF category — use `if let Some(...) = get_loop_data(...) { ... } else { ... get_single_data(...) ... }`.
+- `row_str(row, idx)` filters missing mmCIF values (`""`, `"?"`, `"."`). `get_single_data` does **not** filter — callers must use `.filter(|v| !is_missing_mmcif_value(v))` when needed.
+- `ins_code_or_tilde(value: Option<&str>)` returns `"~"` for missing insertion codes.
+
+### PDB Parsing Patterns
+- Fixed-width columns, 0-indexed in parser code.
+- `ins_code_or_tilde(code: &str)` returns `"~"` for empty insertion codes.
+- `chain_id_for_pdb(chains, chain_ref)` resolves chain labels for output.
+- `put_left`/`put_right` for fixed-width field formatting in PDB output.
+
+### ResidueId
+- Used in both parsers for residue lookup: `{ chain_id, sequence_number, insertion_code, residue_name }`.
+- Insertion code sentinel: `"~"` means no insertion code.
+- Defined separately in each parser module (not shared).
+
+### Testing
+- `cargo test` runs unit tests (fast, ~18 tests).
+- `cargo test --test convert` runs integration tests (~39 parity tests comparing PDB vs mmCIF parsing).
+- Parity tests download structures from RCSB, parse both formats, and compare the resulting TRC structs.
+- Test data cached in `test_cache/` (gitignored) and `tests/data/` (committed JSON snapshots).
+
+### Versioning
+- Crate version in `Cargo.toml` follows semver.
+- `SchemaVersion` in `src/version.rs` is the **data format** version (currently 0.2.0), independent of the crate version. Only bump if the serialized TRC format changes in a breaking way.
+
+### Git
+- Conventional commit messages: `feat:`, `fix:`, `refactor:`, `chore:`.
+- Main branch: `master`.