persistent-homology 0.1.0__tar.gz

persistent_homology-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 <Roy ABALLO>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

persistent_homology-0.1.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: persistent-homology
+Version: 0.1.0
+Summary: A from-scratch implementation of persistent homology for Vietoris-Rips filtrations.
+Author-email: Roy Aballo <abalo.g.roy@aims-senegal.org>
+License: MIT
+Project-URL: Homepage, https://github.com/royaballo/persistent-homology
+Project-URL: Repository, https://github.com/royaballo/persistent-homology
+Project-URL: Issues, https://github.com/royaballo/persistent-homology/issues
+Keywords: persistent homology,topological data analysis,Vietoris-Rips,TDA,algebraic topology
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Requires-Dist: scipy>=1.15
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: pandas>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Provides-Extra: benchmark
+Requires-Dist: ripser>=0.6.14; extra == "benchmark"
+Requires-Dist: gudhi>=3.11.0; extra == "benchmark"
+Provides-Extra: bio
+Requires-Dist: biopython>=1.85; extra == "bio"
+Dynamic: license-file
+
+# Persistent Homology
+
+A from-scratch, readable implementation of persistent homology for
+Vietoris–Rips filtrations, written as the computational half of an MSc thesis
+in Topological Data Analysis.
+
+The point of this code is not to be fast. Production libraries like Ripser and
+GUDHI already are, and they are very hard to read. The point is the opposite:
+every function here lines up with a definition or an algorithm from the thesis,
+so that someone can follow the path from "a point cloud" to "a persistence
+diagram" without taking any step on faith. Where there was a choice between a
+clever trick and a transparent one, the transparent one won.
+
+## What it does
+
+Given a finite point cloud, the pipeline:
+
+1. **Builds the Vietoris–Rips filtration** up to a chosen dimension and scale.
+   VR is the only filtration the code implements; Čech and Alpha are discussed
+   in the thesis as context but are not built here.
+2. **Assembles the combined boundary matrix** over $\mathbb{Z}/2\mathbb{Z}$,
+   stored sparsely as columns of row indices.
+3. **Reduces it** by one of three interchangeable strategies, and reads off the
+   birth–death pairs.
+4. **Returns persistence diagrams** per dimension, as `{dimension: [(birth,
+   death), ...]}`, ready to plot.
+
+The three reduction strategies are the heart of the project, and you can switch
+between them with a single argument:
+
+| Strategy      | What it is                                                        | Where it shines |
+|---------------|-------------------------------------------------------------------|-----------------|
+| `standard`    | Plain left-to-right column reduction (Zomorodian–Carlsson)        | The baseline; easiest to read |
+| `clearing`    | Standard reduction, but births in dimension *k* are zeroed once dimension *k+1* is done | Skips a lot of wasted work in high dimensions |
+| `cohomology`  | Reduces the anti-transpose instead (pCoh, de Silva–Morozov–Vejdemo-Johansson) | Much shorter columns on VR complexes; usually the fastest of the three |
+
+All three return the *same* diagram — that is the whole content of the duality
+results, and the test suite checks it explicitly on every dataset.
+
+## Installation
+
+```bash
+git clone https://github.com/royaballo/persistent-homology.git
+cd persistent-homology
+pip install -e .
+```
+
+That installs the `persistent_homology` package in editable mode along with its
+dependencies (NumPy, SciPy, Matplotlib; `ripser` and `gudhi` are pulled in for
+the correctness tests and benchmarks). Python 3.11+ is expected.
+
+## A first example
+
+```python
+from persistent_homology.persistence import compute_persistence
+from datasets.synthetic import make_circle
+
+# 30 points sampled on a noisy circle
+points = make_circle(n=30, noise=0.05)
+
+# one long-lived H1 class is the circle's hole
+diagram = compute_persistence(
+    points,
+    max_dim=2,
+    max_eps=2.0,
+    algorithm="cohomology",   # or "standard", "clearing"
+)
+
+for dim, dgm in diagram.items():
+    print(f"H{dim}: {len(dgm)} features")
+```
+
+To see it rather than read it:
+
+```python
+from persistent_homology.plotting import plot_persistence_diagram
+
+plot_persistence_diagram(diagram, max_dim=2)
+```
+
+The circle gives one point sitting well above the diagonal in $H_1$ (the hole)
+and a cloud of short-lived noise near it. That gap between signal and noise is
+the thing persistent homology is for. Essential features — the ones that never
+die — are drawn as triangles along a dashed `∞` line near the top, since their
+true death is infinite and cannot be placed on the axis.
+
+## Repository structure
+
+```
+persistent_homology/      the actual library
+    filtration.py             Vietoris–Rips construction (flag complex from the 1-skeleton)
+    boundary.py               boundary and coboundary matrices over Z/2Z
+    reduction.py              standard, clearing, and cohomology (pCoh) reductions
+    persistence.py            end-to-end entry point: points in, diagrams out
+    plotting.py               persistence diagrams (and the log-log benchmark plots)
+
+datasets/
+    synthetic.py              circle, sphere, torus, cube samplers (known topology)
+    proteins.py               loads Cα coordinates from PDB files
+
+tests/
+    test_correctness.py       checks our diagrams against Ripser and GUDHI
+
+benchmarks/                   timing and memory scripts; results land in benchmarks/results/
+applications/                 the protein case study (analyse_proteins.py, benchmark_lysozyme.py)
+notebooks/                    correctness, benchmark, and protein analysis walkthroughs
+data/proteins/                PDB files, extracted Cα coordinates, and computed diagrams
+figures/                      generated plots (regenerated by the scripts; not meant to be edited by hand)
+```
+
+If you only want to understand the method, read `filtration.py`, then
+`boundary.py`, then `reduction.py`, in that order. They mirror the thesis
+chapter on algorithms section by section.
+
+## How the thesis was built, in order
+
+The work went in five steps, and the repository is laid out so that each one can
+be re-run on its own.
+
+**1. Implement the pipeline.** Build the VR filtration, the boundary matrices,
+and the three reductions — the `persistent_homology/` package. The guiding rule
+was a one-to-one match between code and theory rather than speed.
+
+**2. Prove it is correct.** Before any benchmark means anything, the output has
+to be right. `tests/test_correctness.py` runs our three algorithms on the
+synthetic datasets and on small random complexes, and checks that the diagrams
+agree with both Ripser and GUDHI up to the usual reordering. The
+`correctness_verification.ipynb` notebook shows this in a readable form.
+
+**3. Benchmark it.** With correctness settled, the `benchmarks/` scripts measure
+how the three strategies scale. `computation_time.py` and `memory_usage.py`
+sweep dataset size on circle, sphere, torus, and cube; `effect_filtration_scope.py`
+isolates how much capping the homology dimension actually saves. Fitted scaling
+exponents are written to `benchmarks/results/`.
+
+**4. Put it to work on real data.** The protein case study in `applications/`
+asks a concrete question: can persistent homology pick out structural features
+of proteins straight from their Cα atomic coordinates, with no
+chemistry-specific input? It runs on three PDB structures (hemoglobin `1A3N`,
+lysozyme `1AKI`, GFP `1EMA`), computes $H_0$, $H_1$, $H_2$ diagrams, and tallies
+the resulting Betti counts.
+
+**5. Write it up.** The thesis ties the theory, the correctness evidence, the
+scaling results, and the protein study together. The notebooks are the bridge:
+they regenerate every figure the thesis uses.
+
+## Reproducing the results
+
+Each step is one command. Run them from the repository root.
+
+```bash
+# correctness: should report all-pass against Ripser and GUDHI
+pytest
+
+# timing and memory across synthetic datasets (writes CSVs to benchmarks/results/)
+python benchmarks/computation_time.py
+python benchmarks/memory_usage.py
+python benchmarks/effect_filtration_scope.py
+
+# protein case study (writes diagrams to data/proteins/results/ and plots to figures/)
+python applications/analyse_proteins.py
+python applications/benchmark_lysozyme.py
+```
+
+The three notebooks in `notebooks/` read the CSVs and `.npy` diagrams produced
+above and assemble the figures and tables exactly as they appear in the thesis.
+Run the scripts first, then the notebooks.
+
+A note on figures: everything in `figures/` is generated. Delete the folder and
+re-run the scripts and you should get it back byte-for-byte, give or take
+matplotlib versions.
+
+## What the results say
+
+The short version, with the detail left for the thesis:
+
+- **The three algorithms agree, always.** This is the duality between homology
+  and cohomology made concrete: same pairs, birth and death simplices swapped.
+- **Empirical scaling sits well below the cubic worst case.** On the synthetic
+  datasets the fitted exponents come out far smaller than the $O(m^3)$ bound,
+  because the boundary matrices are sparse and pivot conflicts are rare. The
+  cohomology route is the quickest, since coboundary columns on VR complexes are
+  short.
+- **Capping the dimension matters.** Most of the simplices, and most of the
+  cost, live in the top dimensions; not computing homology you do not need is
+  the cheapest optimisation available.
+- **The topology of the proteins is legible.** The persistence diagrams pick out
+  components, loops, and voids straight from the coordinates, encouraging for
+  topology as a coordinate-free structural descriptor, though this is a small
+  proof-of-concept and the thesis is careful about not overclaiming.
+
+## References
+
+The algorithms and theory come mainly from:
+
+- H. Edelsbrunner, D. Letscher, A. Zomorodian. *Topological persistence and
+  simplification* (2002).
+- A. Zomorodian, G. Carlsson. *Computing persistent homology* (2005).
+- V. de Silva, D. Morozov, M. Vejdemo-Johansson. *Dualities in persistent
+  (co)homology* (2011).
+- U. Bauer. *Ripser: efficient computation of Vietoris–Rips persistence
+  barcodes* (2021).
+- C. Maria et al. *The GUDHI library* (2014).
+
+Full citations are in the thesis bibliography.
+
+## License
+
+Released under the MIT License. See [LICENSE](LICENSE).

