A quicker way to sort molecular models by size and composition

When a project contains many structural models, finding the one you need can become a small but persistent time sink. You may be looking for a compact model, a structure with a particular number of chains, or a model whose elemental composition fits a downstream task. Opening models one at a time to inspect these properties makes comparison harder than it needs to be.

SAMSON’s Node Specification Language (NSL) lets you express these checks as queries on structural models. The structural model attribute space uses the prefix sm. Its attributes include counts of atoms, chains, molecules, residues, segments, and selected elements, as well as total formal and partial charge. The examples below show how to turn common screening questions into readable expressions.

Start with model size

If your first question is simply “Which models are small enough to inspect?”, query the number of atoms. For example, sm.nat < 1000 matches structural models with fewer than 1,000 atoms. To focus on a band of sizes instead, use a range: sm.nat 100:200.

This is useful for narrowing a large set before you examine individual structures. The same pattern applies to other integer counts: use a comparison to set a threshold, or a range to describe a window. For instance, sm.nc < 3 searches by chain count, while sm.nc 2:4 specifies a range of chain counts.

Use composition counts to refine the search

Atom totals alone may not distinguish the models you care about. NSL also provides element-specific counts, including carbon, hydrogen, nitrogen, oxygen, and sulfur. For example, sm.nO < 10 expresses a search for models with fewer than 10 oxygen atoms, and sm.nC 10:20 selects by a carbon-count range.

These attributes can help you turn a vague inspection task into a concrete question: “Does this model fall within the composition range I’m looking for?” Other available counts include coarse-grained atoms (sm.ncga), residues (sm.nr), molecules (sm.nm), segments (sm.ns), and structural groups (sm.nsg). For example, sm.nr > 130 queries models with more than 130 residues.

Check charge when it matters

For charge-related screening, distinguish between formal charge and partial charge. sm.fc queries total formal charge using integer values; sm.pc queries total partial charge using real values. The documentation gives examples such as sm.fc 6:8 and sm.pc 1.5:2.0. These can be useful when charge is part of the criteria you already use to assess a model.

Make queries easier to read

The short forms are designed to keep expressions compact: sm.nat means number of atoms, sm.nC means number of carbons, and sm.nr means number of residues. If you are still learning the abbreviations, the full attribute names—such as structuralModel.numberOfAtoms—are also documented. Start with the full name if that is clearer, then switch to the short form when you recognize the attributes you use often.

One practical habit is to write down the property you want to check before composing a query: model size, chain count, elemental composition, or charge. Then choose the corresponding attribute and a threshold or range that reflects your screening criterion. This keeps the expression tied to a meaningful question instead of turning it into a collection of unexplained abbreviations.

Structural models also inherit node attributes such as name, visibility, and selection state. These can help describe model nodes in other searches; for example, sm.v checks visibility and sm.n "A" searches by name. The structural model reference lists these alongside the model-specific counts.

For the full attribute list and additional examples, see the structural model attributes documentation.

Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.

Comments are closed.