A molecular scene can contain models that look similar but differ in exactly the details that matter: atom count, chain count, residue count, or total charge. Finding the right one by clicking through objects is slow—and visual inspection will not reliably reveal those properties. SAMSON’s Node Specification Language (NSL) lets you search structural models by measurable attributes instead.
The useful shift is to describe the model you want, rather than trying to recognize it by eye. Structural-model attributes live in the structuralModel attribute space, abbreviated sm. The expressions below are examples from the reference; the short forms keep repeated searches compact.
Start with size and organization
If you are trying to rule out models that are too large, search by atom count. For example, sm.nat < 1000 matches structural models with fewer than 1,000 atoms. To focus on a size band, use a range such as sm.nat 100:200. The same pattern applies to several useful organizational counts:
sm.nc < 3searches by number of chains.sm.nm 2:4searches by number of molecules.sm.nr > 130searches by number of residues.sm.ns 1:3searches by number of segments.sm.nsg > 10searches by number of structural groups.
These counts answer different questions. A model’s atom count describes its overall size, while chain, molecule, residue, segment, and structural-group counts describe aspects of its organization. Choosing the attribute that matches your question can make a search more informative than relying on size alone.
Use composition as a quick check
When the chemical makeup matters, NSL provides counts for selected elements. For instance, sm.nC 10:20 searches by carbon count, while sm.nN < 10, sm.nO 10:20, and sm.nS < 10 search by nitrogen, oxygen, and sulfur counts. Hydrogen counts use sm.nH. For coarse-grained models, sm.ncga is the short name for the number of coarse-grained atoms.
These attributes are handy for narrowing a set of candidate models or checking whether a model’s composition is in the expected range. They are counts, not a substitute for inspecting atom identities or connectivity when those details are important.
Search by charge when charge is the key distinction
Structural models expose both total formal charge and total partial charge. Formal charge uses sm.fc and integer values: sm.fc 1 matches a formal charge of 1, while sm.fc 6:8 searches a range. Partial charge uses sm.pc and real values: sm.pc 1.5:2.0 searches for models with a total partial charge in that interval. Keeping the two attributes distinct matters: they represent different kinds of charge and use different value types.
Make the search readable
NSL also supports the longer attribute names, such as structuralModel.numberOfAtoms < 100, alongside short forms such as sm.nat < 100. Use the long form when documenting a search for collaborators; use the short form when you want a compact expression. Structural models also inherit node attributes for properties such as visibility, selection, and name. For example, sm.v tests visibility, and sm.n "A" searches by name. The documentation shows sm.n "L*" as another name-query example.
A practical workflow is to begin with the property that best separates your candidates—perhaps atom count or residue count—then check composition or charge as needed. Treat each expression as a precise question about a structural model, and consult the attribute reference for the available names and value types before building more elaborate searches.
For the complete attribute list and examples, see the structural model attributes reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.