Quick Start Guide

Use this Quick Start Guide for a compact introduction to SAMSON. It points you to the main interface areas, the first actions most users need, and the deeper User Guide pages to read next.

SAMSON's graphical user interface: (1) Menu, (2) Viewport, (3) Document view, (4) History, (5) Inspector, (6) Status bar, (7) Assets, (8) Animator.

Prefer a more compact printable version? Download the Quick Start Guide PDF.

Why did you start SAMSON?

SAMSON was created to make it easier for people in nanoscience and nanotechnology to model, simulate, visualize, and share work at the atomic scale.

Here, "nanoscience and nanotechnology" is used broadly: it includes any science or technology performed at the atomic scale.

What is SAMSON?

SAMSON is an integrated platform for molecular design. Its open architecture makes it useful in drug design, life science, materials science, physics, nanoscience, electronics, chemistry, education, and combinations of these fields.

SAMSON stands for Software for Adaptive Modeling and Simulation of Nanosystems. For installation and first-launch guidance, start with Getting Started.

What are SAMSON Extensions?

SAMSON Extensions add capabilities to SAMSON. They may provide apps, editors, models, importers, exporters, and other tools for specific tasks.

You can customize SAMSON by adding SAMSON Extensions from SAMSON Connect. Free extensions can be added in one click, and paid extensions can be subscribed to or cancelled from SAMSON Connect.

You can also develop your own SAMSON Extensions and distribute them on SAMSON Connect, either for free or commercially.

How do I load and save molecules and files?

Use Home > File to open, import, save, and export files. Opening and saving rely on importers and exporters, which may come from installed SAMSON Extensions.

Default importers and exporters support formats such as PDB, CIF, MMTF, GRO, MOL2, SDF, SAM, and SAMX. See Supported formats for the current format list, and Loading molecules for first-file workflows.

How do I change the view?

Use the mouse and keyboard to navigate the viewport:

• Hold the right mouse button to rotate the view.
• Hold the mouse wheel, or hold the right mouse button with Ctrl / Cmd, to translate the view.
• Use the mouse wheel to zoom in and out.
• Use the keyboard arrows, with optional Ctrl / Cmd or Alt, for keyboard navigation.
• Press Shift+Space to center the view on the selection.

Activate the compass in the viewport when you need a quick way to orient the view. See Moving around for viewport controls, cameras, and clipping.

How do I use editors?

Editors react to mouse and keyboard events in the viewport. Use them to select, move, build, measure, and modify nodes. Choose the active editor from the left-side menu in the viewport; Moving around explains how default editors work.

Default editors include:

• Rectangle selection (R): select nodes with the left mouse button, drag outside selected nodes to select with a rectangle, use Ctrl / Cmd to add nodes, use Alt to remove nodes, and use the right mouse button to open the context menu. See Selecting using Editors for more detail.
• Move editors (D, M, K): displace, translate, and rotate selected nodes in global or local coordinates. See Moving objects for more detail.
• Add editor (A): add atoms and fragments, and assemble assets to build molecular systems. See Building molecules.
• Measure editor (Ctrl+M / Cmd+M): display distances and angles between atoms, then press Enter to add a label. See Measuring.

You can add more editors from SAMSON Connect - Marketplace.

How do I select nodes?

Viewport: use a selection editor to select nodes with the mouse. Use the selection filter in the top-right corner of the viewport to control which node types can be highlighted and selected.

Document view: click nodes in the Document view to select them and highlight them in the viewport. Use Shift and Ctrl / Cmd for multi-selection. Filter nodes by entering text or a Node Specification Language expression, then press Enter to select matching nodes.

The bottom of the Document view shows a selection summary. Click it to open contextual actions for the current selection.

Find command: use Select > Find (Ctrl+F / Cmd+F) to select nodes with the Node Specification Language.

How do I inspect nodes?

Use the Inspector (Interface > Inspector, Ctrl+2 / Cmd+2) to view and edit properties of selected nodes. Use its filter to show only matching attributes.

How do I customize visualizations?

Use visual models to control how molecular systems are displayed. Add one with Visualization > Visual model (Ctrl+Shift+V / Cmd+Shift+V) or from the context toolbar. Visual models apply to the current selection, or to the whole document when nothing is selected.

Use Visualizing for common visualization tasks, Colorizing for color schemes and palettes, and Rendering effects for advanced rendering options. You can also use the checkbox next to each node in the Document view to hide or show it in the viewport.

Use default Visual presets (Visualization > Visual Presets) or create your own visual presets to reuse visualization settings.

How do I perform interactive simulations?

Select the nodes you want to simulate, or select nothing to simulate the whole document. Add a simulator with the Add > Add simulator context menu or Edit > Add simulator (Ctrl+Shift+M / Cmd+Shift+M), then choose an interaction model and state updater.

