Are Your Molecules Really Visible? Understanding Visual and Selection Flags in SAMSON

When working with complex molecular models, it’s not uncommon to spend precious minutes (or longer) trying to figure out why a molecule doesn’t show up in your scene or stays stubbornly excluded from selections. In the SAMSON molecular design platform, such issues often boil down to how visibility and selection are managed via internal flags and attributes.

In this post, we explore how molecule visibility and selection attributes work in SAMSON’s Node Specification Language (NSL), and how understanding them can help molecular modelers avoid frustration and ensure consistency when analyzing or scripting large molecular systems.

What controls visibility and selection in NSL?

In SAMSON, molecules have multiple attributes that affect their appearance, selection status, and interactivity. These include both user-visible flags (like visible or selected) and lower-level control flags (like visibilityFlag or selectionFlag). Here’s a breakdown:

mol.v (visible): Indicates whether the molecule is visible.
mol.vf (visibilityFlag): A finer-grained control that influences how visibility is computed. Toggling this can override visibility.
mol.selected: Shows whether the molecule is currently selected. No short name is defined for this attribute.
mol.sf (selectionFlag): Similar to visibilityFlag, but manages the automatic handling of selection.

If your molecule appears “invisible” even when mol.v is true, the issue could lie with mol.vf set to false. The same applies to selection behaviors: mol.sf false could prevent a molecule from being reacted to in scripts or user actions, even though it looks selected.

Why does this matter?

When scripting, automating workflows, or filtering large molecular scenes, relying solely on mol.v or mol.selected without checking the corresponding flags can lead to unexpected behaviors. For example, your script might assume a visible molecule is ready for simulation—when in fact it’s suppressed due to a mismatched visibilityFlag.

Best practices for consistency

Always check related flags: When diagnosing issues or writing selection filters, evaluate both mol.v and mol.vf, as well as mol.selected and mol.sf.
Be explicit in NSL queries: Instead of using mol.v alone, use mol.v mol.vf to ensure both visibility conditions are satisfied.
Invert where necessary: Use not mol.v or mol.sf false explicitly when filtering out hidden or unselectable molecules.

Examples

mol.v mol.vf           // Molecules truly visible in the scene
mol.selected mol.sf    // Molecules eligible for manipulation
not mol.v              // Hidden molecules (may still have visibilityFlag true)
mol.vf false           // Molecules where visibility is disabled via flag

mol.v mol.vf // Molecules truly visible in the scene

mol.selected mol.sf // Molecules eligible for manipulation

not mol.v // Hidden molecules (may still have visibilityFlag true)

mol.vf false // Molecules where visibility is disabled via flag

By understanding these subtle controls, molecular modelers can take full advantage of NSL to perform robust, precise queries—even in crowded or hierarchical molecular scenes.

For a deeper dive into molecule attributes in NSL, see the official documentation: https://documentation.samson-connect.net/users/latest/nsl/molecule/.

SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON at https://www.samson-connect.net.