Memory optimization

.github/workflows/update-readme.yml

@@ -0,0 +1,82 @@
+name: Update README badges
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  update-badges:
+    if: github.actor != 'github-actions[bot]'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Rewrite badge block in README
+        env:
+          OWNER: ${{ github.repository_owner }}
+          REPO: ${{ github.event.repository.name }}
+        run: |
+          python3 <<'PY'
+          import os
+          from pathlib import Path
+
+          readme = Path("README.md")
+          text = readme.read_text()
+
+          start = "<!-- badges:start -->"
+          end = "<!-- badges:end -->"
+
+          if start not in text or end not in text:
+              raise SystemExit("README.md is missing badge markers")
+
+          owner = os.environ["OWNER"]
+          repo = os.environ["REPO"]
+
+          badge_block = (
+              f"<!-- badges:start -->\n"
+              f"[![GitHub Actions Build Status](https://github.com/{owner}/{repo}/workflows/CI/badge.svg)]"
+              f"(https://github.com/{owner}/{repo}/actions?query=workflow%3ACI)\n"
+              f"[![codecov](https://codecov.io/gh/{owner}/{repo}/graph/badge.svg?token=JKDOXOYPRS)]"
+              f"(https://codecov.io/gh/{owner}/{repo})\n"
+              f"[![Documentation Status](https://readthedocs.org/projects/frustratometer/badge/?version=latest)]"
+              f"(https://frustratometer.readthedocs.io/en/latest/?badge=latest)\n"
+              f"<!-- badges:end -->"
+          )
+
+          before, rest = text.split(start, 1)
+          _, after = rest.split(end, 1)
+          new_text = before + badge_block + after
+
+          # Rewrite clone URL
+          clone_start = "<!-- clone:start -->"
+          clone_end = "<!-- clone:end -->"
+          if clone_start in new_text and clone_end in new_text:
+              clone_block = (
+                  f"<!-- clone:start -->\n"
+                  f"    git clone https://github.com/{owner}/{repo}\n"
+                  f"<!-- clone:end -->"
+              )
+              cb, crest = new_text.split(clone_start, 1)
+              _, cafter = crest.split(clone_end, 1)
+              new_text = cb + clone_block + cafter
+
+          if new_text != text:
+              readme.write_text(new_text)
+              print("README updated.")
+          else:
+              print("README already up to date.")
+          PY
+
+      - name: Commit changes if needed
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add README.md
+          git diff --cached --quiet || git commit -m "Update README badges for ${{ github.repository }}"
+          git diff --cached --quiet || git push

README.md

@@ -1,9 +1,10 @@
 Frustratometer
 ==============================
