When a project contains many structural models, it can be tedious to find the one you need by opening each model and checking its size, composition, or charge. SAMSON’s Node Specification Language (NSL) provides a compact way to describe those properties and identify matching structural models.
This guide focuses on a practical use case: narrowing a collection of structures by size, atom composition, chain or residue count, and charge. The examples use the structuralModel attribute space, whose short name is sm. These attributes match structural model nodes, so they are useful when your question is about a model as a whole rather than an individual atom.
Start with the scale of the structure
If you need to find models above or below a size threshold, use numberOfAtoms, abbreviated nat. For example, sm.nat < 1000 describes models with fewer than 1,000 atoms. To look for a size band, use a range: sm.nat 100:200.
The same pattern applies to several other counts. To find models with fewer than three chains, use sm.nc < 3; to look for two to four molecules, use sm.nm 2:4. For residue counts, sm.nr > 130 describes models with more than 130 residues. These examples let you express a useful criterion directly, instead of relying on a visual guess about model size.
Use composition as a quick filter
Atom-count attributes can help distinguish models with different compositions. The short names are nC for carbons, nH for hydrogens, nN for nitrogens, nO for oxygens, and nS for sulfurs. For example, sm.nO 10:20 expresses a search for models in the documented oxygen-count range, while sm.nC < 10 expresses a carbon-count threshold.
There are also attributes for coarse-grained atoms and structural groups: sm.ncga and sm.nsg. These can be more relevant than total atom count when you are comparing models that represent structure at different levels of detail. For example, sm.ncga < 1000 sets a coarse-grained-atom threshold, and sm.nsg > 10 describes models with more than ten structural groups.
Check charge when composition is not enough
Two models with similar sizes can still differ in charge. The formal-charge attribute is sm.fc; for instance, sm.fc 1 matches a formal charge of 1, and sm.fc 6:8 describes a range from 6 to 8. For partial charge, use sm.pc: sm.pc 1.5:2.0 describes models with partial charge between 1.5 and 2.0.
Formal charge accepts integer values, while partial charge accepts real values. Keeping that distinction in mind helps you choose an attribute that matches the property you are checking.
A simple way to plan a search
Before writing a query, turn the problem into a measurable question: Is the model too large? Does it have too many chains? Are you looking for a particular elemental count or charge range? Then choose the corresponding attribute and start with a clear threshold or interval. For example, a first pass for models with 100–200 atoms can use sm.nat 100:200; a separate pass for a desired residue count can use sm.nr 100:130.
These are individual example expressions from the structural-model reference. They show how each attribute is written; they do not, by themselves, specify how to combine several criteria into one expression. Begin with the criterion that best separates the candidates, then consult the NSL examples if you need to build more involved searches.
Structural models also inherit node attributes such as sm.h for hidden, sm.v for visible, and sm.selected for selected. These can help describe model state in addition to structural properties. The selected attribute has no short name in this attribute space, so use its full form.
For the complete attribute list and additional examples, see the structural model attributes reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.