When a molecular model contains many structural groups, inspecting each one manually can make a simple question surprisingly slow: Which groups contain a certain number of atoms? Which have a particular charge? Where are the groups with a specific composition? SAMSON’s Node Specification Language (NSL) lets you express these criteria as attribute-based searches.
This guide focuses on one practical task: narrowing structural groups by size, elemental composition, charge, or structure ID. The relevant attribute space is structuralGroup, abbreviated sg. It matches structural group nodes, so you can start a query with sg rather than spelling out structuralGroup.
Start with the question you need to answer
If you are looking for groups by size, use numberOfAtoms, or its short name nat. For example, sg.nat > 100 matches groups with more than 100 atoms, while sg.nat 100:200 matches groups whose atom count is between 100 and 200. A range is useful when you have a size band in mind; a comparison is useful when you only need a lower or upper threshold.
For composition, use the element-count attributes. The short names are nC for carbon, nH for hydrogen, nN for nitrogen, nO for oxygen, and nS for sulfur. For example, sg.nC < 10 looks for groups with fewer than 10 carbon atoms, and sg.nO 10:20 looks for groups with 10 to 20 oxygen atoms. The same comparison and range style applies to these counts. If your model uses coarse-grained atoms, sg.ncga searches by their number; it is distinct from the total atom count, sg.nat.
Use the right kind of charge
Charge searches have two separate attributes. sg.fc is the total formal charge, expressed as an integer. For example, sg.fc 1 matches a formal charge of 1, and sg.fc 6:8 matches values between 6 and 8. sg.pc is the total partial charge and accepts real-number values. For instance, sg.pc 1.5:2.0 searches for partial charges between 1.5 and 2.0.
Keeping these attributes distinct helps avoid a common search mistake: selecting a charge field based only on the word “charge.” Choose fc when the criterion is formal charge, and pc when it is partial charge. The documentation lists the expected value types, so it is worth checking those before writing a query.
Don’t confuse a structure ID with a size
The attribute sg.id refers to a structural group’s structure ID; it does not count atoms or identify an element. You can compare IDs, as in sg.id >= 10, or specify multiple ranges, as in sg.id 5:10, 25:30. This is useful when you already know which ID values you want to match.
A small, repeatable search routine
-
Decide what property defines the groups you need: size, element count, formal charge, partial charge, or ID.
-
Choose the corresponding attribute, using the short name for a compact query: for example,
nat,nO,fc,pc, orid. -
Set a value, comparison, or range that reflects your criterion. For counts, use integers; for partial charge, use real values.
-
Read the expression back in plain language before using it. For example,
sg.nat < 1000means fewer than 1000 atoms, whereassg.nO 10:20is a range for oxygen count.
NSL also exposes inherited node attributes for structural groups, including name, visibility, and selection state. Those can help describe the group itself, while the structural-group-specific attributes above address composition, charge, and ID. The complete reference includes the available names, short names, value types, and examples.
Read the structural group attributes reference to learn more.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.