A molecular model can contain many structural groups, and visual inspection is a poor way to find a group with a particular size, composition, or charge. If you need to narrow down candidates—for example, to locate groups with a certain number of atoms or a specified structure ID—SAMSON’s Node Specification Language (NSL) lets you describe those properties as queries.
The key is to use the structuralGroup attribute space. Its short prefix is sg, and it matches structural group nodes. That scope matters: these expressions are for structural groups, not a general query for every kind of node in a molecular scene.
Start with the question you need answered
For a quick size screen, use numberOfAtoms, abbreviated nat. For example, sg.nat > 100 matches structural groups with more than 100 atoms. To specify a range, use sg.nat 100:200. This is useful when an enormous structure is making it hard to focus on groups of a manageable size—or when you want to check which groups fall within a chosen size band.
If total size is not informative enough, query particular element counts instead. The short names are nC for carbons, nH for hydrogens, nN for nitrogens, nO for oxygens, and nS for sulfurs. For instance, sg.nO 10:20 matches groups with 10 to 20 oxygen atoms, while sg.nC < 10 matches groups with fewer than 10 carbon atoms. The reference also lists ncga for the number of coarse-grained atoms.
These counts help answer different questions. A total atom count can find groups by scale; an element count can distinguish groups with similar sizes but different compositions. They are structural filters, not a substitute for interpreting the chemistry of a match.
Use charge and ID to narrow the search
Structural groups have two charge attributes. sg.fc queries total formal charge, while sg.pc queries total partial charge. For example, sg.fc 6:8 specifies formal charges in the range 6–8, and sg.pc 1.5:2.0 specifies partial charges in the range 1.5–2.0. Partial charge values can be decimal numbers; formal charge values are integers. Keep the distinction in mind when choosing a query: these attributes represent different charge descriptions.
If you already know which structure IDs you want, use sg.id. The expression sg.id >= 10 selects groups with an ID of 10 or greater. To specify multiple intervals, the reference gives sg.id 5:10, 25:30. This can be handy when checking a set of known structures without relying on names or visual position.
Make queries easier to read
Short names make repeated searches compact, but full names can be easier to understand later. For example, structuralGroup.numberOfAtoms > 100 is the long form of sg.nat > 100. When saving or sharing a query, use whichever form makes its intent clearest to the person who will read it.
Structural groups also inherit useful node attributes. You can query a group’s name with sg.n "A", or test visibility with sg.v and hidden status with sg.h. The inherited selected attribute is written sg.selected; this attribute does not have the short name s in the structural-group space.
A practical approach is to begin with one clearly defined property—size, composition, charge, ID, or visibility—and inspect the matches before refining your search. Keeping the criterion explicit makes it easier to tell whether a query is answering the actual modeling question.
For the complete attribute reference and additional examples, see the SAMSON structural group attributes documentation.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.