persistent_homology-0.1.0/README.md

@@ -0,0 +1,209 @@
+# Persistent Homology
+
+A from-scratch, readable implementation of persistent homology for
+Vietoris–Rips filtrations, written as the computational half of an MSc thesis
+in Topological Data Analysis.
+
+The point of this code is not to be fast. Production libraries like Ripser and
+GUDHI already are, and they are very hard to read. The point is the opposite:
+every function here lines up with a definition or an algorithm from the thesis,
+so that someone can follow the path from "a point cloud" to "a persistence
+diagram" without taking any step on faith. Where there was a choice between a
+clever trick and a transparent one, the transparent one won.
+
+## What it does
+
+Given a finite point cloud, the pipeline:
+
+1. **Builds the Vietoris–Rips filtration** up to a chosen dimension and scale.
+   VR is the only filtration the code implements; Čech and Alpha are discussed
+   in the thesis as context but are not built here.
+2. **Assembles the combined boundary matrix** over $\mathbb{Z}/2\mathbb{Z}$,
+   stored sparsely as columns of row indices.
+3. **Reduces it** by one of three interchangeable strategies, and reads off the
+   birth–death pairs.
+4. **Returns persistence diagrams** per dimension, as `{dimension: [(birth,
+   death), ...]}`, ready to plot.
+
+The three reduction strategies are the heart of the project, and you can switch
+between them with a single argument:
+
+| Strategy      | What it is                                                        | Where it shines |
+|---------------|-------------------------------------------------------------------|-----------------|
+| `standard`    | Plain left-to-right column reduction (Zomorodian–Carlsson)        | The baseline; easiest to read |
+| `clearing`    | Standard reduction, but births in dimension *k* are zeroed once dimension *k+1* is done | Skips a lot of wasted work in high dimensions |
+| `cohomology`  | Reduces the anti-transpose instead (pCoh, de Silva–Morozov–Vejdemo-Johansson) | Much shorter columns on VR complexes; usually the fastest of the three |
+
+All three return the *same* diagram — that is the whole content of the duality
+results, and the test suite checks it explicitly on every dataset.
+
+## Installation
+
+```bash
+git clone https://github.com/royaballo/persistent-homology.git
+cd persistent-homology
+pip install -e .
+```
+
+That installs the `persistent_homology` package in editable mode along with its
+dependencies (NumPy, SciPy, Matplotlib; `ripser` and `gudhi` are pulled in for
+the correctness tests and benchmarks). Python 3.11+ is expected.
+
+## A first example
+
+```python
+from persistent_homology.persistence import compute_persistence
+from datasets.synthetic import make_circle
+
+# 30 points sampled on a noisy circle
+points = make_circle(n=30, noise=0.05)
+
+# one long-lived H1 class is the circle's hole
+diagram = compute_persistence(
+    points,
+    max_dim=2,
+    max_eps=2.0,
+    algorithm="cohomology",   # or "standard", "clearing"
+)
+
+for dim, dgm in diagram.items():
+    print(f"H{dim}: {len(dgm)} features")
+```
+
+To see it rather than read it:
+
+```python
+from persistent_homology.plotting import plot_persistence_diagram
+
+plot_persistence_diagram(diagram, max_dim=2)
+```
+
+The circle gives one point sitting well above the diagonal in $H_1$ (the hole)
+and a cloud of short-lived noise near it. That gap between signal and noise is
+the thing persistent homology is for. Essential features — the ones that never
+die — are drawn as triangles along a dashed `∞` line near the top, since their
+true death is infinite and cannot be placed on the axis.
+
+## Repository structure
+
+```
+persistent_homology/      the actual library
+    filtration.py             Vietoris–Rips construction (flag complex from the 1-skeleton)
+    boundary.py               boundary and coboundary matrices over Z/2Z
+    reduction.py              standard, clearing, and cohomology (pCoh) reductions
+    persistence.py            end-to-end entry point: points in, diagrams out
+    plotting.py               persistence diagrams (and the log-log benchmark plots)
+
+datasets/
+    synthetic.py              circle, sphere, torus, cube samplers (known topology)
+    proteins.py               loads Cα coordinates from PDB files
+
+tests/
+    test_correctness.py       checks our diagrams against Ripser and GUDHI
+
+benchmarks/                   timing and memory scripts; results land in benchmarks/results/
+applications/                 the protein case study (analyse_proteins.py, benchmark_lysozyme.py)
+notebooks/                    correctness, benchmark, and protein analysis walkthroughs
+data/proteins/                PDB files, extracted Cα coordinates, and computed diagrams
+figures/                      generated plots (regenerated by the scripts; not meant to be edited by hand)
+```
+
+If you only want to understand the method, read `filtration.py`, then
+`boundary.py`, then `reduction.py`, in that order. They mirror the thesis
+chapter on algorithms section by section.
+
+## How the thesis was built, in order
+
+The work went in five steps, and the repository is laid out so that each one can
+be re-run on its own.
+
+**1. Implement the pipeline.** Build the VR filtration, the boundary matrices,
+and the three reductions — the `persistent_homology/` package. The guiding rule
+was a one-to-one match between code and theory rather than speed.
+
+**2. Prove it is correct.** Before any benchmark means anything, the output has
+to be right. `tests/test_correctness.py` runs our three algorithms on the
+synthetic datasets and on small random complexes, and checks that the diagrams
+agree with both Ripser and GUDHI up to the usual reordering. The
+`correctness_verification.ipynb` notebook shows this in a readable form.
+
+**3. Benchmark it.** With correctness settled, the `benchmarks/` scripts measure
+how the three strategies scale. `computation_time.py` and `memory_usage.py`
+sweep dataset size on circle, sphere, torus, and cube; `effect_filtration_scope.py`
+isolates how much capping the homology dimension actually saves. Fitted scaling
+exponents are written to `benchmarks/results/`.
+
+**4. Put it to work on real data.** The protein case study in `applications/`
+asks a concrete question: can persistent homology pick out structural features
+of proteins straight from their Cα atomic coordinates, with no
+chemistry-specific input? It runs on three PDB structures (hemoglobin `1A3N`,
+lysozyme `1AKI`, GFP `1EMA`), computes $H_0$, $H_1$, $H_2$ diagrams, and tallies
+the resulting Betti counts.
+
+**5. Write it up.** The thesis ties the theory, the correctness evidence, the
+scaling results, and the protein study together. The notebooks are the bridge:
+they regenerate every figure the thesis uses.
+
+## Reproducing the results
+
+Each step is one command. Run them from the repository root.
+
+```bash
+# correctness: should report all-pass against Ripser and GUDHI
+pytest
+
+# timing and memory across synthetic datasets (writes CSVs to benchmarks/results/)
+python benchmarks/computation_time.py
+python benchmarks/memory_usage.py
+python benchmarks/effect_filtration_scope.py
+
+# protein case study (writes diagrams to data/proteins/results/ and plots to figures/)
+python applications/analyse_proteins.py
+python applications/benchmark_lysozyme.py
+```
+
+The three notebooks in `notebooks/` read the CSVs and `.npy` diagrams produced
+above and assemble the figures and tables exactly as they appear in the thesis.
+Run the scripts first, then the notebooks.
+
+A note on figures: everything in `figures/` is generated. Delete the folder and
+re-run the scripts and you should get it back byte-for-byte, give or take
+matplotlib versions.
+
+## What the results say
+
+The short version, with the detail left for the thesis:
+
+- **The three algorithms agree, always.** This is the duality between homology
+  and cohomology made concrete: same pairs, birth and death simplices swapped.
+- **Empirical scaling sits well below the cubic worst case.** On the synthetic
+  datasets the fitted exponents come out far smaller than the $O(m^3)$ bound,
+  because the boundary matrices are sparse and pivot conflicts are rare. The
+  cohomology route is the quickest, since coboundary columns on VR complexes are
+  short.
+- **Capping the dimension matters.** Most of the simplices, and most of the
+  cost, live in the top dimensions; not computing homology you do not need is
+  the cheapest optimisation available.
+- **The topology of the proteins is legible.** The persistence diagrams pick out
+  components, loops, and voids straight from the coordinates, encouraging for
+  topology as a coordinate-free structural descriptor, though this is a small
+  proof-of-concept and the thesis is careful about not overclaiming.
+
+## References
+
+The algorithms and theory come mainly from:
+
+- H. Edelsbrunner, D. Letscher, A. Zomorodian. *Topological persistence and
+  simplification* (2002).
+- A. Zomorodian, G. Carlsson. *Computing persistent homology* (2005).
+- V. de Silva, D. Morozov, M. Vejdemo-Johansson. *Dualities in persistent
+  (co)homology* (2011).
+- U. Bauer. *Ripser: efficient computation of Vietoris–Rips persistence
+  barcodes* (2021).
+- C. Maria et al. *The GUDHI library* (2014).
+
+Full citations are in the thesis bibliography.
+
+## License
+
+Released under the MIT License. See [LICENSE](LICENSE).

