A common molecular-modeling puzzle is that a node’s own setting does not tell the whole story. An atom, residue, or other node can inherit visibility, selection, or locking state from an ancestor in the structure hierarchy. That makes it easy to search for the wrong thing: a node may have its visibility flag enabled and still be hidden because a parent is hidden.
SAMSON’s Node Specification Language (NSL) helps separate a node’s own flag from its effective state. That distinction is useful when you are diagnosing a display, checking a selection, or figuring out why part of a molecular hierarchy behaves differently than expected.
Visibility: flag versus effective state
Use node.visibilityFlag (short form n.vf) to query a node’s own visibility flag. For example, n.vf false finds nodes whose own flag is false.
Use node.visible (short form n.v) to ask whether a node is actually visible. A node is visible only when its visibility flag is true and its ancestors are visible. Conversely, node.hidden (short form n.h) matches nodes hidden either by their own flag or by an ancestor’s flag.
This gives you a practical way to narrow down a visibility problem:
n.vf falsechecks for nodes explicitly marked invisible.n.hchecks for nodes that are hidden in the hierarchy, including through inheritance.not n.vfinds nodes that are not effectively visible.n.vselects nodes that are visible, taking their ancestors into account.
If n.h finds a node but n.vf false does not, the difference is a useful clue: the node may be hidden because of an ancestor rather than its own visibility flag. You can then inspect the relevant hierarchy instead of changing individual atoms one by one.
The same distinction helps with selection and locking
Selection also has an own flag and an inherited state. node.selectionFlag (or n.sf) checks the node’s selection flag. node.selected (or n.s) matches nodes that are selected because their own flag is true or because an ancestor’s selection flag is true. For instance, n.sf false checks for nodes whose own selection flag is false, while not n.s checks for nodes that are not selected in the hierarchy.
Locking follows a similar pattern. node.lockedFlag (or n.lf) examines the node’s own locked flag, while node.locked (or n.l) also accounts for a locked ancestor. This can help distinguish a node that is directly locked from one that behaves as locked because of its place in the hierarchy.
A small habit that saves time
When investigating an unexpected state, ask two questions: “What is this node’s own flag?” and “What is its effective state after the hierarchy is considered?” In NSL, the flag attributes—n.vf, n.sf, and n.lf—answer the first question. The state attributes—n.v, n.s, and n.l—answer the second.
This is especially helpful when a search returns more nodes than expected, or when a child node seems to contradict its own settings. Rather than treating the result as inconsistent, check whether a parent contributes the inherited state.
For the full list of node attributes, values, and examples, see the SAMSON node attributes reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.