ENM Base class by stratixs · Pull Request #22 · biotite-dev/springcraft

stratixs · 2026-06-08T12:35:28Z

Logical changes

Adds a base class ENM that handles common logic across GNM and ANM (specifically constructor, covariance calculation, calls to NMA). The goal is to reduce code duplications.
The covariance is calculated with np.linalg.pinv. Internally this method uses np.linalg.eigh to calculate the eigenvalues/-vectors and constructs the pseudo-inverse using the reciprocal eigenvalues. This change makes this calculation explicitly and stores the eigenvalues/-vectors in the process so that they can be easily reused for NMA calculations without recalculation.
Instead of relying on fixed number of trivial nodes the number of zero eigenvalues can be centrally calculated and returned alongside when calling the ENM.eigen() function.
Optimize NMA calculations to reduce complexity for maintainers. These changes are also a result from the common attributes introduced by the ENM base class.

Bug fixes

Use direct evaluation of coord difference between atoms instead of calling struc.displacement as the latter one forces float32 precision but float64 is desired.

Housekeeping

Switches to hatch build system (the same as the biotite parent project)
Extends/corrects docstrings to adhere to numpydoc standard (uses the same numpydoc lint rules as the parent project)
Adds type information to attributes and return values so that users can utilize IDE's static analyzers when calling the functions
Switches from .pdb to .cif files for tests because RCSB will phase out the old format.
Boost test coverage from

Name                             Stmts   Miss Branch BrPart  Cover
------------------------------------------------------------------
src/springcraft/__init__.py          8      0      0      0   100%
src/springcraft/anm.py              79     18     24      4    73%
src/springcraft/forcefield.py      249     25     64     17    86%
src/springcraft/gnm.py              70     17     24      4    71%
src/springcraft/interaction.py      61      3     18      3    92%
src/springcraft/nma.py             151     44     58     10    66%
------------------------------------------------------------------
TOTAL                              618    107    188     38    78%

to

Name                             Stmts   Miss Branch BrPart  Cover
------------------------------------------------------------------
src/springcraft/__init__.py          8      0      0      0   100%
src/springcraft/anm.py              61      2      8      0    97%
src/springcraft/enm.py             112      5     28      2    95%
src/springcraft/forcefield.py      276     18     64     10    91%
src/springcraft/gnm.py              51      0      8      0   100%
src/springcraft/interaction.py      62      3     18      3    92%
src/springcraft/nma.py             109     35     42      7    62%
------------------------------------------------------------------
TOTAL                              679     63    168     22    88%

calculation into respective classes

perturbation

update

docstring updates and hatch building system

build system

JHKru

Hi, thanks for your extensive contributions!
They are well-thought out and structured, but for the future, feel free to size them down to multiple individual commits that are easier to handle and review on their own.

A few additional points for discussion:

Regarding changes to the build system -> To what extent/why are these necessary? Any need to (mostly) switch away from conda here?
You might like to squash/combine some of intermediate commits, because it is a bit difficult to follow.
For instance, in intermediate commits a Cython extension for ENM-perturbation is set up, that is not part of the overall PR, if I'm not mistaken (commit 39d2795)?

JHKru · 2026-06-14T16:52:43Z

+      - uses: actions/upload-artifact@v7
        with:
-          name: Springcraft distribution
+          name: release-dist


Any reason for this change here?

JHKru · 2026-06-14T16:56:05Z

-        This is not a copy: Create a copy before modifying this matrix.
    masses : None or ndarray, shape=(n,), dtype=float
        The mass for each atom, `None` if no mass weighting is applied.
+    hessian : ndarray, shape=(n,n), dtype=float


If I'm not mistaken shape=(n3, n3) is expected here (Hessian).

JHKru · 2026-06-14T18:13:35Z

    return join(dirname(realpath(__file__)), "data")
+
+
+def load_protein_structure(pdb_id: str) -> struc.AtomArray:


pdb_id could be replaced with cif_id for clarity here.

JHKru · 2026-06-14T21:09:11Z

+            i = 0
+            while self._eig_values[i] < -threshold:
+                i = i + 1
+            n_neg = i
+            while self._eig_values[i] <= threshold:
+                i = i + 1
+            n_triv = i + n_neg


This could be handled by regular Numpy indexing/Boolean masks, instead of directly looping through the Array.

JHKru · 2026-06-14T21:21:15Z

-    enm : ANM or GNM
-        Elastic network model; an instance of either an GNM or ANM
-        object.
+    enm : ENM