persistent_homology-0.1.0/persistent_homology/__init__.py

@@ -0,0 +1,23 @@
+"""Persistent homology: a from-scratch implementation for Vietoris-Rips filtrations.
+
+The package computes persistent homology of point clouds through three
+interchangeable reduction strategies (standard, clearing, cohomology),
+exposed through the single entry point :func:`compute_persistence`.
+"""
+
+from .boundary import build_boundary_matrix
+from .filtration import vr_filtration
+from .persistence import compute_persistence, extract_diagram
+from .reduction import (add_columns_z2, reduce_pcoh, reduce_standard,
+                        reduce_with_clearing)
+
+__all__ = [
+    "compute_persistence",
+    "vr_filtration",
+    "build_boundary_matrix",
+    "add_columns_z2",
+    "reduce_standard",
+    "reduce_with_clearing",
+    "reduce_pcoh",
+    "extract_diagram",
+]

persistent_homology-0.1.0/persistent_homology/boundary.py

@@ -0,0 +1,41 @@
+"""Boundary matrix construction and Z/2Z column arithmetic.
+
+The boundary matrix encodes, for each simplex, its codimension-1 faces.
+Over Z/2Z a column is stored simply as the sorted list of row indices
+where it is non-zero, and column addition is symmetric difference.
+"""
+
+
+def build_boundary_matrix(filtration):
+    """Build the combined boundary matrix.
+
+    Parameters
+    ----------
+    filtration : list of (filtration_value, simplex_tuple)
+        The filtration, as returned by :func:`vr_filtration`.
+
+    Returns
+    -------
+    columns : list of lists
+        "columns[j]" is the sorted list of row indices "i" such that
+        simplex "i" is a codimension-1 face of simplex "j".
+    """
+    # Map each simplex to its index in the filtration
+    simplex_to_idx = {}
+    for idx, (_, simplex) in enumerate(filtration):
+        simplex_to_idx[simplex] = idx
+
+    m = len(filtration)
+    columns = [[] for _ in range(m)]
+
+    for j, (_, simplex) in enumerate(filtration):
+        if len(simplex) <= 1:
+            continue  # 0-simplices have empty boundary
+        # Faces: remove each vertex in turn
+        for i in range(len(simplex)):
+            face = simplex[:i] + simplex[i + 1:]
+            face_idx = simplex_to_idx[face]
+            columns[j].append(face_idx)
+        columns[j].sort()
+
+    return columns