-[//]: # (Badges)
+<!-- badges:start -->
 [![GitHub Actions Build Status](https://github.com/cabb99/Frustratometer/workflows/CI/badge.svg)](https://github.com/cabb99/Frustratometer/actions?query=workflow%3ACI)
-[![codecov](https://codecov.io/gh/HanaJaafari/Frustratometer/graph/badge.svg?token=JKDOXOYPRS)](https://codecov.io/gh/HanaJaafari/Frustratometer)
+[![codecov](https://codecov.io/gh/cabb99/Frustratometer/graph/badge.svg?token=JKDOXOYPRS)](https://codecov.io/gh/cabb99/Frustratometer)
 [![Documentation Status](https://readthedocs.org/projects/frustratometer/badge/?version=latest)](https://frustratometer.readthedocs.io/en/latest/?badge=latest)
+<!-- badges:end -->
 
 
 
@@ -39,7 +40,9 @@ Note: `openmm` and `pdbfixer` are not available on PyPI and must be installed se
 
 ### From source
 
-    git clone https://github.com/HanaJaafari/Frustratometer
+<!-- clone:start -->
+    git clone https://github.com/cabb99/Frustratometer
+<!-- clone:end -->
     cd Frustratometer
     conda install -c conda-forge --file requirements.txt
     pip install -e .

devtools/profiling.py

@@ -0,0 +1,86 @@
+"""
+Profiling utilities for tracking memory usage and execution time.
+
+Usage (from the project folder)
+    from devtools.profiling import track_time, track_memory, profile
+
+    # Context managers
+    with track_time("Building AWSEM model"):
+        model = frustratometer.AWSEM(structure)
+
+    with track_memory("AWSEM sparse"):
+        model = frustratometer.AWSEM(structure, sparse=True)
+
+    # Decorator
+    @profile
+    def my_function():
+        ...
+"""
+
+import time
+import tracemalloc
+import functools
+from contextlib import contextmanager
+
+
+@contextmanager
+def track_time(label=""):
+    """Context manager that prints elapsed wall-clock time."""
+    start = time.perf_counter()
+    yield
+    elapsed = time.perf_counter() - start
+    tag = f" [{label}]" if label else ""
+    print(f"Time{tag}: {elapsed:.4f} s")
+
+
+@contextmanager
+def track_memory(label=""):
+    """Context manager that prints peak memory allocated inside the block.
+
+    Uses ``tracemalloc`` to measure only *new* Python allocations within the
+    block, so the numbers reflect the incremental cost of the code inside.
+    """
+    tracemalloc.start()
+    snapshot_before = tracemalloc.take_snapshot()
+    yield
+    snapshot_after = tracemalloc.take_snapshot()
+    tracemalloc.stop()
+    stats = snapshot_after.compare_to(snapshot_before, "lineno")
+    total = sum(s.size_diff for s in stats if s.size_diff > 0)
+    tag = f" [{label}]" if label else ""
+    print(f"Memory{tag}: {_fmt_bytes(total)}")
+
+
+@contextmanager
+def track_peak_memory(label=""):
+    """Context manager that prints the peak memory usage (high-water mark)."""
+    tracemalloc.start()
+    yield
+    _, peak = tracemalloc.get_traced_memory()
+    tracemalloc.stop()
+    tag = f" [{label}]" if label else ""
+    print(f"Peak memory{tag}: {_fmt_bytes(peak)}")
+
+
+def profile(func):
+    """Decorator that prints time and peak memory for a function call."""
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        tracemalloc.start()
+        start = time.perf_counter()
+        result = func(*args, **kwargs)
+        elapsed = time.perf_counter() - start
+        _, peak = tracemalloc.get_traced_memory()
+        tracemalloc.stop()
+        print(f"{func.__name__}: {elapsed:.4f} s, peak {_fmt_bytes(peak)}")
+        return result
+    return wrapper
+
+
+def _fmt_bytes(n):
+    """Format byte count in human-readable units."""
+    for unit in ("B", "KB", "MB", "GB"):
+        if abs(n) < 1024:
+            return f"{n:.2f} {unit}"
+        n /= 1024
+    return f"{n:.2f} TB"

docs/api_classes.rst

@@ -33,7 +33,7 @@ The frustratometer package provides a handful of classes used to encapsulate the
    :inherited-members:
    :private-members:  
 
-.. autoclass:: Frustratometer
+.. autoclass:: frustratometer.classes.Frustratometer.Frustratometer
    :members:
    :undoc-members:
    :member-order: bysource
@@ -49,4 +49,14 @@ The frustratometer package provides a handful of classes used to encapsulate the
    :inherited-members:
    :private-members:  
 
+.. autoclass:: SparseMatrix
+   :members:
+   :undoc-members:
+   :member-order: bysource
+   :show-inheritance:
 
+.. autoclass:: Gamma
+   :members:
+   :undoc-members:
+   :member-order: bysource
+   :show-inheritance:

docs/examples_awsem.rst

@@ -9,18 +9,30 @@ The Frustratometer package includes a prody-based Structure class to load the st
 .. code-block:: python
 
     import frustratometer
+    from pathlib import Path
 
     # Define the path to your PDB file
     pdb_path = Path('data/my_protein.pdb')
-    # Load the structure
+    # Load the structure (dense distance matrix)
     structure = frustratometer.Structure.full_pdb(pdb_path)
     structure.sequence #The sequence of the structure
 
+For large proteins you can use a sparse distance matrix to avoid allocating the
+full :math:`(L, L)` array:
+
+.. code-block:: python
+
+    structure_sparse = frustratometer.Structure.full_pdb(pdb_path, sparse=True)
+
 Creating an AWSEM Model Instance
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 After loading the structure, create an AWSEM model instance with the desired parameters. Here we provide some typical configurations that can be found elsewhere.
 
+The AWSEM constructor defaults to ``sparse=True``, building a sparse Potts model
+that stores couplings only at contact positions. Pass ``sparse=False`` to build
+the full dense representation.
+
 .. code-block:: python
 
     ## Single residue frustration with electrostatics

docs/examples_dca.rst

@@ -9,6 +9,7 @@ The Frustratometer package includes a prody-based Structure class to load the st
 .. code-block:: python
 
     import frustratometer
+    from pathlib import Path
 
     # Define the path to your PDB file
     pdb_path = Path('data/my_protein.pdb')
@@ -23,7 +24,13 @@ After loading the structure, create a DCA model instance with the desired parame
 
 When using Potts Model files generated by the mfDCA algorithm, make sure to set the "reformat_potts_model" to True.
 
+All DCA factory methods default to ``sparse=True``, which stores couplings only
+at contact positions to avoid allocating the full :math:`(N, N, 21, 21)` tensor.
+Pass ``sparse=False`` if you need the dense representation (e.g. for contact
+prediction via ``scores()``).
+
 .. code-block:: python
+
     potts_model_file=Path('data/my_potts_model.mat')
 
     ## Using existing potts model file
@@ -36,6 +43,7 @@ Check the Accuracy of the Potts Model
 In order to check the accuracy of the contacts predicted by the Potts model and true contacts from the protein's contact map, the receiver operator curve (ROC) can be generated. If the Potts model has high accuracy, the Area Under the Curve (AUC) of the ROC will be 1.
 
 .. code-block:: python
+
     ## Generate the ROC curve
     model_dca.plot_roc()
 

docs/frustratometer.rst

@@ -27,7 +27,7 @@ In this module, we implement a version of the frustratometer based on Direct Cou
 Copyright
 ---------
 
-Copyright (c) 2022-2024, Carlos Bueno, Hana Jaafari
+Copyright (c) 2022-2026, Carlos Bueno, Hana Jaafari
 
 Acknowledgements
 ----------------

docs/index.rst

@@ -14,6 +14,7 @@ Welcome to Frustratometer's documentation!
    installation
    examples_awsem
    examples_dca
+   sparse
    api_classes
    api_modules