Could be kept it specific here and in the remainder of the file, like in the example above (eigen):
"Elastic network model; an instance of either a GNM or ANM"

stratixs added 30 commits May 1, 2026 18:33

Update dependencies

af31ef6

Add type information

68a6091

Add ENM base class

1a4fc94

Eigenvalues and -vectors as class attributes

561496c

Moved shared nma calls into ENM base class

f68114f

Move adjacency calculation into ENM base class and Kirchhoff/Hessian

4e6e697

calculation into respective classes

Make ENM.eigen() be able to return number of zero eigenvalues

cdb82a3

Boost test coverage for GNM and ANM

ea615ae

Make ForceField updatable

364f1a8

Fix ForceField test

46a97f1

Add benchmark dependency

aabd0c3

Fix inverse calculation

8925369

Merge branch 'base-class' into perturbation

53855aa

Add covariance perturbation for GNM

7b5881f

Fix covariance perturbation

24a2be6

Restructure covariance perturbation

c4d4a00

Further covariance perturbation restructuring and optimization

b658ad7

Initial ANM covariance perturbation

460417e

Add cython setup for eigenvalue perturbation

39d2795

Sync changes with branches

c6ecc33

Use covariance matrix for msqf if available

077f84c

ANM msqf tests

fb18abf

Add frequency perturbation

8c248d8

Generalize modify_contact algorithm

bc36226

Merge branch eigen-perturbation into perturbation; update to covariance

6c9c060

perturbation

Rework modify_atom

09dacde

Merge branch 'perturbation' into base-class; upstream changes

16708de

Merge branch 'base-class' into perturbation; mean square fluctuation

0a6d5b1

update

revert changes to interaction calculation

01657f1

Make enm.eigen() return nb of zero eigenvalues instead of zero mask

4443f9d

stratixs added 28 commits June 1, 2026 20:52

Add msqf and bfactor one-rank perturbation

34db29e

Merge branch 'perturbation' into eigen-perturbation

7330be5

Add frequency perturbation

99616d8

Change functions names from '_pert' to _chng'

eb30109

Add msqf and bfactor algorithm for subsets

b341dfb

Rework dcc calculation and add dcc one-rank update

9263a14

Function and variable renaming

b6b0135

Docstring corrections

1db6a98

Docstring overhaul

872902b

Update README and advanced documentation

5c28bee

github actions update

7899877

Fix doc deploy env

2d91503

Fix githuib workflows

9b15662

Workflow fix

3382454

Update test.yml

80a508c

Change build system to hatch

a2c3efa

Fix cython args and changes to deploy workflow

b55a30e

Update deploy.yml

8cd643a

Update deploy.yml

46f5248

Remove unnecessary hatch dev env and fix build-docs in deploy workflow

0d0661b

Update deploy.yml

099b8c3

Finalize deploy workflow

df81110

Fix to modify_contact

a165ae0

Merge branch 'eigen-perturbation' into perturbation; NMA perturbation,

18e5d2a

docstring updates and hatch building system

Merge branch 'perturbation' into base-class; numpy docstrings and hatch

fcbd3b2

build system

Prs test with cif

c51e3d7

fix deploy workflow

c87dda2

Remove unused import

38456cc

JHKru reviewed Jun 14, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ENM Base class#22

ENM Base class#22
stratixs wants to merge 63 commits into
biotite-dev:masterfrom
stratixs:base-class

stratixs commented Jun 8, 2026 •

edited

Loading

Uh oh!

JHKru left a comment

Uh oh!

JHKru Jun 14, 2026

Uh oh!

JHKru Jun 14, 2026

Uh oh!

JHKru Jun 14, 2026

Uh oh!

JHKru Jun 14, 2026

Uh oh!

JHKru Jun 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		return join(dirname(realpath(__file__)), "data")


		def load_protein_structure(pdb_id: str) -> struc.AtomArray:

Conversation

stratixs commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Logical changes

Bug fixes

Housekeeping

Uh oh!

JHKru left a comment

Choose a reason for hiding this comment

Uh oh!

JHKru Jun 14, 2026

Choose a reason for hiding this comment

Uh oh!

JHKru Jun 14, 2026

Choose a reason for hiding this comment

Uh oh!

JHKru Jun 14, 2026

Choose a reason for hiding this comment

Uh oh!

JHKru Jun 14, 2026

Choose a reason for hiding this comment

Uh oh!

JHKru Jun 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

stratixs commented Jun 8, 2026 •

edited

Loading