When a molecular model contains many structural groups, spotting the one you need can turn into a tedious counting exercise. Is this group unusually large? Does it contain a particular number of oxygen atoms? Which groups have a specific charge? SAMSON’s Node Specification Language (NSL) lets you describe these properties as search criteria, so you can focus on groups that meet a clear condition instead of inspecting them one by one.
This is especially useful when you are narrowing down a model by composition, size, or charge. The structural-group attribute space is written structuralGroup, or more briefly sg. Its attributes describe structural groups—not individual atoms—and include counts of selected element types, total atom count, formal charge, partial charge, and structure ID.
Start with a practical question
Think of each query as a way to turn a modeling question into a testable condition. For example, if you want to find groups containing more than 100 atoms, use:
sg.nat > 100
The longer form is structuralGroup.nat > 100. Both use the numberOfAtoms attribute. To look for groups with an atom count between 100 and 200, use sg.nat 100:200.
These patterns can help you quickly define a size range that is relevant to your model. Rather than counting atoms manually, specify the threshold or interval that matches the question you are investigating.
Filter by elemental composition
Structural groups also have element-specific atom counts. The short names are nC for carbon, nH for hydrogen, nN for nitrogen, nO for oxygen, and nS for sulfur. For instance:
sg.nC < 10matches groups with fewer than 10 carbon atoms.sg.nO 10:20matches groups with between 10 and 20 oxygen atoms.sg.nN < 10matches groups with fewer than 10 nitrogen atoms.
The same comparison and range style applies to these atom-count attributes. That makes it easy to adapt a query: change the element or the numeric condition to express a different composition-based criterion. For example, sg.nH 10:20 checks a hydrogen-count range, while sg.nS < 10 checks a sulfur-count threshold.
Use charge as a selection criterion
When charge is the property that matters, NSL provides two distinct attributes. sg.fc refers to total formal charge and accepts integers. sg.pc refers to total partial charge and accepts real numbers. For example, sg.fc 6:8 describes a formal-charge range, while sg.pc 1.5:2.0 describes a partial-charge range.
Keeping these attributes separate is important: formal charge and partial charge are different quantities, and their query values are expressed differently. Use sg.fc when you mean formal charge; use sg.pc when you mean partial charge.
Identify groups by structure ID
If you are looking for groups associated with particular structure IDs, use sg.id. You can specify a single value, a comparison, or multiple intervals. For example, sg.id >= 10 selects IDs greater than or equal to 10, and sg.id 5:10, 25:30 specifies the ranges 5–10 and 25–30.
A small query vocabulary, many useful checks
A helpful way to build confidence with structural-group searches is to begin with one attribute and one condition. Use sg.nat for total size, the element-count short names for composition, sg.fc or sg.pc for charge, and sg.id for structure IDs. The examples above show how to express thresholds, ranges, and—in the structure-ID example—multiple ranges.
NSL also exposes inherited node attributes for structural groups, including sg.name, sg.visible, sg.hidden, and sg.selected. These can help describe groups by name or state as well as by molecular properties. For example, the documented name syntax includes sg.n "A". The selected attribute is written sg.selected; it does not have the short name s in this attribute space.
For the full attribute list and additional examples, see the structural group attributes reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.