persistent_homology-0.1.0/persistent_homology/datasets/__init__.py

@@ -0,0 +1 @@
+"""Dataset generators and loaders for the persistent homology experiments."""

persistent_homology-0.1.0/persistent_homology/datasets/proteins.py

@@ -0,0 +1,112 @@
+"""Download protein structures from the RCSB Protein Data Bank.
+
+Downloads the three proteins used in the Chapter 6 case study:
+
+* 1AKI: Lysozyme (single-domain enzyme, 129 residues)
+* 1EMA: Green Fluorescent Protein (beta-barrel, 221 residues)
+* 1A3N: Hemoglobin (tetramer, 572 residues)
+
+The PDB files are cached locally; rerunning the script does not
+re-download them. The script also extracts the C-alpha coordinates and
+saves them as plain .npy arrays for downstream use.
+"""
+
+from pathlib import Path
+
+import numpy as np
+
+from Bio.PDB import PDBList, PDBParser  # type: ignore[import-not-found]
+
+# Where to store the downloaded files and the extracted coordinates.
+DATA_DIR = Path("data/proteins")
+PDB_DIR = DATA_DIR / "pdb"
+COORDS_DIR = DATA_DIR / "ca_coords"
+
+# The three proteins used in the case study, with metadata for reference.
+PROTEINS = [
+    {"id": "1AKI", "name": "Lysozyme", "expected_residues": 129},
+    {"id": "1EMA", "name": "Green Fluorescent Protein", "expected_residues": 221},
+    {"id": "1A3N", "name": "Hemoglobin", "expected_residues": 572},
+]
+
+
+def download_pdb(pdb_id, target_dir):
+    """Download a PDB file via Biopython, return the local path.
+
+    Biopython caches the file by default; if the file is already present
+    it will not re-download. The filename pattern produced is
+    ``pdb{pdb_id_lower}.ent``; we rename it to ``{pdb_id}.pdb`` for
+    clarity.
+    """
+    target_dir.mkdir(parents=True, exist_ok=True)
+    target = target_dir / f"{pdb_id}.pdb"
+
+    if target.exists():
+        print(f"  {pdb_id}: already present at {target}")
+        return target
+
+    pdbl = PDBList(verbose=False)
+    # retrieve_pdb_file writes to pdir as 'pdb{id_lower}.ent' (or .cif).
+    raw = pdbl.retrieve_pdb_file(
+        pdb_id,
+        pdir=str(target_dir),
+        file_format="pdb",
+        overwrite=False,
+    )
+    # Rename for consistency.
+    Path(raw).rename(target)
+    print(f"  {pdb_id}: downloaded to {target}")
+    return target
+
+
+def extract_ca_coordinates(pdb_path, pdb_id):
+    """Return an (n, 3) array of C-alpha coordinates from a PDB file.
+
+    Only the first model is used (most PDB files have one model;
+    NMR ensembles have several, of which we keep the first). All chains
+    are included, so multi-chain proteins like hemoglobin yield the
+    union of C-alpha atoms across subunits. Non-standard residues and
+    HETATM records are skipped.
+    """
+    parser = PDBParser(QUIET=True)
+    structure = parser.get_structure(pdb_id, str(pdb_path))
+
+    coords = []
+    model = next(structure.get_models())  # first model only
+    for chain in model:
+        for residue in chain:
+            # Skip waters, ligands, etc. Standard residues have
+            # hetflag == ' '.
+            if residue.id[0] != " ":
+                continue
+            if "CA" in residue:
+                coords.append(residue["CA"].get_coord())
+
+    if not coords:
+        raise RuntimeError(f"No C-alpha atoms found in {pdb_path}")
+    return np.array(coords, dtype=np.float64)
+
+
+def main():
+    PDB_DIR.mkdir(parents=True, exist_ok=True)
+    COORDS_DIR.mkdir(parents=True, exist_ok=True)
+
+    for protein in PROTEINS:
+        pdb_id = protein["id"]
+        print(f"\n[{pdb_id}] {protein['name']}")
+
+        pdb_path = download_pdb(pdb_id, PDB_DIR)
+        coords = extract_ca_coordinates(pdb_path, pdb_id)
+
+        n = coords.shape[0]
+        expected = protein["expected_residues"]
+        status = "OK" if n == expected else f"WARNING: expected {expected}"
+        print(f"  Extracted {n} C-alpha atoms  [{status}]")
+
+        out = COORDS_DIR / f"{pdb_id}_ca.npy"
+        np.save(out, coords)
+        print(f"  Saved coordinates to {out}")
+
+
+if __name__ == "__main__":
+    main()