Use the Edit menu to start and stop interactive simulation. During simulation, selection and move editors can still be used to interact with atoms.

Use Edit > Minimize to interactively minimize the selected nodes. See Modeling and Simulation and Minimizing for detailed workflows.

How do I use apps?

Apps are tools with graphical interfaces. Some apps are installed by default, and additional apps can be added from SAMSON Connect - Marketplace.

Open apps from Home > Apps or by searching with Find everything.

How are SAMSON documents organized?

SAMSON documents are hierarchies of SAMSON nodes. The hierarchy is visible in the Document view. Documents may contain folders, files, cameras, models, simulators, labels, notes, conformations, paths, and node groups.

Several node types are used to organize, view, present, and annotate a document:

• Camera: stores a 3D view. Documents may contain multiple cameras, and the viewport reflects the active one.
• Folder: organizes nodes and may contain folders, files, notes, cameras, models, simulators, labels, conformations, paths, render presets, and node groups.
• File: embeds files. You can embed files or folders when importing data in SAMSON.
• Script: stores a Python script that can automate tasks through the SAMSON Python API. Add one with Edit > Script.
• Note: annotates documents, folders, and results. Add one with Edit > Note, then edit it in the Inspector.
• Node group: saves a selection. Use Select > Group (G) to create a group from the current selection. Double-click the group in the Document view to restore the selection.
• Label: annotates nodes. Labels may be created by editors, apps, and other tools. Customize label rendering in Interface > Preferences.
• Presentation: stores a presentation with animations. Use Visualization > Presentation to create one, then use the Animator (Ctrl+7 / Cmd+7) to add and modify animations.

Five node types represent the five categories of models:

• Structural model: describes molecular geometry and topology. Structural models contain structural nodes and are usually created by importing files, editors, or apps.
• Visual model: provides custom visual representations of other nodes. Add one with the context toolbar or Visualization > Visual model.
• Dynamical model: describes degrees of freedom in a simulated system. Dynamical models are added automatically when needed by simulators.
• Interaction model: describes energies and forces inside a dynamical model. The default interaction model is the Universal force field.
• Property model: stores properties outside the other model categories. Property models may come from SAMSON Extensions.

Several node types are used to break down structural models into sub-structural components:

• Structural group: organizes structural nodes. It may contain atoms, backbones, bonds, chains, molecules, pseudo-atoms, residues, segments, side chains, and structural groups.
• Molecule: may contain structural groups, chains, segments, residues, atoms, pseudo-atoms, and bonds.
• Chain: may contain structural groups, segments, residues, atoms, and bonds.
• Segment: may contain atoms, bonds, structural groups, and residues.
• Residue: represents an amino acid or nucleic acid. A residue may contain a backbone and a side chain.
• Backbone: represents an amino acid backbone or nucleic acid backbone. A backbone may contain atoms and bonds.
• Side chain: represents an amino acid side chain or nucleic acid side chain. A side chain may contain atoms and bonds.
• Atom: represents an atom, including coarse-grained atoms. In the Document view, atom icons are colored by atom type.
• Bond: represents a bond between two atoms. Select a bond and use the Inspector to see the atoms it connects.

Double-click an atom or bond to select it and zoom to it.

Two node types are used for simulation:

• Simulator: runs interactive or offline simulations. Add one with Edit > Add simulator (Ctrl+Shift+M / Cmd+Shift+M) or the Add > Add simulator context menu.
• State updater: updates simulations. State updaters are added through simulators; default examples include Interactive modeling, Steepest descent, and Partitioned Euler.

Finally, two node types are used to save conformations and paths:

• Conformation: stores positions of atoms and pseudo-atoms. Use Edit > Conformation (S) to save a conformation, then double-click it in the Document view to restore it.
• Path: stores positions, velocities, forces, energy, and time along a path. Paths may be created by editors, apps, importers, and simulations. Double-click a path in the Document view to start or stop animating it.

How do I find commands? How do I mark them as favorites?

Use Find everything (Shift+E) at the top of the menu to search for commands, apps, editors, and documentation. From search results, and often from menus, click the star icon to mark commands, editors, and apps as favorites.

Favorites appear near the top of the ribbon menu and in the editor menu so you can access them faster. See First look: the interface and the interface reference.

How do I learn more?

Start interactive tutorials in SAMSON from Help > Tutorials when you want guided walkthroughs inside the application.

Use SAMSON AI (Ctrl+0 / Cmd+0) to ask questions, find commands, select nodes, and generate scripts.

For deeper routes, return to the SAMSON User Guide, browse the Documentation map, or download SAMSON from SAMSON Connect.