# SAMSON Documentation Center > The Documentation Center contains information about using SAMSON and SAMSON extensions. It integrates the SAMSON User Guide that helps users install SAMSON, learn the interface, work with molecular structures, visualize and present results, simulate and analyze systems, collaborate, automate workflows, and find reference material. It also contains intro guides about developing with SAMSON in Python or C++. # Home # SAMSON Documentation Center Use the SAMSON Documentation Center to find the right guide, tutorial, update, or support resource for your next task in SAMSON. ## Start here If you are new to SAMSON, begin with installation and a short orientation before opening longer guides. - [**Install SAMSON**](https://documentation.samson-connect.net/users/latest/getting-started/#installing-samson) ______________________________________________________________________ Install SAMSON, sign in, and get ready to use the platform. - [**SAMSON User Guide**](https://documentation.samson-connect.net/users/latest/index.md) ______________________________________________________________________ Learn core SAMSON concepts, interface tools, modeling workflows, visualization, selection, and documents. ## Learn by task Use tutorials when you want to follow a practical scientific workflow with SAMSON Extensions. - [**Extensions Tutorials**](https://documentation.samson-connect.net/tutorials/index.md) ______________________________________________________________________ Find task-based tutorials for docking, molecular dynamics, materials science, DNA origami, and other extension workflows. - [**Documentation map**](https://documentation.samson-connect.net/documentation-map/index.md) ______________________________________________________________________ Choose a documentation route by goal when you are not sure which resource to open. ## Stay current Use the updates archive for SAMSON news and the release notes for version-specific changes. - [**Updates**](https://documentation.samson-connect.net/updates/index.md) ______________________________________________________________________ Read monthly SAMSON updates about platform news, tutorials, events, ecosystem changes, and documentation. - [**Release notes**](https://documentation.samson-connect.net/samson-release-notes/index.md) ______________________________________________________________________ Check product and extension changes by SAMSON version. ## Automate and extend SAMSON Use these resources when you want to automate workflows, write scripts, or build SAMSON Extensions. - [**Python Scripting**](https://documentation.samson-connect.net/python/index.md) ______________________________________________________________________ Automate SAMSON with Python and use the exposed SAMSON Python API. - [**Developing SAMSON Extensions in C++**](https://documentation.samson-connect.net/developing-samson-extensions/index.md) ______________________________________________________________________ Start from the overview for C++ extension development. ## Community and support Use external community resources when you want videos, product examples, answers, or SAMSON Connect services. - [**Forum**](https://forum.samson-connect.net/) ______________________________________________________________________ Ask questions, search answers, and share feedback with the SAMSON community. - [**Blog**](https://blog.samson-connect.net/) ______________________________________________________________________ Read product news, focused tips, and workflow examples. - [**YouTube**](https://www.youtube.com/@samsonconnect) ______________________________________________________________________ Watch tutorials, webinars, and feature demonstrations. - [**SAMSON Connect**](https://www.samson-connect.net/) ______________________________________________________________________ Manage your account, download SAMSON, find extensions, and access shared documents. ## Site files - [Privacy Policy](https://www.samson-connect.net/privacyPolicy) - [Terms of Use](https://www.samson-connect.net/termsOfUse) - [llms-full.txt](https://documentation.samson-connect.net/llms-full.txt) - an LLM-oriented text representation of this Documentation Center, including the User Guide, but excluding the separate Python Scripting Guide and Developers Guide. - [llms.txt](https://documentation.samson-connect.net/llms.txt) - an LLM-oriented map with links to Markdown files corresponding to each page of this Documentation Center, including the User Guide, but excluding the separate Python Scripting Guide and Developers Guide. # Documentation Map # Documentation map Use this page to choose the right SAMSON documentation resource for your goal. ## I am new to SAMSON - [Install SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/#installing-samson) when you need to download, install, and start the application. - [Quick Start Guide](https://documentation.samson-connect.net/users/latest/quick-start-guide/index.md) when you want a compact web introduction or the downloadable PDF. - [SAMSON User Guide](https://documentation.samson-connect.net/users/latest/index.md) when you want the main guide to SAMSON concepts, interface tools, and core workflows. ## I want to learn core SAMSON usage - [SAMSON User Guide](https://documentation.samson-connect.net/users/latest/index.md) for selection, editing, visualization, documents, importing, exporting, and general workflows. - [YouTube](https://www.youtube.com/@samsonconnect) for video tutorials, webinars, and feature demonstrations. ## I want a scientific workflow tutorial - [Extensions Tutorials](https://documentation.samson-connect.net/tutorials/index.md) when you want task-based workflows with SAMSON Extensions. - [GROMACS Wizard tutorials](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md) when you want a guided molecular dynamics path. - [SAMSON Connect Marketplace](https://www.samson-connect.net/extensions) when you want to find extensions for a specific task. ## I want to automate SAMSON with Python - [Automating with Python or developing SAMSON Extensions in Python](https://documentation.samson-connect.net/python/index.md) when you want the Documentation Center route for Python-based automation or extension development. - [Python Scripting Guide](https://documentation.samson-connect.net/scripting/latest/index.html) for the SAMSON Python API and scripting workflows. ## I want to develop SAMSON Extensions - [Developing SAMSON Extensions in C++](https://documentation.samson-connect.net/developing-samson-extensions/index.md) for the Documentation Center overview of extension development with the SAMSON C++ SDK. - [Developers Guide](https://documentation.samson-connect.net/developers/latest/) for the C++ SDK guide. ## I want updates and release notes - [Updates and release notes](https://documentation.samson-connect.net/updates/index.md) when you want the archive entry point. - [Monthly updates](https://documentation.samson-connect.net/updates/#monthly-updates) for newsletter-style SAMSON news and ecosystem updates. - [Release notes](https://documentation.samson-connect.net/updates/#release-notes) for version-specific SAMSON and extension changes. ## I need help or community support - [Forum](https://forum.samson-connect.net/) to ask questions, search answers, and share feedback. - [Blog](https://blog.samson-connect.net/) to read tips, product news, and examples. - [SAMSON Connect](https://www.samson-connect.net/) to manage your account, download SAMSON, find extensions, and access shared documents. ## Next step If you are still unsure where to go, start with the [SAMSON Documentation Center home page](https://documentation.samson-connect.net/index.md) and choose the route that best matches your current task. # User Guide # Welcome to the SAMSON User Guide Use the [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) User Guide to find the right page for installing [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), learning the interface, loading structures, visualizing results, modeling systems, analyzing trajectories, scripting workflows, sharing work, or looking up reference details. Start here if you are new to [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), or use this page as the front door for visualization, modeling, analysis, scripting, collaboration, and help resources. ## Start here - **New to SAMSON**: start with [Getting Started](https://documentation.samson-connect.net/users/latest/getting-started/index.md), use the [Quick Start Guide](https://documentation.samson-connect.net/users/latest/quick-start-guide/index.md) for a compact tour, then continue to [First look: the interface](https://documentation.samson-connect.net/users/latest/first-look/index.md) and [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md). - **Already installed**: jump to [Start here](https://documentation.samson-connect.net/users/latest/start/index.md) for the guided onboarding sequence or go directly to the hub that matches your task. - **Need a printable overview**: open the [Quick Start Guide](https://documentation.samson-connect.net/users/latest/quick-start-guide/index.md). ## Common goals - **I want to open or inspect a structure**: start with [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md), then use [Work with structures](https://documentation.samson-connect.net/users/latest/work-with-structures/index.md). - **I want to build or modify a model**: use [Build and edit](https://documentation.samson-connect.net/users/latest/build-and-edit/index.md). - **I want a clearer image, figure, or movie**: use [Visualize and present](https://documentation.samson-connect.net/users/latest/visualize-and-present/index.md). - **I want to simulate, analyze a path, or run cloud jobs**: use [Simulate and analyze](https://documentation.samson-connect.net/users/latest/simulate-and-analyze/index.md). - **I want to automate work or add extensions**: use [Automate and extend](https://documentation.samson-connect.net/users/latest/automate-and-extend/index.md). - **I want a quick answer or reference detail**: use [Reference and help](https://documentation.samson-connect.net/users/latest/reference-and-help/index.md). ## Main routes ### Start here - [Start here](https://documentation.samson-connect.net/users/latest/start/index.md): onboarding path for installation, first use, navigation, and early help choices. - [Getting Started](https://documentation.samson-connect.net/users/latest/getting-started/index.md): requirements, installation, first launch, and early extension setup. - [Quick Start Guide](https://documentation.samson-connect.net/users/latest/quick-start-guide/index.md): compact web overview of the interface, navigation, selection, documents, simulations, apps, and help routes. - [First look: the interface](https://documentation.samson-connect.net/users/latest/first-look/index.md): quick orientation to the menu, viewport, document view, and core panels. - [Moving around](https://documentation.samson-connect.net/users/latest/moving-around/index.md): navigate the viewport, choose a default editor, control cameras, and use clipping. - [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md): open files, fetch structures, understand documents, and work with shared documents. - [Interactive tutorials](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md): start with guided tutorials built directly into SAMSON. - [SAMSON AI](https://documentation.samson-connect.net/users/latest/samson-ai/index.md): ask questions, run commands, select nodes, and generate scripts. ### Work with structures - [Work with structures](https://documentation.samson-connect.net/users/latest/work-with-structures/index.md): choose the right path for selection, inspection, measurement, and undo/redo. - [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md): choose atoms, residues, molecules, and other nodes for later tasks. - [Inspecting](https://documentation.samson-connect.net/users/latest/inspecting/index.md): check and edit properties of selected nodes. - [Measuring](https://documentation.samson-connect.net/users/latest/measuring/index.md): measure distances, angles, dihedrals, and saved measurement labels. ### Build and edit - [Build and edit](https://documentation.samson-connect.net/users/latest/build-and-edit/index.md): move structures, build molecules, create patterns, and relax geometry. - [Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md): construct systems from atoms, fragments, and assets. - [Minimizing](https://documentation.samson-connect.net/users/latest/minimizing/index.md): relax geometry during or after edits. ### Visualize and present - [Visualize and present](https://documentation.samson-connect.net/users/latest/visualize-and-present/index.md): choose the right path for visual models, color, rendering, labels, and movies. - [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md): improve the everyday viewport and apply visual models or presets. - [Presenting and animating](https://documentation.samson-connect.net/users/latest/presenting/index.md): create presentations, animations, and movie exports. ### Simulate and analyze - [Simulate and analyze](https://documentation.samson-connect.net/users/latest/simulate-and-analyze/index.md): route into interactive simulation, trajectory analysis, and cloud workflows. - [Modeling and Simulation](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md): add simulators, run interactive modeling, and create conformations or paths. - [Path Analyzer](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md): inspect trajectories and observables with interactive cards, plots, and dashboards. - [Interaction Designer](https://documentation.samson-connect.net/users/latest/interaction-designer/index.md): inspect protein-ligand interactions. ### Share and collaborate - [Share and collaborate](https://documentation.samson-connect.net/users/latest/share-and-collaborate/index.md): use the collaboration path for accounts, groups, shared documents, and shared jobs. - [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md): downloads, extensions, shared resources, and account-level workflows. - [Share documents](https://documentation.samson-connect.net/users/latest/share-documents/index.md): share documents or download shared documents. - [Collaboration](https://documentation.samson-connect.net/users/latest/collaboration/index.md): profiles, groups, permissions, shared documents, and job sharing. ### Automate and extend - [Automate and extend](https://documentation.samson-connect.net/users/latest/automate-and-extend/index.md): choose between scripting workflows and extension management. - [Scripting](https://documentation.samson-connect.net/users/latest/scripting/index.md): use the integrated Python environment, templates, and embedded scripts. - [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md): install extensions or explore the SDK path. ### Reference and help - [Reference and help](https://documentation.samson-connect.net/users/latest/reference-and-help/index.md): choose the fastest route to answers, fixes, and deeper references. - [References](https://documentation.samson-connect.net/users/latest/references/index.md): browse the reference families for SAMSON features. - [FAQ](https://documentation.samson-connect.net/users/latest/faq/index.md) and [Troubleshooting](https://documentation.samson-connect.net/users/latest/troubleshooting/index.md): solve common questions and practical problems quickly. ## Related resources - [Documentation center](https://documentation.samson-connect.net/): browse the wider documentation site and adjacent guides. - [Tutorials](https://documentation.samson-connect.net/tutorials/index.md): extension and workflow tutorials beyond this guide. - [Python Scripting Guide](https://documentation.samson-connect.net/scripting/latest/): API documentation and more scripting examples. - [Developer Guide](https://documentation.samson-connect.net/developers/latest/): SDK and extension-development documentation. - [FAQ](https://documentation.samson-connect.net/users/latest/faq/index.md) and [Troubleshooting](https://documentation.samson-connect.net/users/latest/troubleshooting/index.md): find quick answers and fix paths. ## Next step - Start with [Getting Started](https://documentation.samson-connect.net/users/latest/getting-started/index.md) if you are new to [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). - Continue with [Start here](https://documentation.samson-connect.net/users/latest/start/index.md) if you want the guided onboarding sequence. - Jump straight to the hub in **Main routes** that matches your current task. # User Guide - Start here # Start here Use this topic if you are setting up SAMSON for the first time, getting oriented after installation, or returning and want a fast refresher on the basics. It brings setup, interface orientation, navigation, first structure loading, and early help options into one place. Follow the full sequence if you are new to SAMSON, or use the guided paths below to jump directly to the part you need. ## Who this topic is for - First-time SAMSON users - Users setting up SAMSON on a new workstation - Returning users who need a refresher on the interface and loading basics - Users deciding whether to use tutorials, SAMSON AI, or SAMSON Connect early ## What you will be able to do afterward - Verify the requirements and install SAMSON - Launch SAMSON and recognize the main parts of the interface - Move around the viewport and choose a default editor - Load or fetch a first structure and understand how documents work - Choose the right help path for onboarding ## Recommended reading order 1. [Getting Started](https://documentation.samson-connect.net/users/latest/getting-started/index.md) - Read this first for the broad onboarding overview and first-launch context. `Foundational.` 1. [Quick Start Guide](https://documentation.samson-connect.net/users/latest/quick-start-guide/index.md) - Use this compact tour to connect setup, interface basics, navigation, selection, documents, simulations, apps, and help routes. `Foundational / refresher.` 1. [Requirements and Platforms](https://documentation.samson-connect.net/users/latest/requirements-and-platforms/index.md) - Confirm operating-system support, graphics requirements, and Linux dependencies before installation. `Foundational if not installed yet.` 1. [Install SAMSON](https://documentation.samson-connect.net/users/latest/installation/index.md) - Use this to complete the installer flow, sign-in steps, and key entry. `Foundational if not installed yet.` 1. [First look: the interface](https://documentation.samson-connect.net/users/latest/first-look/index.md) - Learn the main parts of the interface so later instructions are easier to follow. `Foundational.` 1. [Moving around](https://documentation.samson-connect.net/users/latest/moving-around/index.md) - Learn viewport controls and the default editors used for navigation and selection. `Foundational.` 1. [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md) - Open or fetch a first structure and understand where documents, files, and shared data appear. `Foundational.` 1. [Interactive tutorials](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md) - Use the built-in guided walkthroughs after you know where the main interface parts are. `Optional.` 1. [SAMSON AI](https://documentation.samson-connect.net/users/latest/samson-ai/index.md) - Use the assistant for questions, commands, selections, and scripts once the basics are familiar. `Optional / task-specific.` 1. [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) - Go here when you need downloads, extensions, account settings, or shared documents. `Task-specific.` 1. [Webinars](https://documentation.samson-connect.net/users/latest/webinars/index.md) - Use the recordings for a refresher or feature survey rather than as your primary start point. `Optional.` ## Read this first Start with [Getting Started](https://documentation.samson-connect.net/users/latest/getting-started/index.md). If you want the shortest guided tour before opening detailed pages, continue with the [Quick Start Guide](https://documentation.samson-connect.net/users/latest/quick-start-guide/index.md). If SAMSON is not installed yet, continue with [Requirements and Platforms](https://documentation.samson-connect.net/users/latest/requirements-and-platforms/index.md) and [Install SAMSON](https://documentation.samson-connect.net/users/latest/installation/index.md). ## You can skip this for now if... - You already have SAMSON running on a supported machine, in which case you can skip [Requirements and Platforms](https://documentation.samson-connect.net/users/latest/requirements-and-platforms/index.md) and [Install SAMSON](https://documentation.samson-connect.net/users/latest/installation/index.md) - You only need local first-run basics, in which case you can skip [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) - You prefer direct documentation instead of guided walkthroughs, in which case you can skip [Interactive tutorials](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md) - You are not using assistant-led workflows yet, in which case you can skip [SAMSON AI](https://documentation.samson-connect.net/users/latest/samson-ai/index.md) - You want the fastest route to hands-on work, in which case you can skip [Webinars](https://documentation.samson-connect.net/users/latest/webinars/index.md) ## Suggested paths - **Setup a new machine**: [Requirements and Platforms](https://documentation.samson-connect.net/users/latest/requirements-and-platforms/index.md) -> [Install SAMSON](https://documentation.samson-connect.net/users/latest/installation/index.md) -> [Getting Started](https://documentation.samson-connect.net/users/latest/getting-started/index.md) -> [Quick Start Guide](https://documentation.samson-connect.net/users/latest/quick-start-guide/index.md) -> [First look: the interface](https://documentation.samson-connect.net/users/latest/first-look/index.md) - **Already installed, get productive fast**: [Quick Start Guide](https://documentation.samson-connect.net/users/latest/quick-start-guide/index.md) -> [First look: the interface](https://documentation.samson-connect.net/users/latest/first-look/index.md) -> [Moving around](https://documentation.samson-connect.net/users/latest/moving-around/index.md) -> [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md) - **Learn with built-in help**: [Quick Start Guide](https://documentation.samson-connect.net/users/latest/quick-start-guide/index.md) -> [Interactive tutorials](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md) -> [SAMSON AI](https://documentation.samson-connect.net/users/latest/samson-ai/index.md) ## Where to go next - [Work with structures](https://documentation.samson-connect.net/users/latest/work-with-structures/index.md) - After loading a document, continue with selection, inspection, measurement, and undo/redo. - [Build and edit](https://documentation.samson-connect.net/users/latest/build-and-edit/index.md) - Go here when you want to modify or construct systems. - [Visualize and present](https://documentation.samson-connect.net/users/latest/visualize-and-present/index.md) - Continue here when your next goal is clearer visualization, labeling, rendering, or presentation output. ## Notes [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) appears here because downloads, keys, extensions, and shared documents are part of onboarding, while deeper collaboration workflows live later in [Share and collaborate](https://documentation.samson-connect.net/users/latest/share-and-collaborate/index.md). # Getting Started This page helps you install [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), confirm platform requirements, launch it for the first time, and choose the best next steps for your workflow. Use it as the main onboarding page before moving on to [First look](https://documentation.samson-connect.net/users/latest/first-look/index.md), [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md), or [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). ## Use this page when - You are installing [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) or checking whether your computer can run it. - You have just launched [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) and need to know what to do next. - You need the current public version, basic launch commands, or the first extension-management path. ## You can skip this if - [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) is already installed and you only need interface orientation: go to [First look: the interface](https://documentation.samson-connect.net/users/latest/first-look/index.md). - You only need to open a structure: go to [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md). - You already know the basics and need account, Marketplace, or key management: go to [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). ## What SAMSON is **SAMSON** is a software platform for computational nanoscience. Its generic, open architecture makes it suitable for life science, material science, physics, electronics, chemistry, and education. SAMSON stands for *Software for Adaptive Modeling and Simulation Of Nanosystems*. SAMSON is developed by [OneAngstrom](https://oneangstrom.com). ## Quick Start Guide For a compact introduction to the interface, navigation, documents, visualizations, simulations, and help routes, open the [Quick Start Guide](https://documentation.samson-connect.net/users/latest/quick-start-guide/index.md). A downloadable PDF version is available from that page. ## Start with these guides - [Requirements and platforms](https://documentation.samson-connect.net/users/latest/requirements-and-platforms/index.md): check operating-system support, hardware needs, and Linux dependencies. - [Install SAMSON](https://documentation.samson-connect.net/users/latest/installation/index.md): follow the installer workflow from download to first launch. - [Webinars](https://documentation.samson-connect.net/users/latest/webinars/index.md): watch recent onboarding and release overviews without interrupting the setup flow. ## Webinars Recent onboarding and release-webinar recordings now live on [Webinars](https://documentation.samson-connect.net/users/latest/webinars/index.md) so that this page can stay focused on installation and first launch. ## Current version The current version of [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) is 2026 R1. Versioning Use [Versioning](https://documentation.samson-connect.net/users/latest/versioning/index.md) for details about version numbers. ## Installing SAMSON - Start with [Requirements and platforms](https://documentation.samson-connect.net/users/latest/requirements-and-platforms/index.md) to confirm operating-system support, hardware expectations, and Linux dependencies. - Continue with [Install SAMSON](https://documentation.samson-connect.net/users/latest/installation/index.md) for the installer workflow, sign-in step, and key entry. - Use [Troubleshooting](https://documentation.samson-connect.net/users/latest/troubleshooting/index.md) if installation or graphics setup does not behave as expected. If you only need the step-by-step installer instructions, go directly to [Install SAMSON](https://documentation.samson-connect.net/users/latest/installation/index.md). ## Starting SAMSON Here is how you start [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) depending on your operating system. ### Windows On Windows, start [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) from the *Start* menu. Typing SAMSON in the search box might just lead you there. Else, SAMSON executable can be found in the following folder: ``` C:/Users/%USERNAME%/OneAngstrom/SAMSON-Application/11.0.0/Binaries/SAMSON-Core.exe ``` ### Mac On Mac, start [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) from Launchpad or from the `Applications` folder. The most recent [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) version will be launched. [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) is installed in the following folder: ``` $HOME/Applications/SAMSON.app/ ``` ### Linux You can launch [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) like other apps via the Apps dashboard. You can also directly launch the `SAMSON-Core.sh` script from the SAMSON installation folder path (it should be `~/OneAngstrom/SAMSON-Application/11.0.0/Binaries`): ``` ./SAMSON-Core.sh ``` You may create an alias in your `~/.bashrc` or `~/.zprofile`: ``` alias samson='$HOME/OneAngstrom/SAMSON-Application/11.0.0/Binaries/SAMSON-Core.sh' ``` Now, open a new terminal and execute `samson`. If you have issues on Linux with AMD/ATI graphics cards, use the [Troubleshooting](https://documentation.samson-connect.net/users/latest/troubleshooting/#linux-amd) section. ## What are SAMSON Extensions? [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) has an open architecture that lets you extend and adapt it to your needs by downloading [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) from [SAMSON Connect](https://www.samson-connect.net/). [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) come in many flavors, including apps, editors, controllers, models, and parsers. They help users build models, perform calculations, run simulations, visualize results, and adapt [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) to a specific domain or workflow. ## Extending SAMSON The first time you start [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), it downloads a set of default [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) from [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). To customize your installation later, sign in to your account, go to the [Marketplace](https://www.samson-connect.net/extensions), and choose the [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) you need. Read [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) when you are ready to manage extensions in more detail or explore the SDK path. ## Related pages - [Requirements and platforms](https://documentation.samson-connect.net/users/latest/requirements-and-platforms/index.md) - [Install SAMSON](https://documentation.samson-connect.net/users/latest/installation/index.md) - [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) - [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) ## Next step - [First look: the interface](https://documentation.samson-connect.net/users/latest/first-look/index.md) for a fast orientation to the main parts of [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). - [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md) to open a first structure and understand documents. - [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) if you need downloads, keys, extensions, or shared resources. - [Start here](https://documentation.samson-connect.net/users/latest/start/index.md) if you want the full onboarding path in one place. # Quick Start Guide Use this Quick Start Guide for a compact introduction to [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). 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](https://documentation.samson-connect.net/users/latest/first-look/index.md): (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](https://documentation.samson-connect.net/assets/SAMSON-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](https://documentation.samson-connect.net/users/latest/getting-started/index.md) 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](https://documentation.samson-connect.net/users/latest/getting-started/index.md). ## What are SAMSON Extensions? [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) add capabilities to [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). They may provide [apps](https://documentation.samson-connect.net/users/latest/apps/index.md), [editors](https://documentation.samson-connect.net/users/latest/editors/index.md), [models](https://documentation.samson-connect.net/users/latest/models/index.md), [importers](https://documentation.samson-connect.net/users/latest/importers/index.md), [exporters](https://documentation.samson-connect.net/users/latest/exporters/index.md), and other tools for specific tasks. You can customize [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) by [adding SAMSON Extensions from SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/#marketplace). Free extensions can be added in one click, and paid extensions can be subscribed to or cancelled from [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). You can also [develop your own SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/#develop-a-samson-extension) and [distribute them on SAMSON Connect](https://documentation.samson-connect.net/users/latest/extending-samson/#distribute-your-samson-extension), 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](https://documentation.samson-connect.net/users/latest/importers/index.md) and [exporters](https://documentation.samson-connect.net/users/latest/exporters/index.md), which may come from installed [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md). Default importers and exporters support formats such as PDB, CIF, MMTF, GRO, MOL2, SDF, SAM, and SAMX. See [Supported formats](https://documentation.samson-connect.net/users/latest/supported-formats/index.md) for the current format list, and [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md) for first-file workflows. ## How do I change the view? Use the mouse and keyboard to navigate the [viewport](https://documentation.samson-connect.net/users/latest/first-look/#main-interface-areas): - 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](https://documentation.samson-connect.net/users/latest/moving-around/index.md) for viewport controls, cameras, and clipping. ## How do I use editors? [Editors](https://documentation.samson-connect.net/users/latest/editors/index.md) 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](https://documentation.samson-connect.net/users/latest/moving-around/#default-editors) 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](https://documentation.samson-connect.net/users/latest/selecting/#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](https://documentation.samson-connect.net/users/latest/moving-objects/index.md) for more detail. - **Add editor** (`A`): add atoms and fragments, and assemble assets to build molecular systems. See [Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md). - **Measure editor** (`Ctrl`+`M` / `Cmd`+`M`): display distances and angles between atoms, then press `Enter` to add a label. See [Measuring](https://documentation.samson-connect.net/users/latest/measuring/index.md). You can add more editors from [SAMSON Connect - Marketplace](https://documentation.samson-connect.net/users/latest/samson-connect/#marketplace). ## How do I select nodes? **Viewport**: use a selection editor to [select nodes](https://documentation.samson-connect.net/users/latest/selecting/index.md) 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](https://documentation.samson-connect.net/users/latest/interface/#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](https://documentation.samson-connect.net/users/latest/nsl/index.md) 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**](https://documentation.samson-connect.net/users/latest/nsl/#find-command): use **Select > Find** (`Ctrl`+`F` / `Cmd`+`F`) to select nodes with the [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md). ## How do I inspect nodes? Use the [Inspector](https://documentation.samson-connect.net/users/latest/inspecting/index.md) (**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](https://documentation.samson-connect.net/users/latest/models/#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](https://documentation.samson-connect.net/users/latest/visualizing/index.md) for common visualization tasks, [Colorizing](https://documentation.samson-connect.net/users/latest/colorizing/index.md) for color schemes and palettes, and [Rendering effects](https://documentation.samson-connect.net/users/latest/rendering-effects/index.md) 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](https://documentation.samson-connect.net/users/latest/visual-presets/index.md) (**Visualization > Visual Presets**) or [create your own visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/#create) 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](https://documentation.samson-connect.net/users/latest/models/#interaction-models) and [state updater](https://documentation.samson-connect.net/users/latest/models/#state-updaters). 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](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md) and [Minimizing](https://documentation.samson-connect.net/users/latest/minimizing/index.md) for detailed workflows. ## How do I use apps? [Apps](https://documentation.samson-connect.net/users/latest/apps/index.md) are tools with graphical interfaces. Some apps are installed by default, and additional apps can be added from [SAMSON Connect - Marketplace](https://documentation.samson-connect.net/users/latest/samson-connect/#marketplace). Open apps from **Home > Apps** or by searching with **Find everything**. ## How are SAMSON documents organized? [SAMSON documents](https://documentation.samson-connect.net/users/latest/documents/index.md) are hierarchies of [SAMSON nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md). 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](https://documentation.samson-connect.net/users/latest/camera/index.md): stores a 3D view. Documents may contain multiple cameras, and the viewport reflects the active one. - [Folder](https://documentation.samson-connect.net/users/latest/documents/#folders): organizes nodes and may contain folders, files, notes, cameras, models, simulators, labels, conformations, paths, render presets, and node groups. - [File](https://documentation.samson-connect.net/users/latest/documents/#files): embeds files. You can [embed files or folders](https://documentation.samson-connect.net/users/latest/loading-molecules/#embedding) when importing data in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). - **Script**: stores a [Python script](https://documentation.samson-connect.net/users/latest/scripting/index.md) 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](https://documentation.samson-connect.net/users/latest/selecting/#saving-selections-as-groups). Double-click the group in the Document view to restore the selection. - **Label**: [annotates nodes](https://documentation.samson-connect.net/users/latest/labeling/index.md). Labels may be created by editors, apps, and other tools. Customize label rendering in **Interface > Preferences**. - [Presentation](https://documentation.samson-connect.net/users/latest/presenting/#what-is-a-presentation): stores a [presentation with animations](https://documentation.samson-connect.net/users/latest/presenting/index.md). Use **Visualization > Presentation** to create one, then use the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator) (`Ctrl`+`7` / `Cmd`+`7`) to add and modify [animations](https://documentation.samson-connect.net/users/latest/animations/index.md). Five node types represent the five categories of [models](https://documentation.samson-connect.net/users/latest/models/index.md): - [Structural model](https://documentation.samson-connect.net/users/latest/models/#structural-models): describes molecular geometry and topology. Structural models contain structural nodes and are usually created by importing files, editors, or apps. - [Visual model](https://documentation.samson-connect.net/users/latest/models/#visual-models): provides custom visual representations of other nodes. Add one with the context toolbar or **Visualization > Visual model**. - [Dynamical model](https://documentation.samson-connect.net/users/latest/models/#dynamical-models): describes degrees of freedom in a simulated system. Dynamical models are added automatically when needed by simulators. - [Interaction model](https://documentation.samson-connect.net/users/latest/models/#interaction-models): describes energies and forces inside a dynamical model. The default interaction model is the Universal force field. - [Property model](https://documentation.samson-connect.net/users/latest/models/#property-models): stores properties outside the other model categories. Property models may come from [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md). 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](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/#simulators): 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](https://documentation.samson-connect.net/users/latest/models/#state-updaters): 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](https://documentation.samson-connect.net/users/latest/first-look/#customization-of-the-samson-interface) and the [interface reference](https://documentation.samson-connect.net/users/latest/interface/#find-everything). ## How do I learn more? Start [interactive tutorials in SAMSON](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md) from **Help > Tutorials** when you want guided walkthroughs inside the application. Use [SAMSON AI](https://documentation.samson-connect.net/users/latest/samson-ai/index.md) (`Ctrl`+`0` / `Cmd`+`0`) to ask questions, find commands, select nodes, and generate scripts. For deeper routes, return to the [SAMSON User Guide](https://documentation.samson-connect.net/users/latest/index.md), browse the [Documentation map](https://documentation.samson-connect.net/documentation-map/index.md), or download [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) from [SAMSON Connect](https://www.samson-connect.net/). # Requirements and Platforms This page summarizes the supported operating systems, hardware requirements, graphics constraints, and Linux package dependencies needed to run [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). Read it before installing [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) or when checking whether a workstation is ready for deployment. ## What you will learn This page tells you which operating systems are supported, what graphics capabilities are required, and which Linux packages are commonly needed before the installer can run correctly. ## Supported platforms This version of [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) supports: - Windows 11 and Windows 10 - Linux: Ubuntu 22.04 and newer, Fedora 42 and newer, CentOS, and other similar Linux OS. - macOS: Tahoe (26), Sequoia (15), Sonoma (14), Ventura (13), and Monterey (12) on Intel and Apple Silicon Older platforms may work, but they are not part of the currently tested support matrix. ## Requirements - a 64-bit operating system - a graphics card with **OpenGL 4.1** support - latest drivers for NVIDIA or AMD GPUs when applicable Does SAMSON require admin rights? **No admin rights are necessary.** [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) installs in the user home and checks that it is not running in admin mode. Warning If you run [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) in a **virtual machine**, enable hardware GPU acceleration. Without it, OpenGL features required by [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) may be unavailable. ### Linux dependencies To run SAMSON, you might need first to install some libraries. On Ubuntu-like systems, you may need: ``` sudo apt install libxcb-cursor0 libatomic1 ``` On CentOS-like systems, you may need: ``` sudo dnf install xcb-util* ``` If OpenGL libraries are missing or incorrectly configured, continue with [Installing OpenGL drivers on Linux](https://documentation.samson-connect.net/users/latest/troubleshooting/#linux-install-opengl). ## Recommended next checks - Confirm that you can access your account and installer on [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). - Review [Install SAMSON](https://documentation.samson-connect.net/users/latest/installation/index.md) for the full setup flow. - If you manage shared machines or teaching labs, test the graphics path before broad deployment. ## Related pages - [Install SAMSON](https://documentation.samson-connect.net/users/latest/installation/index.md) - [Getting Started](https://documentation.samson-connect.net/users/latest/getting-started/index.md) - [Troubleshooting](https://documentation.samson-connect.net/users/latest/troubleshooting/index.md) # Install SAMSON This guide walks you through downloading the installer, signing in with your SAMSON account, entering your SAMSON key, and completing the installation on Windows, Linux, and macOS. Use it when you want the installation procedure without the extra onboarding material from the main [Getting Started](https://documentation.samson-connect.net/users/latest/getting-started/index.md) page. ## What you will learn This page covers the installation flow from download to first launch. It also points to the best follow-up pages if you need platform requirements, troubleshooting, or extension setup. ## Before you install - Confirm the supported operating system and graphics requirements in [Requirements and platforms](https://documentation.samson-connect.net/users/latest/requirements-and-platforms/index.md). - Make sure you can sign in to [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) and access your SAMSON key. - If you need an older release, review [FAQ: How to install an older version of SAMSON](https://documentation.samson-connect.net/users/latest/faq/#how-to-install-an-older-version-of-samson). ## Download the installer 1. Go to [Download SAMSON](https://www.samson-connect.net/download). 1. Sign in to [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) or create an account. 1. Download the installer for your operating system. During installation you will be asked for: - the email address used for your [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) account - your **SAMSON key** Where can I find my SAMSON key? You can find your SAMSON key on [SAMSON Connect](https://www.samson-connect.net/) in **Account > Settings** and on the [download page](https://www.samson-connect.net/download). See [Where can I get my SAMSON Key?](https://documentation.samson-connect.net/users/latest/faq/#keys). Tip If you want to install an older version of SAMSON, please check [How to install an older version of SAMSON](https://documentation.samson-connect.net/users/latest/faq/#how-to-install-an-older-version-of-samson). Note [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) are updated only for the latest version of SAMSON and they are updated automatically when you launch SAMSON. So, we encourage you to update SAMSON when its new version is available. SAMSON regularly checks for updates. The update can also be invoked manually directly from SAMSON via **Interface menu > Update SAMSON**. ## Run the installer Start the installer you downloaded. The setup then guides you through: 1. accepting the license agreement 1. [optional step] configuring a proxy if your network requires one 1. entering your account email and SAMSON key 1. choosing the default or advanced installation mode 1. downloading and installing the selected SAMSON version Linux-specific installer note On Linux, open a terminal in the download folder and run (make the installer executable and launch it): ``` cd ~/Downloads chmod +x ./SAMSON-Setup.run QT_QPA_PLATFORM=xcb ./SAMSON-Setup.run ``` If you run into OpenGL or dependency issues, continue with [Troubleshooting](https://documentation.samson-connect.net/users/latest/troubleshooting/index.md). Note Intel graphics cards may currently cause issues. If you have one, the SAMSON installer will generate a warning. You may choose to ignore the warning, especially if you also have a non-Intel graphics card (NVIDIA or AMD). If your network uses a proxy, use the installer's **Test connection** button before continuing. At this point, the SAMSON installer checks that it can reach [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) - the installer needs to download SAMSON and [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md). If it can, this page shows the message *"SAMSON Connect reached successfully"*. Else, you might have to enter proxy parameters (you may have to ask your system administrator for information). Use the **Test connection** button to check that the proxy parameters you entered are valid. Then enter the email address and SAMSON key associated with your account: If you enable **Advanced mode**, you can choose a custom installation path and select a specific SAMSON version. When the installer starts the download, it retrieves [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) from [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) and installs it locally: When the installation finishes, the final page lets you start [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) and open [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md): ## After installation - Launch [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) for the first time using [Getting Started](https://documentation.samson-connect.net/users/latest/getting-started/#starting-samson). - Review [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) to customize your installation with [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md). - If you are on **macOS** and file access is limited, see [Full Disk Access In MacOS](https://documentation.samson-connect.net/users/latest/troubleshooting/#full-disk-access-on-mac). ## Related pages - [Getting Started](https://documentation.samson-connect.net/users/latest/getting-started/index.md) - [Requirements and platforms](https://documentation.samson-connect.net/users/latest/requirements-and-platforms/index.md) - [Troubleshooting](https://documentation.samson-connect.net/users/latest/troubleshooting/index.md) - [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) # First look: the interface Use this page for a quick tour of the main parts of the [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) interface so you can recognize the menu, viewport, document view, inspector, history, and other core panels. Read it before [SAMSON interface](https://documentation.samson-connect.net/users/latest/interface/index.md) when you need orientation first, or use it as a fast refresher before moving to navigation, structure loading, or a more detailed reference page. ## What this page covers This page identifies the main parts of the [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) interface and points you to the next page for navigation, loading structures, or the full interface reference. Use it when instructions mention the menu, viewport, Document view, Inspector, History, Asset Browser, or Animator and you want to know where those areas are. ## Main interface areas The [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) interface is composed of several main parts, visible in the image below: 1. **The menu** gives you fast access to the main commands, workspaces, and opened documents. 1. **The viewport** shows a three-dimensional representation of the document. 1. **The document view** shows a representation of the structure of the document. 1. **The history** gives you a list of performed actions. 1. **The inspector** provides access to parameters of the chosen nodes (atoms, residues, molecules, etc). 1. **The status bar** may provide messages. 1. **The assets** provides access to asset libraries from which you can easily add atoms, fragments, molecules to construct your systems. 1. **The animator** lets you create a presentation and add or modify animation effects. The [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) interface is automatically constructed from your [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md): the [menu](https://documentation.samson-connect.net/users/latest/interface/#menu) is populated with the functionality from the installed [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md). You can easily find commands, apps, and editors using the **Find everything** search box on top of the menu. For the full panel-by-panel reference, continue to [SAMSON Interface](https://documentation.samson-connect.net/users/latest/interface/index.md). ## Customization of the SAMSON interface You may customize the [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) interface by rearranging the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view), the [History view](https://documentation.samson-connect.net/users/latest/interface/#history), and the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) via drag-and-drop. These widgets and many other widgets for [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) can be docked together. To dock or undock a widget press on its title bar and move it where you want to place it and then release the mouse. Note Some windows in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) (e.g., some [Apps](https://documentation.samson-connect.net/users/latest/apps/index.md)) may have a "Pin" icon () that you can use to keep the window always on top. You can switch between different [workspaces](https://documentation.samson-connect.net/users/latest/interface/#workspace) to modify the menu representation (see the top-left corner of the menu). You can show or hide some parts of the [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) interface using the **Interface menu** or using the following shortcuts: | Parts of interface | Shortcut on , | Shortcut on | | ------------------------------------------------------------------------------------------------- | ------------- | ----------- | | [SAMSON AI](https://documentation.samson-connect.net/users/latest/samson-ai/index.md) | `Ctrl`+`0` | `Cmd`+`0` | | [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) | `Ctrl`+`1` | `Cmd`+`1` | | [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) | `Ctrl`+`2` | `Cmd`+`2` | | [History](https://documentation.samson-connect.net/users/latest/interface/#history) | `Ctrl`+`3` | `Cmd`+`3` | | [Asset browser](https://documentation.samson-connect.net/users/latest/interface/#asset-browser) | `Ctrl`+`4` | `Cmd`+`4` | | [Periodic table](https://documentation.samson-connect.net/users/latest/interface/#periodic-table) | `Ctrl`+`5` | `Cmd`+`5` | | [Job manager](https://documentation.samson-connect.net/users/latest/interface/#job-manager) | `Ctrl`+`6` | `Cmd`+`6` | | [Animator](https://documentation.samson-connect.net/users/latest/interface/#animator) | `Ctrl`+`7` | `Cmd`+`7` | | [Python console](https://documentation.samson-connect.net/users/latest/interface/#python-console) | `Ctrl`+`8` | `Cmd`+`8` | | [Code Editor](https://documentation.samson-connect.net/users/latest/interface/#code-editor) | `Ctrl`+`9` | `Cmd`+`9` | You may also add commands, apps, and editors to your **favorites** - they will appear in special favorites sections () on top of the ribbon menu and in the Editors viewport menu (on the left side of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md)). You can remove things from favorites by clicking on the corresponding icon. The way you customized the interface of your [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) installation will be saved and loaded the next time you open [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). You can search for available commands, apps, editors, and documentation in the **Find everything** (1) box on top of the ribbon menu. From here, you can add commands, apps, and editors to your favorites by clicking on the () icon when hovering them. 1. Shortcut: `Shift`+`E` For more details about the panels and shortcuts in this section, use the [SAMSON Interface](https://documentation.samson-connect.net/users/latest/interface/index.md) reference. ## Next step - Continue with [Moving around](https://documentation.samson-connect.net/users/latest/moving-around/index.md) if your next goal is camera control and viewport navigation. - Continue with [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md) if you are ready to open or fetch a first structure. - Continue with [SAMSON interface](https://documentation.samson-connect.net/users/latest/interface/index.md) if you want the deeper interface reference. # Moving around Use this page when you need to move around a molecular scene in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md), choose the editor that controls mouse behavior, center the camera, manage multiple cameras, or adjust clipping while inspecting dense structures. See also - [Camera](https://documentation.samson-connect.net/users/latest/camera/index.md): open the dedicated camera reference when you need camera-specific details. ## What this page covers This page explains the navigation controls that are useful early in the onboarding path and later during visualization, editing, and presentation work. You will learn how to: - choose and switch the default editor used for viewport interaction - rotate, pan, zoom, and center the camera with a mouse, trackpad, or keyboard - use the compass and camera context menu for common camera actions - keep several camera views in one document - control progressive clipping and fog when inspecting structures with depth Use [Camera](https://documentation.samson-connect.net/users/latest/camera/index.md) as the detailed camera reference when you need camera properties rather than everyday navigation controls. Use this page for hands-on viewport navigation. Use [Camera](https://documentation.samson-connect.net/users/latest/camera/index.md) when you need camera node behavior, camera creation, camera context-menu actions, or camera-specific reference details. ## When to read this Read this after [First look: the interface](https://documentation.samson-connect.net/users/latest/first-look/index.md), when you can identify the viewport and Document view. After you can rotate, pan, zoom, center the camera, and switch editors confidently, continue to [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md) to bring structures into SAMSON. The key element of visualization in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) is a [camera](https://documentation.samson-connect.net/users/latest/camera/index.md), it provides a 3D view of visualizable objects, and can be easily controlled to point to a specific location, zoom in or out, translate, rotate, etc. Basically, you may consider your screen as a camera pointing into the screen and yourself as an operator seeing through the camera. A [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) is a part of a [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) [document](https://documentation.samson-connect.net/users/latest/documents/index.md), and each [document](https://documentation.samson-connect.net/users/latest/documents/index.md) has at least one camera, and you can add [multiple cameras](#multiple-cameras) into a document to easily switch between different views. Cameras (with all their properties) are saved and loaded together with a [document](https://documentation.samson-connect.net/users/latest/documents/index.md). A [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) has three modes: **rotation**, **translation**, and **zoom**. ## Default editors When you start SAMSON for the first time, you are prompted to select your **default editor** from the following ones: - **View Editor** - **Point Selection Editor** - **Rectangle Selection Editor** The first two editors are especially helpful for users who are familiar with other traditional molecular visualization tools and have specific preferences for how to explore, select, or build molecular structures. Together with the **Rectangle Selection Editor** and other editors, they give you the flexibility to tailor the interface to your workflow — whether you're visualizing, selecting, or designing molecular systems. ### View and selection editors and when to use them | Editor | Shortcut | Best for | | ------------------------------ | -------- | -------------------------------------------------------------------------------------------- | | **View Editor** | `V` | Visualizing structures (recommended for users familiar with standard visualization software) | | **Point Selection Editor** | `P` | Combining visualization and design (e.g. bio-structural editing, residue or atom selections) | | **Rectangle Selection Editor** | `R` | Detailed structural design and construction (e.g. nanostructures) | ### Switching editors You can switch editors anytime: - Via the editor icons in the **Editors toolbar** on the left side of the viewport. Editor toolbar The Editor Toolbar on the left side of the viewport includes all available editors, including those installed via extensions. - By pressing the appropriate keyboard shortcut. - Or by pressing `Esc` to return to your default editor. ### Setting default editor You can **change the default editor** anytime in the **Preferences > Editors > Default**. ## How to navigate with the View Editor The **View editor** (`V`) provides intuitive navigation for exploring molecular systems. | Action | How to perform | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **Rotate** | - Click and drag with the left or right mouse button (or single-finger drag on a trackpad) - Use keyboard arrows: `Up`, `Down`, `Left`, `Right` | | **Pan** | Use the middle mouse button, or `Shift` + `Ctrl`/`Cmd` + drag on a trackpad | | **Zoom** | Scroll wheel or pinch gesture on a trackpad | Tip SAMSON includes tooltips and UI hints to guide navigation based on your hardware (mouse or trackpad). Hover over tools to view shortcuts and usage tips. Note The rotation behavior slightly changes depending on whether the **grid** is on or off: - When the grid is on, consider it as a table on which you rotate a system. - When the grid is off, consider that you rotate a system that is floating free. ## How to navigate with the Point Selection Editor The **Point selection editor** (`P`) has the same navigation commands as the [View editor](#how-to-navigate-with-the-view-editor) with an addition of **selecting objects on click**. ## How to navigate with the Rectangle Selection Editor ### Using a mouse - Click on the *right mouse button* to **rotate the view**. - Press the *mouse wheel* to **translate the view**. - Scroll the *mouse wheel* to **zoom in/out**. - Double-click on the *middle button/mouse wheel* to **center the view**. `Ctrl`/`Cmd` + *right mouse button* replaces the middle button. ### Using a keyboard - `Up`, `Down`, `Left`, `Right` - **rotate the view** around the horizontal or vertical axis. - `Alt` and `Left`, `Right` - **rotate the view** in the viewport plane around its center. - `Ctrl` and `Up`, `Down`, `Left`, `Right` - **translates the view** horizontally or vertically. - `Ctrl`+`+` - zoom in. - `Ctrl`+`-` - zoom out. - `Shift`+`Space` - center the camera on the selection or on the full view if nothing is selected. Note The rotation behavior slightly changes depending on whether the **grid** is on or off: - When the grid is on, consider it as a table on which you rotate a system. - When the grid is off, consider that you rotate a system that is floating free. ### Rotation mode To switch the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) into a **rotation mode**, press and hold the *right mouse button*. There are two rotation modes: close to the borders of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) and a trackball rotation mode (the view point is rotating around the center) in the middle part of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). ### Translation mode To switch the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) into a **translation mode**, press and hold the *mouse wheel*. Try to move your mouse and you will see that the molecule follows it. ### Zoom mode To switch the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) into a **zoom mode**, scroll the *mouse wheel*: turn the wheel and the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) will zoom in and zoom out depending on the wheel scrolling direction. ### Centering Double-click on the *mouse wheel* to **center the view**. The `Shift`+`Space` shortcut changes the camera focus. Select an atom and press `Shift`+`Space`, this centers the camera on the selected part (so that the selection will be in focus). If nothing is selected, then the camera is centered on the full view of the molecular system (the whole molecular system in the active [document](https://documentation.samson-connect.net/users/latest/documents/index.md)). Tip If you lose your molecular system, press `Shift`+`Space` and the camera will be re-positioned. Tip If the camera is centered on an atom and you rotate the view, the rotation will be centered around the atom. ## Compass The **compass** is a dedicated [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) controller, which is situated in the bottom-left corner of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) and can be shown/hidden using the menu in the bottom part of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) by clicking on the corresponding icon. The compass allows you to easily align the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) and rotate it around different axes. ## Camera functions You can access some of the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md)'s functionality through its context menu. Right-click on a camera in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) to apply some of its actions: - center the camera on the [selection](https://documentation.samson-connect.net/users/latest/selecting/index.md) or on the whole document - activate the **camera inertia** which will allow for a movement with inertia - activate the **camera orthographic projection** which is useful e.g. for viewing crystals - set the camera as the active one - move the camera Try switching the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) inertia on and move or rotate the molecule. Try switching on and off the orthographic projection mode. ## Multiple cameras You can have multiple cameras in one [document](https://documentation.samson-connect.net/users/latest/documents/index.md) but only one camera can be active at a time. Having multiple cameras might be useful if you want to switch fast between different views (e.g., positions, projections, close-up views, and a full view) in the same [document](https://documentation.samson-connect.net/users/latest/documents/index.md). To switch between [cameras](https://documentation.samson-connect.net/users/latest/camera/index.md), *double-click* on one or *right-click* on one in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) and in its context menu click **Set as active camera**. To add a new camera, click **Visualization > Camera** (1). A newly added camera will have a default starting position. 1. , : `Ctrl`+`Shift`+`C`, : `Cmd`+`Shift`+`C` ## Clipping structures **Progressive clipping** is a new visualization feature in SAMSON, introduced in SAMSON 2025 R2 it significantly improves the previous clipping implementation. It enhances how molecular structures are visually explored. Unlike traditional clipping, which creates an abrupt cutoff in the view, progressive clipping offers a gradual transition and it incorporates the previously separate fog rendering option. This helps intuitively understand which parts of the structure are being clipped based on their distance from the camera. This feature is especially useful when inspecting dense molecular structures (e.g., proteins) or creating visualizations with depth clarity for presentations, publications, or interactive analysis. The progressive clipping is activated by default. To see how you can control the way clipping (before the camera target) and fog (after the camera target) work, see the description below. ### Video tutorial You can learn how to use progressive clipping from the following extract of the SAMSON 2025 webinar: ### How to use progressive clipping #### 1. Load a structure To try out progressive clipping, load any structure. For example, use **Home > Fetch** to load a protein of your choice. #### 2. Activate and control progressive clipping Progressive clipping is activated by default. It gradually fades parts of the structure depending on their distance from the camera, providing a more informative and realistic depth perception. ##### Controls - **Mouse + Keyboard shortcuts**: - To **change the clipping distance**: press `Ctrl` (on Windows/Linux) or `Cmd` (on macOS) and scroll or slide on the trackpad. - To **change the thickness of the visible region** ("*viewing slab*" governed by clipping and fog): hold `Shift` + `Ctrl` (Windows/Linux) or `Shift` + `Cmd` (macOS) while scrolling. - **Viewport toolbar**: - Use the **clipping and fog control icon** at the bottom of the SAMSON viewport to open the **clipping control panel**. ##### Clipping control panel The control panel shows: - **Camera Eye** - your current viewing position. - **Camera Target** - what you're looking at. - **Background** - infinite depth. You can: - **Adjust clipping distance** (on the left): Defines how close structures begin to be clipped. - **Adjust fog distance** (on the right): Hides parts further in the background. - Access the **clipping preferences**. #### 3. Customize the appearance You can tailor the clipping style to suit your needs: click the **Settings** icon near the clipping panel, or go to **Interface > Preferences > Rendering > Clipping**. The options include: - **Presets**: Choose from the predefined clipping styles for common visualization needs. For example, choose between progressive and traditional (sharp cut) clipping. - **Border size**: Change the thickness of the clipping edge border to highlight what is being clipped. #### 4. Enhance your view Combine progressive clipping with other [visualization](https://documentation.samson-connect.net/users/latest/visualizing/index.md) and [rendering](https://documentation.samson-connect.net/users/latest/rendering-effects/index.md) tools: - Change [background color](https://documentation.samson-connect.net/users/latest/rendering-effects/#background). - Enable [silhouettes](https://documentation.samson-connect.net/users/latest/rendering-effects/#silhouettes). - Apply [visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/index.md) and [colorization](https://documentation.samson-connect.net/users/latest/colorizing/index.md). - [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) nearby residues (e.g., binding site residues) via **Select > Biology > Binding sites**. - [Label](https://documentation.samson-connect.net/users/latest/labeling/index.md) selections for clarity. All of this remains dynamically visible as you rotate and zoom, thanks to the smooth clipping transitions. ### When to use clipping Progressive clipping is especially helpful when: - Exploring internal binding sites or ligand environments. - Generating images or animations where depth clarity is critical. - Teaching or demonstrating 3D molecular features interactively. ## Related pages - [First look: the interface](https://documentation.samson-connect.net/users/latest/first-look/index.md): identify the viewport, Document view, and toolbars before using navigation controls. - [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md): continue the onboarding path by opening or fetching a structure. - [Camera](https://documentation.samson-connect.net/users/latest/camera/index.md): look up camera-specific properties and actions. - [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md): continue with visual models, presets, visibility, and viewport captures. - [Rendering effects](https://documentation.samson-connect.net/users/latest/rendering-effects/index.md): adjust rendering options that change depth, lighting, and visibility. # Loading molecules Use this page to open local structures, fetch molecules, understand how [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) documents store data, and embed related files. Start here after installation when you are ready to bring real content into [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), whether that content comes from local files, fetched structures, and embedded project material. ## When to read this Read this after [Moving around](https://documentation.samson-connect.net/users/latest/moving-around/index.md), when you can navigate the viewport and recognize the Document view. After loading a structure, most workflows continue with selection, inspection, visualization, editing, simulation, or sharing. ## Open local files and fetch structures To load a molecule use **Home > File > Open** or the `Ctrl`+`O` shortcut (`O` as in Open) on Windows and Linux or `Cmd`+`O` on Mac. To open a recent file, follow **Home > File > Recent**, where you will find a list of the recently opened files. [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) will use an appropriate [importer](https://documentation.samson-connect.net/users/latest/importers/index.md) to load a file based on its format. By default, [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) has importers and exporters for multiple file formats (see the [list of supported formats](https://documentation.samson-connect.net/users/latest/supported-formats/index.md)). If you want additional importers, go to the **Marketplace** on [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) and check for other importers (see [SAMSON Connect - Marketplace](https://documentation.samson-connect.net/users/latest/samson-connect/#marketplace)). Depending on the importer and the file format you might need to specify additional parameters used by the importer, as shown below. The first time you use an importer its parameters are set by default. Once you modify them, they will be saved for the next use. Press **OK** or `Enter` and the file will be imported into [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). You will see it in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) and in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). Molecular structures can also be downloaded using specific [Apps](https://documentation.samson-connect.net/users/latest/apps/index.md), such as **Fetch Structures** (**Home > Fetch**), which lets you download files (in PDB, mmCIF/PDBx, MMTF formats) from the RCSB Protein Data Bank. ## Documents Loaded or created molecules, files, and folders are added in the active [document](https://documentation.samson-connect.net/users/latest/documents/index.md). You can see the [document](https://documentation.samson-connect.net/users/latest/documents/index.md) in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view), which you can open by clicking **Interface > Document view** (1). 1. , : `Ctrl`+`1`, : `Cmd`+`1` The [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) shows the data graph of the active [document](https://documentation.samson-connect.net/users/latest/documents/index.md). Documents store all information about atoms, bonds, molecules, models, simulators, and more. You can simultaneously have several [documents](https://documentation.samson-connect.net/users/latest/documents/index.md) open in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), however, only one [document](https://documentation.samson-connect.net/users/latest/documents/index.md) is active at any given time: the one you see in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view). Having several [documents](https://documentation.samson-connect.net/users/latest/documents/index.md) is useful, for example, when you want to do different tasks with different molecules or copy structures from one document to another. To switch between [documents](https://documentation.samson-connect.net/users/latest/documents/index.md), click on the **Documents** list in the top-left corner of the menu, or **Home > Documents** (1). You can also see there the number of opened documents. 1. , : `Ctrl`+`Tab` and `Ctrl`+`Shift`+`Tab`\ : `Cmd`+`Tab` and `Cmd`+`Shift`+`Tab` To create a new [document](https://documentation.samson-connect.net/users/latest/documents/index.md), follow **Home > File > New** (1). 1. , : `Ctrl`+`N`, : `Cmd`+`N` To open recently opened documents, use **Home > File > Recent**. See [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view), [document](https://documentation.samson-connect.net/users/latest/documents/index.md), and [node types](https://documentation.samson-connect.net/users/latest/node-types/index.md) for more details. ## Embedding files and folders [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) [documents](https://documentation.samson-connect.net/users/latest/documents/index.md) can contain not only molecular models. They enable **Universal File Embedding** and can embed Python scripts and any number of files and folders. This makes it possible to embed Python scripts and whole Python apps (e.g., machine learning apps), research papers, images, data, and much more. To embed files and folders within a [document](https://documentation.samson-connect.net/users/latest/documents/index.md), drag and drop them in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) and you will be asked whether you would like to embed them, or use **Home > Embed files** or **Home > Embed folders**. Folders and files are stored within the [document](https://documentation.samson-connect.net/users/latest/documents/index.md), making the document self-contained, so you can transfer documents between computers and [share documents](https://documentation.samson-connect.net/users/latest/share-documents/index.md). ## Next step - Continue with [Work with structures](https://documentation.samson-connect.net/users/latest/work-with-structures/index.md) if you want to select, inspect, or measure what you opened. - Continue with [Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md) if your next goal is editing or constructing a system. - Continue with [Share documents](https://documentation.samson-connect.net/users/latest/share-documents/index.md) if you need to share documents on [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) or download shared documents. - Continue with [Collaboration](https://documentation.samson-connect.net/users/latest/collaboration/index.md) if you need to manage access rights, groups, or shared documents on [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). # Interactive tutorials Use interactive tutorials when you want SAMSON to guide you through a task directly inside the application. To try one, go to **Help > Tutorials**, select a tutorial, and click **Start tutorial**. ## What this page covers This page explains where to launch built-in tutorials, when they fit into the onboarding sequence, and how to stop or restart one. Use interactive tutorials after you know the main interface areas from [First look: the interface](https://documentation.samson-connect.net/users/latest/first-look/index.md). They are most useful when you want to practice a concrete workflow inside SAMSON instead of only reading about it. ## When to read this Interactive tutorials are optional. Use them after [Moving around](https://documentation.samson-connect.net/users/latest/moving-around/index.md) and [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md) if you want guided practice inside the application, or skip them and return later when a tutorial matches a specific workflow. After completing a tutorial, you should be able to repeat the demonstrated workflow without the tutorial window, or know which guide page to open for the same task. ## Starting a tutorial Go to **Help > Tutorials**, select a tutorial, and click **Start tutorial**. ## Stopping or restarting a tutorial To stop an interactive tutorial, close the tutorial tip window in the top-right corner of the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). You can always restart an interactive tutorial from scratch in **Help > Tutorials**. Tip For [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md), see [SAMSON Extensions Tutorials](https://documentation.samson-connect.net/tutorials/index.md). ## Next step - Continue with [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md) if you want to practice with your own structures. - Continue with [SAMSON AI](https://documentation.samson-connect.net/users/latest/samson-ai/index.md) if you want assistant-led help for questions, commands, selections, or scripts. ## Related pages - [Start here](https://documentation.samson-connect.net/users/latest/start/index.md): follow the full onboarding path before or after a tutorial. - [First look: the interface](https://documentation.samson-connect.net/users/latest/first-look/index.md): learn the interface areas used by tutorials. - [SAMSON AI](https://documentation.samson-connect.net/users/latest/samson-ai/index.md): use the assistant for questions, commands, selections, and scripts. # SAMSON AI Use SAMSON AI when you want in-application help with SAMSON commands, menus, editors, apps, selections, or scripts. The assistant can answer questions, link to relevant documentation, execute commands, generate Python scripts, select nodes, and learn from URLs you provide. You can open the SAMSON AI via **Interface > Assistant** or via the `Ctrl`+`0` shortcut on Windows and Linux or `Cmd`+`0` on Mac. ## What this page covers This page explains how to use SAMSON AI for questions, commands, selections, script generation, and document-aware help inside [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). Note SAMSON AI is based on **GPT-5** in the **Professional plan**. ## Commands SAMSON AI has special commands that give you access to advanced functionality: - `/do`: to execute actions - `/script`: to generate Python scripts - `/select`: to select nodes - `/learn`: to learn from a URL - `/refer`: to ask questions about learned information - `/forget`: to forget all learned information Type `/` in the Assistant's input to show the list of available commands: ### /do This command is utilized to execute actions in the document. You can ask SAMSON AI to perform tasks such as zooming to the selection, selecting the binding site, altering the color of the Van der Waals model, and more. Examples: - `/do zoom to the binding site.` - `/do select the ligand and apply a licorice model.` - `/do erase all surfaces.` - `/do remove water.` - `/do select the gaussian surface and make it light blue.` If you prefer to speak, just say **do** (turn the sound on for the video example below): This is an example of *retrieval-augmented agency* (RAA), where knowledge about SAMSON and its extensions allows the GPT-5-based SAMSON AI to act on user prompts. ### /script This command is used to generate Python scripts. These scripts use the [SAMSON Python API](https://documentation.samson-connect.net/users/latest/scripting/index.md) to interact with the document, and can be combined with other Python modules for e.g., machine learning, trajectory analysis, etc. Examples: - `/script select all atoms and translate them in the z direction by 1 angstrom.` - `/script create a GUI that lets me enter a distance in angstrom, with a 'Move' button.` - `/script compute the gyration radius of the receptor.` ### /select This command allows you to select nodes using natural language. SAMSON AI displays the corresponding [Node Specification Language (NSL)](https://documentation.samson-connect.net/users/latest/nsl/index.md) for your query and executes it. Examples: - `/select the binding site.` - `/select all side chains within 5 angstrom of the ligand.` - `/select all lysines in chain B.` ### /learn The `/learn` command is employed to absorb information from a URL. SAMSON AI reads the provided document and can subsequently answer questions about it. You can use this command multiple times to learn from multiple documents. The learned data persists even when SAMSON is turned off, until the `/forget` command is called. At the moment, SAMSON AI can read regular pages and PDF documents. Examples: - `/learn https://en.wikipedia.org/wiki/COVID-19` - `/learn https://www.biorxiv.org/content/10.1101/2022.08.03.502585v2.full.pdf` ### /refer You can use the `/refer` command to ask questions about the learned data. Examples: - `/refer What is the infection fatality rate?` - `/refer Give me a table showing the IFR estimates per age group.` - `/refer How many molecules does the database contain?` ### /forget This command makes SAMSON AI to forget all the learned data. Usage: - `/forget` ## Limitations While we strive to provide the best AI experience, it is important to be aware of the limitations and potential issues with SAMSON AI. Please take note of the following: - Incomplete Knowledge: SAMSON AI may not be aware of recent developments or discoveries in various fields. - Ambiguity and Misinterpretation: The AI might generate responses that are ambiguous, unclear, or misinterpret your input. Please ensure you provide clear and concise queries. - Bias and Sensitivity: SAMSON AI may inadvertently exhibit biases that are politically, culturally, or emotionally insensitive. - Inaccuracy: While SAMSON AI can provide helpful information, it may not always be accurate or reliable, and may make up facts. Please cross-verify critical information with multiple trusted sources. By using SAMSON AI, you acknowledge these limitations and agree to use the AI responsibly. We welcome feedback to help improve our system and user experience. ## Privacy policy Note: This privacy policy refers to the use of SAMSON AI. For the privacy policy of SAMSON and SAMSON Connect, use the [SAMSON privacy policy](https://www.samson-connect.net/privacyPolicy.html). At OneAngstrom, we value your privacy and are committed to protecting your personal information. This Privacy Policy outlines our practices regarding the collection, use, and disclosure of your information when you use SAMSON AI. By using SAMSON AI, you agree to the collection and use of information in accordance with this policy. ### Information Collection and Use While you use SAMSON AI, we may collect and store information on how you access and use it, including your search queries and interactions with the AI. This data is used to improve our services and provide a better user experience. ### Data Security We take appropriate measures to protect your personal information from unauthorized access, disclosure, alteration, or destruction. In particular, your messages are encrypted during transmission. However, no method of electronic transmission or storage is completely secure, and we cannot guarantee its absolute security. ### Third-Party Services SAMSON AI may use third-party services for various purposes, such as internal processing, analytics and service improvement. ### Contact Us If you have any questions or concerns about this Privacy Policy, please contact us at [contact@samson-connect.net](mailto:contact@samson-connect.net). [Contact us](mailto:contact@samson-connect.net) Thank you for using SAMSON AI, and we are committed to ensuring your privacy while providing the best possible AI experience. ## Related pages - [Scripting](https://documentation.samson-connect.net/users/latest/scripting/index.md) - [Interactive tutorials](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md) - [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) # SAMSON Connect Use this page to understand what [SAMSON Connect](https://www.samson-connect.net/) is for and where to go for downloads, Marketplace extensions, account settings, shared documents, groups, jobs, and developer resources. Read it when you need the website workflow around [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). If your next task is only sharing or permissions, you can jump directly to [Collaboration](https://documentation.samson-connect.net/users/latest/collaboration/index.md) or [Share documents](https://documentation.samson-connect.net/users/latest/share-documents/index.md). ## What this page covers This page explains the main sections of [SAMSON Connect](https://www.samson-connect.net/) and how they connect to downloads, extensions, documents, profiles, collaboration workflows, cloud jobs, and SDK access. ## Use this page when - You need to download [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) or find your SAMSON key. - You want to add, remove, try, or subscribe to [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md). - You need account settings, profiles, groups, shared documents, or shared cloud jobs. - You are a developer looking for the SAMSON SDK download and extension distribution path. ## You can skip this if - You only need to open or inspect local structures; start with [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md). - You already know [SAMSON Connect](https://www.samson-connect.net/) and only need sharing permissions; go to [Collaboration](https://documentation.samson-connect.net/users/latest/collaboration/index.md). - You only need to run or monitor remote jobs from [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md); go to [Cloud computations](https://documentation.samson-connect.net/users/latest/cloud/index.md). [SAMSON Connect](https://www.samson-connect.net/) is organized into several main sections described below. ## Platform The **Platform** section gives an overview of the SAMSON Platform. It's the main landing page. You can also create an account on that page. ## Pricing The [Pricing](https://www.samson-connect.net/pricing.html) section gives an overview and comparison of Plans for [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). You can also find FAQ about plans at the bottom of the [Pricing](https://www.samson-connect.net/pricing.html) page. The functionality available in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) might differ depending on the **Plan** you have. Note [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) will always have a **Free** (Starter) plan while some functionality and the number of free [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) might be limited in it. ## Marketplace Access the [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) marketplace to add new [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md). Here you can see all the available [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md), i.e. modules for [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). The image below shows some [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) that can be found there: When you click on a [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md), it takes you to its web-page which provides its description, an information about its authors, the supported operating systems (e.g. Windows, Linux, and Mac), versions of the [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md), and the latest versions of [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) for which it's available. [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) can be: - included depending on you current Plan, - freely available (can be added from [SAMSON Connect](https://www.samson-connect.net/)), - available through a subscription mechanism. For a freely available [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md), signed in users may click the **Add** button to add it to their [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) installation. The added [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) is then marked as "Added": Once [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) is restarted, it downloads the [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) and installs it automatically. For a [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) available through a subscription mechanism, signed in users may either **try** them or **subscribe** to them. To try an extension, click on the **Request trial** button. It does not require any credit card information. An extension in a trial period is marked as "Trying": To subscribe to an extension, click on the **Subscribe** button for the monthly or yearly plan. If you have an academic status, then you will be able to subscribe to the academic plan. An extension to which you subscribed is marked as **Subscribed**: To remove a free [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md), sign in to your account on [SAMSON Connect](https://www.samson-connect.net/), then go to **Marketplace** or to **Account > Settings** and click on **View my extensions**, go to the [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) you want to remove from your [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) installation and open its page, and hover above the **Added** button - will change to **Remove**, and then click the **Remove** button. To manage your subscriptions, go to **Account > Settings** and click on **View my subscriptions**. This will lead you to the **My Subscriptions** page where you can manage your subscriptions. Once [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) is restarted, the [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) will be removed from your [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) installation. The removed [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) will still be shown in the section **Account > Settings > View my extensions** on [SAMSON Connect](https://www.samson-connect.net/) so that you can easily add it later if you wish so. ## Resources Get computing credits, access various documentation, [Forum](#forum) and [Blog](#blog), and [Shared documents](#shared-documents). ### Computing credits Buy or get computing credits to perform computations in the Cloud. Continue with [Cloud computations](https://documentation.samson-connect.net/users/latest/cloud/index.md) when your next step is running or monitoring remote jobs. ### Documentation The **Documentation** section links to the [Documentation center](https://documentation.samson-connect.net/), which provides this [User Guide](https://documentation.samson-connect.net/users/latest/), [tutorials for various extensions](https://documentation.samson-connect.net/tutorials/index.md), the [Python Scripting Guide](https://documentation.samson-connect.net/scripting/latest/), and the [Developer Guide](https://documentation.samson-connect.net/developers/latest/). ### Forum On the [SAMSON Connect Forum](https://forum.samson-connect.net/) you can ask your questions about [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), [SAMSON Connect](https://www.samson-connect.net/), [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md), as well as leave your feedback and suggestions. ### Blog The [SAMSON Connect Blog](https://blog.samson-connect.net/) contains some blog posts, tips, etc.: ### Shared documents The [SAMSON Connect - Documents](https://www.samson-connect.net/documents) section shows shared [documents](https://documentation.samson-connect.net/users/latest/documents/index.md) that you can download directly into [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). You can also publish a [document](https://documentation.samson-connect.net/users/latest/documents/index.md) right from [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). Shared documents provide a way to share and communicate your work. Note See [Shared documents](https://documentation.samson-connect.net/users/latest/share-documents/index.md) and [Managing shared documents on SAMSON Connect](https://documentation.samson-connect.net/users/latest/collaboration/#managing-shared-documents-on-samson-connect) for more information. ## Sign in Sign in to [SAMSON Connect](https://www.samson-connect.net/) or create a free account if you do not have one. Once signed in you can click on your user's icon to access your personal account, your [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md), your subscriptions, your shared documents, and, in the case if you are a developer, your developed extensions, and a page to download the SAMSON SDK. From your account you can edit your personal information, get your SAMSON Keys, manage your SAMSON Plan, subscriptions to [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md), buy computing credits. ## Account / User menu ### Profile Create and manage your public profile here. See: [Collaboration - Editing your profile](https://documentation.samson-connect.net/users/latest/collaboration/#profile). ### Groups Create and manage private or public groups to share documents, jobs, extensions, and other resources. See: [Collaboration - Creating and managing groups](https://documentation.samson-connect.net/users/latest/collaboration/#groups). ### Documents Manage your public or private shared documents and control who can access them. See: [Collaboration - Sharing documents](https://documentation.samson-connect.net/users/latest/collaboration/#sharing-documents). ### Jobs View and share jobs that you run in the cloud from [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). You can control who has access to them. See: [Collaboration - Viewing and sharing jobs on SAMSON Connect](https://documentation.samson-connect.net/users/latest/collaboration/#sharing-jobs). ### Developed extensions Access and manage [SAMSON extensions developed by you](https://documentation.samson-connect.net/users/latest/extending-samson/#develop-a-samson-extension). ### Settings Here you can: - Access your SAMSON and SAMSON SDK key - Manage your plan - View your extensions - View your subscriptions - Buy credits - Get your referral code ## Download [Download SAMSON or SAMSON SDK](https://www.samson-connect.net/download), the latter of which is necessary if you want to [develop your own SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/#develop-a-samson-extension). You can also find your personal SAMSON and SAMSON SDK private keys there, so do not share them with anyone. ## Next step - Continue with [Collaboration](https://documentation.samson-connect.net/users/latest/collaboration/index.md) if you need profiles, groups, permissions, shared documents, or shared jobs in more detail. - Continue with [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) if your next step is extension management or SDK-based development. - Continue with [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md) if you want to publish or download documents from inside [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). # Webinars Check out the webinars below for an overview of recent SAMSON releases without interrupting the main installation and first-launch workflow. ## SAMSON 2026 webinar [Join our webinar introducing SAMSON 2026 R1](https://1-a.io/samson2026) on April 30, 2026, 8am PST, 11am EST, 5pm CET. ## SAMSON 2025 webinar recording Learn about the **new features in SAMSON 2025 R1 and R2**: Video chapters - [0:00](https://www.youtube.com/watch?v=kGW1_t0GXYo) Intro, downloading SAMSON - [1:30](https://www.youtube.com/watch?v=kGW1_t0GXYo&t=90s) View and Point selection editors - [7:27](https://www.youtube.com/watch?v=kGW1_t0GXYo&t=447s) Progressive Clipping feature to inspect structures - [14:42](https://www.youtube.com/watch?v=kGW1_t0GXYo&t=882s) Quick Groups to store and control selections - [20:33](https://www.youtube.com/watch?v=kGW1_t0GXYo&t=1233s) [Protein Aligner](https://www.samson-connect.net/extensions/0bee42d5-181b-b366-39a5-36607f0b5731) to align multiple sequences and structures of proteins - [30:02](https://www.youtube.com/watch?v=kGW1_t0GXYo&t=1802s) Create and edit 2D and 3D protein-ligand interaction diagrams using the new [Interaction designer](https://www.samson-connect.net/extensions/52fe9e27-19f3-093b-4f4f-4c6aff880a77) - [44:59](https://www.youtube.com/watch?v=kGW1_t0GXYo&t=2699s) Pattern Builders to rapidly create advanced designs ## SAMSON 2024 webinar recording To learn more about the SAMSON 2024 features, watch the webinar recording: Video chapters - [00:00](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=0s) OneAngstrom and SAMSON - [03:16](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=196s) SAMSON's top six distinctive features - [06:55](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=415s) Documentation and interactive tutorials - [09:00](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=540s) Getting answers and getting things done with SAMSON AI - [13:15](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=795s) Selecting with the Document View and the Context Toolbar - [16:29](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=989s) Selecting with the Viewport and Selection filters - [17:37](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=1057s) Selecting with Selection Commands - [18:35](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=1115s) Selecting with the Node Specification Language and SAMSON AI - [21:26](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=1286s) Selecting with the new Interactive Sequence Viewer - [23:47](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=1427s) Producing studio-quality renderings with Cycles, the integrated path tracer from Blender - [26:32](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=1592s) Creating new visualizations quickly with the new Visual Preset Editor - [31:52](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=1912s) Creating movies with the Animator - [33:39](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=2019s) Using the new Cloud Job Manager and predicting protein structures - [36:40](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=2200s) Importing and visualization GROMACS simulations - [39:39](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=2379s) Creating apps and executable documents with the integrated Python Environment - [43:17](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=2597s) Publishing documents securely and privately on SAMSON Connect - [45:48](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=2748s) Creating and publishing your social profile on SAMSON Connect - [46:26](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=2786s) Creating groups and organizing teams on SAMSON Connect - [47:20](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=2840s) Sharing documents with users and groups - [50:00](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=3000s) Beginning Q&A - [51:10](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=3070s) Using Martinize to create coarse-grained structures - [55:35](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=3335s) Importing and sharing cloud jobs - [58:07](https://www.youtube.com/watch?v=9fWndkgPy1Q&t=3487s) Contacting the developers ## Related pages - [Getting Started](https://documentation.samson-connect.net/users/latest/getting-started/index.md) - [First look](https://documentation.samson-connect.net/users/latest/first-look/index.md) - [Interactive tutorials](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md) # User Guide - Work with structures # Work with structures Use this topic after you have opened or loaded a system and need to work with it safely. It covers the core document interactions that most other workflows depend on: selecting the right nodes, checking or changing properties, measuring geometry, and using history to recover from mistakes. Read it in order if you are new to SAMSON, or jump to the task you need. ## Who this topic is for - Users selecting atoms, residues, molecules, or other nodes - Users checking or editing properties in the Inspector - Users measuring distances, angles, or dihedrals - Users exploring structures safely with undo and redo ## What you will be able to do afterward - Select nodes with commands, editors, filters, or NSL - Inspect and adjust node properties - Create and save measurements - Move backward and forward through document history ## Recommended reading order 1. [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) - Start here because selection is the basis for inspection, measurement, and most editing actions. `Foundational.` 1. [Inspecting](https://documentation.samson-connect.net/users/latest/inspecting/index.md) - Continue here to check and edit properties of the nodes you selected. `Foundational.` 1. [Measuring](https://documentation.samson-connect.net/users/latest/measuring/index.md) - Read this when you need geometric checks or saved measurement labels. `Task-focused.` 1. [History: Undo and redo](https://documentation.samson-connect.net/users/latest/history/index.md) - Use this to understand how to move safely through document changes while you work. `Task-focused.` ## Read this first Start with [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md). ## You can skip this for now if... - You are not checking geometry yet, in which case you can skip [Measuring](https://documentation.samson-connect.net/users/latest/measuring/index.md) - You only need a quick refresher and are not changing the document yet, in which case you can skip [History: Undo and redo](https://documentation.samson-connect.net/users/latest/history/index.md) ## Suggested paths - **Selection and properties**: [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) -> [Inspecting](https://documentation.samson-connect.net/users/latest/inspecting/index.md) - **Geometry checks**: [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) -> [Measuring](https://documentation.samson-connect.net/users/latest/measuring/index.md) - **Safe trial-and-error editing**: [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) -> [History: Undo and redo](https://documentation.samson-connect.net/users/latest/history/index.md) ## Where to go next - [Build and edit](https://documentation.samson-connect.net/users/latest/build-and-edit/index.md) - Continue here when you want to change structures after selecting and inspecting them. - [Visualize and present](https://documentation.samson-connect.net/users/latest/visualize-and-present/index.md) - Go here when you want clearer views, color, labels, or presentation output. - [Simulate and analyze](https://documentation.samson-connect.net/users/latest/simulate-and-analyze/index.md) - Continue here when your next step is modeling, trajectories, or analysis. # Selecting Use this page to choose atoms, residues, molecules, and other [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) before you inspect, edit, move, measure, visualize, or simulate them. [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides several ways to make simple or complex selections: - [Selection commands](https://documentation.samson-connect.net/users/latest/selecting/#selection-commands), see the **Select menu** - [Selecting using the Document View](https://documentation.samson-connect.net/users/latest/selecting/#selecting-using-the-document-view) - [Selection editors](https://documentation.samson-connect.net/users/latest/selecting/#selecting-using-editors) - [Selection filters](https://documentation.samson-connect.net/users/latest/selecting/#selection-filters) - [Selecting using the Node Specification Language](https://documentation.samson-connect.net/users/latest/selecting/#selecting-using-nsl) - [Python Scripting](https://documentation.samson-connect.net/users/latest/scripting/index.md) for even more complex and scripted selections. [Interactive tutorials](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md) in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) (**Help > Tutorials**): *"Working with documents"*, *"Selecting in the Viewport"*, *"Selecting using the Node Specification Language"*. ## What this page covers This page explains the main ways to select nodes in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), from viewport tools and document filters to NSL expressions and saved groups. **What you will learn from this tutorial**: From this tutorial, you will learn how to select [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view), and using commands, editors, selection filters, and Node Specification Language. **What is not covered in this tutorial**: For how to select [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) with the help of **Python Scripting**, please, refer to the [Python Scripting Guide](https://documentation.samson-connect.net/scripting/latest/). ## Selection commands [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides a number of various selection commands that can be found in the **Select menu** or via **Find everything** at the top of the menu. Some selection commands are available via the context toolbar which appears when something is selected. Some selection commands (**Select all** and **Deselect all**) are available in the selection filter menu in the top-right corner of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). Hover above the commands in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) to see more information on them in their tool tips. In general, the selection commands select from the whole [document](https://documentation.samson-connect.net/users/latest/documents/index.md) and not from the current selection. Some of these commands have **special modifiers** that change how they work (see command tool tips): - Press `Ctrl`/`Cmd` and click on the command to **add** to the current selection. - Press `Alt` and click on the command to **remove** from the current selection. - Press `Shift` and click on the command to **intersect** with the current selection. Note Some commands are enabled only if the active document has specific [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) to which they can be applied (structural models, atoms, etc) or only if something is selected (for commands that act on the selection). ## Selecting using the Document View You can select [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) through the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) which shows the hierarchical data graph of the active [document](https://documentation.samson-connect.net/users/latest/documents/index.md). If you do not see the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view), you can enable it via **Interface > Document view** (1). 1. , : `Ctrl`+`1`, : `Cmd`+`1` Open any molecule, e.g. "1YRF - Default structure.sam" from the *Samples* folder. To unfold a level, click on the **+** (); to fold a level, click on **-** (). To select a node, simply click on it in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view). For example, in the image below a residue is selected. To perform more complex selections: - Hold `Ctrl`/`Cmd` and click on a node in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) to add it to the current selection or remove it from the current selection if it already was selected. - Hold `Shift` and click on a node to select nodes consecutively. When selecting nodes, a context toolbar appears with specialized actions. It gives you a quick access to some actions that can be done on selections and to some general actions. At the bottom of the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) you can see the **selection summary** which shows the number of selected nodes, and below it you can see some other statistics. Tip Click on the selection summary or *right-click* on the selection to see context menu and the context toolbar. You can filter [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) by entering in the **Filter nodes...** (1) box a string (filtering by name) or a [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) expression (filtering by properties and other complex expressions). It does not select [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) right away but only filters them. To select [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) matching the filter, press `Enter`. 1. Shortcut: `Shift`+`F` Let's filter lysine (LYS) residues by name, type `LYS` in the **Filter nodes...** (1) box and press `Enter` to select the filtered [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md). 1. Shortcut: `Shift`+`F` You might notice in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view), in the selection summary, or in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) that 15 [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) were actually selected in total, while there are only 5 LYS residues, this is because backbones and side chains of LYS residues were as well selected, since their names also contain "LYS". Filtering by string is based on names of the [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md). For a more precise filtering you can use the [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md). To choose only LYS residues, type the following [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) expression: `residue.type LYS` (or a short version `r.t LYS`). Press `Enter` to select the [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) matching the filter. You should see that only the LYS residues are selected now. Note If you have the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) opened (1), you can see in it some detailed info on the selected [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md). The [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) is a powerful tool with which you can view and edit properties of selected nodes. Please, see [Inspecting](https://documentation.samson-connect.net/users/latest/inspecting/index.md) to learn more about how to work with the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). 1. **Interface > Inspector**, , : `Ctrl`+`2`, : `Cmd`+`2` See [Selecting using the Node Specification Language](#selecting-using-nsl) section to learn more about how to select [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) using [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) expressions. ## Selecting using Editors [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides a **rectangle selection editor** (, shortcut: `R`) to perform selections in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). You can find the selection editor, as all other editors, in the left-side menu in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). Note In SAMSON, there is always an active editor and the selection editor is set as the active editor when you start [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). The rectangle selection editor acts in two modes: - a **point selection** in which it selects when you click on nodes, - a **rectangle selection** in which it selects via a rectangle. To select a [node](https://documentation.samson-connect.net/users/latest/node-types/index.md) in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) via a **point selection**, *left-click* on it in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). To select more than one node, hold `Ctrl`/`Cmd`. To remove a node from the selection, hold `Alt`. To select nodes in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) via a **rectangle selection**, *left-click* and hold in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) and start moving your mouse, you will see the rectangle, once you release the left button the [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) behind the drawn rectangle will be selected. To select more than once, hold `Ctrl`. To unselect using the rectangle selection, hold `Alt`. The rectangle selection can either select or not select nodes hidden behind other nodes. To modify this setting, go to **Interface > Preferences > Editor > Select** and change the **Perform deep selection** option. Note that the deep selection might be significantly slower for big systems. The **selection level** at which the selection editor operates depends on the [selection filter](https://documentation.samson-connect.net/users/latest/selecting/#selection-filters) (more on it in the next section) which you can find in the top-right corner of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). For example, if the selection filter is set to "Residues" then the selection editor will be selecting on the residues level when you click on an atom in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). See [Selection filter](https://documentation.samson-connect.net/users/latest/selecting/#selection-filters) for more information. Tip To center the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) on the selection, press `Shift`+`Space`. ## Selection filters The **selection filter** governs at which [node](https://documentation.samson-connect.net/users/latest/node-types/index.md) level the rectangle selection editor and some other editors operate. The **selection filter** is in the top-right corner of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). By default, the selection filter is set to "Any node". [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides a number of selection filters by default, and you can add your own selection filters (see [Selecting using the Node Specification Language](#selecting-using-nsl)). To the right of the selection filter, you can find some common selection actions: - **Select all**: selects all selectable nodes in the active [document](https://documentation.samson-connect.net/users/latest/documents/index.md) based on the current selection filter. - **Deselect all**: deselects all selected nodes in the active [document](https://documentation.samson-connect.net/users/latest/documents/index.md). Enabled only if the selection is not empty. If the selection filter is set to "Any node", then when you click on the **Select all** button () just next to the selection filter, then it will select all the nodes present in the [document](https://documentation.samson-connect.net/users/latest/documents/index.md). To clear the selection, click on the **Deselect all** button (). If the selection filter is set to "Residues", then the selection editor will be selecting on the residues level when you click on an atom in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). If you click on the **Select all** button (), then it will select all residues present in the [document](https://documentation.samson-connect.net/users/latest/documents/index.md). If the selection filter is set to "Atoms", then when you click on the **Select all** button () it will select all the atoms present in the [document](https://documentation.samson-connect.net/users/latest/documents/index.md). Reset the selection filter to "Any node". ## Selecting using the Node Specification Language You can use the [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) (NSL) for selecting [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) via the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view)'s filter as it was shown in the [Selecting using the Document View](#selecting-using-the-document-view) section, or by using the [Find window](https://documentation.samson-connect.net/users/latest/nsl/index.md) (1). 1. The [Find window](https://documentation.samson-connect.net/users/latest/nsl/index.md) can be opened via **Select > Find** () and `Ctrl`+`F` on Windows and Linux or `Cmd`+`F` on Mac. Tip See the [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) section to learn more. ## Saving selection filters A [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) expression can be saved as a [selection filter](https://documentation.samson-connect.net/users/latest/selecting/#selection-filters). To do so: 1. Open the [Find window](https://documentation.samson-connect.net/users/latest/nsl/index.md) (**Select > Find** , `Ctrl`/`Cmd` + `F`). 1. Type a selection string. 1. Click **Save**. 1. Enter the name for the selection filter - it will be shown in the selection filter list - and click **OK**. Let's save the selection filter which gives us LYS or HIS residues: `r.t LYS or r.t HIS`. Click on the Save button and name it "LYS and HIS residues" then press **OK** or `Enter`. The newly added selection filter should appear at the end of the [selection filter](https://documentation.samson-connect.net/users/latest/selecting/#selection-filters) list. You can remove any custom filter or reset all custom filters. To remove a custom filter, set this filter as the active one and *right-click* on the selection filter list. Note Clicking on the **Reset selection filters** will remove all the selection filters added by you. ## Saving selections as groups In [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), selections can be saved as groups that reference the [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md). This is useful, for example, to have a fast access to some [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) and to perform some actions on selections (e.g., an intersection). Note A group does not contain the [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) it refers to, but only links to them. If you select a group but some of the nodes were deleted, only the still existing nodes will be selected. Open a molecule and select some atoms. Right-click on the selection and click on **Select > Group** (). In the pop-up dialog, provide the group name. The newly created group will be added to the end of the [document](https://documentation.samson-connect.net/users/latest/documents/index.md), and you should see it in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view). You can perform different actions with a group via its context menu. ## Quick Groups **Quick Groups** allow you to rapidly save and switch between multiple selections in a SAMSON document. This feature is especially useful for: - Retrieve and navigate different remembered structural elements. - Designing or analyzing complex molecular structures. - Comparing different parts of a system. - Quickly applying visual models or transformations to specific regions. - Streamline visual modeling, simulation preparation, or educational walkthroughs. Quick Groups complement SAMSON's powerful selection tools by making it easy to recall and navigate between different selections using simple shortcuts. They can be easily accessed from the *Document view* or via numeric shortcuts (`1`, `2`, ...) and allow you to quickly select associated nodes and perform complex selections or other operations. **Quick Groups** are temporary, unnamed groups that appear in the **lower section of the document view**. They allow for extremely fast toggling and zooming between selections. ### Video tutorial You can learn more how to use Quick Groups in your molecular-design workflows from the following extract of the SAMSON 2025 webinar: ### Assigning Quick Groups 1. Make a selection (e.g., atoms, residues). 1. **Assign to a Quick Group**: - **Mouse method**: Hover over a Quick Group slot in the **Document view** and press `Shift` + click. - **Keyboard method**: Press `Shift` + **number** (e.g., `Shift`+`2`) to assign to Quick Group `2`. You can create up to 10 Quick Groups (indexed 1-10). Quick Groups can be **cleared or redefined** at any time, making them ideal for iterative design workflows. ### Switching between Quick Groups Once groups are assigned, you can: - Press `1`, `2`, etc., to **switch selection** to Quick Group `1`, `2`, etc. - Click directly on the Quick Group icons in the **Document view**. - **Double-press a number key** (e.g., 1 1) to zoom to that group's selection. This allows for seamless switching between areas of interest, similar to control groups in real-time strategy games. ### Example workflow with Quick Groups - **Select ligand** and assign to **Quick Group 1**. - **Select receptor** and assign to **Quick Group 2**. - **Select water** molecules and assign to **Quick Group 3**. - Toggle between them using keys `1`, `2`, `3`. - Apply different [visualizations](https://documentation.samson-connect.net/users/latest/visualizing/index.md) to each group. ## Inverting and expanding selections To invert the selection, click **Select > Invert** or *right-click* on the selection either in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) or in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) and, in the context menu, click **Invert selection**. To expand the selection, go to **Select > Expand** or *right-click* on the selection either in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) or in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) and, in the context menu, go to **Expand selection** and choose how to expand the selection. ## Related pages - [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) - [Node types](https://documentation.samson-connect.net/users/latest/node-types/index.md) - [Interface](https://documentation.samson-connect.net/users/latest/interface/index.md) # Inspecting The **Inspector** is a powerful tool which provides a possibility to view and edit the properties (attributes) of the selected [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md), whether it is one node or a group of different nodes. Simply, [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a node and open the Inspector to see what is available. You can open the **Inspector** as follows: - **Interface > Inspector** - Shortcut: `Ctrl`+`2` on Windows and Linux or `Cmd`+`2` on Mac - Via the context toolbar of a selection ## Before you start - Use [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) to learn how to select objects in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). ## Attributes and groups The [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) shows attributes for the selected [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md). Attributes are grouped into corresponding [node type](https://documentation.samson-connect.net/users/latest/node-types/index.md) groups and attribute groups inside of each [node type](https://documentation.samson-connect.net/users/latest/node-types/index.md) group. You may see several [node type](https://documentation.samson-connect.net/users/latest/node-types/index.md) groups (e.g. Atom, Bond, Residue, etc.) in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) depending on what nodes are selected. [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) any atom, and you will see all the attributes of these atoms grouped into attribute groups. Attributes can either be modifiable or not. For example, for an atom, you cannot modify its atomic weight, element name and symbol, since they depend on the element type; however, you can modify the element type, and once you do, all the dependent attributes will be changed accordingly. For some attributes, you can **reset** their value to the default one. For that, hover above the attribute's description and if the cursor changes as in the image below you can double-click on the label to reset this attribute to its default value. Note The [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) shows the attributes' values for the last selected node of this type even if there are several nodes of this type that are selected. For example, if you have several atoms selected, it will show the position of the atom that was selected as the last one. If you modify some attribute values, they will be modified for all the nodes of the same type accordingly. [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) multiple atoms and try to modify the position through the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). You will see that all atoms in the selection change their positions (check that the **Relative** option is on). Note If you want to move a group of atoms without changing the relative positions of atoms inside the group, do not uncheck the **Relative** option. If the **Relative** option is unchecked, the positions for all selected atoms will be modified to the same value. Try it, you can always [undo](https://documentation.samson-connect.net/users/latest/history/index.md) thanks to the [history](https://documentation.samson-connect.net/users/latest/history/index.md) mechanism. ## Filtering attributes You can use the filter to see matching attributes only. Having at least one atom selected, start typing `position` in the filter and you will only see the matching attributes. Now, let's try and change one of the attributes as shown in the image below. When modifying the atom's position you will see how it moves. ## Related pages - [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md): select the nodes whose properties you want to inspect. - [Node types](https://documentation.samson-connect.net/users/latest/node-types/index.md): understand the kinds of nodes whose attributes appear in the Inspector. - [Work with structures](https://documentation.samson-connect.net/users/latest/work-with-structures/index.md): return to the structure-work hub for selection, measurement, and history workflows. # Measuring [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides the **Measure editor** to measure distances, bond lengths, angles, and dihedrals. You can find it in the left-side menu in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) () or invoke it using the `Ctrl`/`Cmd` + `M` shortcut. You can use the **Measure editor** as follows: - Click on a **bond** to toggle displaying its **length**. - Click on **two atoms** to display the **distance** between them. - Click on **three atoms** to display the **angle** between them. - Click on **four atoms** to display the **torsion** between them. To save the displayed data as a [label](https://documentation.samson-connect.net/users/latest/labeling/index.md) in the [document](https://documentation.samson-connect.net/users/latest/documents/index.md), press `Enter`. If a measurement is not saved in the [document](https://documentation.samson-connect.net/users/latest/documents/index.md) as a [label](https://documentation.samson-connect.net/users/latest/labeling/index.md), it acts as a temporary one that will always be shown no matter the zoom level but it will disappear once the next measurement is done - you can have only one temporary measurement, if you want to have more than one, then you need to save it as a [label](https://documentation.samson-connect.net/users/latest/labeling/index.md) by pressing `Enter`. Note If you save your document in one of the SAMSON file formats (.sam or .samx), labels with measurements will be saved as well. If the label was saved in a [document](https://documentation.samson-connect.net/users/latest/documents/index.md), you can access the atoms associated with the measurement by [selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) a label and opening the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). See the Measure group in the image below. The atom-atom distance measurement, if saved as a label, has additional measurements shown in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) for projections on the planes. Other types of available measurements are [labels](https://documentation.samson-connect.net/users/latest/labeling/index.md) for **formal and partial charges of atoms**. They can be added as [labels](https://documentation.samson-connect.net/users/latest/labeling/index.md) via a context toolbar for selected nodes: **Label > Add label to... > Atoms (formal charges)**. ## Updating Measurements are automatically updated (in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md), [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view), and in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector)), when the associated atoms change their positions or charges. So, you can follow the measurements, while using [Move editors](https://documentation.samson-connect.net/users/latest/moving-objects/#move-editors) or [interactive minimization](https://documentation.samson-connect.net/users/latest/minimizing/index.md). ## Appearance **Prerequisites**: Use [Inspecting](https://documentation.samson-connect.net/users/latest/inspecting/index.md) to learn how to inspect nodes in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). Measurements saved as [labels](https://documentation.samson-connect.net/users/latest/labeling/index.md) in the [document](https://documentation.samson-connect.net/users/latest/documents/index.md) act exactly as [labels](https://documentation.samson-connect.net/users/latest/labeling/index.md): their visibility changes depending on the zoom level, and you can change their font, color, and offset. Use [Labeling](https://documentation.samson-connect.net/users/latest/labeling/index.md) to modify labels. For measurement labels you can also modify colors of distance lines and angle planes using the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) (see "Line color", "Angle color", "Planes color"). To reset to the default colors, double-click on the associated text in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) as shown on the image below. To reset the text color, click on **X** () button next to the **Text color** as shown on the image below. You can also specify the font for each label in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). ## Preferences You can specify the font for labels per label directly in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) or for all the labels, for which the font has not been specified directly, in [Preferences > Rendering > Labels](https://documentation.samson-connect.net/users/latest/preferences/#labels) and change it there. There you can also modify the number of decimal places for angles and distances shown in labels which is used for labels created using the **Measure editor**. ## Related pages - [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md): select atoms, residues, molecules, or labels before measuring or editing measurement labels. - [Inspecting](https://documentation.samson-connect.net/users/latest/inspecting/index.md): inspect saved measurement labels and adjust their properties. - [Labeling](https://documentation.samson-connect.net/users/latest/labeling/index.md): format saved labels and measurement annotations. - [Work with structures](https://documentation.samson-connect.net/users/latest/work-with-structures/index.md): return to the structure-work hub. # History: Undo and redo Use this page when you want to undo or redo document operations, inspect the action history, or understand why some operations cannot be reversed. Each [document](https://documentation.samson-connect.net/users/latest/documents/index.md) in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) has its own history - a list of undoable actions done with the [document](https://documentation.samson-connect.net/users/latest/documents/index.md). You can open the [History view](https://documentation.samson-connect.net/users/latest/interface/#history) using **Interface > History** or via the `Ctrl`+`3` shortcut on Windows and Linux or `Cmd`+`3` on Mac. ## What this page covers This page explains how to open the History view, move through previous document states, and use undo and redo while editing, building, or moving structures. You can go through the history - through the states of the [document](https://documentation.samson-connect.net/users/latest/documents/index.md) - by clicking on actions in the [History view](https://documentation.samson-connect.net/users/latest/interface/#history) or by clicking in the **Edit menu** on: - **Undo** (, : `Ctrl`+`Z`, : `Cmd`+`Z`), - **Redo** (, : `Ctrl`+`Y`, : `Cmd`+`Y`). Note Not all the operations are undoable, if in between of undoable operations you did operations which are not undoable it might not be possible for [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) to properly undo operations, which may result in a loss of data. ## Related pages - [Work with structures](https://documentation.samson-connect.net/users/latest/work-with-structures/index.md): return to the structure-work hub. - [Moving objects](https://documentation.samson-connect.net/users/latest/moving-objects/index.md): use history while trying transformations. - [Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md): use undo and redo while constructing or editing structures. # User Guide - Build and edit # Build and edit Use this topic when you want to change structures, not just inspect them. It covers the main editing workflows in SAMSON: repositioning objects, building from atoms or assets, creating repeated arrangements, and relaxing geometry while you work. Follow the full sequence if you are new to editing in SAMSON, or jump to the path that matches your immediate task. ## Who this topic is for - Users repositioning structures or fragments - Users building molecules from scratch or from assets - Users creating repeated nanoscale arrangements - Users refining geometry during construction ## What you will be able to do afterward - Move and align selected structures - Build molecules from atoms or fragments - Create linear, circular, or curved patterns - Minimize a whole molecule or only the part you are editing ## Recommended reading order 1. [Moving objects](https://documentation.samson-connect.net/users/latest/moving-objects/index.md) - Start here to learn the move editors, alignment tools, and basic structure repositioning. `Foundational.` 1. [Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md) - Continue here to construct and modify molecules with atoms, fragments, and the Asset Browser. `Foundational.` 1. [Minimizing](https://documentation.samson-connect.net/users/latest/minimizing/index.md) - Read this once you are editing structures and need to relax geometry during or after changes. `Task-focused.` 1. [Creating patterns](https://documentation.samson-connect.net/users/latest/creating-patterns/index.md) - Use this after the basics when you need repeated linear, circular, or curved arrangements. `Optional / specialized.` ## Read this first Start with [Moving objects](https://documentation.samson-connect.net/users/latest/moving-objects/index.md). If your goal is molecule construction rather than repositioning, continue immediately with [Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md). ## You can skip this for now if... - You only need to reposition or align structures, in which case you can skip [Minimizing](https://documentation.samson-connect.net/users/latest/minimizing/index.md) - You are not duplicating structures or building repeated systems, in which case you can skip [Creating patterns](https://documentation.samson-connect.net/users/latest/creating-patterns/index.md) ## Suggested paths - **Reposition a structure**: [Moving objects](https://documentation.samson-connect.net/users/latest/moving-objects/index.md) - **Build and relax a molecule**: [Moving objects](https://documentation.samson-connect.net/users/latest/moving-objects/index.md) -> [Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md) -> [Minimizing](https://documentation.samson-connect.net/users/latest/minimizing/index.md) - **Replicate a structure**: [Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md) -> [Creating patterns](https://documentation.samson-connect.net/users/latest/creating-patterns/index.md) -> [Minimizing](https://documentation.samson-connect.net/users/latest/minimizing/index.md) ## Where to go next - [Visualize and present](https://documentation.samson-connect.net/users/latest/visualize-and-present/index.md) - Continue here when your next goal is clearer appearance, figures, or movies. - [Simulate and analyze](https://documentation.samson-connect.net/users/latest/simulate-and-analyze/index.md) - Go here when you want to evaluate the system with simulators, paths, or analysis tools. - [Automate and extend](https://documentation.samson-connect.net/users/latest/automate-and-extend/index.md) - Continue here when you want repeatable scripted editing workflows or extra capabilities. # Moving objects Use this page when you need to reposition, align, distribute, or transform structures and other movable nodes in the [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) viewport. In [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), you can move objects via: - [Move editors](#move-editors): [Displacer](#displacer-move-editor), [Local move editor](#local-move-editor), [Global move editor](#global-move-editor) - [Align structures in global reference frame](#aligning-structures-in-the-global-reference-frame) - [Align and distribute structures](#align-and-distribute-structures) - [Python Scripting](https://documentation.samson-connect.net/users/latest/scripting/index.md) Only the following [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) can be moved: - structural nodes that have atoms - certain types of [labels](https://documentation.samson-connect.net/users/latest/labeling/index.md) - [lights](https://documentation.samson-connect.net/users/latest/rendering/#lights) - meshes Other types of nodes either do not have positions in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) (e.g. conformations, files, etc.), or they are automatically moved based on structural nodes on which they depend which is the case for some [visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models). [Interactive tutorial](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md) in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) (**Help > Tutorials**): *"Move objects in the Viewport"*. See also - [Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md): continue here when object motion is part of a construction workflow. ## What this page covers - About the [Move editors](https://documentation.samson-connect.net/users/latest/moving-objects/#move-editors). - [How to move objects using move editors](https://documentation.samson-connect.net/users/latest/moving-objects/#moving-objects-using-move-editors). **What is not covered in this tutorial**: For how to move objects with the help of **Python Scripting**, please, refer to the [Python Scripting Guide](https://documentation.samson-connect.net/scripting/latest/). **Examples of the usage of move editors**: Let's first see some examples of what you can do with [Move editors](https://documentation.samson-connect.net/users/latest/moving-objects/#move-editors) in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). Let's now see how to use [Move editors](https://documentation.samson-connect.net/users/latest/moving-objects/#move-editors) in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). ## Aligning structures in the global reference frame You can align atomic structures with respect to axes or planes of the *global reference XYZ frame*: - right-click on a structure or click on the current selection in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) to invoke its context menu; - in the context menu, go to *Move selection* and choose how you want to align the selection with respect to the global reference frame: - *Center on the origin* - *Align with X axis* - *Align with Y axis* - *Align with Z axis* - *Align with XY plane* - *Align with XZ plane* - *Align with YZ plane* Tip You can switch on the **grid** in the bottom menu of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) to see the global reference frame's XY plane at Z=0. ## Align and distribute structures You can **align and distribute** atomic structures, meshes, and [lights](https://documentation.samson-connect.net/users/latest/rendering/#lights). You can find the corresponding commands in **Edit > Align** and **Edit > Distribute**. You can also align with axes and planes using the **compass actions** - simply right-click on a compass widget to access the related commands for alignment. ## Move editors The **move editors** in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provide precise control over the positions and orientations of molecules. To move - rotate and translate - a selection you can use one of the several move editors provided with [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) by default: - [Displacer](#displacer-move-editor) - a simple move editor to move objects in the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) plane. - [Local move editor](#local-move-editor) - translate and rotate along the principal axes of the selection. - [Global move editor](#global-move-editor) - translate and rotate along the global XYZ axes. You can find these editors in the left-side menu of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). In [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), to move an object (e.g., an atom, a molecule, a mesh, a label, etc) first you need to [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) it (1). 1. Use [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) to learn how to select objects. ### The displacer editor Shortcut: `D` This displacer move editor lets you displace [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) in the plane of the screen (the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) plane). You can either displace currently selected nodes by clicking and dragging, or click on another node and drag it. In the latter case, the selection is based on the current [Selection filter](https://documentation.samson-connect.net/users/latest/selecting/#selection-filters). This editor is particularly useful when performing interactive simulations. You can move object with or without snapping. You can modify the snapping preference in the editor's quick access menu in the top-left corner of the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md), or in the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) (**Interace > Preferences > Editors > Snapping**). ### The local move editor Shortcut: `M` The local move editor allows you to translate and rotate the selected objects along its principal axes: - Use the **central translation widget** (the cross with arrows) to move objects in the plane of the camera. - Use the **side translation widgets** (straight arrows and planes) to move objects along the principal axes of the selected objects. - Use the **side rotation widgets** (curved arrows) to rotate objects around the principal axes of the selected objects. - Use the **trackball** (the sphere) widget to rotate objects freely. The colors of the translation and rotation widgets indicate the principal axes: - light blue: first principal axis (local X axis) - mid blue: second principal axis (local Y axis) - dark blue: third principal axis (local Z axis) You can move object with or without snapping. You can modify the snapping preference in the editor's quick access menu in the top-left corner of the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md), or in the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) (**Interace > Preferences > Editors > Snapping**). You can provide the precise translation and rotation parameters as follows: - *right-click* on the move editor's widgets - press `Ctrl`/`Cmd` and *left-click* on the move editor's widgets You can also align objects along global axes by right-clicking on the move editor's widgets. The **Local Move editor** (`M`) makes it easier to edit **dihedral angles**: click on the half of the bond corresponding to the fragment that you want to rotate, and edit the angle using the widget that appears: ### The global move editor Shortcut: `K` The global move editor allows you to translate and rotate the selected objects along global X, Y, Z axes: - Use the **central translation widget** (the cross with arrows) to move objects in the plane of the camera. - Use the **side translation widgets** (straight arrows and planes) to move objects along the axes of the global reference frame (X, Y, and Z). - Use the **side rotation widgets** (curved arrows) to rotation objects along the axes of the global reference frame (X, Y, and Z). - Use the **trackball widget** (the sphere) to rotate objects freely. The colors of the translation and rotation widgets indicate the global axes: - red: X axis - green: Y axis - blue: Z axis You can move object with or without snapping. You can modify the snapping preference in the editor's quick access menu in the top-left corner of the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md), or in the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) (**Interace > Preferences > Editors > Snapping**). You can provide the precise translation and rotation parameters as follows: - *right-click* on the move editor's widgets - press `Ctrl`/`Cmd` and *left-click* on the move editor's widgets You can also align objects along global axes by right-clicking on the move editor's widgets. ## Moving objects using move editors In this section, you will learn how to use [move editors](#move-editors) on an example of the [local move editor](#local-move-editor) (shortcut: `M`). The local move editor allows for translating and rotating based on the principal axes of the selection and using the trackball. **Prerequisites**: Use [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) to learn how to select objects in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). Load a molecule from a file or from assets (1). [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a part of the molecule - use the [rectangle selection editor](https://documentation.samson-connect.net/users/latest/selecting/#selecting-using-editors) (2) to select a group of atoms. 1. See the [Building with available assets](https://documentation.samson-connect.net/users/latest/building-molecules/#building-with-available-assets) section. 1. Shortcut: `R` To move the selected atoms in the camera plane: 1. Press with the left mouse button on the **central translation widget** (the cross with arrows). 1. While pressing, move the mouse to translate in the desired direction. The editor should display the positional shift. If you would like to cancel, just click `Esc`, and the position will be restored. 1. Release the mouse to apply the displacement. Note The move operations are [undoable](https://documentation.samson-connect.net/users/latest/history/index.md), so you can always undo them by clicking **Edit > Undo** (1). 1. , : `Ctrl`+`Z`, : `Cmd`+`Z` You can enable translational snapping in the top-left corner of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) to snap the translation to this value. Set the translational snapping to e.g. 0.5Å, and translate the selection. To rotate around an axis: 1. Press with the left mouse button on a **side rotation widget** (a curved arrow). 1. While pressing, move the mouse to rotate the selection in the desired direction. The editor should display the positional shift. If you would like to cancel, just click `Esc`, and the position will be restored. 1. Release the mouse to apply the displacement. You can enable rotational snapping in the top-left corner of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) to snap the rotation to this value. Set the rotational snapping to e.g. 10°, and rotate the selection. To rotate using the trackball (on a sphere): 1. Press with the left mouse button on the **trackball** (the sphere). 1. While pressing, move the mouse to rotate in the desired direction. The editor should display the positional shift. If you would like to cancel, just click `Esc`, and the position will be restored. 1. Release the mouse to apply the displacement. ## Moving objects with snapping As mentioned above, you can move objects with *snapping*. You can modify the snapping preference in the editor's quick access menu in the top-left corner of the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md), or in the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) (**Interace > Preferences > Editors > Snapping**). In the video below, we copy the main structure and position its copies around it using the [Global Move Editor](#global-move-editor) (shortcut `K`) by specifying the *pivot* (the rotational center) atom and rotational snapping. ## Related pages - [Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md) - [Creating patterns](https://documentation.samson-connect.net/users/latest/creating-patterns/index.md) # Building molecules Use this page when you want to construct or modify molecular systems in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) with atoms, fragments, assets, editors, and hierarchy tools. Here are the various [editors](https://documentation.samson-connect.net/users/latest/editors/index.md) and [apps](https://documentation.samson-connect.net/users/latest/apps/index.md) that can be used for building molecular structures: - [Add editor and assets](#quick-look-on-builder-features) - [Create molecules in 2D with Interaction Designer](https://documentation.samson-connect.net/users/latest/interaction-designer/#create-new-molecules-in-2d) - [Python Scripting](https://documentation.samson-connect.net/users/latest/scripting/index.md) - [Twister editor](https://www.samson-connect.net/extensions/8b38b2fd-de8d-f24a-36e7-7ac624173f9f) - [Graphene Sheet Creator](https://www.samson-connect.net/extensions/ff9be415-c812-1c1a-cdbe-78896176b067) - [Nanotube Creator](https://www.samson-connect.net/extensions/1ebd1e1c-2f89-62bd-02c2-08216dcbd60b) - [Pattern builders](https://documentation.samson-connect.net/users/latest/creating-patterns/index.md) - [Rotamers editor](https://www.samson-connect.net/extensions/7cc74ea8-c24b-78fa-49a6-a75562902a12) - [Symmetry Mate editor](https://www.samson-connect.net/extensions/d5c311da-ad75-2934-8845-79b38b289ff8) - [Molecular Box Builder](https://www.samson-connect.net/extensions/3d8237a4-d3a0-942b-a6b0-9baa049cb195) - etc. [Interactive tutorial](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md) in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) (**Help > Tutorials**): *"Building with atoms"*. ## What this page covers This page explains how to build molecules from atoms and fragments, orient them, and adjust their hierarchy as part of a construction workflow in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). ## What you will be able to do afterward - Build molecules using atoms and assets, from [constructing a simple fragment from atoms](#building-with-atoms) to [constructing a molecule from several assets](#building-with-fragments). - Adjust [builder options](#preferences). - [Orient molecule fragments](#orienting-molecule-fragments). - [Modify hierarchical structures](#modifying-hierarchical-structure). ## Before you start - Use [Moving around](https://documentation.samson-connect.net/users/latest/moving-around/index.md) first if you are not comfortable rotating, panning, zooming, or switching editors. - Use [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) first if the building operation should apply only to part of a document. - Use the [Python Scripting Guide](https://documentation.samson-connect.net/scripting/latest/) when you want to build objects with Python scripts. Let's first take a quick look at the main builder features. ## Quick look on builder features Let's take a quick look at the main builder features in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). Building combined with [interactive minimization](https://documentation.samson-connect.net/users/latest/minimizing/index.md): [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) lets you build using individual atoms from the [Asset Browser](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser) (with quick access to H, C, N, O atoms at the bottom of the [Asset Browser](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser))... or using the [Periodic table](https://documentation.samson-connect.net/users/latest/interface/#periodic-table)... or by assembling assets. **Assets** can be anything: atoms, functional groups, rings, fragments, radicals, whole molecules, proteins, nanoparticles, 2D materials, etc. You can assemble them in the [document](https://documentation.samson-connect.net/users/latest/documents/index.md) to rapidly set up complex models for analysis and simulation. Whether you're constructing with individual atoms or with assets, the builder has several cool features to assist you, as shown above, in particular, it has options to: - **predict fragments orientations**; - **prevent implausible substitutions**: acceptable substitutions or additions have a green overlay, while forbidden ones have a red overlay; - automatically **adjust hydrogens**; - **merge overlapping atoms**. You can control in the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) whether you want to follow these recommendations or override them (see [Structural model preferences](https://documentation.samson-connect.net/users/latest/building-molecules/#preferences)). By pressing and holding the `Shift` key, you can choose which atom and bond in the asset are used to replace the atoms and bonds you click in the document: ### Asset Browser The **Asset Browser** (1) provides access to the assets (molecule fragments, etc.) included by default in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) together with the assets you can obtain from [SAMSON Connect](https://www.samson-connect.net/). 1. **Interface > Assets**, , : `Ctrl`+`4`, : `Cmd`+`4` Try going through various folders in the **Asset Browser** to see what is available. To search for available assets, use the **Filter assets...** at the top of the [Asset Browser](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser). To search for available assets, use the **Filter assets...** at the top of the [Asset Browser](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser). To change the size of images and text in the [Asset Browser](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser), you can zoom in / zoom out using `Ctrl` and *mouse wheel* or use commands with the magnifying glass with **+** and **-** icons. To switch between the grid and the list view, use the right-most buttons (, ) at the bottom of the [Asset Browser](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser). If you would like to make your library of fragments/molecules available in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), [contact us](mailto:contact@samson-connect.net). ## Prerequisites Before going through this tutorial, we recommend going through the [interactive tutorials](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md) (1) integrated into [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) that will guide you through the basic operations. Specifically, we recommend going through the following interactive tutorials: 1. **Help > Tutorials** - "Working with documents" - "Selecting in the Viewport" - "Building with atoms" - "Moving objects in the Viewport" You can also check the following sections of the User Guide: - [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) - [Moving around](https://documentation.samson-connect.net/users/latest/moving-around/index.md) - [Moving objects](https://documentation.samson-connect.net/users/latest/moving-objects/index.md) In this section, we will partly cover what is covered in the "Building with atoms" [interactive tutorial](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md) as well. ## Preferences Building in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) is done using the **Add editor** which has various options that can be checked in **Preferences > Editors > Add**. Go to [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) (**Interface > Preferences**) and there in the **Editors > Add** section, and make sure that the **Adjust hydrogens when adding fragments...** option is checked. **Adjust hydrogens when adding fragments...** - if this option is checked, then hydrogens will be adjusted automatically (as best as possible) when adding atoms/fragments, linking atoms/fragments, editing bond order, and changing atom formal charge based on valences. **Automatically orient fragments on substitution** - if this option is checked, then when trying to connect a fragment to an existing molecule it will be positioned (as best as possible) such that its atoms won't overlap with the molecule's atoms. **Merge neighboring atoms** - if this option is checked, then when trying to connect a fragment to an existing molecule and some fragment atoms appear to be close enough to the molecule's atoms then they will be merged together as well as the substitution atom. **Prevent unexpected substitutions** - if this option is checked, then it prevents implausible substitutions: acceptable substitutions or additions have a green overlay, while forbidden ones have a red overlay **Select fragments after adding them** - if checked, selects the just added fragment. **Randomize orientations** - if checked, randomizes orientation of fragments placed separately. For example, when adding water or methane molecules this will randomize molecule's orientation. **Create new structural models when adding non-covalent fragments** - if checked, a new structural model will be created for each added fragment that is not covalently linked to any other molecule in the [document](https://documentation.samson-connect.net/users/latest/documents/index.md). ## Building with atoms Before proceeding, please check the [Preferences](https://documentation.samson-connect.net/users/latest/building-molecules/#preferences) section and make sure that options are checked as shown there. ### Constructing a molecule from atoms Let's start by constructing a simple N-acetyl group. The building in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) is done thanks to the **Add editor** (1). With the **Add editor**, you can build with atoms and available assets (fragments, etc.). When you activate the **Add editor**, you should see the current active fragment in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md), and it will also open the [Asset Browser](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser) with all the available assets. You have quick access to some common atoms, rings, the [Periodic table](https://documentation.samson-connect.net/users/latest/interface/#periodic-table) with all atoms in the [Asset Browser](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser). 1. Shortcut: `A`, the left-side menu in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) In the top-left corner of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md), you should see the **Snapping** options (translational and angular displacement snapping) - they might influence how the fragments are added and positioned. **Snapping** can be useful, for example, when you need to place fragments on a grid with a specific distance between them. Just set both of them to **Off** for the sake of this tutorial. Let's start by adding a Carbon atom: click on **C** () in the [Asset Browser](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser) and click anywhere in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). With the **Adjust hydrogens...** option checked (see [Preferences](https://documentation.samson-connect.net/users/latest/building-molecules/#preferences)) it should automatically add the necessary hydrogens. So, in this case, it should become CH4. Let's now connect another Carbon to it. There are two main modes to connect atoms/fragments: **1. Substitute an atom**: hover above the atom that you want to substitute and click on it. Note When adding by substitution an atom or a fragment, [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) tries to position the newly added atom or fragment with taking into account covalent radii of atoms. You can see it on the gif below. **2. Create a bond between atoms**: hover above the atom to which you would like to attach the fragment, press on the atom, and hold, then move your mouse away and release it once it is at a sufficient (bond-like) distance. Try these modes to add another Carbon. Note The **Add editor** (`A`) automatically chooses where atoms and bonds are located in a structure hierarchy. For example, when adding atoms to a side chain, the added atoms are placed in the same side chain. Note You can always [undo](https://documentation.samson-connect.net/users/latest/history/index.md) commands by clicking **Edit > Undo** (1) and [redo](https://documentation.samson-connect.net/users/latest/history/index.md) by clicking **Edit > Redo** (2). 1. , : `Ctrl`+`Z`, : `Cmd`+`Z` 1. , : `Ctrl`+`Y`, : `Cmd`+`Y` When building, you can always switch on [interactive minimization](https://documentation.samson-connect.net/users/latest/minimizing/index.md) in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) (shortcut: `Z`, **Edit > Minimize**). You can build fragments and connect them while the interactive minimization is running. Now switch on [interactive minimization](https://documentation.samson-connect.net/users/latest/minimizing/index.md) by pressing `Z`. This should minimize the system. To switch it off, press `Z` once more. Let's now add Nitrogen and Oxygen atoms. When the [interactive minimization](https://documentation.samson-connect.net/users/latest/minimizing/index.md), you can see how the molecule is minimized while you build it. Note If you need to use other atom types, click on the [Periodic table](https://documentation.samson-connect.net/users/latest/interface/#periodic-table) (1) and choose an atom from there simply by clicking on it. 1. , : `Ctrl`+`5`, : `Cmd`+`5`, **Interface > Periodic table**, or in the [Asset Browser](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser) We are almost done, now we just need to change the bond order between the oxygen atom and a carbon atom bonded to it. ### Changing bond order You can easily modify interactively the bond order using the **Edit bonds** editor (shortcut: `B`, the left-side menu in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md)). Click on this editor to activate it and hover above the bond that you would like to modify. Click on **-** or **+** to change the bond order. As you can see, the N-C bond order also changed (to about 1.4) due to the use of the Universal Force Field in the [interactive minimizer](https://documentation.samson-connect.net/users/latest/minimizing/index.md). Note Depending on the file format in which you chose to save, it might be saved as a single bond. See the below how to modify the bond order using the Inspector. You can also modify the bond order and bond type by [selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) the bond and going to the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) (1). But note that in this case, hydrogens will not be adjusted automatically. 1. **Interface > Inspector**, , : `Ctrl`+`2`, : `Cmd`+`2` ### Changing atom formal charge If you want to modify formal charges of atoms, you can use the **Edit charges** editor (shortcut: `C`, the left-side menu in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md)). Click on this editor to activate it and hover above an atom for which you would like to modify the formal charge and click on **-** or **+** to change it. ## Building with fragments Before proceeding, please check the [Preferences](https://documentation.samson-connect.net/users/latest/building-molecules/#preferences) section and make sure that options are checked as shown there. To build from fragments you can use: - available assets from the [Asset Browser](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser) - molecules or fragments of molecules from the [document](https://documentation.samson-connect.net/users/latest/documents/index.md). ### Using constructed fragments for building You can use a molecule or a fragment of a molecule for building: 1. Activate the **Add editor** or the **Select editor** . 1. [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) (in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) or in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) using the [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) editor) a fragment that you would like to use. 1. *Right-click* on it and in the context menu to choose **Use selection to build**: This should create a building fragment from the current selection. If you want to **modify the substitution atom**, press `Ctrl`/`Cmd` and choose the substitution atom in the fragment as shown in the gif below. Note In case of acceptable operations the fragment has a green overlay, while forbidden ones have a red overlay. You can control in the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) whether you want to follow these recommendations or override them (option: **Prevent unexpected substitutions**). ### Building with available assets [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides a set of various assets by default. You can find all the available assets in the [Asset Browser](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser) (1). 1. **Interface > Assets**, , : `Ctrl`+`4`, : `Cmd`+`4` To search for available assets, use the **Filter assets...** at the top of the [Asset Browser](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser). To change the size of images and text in the [Asset Browser](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser), you can zoom in / zoom out using `Ctrl` + *mouse wheel* or use commands with the magnifying glass with **+** and **-** icons. To switch between the grid and the list view, use the right-most buttons (, ) at the bottom of the [Asset Browser](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser). For the sake of tutorial, let's combine phenol molecules. Open the [Asset Browser](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser) (1), go to the **Aromatics** folder, and double-click on the **phenol** asset. This should activate the **Add editor** if it has not been active. 1. **Interface > Assets**, , : `Ctrl`+`4`, : `Cmd`+`4` Note If you have the **Add editor** set as the active editor then you should see the chosen fragment shown right away in the center of the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). If the **Add editor** is not the active editor, then simply double-click on the asset to activate the **Add editor** with this asset set as the current fragment. First, we need to add the phenol molecule - click anywhere in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). Then try adding phenol fragments to it using bond connections or by substituting atoms. Note You can change the substitution atom (or bond) in the fragment by holding the `Ctrl`/`Cmd` key and choosing the atom or bond in the fragment. Note You can always apply [interactive minimization](https://documentation.samson-connect.net/users/latest/minimizing/index.md) (as done at the end in the example above) by pressing `Z` (or via **Edit > Minimize**). To stop the interactive minimization, press `Z` once again. Let's now try to construct Bisphenol A (BPA) as follows (see the gif below): 1. Use carbon atom to construct a propane molecule (C3H8). 1. Change the current fragment to **phenol**. For that, in the [Asset Browser](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser), go to the **Aromatics** folder and click on the **phenol** asset (you should see the a#ctive fragment in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md)). 1. Change the substitution atom in the **phenol** fragment. For that, press the `Ctrl`/`Cmd` key and choose the carbon atom as shown in the gif below. 1. Substitute 2 hydrogens of the central carbon atom in the propane molecule by phenol fragments. For that, move your mouse to position the fragment onto hydrogen atoms of the central carbon atom in propane. You should see how the fragment is being automatically reoriented. Press the *left -click* to substitute an atom with the substitution atom of the current fragment. 1. Apply [interactive minimization](https://documentation.samson-connect.net/users/latest/minimizing/index.md) by pressing `Z` (or via **Edit > Minimize**). To stop the interactive minimization, press `Z` once again. Note You can always rotate the fragment by holding `Shift` + *right-click*. If you would like to see atom names when hovering above them, as in the gif above, switch on the **Node details** option in the menu at the bottom of the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). You can also add [labels](https://documentation.samson-connect.net/users/latest/labeling/index.md) to atoms, molecules, and other nodes, using the **Label editor** (1) or via the context toolbar. Use [Labeling](https://documentation.samson-connect.net/users/latest/labeling/index.md) for label-specific controls. 1. , : `Ctrl`+`L`, : `Cmd`+`L` ## Orienting molecule fragments If you would like to change the orientation of the added fragment you can easily do it using [Move editors](https://documentation.samson-connect.net/users/latest/moving-objects/index.md). If you have just added a fragment to a molecule then it will be selected automatically, else you can [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a part of a molecule in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) or in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). Note Multiple different [Move editors](https://documentation.samson-connect.net/users/latest/moving-objects/index.md) are available in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). You can check them in the left-side menu in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md), and you can learn more about their differences in the [Moving objects](https://documentation.samson-connect.net/users/latest/moving-objects/index.md) section. Click `M` to activate the [Local Move Editor](https://documentation.samson-connect.net/users/latest/moving-objects/#local-move-editor). You can change the *pivot for the rotation*. For that, zoom in so that the atom you would like to set as the pivot is not hidden by the Move editor's controls, as shown in the gif below, and click on the atom to set it as the pivot, as shown in the gif below. Now you can use the [move editor](https://documentation.samson-connect.net/users/latest/moving-objects/#move-editors)'s controls to rotate the chosen fragment - press and hold anywhere on the controller's sphere and move the mouse to rotate using the trackball sphere. You can also use the arrow controllers to rotate around a principal axis of the fragment. In the video below, we copy the main structure and position its copies around it using the [Global Move Editor](https://documentation.samson-connect.net/users/latest/moving-objects/#global-move-editor) (shortcut `K`) by specifying the *pivot* (the rotational center) atom and rotational snapping. To *rotate a molecular fragment around a bond*, use the [Local Move Editor](https://documentation.samson-connect.net/users/latest/moving-objects/#local-move-editor) (shortcut `M`) and just click on the bond. The editor will automatically select the shortest fragment and will show the move widgets. See the video below: Tip You can learn more on how to move fragments of molecules and whole molecules please in the [Moving objects](https://documentation.samson-connect.net/users/latest/moving-objects/index.md) section and in the *"Move objects in the Viewport"* [interactive tutorial](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md) (1) in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). 1. **Help > Tutorials** Tip See also [Align and distribute structures](https://documentation.samson-connect.net/users/latest/moving-objects/#align-and-distribute-structures). ## Modifying hierarchical structure After you have built a molecule you might want to modify the hierarchical structure of the molecule or the [document](https://documentation.samson-connect.net/users/latest/documents/index.md). You can do it easily in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view). [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) lets you make various changes to the [document](https://documentation.samson-connect.net/users/latest/documents/index.md) hierarchy: - add new nodes (structural model, chain, molecule, segment, structural group, etc), - move nodes using drag-and-drop, - extract nodes. You can also modify node properties using the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). Use [Inspecting](https://documentation.samson-connect.net/users/latest/inspecting/index.md) for the Inspector workflow. To add a new node to some parent node, *right-click* on the parent node in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) and, in the context menu, go to **Add > Structural node** and choose a node by its type. To move nodes using the drag-and-drop mechanism, [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) nodes and drag them to a node where you would like to place them. [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) will automatically checks the validity of the drag-and-drop operation based on the node hierarchy. To extract nodes, *right-click* on them and choose **Extract structure** from the context menu. See also the *"Documents: drag-and-drop, history"* [interactive tutorial](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md) (1) in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). 1. **Help > Tutorials** ## Related pages - [Moving objects](https://documentation.samson-connect.net/users/latest/moving-objects/index.md): reposition, align, distribute, and transform structures. - [Creating patterns](https://documentation.samson-connect.net/users/latest/creating-patterns/index.md): create repeated linear, circular, or curve-based arrangements. - [Minimizing](https://documentation.samson-connect.net/users/latest/minimizing/index.md): relax geometry while or after building. - [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md): open or fetch starting structures before editing. # Creating patterns [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides a number of powerful ways to [build and modify molecular systems](https://documentation.samson-connect.net/users/latest/building-molecules/index.md) thanks to various [editors](https://documentation.samson-connect.net/users/latest/editors/index.md) and [apps](https://documentation.samson-connect.net/users/latest/apps/index.md). Among them are the three [pattern building editors](https://www.samson-connect.net/extensions/8d2e17bf-c8f4-2118-d9df-4143eef7023e) that let you rapidly replicate and arrange molecular structures in linear, circular, or curved patterns: - **Linear pattern editor** (shortcut: `L`) - **Circular pattern editor** (shortcut: `W`) - **Curved pattern editor** (shortcut: `Q`) Pattern builders enable fast construction of complex nanoscale architectures and is useful across domains like: - Nanotechnology (e.g., nanotubes, nanomachines). - Biomolecular modeling. - Material science. Pattern creation supports designing systems with hundreds of thousands of atoms in a few steps, using intuitive and precise controls. ## What this page covers This page explains how to build linear, circular, and curve-based patterns so you can assemble larger systems efficiently in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). ## Quick look on pattern creation features > The three new editors in the upcoming release of SAMSON (Linear pattern, Curved pattern and Circular pattern) make it possible to build complex molecular shapes in just a few clicks. We're excited to see what people will build with it! CC [@mooreth42](https://twitter.com/mooreth42?ref_src=twsrc%5Etfw) [@mechadense](https://twitter.com/mechadense?ref_src=twsrc%5Etfw) [@somewhereville](https://twitter.com/somewhereville?ref_src=twsrc%5Etfw) [pic.twitter.com/N4aoBPpK6t](https://t.co/N4aoBPpK6t) > > — Stephane Redon (@StephaneRedon) [March 11, 2025](https://twitter.com/StephaneRedon/status/1899495914496028729?ref_src=twsrc%5Etfw) ## Video tutorial You can learn how to use Pattern Buildes from the following extract of the SAMSON 2025 webinar: ## Tips and resources We recommend going through the following [interactive tutorials](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md) (1) integrated into [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) that will guide you through the basic operations: 1. **Help > Tutorials** - "Working with documents" - "Selecting in the Viewport" - "Building with atoms" - "Moving objects in the Viewport" You can also check the following sections of the User Guide: - [**Selecting**](https://documentation.samson-connect.net/users/latest/selecting/index.md) ______________________________________________________________________ Learn how to perform selections in SAMSON using commands, filters, editors, scripting, or directly in the document view. - [**Moving around**](https://documentation.samson-connect.net/users/latest/moving-around/index.md) ______________________________________________________________________ Learn how to move around in SAMSON's viewport using mouse or keyboard. - [**Moving objects**](https://documentation.samson-connect.net/users/latest/moving-objects/index.md) ______________________________________________________________________ Learn how to move objects in SAMSON using various move editors. - [**Building molecules**](https://documentation.samson-connect.net/users/latest/building-molecules/index.md) ______________________________________________________________________ Learn how to build and modify molecular systems using various tools in SAMSON: editors, assets, etc. ## Available Pattern editors You can access **Pattern editors** via the **Editors Toolbar** (left of the viewport) or via the **Find everything...** bar at the top. - **Linear pattern editor** (shortcut: `L`) - **Circular pattern editor** (shortcut: `W`) - **Curved pattern editor** (shortcut: `Q`) Each editor provides an interactive widget to position, rotate, and duplicate structures with live visual feedback. ## Basic usage steps 1. [Create](https://documentation.samson-connect.net/users/latest/building-molecules/index.md) or [load](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md) an atomic structure, then [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) the structure to duplicate (atoms, molecules, rings, etc.). 1. **Activate a Pattern Editor** (Linear, Circular, or Curved). 1. **Position and rotate** the duplicated structures using on-screen widgets: - **Drag handles** for interactive transformation. - Hold `Ctrl` (Windows/Linux) or `Cmd` (macOS) and click widgets to enter **precise values** for translations and rotations. - Set **snapping** to control translation distances and rotation angles. 1. **Adjust the number of copies**: - Scroll the mouse wheel while hovering over the central widget. - Use `Ctrl` / `Cmd` + scroll to change copy count more quickly. 1. Click **Accept** () to finalize the pattern. ## Advanced controls and preferences You can fine-tune pattern behavior in **Preferences > Edit > Create pattern (circular / curved / linear)**: - **Automatically merge nearby atoms**. - **Adjust hydrogens atoms**. - Choose whether to group or **combine generated structures** with existing ones. Use **Edit > Align / Distribute** for further structure organization (see [Align and distribute structures](https://documentation.samson-connect.net/users/latest/moving-objects/#align-and-distribute-structures)): - **Align** by origin, axis, or compass planes. - **Distribute** structures evenly across chosen directions. ## Example: Creating a linear pattern 1. Build a small molecule and minimize it. 1. Select it and activate the **Linear Pattern Editor** (`L`). 1. Adjust spacing and rotation between replicas. 1. For precise alignment, click the center of the widget: - Set X/Y/Z translations (e.g., 2 Å on Z-axis). - Set incremental rotation between copies (e.g., 0°). 1. Accept () the result to build your extended structure. ## Example: Constructing a nanotube manually SAMSON includes a **Carbon Nanotube Editor** that can be accessed via the **Editors Toolbar** (left of the viewport) or via the **Find everything...** bar at the top. In the [video tutorial](#video-tutorial), we show how to create a Carbon Nanotube (CNT) using the Pattern Builders. You can follow it with these steps: 1. **[Create](https://documentation.samson-connect.net/users/latest/building-molecules/index.md) a ring**, remove hydrogen atoms, and [rotate](https://documentation.samson-connect.net/users/latest/moving-objects/index.md) to align edges. 1. Activate the **Circular Pattern Editor** (`W`): - Increase the number of instances (e.g., 12) to form a closed ring. - Adjust the radius to align edges for bonding. - Accept () to merge overlapping atoms into a single ring. 1. Align the ring (e.g., to the XY plane) using **Edit > Align** (see [Align and distribute structures](https://documentation.samson-connect.net/users/latest/moving-objects/#align-and-distribute-structures)). 1. Apply the **Linear Pattern Builder** (`L`) to stack rings into a tube: - Translate along the Z-axis (e.g., 2 Å). - Incrementally rotate each replica if needed to match bonds. - Accept () to create a tube structure. 1. [Minimize](https://documentation.samson-connect.net/users/latest/minimizing/index.md) to relax the geometry and optionally add hydrogens. ## Related pages - [Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md) - [Moving objects](https://documentation.samson-connect.net/users/latest/moving-objects/index.md) - [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) # Minimizing You can minimize your structures interactively in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). To start and stop the minimization click **Edit > Minimize** (shortcut: `Z`). The interactive minimization uses the [Universal Force Field (UFF)](https://www.samson-connect.net/extensions/8cbdc8b1-59e1-6459-d68f-b840275dd5e9). During the minimization you can: - Use [Move editors](https://documentation.samson-connect.net/users/latest/moving-objects/#move-editors) to move nodes. - Use [Add editor](https://documentation.samson-connect.net/users/latest/building-molecules/index.md) to add atoms or assets. ## Before you start Use [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) first if you want to minimize only one molecule or one part of a molecule. Use [Modeling and Simulation](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md) instead when you need a full simulator workflow with a chosen force field and state updater. You can modify the interactive minimizer options in the **Minimize** section in the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) panel. By default, the minimizer minimizes all the molecules in the active document. ## Minimizing a single molecule in a document If you would like to minimize only a single molecule (a single connected component) in a document without minimizing other molecules in the system, then: 1. Uncheck the **Include all atoms in the document** option in **Interface > Preferences > Editors > Minimize** 1. [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a molecule that you would like to minimize. 1. Click **Edit > Minimize** (1). 1. Shortcut: `Z` Note When minimizing a selection only, the minimizer takes into account the whole connected component of the current selection. For example, if you choose a single atom in a molecule, the minimizer considers the whole molecule connected to this atom and minimizes this whole connected component. To minimize only part of a molecule, use [Minimizing a part of a molecule](#minimizing-a-part-of-a-molecule). ## Minimizing a part of a molecule You can minimize only a part of a molecule (a part of a connected component) by *freezing* the rest of the molecule: 1. [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) the whole molecule or keep the selection empty. 1. Click **Edit > Freeze** (1) to freeze (fix) atoms in the selection or in the whole document if the selection is empty. 1. [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) the part of the molecule that you would like to minimize. 1. Click **Edit > Unfreeze** (2) to unfreeze only atoms in the selection. 1. Click **Edit > Minimize** (3) to start the interactive minimization. 1. ... 1. Click **Edit > Minimize** to stop the interactive minimization. 1. Unfreeze the whole system by clicking **Edit > Unfreeze** with the molecule selected or nothing selected. 1. Shortcut: `F` 1. Shortcut: `U` 1. Shortcut: `Z` The frozen (fixed) atoms are not minimized and their positions stay fixed. Note Frozen atoms have a dark blue overlay in the viewport. See the video below with an example of the minimization with frozen atoms. ## Minimizing using simulators You can also minimize structures using [simulators](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md) by choosing a force field and a state updater. Below is the video of a quick molecular geometry optimization using [FIRE state updater](https://www.samson-connect.net/extensions/8ec255b0-7326-0bed-366e-40be71c1d160): when this carbon nanotube is sliced, it quickly relaxes to a mostly flat graphene sheet. ## Related pages - [Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md): continue here when minimization is part of an editing workflow. - [Moving objects](https://documentation.samson-connect.net/users/latest/moving-objects/index.md): move selected structures while the interactive minimizer is running. - [Modeling and Simulation](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md): use simulator-based minimization and simulation workflows. - [Build and edit](https://documentation.samson-connect.net/users/latest/build-and-edit/index.md): return to the editing hub. # User Guide - Visualize and present # Visualize and present Use this topic when you want structures to be clearer, more informative, or ready for output. It covers the path from everyday viewport setup to polished figures and animations: visual models, color, rendering style, labels, high-quality rendering, and presentations. Follow the full sequence if you are new to SAMSON visualization, or choose the path that matches your output goal. ## Who this topic is for - Users improving clarity in the viewport - Users preparing figures or images - Users adding labels or annotations - Users creating animations or movies ## What you will be able to do afterward - Apply visual presets and models - Colorize structures meaningfully - Tune viewport rendering - Add and style labels - Render final images - Build and export presentations or movies ## Recommended reading order 1. [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) - Start here for the main visualization workflow and the fastest ways to improve what you see. `Foundational.` 1. [Colorizing](https://documentation.samson-connect.net/users/latest/colorizing/index.md) - Continue here to apply meaningful color schemes and palettes to structural and visual models. `Foundational.` 1. [Rendering effects](https://documentation.samson-connect.net/users/latest/rendering-effects/index.md) - Read this next to tune the real-time viewport with lighting, fog, clipping, silhouettes, and related effects. `Foundational.` 1. [Labeling](https://documentation.samson-connect.net/users/latest/labeling/index.md) - Use this when you need text annotations or saved measurements to stay readable in the viewport. `Optional / task-focused.` 1. [Rendering using Cycles](https://documentation.samson-connect.net/users/latest/rendering/index.md) - Continue here when you are preparing a final-quality still image or rendered movie. `Advanced / output-focused.` 1. [Presenting and animating](https://documentation.samson-connect.net/users/latest/presenting/index.md) - Read this when your goal is a timeline-based presentation, animation, or movie export. `Advanced / output-focused.` ## Read this first Start with [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md). ## You can skip this for now if... - You do not need annotations, in which case you can skip [Labeling](https://documentation.samson-connect.net/users/latest/labeling/index.md) - Real-time viewport quality is enough, in which case you can skip [Rendering using Cycles](https://documentation.samson-connect.net/users/latest/rendering/index.md) - You are not making movies or slide-like presentations, in which case you can skip [Presenting and animating](https://documentation.samson-connect.net/users/latest/presenting/index.md) ## Suggested paths - **Improve the everyday viewport**: [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) -> [Colorizing](https://documentation.samson-connect.net/users/latest/colorizing/index.md) -> [Rendering effects](https://documentation.samson-connect.net/users/latest/rendering-effects/index.md) - **Create a polished still image**: [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) -> [Colorizing](https://documentation.samson-connect.net/users/latest/colorizing/index.md) -> [Rendering effects](https://documentation.samson-connect.net/users/latest/rendering-effects/index.md) -> [Rendering using Cycles](https://documentation.samson-connect.net/users/latest/rendering/index.md) - **Create a movie or presentation**: [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) -> [Colorizing](https://documentation.samson-connect.net/users/latest/colorizing/index.md) -> [Presenting and animating](https://documentation.samson-connect.net/users/latest/presenting/index.md) -> [Rendering using Cycles](https://documentation.samson-connect.net/users/latest/rendering/index.md) ## Where to go next - [Simulate and analyze](https://documentation.samson-connect.net/users/latest/simulate-and-analyze/index.md) - Continue here when your visual work is driven by modeling results, trajectories, or analysis. - [Share and collaborate](https://documentation.samson-connect.net/users/latest/share-and-collaborate/index.md) - Go here when you need to share documents, jobs, or outputs with other users. - [Reference and help](https://documentation.samson-connect.net/users/latest/reference-and-help/index.md) - Continue here for deeper references, including animation families and troubleshooting paths. ## Notes [Rendering using Cycles](https://documentation.samson-connect.net/users/latest/rendering/index.md) is for final-quality output, while [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) and [Rendering effects](https://documentation.samson-connect.net/users/latest/rendering-effects/index.md) cover the real-time viewport workflow. # Visualizing Use this page to make molecular systems easier to inspect and communicate in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). It covers the everyday visualization workflow: apply visual presets, add visual models, adjust visibility and transparency, capture the viewport, and continue toward color, rendering, or animation pages when you need more control. [Interactive tutorials](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md) in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) (**Help > Tutorials**): - *"Visualization: visual models and colorization"*, - *"Visualization: rendering parameters"*. See also: [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md), [Colorizing](https://documentation.samson-connect.net/users/latest/colorizing/index.md), [Visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models), [Visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/index.md), [Rendering effects](https://documentation.samson-connect.net/users/latest/rendering-effects/index.md), [Rendering using Cycles](https://documentation.samson-connect.net/users/latest/rendering/index.md), and [Presenting and animating](https://documentation.samson-connect.net/users/latest/presenting/index.md). See also - [Colorizing](https://documentation.samson-connect.net/users/latest/colorizing/index.md), [Visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/index.md), and [Rendering](https://documentation.samson-connect.net/users/latest/rendering/index.md): use the specialized sibling guides when you want more depth. ## Before you start - Use [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) first if you need to choose specific atoms, residues, molecules, or visual models. - Use [Inspecting](https://documentation.samson-connect.net/users/latest/inspecting/index.md) when you need to edit properties in the Inspector. ## What this page covers This page gives you the main visualization workflow inside [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) and points you to the deeper pages that cover colorization, rendering effects, final-quality rendering, and preset authoring. ## Use a related page instead when - You already know you need a reusable visual preset: use [Visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/index.md). - You only need color schemes or palettes: use [Colorizing](https://documentation.samson-connect.net/users/latest/colorizing/index.md). - You want to tune lighting, fog, shadows, silhouettes, clipping, or related real-time effects: use [Rendering effects](https://documentation.samson-connect.net/users/latest/rendering-effects/index.md). - You are preparing a final-quality Cycles image or movie: use [Rendering using Cycles](https://documentation.samson-connect.net/users/latest/rendering/index.md). - You are building a timeline-based animation or presentation: use [Presenting and animating](https://documentation.samson-connect.net/users/latest/presenting/index.md). ## Applying visual presets The fastest way to visualize a molecular system is by applying [visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/index.md) to it. [Visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/index.md) provide an efficient way to apply multiple visual representations and color schemes simultaneously to a complex molecular system based on selectors, all in just a few clicks. [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides a set of default visual presets and you can [create and save your own visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/#create), e.g., by modifying the existing ones. See the [Visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/index.md) section on how to [apply](https://documentation.samson-connect.net/users/latest/visual-presets/#apply) and [create visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/#create). To apply a [visual preset](https://documentation.samson-connect.net/users/latest/visual-presets/index.md) click on **Visualization > Visual preset** and choose a visual preset among the existing ones. Here is how the "Protein-ligand" preset looks like on PDB code 1AA1: Use [Visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/index.md) for the full reference on applying presets and creating your own presets. Further in this section you will learn how to apply [visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models), [colorize](https://documentation.samson-connect.net/users/latest/colorizing/index.md), and change various rendering effects. ## Applying illustrative style If you would like to apply an illustrative visualization and rendering style inspired by the [RCSB PDB Molecule of the Month](https://pdb101.rcsb.org/motm/motm-about) style by [David S. Goodsell](http://ccsb.scripps.edu/goodsell/) (RCSB PDB-Rutgers and The Scripps Research Institute) follow these steps: - to apply the illustrative visualization style, click **Visualization > Visual preset** and, from the visual presets, select **Illustrate...** which would apply the van der Waals visual model for receptors and ligands with the color per chain ID (illustrative) and the van der Waals model for ions. - to apply the illustrative rendering style, click **Visualization > Presets > Illustrative** which would set the rendering preferences to resemble the illustrative style. To **reset** the view and the rendering style, remove the applied visual models in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) and in **Visualization > Presets** choose **Default** or **High quality** as shown in the [Changing rendering presets](#changing-rendering-presets) subsection. ## Changing rendering presets [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides several predefined rendering presets between which you can easily switch in **Visualization > Presets**. Rendering presets make it possible to quickly switch between different sets of [special rendering effects](https://documentation.samson-connect.net/users/latest/rendering-effects/index.md) like [ambient occlusion](https://documentation.samson-connect.net/users/latest/rendering-effects/#ambient-occlusion), [lighting](https://documentation.samson-connect.net/users/latest/rendering-effects/#lighting), [fog](https://documentation.samson-connect.net/users/latest/rendering-effects/#fog), [shadows](https://documentation.samson-connect.net/users/latest/rendering-effects/#shadows). You can also easily change these rendering effects in **Visualization > Options** or directly in **Preferences** as described in the [Rendering Effects](https://documentation.samson-connect.net/users/latest/rendering-effects/index.md) section. ## Capturing viewport To save a picture, you can capture the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md): - Press `F10` to take the viewport capture, the captured image is saved in the folder specified in [capture preferences](https://documentation.samson-connect.net/users/latest/preferences/#captures). - Press `Ctrl`/`Cmd` + `F10` to take the viewport capture and choose where to save it. - Press `Shift`+`F10` to copy the viewport capture to the clipboard. You can modify the [capture preferences](https://documentation.samson-connect.net/users/latest/preferences/#captures) in the **Interface > Preferences > Interface > Captures** panel (**Interface > Preferences**). ## Hiding and showing nodes You can hide from displaying in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) any group of structural nodes (atoms, chains, residues, molecules, etc.), [folders](https://documentation.samson-connect.net/users/latest/documents/#folders), [visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models), meshes, [labels](https://documentation.samson-connect.net/users/latest/labeling/index.md), and some other [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md). When you hide a parent [node](https://documentation.samson-connect.net/users/latest/node-types/index.md) its descendants will be automatically hidden as well, e.g. if you hide a residue then atoms in this residue will be hidden, but you can make descendant nodes visible while their parent node is hidden. You can hide a [node](https://documentation.samson-connect.net/users/latest/node-types/index.md) just by unchecking the box of this [node](https://documentation.samson-connect.net/users/latest/node-types/index.md) in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view). For example, in the image below the chain B is hidden and won't be visible in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). You can show a [node](https://documentation.samson-connect.net/users/latest/node-types/index.md) by checking the box back. Note If at least one descendant of a node is visible then the node's box in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) will be shown as ticked to depict that some of its descendants are visible. To change the visibility of nodes, select them in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) or in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md), then in the context toolbar go to the **Visibility** section where you can change the visibility of the selection and of all nodes. For example, in the image below we are to hide the two selected chains. Also, you can hide/show nodes using [Python Scripting](https://documentation.samson-connect.net/users/latest/scripting/index.md). ## Transparency For some [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) ([structural models](https://documentation.samson-connect.net/users/latest/models/#structural-models), [folders](https://documentation.samson-connect.net/users/latest/documents/#folders), [labels](https://documentation.samson-connect.net/users/latest/labeling/index.md), and many [visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models), meshes) you can modify their transparency by [selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) them and changing this parameter in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). Here is how, a semi-transparent structural model might look like along an opaque secondary structure visual representation: ## Representation of atoms and bonds Atoms and bonds in [structural models](https://documentation.samson-connect.net/users/latest/models/#structural-models) have a default visual representation, where atoms are represented as balls and bonds as sticks. You can modify it in [Preferences > Rendering > Structural models](https://documentation.samson-connect.net/users/latest/preferences/#structural-model-settings): Try various options, constant atoms size or atom size proportional to van der Waals radius, and various parameters for atom and bond sizes to see how it affects the display of molecules. If the **Automatically test** box is checked, this immediately affects the rendering in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). For example, here is how a molecule looks like with the **Constant atom size** option and the default atom radius (0.3Å): And here how the same molecule looks like with the **Atom size proportional to van der Waals radius** option. ## Adding visual models [Visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models) provide alternate visual representations of [structural models](https://documentation.samson-connect.net/users/latest/models/#structural-models), or even some arbitrary shapes, that may be displayed in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). Let's open a molecule, e.g. `1AF6` using **Home > Fetch** which will download it from RCSB PDB. We will apply a *Ribbons* (secondary structure) visual model to it. Note When a new visual model is added to the [document](https://documentation.samson-connect.net/users/latest/documents/index.md), it is applied to the current selection, or, if nothing is selected, to the whole [document](https://documentation.samson-connect.net/users/latest/documents/index.md). So, before adding a visual model make sure that a system to which you would like to apply it is selected and nothing else is selected, or nothing is selected if you would like to apply it to everything in the [document](https://documentation.samson-connect.net/users/latest/documents/index.md). Visual models may be added from the Visualization menu (**Visualization > Visual model**) or via `Ctrl`/`Cmd` + `Shift`+`V`. A pop-up menu will appear asking you to choose a visual model type and provide a name for a visual model node that will be created. For example, let's choose the *Ribbons* (secondary structure) visual model. As a result, a new visual model will be added in the [document](https://documentation.samson-connect.net/users/latest/documents/index.md). You can also hide the [structural model](https://documentation.samson-connect.net/users/latest/models/#structural-models) by unchecking its box in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view). Provided they handle them, [visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models) can be [colorized](https://documentation.samson-connect.net/users/latest/colorizing/index.md) with [color schemes](https://documentation.samson-connect.net/users/latest/colorizing/#color-schemes). This is the case for the *Ribbons* (secondary structure) visual model which we added before (when no color scheme is applied, a default color scheme based on the residue sequence numbers is used, as in the picture above). Use [Colorizing](https://documentation.samson-connect.net/users/latest/colorizing/index.md) for color schemes and palettes. As other node, you can [colorize](https://documentation.samson-connect.net/users/latest/colorizing/index.md) a visual model in several ways: - [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a visual model and, in its context toolbar, set the color . - [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a visual model and apply a color scheme from **Visualization > Color**. - [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a visual model and change/apply a color scheme in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). In the example below, we apply different color schemes to the *Ribbons* visual model using the above-mentioned ways. You can apply several visual models at once even to the same nodes. For example, try applying the Licorice visual model: select a molecule, click `Ctrl`/`Cmd` + `Shift`+`V`, and choose the Licorice visual model. ## Colorizing See the [Colorizing](https://documentation.samson-connect.net/users/latest/colorizing/index.md) section. ## Special effects See the [Rendering effects](https://documentation.samson-connect.net/users/latest/rendering-effects/index.md) section. ## Examples ### Dengue virus Let's make the following image of the molecule with PDB code [3J27](https://www.rcsb.org/structure/3J27) (part of the Dengue virus): You can reproduce this image via the following steps: - Add the Ribbons (secondary structure) visual model (`Ctrl`/`Cmd` + `Shift`+`V`). - Add the Licorice visual model. - Hide the structural model of the molecule. - Orient the molecule in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md), you can for it use the Compass in the bottom-left corner of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). - Colorize the Licorice visual model by the residue index (select the Licorice visual model and in the context toolbar choose **Color > Per attribute > Residueindex**). - Ambient occlusion: enable object-space ambient occlusion with the default parameters. - Anti-aliasing: enable with multisampling factor set to 2, enable FXAA. - Background: white. - Fog: enable with the far distance parameter set to 100Å. - Lighting: default parameters for the first and second lights; set ambient light to 0. - Shadows: enable with the default parameters. - Silhouettes: disable. ### The nucleosome core particle Let's make the following image of the molecule with PDB code [1EQZ](https://www.rcsb.org/structure/1EQZ) (the nucleosome core particle): You can reproduce this image via the following steps: - Orient the molecule in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md), you can for it use the Compass in the bottom-left corner of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). - In the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view), expand the molecule to see chains. Select chains from **A** to **H** and apply the Ribbons (secondary structure) visual model (`Ctrl`/`Cmd` + `Shift`+`V`), and then hide the selection. - Select the Ribbons (secondary structure) visual model and colorize it with a constant color (white). - Open [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md), modify the structural models representation (**Rendering > Structural models**): set the atom radius to 1Å. - Select the chain **I** and colorize it with a constant color. Colorize the chain **J** with a constant color. - Ambient occlusion: disable. - Anti-aliasing: enable with multisampling factor set to 2, enable FXAA. - Background: white. - Fog: enable with the default parameters. - Lighting: default parameters. - Shadows: enable with the default parameters. - Silhouettes: enable and set the silhouette opacity to 60%. ### Pilus machine Let's reproduce an image of the molecule with PDB code [3JC8](https://pdb101.rcsb.org/motm/211) (the type IVa pilus machine in a piliated state). Here we colorized 3JC8 by groups of chains. Please, download [3JC8.sam](https://documentation.samson-connect.net/wp-content/uploads/3JC8.sam_.zip) file in which for simplicity we combined chains in groups. You can reproduce this image via the following steps: - Orient the molecule in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md), you can for it use the Compass in the bottom-left corner of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). - Open [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md), modify the structural models representation (**Rendering > Structural models**): set the atom radius to 3Å. - Colorize each group of chains: double-click on the group and colorize it with a constant color. - Ambient occlusion: enable object-space ambient occlusion with the default parameters. - Anti-aliasing: enable with multisampling factor set to 2, enable FXAA. - Background: white. - Fog: disable. - Lighting: the light intensity for first and second lights is set to zero; the ambient light is set to 1 and the Fresnel intensity is set to 0. - Shadows: enable with the default parameters. - Silhouettes: enable, set the silhouette opacity to 60%, the silhouette thickness to 1, and the distance threshold to 2Å. ### DNA polymerase with DNA Let's make the following image of the molecule with PDB code [4QWE](https://www.rcsb.org/structure/4qwe) (DNA polymerase in complex with DNA). You can reproduce this image via the following steps: - In the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view), expand the molecule to see chains. Select the chain **A** and apply the Ribbons (secondary structure) visual model (`Ctrl`/`Cmd` + `Shift`+`V`), and then hide the selected chain. - Find all Sulfur and Calcium atoms. Open the [Find window](https://documentation.samson-connect.net/users/latest/selecting/#selecting-using-nsl) (**Select > Find** or `Ctrl`/`Cmd` + `F`). Input `atom.symbol S or atomsymbol Ca` (short version: `a.s S or a.s Ca`) and click `Enter`. Now you should see 11 nodes selected, press `Ctrl`/`Cmd` + `Shift`+`V` and add Van der Waalsvisual model. Select in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) the newly created Van der Waals visual model and in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) (click `Ctrl`/`Cmd` + `I` if you do not see the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector)) set the scale to 0.75. - In the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view), select the chains **C** and **D** and apply to them the Licorice visual model. - Ambient occlusion: disable. - Anti-aliasing: enable with multisampling factor set to 2, enable FXAA. - Background: white. - Fog: enable with the far distance set to 50Å. - Lighting: default parameters. - Shadows: enable with the default parameters. - Silhouettes: enable and set the silhouette opacity to 50%. ### The human erythrocyte catalase Let's make the following image of the molecule with PDB code [1DGF](https://www.rcsb.org/structure/1dgf) (the human erythrocyte catalase). You can reproduce this image via the following steps: - Add the Ribbons (secondary structure) visual model (`Ctrl`/`Cmd` + `Shift`+`V`). - Let's now hide all residues and water atoms, leaving shown only **ACT**, **HEM**, and **NDP** structural groups. Open the [Find window](https://documentation.samson-connect.net/users/latest/selecting/#selecting-using-nsl) (**Select > Find** or `Ctrl`/`Cmd` + `F`). First we will hide all non structural groups: input `n.t structuralGroup` (short version: `n.t sg`) and click `Enter`, then *right-click* on any selected node, choose **Invert selection** in the context menu, and use the context toolbar for the selection to choose **Visibility > Hide selection**. Let's now hide all water atoms: open the **Find window**, input `a.water` and click `Enter`, then in the context toolbar choose **Visibility > Hide selection**. - Open [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md), modify the structural models representation (**Rendering > Structural models**): set atom and bond radius to 0.3Å. - In the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view), select the Ribbons (secondary structure) visual model and colorize it with a constant color (white). - Let's colorize **HEM** and **NDP** structural groups. In the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view), enter **HEM** in the **Filter nodes...** and click `Enter`. Colorize it with a constant color. Do the same for the **NDP** structural groups. - Ambient occlusion: disable. - Anti-aliasing: enable with multisampling factor set to 2, enable FXAA. - Background: white. - Fog: enable with the far distance set to 50Å. - Lighting: default parameters. - Shadows: enable with the default parameters. - Silhouettes: enable and set the silhouette opacity to 50%. - Orient the molecule in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). See also - [Color schemes](https://documentation.samson-connect.net/users/latest/colorizing/#color-schemes) - [Visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models) - [Visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/index.md) - [Presenting and animating](https://documentation.samson-connect.net/users/latest/presenting/index.md) ## Related pages - [Colorizing](https://documentation.samson-connect.net/users/latest/colorizing/index.md) - [Rendering effects](https://documentation.samson-connect.net/users/latest/rendering-effects/index.md) # Colorizing In [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), you can colorize [visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models), meshes, [labels](https://documentation.samson-connect.net/users/latest/labeling/index.md), and structural [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) (residues, atoms, etc.) using various [color schemes](https://documentation.samson-connect.net/users/latest/colorizing/#color-schemes). Color schemes can be used to, for example, assign a constant color to a [node](https://documentation.samson-connect.net/users/latest/node-types/index.md), colorize atoms by residue, chain, etc., or based on some [node](https://documentation.samson-connect.net/users/latest/node-types/index.md) property (e.g., temperature factor, side chain charge, etc.). You can apply different [color schemes](https://documentation.samson-connect.net/users/latest/colorizing/#color-schemes) to different [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md). A [color scheme](https://documentation.samson-connect.net/users/latest/colorizing/#color-schemes) is applied to a [node](https://documentation.samson-connect.net/users/latest/node-types/index.md) via a **material** which contains not only a color scheme but also other appearance options such as metallic, roughness, transmission, etc. When a [color scheme](https://documentation.samson-connect.net/users/latest/colorizing/#color-schemes) or, more generally, a material is applied to a [node](https://documentation.samson-connect.net/users/latest/node-types/index.md), all the [node](https://documentation.samson-connect.net/users/latest/node-types/index.md)'s descendants are affected. [Interactive tutorial](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md) in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) (**Help > Tutorials**): *"Visualization: visual models and colorization"*. ## What this page covers This page explains how to colorize nodes in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), choose color schemes, and combine palettes with visualization workflows. **What you will learn from this tutorial**: - About [color schemes](https://documentation.samson-connect.net/users/latest/colorizing/#color-schemes) in SAMSON. - [How to apply color schemes](#applying-color-schemes). - About [color palettes](https://documentation.samson-connect.net/users/latest/colorizing/#color-palettes) in SAMSON. - [How to modify the already applied material via the Inspector](#changing-materials-in-the-inspector). **What is not covered in this tutorial**: For how to move apply various visualizations, please, refer to the [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) section. ## Color schemes [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides the following color schemes: - **Constant**: applies a constant color. - **Constant illustrative**: applies a constant color (illustrative). It helps to depict molecules in a style similar to [David S. Goodsell](http://ccsb.scripps.edu/goodsell/)'s artwork. - Per atom element: - **Per element** / **CPK** - sets atom colors based on their element types using the classic Corey-Pauling-Koltun (CPK) color scheme. This is the default color scheme for structural nodes. - **Per element (custom carbons)** - sets the specified color for carbons and CPK colors for other atom element types. - **Per element (per chain carbons)** - sets palette colors for carbons based on their chain ID and CPK colors for other atom element types. - **Per element (per structural model carbons)** - sets palette colors for carbons based on their structural models and CPK colors for other atom element types. - **Per attribute**: the color is determined based on a structural [node](https://documentation.samson-connect.net/users/latest/node-types/index.md) attribute. The following per-attribute color scheme are available: - **Chain** - colorizes per chain ID. - **Chain (illustrative)** - colorizes per chain ID in a style similar to [David S. Goodsell](http://ccsb.scripps.edu/goodsell/)'s artwork. - **Formal charge** - colorizes based on formal charges of atoms. - **Occupancy** - colorizes based on atom occupancies. - **Partial charge** - colorizes based on partial charges of atoms. - **Temperature factor** - colorizes based on temperature factor of atoms. - **Residue index** - colorizes based on the residue id. - **Residue type** - colorizes based on the residue type. - **Secondary structure type** - colorizes based on the residues' secondary structure. - **Side chain charge** - colorizes residues based on their standard side chain charge. - **Side chain polarity** - colorizes residues based on their standard side chain polarity. - **Structural model** - colorizes per structural models. - **Structural model (illustrative)** - colorizes per structural models in a style similar to [David S. Goodsell](http://ccsb.scripps.edu/goodsell/)'s artwork. - **Custom...** - choose a per attribute color scheme and a [color palette](https://documentation.samson-connect.net/users/latest/colorizing/#color-palettes). The per attribute color schemes colorize using their default [color palette](https://documentation.samson-connect.net/users/latest/colorizing/#color-palettes), which you can [change using the Inspector](#changing-materials-in-the-inspector) or by [colorizing using Custom...](https://documentation.samson-connect.net/users/latest/colorizing/#color-palettes). You can see some of the default per-attribute color schemes on the image below. ## Applying color schemes Color schemes can be applied to selected [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) in several ways: - [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a node and, in the context toolbar menu, click on the material. - [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a node and apply the colorization using **Visualization > Color**. - [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a node and change/apply the colorization in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) via a material (see [Changing materials in the Inspector](#changing-materials-in-the-inspector) section below). In the example below, we apply different color schemes to the Ribbons visual model using the above-mentioned ways. Open a molecule, e.g. download a protein from RCSB PDB using **Home > Fetch**. [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a structural model in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) and apply a constant color scheme via its context toolbar as shown in the image below or via the **Visualization > Color**. A dialog will appear in which you can choose the color. As a result, all the chosen nodes will be colorized with the same color. Note You can always [undo](https://documentation.samson-connect.net/users/latest/history/index.md) operations by clicking **Edit > Undo** (1). 1. , : `Ctrl`+`Z`, : `Cmd`+`Z` You can see which nodes have materials in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) - it is indicated with the material icon as shown in the image below: Now, [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a structural model and apply a per attribute color scheme, e.g. the "Residue hydrophobicity" color scheme in case you have a protein selected. For that, go to the **Visualization > Color > Per attribute > Residue hydrophobicity** as shown in the image below or use the context toolbar. As a result, all residues will be colorized according to their hydrophobicity. To reset the colorization to the default one, [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) the [node](https://documentation.samson-connect.net/users/latest/node-types/index.md) and in the context toolbar select **Color > Reset color** as shown in the image below or go to **Visualization > Color > Reset color**. If you want to reset the colorization, then [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) the node and, either in the toolbar menu or in the **Visualization menu**, click on **Color > Reset color**, or simply clear it via the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). ## Color palettes Each per attribute color scheme has its own default color palette. You can [modify it using the Inspector](#changing-materials-in-the-inspector), or you can colorize using **Color > Custom...**. The later one opens a dialog window in which you can choose which color scheme to apply and what color palette to use. A **color palette** defines how the colors change depending on the value to which the color scheme is associated. In [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), the following color palette types are available: - A standard color palette in the **HSV (Hue-Saturation-Value)** color space. - [Discrete color palettes](https://documentation.samson-connect.net/users/latest/color-palettes/#discrete-color-palettes) - A set of color palettes in the **HCL (Hue-Chroma-Luminance)** color space: - [Qualitative](https://documentation.samson-connect.net/users/latest/color-palettes/#qualitative-hcl-color-palettes) - [Sequential single- and multi-hue](https://documentation.samson-connect.net/users/latest/color-palettes/#sequential-hcl-color-palettes) - [Diverging](https://documentation.samson-connect.net/users/latest/color-palettes/#diverging-hcl-color-palettes) - [Flexible diverging](https://documentation.samson-connect.net/users/latest/color-palettes/#flexible-diverging-hcl-color-palettes) See the tables of [default HCL color palettes](https://documentation.samson-connect.net/users/latest/color-palettes/index.md) available in SAMSON with their color bars. Note The HCL color space is better suited for human perception - you can directly control the color (hue), the "colorness" (chroma) and the luminance (brightness). [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) includes most of the HCL color palettes available in R and Python by default. See [HCL Wizard](https://hclwizard.org) for details on the advantages of the HCL color space. Note You can **revert left and right arms** of color palettes by checking the **Reverse** option at the top of the dialog. If you want to see how your system looks like with color palettes while switching between them, then, at the bottom of the color palette window check the **Auto update** option or click the **Update** button. Please note that it might be slow for big systems. At the bottom of the color palette window you can find the **Color Vision Deficiency Emulator** which shows how the current color palette will be perceived by people with certain color vision deficiencies: You can also **create your own color palettes in the HCL color space** by copying the parameters from the existing one, checking the **Custom HCL palette** option, and modifying it. You can save your color palette as a new one for later use - it will be stored in your local [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) configurations. ## Changing materials in the Inspector **Prerequisites**: Use [Inspecting](https://documentation.samson-connect.net/users/latest/inspecting/index.md) to learn how to inspect nodes in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). You can view and modify materials applied to [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). You can add a material from the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) as follows: You can modify the reset the color scheme and choose another one: For a constant [color scheme](https://documentation.samson-connect.net/users/latest/colorizing/#color-schemes) you can modify its color, and for a per-attribute [color scheme](https://documentation.samson-connect.net/users/latest/colorizing/#color-schemes) you can modify its [color palette](https://documentation.samson-connect.net/users/latest/colorizing/#color-palettes) by clicking on the color bar: For per-attribute [color schemes](https://documentation.samson-connect.net/users/latest/colorizing/#color-schemes), you can also modify their range by altering the min and max values. This might be useful when you would like to have a specific range for colorization based on, for example, the temperature factor. You can apply an appearance preset for a material in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector): ## Related pages - [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) - [Color palettes](https://documentation.samson-connect.net/users/latest/color-palettes/index.md) - [Visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/index.md) # Labeling A **label** is a type of a [node](https://documentation.samson-connect.net/users/latest/node-types/index.md) that is stored in the [document](https://documentation.samson-connect.net/users/latest/documents/index.md) and depicts some text in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). A label can contain a node's name, a text describing a group of nodes, or some [measurement](https://documentation.samson-connect.net/users/latest/measuring/index.md). Note If you save your document in one of the SAMSON file formats (.sam or .samx), labels will be saved as well. **Prerequisites**: - Use [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) to learn how to select nodes in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). - Use [Inspecting](https://documentation.samson-connect.net/users/latest/inspecting/index.md) to learn how to inspect nodes in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). ## What this page covers This page explains how to add, customize, and position labels so important structural features remain clear during analysis and presentation. You will learn how to add labels and modify them (change their visibility, font, color, and positions). ## Adding labels You can add labels to selected [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) via their context toolbar. Note Labels cannot be added to all types of nodes but mainly to structural nodes (molecules, residues, atoms, etc). ### Adding labels to selection To add labels to selected nodes, in the context toolbar, choose : - **Add label** - this will add a single label for the currently selected group of nodes (this does not add labels to descendants of the selected nodes but only to the directly selected group of node). - **Add label to...** - you can choose to what type of nodes to add labels, including descendants of the currently selected nodes, for example to all the residues in the current selection. ### Adding labels in Viewport To add labels in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md), first, you need to activate the **Label editor** (1) in the left-side menu of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). 1. , : `Ctrl`+`L`, : `Cmd`+`L` Please note, that the type of a node to which a label will be added depends on the current [selection filter](https://documentation.samson-connect.net/users/latest/selecting/index.md). For example, if it is set to **Atoms and bonds** then labels will be added to atoms or bonds, if it is set to **Residues** then labels will be added to residues. ## Visibility of labels You can switch on/off the visibility of labels in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) by ticking/unticking them. The visibility of labels changes progressively when zooming in and out on the system. When zooming out, the labels for smaller nodes (e.g., atoms) will start to disappear and the labels for larger nodes (e.g., molecules) will start to appear, and vice versa when zooming in. You can modify when labels appear and disappear. For that, [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a label and, in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector), change **maximum and minimum display radii** - these parameters govern when the label is visible. ## Changing font of labels You can modify the font for all the labels or just for a group of labels. To modify the font for all the labels for which the font has not been specified directly, open the [Preferences > Rendering > Labels](https://documentation.samson-connect.net/users/latest/preferences/#labels) and change it there. You can also modify there the number of decimal places for angles and distances shown in labels which is useful for labels created using the [Measure editor](https://documentation.samson-connect.net/users/latest/measuring/index.md). To modify the font for a label or a group of labels, [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) them and open the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). In the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector), click on **Choose font...** to modify the font for the last selected label or for all selected labels at once if you choose to **Edit all selected nodes**. To reset the font for labels to the one specified in [Preferences](https://documentation.samson-connect.net/users/latest/preferences/#labels), [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) these labels and, in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector), double-click on the **Font** as shown in the image below. ## Colorizing labels Labels can be [colorized](https://documentation.samson-connect.net/users/latest/colorizing/index.md) as many other [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md). You can change the color of a label as follows: - click on a label in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view), then, in the context toolbar, go to **Color > Constant** and choose a color from the pop-up dialog. - [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a label and in the **Visualization > Color** click on **Constant**. - [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a label and in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) click on **Color > Constant**: You can **reset** the label's color to the default one in the same way. - click on a label in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view), then, in the context toolbar, go to **Color > Reset color**. - [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a label and in the **Visualization > Color** click on **Reset color**. - [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a label and in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) click on **X** () button next to the **Text color**: You can also modify the **transparency** of labels in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). ## Selecting labels in Viewport Apart from [selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) labels in the [document](https://documentation.samson-connect.net/users/latest/documents/index.md), you can select them in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) as well. The level of [selection](https://documentation.samson-connect.net/users/latest/selecting/index.md) in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) is governed by the [Selection filter](https://documentation.samson-connect.net/users/latest/selecting/index.md), so first you need to set it to "Labels" and only then you can [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) labels in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). Note Only the visible labels will be chosen. Do not forget to switch the [Selection filter](https://documentation.samson-connect.net/users/latest/selecting/index.md) if you want to [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) other types of nodes in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) later. ## Moving labels **Prerequisites**: Use [Moving objects](https://documentation.samson-connect.net/users/latest/moving-objects/index.md) to learn how to move objects in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). When labels are created they are placed at the geometric center of the nodes and they are always situated in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) plane. You can move labels using one of the following ways. 1. [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a label and change its **viewport offset** in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). 1. Set the [Selection filter](https://documentation.samson-connect.net/users/latest/selecting/index.md) to "Labels" and use one of the [Move editors](https://documentation.samson-connect.net/users/latest/moving-objects/#move-editors), e.g. the [Displace editor](https://documentation.samson-connect.net/users/latest/moving-objects/#moving-objects-using-move-editors) (shortcut: `D`). Do not forget to switch the [Selection filter](https://documentation.samson-connect.net/users/latest/selecting/index.md) if you want to [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) other types of nodes in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) later. 1. [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a label in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) and use one of the [Move editors](https://documentation.samson-connect.net/users/latest/moving-objects/#move-editors). ## Related pages - [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) - [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) - [Presenting and animating](https://documentation.samson-connect.net/users/latest/presenting/index.md) # Rendering effects Use this page when the molecular scene is already loaded and you want the real-time viewport to be clearer, more readable, or closer to the image style you need. It explains the rendering effects that control depth, edges, background, lighting, shadows, silhouettes, fog, and clipping. You can change these rendering effects in: - **Visualization > Options** which gives you a quick access to switching them on/off and switching between their presets. - the **Rendering** section in the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) panel, which gives you more control over their parameters. [Interactive tutorial](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md) in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) (**Help > Tutorials**): *"Visualization: rendering parameters"*. ## Start with these guides - [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md): use the broader guide when you need the full visualization workflow. - [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md): use the full preferences reference when you need panel-by-panel settings. - [Rendering](https://documentation.samson-connect.net/users/latest/rendering/index.md): use this page when you are preparing a final high-quality render. ## What this page covers This page explains the rendering effects that change how the viewport looks in real time, and shows where to adjust them from quick controls or detailed preferences. Use this page for interactive viewport appearance. Use [Rendering using Cycles](https://documentation.samson-connect.net/users/latest/rendering/index.md) when you need final-quality offline rendering, and use [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) when you are still choosing visual models, visibility, presets, or captures. See also - [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) - [Rendering](https://documentation.samson-connect.net/users/latest/rendering/index.md) ## Ambient occlusion Ambient occlusion improves the perception of depth in molecules, by simulating the fact that deeper regions are less accessible to light, and are thus darker. Two types of ambient occlusion are handled in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) - **Screen-space ambient occlusion** efficiently provides an approximate simulation, but is sensitive to the distance to the camera. - **Object-space ambient occlusion** is more realistic, but slower. Even screen-space ambient occlusion is very useful to improve depth perception however. The [ambient occlusion](https://documentation.samson-connect.net/users/latest/preferences/#ambient-occlusion) settings may be changed in the **Rendering > Ambient occlusion** section of the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) panel: The screen-space ambient occlusion can be switched on/off in one click in the **Visualization > Options**. Here is the Ribbons visual model of `1AF6` without ambient occlusion: And here it is with enabled screen-space ambient occlusion: ## Anti-aliasing Anti-aliasing removes jagged edges from images, and may significantly improve rendering. The [anti-aliasing settings](https://documentation.samson-connect.net/users/latest/preferences/#anti-aliasing) may be changed in the **Rendering > Ambient occlusion** section of the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) panel. *Fast Approximate Anti-Aliasing (FXAA)* is typically very efficient, and can be activated on most recent graphics cards. Note Anti-aliasing requires more rendering from your GPU and therefore may slow-down the visualization for big systems. Without anti-aliasing (choose *Best speed* from the list: multisampling factor set to 1, no FXAA), edges are very visible: With FXAA and multisampling set to 2 (choose *Higher quality* from the list), edges are much smoother, and pixel boundaries are much less visible: ## Background The background color of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) may be changed in the **Rendering > Background** section of the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) panel: Four options are available: - **SAMSON**: the default SAMSON background; - **Black**: an entirely black background; - **White**: an entirely white background; - **Custom**: a gradient from a user-defined top color to a user-defined bottom color; - **Image**: you can set an image as a background. Let's try to set a custom gradient background by choosing **Custom** and modifying the **Custom top color** and the **Custom bottom color**. You can switch between different backgrounds easily in the **Visualization > Options** and in the bottom of the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). You can always return to the default [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) background color. ## Bloom The bloom rendering effect produces highlights of the brightest parts of the image. The [bloom settings](https://documentation.samson-connect.net/users/latest/preferences/#bloom) may be changed in the **Rendering > Bloom** section of the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) panel: The bloom can be switched on/off in one click in **Visualization > Options**. Here is an example of the bloom effect: ## Clipping See [Clipping structures](https://documentation.samson-connect.net/users/latest/moving-around/#clipping-structures). ## Depth of field This effect simulates the depth of field effect produced by actual cameras (e.g. blurred distant objects). If enabled, when you zoom in the molecule its distant parts will be blurred. The [depth of field settings](https://documentation.samson-connect.net/users/latest/preferences/#depth-of-field) may be changed in the **Rendering > Depth of field** section of the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) panel: Turn the depth of field on, set the strength to 80 and zoom on a molecule. The depth of field can be switched on/off in one click in **Visualization > Options**. ## Fog Basically, fog makes distant objects less visible. Fog attenuates distant parts by blending them progressively with the background. Turn it on to make it easier to focus on the foreground. The near and far distances are based on the camera location and determine where the fog is enabled. Before the *near distance* there is no fog, after the *far distance* every node is invisible. The *strength* parameter influences the speed at which the fog appears. The [fog settings](https://documentation.samson-connect.net/users/latest/preferences/#fog) may be changed in the **Rendering > Fog** section of the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) panel: The fog can be switched on/off in one click in **Visualization > Options**. Here is 1YRF again with both depth of field and fog: ## Lighting In [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), [lighting settings](https://documentation.samson-connect.net/users/latest/preferences/#lighting) can be modified in the **Rendering > Lighting** section of the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) panel: This section makes it possible to control the parameters of the two point lights that illuminate the document, as well as global parameters. Each light has the following parameters: - **Light color**: click the square to change the color of the light - **Light intensity** (between 0 and 1): the intensity of the light - **Specular intensity** (between 0 and 1): the intensity of the light reflection on surfaces. High values make surfaces look like plastic, while low values make surfaces look matte. - **Specular power** (between 0 and 1000): the decay of specular reflection. High values produce sharper specular reflections. - **Longitude and latitude** control the position of the light. The first light is typically the main light, which is thus typically brighter than the second light (a *back light*). Finally, three more parameters are global: - **Fresnel intensity** (between 0 and 1): the amount of background light reflected at grazing angles - **Fresnel power** (between 0 and 100): how fast the Fresnel effect decays - **Ambient light**: the amount of light that reaches objects, even when the intensity of both lights is set to 0. Try changing all parameters and see the impact on rendering (switch on the **Automatically test** check box in the bottom). You can easily switch between various presets for lighting either in **Visualization > Options > Lighting** or in **Interface > Preferences > Rendering > Lighting**. if you want to reproduce the flat lighting, set the light intensity for both first and second light to zero, the ambient light to 0.8, and the Fresnel power to zero. ## Pinhole The pinhole rendering effect makes objects less visible when they are far from the center of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). The [pinhole settings](https://documentation.samson-connect.net/users/latest/preferences/#pinhole) may be changed in the **Rendering > Pinhole** section of the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) panel: The pinhole can be switched on/off in one click in **Visualization > Options**. Here is an example of the pinhole effect: ## Shadows Shadows are particularly helpful to improve the perception of relative positions. Note In case of an old graphics card you may want to either disable this option, or choose the lower preset. The [shadows settings](https://documentation.samson-connect.net/users/latest/preferences/#shadows) may be changed in the **Rendering > Shadows** section of the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) panel: The shadows can be switched on/off in one click in **Visualization > Options**. Without shadows, it may be difficult to perceive the relative positions, e.g., of 1YRF to the graphene sheet behind it: With shadows, however, this becomes much easier: ## Silhouettes Silhouettes make it easier to separate regions with different depths. The [silhouettes settings](https://documentation.samson-connect.net/users/latest/preferences/#silhouettes) may be changed in the **Rendering > Silhouettes** section of the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) panel. The silhouettes can be switched on/off in one click in **Visualization > Options**. Let's create the Ribbons (secondary structure) visual model for 1YRF molecule and enable silhouettes with the thickness set to 1. ## Related pages - [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) - [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) - [Rendering](https://documentation.samson-connect.net/users/latest/rendering/index.md) # Rendering using Cycles Use this page when real-time viewport rendering is not enough and you want final-quality images or movies from [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) integrates the **Cycles** renderer, a path-tracing renderer from [Blender](https://www.blender.org/), for interactive photorealistic rendering inside the viewport. You can activate Cycles with just one click: **Visualization > Trace** or click `F9`. ## What this page covers This page explains how to prepare a scene for high-quality rendering in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) and when to switch from real-time visualization settings to final rendering settings. ## What you will be able to do afterward - Activate [Cycles](https://documentation.samson-connect.net/users/latest/rendering/#rendering-using-cycles) in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). - Control [materials](https://documentation.samson-connect.net/users/latest/rendering/#materials). - Control [lights](https://documentation.samson-connect.net/users/latest/rendering/#lights). - Use [advanced rendering effects](https://documentation.samson-connect.net/users/latest/rendering/#advanced-rendering-effects) with Cycles. - [Import 3D objects](https://documentation.samson-connect.net/users/latest/rendering/#importing-3d-objects). - [Save rendered images or animations](https://documentation.samson-connect.net/users/latest/rendering/#export). ## Before you start - Use [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) first if you still need to add visual models, choose visibility, or capture the viewport. - Use [Colorizing](https://documentation.samson-connect.net/users/latest/colorizing/index.md) first if the structures or visual models need color schemes. - Use [Inspecting](https://documentation.samson-connect.net/users/latest/inspecting/index.md) when you need to edit material, light, or rendering parameters in the Inspector. See also [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md), [Colorizing](https://documentation.samson-connect.net/users/latest/colorizing/index.md), [Rendering effects](https://documentation.samson-connect.net/users/latest/rendering-effects/index.md). You can **activate Cycles** with just one click: **Visualization > Trace** or click `F9`. Once activated, it begins path tracing and you will immediately see its results in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) updating in real time. And it is fully **interactive** - move a [camera](https://documentation.samson-connect.net/users/latest/camera/index.md), apply [visualization](https://documentation.samson-connect.net/users/latest/visualizing/index.md) or [colorization](https://documentation.samson-connect.net/users/latest/colorizing/index.md) and you will see the changes applied automatically to the rendered image. You can control Cycles parameters in the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md): [Preferences > Cycles](https://documentation.samson-connect.net/users/latest/preferences/#path-tracing). Check out this short thread that explains in 5 simple steps how to use Cycles in SAMSON to produce fantastic-looking molecular images: > Here's a quick thread on how to make this type of images in 5 simple steps: > > — Stephane Redon (@StephaneRedon) [July 26, 2024](https://twitter.com/StephaneRedon/status/1816804993816752272?ref_src=twsrc%5Etfw) ## Material Control: Metal, Glass, Emissive and More A vital aspect of high-quality rendering is the ability to control **materials**. With the integrated Cycles Renderer, you can customize a range of materials, from metallic surfaces to glass translucency and even emissive materials that glow. The power to create visually rich and scientifically accurate models is now at your fingertips. **Materials** are easily controlled in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector), and **Appearance presets** make it possible to change the look of your models in just a few clicks. The following material categories are available: - **Metallic**: Carbon Fiber, Carbon Steel, Copper, Gold, Paint, Silver, Steel, Zinc - **Semi**-metallic: Brass, Bronze, Epoxy, Pearl, Rust - **Smooth**: Ceramic, Latex, Marble, Paint, Paper, Plastic, Polystyrene, Satin, Shiny plastic - **Rough**: Concrete, Feather, Granite, Velvet, Wood - **Emissive**: Faint, Soft, Glowing, Shining, Bright, Strong, Intense - **Transparent**: Ice, Glass, Jade, Obsidian, Water, Wax You can further adjust individual parameters of the material in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). Below you can see some examples of these materials. ## Lights Control The Cycles Renderer provides advanced light and shadow controls, letting you set the mood and atmosphere for your renders. Whether it's a soft ambient light to highlight subtle features, powerful lights to accentuate details, or even colored lights, you can do it all. To add a light, click **Visualization > Light** (1). This will add a new light node in your [document](https://documentation.samson-connect.net/users/latest/documents/index.md). 1. , : `Ctrl`+`Shift`+`L`, : `Cmd`+`Shift`+`L` You can add multiple lights at different positions with different parameters (e.g. colors). You can modify various parameters of the light using the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector): - color - position - power - radius To hide a light node from rendering in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md), simply uncheck it in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view). You can easily move the lights, see [Moving objects](https://documentation.samson-connect.net/users/latest/moving-objects/index.md) and the video below. \[ \](https://documentation.samson-connect.net/wp-content/uploads/CycleLights.mp4) ## Advanced rendering effects You can enhance your visual storytelling with special rendering effects like [depth of field](https://documentation.samson-connect.net/users/latest/rendering-effects/#depth-of-field), which adds a cinematic touch by blurring out-of-focus regions. This can be especially useful for emphasizing focal points in your molecular models or simulations. You can also modify the [background](https://documentation.samson-connect.net/users/latest/rendering-effects/#background) and other [rendering effects](https://documentation.samson-connect.net/users/latest/rendering-effects/index.md). ## Importing 3D objects You can import 3D objects into [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) to render them alongside your molecules and create complex scenes. [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) supports the following 3D geometry formats: - STL - OBJ - glTF To import a 3D object, use **Home > File > Open...** or drag-and-drop a file in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). When loading a 3D object, you might be asked to specify its size or the size units. 3D geometry is imported in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) as a mesh and you can easily move (see [Moving objects](https://documentation.samson-connect.net/users/latest/moving-objects/index.md)) or apply other transformations to it (e.g. scaling). You can also apply materials to meshes and colorize them. ## Save rendered image or animation To save a rendered image, you can capture the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md): - Press `F10` to take the viewport capture, the captured image is saved in the folder specified in [capture preferences](https://documentation.samson-connect.net/users/latest/preferences/#captures). - Press `Ctrl`/`Cmd` + `F10` to take the viewport capture and choose where to save it. - Press `Shift`+`F10` to copy the viewport capture to the clipboard. You can modify the [capture preferences](https://documentation.samson-connect.net/users/latest/preferences/#captures) in the **Interface > Preferences > Interface > Captures** panel (**Interface > Preferences**). To render an [animation](https://documentation.samson-connect.net/users/latest/presenting/index.md) and save it: - Switch on the rendering by clicking **Visualization > Trace** or click `F9`. - Click [Export a movie](https://documentation.samson-connect.net/users/latest/presenting/#exporting-a-movie) in the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). ## Related pages - [Rendering effects](https://documentation.samson-connect.net/users/latest/rendering-effects/index.md): tune real-time viewport effects before or alongside Cycles. - [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md): prepare visual models, visibility, presets, and captures. - [Presenting and animating](https://documentation.samson-connect.net/users/latest/presenting/index.md): create timelines and export movies. # Presenting and animating Use this page when you want to turn a SAMSON document into a presentation, animation, or exported movie. It explains how presentations, animation nodes, the Animator, camera motions, controllers, watermarks, and movie export fit together. Animation capabilities in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) include: - **animations of molecules**: dock structures, assemble structures, create custom paths, play simulation trajectories; - **camera animations**: orbit around structures, add standard paths, create custom paths; - various **animation effects**: entrance, exit, highlight, etc. See also [Animations](https://documentation.samson-connect.net/users/latest/animations/index.md) - see references for specific animation effects. Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` See also - [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) - [Colorizing](https://documentation.samson-connect.net/users/latest/colorizing/index.md) - [Rendering](https://documentation.samson-connect.net/users/latest/rendering/index.md) - [Visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models) - [Visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/index.md) ## What this page covers This page explains how presentations, the Animator, animation effects, controllers, camera positions, watermarks, and movie export fit together when you create animated output in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). ## Before you start - Use [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) and [Colorizing](https://documentation.samson-connect.net/users/latest/colorizing/index.md) first if the scene still needs visual models, visibility choices, or color schemes. - Use [Rendering effects](https://documentation.samson-connect.net/users/latest/rendering-effects/index.md) when the real-time viewport style needs lighting, fog, clipping, shadows, or silhouettes. - Use [Animations](https://documentation.samson-connect.net/users/latest/animations/index.md) when you already know you need the reference page for a specific animation effect. ## What you will be able to do afterward - Create and open a presentation in the Animator. - Add animation effects and adjust their timing. - Use camera and motion controllers. - Set presentation options and watermarks. - Export a presentation as a movie. ## Video tutorial A quick video example of the [Assemble animation](https://documentation.samson-connect.net/users/latest/animations/assemble/index.md): A video tutorial with introduction into animating with SAMSON: [How to create molecular animations in SAMSON](https://www.youtube.com/watch?v=41zg-DHXb2A) (1 h 11 min). Video chapters - [0:00](https://www.youtube.com/watch?v=41zg-DHXb2A) Welcome - [1:44](https://www.youtube.com/watch?v=41zg-DHXb2A&t=104s) Overview of SAMSON - [7:33](https://www.youtube.com/watch?v=41zg-DHXb2A&t=453s) The SAMSON Animator - [14:50](https://www.youtube.com/watch?v=41zg-DHXb2A&t=890s) Animating molecules - [19:36](https://www.youtube.com/watch?v=41zg-DHXb2A&t=1176s) Creating a docking animation - [23:55](https://www.youtube.com/watch?v=41zg-DHXb2A&t=1435s) Creating an assembly animation - [25:12](https://www.youtube.com/watch?v=41zg-DHXb2A&t=1512s) Integrating molecular dynamics trajectories in an animation - [33:22](https://www.youtube.com/watch?v=41zg-DHXb2A&t=2002s) Creating custom molecular trajectories - [40:33](https://www.youtube.com/watch?v=41zg-DHXb2A&t=2433s) Creating an orbiting animation - [45:53](https://www.youtube.com/watch?v=41zg-DHXb2A&t=2753s) Creating a zooming animation - [47:29](https://www.youtube.com/watch?v=41zg-DHXb2A&t=2849s) Following atoms with the camera - [49:54](https://www.youtube.com/watch?v=41zg-DHXb2A&t=2994s) Creating custom camera motions - [52:17](https://www.youtube.com/watch?v=41zg-DHXb2A&t=3137s) Adding Entrance and Exit effects - [54:41](https://www.youtube.com/watch?v=41zg-DHXb2A&t=3281s) Exporting movies - [56:54](https://www.youtube.com/watch?v=41zg-DHXb2A&t=3414s) Pausing and stopping animations - [59:02](https://www.youtube.com/watch?v=41zg-DHXb2A&t=3542s) Integrating slides and creating presentations - [1:07:33](https://www.youtube.com/watch?v=41zg-DHXb2A&t=4053s) Modifying Easing curves - [1:09:50](https://www.youtube.com/watch?v=41zg-DHXb2A&t=4190s) Sharing your animations Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` ## What is a presentation A **Presentation** is a [node](https://documentation.samson-connect.net/users/latest/node-types/index.md) that combines **Animation** nodes helping you to form a story and show presentations or [export them as movies](#exporting-a-movie). Presentation and animation [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) are part of [documents](https://documentation.samson-connect.net/users/latest/documents/index.md) and are visible in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view). A [document](https://documentation.samson-connect.net/users/latest/documents/index.md) might contain multiple presentations, each one of them containing multiple different animations. Presentation and animation [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) are saved with a [document](https://documentation.samson-connect.net/users/latest/documents/index.md), which means that you can easily **save, load, and share** your presentations and animations. You can check for some shared documents with presentations and animations on [SAMSON Connect - Documents](https://www.samson-connect.net/documents) where users can share their documents. Let's see an example - we will try one of the presentations shared on [SAMSON Connect - Documents](https://www.samson-connect.net/documents): Copy this link and, in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), click on **Home > Download** (1): 1. , : `Ctrl`+`Alt`+`O`, : `Cmd`+`Alt`+`O` And paste the link in the pop-up dialog: In a moment, it will download this shared document into your [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). Double-click on the Presentation node in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) and it will open the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). Now, click `Space` to start and stop the presentation or use the [animator's controls](#animator-controls) on the top-center of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). Let's first briefly see what the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator) consists off and then we will see how to create presentations. ## Animator The **Animator** makes it possible to create, edit, and play presentations, and export them as movies. To open the **Animator**, go to **Interface > Animator** (1) or if you already have a [presentation](https://documentation.samson-connect.net/users/latest/presenting/index.md) in the [document](https://documentation.samson-connect.net/users/latest/documents/index.md) simply double-click on it. 1. , : `Ctrl`+`7`, : `Cmd`+`7` When no presentation is opened in the Animator, it looks as follows: If you open a presentation in the Animator you should see the **Track view** populated with tracks of animations that are part of the presentation. Let's see in detail what the Animator consists off. ### Controls In the top part of the Animator, you can find its controls (from left to right): - **grid and angle snapping** govern how some animations related to movements operate - **presentation controls**: play mode (Once, Loop, Bounce), go to the beginning, go to the previous frame, play back, the current frame, play forward, go to the next frame, go to the last frame, frame duration in seconds - **fit in** the **Track view** with animation tracks; **zoom in/out** on animation tracks - the **begin and the end frames** of the presentation - global **presentation preferences**, see [Presentation options](#presentation-options) ### Track view In the central part of the Animator, you can see the **Track view** with animation tracks. When a presentation is being edited in the Animator, its animations are visible in the **Track view**. Each animation corresponds to a track, and may be composed of one or more **keyframes** (represented as circles on the track), i.e. **key events** that happen at specific frames of a presentation. Different types of animations have different colors of tracks to make it easier to distinguish between them. The number of keyframes depends on the animation itself. For example, for some animations, there are only two keyframes showing the first and the last key event of the animation, basically, where the animation starts and ends. ### Animation panel In the right part of the Animator, you can find the **Animation panel** with a list of available animations which are split into six categories (you can switch between them using buttons in the top part): - **Motion animations**: for docking, assembling, etc. - **Camera animations**: orbit, custom paths, etc. - **Entrance effects**: appearing, showing, etc. - **Exit effects**: disappearing, hiding, etc. - **Highlighting effects**: e.g. pulsing effects - **Other animations**: e.g. to pause and stop a presentation, as well as to change backgrounds and display background images such as presentation slides The buttons on the bottom of the **Animation panel** allow you to change the view of the animation list: zoom in, zoom out, switch between the list and image views. You can also search for animations using the search box on the top of the **Animation panel**. ### Preview The Animator allows you to easily preview the impact of your design decisions by letting you interactively choose the current presentation frame either using the controls in the top part of the Animator or by choosing the frame directly in the Track view. ## Adding a presentation You can add a presentation via the **Visualization > Add > Presentation**. This will also open the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). Or, open the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator) and simply double-click in it on an animation you want to add to the presentation. You should see a new presentation node added in the [document](https://documentation.samson-connect.net/users/latest/documents/index.md). For a newly added presentation, the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator) shows an empty animation track view where you can add animations. By default, the duration of the presentation is set to 180 frames. You can modify the duration of the presentation but the maximum number of frames is limited depending on the [Plans](https://documentation.samson-connect.net/users/latest/samson-connect/#pricing). The **Animator** provides access to all animation capabilities including the creation of a presentation, saving movies and frames, and adding animation effects. ## Animations [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides a wide variety of animations making it easy to create complex animations, [presentations](https://documentation.samson-connect.net/users/latest/presenting/index.md), and movies. Different animations act on different objects - some act on [cameras](https://documentation.samson-connect.net/users/latest/camera/index.md), some act on nodes like [structural models](https://documentation.samson-connect.net/users/latest/models/#structural-models), [visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models), meshes, and [labels](https://documentation.samson-connect.net/users/latest/labeling/index.md). The animations are split into the following categories: - [Motion animations](#motion-animations): for docking, assembling, etc. - [Camera animations](#camera-animations): orbit, custom paths, etc. - [Entrance effects](#entrance-and-exit-effects): appearing, showing, etc. - [Exit effects](#entrance-and-exit-effects): disappearing, hiding, etc. - [Highlighting animations](#highlighting-effects): e.g. pulsing effects - [Other animations](#other-animations): e.g. to pause and stop a presentation, as well as to change backgrounds and display background images such as presentation slides The animations can be found in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator) : **Animations are applied in correspondence with their order in the presentation** as seen in the [document](https://documentation.samson-connect.net/users/latest/documents/index.md). This means that if you have, for example, several camera animations at the same frame then they will be applied consecutively and the state of the camera will correspond to the last camera animation applied at that frame. You can always changed the order of animations in a presentation - simply use the drag-and-drop mechanism. ### Motion animations - [Assemble](https://documentation.samson-connect.net/users/latest/animations/assemble/index.md) and [Disassemble](https://documentation.samson-connect.net/users/latest/animations/disassemble/index.md) - animate assembling of systems. - [Dock](https://documentation.samson-connect.net/users/latest/animations/dock/index.md) and [Undock](https://documentation.samson-connect.net/users/latest/animations/undock/index.md) - animate docking. - [Hold atoms](https://documentation.samson-connect.net/users/latest/animations/hold-atoms/index.md) - hold atoms positions fixed between two frames. - [Move atoms](https://documentation.samson-connect.net/users/latest/animations/move-atoms/index.md) - make atoms move freely; the animation will interpolate between the positions of the atoms to which the animation was applied. - [Play path](https://documentation.samson-connect.net/users/latest/animations/play-path/index.md) and [Play reverse path](https://documentation.samson-connect.net/users/latest/animations/play-reverse-path/index.md) - animate one or more trajectories. - [Record path](https://documentation.samson-connect.net/users/latest/animations/record-path/index.md) - record atoms trajectories along the presentation as a path. - [Rock](https://documentation.samson-connect.net/users/latest/animations/rock/index.md) - make a group of particles rock around its geometric center. - [Rotate](https://documentation.samson-connect.net/users/latest/animations/rotate/index.md) - make a group of particles rotate around its geometric center. - [Simulate](https://documentation.samson-connect.net/users/latest/animations/simulate/index.md) - perform a multiple-step simulation at each frame. Note If you use motion animations, then, preferably, for the structural nodes to which motion animations were applied you should also apply the [Hold atoms](https://documentation.samson-connect.net/users/latest/animations/hold-atoms/index.md) animation at frames where no motion animations other than the [Hold atoms](https://documentation.samson-connect.net/users/latest/animations/hold-atoms/index.md) animation are used. This is optional but might be necessary because positions of structural nodes can be changed when working with the [document](https://documentation.samson-connect.net/users/latest/documents/index.md) or when switching between frames of the presentation. It will ensure that these structural nodes have proper positions along the presentation. ### Camera animations - [Dolly camera](https://documentation.samson-connect.net/users/latest/animations/dolly-camera/index.md) - a dolly effect, i.e. zoom the camera between two frames with changing the camera's target point. - [Follow atoms](https://documentation.samson-connect.net/users/latest/animations/follow-atoms/index.md) - continuously follow the specified atoms. Both the camera target and the camera position move to preserve a constant distance between the camera and the atoms. - [Hold camera](https://documentation.samson-connect.net/users/latest/animations/hold-camera/index.md) - fix the camera at the certain position. Use this if you don't use other camera animations at some frames and you would like to have a certain view since the view can be changed while working with the document. - [Look at atoms](https://documentation.samson-connect.net/users/latest/animations/look-at-atoms/index.md) - continuously look at the specified atoms. Only the camera target moves while the camera position does not change. - [Move camera](https://documentation.samson-connect.net/users/latest/animations/move-camera/index.md) - create custom camera paths. - [Orbit camera](https://documentation.samson-connect.net/users/latest/animations/orbit-camera/index.md) - orbit around a system. - [Pedestal camera](https://documentation.samson-connect.net/users/latest/animations/pedestal-camera/index.md) - move the camera vertically between two keyframes (in the camera reference frame). - [Truck camera](https://documentation.samson-connect.net/users/latest/animations/truck-camera/index.md) - moves the camera horizontally between two keyframes (in the camera reference frame). - [Zoom camera](https://documentation.samson-connect.net/users/latest/animations/zoom-camera/index.md) - zoom the camera between two frames. Note Preferably, you should always have some camera animation at each frame to specify the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) position because the camera position can be changed when working with the [document](https://documentation.samson-connect.net/users/latest/documents/index.md). If you don't need to use any advanced camera animations then just use the [Hold camera](https://documentation.samson-connect.net/users/latest/animations/hold-camera/index.md) animation to have a defined static view of your system. This will ensure that the active camera has proper positions along the presentation. ### Entrance and Exit effects - [Appear](https://documentation.samson-connect.net/users/latest/animations/appear/index.md) and [Disappear](https://documentation.samson-connect.net/users/latest/animations/disappear/index.md) - make nodes progressively appear or disappear; can only be applied to nodes with the transparency attribute, e.g. structural nodes, visual models, meshes, and labels. - [Reveal atoms](https://documentation.samson-connect.net/users/latest/animations/reveal-atoms/index.md) and [Conceal atoms](https://documentation.samson-connect.net/users/latest/animations/conceal-atoms/index.md) - make atoms appear or disappear progressively between two frames. - [Show](https://documentation.samson-connect.net/users/latest/animations/show/index.md) and [Hide](https://documentation.samson-connect.net/users/latest/animations/hide/index.md) - show or hide nodes at the current frame. - [Shown](https://documentation.samson-connect.net/users/latest/animations/shown/index.md) and [Hidden](https://documentation.samson-connect.net/users/latest/animations/hidden/index.md) - make nodes shown or hidden between two frames. Note Preferably, to make sure that all the nodes are shown/hidden as expected at each frame, you should always specify what nodes should be shown or hidden at frames where no other Entrance, Exit, or Highlighting effects are applied to those nodes. This is optional but might be necessary because the visibility or transparency of nodes can be changed when working with the [document](https://documentation.samson-connect.net/users/latest/documents/index.md) or when switching between frames of the presentation. It will ensure that these structural nodes have proper visibility along the presentation. ### Highlighting effects - [Flash](https://documentation.samson-connect.net/users/latest/animations/flash/index.md) - make nodes appear at the begin keyframe and disappear at the end keyframe by changing their visibility. - [Pulse](https://documentation.samson-connect.net/users/latest/animations/pulse/index.md) - make nodes progressively appear then disappear by changing their transparency. It can only be applied to nodes with the transparency attribute, e.g. structural nodes, visual models, meshes, and labels. ### Other animations - [Pause](https://documentation.samson-connect.net/users/latest/animations/pause/index.md) - pause the presentation at a given frame for a given number of seconds which can be specified in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). - [Stop](https://documentation.samson-connect.net/users/latest/animations/stop/index.md) - stop the presentation at a given frame. To resume the presentation press `Space` or the Play button in [animator's controls](#animator-controls). You can use this, for example, to subdivide your presentation into slides. - [Set background](https://documentation.samson-connect.net/users/latest/animations/set-background/index.md) - set background between two frames; you can also display background images such as presentation slides. Please see the [Animations](https://documentation.samson-connect.net/users/latest/animations/index.md) section for the description of animations available in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). ## Adding animations Let's now create some animations. If you would like to repeat the steps below, load `1AF6` molecule using **Home > Fetch** which will download it from RCSB PDB. Then [apply a Ribbons (secondary structure) visual model](https://documentation.samson-connect.net/users/latest/visualizing/#adding-visual-models) to it. Let's see, for example, how to add the [Orbit camera](https://documentation.samson-connect.net/users/latest/animations/orbit-camera/index.md) animation. First, position the camera in the plane in which you want it to be rotated around the object. Note, that the rotation plane will be defined differently whether you have the grid switched on or off. You can later adjust the rotation plane using the animation controllers. Then, double-click on the **Orbit camera** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). By default, camera animations are applied to the active camera. How the camera animations behave also depends on whether you have the grid in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) or not. Those options can be changed in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) for each camera animation. Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` You can click on play or change the frames in the [Track view](#animator-track-view) to see how the presentation would look like. All the camera animations have specialized **camera controllers** allowing for fine positioning of the camera: the central point, camera orientations, etc. In the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md), you can see the associated keyframe numbers shown near the keyframe camera animation controllers. Let's see, for example, how can the Orbit camera positioning be adjusted. Note, if you don't see the camera controllers, you might need to zoom out in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) (use the mouse scroll button or press `Ctrl`/`Cmd` + `-`). While editing camera positions, **Thumbnails** automatically appear at the bottom of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) to help you frame the best shots. **Thumbnails** are shown for the currently modified keyframe and for the next and previous keyframes (if any) of the currently modified camera animation. Let's see how it looks like with an example of the [Move camera](https://documentation.samson-connect.net/users/latest/animations/move-camera/index.md) animation. Animations have various options that can be changed in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). For that, select an animation in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) and open the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) (1). 1. **Interface > Inspector**, , : `Ctrl`+`2`, : `Cmd`+`2` Let's now make the structural representation of the molecule progressively disappear during the presentation. For that, first, select the structural model in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view), then double-click on the **Disappear** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` You can move the animation's keyframes in the [Track view](#animator-track-view) to alter the animation's behavior. Simply select them and move as shown above. Let's now make the Ribbons visual model progressively appear during the presentation. For that, first, select the Ribbons visual model in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view), then double-click on the **Appear** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). ## Editing a presentation To view and edit a presentation in the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator), double-click on the presentation in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) or press **Edit presentation in Animator** in its context menu. You can view and edit in the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator) only a single presentation at a time. To change the order of animations within a presentation, move them using the drag-and-drop mechanism directly in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view). To delete an animation from a presentation, *right-click* on the animation either in the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator) or in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) and, in the context menu, click **Erase**. ## Animation controllers Some camera and motion animations (e.g., [Move camera](https://documentation.samson-connect.net/users/latest/animations/move-camera/index.md) and [Move atoms](https://documentation.samson-connect.net/users/latest/animations/move-atoms/index.md) animations) have their controllers shown in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). You can hide/show those controllers by checking/unchecking this animation in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) or by right-clicking on it and, in the context menu, clicking **Hide/Show animation controllers**. See [Adjusting camera positions](https://documentation.samson-connect.net/users/latest/presenting/#animations-adjusting-camera-positions) on how to use camera animation controllers to adjust camera positions. By default, when playing a presentation or exporting it in a movie or in frames the animation controllers will be hidden - you can modify this in [Preferences > Rendering > Presentations](https://documentation.samson-connect.net/users/latest/preferences/#presentations). ## Adjusting camera positions Most of the camera animations have specialized **camera controllers** allowing for fine positioning of the camera: the target point, camera orientations, etc. In the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md), you can see the associated keyframe numbers shown near the keyframe camera animation controllers. Let's see how it looks like with an example of the Move camera animation. Note, if you don't see the camera controllers, you might need to zoom out in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) (use the mouse scroll button or press `Ctrl`/`Cmd` + `-`). While editing camera positions, **Thumbnails** automatically appear at the bottom of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) to help you frame the best shots. **Thumbnails** are shown for the currently modified keyframe and for the next and previous keyframes (if any) of the currently modified camera animation. ## Easing curve Some animations have parameters that specify the rate of change of some parameters along the animation which are governed by easing functions. In that case, you can choose which easing function/curve will be used. You can check the web-page to see how easing functions change a parameter over time - hover above an easing function to see how it changes. ## Setting a watermark Depending on the [Plans](https://documentation.samson-connect.net/users/latest/samson-connect/#pricing), you can remove the [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) watermark and set your own watermark in the [Presentation options](#presentation-options). You can also change the background and set images as the background in [Preferences > Rendering > Background](https://documentation.samson-connect.net/users/latest/preferences/#background) or using the **Set background** animation if you would like to switch between various backgrounds in the presentation. ## Exporting a movie To save a presentation as a movie, click the **Save movie** button in the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). In the **Save as...** dialog, choose the movie format (mp4, gif, webm) and where to save it. The way the movie will be saved might depend on the global [Presentation options](#presentation-options). ## Presentation options Presentations have a number of global rendering [options](https://documentation.samson-connect.net/users/latest/preferences/#presentations) that can be accessed and modified via **Interface > Preferences > Rendering > Presentations** or by clicking on the settings button in the top-right corner of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). ## Examples See more examples in [What's new in SAMSON 2021](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2021/index.md). Some examples of presentations available on [SAMSON Connect - Documents](https://www.samson-connect.net/documents): - [1AF6 - Fly around](https://www.samson-connect.net/documents/858bd00b-80f6-4001-8def-eebbf9f09a9b) - uses [Move camera](https://documentation.samson-connect.net/users/latest/animations/move-camera/index.md), [Appear](https://documentation.samson-connect.net/users/latest/animations/appear/index.md), and [Conceal atoms](https://documentation.samson-connect.net/users/latest/animations/conceal-atoms/index.md) animations - [1AF6 - Fly around - 2](https://www.samson-connect.net/documents/f7dfa5e2-c6af-4a7a-bdf6-30ca2afeb661) - uses [Move camera](https://documentation.samson-connect.net/users/latest/animations/move-camera/index.md), [Appear](https://documentation.samson-connect.net/users/latest/animations/appear/index.md), [Disappear](https://documentation.samson-connect.net/users/latest/animations/disappear/index.md), and [Conceal atoms](https://documentation.samson-connect.net/users/latest/animations/conceal-atoms/index.md) animations - [1AVX - Orbit around assembly](https://www.samson-connect.net/documents/5ef49e26-1acd-427b-ac30-e7af6421cc16) - uses [Assemble](https://documentation.samson-connect.net/users/latest/animations/assemble/index.md), [Appear](https://documentation.samson-connect.net/users/latest/animations/appear/index.md), and [Orbit camera](https://documentation.samson-connect.net/users/latest/animations/orbit-camera/index.md) animations - [2AZ8 - Dock animation](https://www.samson-connect.net/documents/aad9c1a7-3200-48e9-8ee8-0d74bc59657b) - uses [Dock](https://documentation.samson-connect.net/users/latest/animations/dock/index.md), [Hold atoms](https://documentation.samson-connect.net/users/latest/animations/hold-atoms/index.md), [Appear](https://documentation.samson-connect.net/users/latest/animations/appear/index.md), and [Move camera](https://documentation.samson-connect.net/users/latest/animations/move-camera/index.md) animations - [2BRD - Rock animation](https://www.samson-connect.net/documents/54a5e67a-0661-4c09-8c70-b967318b4154) - uses the [Rock](https://documentation.samson-connect.net/users/latest/animations/rock/index.md) animation - [2XQ6 - Assemble animation](https://www.samson-connect.net/documents/fbf80d12-d964-4a15-b385-207aca3b2792) - uses [Assemble](https://documentation.samson-connect.net/users/latest/animations/assemble/index.md), [Hold atoms](https://documentation.samson-connect.net/users/latest/animations/hold-atoms/index.md), [Appear](https://documentation.samson-connect.net/users/latest/animations/appear/index.md), [Disappear](https://documentation.samson-connect.net/users/latest/animations/disappear/index.md), and [Move camera](https://documentation.samson-connect.net/users/latest/animations/move-camera/index.md) animations - [5SAT - Dock animation](https://www.samson-connect.net/documents/a9f2b952-e2e7-4800-b8c4-28152fe313a5) - uses [Dock](https://documentation.samson-connect.net/users/latest/animations/dock/index.md), [Hold atoms](https://documentation.samson-connect.net/users/latest/animations/hold-atoms/index.md), [Appear](https://documentation.samson-connect.net/users/latest/animations/appear/index.md), [Disappear](https://documentation.samson-connect.net/users/latest/animations/disappear/index.md), [Move camera](https://documentation.samson-connect.net/users/latest/animations/move-camera/index.md), and [Hold camera](https://documentation.samson-connect.net/users/latest/animations/hold-camera/index.md) animations - [Multi-walled nanotube animation](https://www.samson-connect.net/documents/6c0b4c95-ed67-491f-830e-c7fd7810978b) - uses [Move atoms](https://documentation.samson-connect.net/users/latest/animations/move-atoms/index.md), [Appear](https://documentation.samson-connect.net/users/latest/animations/appear/index.md), [Disappear](https://documentation.samson-connect.net/users/latest/animations/disappear/index.md), [Move camera](https://documentation.samson-connect.net/users/latest/animations/move-camera/index.md), and [Hold camera](https://documentation.samson-connect.net/users/latest/animations/hold-camera/index.md) animations - [Nanotube - Keyframed animation](https://www.samson-connect.net/documents/31bb8a79-2968-4b86-bf11-d60172d94055) - uses the [Move atoms](https://documentation.samson-connect.net/users/latest/animations/move-atoms/index.md) animation - [NU1000 (CCDC-1580411) - Fly around](https://www.samson-connect.net/documents/a264e668-0865-41f2-8e14-80bf27a3db2e) - uses [Orbit camera](https://documentation.samson-connect.net/users/latest/animations/orbit-camera/index.md) and [Move camera](https://documentation.samson-connect.net/users/latest/animations/move-camera/index.md) animations ## Related pages - [Animations](https://documentation.samson-connect.net/users/latest/animations/index.md): look up individual animation effects. - [Rendering using Cycles](https://documentation.samson-connect.net/users/latest/rendering/index.md): prepare final-quality rendered images or movies. - [Visualize and present](https://documentation.samson-connect.net/users/latest/visualize-and-present/index.md): return to the visualization and output hub. # User Guide - Simulate and analyze # Simulate and analyze Use this topic when you want SAMSON to do more than static editing and viewing. It covers interactive simulation, path and trajectory analysis, and cloud workflows for jobs that run beyond the local application. Follow the full sequence if you are starting from a structure, or jump straight to analysis if you already have a path. ## Who this topic is for - Users launching interactive simulations - Users analyzing saved paths or trajectories - Users running remote jobs - Users comparing structure evolution over time ## What you will be able to do afterward - Add and run simulators - Save conformations and paths - Analyze trajectories with Path Analyzer - Analyze protein-ligand interactions with Interaction Designer - Monitor and retrieve cloud job results ## Recommended reading order 1. [Modeling and Simulation](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md) - Start here to add simulators, run interactive modeling, and create conformations or paths. `Foundational.` 1. [Path Analyzer](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md) - Continue here once you have a path or trajectory and want observables, plots, and dashboards. `Foundational for analysis.` 1. [Interaction Designer](https://documentation.samson-connect.net/users/latest/interaction-designer/index.md) - Continue here if you want to analyze protein-ligand interactions. `Foundational for analysis.` 1. [Cloud computations](https://documentation.samson-connect.net/users/latest/cloud/index.md) - Read this when your workflow depends on remote jobs, monitoring, or result retrieval. `Optional / task-specific.` ## Read this first Start with [Modeling and Simulation](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md). If you already have a path or imported trajectory and only need analysis, you can jump directly to [Path Analyzer](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md). ## You can skip this for now if... - You do not yet have a path or trajectory, in which case you can skip [Path Analyzer](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md) - You are working locally and do not need remote jobs, in which case you can skip [Cloud computations](https://documentation.samson-connect.net/users/latest/cloud/index.md) ## Suggested paths - **Interactive modeling**: [Modeling and Simulation](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md) - **Generate then analyze a path**: [Modeling and Simulation](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md) -> [Path Analyzer](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md) - **Simulate then analyze interactions**: [Modeling and Simulation](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md) -> [Interaction Designer](https://documentation.samson-connect.net/users/latest/interaction-designer/index.md) - **Run a cloud workflow**: [Cloud computations](https://documentation.samson-connect.net/users/latest/cloud/index.md) ## Where to go next - [Visualize and present](https://documentation.samson-connect.net/users/latest/visualize-and-present/index.md) - Continue here when you want to communicate results through clearer visuals, figures, or movies. - [Share and collaborate](https://documentation.samson-connect.net/users/latest/share-and-collaborate/index.md) - Go here when you need to share jobs, documents, or collaboration access. - [Automate and extend](https://documentation.samson-connect.net/users/latest/automate-and-extend/index.md) - Continue here when you want scripted analysis, automation, or extension-based workflows. ## Notes [Cloud computations](https://documentation.samson-connect.net/users/latest/cloud/index.md) requires Computing Credits, and [Path Analyzer](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md) expects a path in the active document. # Modeling and Simulation Use this page to add simulators, run interactive modeling, and understand how SAMSON stores models, simulators, conformations, and paths in a [document](https://documentation.samson-connect.net/users/latest/documents/index.md). [Interactive tutorial](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md) in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) (**Help > Tutorials**): *"Modeling: launching simulations"*. Tip Use [Models](https://documentation.samson-connect.net/users/latest/models/index.md) to learn about model nodes in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). ## What this page covers This page introduces the models and simulation concepts used in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) and helps you navigate to the right workflow or reference page next. ## Simulators **Simulators** (potentially interactive ones) are used to build physically-based models, and predict properties. A simulator is applied to a [dynamical model](https://documentation.samson-connect.net/users/latest/models/#dynamical-models), an [interaction model](https://documentation.samson-connect.net/users/latest/models/#interaction-models), and a [state updater](https://documentation.samson-connect.net/users/latest/models/#state-updaters). When you start interactive simulation, [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) goes through all simulators added to the [document](https://documentation.samson-connect.net/users/latest/documents/index.md) and calls their [state updaters](https://documentation.samson-connect.net/users/latest/models/#state-updaters) to update the state of the attached [dynamical model](https://documentation.samson-connect.net/users/latest/models/#dynamical-models). The simulator contains [dynamical model](https://documentation.samson-connect.net/users/latest/models/#dynamical-models), [interaction model](https://documentation.samson-connect.net/users/latest/models/#interaction-models), [state updater](https://documentation.samson-connect.net/users/latest/models/#state-updaters), and synchronizes these different models. In [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), force fields are named [interaction models](https://documentation.samson-connect.net/users/latest/models/#interaction-models) and integrators are named [state updaters](https://documentation.samson-connect.net/users/latest/models/#state-updaters). Simulations in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) are interactive in the sense that you can still act on the atoms while the simulation is running. ## Applying simulators **Prerequisites**: Use [Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md) to learn how to build molecules in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). Let's apply a [simulator](#simulators) to a simple system, to see how the simulation affects its geometry. Add any molecule from the [Asset Browser](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser) or simply switch to the **Add editor** () in the left-side menu of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) and click anywhere in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) to add an atom (by default it should be Carbon). To add a simulator: 1. click **Edit > Add simulator** (shortcut: `Ctrl`+`Shift`+`M` on Windows and Linux, `Cmd`+`Shift`+`M` on Mac). 1. Select an [interaction model](https://documentation.samson-connect.net/users/latest/models/#interaction-models): **Universal Force Field**. 1. Select a [state updater](https://documentation.samson-connect.net/users/latest/models/#state-updaters): **Interactive modeling**. 1. Specify the simulator name if you would like to. 1. Press **OK**. Note See [doi:10.1002/jcc.24309](https://doi.org/10.1002/jcc.24309) for details on the Universal Force Field (UFF) implementation in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). You should see a property window for the Universal Force Field [interaction model](https://documentation.samson-connect.net/users/latest/models/#interaction-models) and you can view the properties of the Interactive modeling [state updater](https://documentation.samson-connect.net/users/latest/models/#state-updaters) by [selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) it and opening the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector): To launch the simulation: - click **Edit > Start simulation** - shortcut: `X`. To stop the simulation: - click **Edit > Stop simulation** - shortcut: `X`. The newly created [simulator](#simulators) including the [interaction model](https://documentation.samson-connect.net/users/latest/models/#interaction-models), [state updater](https://documentation.samson-connect.net/users/latest/models/#state-updaters), and the associated [dynamical model](https://documentation.samson-connect.net/users/latest/models/#dynamical-models) will be added in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view): In the image above you can see the following: - A [structural model](https://documentation.samson-connect.net/users/latest/models/#structural-models) that contains atoms and bonds. - Particle system - a [dynamical model](https://documentation.samson-connect.net/users/latest/models/#dynamical-models) to which the simulator is applied. It contains the degrees of freedom of your system. - An [interaction model](https://documentation.samson-connect.net/users/latest/models/#interaction-models) (force field) used in the simulator. It contains the computed energy and forces. - Simulator with references to the [dynamical model](https://documentation.samson-connect.net/users/latest/models/#dynamical-models), [interaction model](https://documentation.samson-connect.net/users/latest/models/#interaction-models), and the Interactive modeling [state updater](https://documentation.samson-connect.net/users/latest/models/#state-updaters). Select an atom in the Methane molecule and try to drag it slowly, you should see the interactive simulation in action - the molecule should follow the dragged atom. For the Interactive modeling [state updater](https://documentation.samson-connect.net/users/latest/models/#state-updaters) you can modify the step size and the number of steps. You can increase the number of simulations steps to increase the stiffness of the system. Try modifying the number of steps and the step size for the Interactive modeling [state updater](https://documentation.samson-connect.net/users/latest/models/#state-updaters). ## Simulation examples ### Building a carbon nanopore In the video below, you can see an example of an interactive building of a carbon nanopore: draw a graphene sheet and a nanotube using the corresponding editors, remove some atoms, and use the [Brenner reactive force field](https://www.samson-connect.net/extensions/ad608cb6-6971-7cd4-6fcc-34531998e743) (1) during interactive minimization to meld them. 1. The **Brenner potential** ([Brenner et al. A second-generation reactive empirical bond order (REBO) potential energy expression for hydrocarbons, Journal of Physics: Condensed Matter, Volume 14, Number 4, 2002](https://doi.org/10.1088/0953-8984/14/4/312)) is a many-body potential-energy expression with a chemical bond description, which produces realistic geometries for hydrocarbon systems. ### Molecular geometry optimization Below is the video of a quick molecular geometry optimization using [FIRE state updater](https://www.samson-connect.net/extensions/8ec255b0-7326-0bed-366e-40be71c1d160) (1): when this carbon nanotube is sliced, it quickly relaxes to a mostly flat graphene sheet. 1. The **Fast Inertial Relaxation Engine (FIRE)** is an efficient optimizer for molecular structures. Its implementation is based on [Bitzek E., Koskinen P., Gahler F., Moseler M., Gumbsch P. Structural relaxation made simple. Physical review letters 97.17 (2006): 170201](https://doi.org/10.1103/PhysRevLett.97.170201). ## Conformations In [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), **conformations** are used to store a state (positions) of a [structural model](https://documentation.samson-connect.net/users/latest/models/#structural-models) or a group of atoms. It is like a single frame in a trajectory. To save the current state of a [structural model](https://documentation.samson-connect.net/users/latest/models/#structural-models) or group of atoms: 1. [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) this [structural model](https://documentation.samson-connect.net/users/latest/models/#structural-models) or this group of atoms. 1. Click on **Edit > Conformation** (shortcut: `S`). A new conformation node should appear in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view): You can restore a conformation by double-clicking on it in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) or *right-click* on it and choose **Restore conformation**: You can create a path (a trajectory) from a set of conformations given that they store information for the same set of atoms: 1. [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a set of conformations. 1. Right-click on the selection and, in the context menu, go to **Conformation > Create path from conformations**. Once a path has been created, you can explore it further with [Path Analyzer](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md). Note When you save a [document](https://documentation.samson-connect.net/users/latest/documents/index.md) in a **.sam** or **.samx** file, then all the conformations are saved as well. ## Related pages - [Minimizing](https://documentation.samson-connect.net/users/latest/minimizing/index.md) - [Path Analyzer](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md) - [Models](https://documentation.samson-connect.net/users/latest/models/index.md) # Path Analyzer **Path Analyzer** is a SAMSON app for exploring paths and molecular dynamics trajectories directly inside your document. It combines an **Analysis Builder**, an **Analysis Tray**, and an interactive **dashboard** so you can go from a selection to a useful plot in just a few clicks. Use it to measure geometric observables, inspect structural changes, compare saved analyses, build density maps, and explore energy landscapes without exporting your data first. ## What this page covers This page explains what Path Analyzer is best used for, how its cards fit together, and which detailed reference page to open for each observable. ## Opening Path Analyzer After installing the **Path Analyzer** extension, open it from **Home > Apps** and choose **Path Analyzer**. Path Analyzer works with paths already present in the active document. These paths may come, for example, from imported trajectories, from external tools, from conformations converted to a path, or from subset paths created inside Path Analyzer itself. ## The main parts of the interface - **Analysis Builder**: choose an observable, choose a path when needed, define selections, and add a new card. - **Analysis Tray**: keep reusable saved analyses that can later be combined into a **Custom scatter**, **Density curve**, **2D density map**, or **Energy landscape**. - **Dashboard**: explore the resulting cards, move and resize them, change settings, and export them. ## Typical workflow 1. Choose an **Observable** in the builder. 1. Choose a **Path** when the analysis is path-based. 1. Define the required targets. For example, two groups for **Distance**, a measured set and a fit set for **RMSD**, or saved analyses from the **Analysis Tray** for **Custom scatter**. 1. Click the action button to create the card. The button label adapts to the selected observable, for example **Add Time Series**, **Add Scatter**, **Add Heatmap**, **Add RDF**, or **Add Energy Landscape**. 1. Reuse the saved analysis later if you want to derive higher-level views from it. ## How Path Analyzer interprets a selected group This is important: a selected group is **not** always converted the same way in every analysis. - In **Angle** and **Dihedral**, each selected group is converted to a single representative position. One atom gives one atomic position; a multi-atom group is reduced to its **center of mass**. - In **Distance** with the `Centroids` mode, each group is represented by its **centroid**, i.e. the simple geometric average of the atom positions. - In **Distance** with `Minimum`, `Minimum along X`, `Minimum along Y`, or `Minimum along Z`, Path Analyzer does **not** reduce the group to one point. Instead, it compares the full atom sets and takes the minimum pairwise separation. - In analyses such as **RMSD**, **RMSF**, **Contacts**, **Contact persistence**, and **RDF**, Path Analyzer generally works on the full selected atom sets rather than replacing each group by a single representative point. This means that changing the size or composition of a selection can affect the result in very different ways depending on the chosen observable. ## What Path Analyzer does especially well - It keeps plots linked to the current path whenever the analysis is frame-resolved. - It automatically uses time on the x-axis when the path provides meaningful time values, and falls back to frame indices otherwise. - It lets you keep several complementary cards side by side, for example a **Distance** series, a **RMSD** series, and an **Energy landscape** built from those saved analyses. - It stays useful both for quick inspection and for publication-oriented export. ## Interacting with the dashboard - Clicking a point in a frame-resolved time series or scatter plot moves the source path to the corresponding frame. - Clicking a cell in **RMSD (pairwise)** moves the path to the later of the two selected frames. - Double-clicking certain plots selects the corresponding feature in SAMSON, for example a residue in a **Ramachandran** plot or a feature in a **RMSF** profile. - Brushing points can create a frame subset, and that subset can be promoted to a new path. - Cards can be moved and resized freely in the dashboard. ## Card settings and export Each card can expose settings that are specific to the selected analysis: - axis titles - series colors - heatmap color scale - energy, force, or velocity units - energy component and energy view mode - Ramachandran background - current-frame indicator visibility - contour-line visibility and color for energy landscapes You can export each card as: - `CSV` - `PNG` - `SVG` ## Picking the right analysis ### Geometry - [Distance](https://documentation.samson-connect.net/users/latest/references/path-analyzer/distance/index.md): follow a separation between two groups. - [Angle](https://documentation.samson-connect.net/users/latest/references/path-analyzer/angle/index.md): monitor a three-point angle. - [Dihedral](https://documentation.samson-connect.net/users/latest/references/path-analyzer/dihedral/index.md): monitor a torsion angle defined by four groups. ### Structural and trajectory observables - [RMSD](https://documentation.samson-connect.net/users/latest/references/path-analyzer/rmsd/index.md) - [RMSD (pairwise)](https://documentation.samson-connect.net/users/latest/references/path-analyzer/rmsd-pairwise/index.md) - [RMSF](https://documentation.samson-connect.net/users/latest/references/path-analyzer/rmsf/index.md) - [Contacts](https://documentation.samson-connect.net/users/latest/references/path-analyzer/contacts/index.md) - [Contact persistence](https://documentation.samson-connect.net/users/latest/references/path-analyzer/contact-persistence/index.md) - [Ramachandran](https://documentation.samson-connect.net/users/latest/references/path-analyzer/ramachandran/index.md) - [SASA](https://documentation.samson-connect.net/users/latest/references/path-analyzer/sasa/index.md) - [Radius of gyration](https://documentation.samson-connect.net/users/latest/references/path-analyzer/radius-of-gyration/index.md) - [Asphericity](https://documentation.samson-connect.net/users/latest/references/path-analyzer/asphericity/index.md) - [Shape parameter](https://documentation.samson-connect.net/users/latest/references/path-analyzer/shape-parameter/index.md) - [Secondary structure content](https://documentation.samson-connect.net/users/latest/references/path-analyzer/secondary-structure-content/index.md) ### Distribution, density, and comparison - [RDF](https://documentation.samson-connect.net/users/latest/references/path-analyzer/rdf/index.md) - [Density curve](https://documentation.samson-connect.net/users/latest/references/path-analyzer/density-curve/index.md) - [2D density map](https://documentation.samson-connect.net/users/latest/references/path-analyzer/density-map-2d/index.md) - [Custom scatter](https://documentation.samson-connect.net/users/latest/references/path-analyzer/custom-scatter/index.md) ### Energetics and dynamics - [Energy](https://documentation.samson-connect.net/users/latest/references/path-analyzer/energy/index.md) - [Energy landscape](https://documentation.samson-connect.net/users/latest/references/path-analyzer/energy-landscape/index.md) - [Average force](https://documentation.samson-connect.net/users/latest/references/path-analyzer/average-force/index.md) - [Average velocity](https://documentation.samson-connect.net/users/latest/references/path-analyzer/average-velocity/index.md) Tip - Start with scalar analyses such as **Distance**, **RMSD**, **Energy**, or **Radius of gyration**. They combine especially well later. - For **RMSD** and **RMSF**, choose the fit set deliberately: it defines what motion is treated as overall rigid-body motion and what motion is treated as internal change. - For **Contacts** and **Contact persistence**, use chemically meaningful root selections such as residues, ligands, domains, or chains, so the map and timeline remain readable. - For **RDF**, provide a path with valid unit-cell information when possible, since that enables a properly normalized `g(r)`. - Use the [Path Analyzer reference](https://documentation.samson-connect.net/users/latest/references/path-analyzer/index.md) when you want details for one specific plot type. ## Related pages - [Path Analyzer Reference](https://documentation.samson-connect.net/users/latest/references/path-analyzer/index.md) - [Modeling and simulation](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md) - [Scripting](https://documentation.samson-connect.net/users/latest/scripting/index.md) # Interaction designer The [Interaction Designer](https://www.samson-connect.net/extensions/52fe9e27-19f3-093b-4f4f-4c6aff880a77) in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) makes it possible to **visualize molecular interactions in 2D** - such as protein-ligand interactions - in 2D, and **design molecules directly in 2D**. This functionality is seamlessly integrated with the 3D viewport, providing a tightly coupled 2D-3D environment for intuitive molecular exploration and design. The **Interaction Designer** has two main modes: - [Creating interaction diagrams](#create-interaction-diagrams): use the **Home > Diagram** command to automatically create an interaction diagram based on the current selection, or the whole document if nothing is selected. - [Creating new molecules in 2D](#create-new-molecules-in-2d): use the **Edit > Design** command to start a new molecule. The **Interaction Designer** keeps the 2D documents synchronized with the 3D viewport: selecting, adding, and removing atoms and fragments is performed in both 2D and 3D. Acknowledgments The **Interaction Designer** uses functionality from [RDKit](https://www.rdkit.org/). ## What this page covers This page explains how to use the Interaction Designer to create and edit 2D and 3D interaction diagrams inside [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). ## Create interaction diagrams Use the **Home > Diagram** command to **automatically create an interaction diagram** based on the current selection, or the whole document if nothing is selected. The **Interaction Designer** provides the following features when creating interaction diagrams: - Tight **integration with the 3D viewport**: select structures, atoms, and zoom on them. Click on an atom or structure to select it, double-click to zoom on it. - Show the **binding pocket** for protein-ligand interactions. - Show **solvent accessibility** of ligand atoms. - Show **interacting residues and structural groups**. See the [list of supported interactions](#supported-interactions). - **Editable 2D diagram**: - You can **move all labels and interaction symbols** to control the diagram layout, as well as the caption/legend. - You can **hide and show interactions** by clicking on their name or icon in the caption/legend. - You can **change the interaction colors** by double-clicking on their name or icon in the caption/legend. You can **restore the colors** in the **Interaction Designer** settings that you can access via its window title bar. Tip Use the bottom menu of the **Interaction Designer** to update the view and align the 2D and 3D views. You can zoom in/out by holding `Ctrl`/`Cmd` and using the scroll button of the mouse. To translate the diagram, hold either middle mouse button and right mouse button and move the mouse. ### Video tutorial You can learn how to create and edit 2D and 3D protein-ligand interaction diagrams from the following extract of the SAMSON 2025 webinar: ### Supported interactions The **Interaction Designer** aims to support the same types of interatomic contacts as the [arpeggio](https://github.com/PDBeurope/arpeggio) tool by the [PBDe team](https://pdbe.org/) and is validated against results from arpeggio and other tools. #### Atom-atom interactions | Interaction | Description | | ------------------- | ------------------------------------------------------------------------------------ | | Clash | The atom is involved in a steric clash. | | Covalent | The atom appears to be covalently bonded. | | van den Waals (VdW) | The van der Waals radius of the atom is interacting with one or more other atoms. | | VdW Clash | The van der Waals radius of the atom is clashing with one or more other atoms. | | Proximal | The atom is > the VdW interaction distance, but within 5 Angstroms of other atom(s). | | Hydrogen Bond | The atom forms a hydrogen bond. | | Weak Hydrogen Bond | The atom forms a weak hydrogen bond. | | Halogen Bond | The atom forms a halogen bond. | | Ionic | The atom may interact via charges. | | Metal Complex | The atom is part of a metal complex. | | Aromatic | An aromatic ring atom interacting with another aromatic ring atom. | | Hydrophobic | Hydrophobic interaction. | | Carbonyl | A carbonyl-carbon:carbonyl-carbon interaction. | | Polar | Less strict hydrogen bonding (without angle terms). | | Weak Polar | Less strict weak hydrogen bonding (without angle terms). | #### Atom-plane interactions | Interaction | Description | | -------------- | -------------------------------------------------------------------------------------------------------------- | | Carbon-(\\pi) | Weakly electropositive carbon atom - (\\pi) interactions \[[ref](https://doi.org/10.1016/j.bmc.2007.09.023)\] | | Cation-(\\pi) | Positively charged group - (\\pi) (aromatic ring) interactions \[[ref](https://doi.org/10.1002/prot.20417)\] | | Donor-(\\pi) | Hydrogen Bond donor - (\\pi) (aromatic ring) interactions \[[ref](https://doi.org/10.1016/j.bmc.2007.09.023)\] | | Halogen-(\\pi) | Halogen Bond donor - (\\pi) (aromatic ring) interactions \[[ref](https://doi.org/10.1073/pnas.0407607101)\] | | Sulfur-(\\pi) | Methionine sulfur - (\\pi) (aromatic ring) interactions \[[ref](https://doi.org/10.1074/jbc.M112.374504)\] | #### Plane-plane interactions See [Chakrabarti and Bhattacharyya, Geometry of nonbonded interactions involving planar groups in proteins (2007)](https://doi.org/10.1016/j.pbiomolbio.2007.03.016). #### Group-group/plane interactions | Interaction | Description | | ------------- | -------------------------------------------------------------------------------------------------------- | | (\\pi)-(\\pi) | Direct interactions between two (\\pi)-systems (aromatic rings) | | Amide-amide | Interactions between two amide groups | | Amide-(\\pi) | Interactions between amides and aromatic rings \[[ref]()\] | ## Create new molecules in 2D Use the **Edit > Design** command to start drawing a new molecule in 2D. Note The **Interaction Designer** keeps the 2D documents synchronized with the 3D viewport: selecting, adding, and removing atoms and fragments is performed in both 2D and 3D. Tip To learn about other ways to build molecules in SAMSON, especially in 3D, use [Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md). You can start building a molecule: - from scratch, - starting from a molecule in the active document, - starting from the current selection. In the left panel of the **Interaction designer**, click on **Add** - this will switch it into the building mode with the Carbon atom set as the default atom for building. Click anywhere in the designer window to add an atom. To add another atom, click on the atom to which you would like to connect it. Tip You can switch off the display of solvent accessibility by clicking on it in the legend. Tip Use the bottom menu of the **Interaction Designer** to update the view and align the 2D and 3D views. You can zoom in/out by holding `Ctrl`/`Cmd` and using the scroll button of the mouse. To translate the diagram, hold either middle mouse button and right mouse button and move the mouse. You can use any atom element or any fragment to build molecules in 2D. You can change to a different atom element or a fragment using the [Asset Browser](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser) (1). 1. The **Asset Browser** provides access to the assets (molecule fragments, etc.) included by default in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) together with the assets you can obtain from [SAMSON Connect](https://www.samson-connect.net/).\ To open it use: **Interface > Assets**, , : `Ctrl`+`4`, : `Cmd`+`4` ### Build with atoms You can **change to another atom element** via the **Assets Browser** in two ways. For H, C, N, O atoms, you can use one of the buttons at the bottom of the Asset Browser. For other atomic elements, open the **Periodic table** (1) and click on the desired element. 1. **Asset Browser > Periodic Table** or **Interface > Periodic Table**,\ , : `Ctrl`+`5`,\ : `Cmd`+`5` Note Clicking in the designer on an atom while having a different atom element chosen as the atom for building will modify the clicked atom type. ### Build with fragments To **use a fragment for building**, choose it from the **Assets Browser**. You can **change the pivot atom in the fragment** used for building. For that hold `Ctrl`/`Cmd` and choose the desired pivot atom. ### Erase atoms To erase atoms, click on **Erase** in the left panel of the **Interaction Designer** and then click on the atoms you want to delete. ## Export interaction diagrams and 2D sketched You can save your interaction diagrams and 2D drawings of molecules in various image formats, including png, jpg, jpeg, bmp, and svg. For that, click on **Save** in the bottom panel of the **Interaction Designer**. ## Related pages - [Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md) - [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) - [Measuring](https://documentation.samson-connect.net/users/latest/measuring/index.md) # Cloud computations Use this page to run, monitor, retrieve, and share cloud computations launched from [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), such as protein structure prediction using AlphaFold and NVIDIA BioNeMo Services or molecular dynamics simulations using GROMACS. Note Performing calculations in the cloud in SAMSON requires **Computing Credits**. [Refer](https://www.samson-connect.net/freeComputingCredits) friends and colleagues to the SAMSON Cloud Services to earn free Computing Credits. ## Job Manager You can manage the jobs launched in the Cloud using the **Job manager**. To open the **Job manager**, click on **Interface > Job manager** (1). 1. , : `Ctrl`+`6`, : `Cmd`+`6` The **Job manager** lets you: - Create jobs from SAMSON for extensions that provide such functionality. - Execute jobs in the cloud (start, pause, stop) and monitor them. - Get results back into SAMSON. To view the **job details** click on a job and they will be shown on the right side of the Job Manager. You can edit the job name and notes - they will be automatically synced with your [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) Account: You can **download all job files** by double-clicking the job: A job **Context menu** now gives you rapid access to local files (the ones that have already been downloaded), remote files (the ones stored in the cloud), as well as the job view on [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) (see: [Collaboration - Viewing and sharing jobs on SAMSON Connect](https://documentation.samson-connect.net/users/latest/collaboration/#sharing-jobs)). Note See an example on how to launch Jobs in the cloud: [GROMACS Wizard - Computing in the cloud](https://documentation.samson-connect.net/tutorials/gromacs-wizard/cloud/index.md) ## Viewing and sharing jobs on SAMSON Connect The jobs you run in the cloud from SAMSON (e.g., using AlphaFold, NVIDIA BioNeMo services, GROMACS, etc.) are accessible from [SAMSON Connect](https://www.samson-connect.net/), and you can control who has access to them. See: [Collaboration - Viewing and sharing jobs on SAMSON Connect](https://documentation.samson-connect.net/users/latest/collaboration/#sharing-jobs). ## Related pages - [Simulate and analyze](https://documentation.samson-connect.net/users/latest/simulate-and-analyze/index.md): choose between local simulation, trajectory analysis, and cloud workflows. - [Collaboration](https://documentation.samson-connect.net/users/latest/collaboration/index.md): manage job visibility and sharing permissions on [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). - [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md): manage account settings, computing credits, and shared resources. # User Guide - Share and collaborate # Share and collaborate Use this topic when your work needs to move beyond a local document. It starts with the account-level site workflows in SAMSON Connect, then continues to the collaboration features for profiles, groups, permissions, shared documents, and shared jobs. Read both if you are setting up collaboration from scratch, or jump straight to the collaboration page if your account is already in place. ## Who this topic is for - Users managing accounts, downloads, or Marketplace access - Users sharing documents - Users organizing teams or groups - Users controlling access to cloud jobs ## What you will be able to do afterward - Navigate the main sections of SAMSON Connect - Manage profiles and groups - Publish and access shared documents - Manage job visibility and permissions ## Recommended reading order 1. [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) - Start here for the website sections, account context, downloads, extensions, and shared resources. `Foundational.` 1. [Share documents](https://documentation.samson-connect.net/users/latest/share-documents/index.md) - Continue here when you need to share documents on [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) or download shared documents. `Foundational for collaboration workflows.` 1. [Collaboration](https://documentation.samson-connect.net/users/latest/collaboration/index.md) - Continue here when you need profiles, groups, permissions, shared documents, and shared jobs. `Foundational for collaboration workflows.` ## Read this first Start with [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). ## You can skip this for now if... - You only need downloads, Marketplace access, or account settings and are not sharing work yet, in which case you can skip [Collaboration](https://documentation.samson-connect.net/users/latest/collaboration/index.md) ## Suggested paths - **Account, downloads, and Marketplace**: [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) - **Share documents or jobs**: [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) -> [Share documents](https://documentation.samson-connect.net/users/latest/share-documents/index.md) -> [Collaboration](https://documentation.samson-connect.net/users/latest/collaboration/index.md) - **Groups and permissions**: [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) -> [Collaboration](https://documentation.samson-connect.net/users/latest/collaboration/index.md) ## Where to go next - [Work with structures](https://documentation.samson-connect.net/users/latest/work-with-structures/index.md) - Continue here after opening or downloading shared documents and you need to inspect or edit the contents. - [Simulate and analyze](https://documentation.samson-connect.net/users/latest/simulate-and-analyze/index.md) - Go here for cloud-job workflows, paths, and analysis. - [Automate and extend](https://documentation.samson-connect.net/users/latest/automate-and-extend/index.md) - Continue here when you want to share scripted documents or extend workflows with automation. ## Notes [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) explains the site sections and account context, while [Collaboration](https://documentation.samson-connect.net/users/latest/collaboration/index.md) covers profiles, groups, permissions, documents, and jobs. # Share documents Use [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) to share [documents](https://documentation.samson-connect.net/users/latest/documents/index.md) through [SAMSON Connect - Documents](https://www.samson-connect.net/documents). You can control who can access shared documents when you publish them or later from your account on [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). ## Downloading shared documents You can download [documents](https://documentation.samson-connect.net/users/latest/documents/index.md) shared in [SAMSON Connect - Documents](https://www.samson-connect.net/documents) by clicking **Home > Download** (1). 1. , : `Ctrl`+`Alt`+`O`, : `Cmd`+`Alt`+`O` ## Sharing documents You can also share your documents from [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) on [SAMSON Connect](https://www.samson-connect.net/) by clicking **Home > Publish** (1). 1. , : `Ctrl`+`Alt`+`S`, : `Cmd`+`Alt`+`S` In the dialog window, fill in the name of the document, its description, and choose the document visibility. For the **document visibility** you can choose one of the following options: - **Public** - everyone can use this document, but editing requires access rights. - **Hidden** - anyone with the link can use this document, but editing requires access rights. - **Restricted** - using or editing this document requires access rights. Then click **Publish document** and the document will be shared in [SAMSON Connect - Documents](https://www.samson-connect.net/documents) and the link to it will be provided in the same window. You can **access and manage all your shared documents** and the ones that have been shared with you in your account at [SAMSON Connect](https://www.samson-connect.net/) - see [Collaboration - Managing shared documents on SAMSON Connect](https://documentation.samson-connect.net/users/latest/collaboration/#managing-shared-documents-on-samson-connect). ## Next step - Continue with [Collaboration](https://documentation.samson-connect.net/users/latest/collaboration/index.md) if you need to manage access rights, groups, or shared documents on [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). # Collaboration Use this page when you need to collaborate through [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) and [SAMSON Connect](https://www.samson-connect.net/): create a profile, organize users into groups, publish documents, share cloud jobs, and control who can view or edit shared resources. ## What this page covers This page explains how to collaborate through [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) and [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md), including profiles, groups, shared documents, shared cloud jobs, and access permissions. Here is an overview of the collaboration areas: - **Profile**: create a user profile and make it public. - **Groups**: you can create an unlimited number of public or private groups, invite others, manage applications, etc. - **Documents**: you can upload an unlimited number of public or private documents on SAMSON Connect (the total size limit varies based on your SAMSON plan), and you can control who you share these documents with. - **Jobs**: the jobs you run in the cloud from SAMSON (e.g., using AlphaFold, NVIDIA BioNeMo services, GROMACS, etc.) are now accessible from SAMSON Connect, and you can control who has access to them. ## Use a related page instead when - You need the general website overview, downloads, Marketplace, or account-level navigation: use [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). - You only need the document publishing or download workflow: use [Share documents](https://documentation.samson-connect.net/users/latest/share-documents/index.md). - You need to launch, monitor, or retrieve cloud jobs from SAMSON: use [Cloud computations](https://documentation.samson-connect.net/users/latest/cloud/index.md). ## Editing your profile You can create a **public profile** with a **public handle of your choice** (act quickly to reserve yours!), an extensive bio (20,000 characters allowed!), and links to your social networks (LinkedIn, X, ResearchGate, GitHub, etc.). On [SAMSON Connect](https://www.samson-connect.net/), go to **User menu > Profile** to edit your profile: You can use Markdown to format your biography and include titles, links, images, etc. If public, your profile becomes accessible on SAMSON Connect: ## Creating and managing groups You can create (and manage) an unlimited number of private or public groups to easily share documents, jobs, extensions, etc. Go to **Groups** to manage groups you own or belong to: Provided you are a **group owner**, editing a group is similar to editing your profile. You can control the **group visibility**, as well as **how others join your group**: Being a group owner also lets you **edit group memberships**. In particular, you can change **group roles** and **membership end dates**: To add a new member to the group, click the **Add a member** button and search by username, full name or email address: If the invitee does not yet have a SAMSON account, you can still invite them by **entering their email address** and clicking **Add**. ## Sharing documents You can upload documents to SAMSON Connect while controlling the **document visibility**. To share your document from SAMSON click **Home > Publish** (1). 1. , : `Ctrl`+`Alt`+`S`, : `Cmd`+`Alt`+`S` In the dialog window, fill in the name of the document, its description, and choose the document visibility. For the **document visibility** you can choose one of the following options: - **Public** - everyone can use this document, but editing requires access rights. - **Hidden** - anyone with the link can use this document, but editing requires access rights. - **Restricted** - using or editing this document requires access rights. Then click **Publish document** and the document will be shared in [SAMSON Connect - Documents](https://www.samson-connect.net/documents) and the link to it will be provided in the same window. You can access and manage all your shared documents in your account at [SAMSON Connect](https://www.samson-connect.net/) (see below). ### Managing shared documents on SAMSON Connect On [SAMSON Connect](https://www.samson-connect.net/), you can manage the documents you published and the ones that have been shared with you by clicking **Documents** in your user menu. If you are a **document owner** or **document editor**, you can edit the document settings: If you are a **document owner**, you can also edit who can access the document by controlling its visibility (Public, Hidden or Restricted): and grant **access rights** to users: or directly to **groups**: Note You can create an unlimited number of private or public groups on [SAMSON Connect](https://www.samson-connect.net/) to easily share documents, jobs, extensions, etc., for example, based on the projects you are working on. ## Viewing and sharing jobs on SAMSON Connect The jobs you run in the cloud from SAMSON (e.g., using AlphaFold, NVIDIA BioNeMo services, GROMACS, etc.) are **accessible from [SAMSON Connect](https://www.samson-connect.net/)**, and **you can control who has access to them**. Like [shared documents](https://documentation.samson-connect.net/users/latest/samson-connect/#shared-documents), a job can either be: - **Public** - visible to everyone, - **Hidden** - a link is needed to download the files, - **Restricted** - specific access rights must be granted to access the files or edit the job details. Note By default, a job visibility is automatically set to **Restricted**. On [SAMSON Connect](https://www.samson-connect.net/), you can manage the jobs you created and the ones that have been shared with you by clicking **Jobs** in your user menu: By clicking on a job, you can directly access the job files: and you can use the context menu to download job files: As with shared documents, you can edit the job details (name and notes) when you are a **job owner** or **job editor**. Similarly, you can grant access rights to a user or a group when you are a **job owner**. Note You can also create an unlimited number of private or public groups on [SAMSON Connect](https://www.samson-connect.net/) to easily share documents, jobs, extensions, etc. ## Related pages - [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) - [Cloud computations](https://documentation.samson-connect.net/users/latest/cloud/index.md) - [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md) # User Guide - Automate and extend # Automate and extend Use this topic when you want SAMSON to do more for you with less repeated manual work. It covers Python automation inside SAMSON on one side, and extension installation or development on the other. Follow the full sequence if you are exploring both, or jump directly to the track that matches your goal. ## Who this topic is for - Users automating repetitive tasks - Users embedding Python scripts in documents - Users managing extensions - Developers exploring the SDK and extension distribution path ## What you will be able to do afterward - Use the integrated Python environment - Manage packages and run scripts - Embed scripts or apps in documents - Add or remove extensions - Understand the SDK and extension development path ## Recommended reading order 1. [Scripting](https://documentation.samson-connect.net/users/latest/scripting/index.md) - Start here if you want automation, reproducibility, or document-embedded Python workflows inside SAMSON. `Foundational.` 1. [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) - Continue here when you want to install more capabilities or understand the SDK and extension distribution path. `Task-focused.` ## Read this first Start with [Scripting](https://documentation.samson-connect.net/users/latest/scripting/index.md) if you want automation inside SAMSON. If your immediate goal is to add capabilities or understand the SDK path, jump straight to [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md). ## You can skip this for now if... - You are not writing Python or embedding scripts, in which case you can skip [Scripting](https://documentation.samson-connect.net/users/latest/scripting/index.md) - You only need built-in capabilities and are not managing extensions, in which case you can skip [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) ## Suggested paths - **Automate with Python**: [Scripting](https://documentation.samson-connect.net/users/latest/scripting/index.md) - **Package a reproducible scripted workflow**: [Scripting](https://documentation.samson-connect.net/users/latest/scripting/index.md) - **Install or develop new capabilities**: [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) ## Where to go next - [Simulate and analyze](https://documentation.samson-connect.net/users/latest/simulate-and-analyze/index.md) - Continue here for scripted modeling, path generation, or analysis pipelines. - [Share and collaborate](https://documentation.samson-connect.net/users/latest/share-and-collaborate/index.md) - Go here when you want to distribute scripted documents or collaborate around them. - [Reference and help](https://documentation.samson-connect.net/users/latest/reference-and-help/index.md) - Continue here for deeper references, troubleshooting, or related help paths. # Scripting Use this page when you want to automate [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) workflows with Python, run code in the integrated console, manage packages, edit scripts, or embed scripts and apps in documents. The integrated Python environment includes: - [SAMSON Python API](https://documentation.samson-connect.net/users/latest/scripting/#samson-python-api) - [Python interpreter](https://documentation.samson-connect.net/users/latest/scripting/#python-console) - [Python package manager](https://documentation.samson-connect.net/users/latest/scripting/#installing-python-packages) - [Code Editor](https://documentation.samson-connect.net/users/latest/interface/#code-editor) - The possibility to [embed Python scripts and apps in SAMSON documents](https://documentation.samson-connect.net/users/latest/scripting/#embed-scripts) See also: [Python Scripting Guide](https://documentation.samson-connect.net/scripting/latest/). ## What this page covers This page explains how to use the integrated Python environment in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) for automation, reproducibility, and custom workflows. ## SAMSON Python API [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) comes with the [Python Scripting Extension](https://www.samson-connect.net/extensions/7b654ce6-e38c-b97f-6746-4fd6934487c2) which exposes the SAMSON API in Python and provides a Jupyter Qt console embedded in SAMSON (see [Python interpreter](https://documentation.samson-connect.net/users/latest/scripting/#python-console)). This allows you to script almost everything in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) with Python, model and simulate from scripts, create pipelines, integrate Python packages for deep learning, bioinformatics, statistics, visualization, and more. You can use [SAMSON AI](https://documentation.samson-connect.net/users/latest/samson-ai/index.md) to help you with Python development - it has been trained on the [Python Scripting Guide](https://documentation.samson-connect.net/scripting/latest/). For that, use [/script](https://documentation.samson-connect.net/users/latest/samson-ai/#script-command) in the **SAMSON AI assistant** - it will generate Python scripts based on your requests. With this command, SAMSON AI can draft Python scripts using the SAMSON Python API, tailored to your specific needs. Note See the [Python Scripting Guide](https://documentation.samson-connect.net/scripting/latest/) to learn more how to use SAMSON Python API. ## Python Console The **Python Console** lets you access [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) functionality with Python and automate workflows with scripts. The Python Console integrates the Jupyter Qt Console. To open the **Python Console**, click on **Interface > Python Console** (1). 1. , : `Ctrl`+`8`, : `Cmd`+`8` ## Managing Python packages To manage installed Python packages, in **Python Console** go to **Edit > Manage packages...**. This will open the **Python Package Manager** window. In the **Package Manager**, you can see the list of installed packages and their versions, install/uninstall Python packages. ### Installing Python packages To install a Python package provide its name and click **Install**. Note To install a Python package not available from [PyPI](https://pypi.org/), please see [Installing a local Python package](#installing-a-local-python-package). Packages are managed using `pip` and what you provide will be done using `pip`. This means that you can: - Provide a list of packages to install or uninstall. - Specify the package version, if necessary, as you would do when installing using `pip`, for example: - `foo==1.2.0` to install the version 1.2.0 of the *foo* package - `foo>=2.1.0` to install the *foo* package with the minimal version of 2.1.0 - Add various `pip` flags after the package name, e.g.: `foo --upgrade` to upgrade to the latest version. ### Installing a local Python package In the Package Manager, you can also install a local Python package: - Provide a path to the package you want to install. Note that it should be a valid Python package, i.e. with `setup.py`, etc. - Click **Install**. You can also install a local Python package in the *editable/develop* mode (i.e., same as `pip install -e`), such that changes in the package's code are dynamically reflected without needing to reinstall it. This is useful when you are making changes in the package since this allows Python to directly reference the package's source files in the package's working directory, so any changes you make are automatically reflected in the package. If you change the package's working directory then you will need to uninstall and reinstall the package again. Note If you want to install a package for which you don't need to modify its source code, then do not check the *editable/develop* mode. Warning On some macOS installations, packages installed in the *editable* mode might not load on the next launch of SAMSON. In this case, you might need to install them in the non-editable mode or reinstall them or register paths to directories with their source files in `sys.path`. ### Uninstalling Python packages To uninstall a Python package (either installed from PyPI or a local Python package), simply provide its name and click **Uninstall**. ## Code Editor [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides **Code editor** which integrates **Monaco Editor**, from Visual Studio Code. It offers an intuitive coding experience, complete with syntax highlighting, auto-completion, and more. The **Code editor** opens and modifies text files, including Python scripts, and can run Python files. To open the **Code editor**, click on **Interface > Code editor** (1). 1. , : `Ctrl`+`9`, : `Cmd`+`9` To run a Python script, click **Run** () on the left panel of the Code Editor or in its **Run menu**, or use the integrated **Python Console** right within [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) for quick execution. You get access to the entire [SAMSON Python API](https://documentation.samson-connect.net/users/latest/scripting/#samson-python-api) and can even rapidly create graphical user interfaces using PyQt. The **Code editor** provides a set of Python script templates that demonstrate usages of [SAMSON Python API](https://documentation.samson-connect.net/users/latest/scripting/#samson-python-api). You can start from them. See the [Python Scripting Guide](https://documentation.samson-connect.net/scripting/latest/) to learn more how to use [SAMSON Python API](https://documentation.samson-connect.net/users/latest/scripting/#samson-python-api) and for more examples. ## Python templates In the [Code editor](#code-editor), you can find a set of Python templates demonstrating the usage of Python Scripting and the SAMSON Python API for various tasks. Note You can find other examples in the [Python Scripting Guide: Examples](https://documentation.samson-connect.net/scripting/latest/docs/Examples.html). ## Embedding Python Scripts and Apps [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) [documents](https://documentation.samson-connect.net/users/latest/documents/index.md) can contain not only molecular models. They enable **Universal File Embedding** and can embed Python scripts and any number of files and folders. This makes it possible to embed Python scripts and whole Python apps (e.g., machine learning apps), research papers, images, data, and much more. To embed files and folders within a [document](https://documentation.samson-connect.net/users/latest/documents/index.md), drag and drop them in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) and you will be asked whether you would like to embed them, or use **Home > Embed files** or **Home > Embed folders**. Folders and files are stored within the [document](https://documentation.samson-connect.net/users/latest/documents/index.md), making the document self-contained, so you can transfer documents between computers and share documents. To open an embedded Python script in the [Code Editor](https://documentation.samson-connect.net/users/latest/interface/#code-editor), simply double-click on it. You can share or distribute a [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) [document](https://documentation.samson-connect.net/users/latest/documents/index.md) via email, GitHub, or the [SAMSON Connect - Documents](https://www.samson-connect.net/documents). Your colleagues or students can then open the document and run your embedded Python apps seamlessly. Here are some of the possibilities: - You can collaborate with your colleagues by sharing SAMSON documents that include project files, meeting notes, and automated workflow scripts. - As a researcher, you can attach executable data analysis scripts to published molecular models, increasing transparency and reproducibility. - As a professor, you can distribute SAMSON documents containing both lecture notes and interactive Python-based exercises for students. - As an educator, you can create comprehensive, interactive learning modules that students can execute directly within SAMSON. ## Python code for commands, palettes, and visual presets You can easily get the Python code corresponding to SAMSON commands. For example, to know the code corresponding to the **Add hydrogens** command, begin by searching the command in the **Find everything** box (1) and click on the **Copy icon** next to the message *"This command is available as Python code"*: 1. Shortcut: `Shift`+`E` You can then use the code in the **Code editor** or in the **Python console**. You can also access Python code corresponding to color palettes from the color palette or color scheme windows: as well as to **Visual Presets**, by clicking on the **Copy as Python code** button: ## Related pages - [SAMSON AI](https://documentation.samson-connect.net/users/latest/samson-ai/index.md) - [Interface](https://documentation.samson-connect.net/users/latest/interface/index.md) - [Path Analyzer](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md) - [Automate and extend](https://documentation.samson-connect.net/users/latest/automate-and-extend/index.md) ## Next step - Continue with [Automate and extend](https://documentation.samson-connect.net/users/latest/automate-and-extend/index.md) if you want the broader route for scripting and extension workflows. - Continue with [SAMSON AI](https://documentation.samson-connect.net/users/latest/samson-ai/index.md) if you want assistant help generating scripts with `/script`. - Continue with [Path Analyzer](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md) or [Modeling and Simulation](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md) if your next step is a scripted analysis or simulation workflow. # Extending SAMSON [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) has an open architecture that lets you extend and adapt it to your needs by downloading [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) (modules) from the [SAMSON Connect](https://www.samson-connect.net/) website. [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) come in many flavors: [apps](https://documentation.samson-connect.net/users/latest/apps/index.md), assets, [editors](https://documentation.samson-connect.net/users/latest/editors/index.md), controllers, [models](https://documentation.samson-connect.net/users/latest/models/index.md), parsers, etc., and are adapted to different application domains. [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) help you build new models, perform calculations, run interactive or offline simulations or simulations in the Cloud, visualize and interpret results, and more. The first time you start [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), it downloads from [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) a set of [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) included by default. Later you can extend your [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) installation by adding more [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) . ## SAMSON Extensions SAMSON Extensions are modules for [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) that you add from [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). The first time you start [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), it downloads from [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) a set of [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) included by default. SAMSON Extensions may contain [apps](https://documentation.samson-connect.net/users/latest/apps/index.md), [editors](https://documentation.samson-connect.net/users/latest/editors/index.md), [importers](https://documentation.samson-connect.net/users/latest/importers/index.md), [exporters](https://documentation.samson-connect.net/users/latest/exporters/index.md), [visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models), [interaction model](https://documentation.samson-connect.net/users/latest/models/#interaction-models)s, [state updaters](https://documentation.samson-connect.net/users/latest/models/#state-updaters), and also many other things like workspaces, commands, selectors, [visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/index.md), [interactive tutorials](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md), etc. [Apps](https://documentation.samson-connect.net/users/latest/apps/index.md) may provide any type of functionality. For example, an app may be a connector to an external executable or web service, may wrap previously developed code to integrate its functionality with [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) and other [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md), or provide entirely new functionality. To start using an app, click on it from either the **Home > Apps** or search for it in the **Find everything** search box at the top of [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). [Editors](https://documentation.samson-connect.net/users/latest/editors/index.md) are one of the main ways to interact with documents. Editors receive user events (e.g. mouse and keyboard events) and use these events to provide potentially complex editing functionality. For example, an editor may be a rectangle selection tool, a nanotube generator that lets you create a new nanotube model in a few clicks, a tool for deforming molecular structures while preserving local rigidity, a tool to apply a rigid-body transform to a model, etc. [Editors](https://documentation.samson-connect.net/users/latest/editors/index.md) are positioned in the left-side menu of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). [Importers](https://documentation.samson-connect.net/users/latest/importers/index.md) are dedicated to parsing files. An importer may be e.g. a PDB parser, an electron density parser, etc. [Exporters](https://documentation.samson-connect.net/users/latest/exporters/index.md) are dedicated to exporting content from the document to files. An exporter may be e.g. a PDB exporter, an XYZ exporter, etc. [Visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models) provide visual representations in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). A visual model may be e.g. a secondary structure representation applicable to protein models, an electron density isosurface, a volume rendering of an electrostatics field, etc. [Interaction model](https://documentation.samson-connect.net/users/latest/models/#interaction-models)s are responsible for computing energies and forces and are used in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) to perform various modeling and simulation tasks. An interaction model could be e.g. a spring model, an elastic network model, an extended Hückel model, etc. [State updater](https://documentation.samson-connect.net/users/latest/models/#state-updaters)s implement methods used to advance states during [simulations](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md). State updaters may be e.g. minimization algorithms, Monte Carlo methods, molecular dynamics algorithms, etc. ## Add/Remove a SAMSON Extension To add/remove [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md), sign in to your account on [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md), then go to the [SAMSON Connect - Marketplace](https://www.samson-connect.net/extensions) section to choose the [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) you need. See [SAMSON Connect - Marketplace](https://documentation.samson-connect.net/users/latest/samson-connect/#marketplace) for extension Marketplace details. ## Develop a SAMSON Extension To start developing your own [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) you need to download and install the SAMSON SDK. For that, sign in to [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) and go to the **Download** page. SAMSON SDK makes it possible to create new apps, editors, force fields, services, etc. with maximal performance and control. SAMSON SDK reduces your development costs thanks to code templates for apps, editors, etc. and advanced SDK features to accelerate development. Once a [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) developed, it can be deployed everywhere with SAMSON's multiplatform SDK. You can quickly integrate what you already have or break new ground. SAMSON lets you focus on your expertise and handles visualization, data management, and much more. To learn how to install the SAMSON SDK and create or distribute a SAMSON Extension, use the [Developer Guide](https://documentation.samson-connect.net/developers/latest/) and the [Documentation center](https://documentation.samson-connect.net/). ## Related pages - [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md): manage Marketplace extensions, subscriptions, downloads, and SDK access. - [Apps](https://documentation.samson-connect.net/users/latest/apps/index.md), [Editors](https://documentation.samson-connect.net/users/latest/editors/index.md), [Importers](https://documentation.samson-connect.net/users/latest/importers/index.md), and [Exporters](https://documentation.samson-connect.net/users/latest/exporters/index.md): learn common extension families. - [Scripting](https://documentation.samson-connect.net/users/latest/scripting/index.md): automate workflows inside [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) without creating a compiled extension. - [Developer Guide](https://documentation.samson-connect.net/developers/latest/): build and distribute [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) with the SDK. [Contact us](mailto:contact@samson-connect.net) to learn about the **Partner Program**. ## Distribute your SAMSON Extension You can distribute [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) developed by you on [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). You can make your extensions free or sell subscriptions to them, and sell access to cloud computing services from SAMSON. We provide a simple yet very customizable mechanism to set up various subscription tiers for your extension via our payment partner [Stripe](https://stripe.com/) - you can set up different monthly and yearly subscriptions for industry and academia. [Contact us](mailto:contact@samson-connect.net) to learn about the **Partner Program**. To learn how to install the SAMSON SDK and create or distribute a SAMSON Extension, use the [Developer Guide](https://documentation.samson-connect.net/developers/latest/) and the [Documentation center](https://documentation.samson-connect.net/). # User Guide - Reference and help # Reference and help Use this topic when you need the fastest route to an answer rather than a workflow tutorial. It helps you choose between quick recurring answers, symptom-based fixes, and the broader reference hub for deeper feature details. Start with the FAQ for common issues, or jump straight to troubleshooting or references when you already know the kind of help you need. ## Who this topic is for - Users with a common account, installation, or extension question - Users diagnosing runtime or platform problems - Users who already know the feature family and need the canonical reference page ## What you will be able to do afterward - Get fast answers to recurring questions - Choose the right troubleshooting path - Find the correct reference family without browsing the whole guide ## Recommended reading order 1. [FAQ](https://documentation.samson-connect.net/users/latest/faq/index.md) - Start here for recurring questions about accounts, installation, updates, and extensions. `Foundational.` 1. [Troubleshooting](https://documentation.samson-connect.net/users/latest/troubleshooting/index.md) - Continue here when the issue is symptom-based and you need a practical fix path. `Task-focused.` 1. [References](https://documentation.samson-connect.net/users/latest/references/index.md) - Use this when you need the detailed reference family for a specific SAMSON feature area. `Reference / jump page.` ## Read this first Start with [FAQ](https://documentation.samson-connect.net/users/latest/faq/index.md). If the problem is clearly symptom-based, jump straight to [Troubleshooting](https://documentation.samson-connect.net/users/latest/troubleshooting/index.md). ## You can skip this for now if... - You only need a quick answer or fix, in which case you can skip [References](https://documentation.samson-connect.net/users/latest/references/index.md) - The issue is already clearly a troubleshooting case, in which case you can skip [FAQ](https://documentation.samson-connect.net/users/latest/faq/index.md) - You only need a feature reference, in which case you can skip [Troubleshooting](https://documentation.samson-connect.net/users/latest/troubleshooting/index.md) ## Suggested paths - **Quick answer**: [FAQ](https://documentation.samson-connect.net/users/latest/faq/index.md) - **Fix a problem**: [Troubleshooting](https://documentation.samson-connect.net/users/latest/troubleshooting/index.md) - **Deep feature reference**: [References](https://documentation.samson-connect.net/users/latest/references/index.md) ## Where to go next - [Start here](https://documentation.samson-connect.net/users/latest/start/index.md) - Continue here for installation, first-use orientation, and onboarding follow-up. - [Share and collaborate](https://documentation.samson-connect.net/users/latest/share-and-collaborate/index.md) - Go here for SAMSON Connect, permissions, groups, and shared documents or jobs. - [Automate and extend](https://documentation.samson-connect.net/users/latest/automate-and-extend/index.md) - Continue here for scripting, extensions, and developer-facing workflows. # FAQ Use this page to find quick answers to common questions about accounts, installation, updates, extensions, and licensing in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) and [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). When a full procedure already exists elsewhere in the guide, the answer here points you to the canonical page. ## What this page covers This page collects short answers to the questions that come up most often around accounts, installation, updates, and extensions. When a longer workflow already exists elsewhere in the guide, that workflow remains the canonical page. Below you can find answers to some of the frequently asked questions. If you didn't find an answer to your question here, you can also check the [Troubleshooting](https://documentation.samson-connect.net/users/latest/troubleshooting/index.md) section and [SAMSON Connect Forum](https://forum.samson-connect.net/). ## Registration ### I registered on SAMSON Connect but haven't received a confirmation email If you registered using a Gmail account then you might need to wait a bit since Gmail takes more time. You can access your [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) Key as well in your account on [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) (see [Where can I get my SAMSON Key?](#keys)). ### How can I get an academic status The academic status allows adding some [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) for free and provides significant discounts (up to 90%) for many non-free [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) . To get academic status, please register with your institutional email address; we will grant academic status in about 1-2 working days. If you registered with an academic email address and haven't received academic status, please [contact us](mailto:contact@samson-connect.net). Please note that if you change your email address, you will need to reinstall [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) with the new credentials. If you don't have an academic email address but work in academia or you are a student please [contact us](mailto:contact@samson-connect.net). ## Installation of SAMSON Please check also: [Installing SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/#installing-samson). ### Does SAMSON require admin rights? **No admin rights are necessary!** SAMSON does not need admin rights to be installed - it installs in the user home. SAMSON explicitly checks at startup that it is not run in admin mode to encourage users to restrain the rights they give to SAMSON. ### Can I install SAMSON on a virtual machine? Yes, but make sure your virtual machine (VM) has access to hardware GPU acceleration. Otherwise, SAMSON might not run because some OpenGL functionality may not be supported by your VM's display driver. Use the documentation of your VM software to enable hardware GPU acceleration. ### Where can I get my SAMSON Key? You can get your [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) keys on [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md): sing in and go to your **Account**. ### When I install SAMSON it says that my credentials are invalid or my activation key is not working. Please verify your email address (whether it is the one used when registering on [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md)) and your [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) Key - it shouldn't contain any spaces or additional symbols. You can copy your [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) Key from [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) (see [Where can I get my SAMSON Key?](#keys)). ### How to install an older version of SAMSON If needed, you can install an older version of SAMSON using the same installer. For that, at the second step check the **Install an older version** option as shown on the image below: At the next step, choose the version you would like to install. Please note, that versions are listed with their developers version numbers, for example, the version 2.0.2 corresponds to the 2021 version of SAMSON. To check the corresponding developer version number, please, follow the link: [User Guides for other SAMSON versions](https://documentation.samson-connect.net/user-guide-versions/index.md). If you have multiple versions of SAMSON installed and would like to launch a version of SAMSON different from the installed default one: On Windows: ``` C:/Users/%USERNAME%/OneAngstrom/SAMSON-Application/11.0.0/Binaries/SAMSON-Core.exe ``` On MacOS: ``` $HOME/Applications/SAMSON.app/ ``` On Linux: ``` $HOME/OneAngstrom/SAMSON-Application/11.0.0/Binaries/SAMSON-Core.sh ``` ## Updating SAMSON ### How to update SAMSON SAMSON regularly checks for updates and if an update is available it will ask you whether you would like to update SAMSON. You can change the frequency of update checks in **Preferences > Setup > General**. The update can also be invoked manually directly from SAMSON via **Interface menu > Update SAMSON**. ## How to uninstall SAMSON When updating SAMSON, you will be asked whether you would like to remove older versions of SAMSON. Below are the instruction on how to uninstall SAMSON. ### Windows Delete folders: ``` C:/Users/%USERNAME%/OneAngstrom C:/Users/%USERNAME%/AppData/Local/OneAngstrom C:/Users/%USERNAME%/Documents/OneAngstrom ``` Delete shortcuts: ``` C:/Users/%USERNAME%/Desktop/SAMSON* C:/Users/%USERNAME%/AppData/Roaming/Microsoft/Windows/Start Menu/Programs/SAMSON* ``` If you also would like to clear the registry then open *Registry Editor* (`regedit`) and delete the following records: ``` HKEY_CURRENT_USER\Software\OneAngstrom HKEY_CURRENT_USER\Software\NANO-D ``` ### Linux Delete the following folders and files: ``` rm -rf ${HOME}/OneAngstrom/ rm -rf ${HOME}/.local/share/OneAngstrom rm -rf ${HOME}/.local/share/applications/SAMSON.desktop rm -rf ${HOME}/.config/OneAngstrom # SAMSON Settings, if you want to reinstall SAMSON you can keep it ``` ### MacOS Delete the following folders and files: ``` rm -rf $HOME/Applications/SAMSON*.app rm -rf $HOME/Documents/OneAngstrom rm -rf $HOME/OneAngstrom rm -rf $HOME/.OneAngstrom rm -rf $HOME/Library/Application Support/OneAngstrom rm -rf $HOME/Library/Preferences/com.oneangstrom.* ``` ## SAMSON Extensions Please check also: [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) . ### How to install SAMSON Extensions Just add a [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) from [SAMSON Connect - Marketplace](https://www.samson-connect.net/extensions) (see: [User Guide: Marketplace](https://documentation.samson-connect.net/users/latest/samson-connect/#marketplace)) and SAMSON will do the rest for you - on launch, SAMSON automatically downloads and installs [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md), and also checks for their updates ### How to update SAMSON Extensions **It is automatic!** When you launch SAMSON it checks whether new versions of [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) are available and downloads and installs them for you. Note [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) are updated only for the latest version of SAMSON. So, we encourage you to update SAMSON when a new version is available. ### How to manage SAMSON Extensions: modify or cancel subscriptions, remove an extension To view and modify your subscriptions (access invoices, modify subscriptions, cancel subscriptions) and remove extensions, log in on [SAMSON Connect](https://www.samson-connect.net/) and go to **Account > Settings**. ### I added a SAMSON Extension from SAMSON Connect but I cannot see it in SAMSON Please check the options below from the top to bottom. - Please first check if the [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) you have added is available for your OS and for the version of SAMSON you are using - you can check it on the web-page of the [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) just under the Extension's name. If the [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) is not available for your OS please [contact us](mailto:contact@samson-connect.net). Please note that some default extensions might be added depending on your current Plan. - If [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) was launched when you added a [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) then you need to restart [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) for this extension to be installed - newly added [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) are automatically downloaded from [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) and installed on the next launch of [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). - Note that not all [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) have [Apps](https://documentation.samson-connect.net/users/latest/apps/index.md) (can be found in the **Home > Apps**) or [Editors](https://documentation.samson-connect.net/users/latest/editors/index.md) (can be found in the editors menu on the left-side of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md)). [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) might have other things like [importers](https://documentation.samson-connect.net/users/latest/importers/index.md), [exporters](https://documentation.samson-connect.net/users/latest/exporters/index.md), [visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models), [interaction models](https://documentation.samson-connect.net/users/latest/models/#interaction-models), render presets, commands, etc. Please see [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md). You can also find [Apps](https://documentation.samson-connect.net/users/latest/apps/index.md), [Editors](https://documentation.samson-connect.net/users/latest/editors/index.md), and commands using **Find everything** at the top of [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). - Check the SAMSON Log by going to **Interface > Show log**. You can filter the log for the [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) you have added to see possible issues and whether it has been added to [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) at all. If you see the problem (lines corresponding to a [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) are colored in red), you can send this log to us with an additional information (your user email and the problem description) by clicking on the **Submit** button. ### I want to use a SAMSON Extension but it is not available on my platform - Please contact us via [SAMSON Connect Forum](https://forum.samson-connect.net/) or by email ([contact us](mailto:contact@samson-connect.net)). ### Where can I find documentation for SAMSON Extensions? Please check the web-page of a [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) and its description on [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) and [Documentation Center - Extensions Tutorials](https://documentation.samson-connect.net/tutorials/index.md). ### I couldn't find a SAMSON Extension or functionality in SAMSON that I want. Could you develop it? Yes, we do custom development, [contact us](mailto:contact@samson-connect.net). ## Related pages - [Getting Started](https://documentation.samson-connect.net/users/latest/getting-started/index.md) - [Troubleshooting](https://documentation.samson-connect.net/users/latest/troubleshooting/index.md) - [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) - [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) # Troubleshooting Use this troubleshooting page when SAMSON does not install, launch, display correctly, or find required platform dependencies. Use it as a quick lookup page, then follow the linked task pages for the full procedure when one exists. ## What this page covers This page is organized as a symptom-based troubleshooting reference for installation, display scaling, Linux dependencies, and GPU/OpenGL issues. For the main onboarding workflow, use [Getting Started](https://documentation.samson-connect.net/users/latest/getting-started/index.md). If you have trouble installing SAMSON and cannot find an answer below, please check the [SAMSON Connect Forum](https://forum.samson-connect.net/). ## I have a high DPI monitor and icons in SAMSON look small ### Windows - Right click on the SAMSON executable program to open its properties and go to the **Compatibility** tab: - Click on **Change high DPI settings** and check the lower check box (**Override high DPI scaling behavior**) and for the **Scaling performed by** select **System** from the list: - Restart SAMSON if it was launched. ## Full Disk Access In MacOS It might be necessary to provide a full disk access on macOS for SAMSON, e.g., to be able to access `~/Documents`, desktop files, etc. Please check an example of the procedure to add full disk access here: [https://www.tech-otaku.com/mac/manually-granting-applications-full-disk-access-macos-catalina](https://www.tech-otaku.com/mac/manually-granting-applications-full-disk-access-macos-catalina/). Please note that you will need to perform this for SAMSON and you will need to use `sh` instead of `bash`. ## Installation ### Cannot launch SAMSON on Linux due to missing xcb On Ubuntu-like Linux, you might first need to install the following libraries: `libxcb-xinerama0`, `libxcb-cursor0`: ``` sudo apt install libxcb-xinerama0, libxcb-cursor0 ``` On CentOS-like Linux, you might first need to install `xcb-util*` packages: ``` sudo dnf install xcb-util* ``` ### Installing OpenGL drivers on Linux Please, check how to install GPU driver and OpenGL library for your platform. Below are suggestion for Debian-based systems (e.g. Ubuntu). First, to check which GPU you have run the following command in the terminal: ``` lspci | grep VGA ``` If you have NVIDIA or AMD graphics card, you can install their proprietary drivers. Please, check how to do it for you platform and your GPU. If you have only an integrated GPU (Graphics Processing Unit), you may see only something like: ``` 00:02.0 VGA compatible controller: Intel Corporation ... process Graphics Controller ``` In this case you might need to install Mesa. First check whether you have Mesa with OpenGL already installed in your system: ``` glxinfo | grep OpenGL locate libOpenGL.so locate libGL.so ``` To install Mesa execute the following command in the terminal: ``` sudo apt-get install libgl1-mesa-dev mesa-utils ``` ### Running SAMSON on Linux with an AMD GPU SAMSON requires a graphics card supporting OpenGL 3.2. To detect which GPU you have you may run several commands: ``` sudo lshw -c video lspci -nn | grep VGA ``` SAMSON depends on libOpenGL.so and libGLX.so (to be precise, libOpenGL.so.0 and libGLX.so.0), which are not provided by SAMSON and should be installed on your system. To check whether these libraries are installed on your system, you may run the following commands: ``` sudo updatedb locate libOpenGL.so locate libGLX.so locate libGL.so ``` If you have no libOpenGL.so library in your system, you can make links to either the libQt5OpenGL.so shipped with SAMSON, or to your system library, e.g. by `compiz`: ``` ln -s $HOME/OneAngstrom/SAMSON-Application/11.0.0/Binaries/SAMSONQtLibs/libQt5OpenGL.so $HOME/OneAngstrom/SAMSON-Application/11.0.0/Binaries/SAMSONQtLibs/libOpenGL.so.0 ``` or ``` sudo ln -s /usr/lib/x86_64-linux-gnu/compiz/libopengl.so /usr/lib/x86_64-linux-gnu/libOpenGL.so.0 ``` In the first case, you will need to create this link every time your SAMSON has been updated. If you have no libGLX.so library, you may create a link to libGL.so, e.g. depending on where you have libGL.so: ``` sudo ln -s /usr/lib/x86_64-linux-gnu/libGL.so /usr/lib/x86_64-linux-gnu/libGLX.so.0 ``` or ``` sudo ln -s /usr/lib/x86_64-linux-gnu/mesa/libGL.so.1 /usr/lib/x86_64-linux-gnu/libGLX.so.0 ``` Otherwise, these libraries can be installed through a GPU driver or `mesa`. If, for example, you have Ubuntu 14.04 (up to Xorg 1.16), you may install the `fglrx` driver. See [Ubuntu BinaryDriverHowto/AMD](https://help.ubuntu.com/community/BinaryDriverHowto/AMD). For a newer version of Ubuntu, if you have a recent AMD GPU, you may install the [AMDGPU Driver](https://help.ubuntu.com/community/AMDGPU-Driver) or the [AMDGPU-PRO Driver](http://support.amd.com/en-us/kb-articles/Pages/AMDGPU-PRO-Driver-for-Linux-Release-Notes.aspx). Alternatively, you may install mesa: ``` sudo apt-get install mesa-utils libgl1-mesa-dev ``` ## Related pages - [Getting Started](https://documentation.samson-connect.net/users/latest/getting-started/index.md) - [Requirements and platforms](https://documentation.samson-connect.net/users/latest/requirements-and-platforms/index.md) - [Install SAMSON](https://documentation.samson-connect.net/users/latest/installation/index.md) - [FAQ](https://documentation.samson-connect.net/users/latest/faq/index.md) # User Guide - References # References Use this reference hub when you already know the SAMSON feature family you need and want the fastest route to a detailed lookup page. It gathers the main reference pages for animations, the interface, documents, node types, preferences, supported formats, extension families, visual presets, and the Node Specification Language. ## When to use this Use this hub when you already know which SAMSON feature family you need and want a precise lookup page. If you are still choosing a workflow, start with [Reference and help](https://documentation.samson-connect.net/users/latest/reference-and-help/index.md) or the topic hub closest to your task. ## Reference families - [Animations](https://documentation.samson-connect.net/users/latest/animations/index.md): look up animation effects used in presentations and movies. - [Camera](https://documentation.samson-connect.net/users/latest/camera/index.md): manage cameras and camera nodes. - [Default color palettes](https://documentation.samson-connect.net/users/latest/color-palettes/index.md): inspect the built-in palettes used for color schemes. - [Documents](https://documentation.samson-connect.net/users/latest/documents/index.md): understand documents, folders, files, notes, and paths. - [Node types](https://documentation.samson-connect.net/users/latest/node-types/index.md): identify the main node categories stored in documents. - [Models](https://documentation.samson-connect.net/users/latest/models/index.md): look up structural, visual, interaction, dynamical, and property models. - [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md): use NSL expressions for advanced selections and filters. - [Path Analyzer](https://documentation.samson-connect.net/users/latest/references/path-analyzer/index.md): look up Path Analyzer plots and analyses. - [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md): find user-modifiable SAMSON settings. - [SAMSON Extensions: Apps](https://documentation.samson-connect.net/users/latest/apps/index.md), [Editors](https://documentation.samson-connect.net/users/latest/editors/index.md), [Importers](https://documentation.samson-connect.net/users/latest/importers/index.md), and [Exporters](https://documentation.samson-connect.net/users/latest/exporters/index.md): understand extension families. - [SAMSON Interface](https://documentation.samson-connect.net/users/latest/interface/index.md): look up menus, panels, workspaces, and shortcuts. - [Supported formats](https://documentation.samson-connect.net/users/latest/supported-formats/index.md): check import and export formats. - [Sequence view](https://documentation.samson-connect.net/users/latest/sequence-view/index.md): understand sequence-based views of biological structures. - [Versioning](https://documentation.samson-connect.net/users/latest/versioning/index.md): understand SAMSON version and compatibility conventions. - [Visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/index.md): look up reusable visualization presets. ## Related pages - [Reference and help](https://documentation.samson-connect.net/users/latest/reference-and-help/index.md): choose between FAQ, troubleshooting, and references. - [First look: the interface](https://documentation.samson-connect.net/users/latest/first-look/index.md): start here if you need orientation before a detailed reference. # Apps Use this reference when you need to understand what SAMSON apps are, where to find them, and how they relate to other [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md). Apps can add workflows to [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). For example, an app may connect to an external executable or web service, wrap existing code, or provide new functionality based on the SAMSON Application Programming Interface (SAMSON API). Apps can be found in **Home > Apps**. [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides a set of apps by default and you can add more apps from [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). ## What this reference covers This page is a lookup page for the app extension family. Use [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) when you want to install extensions or follow the development path. To start developing your own apps, use the documentation about [generating SAMSON Extensions](https://documentation.samson-connect.net/developers/latest/extension-generator/) and the [Documentation center](https://documentation.samson-connect.net/). ## Related pages - [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md): add, remove, or develop [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md). - [Editors](https://documentation.samson-connect.net/users/latest/editors/index.md), [Importers](https://documentation.samson-connect.net/users/latest/importers/index.md), and [Exporters](https://documentation.samson-connect.net/users/latest/exporters/index.md): compare other extension families. - [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md): manage Marketplace access and installed extensions. # Camera A **camera** is a part of a [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) [document](https://documentation.samson-connect.net/users/latest/documents/index.md), and each document has at least one camera. A camera is saved/loaded with a [document](https://documentation.samson-connect.net/users/latest/documents/index.md) in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) file formats (**.sam**, **.samx**). A camera provides a 3D view of visualizable objects in the [document](https://documentation.samson-connect.net/users/latest/documents/index.md), and can be easily controlled to point to a specific location, zoom in or out, translate, rotate, etc. Basically, you may consider your screen as a camera pointing into the screen and yourself as an operator seeing through the camera. Check the [Moving around](https://documentation.samson-connect.net/users/latest/moving-around/index.md) section to see how to operate with a camera. You can have multiple cameras in one [document](https://documentation.samson-connect.net/users/latest/documents/index.md) but only one camera can be active at a time. Having multiple cameras might be useful if you want to switch fast between different views (e.g., positions, projections, close-up views, and a full view) in the same [document](https://documentation.samson-connect.net/users/latest/documents/index.md). To switch between [cameras](https://documentation.samson-connect.net/users/latest/camera/index.md), double-click on one or *right-click* on one in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) and in its context menu click **Set as active camera**. To add a new camera, click **Visualization > Camera** (1). A newly added camera will have a default starting position. 1. , : `Ctrl`+`Shift`+`C`, : `Cmd`+`Shift`+`C`+ You can access some of the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md)'s functionality through its context menu. Right-click on a camera in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) to apply some of its actions: - center the camera on the [selection](https://documentation.samson-connect.net/users/latest/selecting/index.md) or on the whole document - activate the camera inertia which will allow for a movement with inertia - activate the camera orthographic projection which is useful e.g. for viewing crystals - set the camera as the active one - move the camera You can view and modify all the camera properties (positions, projection, inertia, etc) through the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) window. For that select the camera and open the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). See also [Moving around](https://documentation.samson-connect.net/users/latest/moving-around/index.md) ## Stereo view If you have a special glasses for a stereo view, you can activate the stereo in the **Visualization menu**. ## Related pages - [Moving around](https://documentation.samson-connect.net/users/latest/moving-around/index.md): control the active camera while navigating the viewport. - [First look: the interface](https://documentation.samson-connect.net/users/latest/first-look/index.md): locate the viewport and Document view. - [Presenting and animating](https://documentation.samson-connect.net/users/latest/presenting/index.md): use camera animations in presentations and movies. # Default color palettes This reference page lists the default color palettes available in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) and shows how they are used in colorization workflows. Use it together with [Colorizing](https://documentation.samson-connect.net/users/latest/colorizing/index.md) and [Visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/index.md). ## What this page covers This reference page explains how the default color palettes in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) are organized and when to use them while colorizing structures. Below you can find the lists of default color palettes available in SAMSON per color palette type: - [Discrete color palettes](https://documentation.samson-connect.net/users/latest/color-palettes/#discrete-color-palettes) - [Sequential HCL color palettes](https://documentation.samson-connect.net/users/latest/color-palettes/#sequential-hcl-color-palettes) - [Qualitative HCL color palettes](https://documentation.samson-connect.net/users/latest/color-palettes/#qualitative-hcl-color-palettes) - [Diverging HCL color palettes](https://documentation.samson-connect.net/users/latest/color-palettes/#diverging-hcl-color-palettes) - [Flexible diverging HCL color palettes](https://documentation.samson-connect.net/users/latest/color-palettes/#flexible-diverging-hcl-color-palettes) Note HCL stands for Hue-Chroma-Luminance color space. Tip You can revert left and right arms of color palettes in the color palette or color scheme dialogs. Tip You can add/create your own custom HCL color palettes - see [Color palettes](https://documentation.samson-connect.net/users/latest/colorizing/#color-palettes). ## Discrete color palettes | Name | Color palette | | ------------- | ------------- | | Accent | | | Carto Antique | | | Carto Bold | | | Carto Pastel | | | Carto Prism | | | Carto Safe | | | Carto Vivid | | | Dark2 | | | Okabe-Ito | | | Paired | | | R4 | | | Set1 | | | Set2 | | | Set3 | | | tab10 | | | tab20 | | | tab20b | | | tab20c | | ## Sequential HCL color palettes | Name | Color palette | | ----------------- | ------------- | | Blue-Green-Yellow | | | Blue-Yellow | | | Blue-Yellow 2 | | | Blue | | | Blue 2 | | | Dark mint | | | Gray | | | Green-Yellow | | | Green | | | Green 2 | | | Heat | | | Inferno | | | Light Gray | | | Oslo | | | Plasma | | | Purple-Blue | | | Purple-Orange | | | Purple | | | Purple 2 | | | Red-Yellow | | | Red | | | Red 2 | | | Teal | | | Viridis | | ## Qualitative HCL color palettes | Name | Color palette | | --------------- | ------------- | | Blue2Green | | | Blue2Green Dark | | | Blue2Red | | | Blue2Red Dark | | | Cold | | | Dark 2 | | | Dark 3 | | | Default | | | Dynamic | | | Green2Blue | | | Green2Blue Dark | | | Green2Red | | | Green2Red Dark | | | Harmonic | | | Pastel | | | Red2Blue | | | Red2Blue Dark | | | Red2Green | | | Red2Green Dark | | | Set 2 | | | Set 3 | | | Warm | | ## Diverging HCL color palettes | Name | Color palette | | ---------- | ------------- | | Berlin | | | Blue-Red | | | Blue-Red 2 | | | Blue-Red 3 | | ## Flexible diverging HCL color palettes | Name | Color palette | | -------- | ------------- | | ArmyRose | | | BrBG | | | Cividis | | | Earth | | | Fall | | | Geyser | | | PiYG | | | pLDDT | | | PRGn | | | PuOr | | | RdBu | | | RdGy | | | RdYlBu | | | RdYlGn | | | Roma | | | Spectral | | | TealRose | | | Temps | | | Tropic | | | Zissou 1 | | ## Related pages - [Colorizing](https://documentation.samson-connect.net/users/latest/colorizing/index.md) - [Visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/index.md) - [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) # Documents [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) documents are hierarchies of [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) and store all the information on these nodes. Documents may contain structural nodes (e.g. molecules, residues, atoms, groups), [cameras](https://documentation.samson-connect.net/users/latest/camera/index.md), [folders](https://documentation.samson-connect.net/users/latest/documents/#folders), [files](https://documentation.samson-connect.net/users/latest/documents/#files), Python scripts, conformations, paths, and other nodes. See [node types](https://documentation.samson-connect.net/users/latest/node-types/index.md) for the description of types of nodes in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) documents. You can see the active [document](https://documentation.samson-connect.net/users/latest/documents/index.md) in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view), which you can open with **Interface > Document view** or the `Ctrl`+`1` shortcut on Windows and Linux or `Cmd`+`1` on Mac. The [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) shows the data graph (hierarchical structure) of the active document. In the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) you can, among other things: - view the document's structure - show/hide nodes - [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) nodes in the document - filter the nodes using [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) and names of the nodes via *Filter nodes...* - change the documents structure, e.g. by drag-and-dropping nodes - apply specialized actions on nodes via their context menu and context toolbar You can simultaneously have several [Documents](https://documentation.samson-connect.net/users/latest/documents/index.md) opened in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), however, only one [document](https://documentation.samson-connect.net/users/latest/documents/index.md) is active at any given time - the one you see in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view). Having several [Documents](https://documentation.samson-connect.net/users/latest/documents/index.md) is useful, for example, when you want to do different tasks with different molecules or copy structures from one document to another. To switch between [Documents](https://documentation.samson-connect.net/users/latest/documents/index.md), click on the **Documents** list in the top-left corner of the menu, or **Home > Documents** (1). You can also see there the number of opened documents. 1. , : `Ctrl`+`Tab` and `Ctrl`+`Shift`+`Tab`\ : `Cmd`+`Tab` and `Cmd`+`Shift`+`Tab` To create a new [document](https://documentation.samson-connect.net/users/latest/documents/index.md), follow **Home > File > New** (1). 1. , : `Ctrl`+`N`, : `Cmd`+`N` To open recently opened documents, use **Home > File > Recent**. See also [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view), [node types](https://documentation.samson-connect.net/users/latest/node-types/index.md). ## Folders A [document](https://documentation.samson-connect.net/users/latest/documents/index.md) can have folders that you can use to group different types of nodes and apply operations to sets of molecules, e.g. hide or show them in one click. To create a new folder, click **Edit > Folder** (1). 1. , : `Ctrl`+`Shift`+`F`, : `Cmd`+`Shift`+`F` You can embed folders with files into your [document](https://documentation.samson-connect.net/users/latest/documents/index.md). Folders and files are stored within the [document](https://documentation.samson-connect.net/users/latest/documents/index.md), making the document self-contained, so you can transfer documents between computers and share documents. See also [Embedding files and folders](https://documentation.samson-connect.net/users/latest/loading-molecules/#embedding). ## Files You can embed files into your [document](https://documentation.samson-connect.net/users/latest/documents/index.md). This includes PDFs, images, various data files, structure files, scripts, etc., basically, any type of file. Folders and files are stored within the [document](https://documentation.samson-connect.net/users/latest/documents/index.md), making the document self-contained, so you can transfer documents between computers and share documents. See also [Embedding files and folders](https://documentation.samson-connect.net/users/latest/loading-molecules/#embedding). ## Related pages - [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md): open files, fetch structures, switch documents, and embed files. - [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view): use the interface reference for the panel that displays document hierarchy. - [Node types](https://documentation.samson-connect.net/users/latest/node-types/index.md): identify the kinds of nodes stored in documents. - [Share documents](https://documentation.samson-connect.net/users/latest/share-documents/index.md): publish or download shared documents through [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). # Editors Use this reference when you need to understand what editors are, where to find them, and how they differ from other [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md). Editors respond to user interaction events, such as mouse and keyboard events, in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). For example, an editor may be a nanotube generator, a tool for deforming molecular structures while preserving local rigidity, a rectangle selection tool, or a rigid-body transform tool. You can find editors in the menu on the left side of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). Above it, in the top-left corner of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md), you can find quick access commands for the active editor. You can also find editors using the **Find everything** search box at the top of [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides a set of editors by default and you can add more editors from [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). Note One and only one editor is **active** at any time. ## What this reference covers This page is a lookup page for the editor extension family. Use [Moving around](https://documentation.samson-connect.net/users/latest/moving-around/index.md) for viewport navigation editors and [Moving objects](https://documentation.samson-connect.net/users/latest/moving-objects/index.md) for transform editors. To start developing your own editors, use the documentation about [generating SAMSON Extensions](https://documentation.samson-connect.net/developers/latest/extension-generator/) and the [Documentation center](https://documentation.samson-connect.net/). ## Related pages - [Moving around](https://documentation.samson-connect.net/users/latest/moving-around/index.md): choose and use view and selection editors. - [Moving objects](https://documentation.samson-connect.net/users/latest/moving-objects/index.md): use move editors for transforms, alignment, and distribution. - [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md): install or develop editor extensions. # Exporters Use this reference when you need to understand how [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) writes document content to files and where exporter extensions fit. Exporters save content from the document to files. An exporter may write PDB, XYZ, or another supported format. [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) includes default exporters for common structures and visualizations, and you can add more exporters from [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). See the list of [formats supported by SAMSON](https://documentation.samson-connect.net/users/latest/supported-formats/index.md). Missing an exporter in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) ? [Contact us](mailto:contact@samson-connect.net). ## What this reference covers This page is a lookup page for the exporter extension family. Use [Supported formats](https://documentation.samson-connect.net/users/latest/supported-formats/index.md) when you need the format list, and [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) when you want to add or develop extensions. To start developing your own exporters, use the documentation about [generating SAMSON Extensions](https://documentation.samson-connect.net/developers/latest/extension-generator/) and the [Documentation center](https://documentation.samson-connect.net/). ## Related pages - [Supported formats](https://documentation.samson-connect.net/users/latest/supported-formats/index.md): check which file formats SAMSON can import and export. - [Importers](https://documentation.samson-connect.net/users/latest/importers/index.md): understand the matching extension family for reading files. - [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md): add or develop extension-based capabilities. # Importers Use this reference when you need to understand how [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) reads files and where importer extensions fit. Importers parse files so SAMSON can load structures, maps, meshes, and other objects into a document. An importer may read PDB, electron density, or another supported format. [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) includes default importers, and you can add more importers from [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). See the list of [formats supported by SAMSON](https://documentation.samson-connect.net/users/latest/supported-formats/index.md). Missing an importer in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) ? [Contact us](mailto:contact@samson-connect.net). ## What this reference covers This page is a lookup page for the importer extension family. Use [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md) when you want the task workflow for opening files, and [Supported formats](https://documentation.samson-connect.net/users/latest/supported-formats/index.md) when you need the format list. To start developing your own importers, use the documentation about [generating SAMSON Extensions](https://documentation.samson-connect.net/developers/latest/extension-generator/) and the [Documentation center](https://documentation.samson-connect.net/). ## Related pages - [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md): open local files, fetch structures, and understand documents. - [Supported formats](https://documentation.samson-connect.net/users/latest/supported-formats/index.md): check which file formats SAMSON can import and export. - [Exporters](https://documentation.samson-connect.net/users/latest/exporters/index.md): understand the matching extension family for writing files. - [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md): add or develop extension-based capabilities. # SAMSON Interface This page explains how the [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) interface is organized, where to find the main menus and panels, and which related pages cover each area in more detail. Use it as a reference hub for workspaces, panels, menus, and built-in windows. See [First look: the interface](https://documentation.samson-connect.net/users/latest/first-look/index.md) for the general description of the [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) interface. ## Start with these guides - [First look](https://documentation.samson-connect.net/users/latest/first-look/index.md): get the quick visual tour before using this full reference. ## Workspace [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides a number of various workspaces that modify the menu to better suit the needs and screen sizes. ## Menu The ribbon menu, located at the top of the interface, is composed of several menus depending on the currently chosen workspace. Note The menu changes depending on a [workspace](https://documentation.samson-connect.net/users/latest/interface/#workspace) and for the same workspace may slightly differ on Windows, Linux, and Mac. Below is the description of the menu for the Default [workspace](https://documentation.samson-connect.net/users/latest/interface/#workspace). ### Home The Home menu lets you manage [Documents](https://documentation.samson-connect.net/users/latest/documents/index.md), access the default editors, manage simulators, and access favorite commands (including [Apps](https://documentation.samson-connect.net/users/latest/apps/index.md)): **Group Documents**: - **File** - **New**: creates a new document with a user-defined name. - **Open...**: shows a modal dialog to open a document. Files with extensions .sam or .samx correspond to entire SAMSON documents, whereas files with other extensions are imported into the current document. - **Fetch**: [fetch structures](https://www.samson-connect.net/extensions/6f5d45c5-e76e-cdc8-52d5-d2821c128be8) from various data banks (RCSB Protein Data Bank, AlphaFold DB, ESM Metagenomic Atlas, PubChem, Crystallography Open Database, etc.). - **Save**: shows a modal dialog to save data to a file. Selecting files with extensions .sam or .samx saves the entire active document to the file, whereas selecting a file with another extension saves the current selection to the file, or the entire document if nothing is selected. - **Save as...**: same as **Save**, but with the possibility of saving to a different file, even if the document has already been saved. - **Save selection as...**: same as **Save as...**, but saves only the currently selected nodes. - **Close**: closes the active document. - **Recent**: shows the list of recently opened files. - **Documents**: switch between the opened [Documents](https://documentation.samson-connect.net/users/latest/documents/index.md), the number indicates the number of opened [Documents](https://documentation.samson-connect.net/users/latest/documents/index.md). **Group Embed**: - **Embed files**: shows a model dialog to choose one or more files that will be embedded in the active document. - **Embed folder**: shows a model dialog to choose a folder that will be embedded in the active document. **Group Share**: - **Publish**: [publishes a document](https://documentation.samson-connect.net/users/latest/share-documents/#sharing-documents) on [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) and provides a shareable link that you can share with others. - **Download**: [downloads a document](https://documentation.samson-connect.net/users/latest/share-documents/#downloading-shared-documents) shared with you using a document's identifier or a shareable link. **Group Structures**: - **Fetch**: [fetch structures](https://www.samson-connect.net/extensions/6f5d45c5-e76e-cdc8-52d5-d2821c128be8) from various data banks (RCSB Protein Data Bank, AlphaFold DB, ESM Metagenomic Atlas, PubChem, Crystallography Open Database, etc.). - **Predict**: predict a 3D structure of proteins using AlphaFold 2, Boltz-2, Chai-1, etc. - **View**: [view protein sequences](https://documentation.samson-connect.net/users/latest/sequence-view/index.md). - **Align**: [align protein sequences](https://documentation.samson-connect.net/tutorials/protein-aligner/protein-aligner/index.md). - **Validate**: [validate a structure](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/#validate-a-protein-system) by removing alternate locations, modifying non-standard residues, checking for clashes and bond lengths. - **Prepare**: [prepare a structure](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) with options to remove alternate locations, ligands, water, ions, and add hydrogens. - **Diagram**: show protein-ligand interaction diagram using the [Interaction Designer](https://documentation.samson-connect.net/users/latest/interaction-designer/index.md). - **Visualize**: apply [visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/index.md). **Group Tools**: - **Apps**: contains all the [apps](https://documentation.samson-connect.net/users/latest/apps/index.md) available in your SAMSON installation. You can add more apps from [SAMSON Connect - Marketplace](https://www.samson-connect.net/extensions). **Group AI**: - **Assistant**: shows/hides the [SAMSON AI assistant](https://documentation.samson-connect.net/users/latest/samson-ai/index.md). ### Edit The Edit menu lets you edit [Documents](https://documentation.samson-connect.net/users/latest/documents/index.md): **Group History**: - **Undo**: [undo an operation](https://documentation.samson-connect.net/users/latest/history/index.md). - **Redo**: [redo an operation](https://documentation.samson-connect.net/users/latest/history/index.md). **Group Clipboard**: - **Copy**: copy the selected part to the clipboard. - **Paste**: paste from the clipboard. - **Cut**: cut the selected part. **Group Add**: - **Folder**: add a folder to the active [document](https://documentation.samson-connect.net/users/latest/documents/index.md). - **Note**: add a note to the active [document](https://documentation.samson-connect.net/users/latest/documents/index.md). You can put in a note any plain text or html information to store it with the document. - **Script**: add a Python script to the active [document](https://documentation.samson-connect.net/users/latest/documents/index.md). - **Conformation**: stores a conformation of selected nodes in the active [document](https://documentation.samson-connect.net/users/latest/documents/index.md). - **Design**: create molecules in 2D and 3D simulataneously using the [Interaction Designer](https://documentation.samson-connect.net/users/latest/interaction-designer/index.md). **Group Adjust**: - **Add hydrogens**: adjust hydrogens in the selection. - **Remove hydrogens**: remove hydrogens from the selection. **Group Organize**: - **Align**: [align the selected objects](https://documentation.samson-connect.net/users/latest/moving-objects/#align-and-distribute-structures). - **Distribute**: [dsitribute the selected objects](https://documentation.samson-connect.net/users/latest/moving-objects/#align-and-distribute-structures). **Group Simulate**: - **Freeze/Unfreeze**: freezes or unfreezes selected atoms or all atoms in the document if the selection is empty. See [Minimizing a part of a molecule](https://documentation.samson-connect.net/users/latest/minimizing/#minimizing-a-part-of-a-molecule). - **Minimize**: run an [interactive minimization](https://documentation.samson-connect.net/users/latest/minimizing/index.md). - **Add simulator...**: add a [simulator](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/#simulators). Opens a window where you can set up a simulator - choose an interaction model and state updater. - **Start**: starts a [simulation](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md) or shows that a simulation is already running. - **Stop**: stops a [simulation](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md) or shows that a simulation is already stopped (there is no running simulation). ### Select The Select menu lets you perform various selections in [Documents](https://documentation.samson-connect.net/users/latest/documents/index.md): **Group Operations**: - **Find**: opens a find window which allows you to do complex searches in the active [document](https://documentation.samson-connect.net/users/latest/documents/index.md). - **Parent**: selects parent nodes of the selected nodes. - **Descendants**: selects all descendants of the selected nodes. - **Connected**: select atoms and bonds within the same connected components as the currently selected atoms. - **Similar**: selects structures similar to the currently selected ones based on names and/or hierarchy. - **Invert**: inverts the selection. - **Expand**: expands the selection. **Group Structures**: Actions related to [selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) based on various properties. - **Biology**: select binding sites, ligands, receptors, DNA, RNA, lipids, glycans, by chain, etc. - **Residues**: select amino and nucleic acid residues based on various properties. - **Res. and groups**: select residues and structural groups based on their IDs (sequence numbers). - **Atoms**: select atoms based on various properties. - **Bonds**: select bonds based on various properties. - **Ions**: select ions: monatomic, polyatomic, by name. - **Water**: select all water. **Group Add**: - **Group**: creates a group out of selected nodes. ### Visualization The Visualization menu lets you access visualization actions: **Group Capture**: - **Trace**: runs a path-tracing for better rendering. - **Save image**: captures the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) (the settings can be changed in the Preferences), or copy the capture in the clipboard. - **Save OBJ/glTF**: saves the nodes that possible (meshes, etc) in an [OBJ](https://www.samson-connect.net/extensions/f5eb4af6-6a1b-e7ba-4d40-2e8abcd91d50) or [glTF](https://www.samson-connect.net/extensions/6566e2fb-e705-5092-ff22-f6afca7890ae) file. **Group Add**: - **Label**: add [labels](https://documentation.samson-connect.net/users/latest/labeling/index.md) based on types of nodes or other properties. - **Color**: [colorize nodes](https://documentation.samson-connect.net/users/latest/colorizing/index.md) using various color schemes and [color palettes](https://documentation.samson-connect.net/users/latest/color-palettes/index.md). - **Visual model**: select and add one of the default [visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models): Ball and stick, Licorice, Lines, Van der Waals, Ribbons, Cartoon, Gaussian surface, Solvent Accessible Surface, Solvent Excluded Surface, etc; adds other [visual model](https://documentation.samson-connect.net/users/latest/models/#visual-models) for the selection, or apply a [visual preset](https://documentation.samson-connect.net/users/latest/visual-presets/index.md). - **Visualize**: apply [visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/index.md). - **Camera**: adds a [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) in the active document. - **Light**: adds a [light](https://documentation.samson-connect.net/users/latest/rendering/#lights) in the active document. - **Presentation**: adds a [presentation](https://documentation.samson-connect.net/users/latest/presenting/index.md) in the active document. **Group Rendering**: - **Options**: various [rendering options](https://documentation.samson-connect.net/users/latest/rendering-effects/index.md), can also be accessed in the Preferences. - **Anti-aliasing**: changes the [anti-aliasing rendering](https://documentation.samson-connect.net/users/latest/rendering-effects/#anti-aliasing). - **Clipping**: switch between [clipping preferences](https://documentation.samson-connect.net/users/latest/moving-around/#clipping-structures). - **Lighting**: switch between [lighting preferences](https://documentation.samson-connect.net/users/latest/rendering-effects/#lighting). - **Shadows**: switches on/off the [shadows rendering](https://documentation.samson-connect.net/users/latest/rendering-effects/#shadows). - **Ambient occlusion**: switches on/off the [screen-space ambient occlusion (SSAO) rendering](https://documentation.samson-connect.net/users/latest/rendering-effects/#ambient-occlusion). - **Bloom**: switches on/off the [bloom rendering](https://documentation.samson-connect.net/users/latest/rendering-effects/#bloom). - **Blur**: switches on/off the [depth of field rendering](https://documentation.samson-connect.net/users/latest/rendering-effects/#depth-of-field). - **Pinhole**: switches on/off the [pinhole rendering](https://documentation.samson-connect.net/users/latest/rendering-effects/#pinhole). - **Silhouettes**: switches on/off the [silhouettes rendering](https://documentation.samson-connect.net/users/latest/rendering-effects/#silhouettes). - **Render preset**: - Create a new render preset based on the current rendering settings. - Switch between default rendering presets (Default, High quality, Illustrative);. - Apply render presets available in all the opened documents. **Group Stereo**: - **Stereo on/off**: switches on/off stereo. - **Flip eyes**: flips eyes in stereo. ### Interface The Interface menu lets you manage the [SAMSON interface](https://documentation.samson-connect.net/users/latest/first-look/index.md), update [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md), and access logs: **Group Select**: - **Assistant**: shows/hides the [SAMSON AI assistant](https://documentation.samson-connect.net/users/latest/samson-ai/index.md). - **Document view**: shows/hides the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view). - **Inspector**: shows/hides the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). - **History**: shows/hides the [history view](https://documentation.samson-connect.net/users/latest/interface/#history). - **Assets**: shows/hides the asset libraries window. - **Periodic table**: shows/hides the periodic table. - **Job manager**: shows/hides the [job manager](https://documentation.samson-connect.net/users/latest/cloud/index.md). - **Animator**: shows/hides the [Animator](https://documentation.samson-connect.net/users/latest/interface/#animator). - **Python Console**: shows/hides the [Python Scripting](https://documentation.samson-connect.net/users/latest/scripting/index.md) console. - **Code Editor**: shows/hides the code editor. **Group Control**: - **Hide interface**: hides the [SAMSON interface](https://documentation.samson-connect.net/users/latest/first-look/index.md). - **Show log**: shows the [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) log. - **Preferences**: opens the [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) window. **Group Extend**: - **Get documents**: opens [SAMSON Connect - Documents](https://www.samson-connect.net/documents) web-page. - **Add extensions**: opens [SAMSON Connect - Marketplace](https://www.samson-connect.net/extensions) web-page. **Group Update**: - **Update SAMSON**: checks for [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) updates. ### Help The Help menu gives you access to various documentation, tutorials, and the forum. ## Viewport menus The menu in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) provides a quick access to the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) associated commands, selection associated commands, favorite [apps](https://documentation.samson-connect.net/users/latest/apps/index.md), all the [editors](https://documentation.samson-connect.net/users/latest/editors/index.md) with quick actions associated to the active editor. The menu at the bottom of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) has commands associated to the view, rendering, and the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). The menu in the top-right corner of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) has commands associated to selection: - **Selection filter**: lets you specify the types of nodes to which the selection should be applied. - **Select all**: selects all selectable nodes in the active [document](https://documentation.samson-connect.net/users/latest/documents/index.md) based on the current selection filter. - **Deselect all**: deselects all selected nodes in the active [document](https://documentation.samson-connect.net/users/latest/documents/index.md). The menu on the right side of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) provides a quick access to the favorite apps. The menu on the left side of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) provides access to all the [editors](https://documentation.samson-connect.net/users/latest/editors/index.md) and, above it, in the top-left corner of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md), quick access commands for the active editor. The editor menu contains: - **Favorite**: gives you a fast access to your favorite editors. - **View** (`V`): the [View editor](https://documentation.samson-connect.net/users/latest/moving-around/#how-to-navigate-with-the-view-editor). - **Point selection** (`P`): the [Point selection editor](https://documentation.samson-connect.net/users/latest/moving-around/#how-to-navigate-with-the-point-selection-editor). - **Rectangle selection** (`R`): the [Rectangle selection editor](https://documentation.samson-connect.net/users/latest/moving-around/#how-to-navigate-with-the-rectangle-selection-editor). - **Add** (`A`): [add atoms, fragments, connect atoms with bonds](https://documentation.samson-connect.net/users/latest/building-molecules/index.md). - **Bonds** (`B`): [change bond order](https://documentation.samson-connect.net/users/latest/building-molecules/#changing-bond-order). - \**Charge* (`C`): [change atom order](https://documentation.samson-connect.net/users/latest/building-molecules/#changing-atom-formal-charge). - **Create linear patter** (`L`): see [Creating patters](https://documentation.samson-connect.net/users/latest/creating-patterns/index.md). - **Create curved patter** (`Q`): see [Creating patters](https://documentation.samson-connect.net/users/latest/creating-patterns/index.md). - **Create circular patter** (`W`): see [Creating patters](https://documentation.samson-connect.net/users/latest/creating-patterns/index.md). - **Displace** (`D`): [the displace move editor](https://documentation.samson-connect.net/users/latest/moving-objects/#move-editors). - **Local move** (`M`): [the move editor in the local coordinates](https://documentation.samson-connect.net/users/latest/moving-objects/#move-editors) (local to the selection). - **Global move** (`K`): [the move editor in the global XYZ coordinates](https://documentation.samson-connect.net/users/latest/moving-objects/#move-editors). - **Twist**: the [Twister editor](https://www.samson-connect.net/extensions/8b38b2fd-de8d-f24a-36e7-7ac624173f9f). - **Erase** (`E`): erase the selected nodes in the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). - **Label** (`Ctrl`/`Cmd` + `L`): add [labels](https://documentation.samson-connect.net/users/latest/labeling/index.md) to atoms, bonds, residues and other nodes depending on the Selection filter. - **Measure** (`Ctrl`/`Cmd` + `M`): [measure distances and angles between atoms](https://documentation.samson-connect.net/users/latest/measuring/index.md). - **All**: all the available editors. This menu shows all the [editors](https://documentation.samson-connect.net/users/latest/editors/index.md) installed in your [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), subdivided into categories. You can add more editors from [SAMSON Connect - Marketplace](https://www.samson-connect.net/extensions). ## Viewport The [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) is dedicated to showing the visual representation of molecules. ## Find everything The **Find everything** search box placed in the top-right corner allows you to easily find commands, apps, and editors and get help on them. It searches in names, tooltips, and shortcuts of commands, apps, and editors. ## Document view The **Document view** shows the hierarchical data graph of the active [document](https://documentation.samson-connect.net/users/latest/documents/index.md). You can open the document view by clicking on **Interface > Document view** or via shortcut `Ctrl`+`1` on Windows and Linux or `Cmd`+`1` on Mac. In the document view you can, among other things: - view the document's structure - show/hide nodes - [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) nodes in the document - filter the nodes using [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) and names of the nodes via *Filter nodes...* - change the documents structure, e.g. by drag-and-dropping nodes - apply specialized actions on nodes via their context menu and context toolbar You can simultaneously have several [Documents](https://documentation.samson-connect.net/users/latest/documents/index.md) opened in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), however, only one [document](https://documentation.samson-connect.net/users/latest/documents/index.md) is active at any given time - the one you see in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view). Having several [Documents](https://documentation.samson-connect.net/users/latest/documents/index.md) is useful, for example, when you want to do different tasks with different molecules or copy structures from one document to another. To switch between [Documents](https://documentation.samson-connect.net/users/latest/documents/index.md), click on the **Documents** list in the top-left corner of the menu, or **Home > Documents**, or use `Ctrl`/`Cmd` + `Tab` or `Ctrl`/`Cmd` + `Shift`+`Tab` shortcuts. You can also see there the number of opened documents. See also [Documents](https://documentation.samson-connect.net/users/latest/documents/index.md), [node types](https://documentation.samson-connect.net/users/latest/node-types/index.md). ## History The **History** shows a [history of undoable operations](https://documentation.samson-connect.net/users/latest/history/index.md), by clicking on any of them you may return to the associated state in the history. To open the **History** click on **Interface > History** or via shortcut `Ctrl`+`3` on Windows and Linux or`Cmd`+`3` on Mac. Note Not all the operations are undoable, if in between of undoable operations you did operations which are not undoable it might not be possible for [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) to properly undo operations, which may result in a loss of data. See also [History: undo and redo](https://documentation.samson-connect.net/users/latest/history/index.md) ## Inspector The **Inspector** provides a possibility to [view and edit the properties of the selected nodes](https://documentation.samson-connect.net/users/latest/inspecting/index.md). To open the **Inspector**, click on **Interface > Inspector** or press `Ctrl`+`2` on Windows and Linux or `Cmd`+`2` on Mac. Note The Inspector inspects all the selected nodes and edits all the selected nodes. You can use the filter to see matching attributes only. See also [Inspecting](https://documentation.samson-connect.net/users/latest/inspecting/index.md) ## Asset Browser The **Asset Browser** gathers the [assets](https://documentation.samson-connect.net/users/latest/building-molecules/#asset-browser) included by default in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) together with the assets you can obtain from [SAMSON Connect](https://www.samson-connect.net/). To open the **Asset Browser**, click on **Interface > Assets** or press `Ctrl`+`4` on Windows and Linux or `Cmd`+`4` on Mac. See also [Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md) ## Periodic Table The **Periodic table** shows the periodic table and lets you [build and modify molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md) - simply click on an atom and you will be switched to the **Add** editor mode. To open the **Periodic table**, click on **Interface > Periodic table** or press `Ctrl`+`5` on Windows and Linux or `Cmd`+`5` on Mac. See also [Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md) ## Job Manager The **Job manager** lets you [manage jobs launched in the Cloud](https://documentation.samson-connect.net/users/latest/cloud/index.md) (for e.g., protein structure prediction using AlphaFold and NVIDIA BioNeMo Services, or molecular dynamics simulations using GROMACS). To open the **Job manager**, click on **Interface > Job manager** or press `Ctrl`+`6` on Windows and Linux or `Cmd`+`6` on Mac. See also [Cloud computations](https://documentation.samson-connect.net/users/latest/cloud/index.md) ## Animator The **Animator** provides a possibility to view and edit [presentations](https://documentation.samson-connect.net/users/latest/presenting/index.md), add and modify [animation](https://documentation.samson-connect.net/users/latest/presenting/index.md) effects. To open the **Animator**, click on **Interface > Animator** or press `Ctrl`/`Cmd` + `7`, or if you already have a [presentation](https://documentation.samson-connect.net/users/latest/presenting/index.md) in the document simply double-click on the [presentation](https://documentation.samson-connect.net/users/latest/presenting/index.md). See also [Presenting and animating](https://documentation.samson-connect.net/users/latest/presenting/index.md), [Animations](https://documentation.samson-connect.net/users/latest/animations/index.md) ## Python Console The **Python Console** lets you access [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) functionality using Python and automate workflows with scripts. To open the **Python Console**, click on **Interface > Python Console** or press `Ctrl`+`8` on Windows and Linux or `Cmd`+`8` on Mac. See also [Python Scripting](https://documentation.samson-connect.net/users/latest/scripting/index.md) ## Code editor The **Code editor** opens and modifies text files, including Python scripts, and can run Python files. To open the **Code editor**, click on **Interface > Code editor** or press `Ctrl`+`9` on Windows and Linux or `Cmd`+`9` on Mac. See also [Python Scripting](https://documentation.samson-connect.net/users/latest/scripting/#code-editor) ## Status bar The status bar is placed at the bottom of the [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) window and shows status messages from [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) and [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) . ## Related pages - [First look](https://documentation.samson-connect.net/users/latest/first-look/index.md) - [Preferences](https://documentation.samson-connect.net/users/latest/preferences/index.md) # Models Use this reference when you need to identify the model categories used in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) documents and understand which category matches the object you see in the Document view. [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) represents nanosystems using **five categories of models**: - [Structural nodes](#structural-models) describe geometry and topology. - [Visual models](#visual-models) provide graphical representations. - [Dynamical models](#dynamical-models) describe dynamical degrees of freedom. - [Interaction models](#interaction-models) describe energies and forces. - [Property models](#property-models) describe properties that do not enter in the first four model categories. Apart from these models, [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) also has [state updaters](https://documentation.samson-connect.net/users/latest/models/#state-updaters) used in the minimization and [simulations](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md). Models and [state updaters](https://documentation.samson-connect.net/users/latest/models/#state-updaters) are [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) [document](https://documentation.samson-connect.net/users/latest/documents/index.md). See also [Node types](https://documentation.samson-connect.net/users/latest/node-types/index.md) ## What this reference covers This page defines the main model categories in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). Use [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) for the task workflow of adding visual models, and [Modeling and Simulation](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md) for simulator, interaction model, and state updater workflows. ## Structural models **Structural models** describe the geometry and topology of nanosystems in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). Typically, a structural model contains atoms and bonds, and might contain [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) representing higher organization levels, e.g. molecules, chains, residues, etc. ## Visual models **Visual models** are used to provide graphical representations. A visual model may be e.g. a secondary structure representation of a protein, a gaussian surface, an isosurface of an electron density, a volumetric representation of an electrostatic field, etc. [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides a set of visual models by default and you can add more from [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) ([SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) may also provide visual models). You can see some of the default visual models supplied with SAMSON on the image below. Visual models are usually applied to selected nodes or to the whole document if nothing is selected as follows: - via the context toolbar menu of the selection - using **Visualization > Add > Visual model** - shortcut: `Ctrl`/`Cmd` + `Shift`+`V` Use [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) to learn how to apply visual models. For some visual models, you can modify their visualization parameters in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). For that, select the visual model in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) and click on **Inspect** in the context menu. The default visual models in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) make it possible to highlight and select atoms, residues, chains, etc. directly via surfaces depending on the current [selection filter](https://documentation.samson-connect.net/users/latest/selecting/#selection-filters). To start developing your own visual models, use the documentation about [generating SAMSON Extensions](https://documentation.samson-connect.net/developers/latest/extension-generator/) and the [Documentation center](https://documentation.samson-connect.net/). See also - [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) - [Color schemes](https://documentation.samson-connect.net/users/latest/colorizing/#color-schemes) - [Visual presets](https://documentation.samson-connect.net/users/latest/visual-presets/index.md) - [Presenting](https://documentation.samson-connect.net/users/latest/presenting/index.md) ## Dynamical models **Dynamical models** are used to indicate where degrees of freedom are in [structural nodes](#structural-models). For example, a particle system dynamical model applied to a group of particles (atoms) assigns three translational degrees of freedom to each atom. Dynamical models describe the dynamical state and store positions, momenta, and masses. ## Interaction models **Interaction models** are used to represent energies and forces in a dynamical model and are used in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) to perform various modeling and simulation tasks. An interaction model could be, for example, a simple Lennard-Jones model to describe unbounded interactions between a group of particles (atoms), a spring model, an elastic network model, a universal force field, etc. An interaction model is in charge of providing forces corresponding to the degrees of freedom in a dynamical model. For example, an interaction model applied to a particle system dynamical model provides both the total energy of the particle system and the force applied to each particle (atom) in the particle system. [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides a set of interaction models by default and you can add more from [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). To start developing your own interaction models, use the documentation about [generating SAMSON Extensions](https://documentation.samson-connect.net/developers/latest/extension-generator/) and the [Documentation center](https://documentation.samson-connect.net/). ## Property models **Property models** are used to represent properties of nanosystems that are not already described by the first four categories of models. For example, property models may be e.g. a simple number describing the gyration radius of a protein, a scalar field (such as an electron density), a vector field (to represent e.g. an electrostatic field), a function, etc. ## State updaters **State updaters** implement methods used to advance states during [simulations](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md). State updaters may be e.g. minimization algorithms, Monte Carlo methods, molecular dynamics algorithms, etc. [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides a set of state updaters by default and you can add more from [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md). To start developing your own state updaters, use the documentation about [generating SAMSON Extensions](https://documentation.samson-connect.net/developers/latest/extension-generator/) and the [Documentation center](https://documentation.samson-connect.net/). ## Related pages - [Node types](https://documentation.samson-connect.net/users/latest/node-types/index.md): understand where models fit in document hierarchy. - [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md): add visual models to represent structures. - [Modeling and Simulation](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md): use interaction models, dynamical models, and state updaters in simulations. - [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md): add or develop model extensions. # Node types This page introduces the main node types used in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) documents and explains how they are organized in the document hierarchy. Use it when you need to understand what a node represents before selecting, inspecting, or scripting it. [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) [document](https://documentation.samson-connect.net/users/latest/documents/index.md) are composed of *nodes*. The image below shows some of the possible node types and their corresponding icons in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view). See also: [Models](https://documentation.samson-connect.net/users/latest/models/index.md) ## Hierarchy [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) [Documents](https://documentation.samson-connect.net/users/latest/documents/index.md) have a hierarchical structure: each node has one and only one parent, and possibly some children or references to other nodes. Nodes of a given type can only have children of some specific types: - A **document** can contain the same node types as the folder, it is basically the root folder. Additionally, it can contain cameras. - A **folder** can contain [folders](https://documentation.samson-connect.net/users/latest/documents/#folders), [files](https://documentation.samson-connect.net/users/latest/documents/#files), Python scripts, structural models, visual models, dynamical models, interaction models, property models, simulators, labels, notes, render presets. - A **presentation** contains [animations](https://documentation.samson-connect.net/users/latest/presenting/index.md). - A **structural model** can contain atoms, backbones, bonds, chain, molecules, residues, segments, side chains, and structural groups. - A **structural group** can contain atoms, backbones, bonds, chain, molecules, residues, segments, side chains, and structural groups. - A **molecule** can contain structural groups, chains, segments, residues, atoms, and bonds. - A **chain** can contain structural groups, segments, residues, atoms, and bonds. - A **segment** can contain atoms, bonds, structural groups, and residues. - A **residue** can contain a single backbone and a single side chain. - A **backbone** can contain atoms and bonds. - A **side chain** can contain atoms and bonds. - A **simulator** can contain a state updater. The following nodes cannot have children: - [Cameras](https://documentation.samson-connect.net/users/latest/camera/index.md) - [visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models) - [dynamical models](https://documentation.samson-connect.net/users/latest/models/#dynamical-models) - [interaction models](https://documentation.samson-connect.net/users/latest/models/#interaction-models) - [property models](https://documentation.samson-connect.net/users/latest/models/#property-models) - [state updaters](https://documentation.samson-connect.net/users/latest/models/#state-updaters) - conformations - paths - files - scripts - notes - render presets Nodes can also *reference* other nodes that are not their children: - A **bond** references two atoms. - A **node group** references the nodes contained in the group. - A **H-bond group** contains H-bonds that reference two to three atoms (an acceptor, a donor, a hydrogen), but are not the parent of the referenced atoms. - A **conformation** references a group of atoms with their position saved. - A **path** is a trajectory of a group of atoms and references this group of atoms. - A **dynamical model** references structural nodes. - An **interaction model** references a dynamical model. - A **simulator** references a dynamical model and an interaction model. Some other types of nodes: - A **file** represents any type of an embedded file, e.g. a PDF, an image, some data file, some structure file, etc., basically, any type of file. - A **script** represents a Python script file, it can be opened via [Code editor](https://documentation.samson-connect.net/users/latest/interface/#code-editor) and launched using the integrated [Python console](https://documentation.samson-connect.net/users/latest/scripting/index.md). - A **note** can contain text (including HTML), e.g. describing the current document, molecules, experiments, etc. - A **render preset** contains rendering settings. ## Related pages - [Documents](https://documentation.samson-connect.net/users/latest/documents/index.md): understand how nodes are stored in document hierarchies. - [Models](https://documentation.samson-connect.net/users/latest/models/index.md): learn how model nodes represent structure, visuals, dynamics, interactions, and properties. - [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md): select and filter nodes by type and attributes. - [Inspecting](https://documentation.samson-connect.net/users/latest/inspecting/index.md): inspect node attributes in the Inspector. # Preferences To open the **Preferences** panel: **Interface > Preferences** or `Ctrl`+`K` on Windows and Linux or `Cmd`+`,` on Mac. Tip Use the search in **Preferences** to quickly find the settings you are looking for. ## What this reference covers Use this reference when you need to find where a setting lives in the **Preferences** panel or understand how a preference category affects the interface, editors, rendering, or file handling. Preferences are organized in several categories visible on the left side of the panel. If the **Automatically test** option in the bottom part of the **Preferences** panel is checked, the changes in preferences immediately affect the interface and rendering. ## Apps This section contains settings for the [apps](https://documentation.samson-connect.net/users/latest/apps/index.md) that expose their settings. ## Assitant Settings for the [SAMSON AI Assistant](https://documentation.samson-connect.net/users/latest/samson-ai/index.md). ## Editors This section contains settings for the default [editors](https://documentation.samson-connect.net/users/latest/editors/index.md) and other editors that expose their settings. ### Add In the **Editors > Add** section of the **Preferences** panel you may modify the Add editor settings. ### Erase In the **Editors > Erase** section of the **Preferences** panel you may modify the Erase editor settings. ### Move In the **Editors > Move** section of the **Preferences** panel you may modify the Move editors settings. ### Minimize In the **Editors > Minimize** section of the **Preferences** panel you may modify the settings for the interactive minimization. ### Select In the **Editors > Select** section of the **Preferences** panel you may modify the Select editor settings. ### Snapping In the **Editors > Snapping** section of the **Preferences** panel you may modify the snapping settings which are used in some move editors. ## Exporters This section contains settings for [exporters](https://documentation.samson-connect.net/users/latest/exporters/index.md) that expose their settings. ## Importers This section contains settings for [importers](https://documentation.samson-connect.net/users/latest/importers/index.md) that expose their settings. ## Interface ### Captures The preferences for the captures of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) may be changed in the **Interface > Captures** section of the **Preferences** panel: This section lets you choose the folder in which captures are saved when pressing `F10`, the prefix used in filenames (prefix to which is appended an integer denoting the capture index), the file format (jpg, png or bmp), and the size (custom, or a multiple of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) size). The **Preserve aspect ratio** option may be checked to maintain proportions when changing the width or the height of the capture. The **Transparent background** option may be checked to remove the background from the image when saving with the png format. ### Dark mode In the **Interface > Dark mode** section of the **Preferences** panel you may switch to the Dark mode version of the interface and back. ### Menu In the **Interface > Menu** section of the **Preferences** panel you may toggle showing of some specialized menu tabs. ### Tips In the **Interface > Tips** section of the **Preferences** panel you may modify the tips settings. ### Windows In the **Interface > Windows** section of the **Preferences** panel you may set the following preferences for the windows: opacity, casting of shadows. ## Network ### Proxy If you need to specify the proxy settings, you can do it in the **Network / Proxy** section of the **Preferences** panel: This settings are useful if you are using a proxy to access the Internet. ## Rendering ### Ambient occlusion The ambient occlusion settings may be changed in the **Rendering > Ambient occlusion** section of the **Preferences** panel: Ambient occlusion improves the perception of depth in molecules, by simulating the fact that deeper regions are less accessible to light, and are thus darker. Two types of ambient occlusion are handled in SAMSON: - **Screen-space ambient occlusion** efficiently provides an approximate simulation, but is sensitive to the distance to the camera. - **Object-space ambient occlusion** is more realistic, but slower. Even the screen-space ambient occlusion is very useful to improve the depth perception however. ### Anti-aliasing The anti-aliasing settings may be changed in the **Rendering > Anti-aliasing** section of the **Preferences** panel: Anti-aliasing removes jagged edges from images and may significantly improve rendering. Fast Approximate Anti-Aliasing (FXAA) is typically very efficient and can be activated on most recent graphics cards. ### Background The background of the [viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md) may be changed in the **Rendering > Background** section of the **Preferences** panel: Four options are available: - **SAMSON**: the default SAMSON background - **Black**: an entirely black background - **White**: an entirely white background - **Custom**: a gradient from a user-defined top color to a user-defined bottom color ### Bloom The bloom settings may be changed in the **Rendering > Bloom** section of the **Preferences** panel: The Bloom effect adds a controllable *halo* around the brightest parts of the image to simulate imaging artefacts, which may add realism to images. ### Cameras The camera settings allow you to switch on/off the orthographic projection (it can also be modified for a camera in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector)): ### Depth of field The depth of field settings may be changed in the **Rendering > Depth of field** section of the **Preferences** panel: This effect simulates the depth of field effect produced by actual cameras (e.g. blurred distant objects). If enabled, when you zoom on the molecule its distant parts will be blurred. ### Fog The fog settings may be changed in the **Rendering > Fog** section of the **Preferences** panel: Basically, fog makes distant objects less visible. Fog attenuates distant parts by blending them progressively with the background. Turn it on to make it easier to focus on the foreground. The near and far distances are based on the camera location and determine where the fog is enabled. Before the *near distance* there is no fog, after the *far distance* every node is invisible. The *strength* parameter influences the speed at which the fog is appearing. ### Grid The grid settings may be changed in the **Rendering > Grid** section of the **Preferences** panel: ### Labels The labels preferences may be changed in the **Rendering > Labels** section of the **Preferences** panel: You can specify the font for labels and the number of decimal places for angles and distances shown in labels. ### Lighting The lighting parameters may be changed in the **Rendering > Lighting** section of the **Preferences** panel: This section makes it possible to control the parameters of the two point lights that illuminate the document, as well as global parameters. Each light has the following parameters: - **Light color**: click the square to change the color of the light - **Light intensity** (between 0 and 1): the intensity of the light - **Specular intensity** (between 0 and 1): the intensity of the light reflection on surfaces. High values make surfaces look like plastic, while low values make surfaces look matte. - **Specular power** (between 0 and 1000): the decay of specular reflection. High values produce sharper specular reflections. - **Longitude and latitude** control the position of the light. The first light is typically the main light, which is thus typically brighter than the second light (a *back light*). Finally, three more parameters are global: - **Fresnel intensity** (between 0 and 1): the amount of background light reflected at grazing angles - **Fresnel power** (between 0 and 100): how fast the Fresnel effect decays - **Ambient light**: the amount of light that reaches objects, even when the intensity of both lights is set to 0. ### Path tracing The path tracing settings may be changed in the **Rendering > Path tracing** section of the **Preferences** panel: The path tracing settings affect how [rendering with Cycles](https://documentation.samson-connect.net/users/latest/rendering/index.md) is done. ### Pinhole The pinhole settings may be changed in the **Rendering > Pinhole** section of the **Preferences** panel: The Pinhole effect simulates looking through a pinhole, which may be useful when you want to focus attention on the center of the image (for example, a ligand followed by the camera using the new Follow atoms animation). ### Presentations The presentations settings may be changed in the **Rendering > Presentations** section of the **Preferences** panel: ### Selection The selection preferences may be changed in the **Rendering > Selection** section of the **Preferences** panel: You can specify the color of selection, its opacity, and to show or not the selection box. The highlighting color is the color used to highlight the node over which you hover in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). This helps you see what nodes will be selected. The outline color is the color which used to colorize the outline of the highlighted or selected nodes. You may set the opacity of the outline to zero to increase the graphics performance and eliminate some lags on old graphics cards. ### Shadows The shadows settings may be changed in the **Rendering > Shadows** section of the **Preferences** panel: Shadows are particularly helpful to improve the perception of relative positions. Without shadows, it may be difficult to perceive the relative positions. In case of an old graphics card you may want to either disable this option, or choose the lower preset. ### Silhouettes The silhouettes settings may be changed in the **Rendering > Silhouettes** section of the **Preferences** panel: Silhouettes make it easier to separate regions with different depths. Turn on silhouettes to produce clearly delineated structures. ### Scale The scale settings may be changed in the **Rendering > Scale** section of the **Preferences** panel: ### Stereo The stereo view preferences may be changed in the **Rendering > Stereo** section of the **Preferences** panel: Stereo settings are applied to the stereo view (3D glasses). ### Structural model settings The atom radius and bond radius may be changed in the **Rendering > Structural models** section of the **Preferences** panel: ## Installation ### General The general installation info can be viewed in the **Installation > General** section of the **Preferences** panel: The general installation info shows the following: - Your user type (User / Developer) - E-mail address used for registration on [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md) - Information on your graphics cards - Frequency of update checks - Information on the SAMSON Installation (the SAMSON key, the SAMSON version, the location, and the installation date) - For a developer, information on the SAMSON SDK Installation (the SAMSON SDK key, the SAMSON SDK version, the location, and the installation date) ### Updates The updates installation info can be viewed in the **Installation > Updates** section of the **Preferences** panel: This page shows the availability of updates for [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) SDK and [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md), the current versions installed, and a possibility to check the detailed information on the installed [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) by clicking the **Details** button which should open a web-page associated with this [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md). In case if you are a developer, this page also shows information on the [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) developed and installed by you locally. You can uninstall them by pressing the **Uninstall** button. ## Related pages - [Rendering effects](https://documentation.samson-connect.net/users/latest/rendering-effects/index.md) - [Interface](https://documentation.samson-connect.net/users/latest/interface/index.md) # Sequence view [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides an interactive **Sequence View** which is in sync with the document: residues selected in a Sequence View become selected in the Document View and the 3D Viewport, and vice versa. Sequence Views let you colorize residues in the sequence based on biophysical properties, and these colors can be transferred to the residues in the 3D Viewport: To access Sequence Views, either click the **View sequence** command from the **Home** menu: or right-click on a structure and select **Structural model > View sequence** from the **Context menu**: If a structure contains multiple chains, a pop-up will appear to let you choose which sequence(s) to view: ## Related pages - [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md): use selected residues in downstream structure workflows. - [Colorizing](https://documentation.samson-connect.net/users/latest/colorizing/index.md): apply meaningful colors to structures and visual models. - [Visualize and present](https://documentation.samson-connect.net/users/latest/visualize-and-present/index.md): return to visualization and presentation workflows. # Supported formats [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) supports a wide range of formats for importing and exporting various data (molecular systems, meshes, images, etc). [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) can also [embed](https://documentation.samson-connect.net/users/latest/loading-molecules/#embedding) almost any type of file (scripts, PDFs, images, data, etc.) into [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) [Documents](https://documentation.samson-connect.net/users/latest/documents/index.md). Thanks to the [Code Editor](https://documentation.samson-connect.net/users/latest/interface/#code-editor) in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) you can also open, edit, and save any text (non-binary) file, including Python scripts. ## What this page covers This reference page helps you find which file formats [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) can import or export and which extension family handles them. Below is a non-comprehensive list of formats supported in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) for importing and exporting various types of data. Most of these formats are available with [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) right away, but for some, it is necessary to add an extension (click on the extension link). Please note that [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) might support additional formats that are not listed here. ## SAMSON formats [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) has its own formats (SAM, SAMX) that support an extensive variety of types of data that can be opened, created, and saved by [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), among them are molecular structures ([structural models](https://documentation.samson-connect.net/users/latest/models/#structural-models), etc.), groups, [visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models), meshes, [animations](https://documentation.samson-connect.net/users/latest/presenting/index.md), notes, [simulators](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/#simulators) (interaction models and state updaters), etc. SAMSON formats can also embed folders and files (scripts, PDFs, images, data, etc.). | File type | Description | Read | Write | | --------- | -------------------- | ---- | ----- | | SAM | SAMSON binary format | | | | SAMX | SAMSON XML format | | | ## Molecular structures | File type | Description | Read | Write | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------- | | ARC | [Tinker format](http://chembytes.wikidot.com/tnk-tut00#toc2) | | | | CIF | [Crystallographic Information File](https://www.iucr.org/resources/cif) - CIF for crystal structures via [Crystal Creator App](https://www.samson-connect.net/extensions/58a75a78-abbc-2c60-6214-e668b5c45a0d) - The [macromolecular Crystallographic Information File (mmCIF)](https://mmcif.wwpdb.org/). Aliases: PDBx, mmCIF | | (PDBx/mmCIF format) | | CML | [Chemical Markup Language file](https://www.xml-cml.org) | | | | CSSR | [SERC Daresbury Laboratory's Cambridge Structure Search and Retrieval (CSSR) file](http://www.chem.cmu.edu/courses/09-560/docs/msi/modenv/D_Files.html#944777) | | | | GRO | [GROMACS structure file](https://manual.gromacs.org/current/reference-manual/file-formats.html#gro) | | | | GZ | GZ archive file | | | | LMP, LMPDAT | [LAMMPS Data file](https://docs.lammps.org/read_data.html#format-of-a-data-file). Alias for read: DATA | | | | MMTF | The [Macromolecular Transmission Format (MMTF)](https://mmtf.rcsb.org/) file | | | | MOL2 | Tripos MOL2 file | | | | MOLDEN | [Molden file](https://www.theochem.ru.nl/molden/molden_format.html) | | | | PDB | [Standard PDB file](https://www.wwpdb.org/documentation/file-format). Aliases for read: ENT, VDB, PDB1, PDB2, etc. | | | | PDBQT | PDBQT file | \*ADVE | \*ADVE | | PSF | CHARMM, NAMD [protein structure file (PSF)](https://www.ks.uiuc.edu/Training/Tutorials/namd/namd-tutorial-unix-html/node23.html) file | | | | PARM7, PRMTOP | AMBER topology file, used when loading [AMBER NetCDF trajectories](https://ambermd.org/netcdf/nctraj.xhtml) | | | | SDF | Chemical table file (CT File) format. Supports V2000 and V3000. Aliases for read: MOL, SD | | | | SMI | [SMILES file](http://opensmiles.org/opensmiles.html) Aliases for read: SMILES SMILES can also be read and generated with the [SMILES Manager](https://www.samson-connect.net/extensions/ce09650a-c071-4e84-1f6a-b8706937d5c1) extension. | | | | TOP | [GROMACS topology file](https://manual.gromacs.org/current/reference-manual/file-formats.html#top) | | \*GW | | TPR | [GROMACS run topology file](https://manual.gromacs.org/current/reference-manual/file-formats.html#tpr) | | \*GW | | XYZ | A simple coordinate trajectory format | | | **ADVE** - PDBQT files can be generated with [AutoDock Vina Extended](https://www.samson-connect.net/extensions/1afc50e6-3567-fa25-1e09-415ebf4d05d7) extension which can also load PDBQT files from docking projects done using **AutoDock Vina Extended**. **GW** - GROMACS project files can be generated with [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5) extension. ## Molecular trajectories | File type | Description | Read | Write | | --------- | -------------------------------------------------------------------------------------------------------------------------- | ---- | ----- | | ARC | [Tinker format](http://chembytes.wikidot.com/tnk-tut00#toc2) | | | | DCD | CHARMM, NAMD, or LAMMPS binary trajectory | | | | LAMMPSTRJ | [LAMMPS](https://www.lammps.org/) ASCII trajectory written by the LAMMPS [dump](https://docs.lammps.org/dump.html) command | | | | NC | [AMBER NetCDF format](http://ambermd.org/netcdf/nctraj.xhtml). Aliases for read: NCDF, NCTRAJ | | | | PDB | [Standard PDB file](https://www.wwpdb.org/documentation/file-format). Aliases for read: ENT, VDB, PDB1, PDB2, etc. | | | | TNG | [Trajectory Next Generation file](https://manual.gromacs.org/current/reference-manual/file-formats.html#tng) | | | | TRR | [GROMACS TRR trajectory](https://manual.gromacs.org/current/reference-manual/file-formats.html#trr) | | | | TRJ | [GROMACS TRJ trajectory format](https://manual.gromacs.org/archive/5.0.7/online/trj.html) | | | | XTC | [GROMACS compressed trajectory](https://manual.gromacs.org/current/reference-manual/file-formats.html#xtc) | | | | XYZ | A simple coordinate trajectory format | | | To read and write some of the trajectory formats, [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) uses the [chemfiles](https://chemfiles.org/) library. ## 3D geometries [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) loads 3D geometries as meshes. [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) can export the following [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) as 3D geometries: [structural models](https://documentation.samson-connect.net/users/latest/models/#structural-models), [visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models) (if such functionality is implemented for this [visual model](https://documentation.samson-connect.net/users/latest/models/#visual-models)), and meshes. | File type | Description | Read | Write | | --------- | ---------------------- | ---- | ----- | | OBJ | Wavefront OBJ file | | | | glTF | GL Transmission Format | | | | STL | | | | ## Python scripts Use [Python Scripting](https://documentation.samson-connect.net/users/latest/scripting/index.md) to learn how to use Python scripts in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). | File type | Description | Read | Write | Execute | | --------- | -------------- | ---- | ----- | ------- | | PY | Python scripts | | | | ## Images Images are loaded as meshes. To save an image, use [Capture](https://documentation.samson-connect.net/users/latest/visualizing/#capturing-viewport). | File type | Read | Write | | --------- | ---- | ----- | | BMP | | | | JPG | | | | PNG | | | | GIF | | | | PBM | | | | PPM | | | | XBM | | | | XPM | | | **GIF** is loaded not as an animation but only as a single image. ## Movies or animations [Animations](https://documentation.samson-connect.net/users/latest/presenting/index.md) in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) can be saved as movies. Use [Presenting and animating](https://documentation.samson-connect.net/users/latest/presenting/index.md) to learn how to create and save animations in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). | File type | Read | Write | | --------- | ---- | ----- | | GIF | | | | MP4 | | | | WEBM | | | ## DNA origami The formats for DNA origami are supported by the [Adenita](https://www.samson-connect.net/extensions/dda2a078-1ab6-96ba-0d14-ee1717632d7a) extension. | File type | Description | Read | Write | | --------- | ------------------------------------------------------------------------------------------------------ | ---- | ----- | | ADN | [Adenita](https://www.samson-connect.net/extensions/dda2a078-1ab6-96ba-0d14-ee1717632d7a) format | | | | ADNPART | [Adenita](https://www.samson-connect.net/extensions/dda2a078-1ab6-96ba-0d14-ee1717632d7a) parts format | | | | JSON | Cadnano or legacy Adenita parts format | | | | PLY | Cadnano mesh | | | ## Adding a new format If [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) does not support a file format that you would like to use and you would like us to add it to [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), then please contact us via the [SAMSON Connect Forum](https://forum.samson-connect.net/). You can also develop your own [importers](https://documentation.samson-connect.net/users/latest/importers/index.md) and [exporters](https://documentation.samson-connect.net/users/latest/exporters/index.md). Use the documentation about [generating SAMSON Extensions](https://documentation.samson-connect.net/developers/latest/extension-generator/) and the [Documentation center](https://documentation.samson-connect.net/) to write new importers for [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). ## Related pages - [Importers](https://documentation.samson-connect.net/users/latest/importers/index.md) - [Exporters](https://documentation.samson-connect.net/users/latest/exporters/index.md) - [Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md) # Versioning [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) has two version numbering systems: a public version (e.g. 2026 R1) and an internal version of [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) and its SDK (e.g. 11.0.0). ## Internal versioning of SAMSON Because [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) and its Software Development Kit (SDK) evolve through successive releases, and [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) depend on specific versions of the SAMSON SDK to compile and run in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), we follow a strict [semantic versioning](https://semver.org/) convention: - Internally, [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) and its SDK have a version number `major.minor.patch` composed of three non-negative integers: a major version number (`major`), a minor version number (`minor`), and a patch version number (`patch`). These numbers evolve according to the following rules: - When a non-backwards-compatible update of SAMSON is released, the major version number `major` is incremented - When a backwards-compatible update of SAMSON that adds functionality is released, the minor version number `minor` is incremented - When a backwards-compatible bug fix of SAMSON is released, the patch version number `patch` is incremented During the beta period, corresponding to a major version number equal to zero, the beta minor version number plays the role of the major version number, and the beta patch version number plays the role of the minor version number *and* the patch version number: - As long as the beta period lasts, the major version number `major` is zero - When a non-backwards-compatible update of SAMSON is released, the minor version number `minor` is incremented - When a backwards-compatible update of SAMSON that adds functionality is released, or when a backwards-compatible bug fix of SAMSON is released, the patch version number `patch` is incremented ## Current version of SAMSON The current public version of [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) is 2026 R1 which is internally based on [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) and its SDK version 11.0.0. ## Compatibility of SAMSON Extensions When starting up, for each [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md), SAMSON compares its own version number with the version number of the SDK that was used to build the [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md), and loads it only if the SDK version is *compatible* with the SAMSON version. As a consequence of the [semantic versioning](https://semver.org/) policy, a version `majorSDK.minorSDK.patchSDK` of the SAMSON SDK is compatible with a version `majorSAMSON.minorSAMSON.patchSAMSON` if and only if: - Both major version numbers `majorSDK` and `majorSAMSON` are identical - The minor version number `minorSDK` of the SDK is *smaller* than the minor version number `minorSAMSON` of SAMSON For example, SDK versions 1.3.5 and 1.7.7 are compatible with SAMSON version 1.7.8, while SDK version 1.8.5 is not compatible with SAMSON version 1.7.8. In the latter case, indeed, a [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) developed with SDK version 1.8.5 might use a function that is not yet present in SAMSON 1.7.8. We encourage you to update SAMSON as often as possible (in particular through the automatic update functionality) to get new features and fixes. ## Automatic updates of SAMSON Extensions SAMSON automatically updates [SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) when new compatible versions appear on [SAMSON Connect](https://www.samson-connect.net/) (and an Internet connection is available). Assume for example that the version of SAMSON installed by the user is 1.7.8, and the version of the SDK used to build the [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) is 1.5.2. SAMSON is able to load this [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) at startup since SAMSON version 1.7.8 is backwards-compatible with SDK version 1.5.2 (the major version numbers are identical). As long as the user does not install a version of SAMSON with a different major version number, the [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) keeps functioning and can be loaded at startup. If a new version of the [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md), built with SDK version 1.6.4, is published on [SAMSON Connect](https://www.samson-connect.net/) (and an Internet connection is available), then SAMSON updates the [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) during startup, since SAMSON version 1.7.8 is compatible with SDK version of 1.6.4. Assume, however, that a version 2.0.0 of SAMSON and its SDK are released, and the developer adds a new version of his or her [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) to [SAMSON Connect](https://www.samson-connect.net/) built with this new version. If the user does not update SAMSON and keeps version 1.7.8, then SAMSON will not update the [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md), and will keep its version 1.6.4. ## Version numbers of SAMSON Extensions Independent of the SDK version used to build it, each [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) has its own version number `major.minor.patch`. This version number can be used to inform users of updates made to a [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md). However, no versioning policy is enforced by SAMSON (besides the `major.minor.patch` format), and only the version of the SDK used to build the [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) is taken into account by SAMSON to determine whether the [SAMSON Extension](https://documentation.samson-connect.net/users/latest/extending-samson/index.md) is compatible and can be loaded at startup. ## Related pages - [Getting Started](https://documentation.samson-connect.net/users/latest/getting-started/index.md): check the current public SAMSON version. - [Extending SAMSON](https://documentation.samson-connect.net/users/latest/extending-samson/index.md): understand how SAMSON Extensions are installed and updated. - [SAMSON Connect](https://documentation.samson-connect.net/users/latest/samson-connect/index.md): manage downloads, extensions, subscriptions, and SDK access. # Visual presets The fastest way to visualize a molecular system is by applying visual presets to it. Visual presets are powerful way to apply multiple visual representations and color schemes simultaneously to a complex molecular system, all in just a few clicks. Visual Presets are accessible from both the **Visualization** menu and the **Home** menu. [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) provides a set of default visual presets and you can [create and save your own visual presets](#create), e.g., by modifying the existing ones. ## Applying visual presets Click on **Home > Visual preset** or **Visualization > Visual preset** and choose a visual preset among the existing ones. Here is how the Protein-ligand preset looks like on PDB code 1AA1: Note The visual preset is applied to the selected nodes or to the whole [document](https://documentation.samson-connect.net/users/latest/documents/index.md) if nothing is selected. When visual preset is applied, it creates a folder in the [document](https://documentation.samson-connect.net/users/latest/documents/index.md) with a name corresponding to this visual preset, and puts there [visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models) created by the visual preset and node groups corresponding to the selections. ## Creating visual presets Visual Presets can be easily customized or created from scratch, with any number of steps, using the **Visual Preset Editor**. Each Visual Preset consists of a series of **steps**, and each step is composed of **four choices**: - A **selection of nodes** to which the step applies (e.g., "Receptor", "Ligands", "Heavy atoms and polar atoms in ligands") - An **optional set of actions** applied to the selection (e.g., "Hide", "Label atoms", "Zoom on selection", etc.) - An **optional visual model** applied to the selection (e.g., "Van der Waals", "Licorice", "Ribbons", etc.) - An **optional color scheme** applied to the selection or the visual model (if added) (e.g., "Per chain", "Per occupancy", "Constant", etc.) You can create and save your own visual presets either by modifying the existing ones or by creating a new one from scratch. Your saved visual presets will be loaded along with the default ones every time you launch SAMSON allowing you to create visualizations and images in the style you want in just a few clicks. To create a new visual preset go to **Home > Visual preset > Create...** or **Visualization > Visual preset > Create...**. If you want to **create a visual preset based on an existing one**, then simply choose it from the list and start modifying, e.g. by adding/removing visual preset steps, changing selections, [visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models), color schemes, color palettes. If you want to **create a visual preset from scratch**, then click on the plus button next to the list of the existing visual presets. Then click on the **Add step** button below to add a new visual preset step. Let's now choose for what types of nodes this step should be applied. There is a number of default options, e.g.: *"Receptor", "Ligands", "Water"*, etc. By default, when you add a new visual preset, it is set to **Any node** which means that this step will be applied to the whole document if nothing was selected or to the current selection to which the visual preset is applied. If you don't find a suitably selection in the list, you can create your own. For that, scroll down the list and click on **More...** - this will open the **Find window** in which you can compose the selection using the [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md). You can apply various actions to the selection (e.g.: *"Hide", "Label atoms", "Zoom on selection"*) - click on in the **Apply actions** row: You can add multiple actions in a single step - they will be applied in the order they've been added. To remove an action, simply hover above it and click on **X** that will appear in its top-right corner: If you want you can choose a [visual model](https://documentation.samson-connect.net/users/latest/models/#visual-models) from the list. If you want you can choose colorization: no colorization, constant color, per element colorization, and different per-attribute color schemes. Note If no colorization is chosen and there is a visual model specified then the visual model will have its default colorization. If no visual model is chosen then the colorization, if specified, is applied to the structural nodes determined by the selection. If a colorization is chosen, then its default color palette (or just a color for constant colorizations) will be shown in the same row. If you want to modify the color palette, then double-click on it and choose (or create one) in the pop-up **Choose color palette...** dialog. If a constant color was chosen as a color scheme, then you can modify the color by double-clicking on it. You can always return to the default color palette associated with the chosen color scheme by double-clicking on the color palette field and selecting the **Default color palette** in the **Choose color palette...** dialog. If you want to delete a step from the visual preset, then click on the visual preset step line and then click on the **Delete step** button. You can also change the order of steps via the **Move up** and **Move down** buttons. If you want to save your custom visual presets click on the **Save visual preset** button or simply click on the **Apply** button to apply it and you will be asked whether you want to save it or not. Would you like your visual presets to be added to the list of default visual presets in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md)? Then please contact us using the **Send feedback** button in the top-right part of [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md). ## Related pages - [Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md): apply visual presets and visual models in everyday visualization workflows. - [Colorizing](https://documentation.samson-connect.net/users/latest/colorizing/index.md): choose color schemes and palettes used by visual preset steps. - [Visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models): understand the visual representations that presets can add. - [Presenting and animating](https://documentation.samson-connect.net/users/latest/presenting/index.md): use presets while preparing presentations and movies. # User Guide - Animations # Animations SAMSON provides a wide variety of animations making it easy to create complex animations, presentations, and movies. Different animations act on different objects - some act on cameras, some act on nodes like structural models, visual models, meshes, and labels. The animations are split into the following categories: - [Motion animations](https://documentation.samson-connect.net/users/latest/presenting/#motion-animations): for docking, assembling, etc. - [Camera animations](https://documentation.samson-connect.net/users/latest/presenting/#camera-animations): orbit, custom paths, etc. - [Entrance effects](https://documentation.samson-connect.net/users/latest/presenting/#entrance-and-exit-effects): appearing, showing, etc. - [Exit effects](https://documentation.samson-connect.net/users/latest/presenting/#entrance-and-exit-effects): disappearing, hiding, etc. - [Highlighting animations](https://documentation.samson-connect.net/users/latest/presenting/#highlighting-effects): e.g. pulsing effects - [Other animations](https://documentation.samson-connect.net/users/latest/presenting/#other-animations): e.g. to pause and stop a presentation, as well as to change backgrounds and display background images such as presentation slides Learn more in the video tutorial: [How to create molecular animations in SAMSON](https://www.youtube.com/watch?v=41zg-DHXb2A). Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` ## What this reference covers Use this reference when you already know you need an animation effect and want to choose the specific effect page. If you need the full presentation workflow first, start with [Presenting and animating](https://documentation.samson-connect.net/users/latest/presenting/index.md). ## Animation effects - [Appear](https://documentation.samson-connect.net/users/latest/animations/appear/index.md) - [Assemble](https://documentation.samson-connect.net/users/latest/animations/assemble/index.md) - [Conceal atoms](https://documentation.samson-connect.net/users/latest/animations/conceal-atoms/index.md) - [Disappear](https://documentation.samson-connect.net/users/latest/animations/disappear/index.md) - [Disassemble](https://documentation.samson-connect.net/users/latest/animations/disassemble/index.md) - [Dock](https://documentation.samson-connect.net/users/latest/animations/dock/index.md) - [Dolly camera](https://documentation.samson-connect.net/users/latest/animations/dolly-camera/index.md) - [Flash](https://documentation.samson-connect.net/users/latest/animations/flash/index.md) - [Follow atoms](https://documentation.samson-connect.net/users/latest/animations/follow-atoms/index.md) - [Hidden](https://documentation.samson-connect.net/users/latest/animations/hidden/index.md) - [Hide](https://documentation.samson-connect.net/users/latest/animations/hide/index.md) - [Hold atoms](https://documentation.samson-connect.net/users/latest/animations/hold-atoms/index.md) - [Hold camera](https://documentation.samson-connect.net/users/latest/animations/hold-camera/index.md) - [Look at atoms](https://documentation.samson-connect.net/users/latest/animations/look-at-atoms/index.md) - [Move atoms](https://documentation.samson-connect.net/users/latest/animations/move-atoms/index.md) - [Move camera](https://documentation.samson-connect.net/users/latest/animations/move-camera/index.md) - [Orbit camera](https://documentation.samson-connect.net/users/latest/animations/orbit-camera/index.md) - [Pause](https://documentation.samson-connect.net/users/latest/animations/pause/index.md) - [Pedestal camera](https://documentation.samson-connect.net/users/latest/animations/pedestal-camera/index.md) - [Play path](https://documentation.samson-connect.net/users/latest/animations/play-path/index.md) - [Play reverse path](https://documentation.samson-connect.net/users/latest/animations/play-reverse-path/index.md) - [Pulse](https://documentation.samson-connect.net/users/latest/animations/pulse/index.md) - [Record path](https://documentation.samson-connect.net/users/latest/animations/record-path/index.md) - [Reveal atoms](https://documentation.samson-connect.net/users/latest/animations/reveal-atoms/index.md) - [Rock](https://documentation.samson-connect.net/users/latest/animations/rock/index.md) - [Rotate](https://documentation.samson-connect.net/users/latest/animations/rotate/index.md) - [Set background](https://documentation.samson-connect.net/users/latest/animations/set-background/index.md) - [Show](https://documentation.samson-connect.net/users/latest/animations/show/index.md) - [Shown](https://documentation.samson-connect.net/users/latest/animations/shown/index.md) - [Simulate](https://documentation.samson-connect.net/users/latest/animations/simulate/index.md) - [Stop](https://documentation.samson-connect.net/users/latest/animations/stop/index.md) - [Truck camera](https://documentation.samson-connect.net/users/latest/animations/truck-camera/index.md) - [Undock](https://documentation.samson-connect.net/users/latest/animations/undock/index.md) - [Zoom camera](https://documentation.samson-connect.net/users/latest/animations/zoom-camera/index.md) ## Related pages - [Presenting and animating](https://documentation.samson-connect.net/users/latest/presenting/index.md): learn how to create presentations, add animations, and export movies. - [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator): understand the timeline and animation controls. # Appear The **Appear** animation makes [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) progressively appear. It can only be applied to nodes with the transparency attribute, e.g. [structural models](https://documentation.samson-connect.net/users/latest/models/#structural-models), [visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models), meshes, and [labels](https://documentation.samson-connect.net/users/latest/labeling/index.md). For nodes which do not have an transparency attribute, this animation is similar to the [Show](https://documentation.samson-connect.net/users/latest/animations/show/index.md) animation. Note that individual atoms and bonds do not have an opacity attribute, but only their [structural models](https://documentation.samson-connect.net/users/latest/models/#structural-models) do. If you would like to change the transparency of atoms and bonds, please apply this animation to the [structural models](https://documentation.samson-connect.net/users/latest/models/#structural-models) themselves. See also animations: [Disappear](https://documentation.samson-connect.net/users/latest/animations/disappear/index.md), [Flash](https://documentation.samson-connect.net/users/latest/animations/flash/index.md), [Pulse](https://documentation.samson-connect.net/users/latest/animations/pulse/index.md), [Show](https://documentation.samson-connect.net/users/latest/animations/show/index.md), [Shown](https://documentation.samson-connect.net/users/latest/animations/shown/index.md), [Hide](https://documentation.samson-connect.net/users/latest/animations/hide/index.md), [Hidden](https://documentation.samson-connect.net/users/latest/animations/hidden/index.md) ## Adding the animation First, choose [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) that you want to progressively appear. Then, double-click on the **Appear** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). This animation has **4 keyframes**: - between keyframes 1 and 2 the specified nodes will be fully transparent - between keyframes 2 and 3 the specified nodes will progressively appear decreasing their transparency - between keyframes 3 and 4 the specified nodes will be fully opaque (no transparency) Move the keyframes of the animation as needed. Note You can always move the keyframes of the animation. Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` ## Properties You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). # Assemble The **Assemble** animation makes a group of structural nodes or meshes assemble to their current positions. The starting positions are automatically computed away from the current positions. See also animations: [Disassemble](https://documentation.samson-connect.net/users/latest/animations/disassemble/index.md), [Hold atoms](https://documentation.samson-connect.net/users/latest/animations/hold-atoms/index.md), [Move atoms](https://documentation.samson-connect.net/users/latest/animations/move-atoms/index.md) ## Adding the animation First, [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a group of structural [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) or meshes that you want to be assembled to their current position. If nothing is selected, then [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) will try to guess to what nodes the animation should be applied. Then, double-click on the **Assemble** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The selected nodes will be assembled between the two keyframes. Move the keyframes of the animation as needed. The amplitude of the movement is computed automatically on the creation of the animation, to change it, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation. Note You can always move the keyframes of the animation. Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` A quick video example of the **Assemble** animation: ## Properties You can change the amplitude of the animation movement in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). ## Examples Some examples of presentations available on [SAMSON Connect - Documents](https://www.samson-connect.net/documents) that use this animation: - [1AVX - Orbit around assembly](https://www.samson-connect.net/documents/5ef49e26-1acd-427b-ac30-e7af6421cc16) - [2XQ6 - Assemble animation](https://www.samson-connect.net/documents/fbf80d12-d964-4a15-b385-207aca3b2792) # Conceal atoms The **Conceal atoms** animation make atoms (and bonds between them) disappear progressively between two frames. This is done via the visibility of nodes and not via their transparency. See also animations: [Reveal atoms](https://documentation.samson-connect.net/users/latest/animations/reveal-atoms/index.md), [Appear](https://documentation.samson-connect.net/users/latest/animations/appear/index.md), [Disappear](https://documentation.samson-connect.net/users/latest/animations/disappear/index.md), [Flash](https://documentation.samson-connect.net/users/latest/animations/flash/index.md), [Pulse](https://documentation.samson-connect.net/users/latest/animations/pulse/index.md), [Show](https://documentation.samson-connect.net/users/latest/animations/show/index.md), [Shown](https://documentation.samson-connect.net/users/latest/animations/shown/index.md), [Hide](https://documentation.samson-connect.net/users/latest/animations/hide/index.md), [Hidden](https://documentation.samson-connect.net/users/latest/animations/hidden/index.md) ## Adding the animation First, choose atoms and bonds that you want to progressively disappear. Then, double-click on the **Conceal atoms** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). This animation has **4 keyframes**: - between keyframes 1 and 2 all the specified atoms (and bonds between them) will be shown - between keyframes 2 and 3 the specified atoms (and bonds between them) will progressively disappear by hiding some atoms (and bonds between hidden atoms) depending on their order in the [selection](https://documentation.samson-connect.net/users/latest/selecting/index.md) - between keyframes 3 and 4 all the specified atoms (and bonds between them) will be hidden Move the keyframes of the animation as needed. Note You can always move the keyframes of the animation. ## Properties You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). ## Examples Some examples of presentations available on [SAMSON Connect - Documents](https://www.samson-connect.net/documents) that use this animation: - [1AF6 - Fly around](https://www.samson-connect.net/documents/858bd00b-80f6-4001-8def-eebbf9f09a9b) - [1AF6 - Fly around - 2](https://www.samson-connect.net/documents/f7dfa5e2-c6af-4a7a-bdf6-30ca2afeb661) # Disappear The **Disappear** animation makes [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) progressively disappear. It can only be applied to nodes with the transparency attribute, e.g. [structural models](https://documentation.samson-connect.net/users/latest/models/#structural-models), [visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models), meshes, and [labels](https://documentation.samson-connect.net/users/latest/labeling/index.md). For nodes which do not have an transparency attribute, this animation is similar to the [Hide](https://documentation.samson-connect.net/users/latest/animations/hide/index.md) animation. Note that individual atoms and bonds do not have an opacity attribute, but only their [structural models](https://documentation.samson-connect.net/users/latest/models/#structural-models) do. If you would like to change the transparency of atoms and bonds, please apply this animation to the [structural models](https://documentation.samson-connect.net/users/latest/models/#structural-models) themselves. See also animations: [Appear](https://documentation.samson-connect.net/users/latest/animations/appear/index.md), [Flash](https://documentation.samson-connect.net/users/latest/animations/flash/index.md), [Pulse](https://documentation.samson-connect.net/users/latest/animations/pulse/index.md), [Show](https://documentation.samson-connect.net/users/latest/animations/show/index.md), [Shown](https://documentation.samson-connect.net/users/latest/animations/shown/index.md), [Hide](https://documentation.samson-connect.net/users/latest/animations/hide/index.md), [Hidden](https://documentation.samson-connect.net/users/latest/animations/hidden/index.md) ## Adding the animation First, choose [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) that you want to progressively disappear. Then, double-click on the **Disappear** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). This animation has **4 keyframes**: - between keyframes 1 and 2 the specified nodes will be fully opaque - between keyframes 2 and 3 the specified nodes will progressively disappear increasing their transparency - between keyframes 3 and 4 the specified nodes will be fully transparent Move the keyframes of the animation as needed. Note You can always move the keyframes of the animation. Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` ## Properties You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). # Disassemble The **Disassemble** animation makes a group of structural nodes or meshes disassemble from their current positions. The final positions are automatically computed away from the current positions. See also animations: [Assemble](https://documentation.samson-connect.net/users/latest/animations/assemble/index.md), [Hold atoms](https://documentation.samson-connect.net/users/latest/animations/hold-atoms/index.md), [Move atoms](https://documentation.samson-connect.net/users/latest/animations/move-atoms/index.md) ## Adding the animation First, [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a group of structural [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) or meshes that you want to be disassembled. If nothing is selected, then [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) will try to guess to what nodes the animation should be applied. Then, double-click on the **Disassemble** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The selected nodes will be disassembled between the two keyframes. Move the keyframes of the animation as needed. The amplitude of the movement is computed automatically on the creation of the animation, to change it, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation. Note You can always move the keyframes of the animation. Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` ## Properties You can change the amplitude of the animation movement in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). ## Examples Some examples of presentations available on [SAMSON Connect - Documents](https://www.samson-connect.net/documents) that use the [Assemble](https://documentation.samson-connect.net/users/latest/animations/assemble/index.md) animation: - [1AVX - Orbit around assembly](https://www.samson-connect.net/documents/5ef49e26-1acd-427b-ac30-e7af6421cc16) - [2XQ6 - Assemble animation](https://www.samson-connect.net/documents/fbf80d12-d964-4a15-b385-207aca3b2792) # Dock The **Dock** animation docks groups of atoms or meshes to their current positions which are considered as docked positions. The starting positions are automatically computed away from the docked positions. See also animations: [Undock](https://documentation.samson-connect.net/users/latest/animations/undock/index.md), [Hold atoms](https://documentation.samson-connect.net/users/latest/animations/hold-atoms/index.md), [Move atoms](https://documentation.samson-connect.net/users/latest/animations/move-atoms/index.md) ## Adding the animation To apply the dock animation, [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) at least two structural [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) or meshes in the document. The first node will act as the static receptor, and the other nodes will be animated. If multiple nodes should act as the receptor, create a folder, move these receptor nodes to the folder, and select the folder as the first node. If nothing is selected, then [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) will try to guess to what nodes the animation should be applied. Then, double-click on the **Dock** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The selected nodes will be docked between the two keyframes. Move the keyframes of the animation as needed. The amplitude of the movement is computed automatically on the creation of the animation, to change it, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation. Note You can always move the keyframes of the animation. Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` ## Properties You can change the amplitude of the animation movement in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). ## Examples Some examples of presentations available on [SAMSON Connect - Documents](https://www.samson-connect.net/documents) that use this animation: - [2AZ8 - Dock animation](https://www.samson-connect.net/documents/aad9c1a7-3200-48e9-8ee8-0d74bc59657b) - [5SAT - Dock animation](https://www.samson-connect.net/documents/a9f2b952-e2e7-4800-b8c4-28152fe313a5) # Dolly camera The **Dolly camera** animation provides a dolly effect by modifying the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md)'s position and target point between the start and end frames. This can be useful when you want to zoom on a part of a system and, for example, change the target points for the [Fog](https://documentation.samson-connect.net/users/latest/rendering-effects/#fog) and [Depth-of-field](https://documentation.samson-connect.net/users/latest/rendering-effects/#depth-of-field) special effects. Compare it to the [Zoom camera](https://documentation.samson-connect.net/users/latest/animations/zoom-camera/index.md) animation which can have only one target point. See also: [Move camera](https://documentation.samson-connect.net/users/latest/animations/move-camera/index.md) animation. ## Adding the animation First, choose the start frame in the [Animator's Track view](https://documentation.samson-connect.net/users/latest/presenting/#animator-track-view) and [orient the view/camera](https://documentation.samson-connect.net/users/latest/moving-around/index.md) as you would like it to be positioned. Then, double-click on the **Dolly camera** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). Set the end frame of the animation as needed. Note You can always move the start and end frames of the animation. ## Properties By default, camera animations are applied to the active [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) (to change that, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation and modify the **Apply to active camera** option). So, the **target point** of the animation will be defined as the current **target position** of the active camera, which is basically the current center of the view. The camera positions might be defined differently whether you have the **grid** in the switched on or off. To change how the animation behaves depending on whether the grid is on or off, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation and modify the **Keep camera upwards** option - if this option is checked then it will depend on whether the grid is on or off. You can also change how the camera's parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). ## Adjusting camera positions You can adjust the camera's target points and positions using the animation controllers. See [Adjusting camera positions](https://documentation.samson-connect.net/users/latest/presenting/#animations-adjusting-camera-positions). # Flash The **Flash** animation makes [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) appear at the begin keyframe and disappear at the end keyframe. This is done via the visibility of nodes and not via their transparency. See also animations: [Appear](https://documentation.samson-connect.net/users/latest/animations/appear/index.md), [Disappear](https://documentation.samson-connect.net/users/latest/animations/disappear/index.md), [Show](https://documentation.samson-connect.net/users/latest/animations/show/index.md), [Shown](https://documentation.samson-connect.net/users/latest/animations/shown/index.md), [Hide](https://documentation.samson-connect.net/users/latest/animations/hide/index.md), [Hidden](https://documentation.samson-connect.net/users/latest/animations/hidden/index.md), [Pulse](https://documentation.samson-connect.net/users/latest/animations/pulse/index.md) ## Adding the animation First, choose [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) that you want to show and hide. Then, double-click on the **Flash** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). This animation has **4 keyframes**: - between keyframes 1 and 2 the specified nodes will stay hidden - at the keyframe 2 the specified nodes will become visible and between keyframes 2 and 3 they will stay visible - at the keyframe 3 the specified nodes will become hidden and between keyframe 3 and 4 they will stay hidden Move the keyframes of the animation as needed. Note You can always move the keyframes of the animation. ## Properties You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). # Follow atoms The **Follow atoms** animation makes the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) continuously follow the atoms that were [selected](https://documentation.samson-connect.net/users/latest/selecting/index.md) when the animation was created. Both the camera target and the camera position move to preserve a constant distance between the camera and the atoms. This animation can be useful, for example, when you want to follow the movement of some part of a system while animating its trajectory. See also: [Look at atoms](https://documentation.samson-connect.net/users/latest/animations/look-at-atoms/index.md) animation ## Adding the animation First, [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) atoms that you want the camera to follow and [orient the view/camera](https://documentation.samson-connect.net/users/latest/moving-around/index.md) as you would like it to be positioned. Then, choose the start frame in the [Animator's Track view](https://documentation.samson-connect.net/users/latest/presenting/#animator-track-view) and double-click on the **Follow atoms** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The camera target point between the two keyframes will move with the geometric center of the specified atoms. The current camera position is used for the start frame and for the end it will be moved as the specified atom system moves keeping the vector between the camera target and the camera position constant. Set the end frame of the animation as needed. Note You can always move the start and end frames of the animation. ## Properties By default, camera animations are applied to the active [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) (to change that, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation and modify the **Apply to active camera** option). So, the **target point** of the animation will be defined as the current **target position** of the active camera, which is basically the current center of the view. The camera positions might be defined differently whether you have the **grid** in the switched on or off. To change how the animation behaves depending on whether the grid is on or off, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation and modify the **Keep camera upwards** option - if this option is checked then it will depend on whether the grid is on or off. ## Adjusting camera positions You can adjust the camera position using the animation controllers but the camera target is kept at the geometric center of the specified atoms. See [Adjusting camera positions](https://documentation.samson-connect.net/users/latest/presenting/#animations-adjusting-camera-positions). # Hidden The **Hidden** animation makes [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) hidden between two keyframes. This is done via the visibility of nodes and not via their transparency. See also animations: [Shown](https://documentation.samson-connect.net/users/latest/animations/shown/index.md), [Appear](https://documentation.samson-connect.net/users/latest/animations/appear/index.md), [Disappear](https://documentation.samson-connect.net/users/latest/animations/disappear/index.md), [Show](https://documentation.samson-connect.net/users/latest/animations/show/index.md), [Hide](https://documentation.samson-connect.net/users/latest/animations/hide/index.md), [Flash](https://documentation.samson-connect.net/users/latest/animations/flash/index.md), [Pulse](https://documentation.samson-connect.net/users/latest/animations/pulse/index.md) ## Adding the animation First, choose [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) that you want to be hidden. Then, double-click on the **Hidden** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The begin keyframe will be set at the current frame. Move the keyframes of the animation as needed. Note You can always move the keyframes of the animation. Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` ## Properties You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). # Hide The **Hide** animation makes [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) disappear at the current keyframe, and stay hidden up until the end keyframe. This is done via the visibility of nodes and not via their transparency. Basically, this animations combines [Shown](https://documentation.samson-connect.net/users/latest/animations/shown/index.md) and [Hidden](https://documentation.samson-connect.net/users/latest/animations/hidden/index.md) consecutive animations into one. See also animations: [Show](https://documentation.samson-connect.net/users/latest/animations/show/index.md), [Appear](https://documentation.samson-connect.net/users/latest/animations/appear/index.md), [Disappear](https://documentation.samson-connect.net/users/latest/animations/disappear/index.md), [Shown](https://documentation.samson-connect.net/users/latest/animations/shown/index.md), [Hidden](https://documentation.samson-connect.net/users/latest/animations/hidden/index.md), [Flash](https://documentation.samson-connect.net/users/latest/animations/flash/index.md), [Pulse](https://documentation.samson-connect.net/users/latest/animations/pulse/index.md) ## Adding the animation First, choose [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) that you want to hide. Then, double-click on the **Hide** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). This animation has **3 keyframes**: - between keyframes 1 and 2 the specified nodes will stay visible - at the keyframe 2 the specified nodes will disappear and between keyframes 2 and 3 they will stay hidden Move the keyframes of the animation as needed. Note You can always move the keyframes of the animation. Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` ## Properties You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). # Hold atoms The **Hold atoms** animation holds atoms positions fixed between two frames. See also animations: [Move atoms](https://documentation.samson-connect.net/users/latest/animations/move-atoms/index.md) ## Adding the animation First, [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a group of particles that you want to have fixed positions between two frames. Then, double-click on the **Hold atoms** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The selected group of particles will be held at the fixed positions between the two keyframes. Move the keyframes of the animation as needed. Note You can always move the keyframes of the animation. Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` ## Examples Some examples of presentations available on [SAMSON Connect - Documents](https://www.samson-connect.net/documents) that use this animation: - [2AZ8 - Dock animation](https://www.samson-connect.net/documents/aad9c1a7-3200-48e9-8ee8-0d74bc59657b) - [2XQ6 - Assemble animation](https://www.samson-connect.net/documents/fbf80d12-d964-4a15-b385-207aca3b2792) - [5SAT - Dock animation](https://www.samson-connect.net/documents/a9f2b952-e2e7-4800-b8c4-28152fe313a5) # Hold camera The **Hold camera** animation holds the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) parameters fixed between two frames. Use this animation if you don't use other camera animations at some frames and you would like a certain view of the system; this might be needed since the view can be changed while working with the document, and the Hold camera animation lets you keep a defined static view of the system. See also: [Move camera](https://documentation.samson-connect.net/users/latest/animations/move-camera/index.md) animation. ## Adding the animation First, choose the start frame in the [Animator's Track view](https://documentation.samson-connect.net/users/latest/presenting/#animator-track-view) and [orient the view/camera](https://documentation.samson-connect.net/users/latest/moving-around/index.md) as you would like it to be positioned. Then, double-click on the **Hold camera** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). Set the end frame of the animation as needed. Note You can always move the start and end frames of the animation. Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` # Look at atoms The **Look at atoms** animation makes the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) continuously look at the atoms that were [selected](https://documentation.samson-connect.net/users/latest/selecting/index.md) when the animation was created. Only the camera target moves while the camera position does not change. This animation can be useful, for example, when you want to keep looking at some part of a system while animating its trajectory without changing the camera position. See also: [Follow atoms](https://documentation.samson-connect.net/users/latest/animations/follow-atoms/index.md) animation ## Adding the animation First, [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) atoms that you want the camera to look at and [orient the view/camera](https://documentation.samson-connect.net/users/latest/moving-around/index.md) as you would like it to be positioned. Then, choose the start frame in the [Animator's Track view](https://documentation.samson-connect.net/users/latest/presenting/#animator-track-view) and double-click on the **Look at atoms** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The camera target point between the two keyframes will move with the geometric center of the specified atoms. The current camera position is used for the start and end frames. Set the end frame of the animation as needed. Note You can always move the start and end frames of the animation. ## Properties By default, camera animations are applied to the active [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) (to change that, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation and modify the **Apply to active camera** option). So, the **target point** of the animation will be defined as the current **target position** of the active camera, which is basically the current center of the view. The camera positions might be defined differently whether you have the **grid** in the switched on or off. To change how the animation behaves depending on whether the grid is on or off, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation and modify the **Keep camera upwards** option - if this option is checked then it will depend on whether the grid is on or off. ## Adjusting camera positions You can adjust the camera position using the animation controllers but the camera target is kept at the geometric center of the specified atoms. See [Adjusting camera positions](https://documentation.samson-connect.net/users/latest/presenting/#animations-adjusting-camera-positions). # Move atoms The **Move atoms** animation makes atoms move freely. The animation will interpolate between the positions of the atoms to which the animation was applied. See also animations: [Hold atoms](https://documentation.samson-connect.net/users/latest/animations/hold-atoms/index.md) ## Adding the animation First, position atoms and [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) them. Then, double-click on the **Move atoms** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). This will add the starting keyframe. Then add another keyframe in the animation track and positions atoms as needed. Note The Move atoms animation has controllers that let you move a system in the same style as using the [Move editors](https://documentation.samson-connect.net/users/latest/moving-objects/#moving-objects-using-move-editors). You can also set the snapping for translations and rotations in the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator) if necessary. Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` ## Adding a new keyframe To add a new keyframe, click in the animation track at the frame at which the atoms should have the desired positions and move the atoms where you would like them to be. Note You can always move the keyframes of the animation. If you would like to use other editors than the Move atoms animation controllers then [hide the Move atoms animation controllers](https://documentation.samson-connect.net/users/latest/presenting/#animation-controllers) by unchecking them in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view), then choose the editor you would like to use, e.g. one of the [Move editors](https://documentation.samson-connect.net/users/latest/moving-objects/#moving-objects-using-move-editors) or the Twister editor, apply transformations to the system, and add a new keyframe in the animation track. Once the transformations are done switch back to the Select editor. ## Removing a keyframe To remove a keyframe, *right-click* on it in the [Animator's Track view](https://documentation.samson-connect.net/users/latest/presenting/#animator-track-view) and click **Remove keyframe**. ## Properties You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve) and switching on/off the smoothing effect. ## Examples Some examples of presentations available on [SAMSON Connect - Documents](https://www.samson-connect.net/documents) that use this animation: - [Multi-walled nanotube animation](https://www.samson-connect.net/documents/6c0b4c95-ed67-491f-830e-c7fd7810978b) - [Nanotube - Keyframed animation](https://www.samson-connect.net/documents/31bb8a79-2968-4b86-bf11-d60172d94055) # Move camera The **Move camera** animation makes the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) move freely. You can add and remove **keyframes** and the animation will interpolate between the positions of the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md). See also animations: [Zoom camera](https://documentation.samson-connect.net/users/latest/animations/zoom-camera/index.md), [Orbit camera](https://documentation.samson-connect.net/users/latest/animations/orbit-camera/index.md), [Pedestal camera](https://documentation.samson-connect.net/users/latest/animations/pedestal-camera/index.md), [Truck camera](https://documentation.samson-connect.net/users/latest/animations/truck-camera/index.md), [Hold camera](https://documentation.samson-connect.net/users/latest/animations/hold-camera/index.md) ## Adding the animation To add the **Move camera** animation to the presentation, [orient the view/camera](https://documentation.samson-connect.net/users/latest/moving-around/index.md) as you would like it to be, then, in the [Animator's Track view](https://documentation.samson-connect.net/users/latest/presenting/#animator-track-view), go to the frame at which the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) should have the desired position. Then double-click on the **Move camera** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). ## Adding a new keyframe To add a new **keyframe**, [orient the view/camera](https://documentation.samson-connect.net/users/latest/moving-around/index.md) as you would like it to be positioned, then, in the [Animator's Track view](https://documentation.samson-connect.net/users/latest/presenting/#animator-track-view), go to the frame at which the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) should have the desired position, and *left-click* in the [animation](https://documentation.samson-connect.net/users/latest/presenting/index.md)Track or *right-click* and choose **Add keyframe**. Note You can always move keyframes along the animation track. Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` ## Removing a keyframe To remove a keyframe, *right-click* on it in the [Animator's Track view](https://documentation.samson-connect.net/users/latest/presenting/#animator-track-view) and click **Remove keyframe**. ## Properties By default, camera animations are applied to the active [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) (to change that, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation and modify the **Apply to active camera** option). So, the **target point** of the **Move camera** animation will be defined as the current **target position** of the active camera, which is basically the current center of the view. The camera positions might be defined differently whether you have the **grid** in the switched on or off. To change how the animation behaves depending on whether the grid is on or off, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation and modify the **Keep camera upwards** option - if this option is checked then it will depend on whether the grid is on or off. You can also change how the camera's parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). ## Adjusting camera positions You can adjust the target point and the camera position using the animation controllers. See [Adjusting camera positions](https://documentation.samson-connect.net/users/latest/presenting/#animations-adjusting-camera-positions). ## Examples Some examples of presentations available on [SAMSON Connect - Documents](https://www.samson-connect.net/documents) that use this animation: - [1AF6 - Fly around](https://www.samson-connect.net/documents/858bd00b-80f6-4001-8def-eebbf9f09a9b) - [1AF6 - Fly around - 2](https://www.samson-connect.net/documents/f7dfa5e2-c6af-4a7a-bdf6-30ca2afeb661) - [2AZ8 - Dock animation](https://www.samson-connect.net/documents/aad9c1a7-3200-48e9-8ee8-0d74bc59657b) - [2XQ6 - Assemble animation](https://www.samson-connect.net/documents/fbf80d12-d964-4a15-b385-207aca3b2792) - [5SAT - Dock animation](https://www.samson-connect.net/documents/a9f2b952-e2e7-4800-b8c4-28152fe313a5) - [Nanotube - Keyframed animation](https://www.samson-connect.net/documents/31bb8a79-2968-4b86-bf11-d60172d94055) - [NU1000 (CCDC-1580411) - Fly around](https://www.samson-connect.net/documents/a264e668-0865-41f2-8e14-80bf27a3db2e) # Orbit camera The **Orbit camera** animation makes the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) orbit around its target point. See also: [Move camera](https://documentation.samson-connect.net/users/latest/animations/move-camera/index.md) animation. ## Adding the animation First, [orient the view/camera](https://documentation.samson-connect.net/users/latest/moving-around/index.md) in the plane in which you want it to be rotated around the object. Then, double-click on the **Orbit camera** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). Set the end frame of the animation as needed. Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` ## Properties By default, camera animations are applied to the active [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) (to change that, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation and modify the **Apply to active camera** option). So, the **target point** of the **Orbit camera** animation will be defined as the current **target position** of the active camera, which is basically the current center of the view. The **orbit rotation plane** will be defined differently whether you have the **grid** in the switched on or off: - **grid is off**: the rotation plane will go through the central horizontal line of the and the target point. - **grid is on**: the rotation plane will go through the central horizontal line of the in the plane parallel to the grid plane. To change how the animation behaves depending on whether the grid is on or off, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation and modify the **Keep camera upwards** option - if this option is checked then it will depend on whether the grid is on or off. You can also change how the camera's parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). ## Adjusting camera positions You can adjust the target point and the rotation plane using the animation controllers. All the camera animations have specialized **camera controllers** allowing for fine positioning of the camera: the central/target point, camera orientations, etc. In the , you can see the associated keyframe numbers shown near the keyframe camera animation controllers. Let's see how can the Orbit camera positioning be adjusted. Note, if you don't see the camera controllers, you might need to zoom out in the (use the mouse scroll button or press `Ctrl`/`Cmd` + `-`). While editing camera positions, **Thumbnails** automatically appear at the bottom of the to help you frame the best shots. ## Examples Some examples of presentations available on [SAMSON Connect - Documents](https://www.samson-connect.net/documents) that use this animation: - [1AVX - Orbit around assembly](https://www.samson-connect.net/documents/5ef49e26-1acd-427b-ac30-e7af6421cc16) - [NU1000 (CCDC-1580411) - Fly around](https://www.samson-connect.net/documents/a264e668-0865-41f2-8e14-80bf27a3db2e) # Pause The **Pause** animation pauses the presentation at a given frame for a given number of seconds. See also: [Stop](https://documentation.samson-connect.net/users/latest/animations/stop/index.md) animation ## Adding the animation Double-click on the **Pause** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The keyframe will be placed at the current frame, move it if needed. Note You can always move the keyframes of the animation. ## Properties You can specify the pause duration in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) for this animation - [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) this animation node in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) and [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) it. # Pedestal camera The **Pedestal camera** animation makes the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) move vertically between two keyframes (in the camera reference frame) by modifying the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md)'s position and target point in a parallel way. This can be useful when you want to move the view (both the camera's target point and position) along some system in a vertical direction. [Truck camera](https://documentation.samson-connect.net/users/latest/animations/truck-camera/index.md) and [Pedestal camera](https://documentation.samson-connect.net/users/latest/animations/pedestal-camera/index.md) animations act in the same way while moving the camera in the horizontal and vertical directions, correspondingly. See also: [Move camera](https://documentation.samson-connect.net/users/latest/animations/move-camera/index.md) animation. ## Adding the animation First, choose the start frame in the [Animator's Track view](https://documentation.samson-connect.net/users/latest/presenting/#animator-track-view) and [orient the view/camera](https://documentation.samson-connect.net/users/latest/moving-around/index.md) as you would like it to be positioned. Then, double-click on the **Pedestal camera** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The camera's target point and position are used for the start frame and for the end frame both of them are shifted vertically up by the same distance. Set the end frame of the animation as needed. Note You can always move the start and end frames of the animation. ## Properties By default, camera animations are applied to the active [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) (to change that, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation and modify the **Apply to active camera** option). So, the **target point** of the animation will be defined as the current **target position** of the active camera, which is basically the current center of the view. The camera positions might be defined differently whether you have the **grid** in the switched on or off. To change how the animation behaves depending on whether the grid is on or off, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation and modify the **Keep camera upwards** option - if this option is checked then it will depend on whether the grid is on or off. You can also change how the camera's parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). ## Adjusting camera positions You can adjust the camera's target points and positions using the animation controllers. See [Adjusting camera positions](https://documentation.samson-connect.net/users/latest/presenting/#animations-adjusting-camera-positions). But the Pedestal camera animation has some special limitations on how the camera's target points and positions can be adjusted. # Play path The **Play path** animation plays a single path or multiple paths between two frames. You can use it to play a trajectory, cycle between conformations, etc. Select the path(s) you want to play and add this animation. If you select multiple paths, they will be synchronized. If the number of frames in the animation and the number of frames in the path are not equal then the path will be smoothed, you can switch off the smoothing in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). In [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), the path node is used to store a trajectory. See also: [Play reverse path](https://documentation.samson-connect.net/users/latest/animations/play-reverse-path/index.md) animation ## Adding the animation First, choose a Path that you want to be played. Then, double-click on the **Play path** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The whole path will be played between the two keyframes. Move the keyframes of the animation as needed. Note You can always move the keyframes of the animation. ## Properties You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). # Play reverse path The **Play reverse path** animation plays a single path or multiple paths between two frames, in reverse. You can use it to play a trajectory, cycle between conformations, etc. Select the path(s) you want to play and add this animation. If you select multiple paths, they will be synchronized. If the number of frames in the animation and the number of frames in the path are not equal then the path will be smoothed, you can switch off the smoothing in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). In [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), the path node is used to store a trajectory. See also: [Play path](https://documentation.samson-connect.net/users/latest/animations/play-path/index.md) animation ## Adding the animation First, choose a Path that you want to be played. Then, double-click on the **Play reverse path** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The whole path will be played in reverse between the two keyframes. Move the keyframes of the animation as needed. Note You can always move the keyframes of the animation. ## Properties You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). # Pulse The **Pulse** animation makes [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) progressively appear and then disappear. It can only be applied to nodes with the transparency attribute, e.g. [structural models](https://documentation.samson-connect.net/users/latest/models/#structural-models), [visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models), meshes, and [labels](https://documentation.samson-connect.net/users/latest/labeling/index.md). See also animations: [Appear](https://documentation.samson-connect.net/users/latest/animations/appear/index.md), [Disappear](https://documentation.samson-connect.net/users/latest/animations/disappear/index.md), [Show](https://documentation.samson-connect.net/users/latest/animations/show/index.md), [Shown](https://documentation.samson-connect.net/users/latest/animations/shown/index.md), [Hide](https://documentation.samson-connect.net/users/latest/animations/hide/index.md), [Hidden](https://documentation.samson-connect.net/users/latest/animations/hidden/index.md), [Flash](https://documentation.samson-connect.net/users/latest/animations/flash/index.md) ## Adding the animation First, choose [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) that you want to progressively shown and hidden. Then, double-click on the **Pulse** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). This animation has **5 keyframes**: - between keyframes 1 and 2 the specified nodes will be fully transparent - between keyframes 2 and 3 the specified nodes will progressively appear decreasing their transparency - at the keyframe 3 the specified nodes will be fully opaque (no transparency) - between keyframes 3 and 4 the specified nodes will progressively disappear increasing their transparency - between keyframe 4 and 5 they will be fully transparent Move the keyframes of the animation as needed. Note You can always move the keyframes of the animation. ## Properties You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). # Record path The **Record path** animation records atoms trajectories along the presentation as a path. It adds a track that records atoms trajectories. You can use this animation together with other animations that affect atomic positions (e.g., [Assemble](https://documentation.samson-connect.net/users/latest/animations/assemble/index.md), [Dock](https://documentation.samson-connect.net/users/latest/animations/dock/index.md), [Move atoms](https://documentation.samson-connect.net/users/latest/animations/move-atoms/index.md), [Simulate](https://documentation.samson-connect.net/users/latest/animations/simulate/index.md), etc.) to record the resulting path. See also: [Play path](https://documentation.samson-connect.net/users/latest/animations/play-path/index.md), [Play reverse path](https://documentation.samson-connect.net/users/latest/animations/play-reverse-path/index.md), [Simulate](https://documentation.samson-connect.net/users/latest/animations/simulate/index.md) animations. ## Adding the animation Double-click on the **Record path** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The keyframe will be placed at the current frame, move it if needed. The track colors indicate whether positions have been recorded: at a given frame, a green segment indicates that positions have been recorded, while a red segment indicates that positions have not yet been recorded or have become invalid. Tip The [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator) executes animations from the top down, so place the **Record path** animation after the ones that you want to record. Note You can always move the keyframes of the animation. Tip You can enable/disable the path recording for the performance reasons, e.g., when you are still working on the presentation or once the whole path has been recorded and won't be changed. You can do this in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) of this animation or right-click on this animation in the **Animator** and change **Enable recording**. If the recording is disabled then the animation controllers will be darkened. ## Exporting the path Once the path has been recorded by the animation (i.e., the presentation has been played and the **Record path** animation is fully green), you can add the corresponding **Path** node in the document using one of the following ways: - in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) of this animation, click on **Create path**; - in the **Animator**, right-click on the **Record path** animation and choose **Create path**. # Reveal atoms The **Reveal atoms** animation makes atoms (and bonds between them) appear progressively between two frames. This is done via the visibility of nodes and not via their transparency. See also animations: [Conceal atoms](https://documentation.samson-connect.net/users/latest/animations/conceal-atoms/index.md), [Appear](https://documentation.samson-connect.net/users/latest/animations/appear/index.md), [Disappear](https://documentation.samson-connect.net/users/latest/animations/disappear/index.md), [Flash](https://documentation.samson-connect.net/users/latest/animations/flash/index.md), [Pulse](https://documentation.samson-connect.net/users/latest/animations/pulse/index.md), [Show](https://documentation.samson-connect.net/users/latest/animations/show/index.md), [Shown](https://documentation.samson-connect.net/users/latest/animations/shown/index.md), [Hide](https://documentation.samson-connect.net/users/latest/animations/hide/index.md), [Hidden](https://documentation.samson-connect.net/users/latest/animations/hidden/index.md) ## Adding the animation First, choose atoms and bonds that you want to progressively disappear. Then, double-click on the **Reveal atoms** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). This animation has **4 keyframes**: - between keyframes 1 and 2 all the specified atoms (and bonds between them) will be hidden - between keyframes 2 and 3 the specified atoms (and bonds between them) will progressively appear by showing some atoms (and bonds between shown atoms) depending on their order in the [selection](https://documentation.samson-connect.net/users/latest/selecting/index.md) - between keyframes 3 and 4 all the specified atoms (and bonds between them) will be shown Move the keyframes of the animation as needed. Note You can always move the keyframes of the animation. ## Properties You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). # Rock The **Rock** animation makes a group of particles rock around its geometric center. The rock movement is done around a vector that goes through the centroid of the group of particles and is collinear with the Z-axis. See also animations: [Rotate](https://documentation.samson-connect.net/users/latest/animations/rotate/index.md), [Hold atoms](https://documentation.samson-connect.net/users/latest/animations/hold-atoms/index.md), [Move atoms](https://documentation.samson-connect.net/users/latest/animations/move-atoms/index.md) ## Adding the animation First, [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a group of particles that you want to be rotated. Then, double-click on the **Rock** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The selected group of particles will perform the rock movement between the two keyframes. Move the keyframes of the animation as needed. Note You can always move the keyframes of the animation. ## Properties You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). ## Examples Some examples of presentations available on [SAMSON Connect - Documents](https://www.samson-connect.net/documents) that use this animation: - [2BRD - Rock animation](https://www.samson-connect.net/documents/54a5e67a-0661-4c09-8c70-b967318b4154) # Rotate The **Rotate** animation makes a group of particles rotate around its geometric center. The rotation is done around a vector that goes through the centroid of the group of particles and is collinear with the Z-axis. See also animations: [Rock](https://documentation.samson-connect.net/users/latest/animations/rock/index.md), [Hold atoms](https://documentation.samson-connect.net/users/latest/animations/hold-atoms/index.md), [Move atoms](https://documentation.samson-connect.net/users/latest/animations/move-atoms/index.md) ## Adding the animation First, [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a group of particles that you want to be rotated around their centroid. Then, double-click on the **Rotate** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The selected group of particles will be rotated between the two keyframes. Move the keyframes of the animation as needed. Note You can always move the keyframes of the animation. Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` ## Properties You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). # Set background The **Set background** animation sets the background between two frames. You can also display background images such as presentation slides. When setting an image as a background you choose whether the image should be fully contained in the or cover it (might be cropped by the largest side). The presentation will automatically perform **interpolations between backgrounds** when multiple backgrounds are present. You may control the interpolation using the easing curve in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). ## Adding the animation Double-click on the **Set background** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The begin keyframe will be placed at the current frame. Move the keyframes of the animation as needed. Note You can always move the keyframes of the animation. The animation has **2 keyframes**: - at the keyframe 1 the specified background will be set - after the keyframe 2, if there is another Set background animation specified then the presentation will perform interpolations between backgrounds ## Properties You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). # Show The **Show** animation makes [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) appear at the current keyframe and stay visible up until the end keyframe. This is done via the visibility of nodes and not via their transparency. Basically, this animations combines [Hidden](https://documentation.samson-connect.net/users/latest/animations/hidden/index.md) and [Shown](https://documentation.samson-connect.net/users/latest/animations/shown/index.md) consecutive animations into one. See also animations: [Hide](https://documentation.samson-connect.net/users/latest/animations/hide/index.md), [Appear](https://documentation.samson-connect.net/users/latest/animations/appear/index.md), [Disappear](https://documentation.samson-connect.net/users/latest/animations/disappear/index.md), [Shown](https://documentation.samson-connect.net/users/latest/animations/shown/index.md), [Hidden](https://documentation.samson-connect.net/users/latest/animations/hidden/index.md), [Flash](https://documentation.samson-connect.net/users/latest/animations/flash/index.md), [Pulse](https://documentation.samson-connect.net/users/latest/animations/pulse/index.md) ## Adding the animation First, choose [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) that you want to show. Then, double-click on the **Show** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). This animation has **3 keyframes**: - between keyframes 1 and 2 the specified nodes will stay hidden - at the keyframe 2 the specified nodes will appear and between keyframes 2 and 3 they will stay visible Move the keyframes of the animation as needed. Note You can always move the keyframes of the animation. Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` ## Properties You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). # Shown The **Shown** animation makes [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) shown between keyframe. This is done via the visibility of nodes and not via their transparency. See also animations: [Hidden](https://documentation.samson-connect.net/users/latest/animations/hidden/index.md), [Appear](https://documentation.samson-connect.net/users/latest/animations/appear/index.md), [Disappear](https://documentation.samson-connect.net/users/latest/animations/disappear/index.md), [Show](https://documentation.samson-connect.net/users/latest/animations/show/index.md), [Hide](https://documentation.samson-connect.net/users/latest/animations/hide/index.md), [Flash](https://documentation.samson-connect.net/users/latest/animations/flash/index.md), [Pulse](https://documentation.samson-connect.net/users/latest/animations/pulse/index.md) ## Adding the animation First, choose [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) that you want to be shown. Then, double-click on the **Shown** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The begin keyframe will be set at the current frame. Move the keyframes of the animation as needed. Note You can always move the keyframes of the animation. Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` ## Properties You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). # Simulate The **Simulate** animation perform a multiple-step simulation at each frame. You can combine this animation with other animations which control atoms positions to perform constrained simulations. You can use the [Record path](https://documentation.samson-connect.net/users/latest/animations/record-path/index.md) animation to save the trajectory generated by the simulation. See also: [Record path](https://documentation.samson-connect.net/users/latest/animations/record-path/index.md), [Play path](https://documentation.samson-connect.net/users/latest/animations/play-path/index.md), [Play reverse path](https://documentation.samson-connect.net/users/latest/animations/play-reverse-path/index.md) animations ## Adding the animation Double-click on the **Simulate** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The keyframe will be placed at the current frame, move it if needed. Tip The [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator) executes animations from the top down, so place the **Simulate** animation after the ones which generates the starting positions of the simulation. Note You can always move the keyframes of the animation. Tip You can change the number of steps per frame and the step size for the simulator's state updater in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector) of the **Simulate** animation. ## Example > Simulating nanosystems helps designing them. In this example, the actuated part (in blue) of the nano gripper moves down too fast (1.7nm over 2.5ps -> 680m/s) and the gripper fails to grasp the cylinder. (Gripper design by [@mooreth42](https://twitter.com/mooreth42?ref_src=twsrc%5Etfw), who showed a successful grasp at a different… [pic.twitter.com/M5yKD7uA8T](https://t.co/M5yKD7uA8T) > > — Stephane Redon (@StephaneRedon) [May 8, 2024](https://twitter.com/StephaneRedon/status/1788013540466442709?ref_src=twsrc%5Etfw) # Stop The **Stop** animation stops the presentation at a given frame. To resume the presentation press `Space` or the Play button in [Animator's controls](https://documentation.samson-connect.net/users/latest/presenting/#animator-controls). You can use this, for example, to subdivide your presentation into slides. See also: [Pause](https://documentation.samson-connect.net/users/latest/animations/pause/index.md) animation ## Adding the animation Double-click on the **Stop** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The keyframe will be placed at the current frame, move it if needed. Note You can always move the keyframes of the animation. # Truck camera The **Truck camera** animation makes the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) move horizontally between two keyframes (in the camera reference frame) by modifying the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md)'s position and target point in a parallel way. This can be useful when you want to move the view (both the camera's target point and position) along some system in a horizontal direction. [Truck camera](https://documentation.samson-connect.net/users/latest/animations/truck-camera/index.md) and [Pedestal camera](https://documentation.samson-connect.net/users/latest/animations/pedestal-camera/index.md) animations act in the same way while moving the camera in the horizontal and vertical directions, correspondingly. See also: [Move camera](https://documentation.samson-connect.net/users/latest/animations/move-camera/index.md) animation. ## Adding the animation First, choose the start frame in the [Animator's Track view](https://documentation.samson-connect.net/users/latest/presenting/#animator-track-view) and [orient the view/camera](https://documentation.samson-connect.net/users/latest/moving-around/index.md) as you would like it to be positioned. Then, double-click on the **Truck camera** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The camera's target point and position are used for the start frame and for the end frame both of them are shifted horizontally to the right by the same distance. Set the end frame of the animation as needed. Note You can always move the start and end frames of the animation. ## Properties By default, camera animations are applied to the active [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) (to change that, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation and modify the **Apply to active camera** option). So, the **target point** of the animation will be defined as the current **target position** of the active camera, which is basically the current center of the view. The camera positions might be defined differently whether you have the **grid** in the switched on or off. To change how the animation behaves depending on whether the grid is on or off, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation and modify the **Keep camera upwards** option - if this option is checked then it will depend on whether the grid is on or off. You can also change how the camera's parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). ## Adjusting camera positions You can adjust the camera's target points and positions using the animation controllers. See [Adjusting camera positions](https://documentation.samson-connect.net/users/latest/presenting/#animations-adjusting-camera-positions). Note The Truck camera animation has some special limitations on how the camera's target points and positions can be adjusted. # Undock The **Undock** animation undocks groups of atoms or meshes from their current positions which are considered as docked positions. The final positions are automatically computed away from the docked positions. See also animations: [Dock](https://documentation.samson-connect.net/users/latest/animations/dock/index.md), [Hold atoms](https://documentation.samson-connect.net/users/latest/animations/hold-atoms/index.md), [Move atoms](https://documentation.samson-connect.net/users/latest/animations/move-atoms/index.md) ## Adding the animation To apply the dock animation, [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) at least two structural [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) or meshes in the document. The first node will act as the static receptor, and the other nodes will be animated. If multiple nodes should act as the receptor, create a folder, move these receptor nodes to the folder, and select the folder as the first node. If nothing is selected, then [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) will try to guess to what nodes the animation should be applied. Then, double-click on the **Undock** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). The selected nodes will be undocked between the two keyframes. Move the keyframes of the animation as needed. The amplitude of the movement is computed automatically on the creation of the animation, to change it, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation. Note You can always move the keyframes of the animation. Note In the movie we use the Animation menu which is no longer present in SAMSON. You can access all animations via the Animation panel in the **Animator** (1) and all presentation actions via the Animator's controls. 1. **Interface > Animator**, , : `Ctrl`+`7`, : `Cmd`+`7` ## Properties You can change the amplitude of the animation movement in the [Inspector](https://documentation.samson-connect.net/users/latest/interface/#inspector). You can change how the parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). ## Examples Some examples of presentations available on [SAMSON Connect - Documents](https://www.samson-connect.net/documents) that use the [Dock](https://documentation.samson-connect.net/users/latest/animations/dock/index.md) animation: - [2AZ8 - Dock animation](https://www.samson-connect.net/documents/aad9c1a7-3200-48e9-8ee8-0d74bc59657b) - [5SAT - Dock animation](https://www.samson-connect.net/documents/a9f2b952-e2e7-4800-b8c4-28152fe313a5) # Zoom camera The **Zoom camera** animation provides a zoom effect by modifying only the [camera](https://documentation.samson-connect.net/users/latest/camera/index.md)'s position between the start and end frames but leaving the target point unchanged. This is useful if you just want to zoom on a part of a system without, for example, changing target points for the [Fog](https://documentation.samson-connect.net/users/latest/rendering-effects/#fog) and [Depth-of-field](https://documentation.samson-connect.net/users/latest/rendering-effects/#depth-of-field) special effects. Compare it to the [Dolly camera](https://documentation.samson-connect.net/users/latest/animations/dolly-camera/index.md) animation which can have different target points for the start and end frames. See also: [Move camera](https://documentation.samson-connect.net/users/latest/animations/move-camera/index.md) animation. ## Adding the animation First, choose the start frame in the [Animator's Track view](https://documentation.samson-connect.net/users/latest/presenting/#animator-track-view) and [orient the view/camera](https://documentation.samson-connect.net/users/latest/moving-around/index.md) as you would like it to be positioned. Then, double-click on the **Zoom camera** animation effect in the [Animation panel](https://documentation.samson-connect.net/users/latest/presenting/#animation-panel) of the [Animator](https://documentation.samson-connect.net/users/latest/presenting/#animator). Set the end frame of the animation as needed. Note You can always move the start and end frames of the animation. ## Properties By default, camera animations are applied to the active [camera](https://documentation.samson-connect.net/users/latest/camera/index.md) (to change that, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation and modify the **Apply to active camera** option). So, the **target point** of the animation will be defined as the current **target position** of the active camera, which is basically the current center of the view. The camera positions might be defined differently whether you have the **grid** in the switched on or off. To change how the animation behaves depending on whether the grid is on or off, [inspect](https://documentation.samson-connect.net/users/latest/inspecting/index.md) the animation and modify the **Keep camera upwards** option - if this option is checked then it will depend on whether the grid is on or off. You can also change how the camera's parameters are interpolated between the frames by modifying the [Easing curve](https://documentation.samson-connect.net/users/latest/presenting/#animations-easing-curve). ## Adjusting camera positions You can adjust the camera's target point and positions using the animation controllers. See [Adjusting camera positions](https://documentation.samson-connect.net/users/latest/presenting/#animations-adjusting-camera-positions). # User Guide - Node Specification Language # Node Specification Language SAMSON has a powerful Node Specification Language (NSL) that can be used to select various structures (ligands, receptors, etc.) and [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) (atoms, residues, etc.) based on their properties. NSL can be used in the **Find** command or to **filter nodes** in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view). [Interactive tutorial](https://documentation.samson-connect.net/users/latest/interactive-tutorials/index.md) in SAMSON (**Help > Tutorials**): *"Selecting using the Node Specification Language"*. ## What you will learn This page teaches the core NSL syntax, where to enter expressions in SAMSON, and which reference pages to use when you need more precise attribute queries. ## NSL Quick Start This brief section introduces the fastest way to begin using the Node Specification Language (NSL) in SAMSON for search and filtering. Use it when you are new to NSL and want a practical starting point before reading the full syntax and attribute-space references. ### Where to use NSL - **Select > Find** for search-driven selections (see the [Find command](#find-command) section to learn more) - the filter box in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) for interactive filtering ### First expressions to try - `node.type residue` - `C or H` - `"CA" within 5A of S` - `node.category ligand, receptor` ### Related pages - [Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) ## Find command The **Find** command (1) in SAMSON lets you enter a NSL string to [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) nodes (atoms, residues, etc.) from the active [document](https://documentation.samson-connect.net/users/latest/documents/index.md): 1. **Select > Find**, , : `Ctrl`+`F`, : `Cmd`+`F` When using the Find command, you may press the `Tab` key in the search box for context-sensitive completion. This is particularly useful when searching nodes by name. For example, entering `"ALA` (with the opening quote sign and without the closing quote sign to indicate a start of a name) and pressing the `Tab` key will list all nodes whose name begins with *"ALA"*, e.g: - `"ALA 22 Backbone"` - `"ALA 22 Side chain"` - `"ALA 22"` - `"ALA 28 Backbone"` - `"ALA 28 Side chain"` - `"ALA 28"` - `...` Tip You can also ask AI Assistant to generate an NSL expression for you - click on the **Ask AI** button on the left of the **selection string**. The AI Assistant knows the active document's hierarchy, so you can ask for selections specific to your document. ## Find using Document View A NSL expression can also be used to **filter nodes** in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) (1) and to [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) them by clicking `Enter`, as shown in the image below when selecting structural groups via the following NSL: `n.t sg` (full version: `node.type structuralGroup`): 1. **Interface > Document view**, , : `Ctrl`+`1`, : `Cmd`+`1` Tip You can also ask AI Assistant to generate an NSL expression for you - click on the **Ask AI** button on the left of the **filter nodes** in the **Document view**. The AI Assistant knows the active document's hierarchy, so you can ask for selections specific to your document. ## Examples Here are some examples of NSL expressions: - `node.category ligand, receptor` (short version: `n.c lig, rec`): matches ligands and receptors - `Hydrogen` (short version: `H`): matches hydrogens - `residue.id 20:40, 50:60` (short version: `r.id 20:40, 50:60`): matches residues with IDs between 20 and 40 and between 50 and 60 - `atom.chainID > 2` (short version: `a.ci > 2`): matches atoms with a chain ID strictly larger than 2 - `Carbon in node.selected` (short version: `C in n.s`): matches carbons in the current selection - `bond.order > 1.5` (short version: `b.o > 1.5`): matches bonds with order strictly larger than 1.5 - `node.type backbone` (short version: `n.t bb`): matches backbone nodes [Logical operators](#logical-operators) examples: - `C or H`: matches atoms that are carbons or hydrogens - `node.type residue and not residue.type ALA` (short version: `n.t r and not r.t ALA`): matches all non-alanine residues [Topology operators](#topology-operators) examples: - `O in node.type sideChain` (short version: `O in n.t sc`): matches oxygens in side chain nodes - `n.t a out of n.t r`: matches atoms that do not belong to residues - `node.type sideChain having S` (short version: `n.t sc h S`): matches side chain nodes that have at least one sulfur atom - `H linking O` (short version: `H l O`): matches hydrogens bonded to oxygen atoms [Proximity operators](#proximity-operators) examples: - `"CA" within 5A of S` (short version: `"CA" w 5A of S`): matches nodes named "CA" that are within 5 angstrom of any sulfur atom (use quotes, since names may contain spaces) - `node.type residue beyond 5A of node.selected` (short version: `n.t r b 5A of n.s`): matches residue nodes beyond 5 angstrom of the current selection - `residue.secondaryStructure helix` (short version: `r.ss h`): matches residue nodes in alpha helices Tip See [more complex examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). ## Specification by attributes Nodes and groups of nodes may be specified by their attributes. SAMSON's NSL supports different attribute spaces based on [node types](https://documentation.samson-connect.net/users/latest/node-types/index.md). Since [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) may have different types in SAMSON (e.g. atom, bond, etc.), each attribute is defined in an *attribute space*: | Attribute space | Short name | | ------------------------------------------------------------------------------------------------------- | ---------- | | [`node`](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) | `n` | | [`animation`](https://documentation.samson-connect.net/users/latest/nsl/animation/index.md) | `an` | | [`atom`](https://documentation.samson-connect.net/users/latest/nsl/atom/index.md) | `a` | | [`backbone`](https://documentation.samson-connect.net/users/latest/nsl/backbone/index.md) | `bb` | | [`bond`](https://documentation.samson-connect.net/users/latest/nsl/bond/index.md) | `b` | | [`camera`](https://documentation.samson-connect.net/users/latest/nsl/camera/index.md) | `ca` | | [`chain`](https://documentation.samson-connect.net/users/latest/nsl/chain/index.md) | `c` | | [`conformation`](https://documentation.samson-connect.net/users/latest/nsl/conformation/index.md) | `co` | | [`file`](https://documentation.samson-connect.net/users/latest/nsl/file/index.md) | `fi` | | [`folder`](https://documentation.samson-connect.net/users/latest/nsl/folder/index.md) | `f` | | [`label`](https://documentation.samson-connect.net/users/latest/nsl/label/index.md) | `la` | | [`light`](https://documentation.samson-connect.net/users/latest/nsl/light/index.md) | `li` | | [`mesh`](https://documentation.samson-connect.net/users/latest/nsl/mesh/index.md) | `me` | | [`molecule`](https://documentation.samson-connect.net/users/latest/nsl/molecule/index.md) | `mol` | | [`nodeGroup`](https://documentation.samson-connect.net/users/latest/nsl/nodeGroup/index.md) | `ng` | | [`note`](https://documentation.samson-connect.net/users/latest/nsl/note/index.md) | `nt` | | [`path`](https://documentation.samson-connect.net/users/latest/nsl/path/index.md) | `p` | | [`presentation`](https://documentation.samson-connect.net/users/latest/nsl/presentation/index.md) | `pr` | | [`propertyModel`](https://documentation.samson-connect.net/users/latest/nsl/propertyModel/index.md) | `pm` | | [`renderPreset`](https://documentation.samson-connect.net/users/latest/nsl/renderPreset/index.md) | `rp` | | [`residue`](https://documentation.samson-connect.net/users/latest/nsl/residue/index.md) | `r` | | [`segment`](https://documentation.samson-connect.net/users/latest/nsl/segment/index.md) | `s` | | [`sideChain`](https://documentation.samson-connect.net/users/latest/nsl/sideChain/index.md) | `sc` | | [`structuralGroup`](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/index.md) | `sg` | | [`structuralModel`](https://documentation.samson-connect.net/users/latest/nsl/structuralModel/index.md) | `sm` | | [`visualModel`](https://documentation.samson-connect.net/users/latest/nsl/visualModel/index.md) | `vm` | The `node` attribute space (short name: `n`) corresponds to attributes that are defined for each node. For example, the [selection flag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag) is a node attribute, since each node has a [selection flag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). Hence, the NSL expression `node.selectionFlag true` may match any node whose selection flag is `true`, regardless of its node type (atom, bond, etc.). For convenience, the other attribute spaces inherit relevant attributes from the `node` attribute space. So, you can also use `atom.selectionFlag true` to match all atoms whose selection flag is `true`. ## Specification by name Nodes may be specified by their names using strings enclosed with quotes. A quoted string can be used in three ways: - **exact matching**: a quoted string without wildcards matches the full name exactly - **glob matching**: use `*` and `?` inside a quoted string for simple pattern matching - **regular-expression matching**: prefix a quoted string with `re` to use a full regular expression Note Bond names are formed from the names of the atoms they bond, and cannot be searched by name. ### Exact matching A quoted string without wildcards matches the full node name exactly. Examples: - `"ALA"`: matches nodes named exactly `ALA` - `"ALA 22"`: matches nodes named exactly `ALA 22` - `"CA"`: matches nodes named exactly `CA` ### Glob matching For simple name patterns, quoted strings support the following wildcards: - `*`: matches zero or more characters - `?`: matches exactly one character This is often the easiest way to search by name when you only need simple patterns. For example, entering `"ALA*"` may yield ALA residues, backbones, and side chains, e.g: - `"ALA 22 Backbone"` - `"ALA 22 Side chain"` - `"ALA 22"` - `"ALA 28 Backbone"` - `"ALA 28 Side chain"` - `"ALA 28"` - `...` Examples: - `"CA*"`: matches nodes whose names start with `CA` - `"*Backbone"`: matches nodes whose names end with `Backbone` - `"*AL*"`: matches nodes that contain `AL` in their names, e.g. ALA and VAL residues, backbones, and side chains - `"C?"`: matches names such as `CA` or `CB` or `CG`, etc. - `"???"`: matches names made of exactly three characters - `"ALA ?2"`: matches names where exactly one character appears before `2`, for example `ALA 12` Tip Use [regular expressions](#regular-expressions) for more complex cases. ### Regular expressions For more advanced matching, prefix the string with `re`, for example `re"..."` or `re "..."`. These expressions use the Perl-like regular-expression syntax (supported by Qt's `QRegularExpression`). Regular expressions are useful when `*` and `?` are not enough, for example when you want to match one of several names, restrict the number of characters, or specify character ranges. Examples: - `re"ALA.*"` or `re "ALA.*"`: matches names that begin with `ALA` - `re".*Backbone$"`: matches names that end with `Backbone` - `re"^(CB|CG|CE)$"`: matches exactly `CB`, `CG`, or `CD` - `re"^[A-Z]{3}$"`: matches names made of exactly three uppercase letters, which is useful for many residue-name patterns - `re"^Chain [A-C]$"`: matches names such as `Chain A`, `Chain B`, or `Chain C` - `re"^[A-Za-z]+ [0-9]+$"`: matches names made of a word followed by a number Tip Use [glob matching](#glob-matching) for simple cases, and use `re` only when you need more advanced matching. ## Specification by symbols and element names In order to efficiently match atoms of a given element type, symbols and element names are valid NSL expressions. Possible values: atomic symbols and element names (with the first character capitalized). Examples: - `Carbon`: matches carbon atoms - `C`: matches carbon atoms - `Ca`: matches calcium atoms - `H`: matches hydrogen atoms ## Lists and ranges NSL supports providing lists (divided by comma `,`) and ranges (via colon `:`) wherever possible. Examples: - `atom.chain A, B, C` (short version: `a.c A,B,C`): matches atoms in chains A, B, and C - `residue.id 20:40, 50:60` (short version: `r.id 20:40, 50:60`): matches residues with IDs between 20 and 40, and between 50 and 60 - `atom.x -1nm:1nm` (short version: `a.x -1nm:1nm`): matches atoms with x-coordinate between -1 nm and 1 nm ## Operations on sets ### Logical operators Logical operators may be used to perform operations on sets. Available operators: - `and` - `not` - `or` - `xor` (exclusive or). Examples: - `sg.id 1000:1040 and sg.nat < 4`: matches structural groups with IDs between 1000 and 1040 that have less than 4 atoms - `a.sn <= 20 or a.sn >=40`: matches atoms with serial number smaller than 20 or larger than 40 - `n.t r and not r.t CYS`: matches residues that are not cysteins - `a.sn >= 20 xor a.oc >= 0.5`: matches atoms which either have a serial number larger than 20, or have an occupancy larger than 0.5, but not those that satisfy both conditions Note Without proper care, the `not` condition might produce surprising results. For example, `not r.t CYS` does not return the list of residues that are not cysteins. Indeed, a folder is *also* a node which is *not* a residue that's a cystein. If only residues should be returned, a proper query would be `n.t r and not r.t CYS`. ### Topology operators Containment operators may be used to specify inclusion in or out of a set, one set having nodes from another set, or having atoms linked to atoms in another set. Available operators: - `in` - `out of` - `having` (short name: `h`) - whether a node has another node(s) - `linking` (short name: `l`) - whether an atom or a structural node is linked to another atom(s) or structural node(s) containing atoms Examples: - `n.t a in "2AZ8"`: matches atoms in "2AZ8" - `n.t a in r.t CYS`: matches atoms that belong to cysteins - `H in r.t ARG`: matches hydrogens that belong to arginins - `H in n.h`: matches hidden hydrogens - `n.t a out of r.t PRO`: matches atoms that do not belong to prolines - `node.type sideChain having S` (short version: `n.t sc h S`): matches side chain nodes that have at least one sulfur atom - `H linking O` (short version: `H l O`): matches hydrogens bonded to oxygen atoms - `node.type residue linking (residue.type PRO, CYS)` (short version: `n.t r l (r.t PRO, CYS)`): matches residues that have atoms linked to atoms in PRO or CYS residues, this includes PRO and CYS residues themselves. ### Proximity operators Proximity operators may be used to select nodes based on distances. | Operator | Short version | | ---------------------- | ----------------- | | `within {distance} of` | `w {distance} of` | | `beyond {distance} of` | `b {distance} of` | Examples: - `C within 5A of "GLN 2"` (short version: `C w 5A of "GLN 2"`): matches carbons within 5 angstrom of "GLN 2" - `node.type atom beyond 5A of "2AZ8-IA"` (short version: `n.t a b 5A of "2AZ8-IA"`): matches atoms beyond 5 angstrom of "2AZ8-IA" Note Without proper care, the `within` and `beyond` conditions might produce surprising results. For example, `* within 5A of "GLN 2"` will select the document node, since some atoms in the document are within 5 angstrom of `"GLN 2"`: the atoms that belong to `"GLN 2"`. If only atom nodes should be returned, a proper query would be `n.t a within 5A of "GLN 2"`. Note that this latter query would also return atoms *that belong to* `"GLN 2"`. If only atoms *outside* `"GLN 2"` should be returned, then a proper query would be `n.t a within 5A of "GLN 2" out of "GLN 2"`. ### Topological proximity operators Topological proximity operators may be used to select nodes based on the maximum number of bonds between atoms. | Operator | Short version | | --------------------------------- | ------------------------- | | `withinBond {number_of_bonds} of` | `wb {number_of_bonds} of` | Examples: - `atom.symbol C withinBond 3 of atom.symbol S` (short version: `a.s C wb 3 of a.s S`): matches Carbon atoms that are within 3 or less bonds of Sulfur atoms - `residue.type ALA withinBond 4 of residue.type GLY` (short version: `r.t ALA wb 4 of r.t GLY`): matches alanine residues that are within 4 or less bonds of glycine residues ## Length units | Length unit | Short name | | ------------ | ---------- | | `femtometer` | `fm` | | `picometer` | `pm` | | `angstrom` | `A` | | `nanometer` | `nm` | | `micrometer` | `um` | | `millimeter` | `mm` | | `centimeter` | `cm` | | `meter` | `m` | ## Mass units | Mass unit | Short name | | -------------- | ---------- | | `dalton` | `Da` | | `kilodalton` | `kDa` | | `megadalton` | `MDa` | | `gigadalton` | `GDa` | | `electronMass` | `auMass` | | `yoctogram` | `yg` | | `zeptogram` | `zg` | | `attogram` | `ag` | | `femtogram` | `fg` | | `picogram` | `pg` | | `nanogram` | `ng` | | `microgram` | `ug` | | `gram` | `g` | | `kilogram` | `kg` | ## Related pages - [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md) - [Atom attributes](https://documentation.samson-connect.net/users/latest/nsl/atom/index.md) - [Node attributes](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) - [Residue attributes](https://documentation.samson-connect.net/users/latest/nsl/residue/index.md) # Animation attributes This reference page summarizes the `animation` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Animation attributes are defined in the `animation` attribute space (short name: `an`), that matches only animation nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------- | ---------- | ----------------- | ------------------------------- | | [hidden](#hidden) | `h` | `true`, `false` | `an.h` `not an.h` | | [name](#name) | `n` | strings in quotes | `an.n "A"` `an.n "L*"` | | [selected](#selected) | | `true`, `false` | `an.selected` `not an.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `an.sf false` `an.sf` | | [visibilityFlag](#visibilityflag) | `vf` | `true`, `false` | `an.vf false` `an.vf` | | [visible](#visible) | `v` | `true`, `false` | `an.v` `not an.v` | ## hidden Inherited from [node.hidden](https://documentation.samson-connect.net/users/latest/nsl/node/#hidden). ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). ## visibilityFlag Inherited from [node.visibilityFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#visibilityflag). ## visible Inherited from [node.visible](https://documentation.samson-connect.net/users/latest/nsl/node/#visible). # Atom attributes This reference page summarizes the `atom` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Atom attributes are defined in the `atom` attribute space (short name: `a`). Atom attributes may only match atom nodes. The following atom attributes are available in NSL: | Attribute name | Short name | Possible values | Examples | | --------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------- | ----------------------------------- | | [altLocation](#altlocation) | `alt` | characters (A, B, ...) | `a.alt A` `a.alt B, C` | | [aminoAcidBackbone](#aminoacidbackbone) | `aabb` | `true`, `false` | `a.aabb` | | [aromatic](#aromatic) | `ar` | `true`, `false` | `a.ar` | | [chain](#chain) | `c` | characters (A, B, ...) | `a.c A` `a.c B, C` | | [chainID](#chainid) | `ci` | integers | `a.ci 1` | | [coarseGrainedMass](#coarsegrainedmass) | `cgm` | [mass](https://documentation.samson-connect.net/users/latest/nsl/#mass-units) | `a.cgm > 50Da` `a.cgm 50Da:75Da` | | [coarseGrainedRadius](#coarsegrainedradius) | `cgr` | [length](https://documentation.samson-connect.net/users/latest/nsl/#length-units) | `a.cgr > 0.5A` `a.cgr 0.5A:1A` | | [coarseGrainedType](#coarsegrainedtype) | `cgt` | names | `a.cgt P4` `a.cgt C3, C5` | | [customType](#customtype) | `ct` | integers | `a.ct 1` | | [element](#element) | `e` | element names | `a.e Carbon` `a.e Nitrogen, Oxygen` | | [formalCharge](#formalcharge) | `fc` | integers | `a.fc > 1` `a.fc -1, 1` | | [geometry](#geometry) | `g` | See atom [geometry](#geometry) | `a.g tetrahedral` | | [heavy](#heavy) | `nonH` | `true`, `false` | `a.heavy` | | [hetatm](#hetatm) | `het` | `true`, `false` | `a.het` | | [hybridization](#hybridization) | `hy` | See atom [hybridization](#hybridization) | `a.hy sp2` | | [hydrogenBondAcceptor](#hydrogenbondacceptor) | `hba` | `true`, `false` | `a.hba` | | [hydrogenBondDonor](#hydrogenbonddonor) | `hbd` | `true`, `false` | `a.hbd` | | [donorBorneHydrogen](#donorbornehydrogen) | `dbh` | `true`, `false` | `a.dbh` | | [fixed](#fixed) | `f` | `true`, `false` | `a.f` | | [inRing](#inring) | | `true`, `false` | `a.inRing` | | [nonPolarHydrogen](#nonpolarhydrogen) | `hnp` | `true`, `false` | `a.hnp` | | [nucleicAcidBackbone](#nucleicacidbackbone) | `nabb` | `true`, `false` | `a.nabb` | | [numberOfBondedAtoms](#numberofbondedatoms) | `nba` | integers | `a.nba > 2` | | [numberOfBondedCarbons](#numberofbondedcarbons) | `nbc` | integers | `a.nbc > 2` | | [numberOfBondedHeavyAtoms](#numberofbondedheavyatoms) | `nbha` | integers | `a.nbha 2` | | [numberOfBondedHydrogens](#numberofbondedhydrogens) | `nbh` | integers | `a.nbh 3` | | [numberOfBondedNitrogens](#numberofbondednitrogens) | `nbn` | integers | `a.nbn 1` | | [numberOfBondedOxygens](#numberofbondedoxygens) | `nbo` | integers | `a.nbo 2` | | [numberOfBondedSulfurs](#numberofbondedsulfurs) | `nbs` | integers | `a.nbs 1` | | [occupancy](#occupancy) | `oc` | floats | `a.oc < 0.3` | | [oxidationState](#oxidationstate) | `os` | integers | `a.os > 2` | | [partialCharge](#partialcharge) | `pc` | floats | `a.pc > 2` | | [planar](#planar) | `pl` | `true`, `false` | `a.pl` | | [polarHydrogen](#polarhydrogen) | `hp` | `true`, `false` | `a.hp` | | [residueSequenceNumber](#residuesequencenumber) | `resi` | integers | `a.resi 42` `a.resi 40:50,100` | | [resonance](#resonance) | `reso` | `true`, `false` | `a.reso` | | [ringSize](#ringsize) | | integers | `a.ringSize 5,6` | | [serialNumber](#serialnumber) | `sn` | integers | `a.sn > 1000` | | [substructureSequenceNumber](#substructuresequencenumber) | `sgi` | integers | `a.sgi 42` `a.sgi 40:50,100` | | [sybyl](#sybyl) | `sy` | SYBYL types | `a.sy C.2` `a.sy C.2, C.3` | | [symbol](#symbol) | `s` | element symbols | `a.s Ca` `a.s H, O, N, C` | | [temperatureFactor](#temperaturefactor) | `tf` | floats | `a.tf > 75` | | [water](#water) | `w` | `true`, `false` | `a.w` | | [x](#x-y-z) | | [length](https://documentation.samson-connect.net/users/latest/nsl/#length-units) | `a.x 0A:100A` | | [y](#x-y-z) | | [length](https://documentation.samson-connect.net/users/latest/nsl/#length-units) | `a.y -1nm:0nm` | | [z](#x-y-z) | | [length](https://documentation.samson-connect.net/users/latest/nsl/#length-units) | `a.z -1nm:1nm` | The following atom attributes depend only on the atom's element type (i.e. they are equal for atoms with the same element type): | Attribute name | Short name | Possible values | Examples | | ------------------------------------------- | ---------- | --------------------------------------------------------------------------------- | ------------------------------ | | [atomicNumber](#atomicnumber) | `at` | integers | `a.at 6` `a.at 6,8` | | [covalentRadius](#covalentradius) | `cr` | [length](https://documentation.samson-connect.net/users/latest/nsl/#length-units) | `a.cr > 0.6A` `a.cr 0.6A:1A` | | [vanDerWaalsRadius](#vanderwaalsradius) | `vdwr` | [length](https://documentation.samson-connect.net/users/latest/nsl/#length-units) | `a.vdwr > 2A` `a.vdwr 1.5A:2A` | | [electronegativity](#electronegativity) | `en` | floats | `a.en > 2` `a.en 1.57:3` | | [mass](#mass) | `m` | [mass](https://documentation.samson-connect.net/users/latest/nsl/#mass-units) | `a.m < 16Da` `a.m 14Da:19Da` | | [actinide](#actinide) | | `true`, `false` | `a.actinide` | | [alkaliMetal](#alkalimetal) | `alkali` | `true`, `false` | `a.alkaliMetal` | | [alkalineEarthMetal](#alkalineearthmetal) | `alkaline` | `true`, `false` | `a.alkalineEarthMetal` | | [diatomicNonmetal](#diatomicnonmetal) | | `true`, `false` | `a.diatomicNonmetal` | | [halogen](#halogen) | `hal` | `true`, `false` | `a.hal` | | [lanthanide](#lanthanide) | | `true`, `false` | `a.lanthanide` | | [metal](#metal) | `met` | `true`, `false` | `a.met` | | [metalloid](#metalloid) | | `true`, `false` | `a.metalloid` | | [nobleGas](#noblegas) | | `true`, `false` | `a.nobleGas` | | [reactiveNonmetal](#reactivenonmetal) | | `true`, `false` | `a.reactiveNonmetal` | | [polyatomicNonmetal](#polyatomicnonmetal) | | `true`, `false` | `a.polyatomicNonmetal` | | [postTransitionMetal](#posttransitionmetal) | | `true`, `false` | `a.postTransitionMetal` | | [transitionMetal](#transitionmetal) | | `true`, `false` | `a.transitionMetal` | ## actinide The `atom.actinide` attribute matches atoms from the actinide subcategory. Possible values: `true`, `false`. ## alkaliMetal The `atom.alkaliMetal` attribute (short name: `a.alkali`) matches atoms from the alkali metal subcategory. Possible values: `true`, `false`. ## alkalineEarthMetal The `atom.alkalineEarthMetal` attribute (short name: `a.alkaline`) matches atoms from the alkaline earth metal subcategory. Possible values: `true`, `false`. ## altLocation The `atom.altLocation` attribute (short name: `a.alt`) matches atoms based on their alternate location. Possible values: a character. Examples: - `atom.altLocation B` (short version: `a.alt B`): matches atoms with alternate location B - `atom.altLocation B, C` (short version: `a.alt B, C`): matches atoms with alternate location B or C ## aminoAcidBackbone The `atom.aminoAcidBackbone` attribute (short name: `a.aabb`) matches **heavy atoms** that belong to an amino-acid backbone. Possible values: `true`, `false`. Examples: - `atom.aminoAcidBackbone` (short version: `a.aabb`): matches **heavy atoms** that belong to an amino-acid backbone - `"CA" and atom.aminoAcidBackbone` (short version: `"CA" and a.aabb`): matches "CA" atoms that belong to an amino-acid backbone ## atomicNumber The `atom.atomicNumber` attribute (short name: `a.at`) matches atoms with specific atomic number. Possible values: integer. Examples: - `atom.atomicNumber 1` (short version: `a.at 1`): matches atoms with atomic number 1 - `atom.atomicNumber 6, 8` (short version: `a.at 6,8`): matches atoms with atomic number 6 or 8 ## aromatic The `atom.aromatic` attribute (short name: `a.ar`) matches atoms that are aromatic. Possible values: `true`, `false`. Examples: - `atom.aromatic` (short version: `a.ar`): matches aromatic atoms - `atom.symbol C and atom.aromatic` (short version: `a.s C and a.ar`): matches aromatic carbon atoms ## chain The `atom.chain` attribute (short name: `a.c`) matches atoms that are aromatic. Possible values: a character. Examples: - `atom.chain A` (short version: `a.c A`): matches atoms from chain A - `atom.chain B, C` (short version: `a.c B, C`): matches atoms from chain B or C ## chainID The `atom.chainID` attribute (short name: `a.ci`) matches atoms with specific chain IDs. Possible values: integers. Examples: - `atom.chainID 0` (short version: `a.ci 0`): matches atoms from chain ID 0 - `atom.chainID >= 0` (short version: `a.ci >= 0`): matches atoms from chain ID greater than 0 - `atom.chainID 0:2` (short version: `a.ci 0:2`): matches atoms from chain ID between 0 and 2 ## coarseGrainedMass The `atom.coarseGrainedMass` attribute (short name: `a.cgm`) matches coarse-grained atoms with specific coarse-grained mass. Note that this works only for coarse-grained atoms. Possible values: [mass units](https://documentation.samson-connect.net/users/latest/nsl/#mass-units). Examples: - `atom.coarseGrainedMass >= 50Da` (short version: `a.cgm >= 50Da`): matches coarse-grained atoms with their mass greater than or equal to 50 dalton - `atom.coarseGrainedMass 60Da:100Da` (short version: `a.cgm 60Da:100Da`): matches coarse-grained atoms that have mass between 60 and 100 daltons ## coarseGrainedRadius The `atom.coarseGrainedRadius` attribute (short name: `a.cgr`) matches coarse-grained atoms with specific coarse-grained radius. Note that this works only for coarse-grained atoms. Possible values: [length units](https://documentation.samson-connect.net/users/latest/nsl/#length-units). Examples: - `atom.coarseGrainedRadius == 0.3A` (short version: `a.cgr == 0.3A`): matches coarse-grained atoms with their radius equal to 0.3A - `atom.coarseGrainedRadius 0.2A:1A` (short version: `a.cgr 0.2A:1A`): matches coarse-grained atoms that have radius between 0.2A and 1A ## coarseGrainedType The `atom.coarseGrainedType` attribute (short name: `a.cgt`) matches coarse-grained atoms with specific types. Note that this works only for coarse-grained atoms with defined type. Possible values: a string. Examples: - `atom.coarseGrainedType P4` (short version: `a.cgt P4`): matches coarse-grained atoms with type P4 - `atom.coarseGrainedType C3, C5` (short version: `a.cgt C3, C5`): matches coarse-grained atoms with type C3 or C5 ## covalentRadius The `atom.covalentRadius` attribute (short name: `a.cr`) matches atoms with specific covalent radius. Possible values: [length units](https://documentation.samson-connect.net/users/latest/nsl/#length-units). Examples: - `atom.covalentRadius > 0.6A` (short version: `a.cr > 0.6A`): matches atoms with their covalent radius greater than 0.6A - `atom.covalentRadius 0.6A:1A` (short version: `a.cr 0.6A:1A`): matches atoms that have covalent radius between 0.6A and 1A ## customType The `atom.customType` attribute (short name: `a.ct`) matches atoms with specific custom types. Note that this works only for atoms with defined custom type. Possible values: integers. Examples: - `atom.customType 0` (short version: `a.ct 0`): matches atoms with custom type 0 - `atom.customType >= 0` (short version: `a.ct >= 0`): matches atoms with custom type greater than 0 - `atom.customType 0:2` (short version: `a.ct 0:2`): matches atoms with custom type between 0 and 2 ## diatomicNonmetal The `atom.diatomicNonmetal` attribute matches atoms from the diatomic nonmetal subcategory (H, N, O, F, Cl, Br, I). Possible values: `true`, `false`. ## electronegativity The `atom.electronegativity` attribute (short name: `a.en`) matches atoms with specific electronegativity. Possible values: float values. Examples: - `atom.electronegativity > 2` (short version: `a.en > 2`): matches atoms with their electronegativity greater than 2 - `atom.electronegativity 1.57:3` (short version: `a.en 1.57:3`): matches atoms that have electronegativity between 1.57 and 3 ## element The `atom.element` attribute (short name: `a.e`) matches atoms by element. Another option is to use [symbol](#symbol). Possible values: element names. Examples: - `atom.element Carbon` (short version: `a.e Carbon`): matches carbon atoms - `atom.element Oxygen, Nitrogen` (short version: `a.e Oxygen, Nitrogen`): matches oxygen and nitrogen atoms - `atom.symbol O` (short version: `a.s O`): matches oxygen atoms ## formalCharge The `atom.formalCharge` attribute (short name: `a.fc`) matches atoms with specific formal charges. Possible values: integer values. Examples: - `atom.formalCharge > 1` (short version: `a.fc > 1`): matches atoms with formal charge greater than 1 - `atom.formalCharge 2:3` (short version: `a.fc 2:3`): matches atoms with formal charge between 2 and 3 ## geometry The `atom.geometry` attribute (short name: `a.g`) matches atoms with specific geometry. Please note, that geometry needs to be computed first. Possible geometry type values: | Attribute name | Short name | | ---------------------------- | ---------- | | `linear` | `l` | | `bent` | `b` | | `trigonalplanar` | `tpl` | | `trigonalpyramidal` | `tpy` | | `tshaped` | `ts` | | `tetrahedral` | `tet` | | `squareplanar` | `spl` | | `seesaw` | `ss` | | `trigonalbipyramidal` | `tb` | | `squarepyramidal` | `spy` | | `pentagonalplanar` | `ppl` | | `octahedral` | `o` | | `trigonalprismatic` | `tpr` | | `pentagonalpyramidal` | `ppy` | | `pentagonalbipyramidal` | `pbp` | | `cappedoctahedral` | `co` | | `cappedtrigonalprismatic` | `ctp` | | `squareantiprismatic` | `sa` | | `dodecahedral` | `d` | | `bicappedtrigonalprismatic` | `btp` | | `tricappedtrigonalprismatic` | `ttp` | | `cappedsquareantiprismatic` | `csa` | | `undefined` | `u` | Examples: - `atom.geometry tetrahedral` (short version: `a.g tet`): matches atoms with tetrahedral geometry - `atom.geometry linear` (short version: `a.g l`): matches atoms with linear geometry - `atom.geometry octahedral, dodecahedral` (short version: `a.g o, d`): matches atoms with octahedral or dodecahedral geometry ## halogen The `atom.halogen` attribute (short name: `a.hal`) matches halogen (F, Cl, Br, I, At). Possible values: `true`, `false`. ## heavy The `atom.heavy` attribute (short name: `a.nonH`) matches heavy atoms (i.e., non-Hydrogens). Possible values: `true`, `false`. ## hetatm The `atom.hetatm` attribute (short name: `a.het`) matches heteroatoms in protein structures, i.e. atoms whose record type is HETATM in the Protein Data Bank file format. Possible values: `true`, `false`. Examples: - `atom.hetatm` (short version: `a.het`): matches atoms with HETATM record - `node.type atom and not (atom.symbol H, C)` (short version: `n.t a and not (a.s H, C)`): matches heteroatoms, i.e. atoms that are not carbons or hydrogens ## hybridization The `atom.hybridization` attribute (short name: `a.hy`) matches atoms with specific hybridization. Please note, that hybridization needs to be assigned first. Note that hybridization might not be specified for atoms by default. Possible hybridization type values: | Attribute name | Aliases | | -------------- | ------- | | `none` | `n` | | `SP` | `sp` | | `SP2` | `sp2` | | `SP3` | `sp3` | | `SP3D` | `sp3d` | | `SP3D2` | `sp3d2` | | `unknown` | `u` | Examples: - `atom.hybridization SP2` (short version: `a.hy sp2`): matches atoms with SP2 hybridization. - `atom.hybridization none` (short version: `a.hy n`): matches atoms with no hybridization specified. - `atom.hybridization SP2, SP3` (short version: `a.hy sp2, sp3`): matches atoms with SP2 or SP3 hybridization. ## hydrogenBondAcceptor The `atom.hydrogenBondAcceptor` (short version: `a.hba`) attribute matches hydrogen-bond acceptors. Possible values: `true`, `false`. ## hydrogenBondDonor The `atom.hydrogenBondDonor` (short version: `a.hbd`) attribute matches hydrogen-bond donors. Possible values: `true`, `false`. ## donorBorneHydrogen The `atom.donorBorneHydrogen` (short version: `a.dbh`) attribute matches donor-linked hydrogens in hydrogen bonds (i.e., donor-born hydrogens). Possible values: `true`, `false`. ## lanthanide The `atom.lanthanide` attribute matches atoms from the lanthanide subcategory. Possible values: `true`, `false`. ## mass The `atom.mass` attribute (short name: `a.cgm`) matches atoms with specific mass. Possible values: [mass units](https://documentation.samson-connect.net/users/latest/nsl/#mass-units). Examples: - `atom.mass > 16Da` (short version: `a.cgm > 16Da`): matches coarse-grained atoms with their mass greater than 16 dalton - `atom.mass 14Da:19Da` (short version: `a.cgm 14Da:19Da`): matches coarse-grained atoms that have mass between 14 and 19 daltons ## metal The `atom.metal` attribute (short name: `a.met`) matches atoms from metal subcategories. Possible values: `true`, `false`. Examples: - `atom.metal` (short version: `a.met`): matches atoms from metal subcategories - `node.type atom and not atom.metal` (short version: `n.t a and not a.met`): matches atoms that are not from metal subcategories ## metalloid The `atom.metalloid` attribute matches atoms from the metalloid subcategory. Possible values: `true`, `false`. ## mobile Deprecated: use [fixed](#fixed) instead. The `atom.mobile` attribute (short name: `a.mo`) matches atoms that are mobile. Possible values: `true`, `false`. Examples: - `atom.mobile` (short version: `a.mo`): matches mobile atoms ## fixed The `atom.fixed` attribute (short name: `a.f`) matches atoms that are fixed (non-mobile). Possible values: `true`, `false`. Examples: - `atom.fixed` (short version: `a.f`): matches fixed atoms - `node.type atom and not atom.fixed` (short version: `n.t a and not a.f`): matches non-fixed atoms ## inRing The `atom.inRing` attribute matches atoms that are in rings. Possible values: `true`, `false`. ## nobleGas The `atom.nobleGas` attribute matches atoms from the noble gas subcategory. Possible values: `true`, `false`. ## nonPolarHydrogen The `atom.nonPolarHydrogen` attribute (short name: `a.hnp`) matches non-polar hydrogens. See also: [polarHydrogen](#polarhydrogen). Possible values: `true`, `false`. ## nucleicAcidBackbone The `atom.nucleicAcidBackbone` attribute (short name: `a.nabb`) matches **heavy atoms** that belong to a nucleic acid backbone. Possible values: `true`, `false`. Examples: - `atom.nucleicAcidBackbone` (short version: `a.nabb`): matches **heavy atoms** that belong to a nucleic acid backbone ## numberOfBondedAtoms The `atom.numberOfBondedAtoms` attribute (short name: `a.nba`) matches atoms with a specific number of bonded atoms. Possible values: integers. Examples: - `atom.numberOfBondedAtoms > 3` (short version: `a.nba > 3`): matches atoms that have more than 3 bonded atoms ## numberOfBondedCarbons The `atom.numberOfBondedCarbons` attribute (short name: `a.nbc`) matches atoms with a specific number of bonded carbon atoms. Possible values: integers. Examples: - `atom.numberOfBondedCarbons > 3` (short version: `a.nbc > 3`): matches atoms that have more than 3 bonded carbon atoms ## numberOfBondedHeavyAtoms The `atom.numberOfBondedHeavyAtoms` attribute (short name: `a.nbha`) matches atoms with a specific number of bonded heavy (non-hydrogen) atoms. Possible values: integers. Examples: - `atom.numberOfBondedHeavyAtoms 3` (short version: `a.nbha 3`): matches atoms that have exactly 3 bonded heavy atoms ## numberOfBondedHydrogens The `atom.numberOfBondedHydrogens` attribute (short name: `a.nbh`) matches atoms with a specific number of bonded hydrogen atoms. Possible values: integers. Examples: - `atom.numberOfBondedHydrogens 3` (short version: `a.nbh 3`): matches atoms that have exactly 1 bonded hydrogen atom ## numberOfBondedNitrogens The `atom.numberOfBondedNitrogens` attribute (short name: `a.nbn`) matches atoms with a specific number of bonded nitrogen atoms. Possible values: integers. Examples: - `atom.numberOfBondedNitrogens < 2` (short version: `a.nbn < 2`): matches atoms that have less than 2 bonded nitrogen atoms ## numberOfBondedOxygens The `atom.numberOfBondedOxygens` attribute (short name: `a.nbo`) matches atoms with a specific number of bonded oxygen atoms. Possible values: integers. Examples: - `atom.numberOfBondedOxygens 2` (short version: `a.nbo 2`): matches atoms that have exactly 2 bonded oxygen atoms ## numberOfBondedSulfurs The `atom.numberOfBondedSulfurs` attribute (short name: `a.nbs`) matches atoms with a specific number of bonded sulfur atoms. Possible values: integers. Examples: - `atom.numberOfBondedSulfurs 0` (short version: `a.nbs 0`): matches atoms that have zero bonded sulfur atoms ## occupancy The `atom.occupancy` attribute (short name: `a.oc`) matches atoms with a specific occupancy. Possible values: floating-point values. Examples: - `atom.occupancy > 0.5` (short version: `a.oc > 0.5`): matches atoms with occupancy greater than 0.5 - `atom.occupancy 0.6:0.7` (short version: `a.oc 0.6:0.7`): matches atoms with occupancy between 0.6 and 0.7 ## oxidationState The `atom.oxidationState` attribute (short name: `a.os`) matches atoms with a specific oxidation state. Possible values: integer values. Examples: - `atom.oxidationState >= 2` (short version: `a.os >= 2`): matches atoms with oxidation state greater than or equal to 2 ## partialCharge The `atom.partialCharge` attribute (short name: `a.pc`) matches atoms with specific partial charges. Possible values: floating-point values. Examples: - `atom.partialCharge >= 1.3` (short version: `a.pc >= 1.3`): matches atoms with partial charge greater than or equal to 1.3 ## planar The `atom.planar` attribute (short name: `a.pl`) matches planar atoms, i.e. atoms that are in a plane with its covalently bonded atoms. Possible values: `true`, `false`. Examples: - `atom.planar` (short version: `a.pl`): matches planar atoms ## polarHydrogen The `atom.polarHydrogen` attribute (short name: `a.hp`) matches polar hydrogens. Polar hydrogens are hydrogens attached to atoms with significantly larger electronegativity: N, O, S, F, Cl. Possible values: `true`, `false`. ## reactiveNonmetal The `atom.reactiveNonmetal` attribute matches atoms from the reactive nonmetal subcategory. Possible values: `true`, `false`. ## polyatomicNonmetal The `atom.polyatomicNonmetal` attribute matches atoms from the polyatomic nonmetal subcategory (C, P, S, Se). Possible values: `true`, `false`. ## postTransitionMetal The `atom.postTransitionMetal` attribute matches atoms from the post-transition metal subcategory. Possible values: `true`, `false`. ## residueSequenceNumber The `atom.residueSequenceNumber` attribute (short name: `a.resi`) matches atoms in residues with specific IDs. Possible values: integers. Examples: - `atom.residueSequenceNumber 12` (short version: `a.resi 12`): matches atoms in residues with ID 12 - `atom.residueSequenceNumber 12:97` (short version: `a.resi 12:97`): matches atoms in residues with IDs between 12 to 97 ## resonance The `atom.resonance` attribute (short name: `a.reso`) matches resonant atoms. Possible values: `true`, `false`. Examples: - `atom.resonance` (short version: `a.reso`): matches resonant atoms - `node.type atom and not atom.resonance` (short version: `n.t a and not a.reso`): matches non-resonant atoms ## ringSize The `atom.ringSize` attribute matches atoms that are only in rings with the specified number of atoms. If an atom is in two rings of different size at the same time, then it will return the smalles ring size. Possible values: integers. Examples: - `atom.ringSize 6` : matches atoms that are in a ring with 6 atoms. - `atom.ringSize 5,6` : matches atoms that are in a ring with 5 or 6 atoms. ## serialNumber The `atom.serialNumber` attribute (short name: `a.sn`) matches atoms with specific serial numbers. Possible values: integers. Examples: - `atom.serialNumber > 20` (short version: `a.sn > 20`): matches atoms with serial number greater than 20 - `atom.serialNumber 20:897` (short version: `a.sn 20:897`): matches atoms with serial number between 20 and 897 ## substructureSequenceNumber The `atom.substructureSequenceNumber` attribute (short name: `a.sgi`) matches atoms in structural groups with specific IDs. Possible values: integers. Examples: - `atom.substructureSequenceNumber 1000` (short version: `a.sgi 1000`): matches atoms in structural groups with ID 1000 - `atom.substructureSequenceNumber 10:40` (short version: `a.sgi 10:40`): matches atoms in structural groups with IDs between 12 to 97 ## sybyl The `atom.sybyl` attribute (short name: `a.sy`) matches atoms with the specified SYBYL type. Please note, that atoms need to have SYBYL types assigned. Possible values: sybyl type names, e.g. "C.2", "C.3", "N.2", etc. Examples: - `atom.sybyl "C.3"` (short version: `a.sy "C.3"`): matches atoms with the specified *C.3* SYBYL type ## symbol The `atom.symbol` attribute (short name: `a.s`) matches atoms with specific symbols. Possible values: element symbols. Examples: - `atom.symbol C` (short version: `a.s C`): matches carbon atoms - `atom.symbol O, N` (short version: `a.s O, N`): matches atoms that are oxygens and nitrogens ## temperatureFactor The `atom.temperatureFactor` attribute (short name: `a.tf`) matches atoms with specific temperature factors. Possible values: floating-point values. Examples: - `atom.temperatureFactor > 2` (short version: `a.tf > 2`): matches atoms with a temperature factor strictly greater than 2 - `atom.temperatureFactor 10:50` (short version: `a.tf 10:50`): matches atoms with a temperature factor between 10 and 50 ## transitionMetal The `atom.transitionMetal` attribute matches atoms from the transition metal subcategory. Possible values: `true`, `false`. ## vanDerWaalsRadius The `atom.vanDerWaalsRadius` attribute (short name: `a.vdwr`) matches atoms with specific van der Waals radius. Possible values: [length units](https://documentation.samson-connect.net/users/latest/nsl/#length-units). Examples: - `atom.vanDerWaalsRadius > 2A` (short version: `a.vdwr > 2A`): matches atoms with their van der Waals radius greater than 2A - `atom.vanDerWaalsRadius 1.5A:2A` (short version: `a.vdwr 1.5A:2A`): matches atoms that have van der Waals radius between 1.5A and 2A ## water The `atom.water` attribute (short name: `a.w`) matches atoms with the water flag. Possible values: `true`, `false`. Examples: - `atom.water` (short version: `a.w`): matches water atoms - `atom.symbol O and atom.water` (short version: `a.s O and a.w`): matches oxygen atoms that have the water flag - `atom.symbol O in water` (short version: `a.s O in wat`): matches oxygen atoms in water ## x, y, z The `atom.x`, `atom.y`, `atom.z` (short names: `a.x`, `a.y`, `a.z`) attributes match atoms with specific x, y, z coordinates. Possible values: [length units](https://documentation.samson-connect.net/users/latest/nsl/#length-units). Examples: - `atom.x >= 1.0 A` (short version: `a.x >= 1.0 A`): matches atoms whose x coordinate is greater than or equal to 1.0 angstrom - `atom.y < 2.0 nm` (short version: `a.y < 2.0 nm`): matches atoms whose y coordinate is less than 2 nm - `atom.z > 100 pm` (short version: `a.z > 100 pm`): matches atoms whose z coordinate is greater than 100 pm - `atom.x 1nm:10nm` (short version: `a.x 1nm:10nm`): matches atoms whose x coordinate is between 1 nm and 10 nm - `atom.x > 10 A and atom.y > 10 A` (short version: `a.x > 10 A and a.y > 10 A`): matches atoms whose x and y coordinates are greater than 10 angstroms ## Related pages - [Node attributes](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) - [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md) # Backbone attributes This reference page summarizes the `backbone` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Backbone attributes are defined in the `backbone` attribute space (short name: `s`), that matches only backbone nodebb. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------- | ---------- | ----------------- | ------------------------------- | | [hasMaterial](#hasmaterial) | `hm` | `true`, `false` | `bb.hm` `not bb.hm` | | [hidden](#hidden) | `h` | `true`, `false` | `bb.h` `not bb.h` | | [name](#name) | `n` | strings in quotes | `bb.n "A"` `bb.n "L*"` | | [ownsMaterial](#ownsmaterial) | `om` | `true`, `false` | `bb.om` | | [selected](#selected) | | `true`, `false` | `bb.selected` `not bb.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `bb.sf false` `bb.sf` | | [visibilityFlag](#visibilityflag) | `vf` | `true`, `false` | `bb.vf false` `bb.vf` | | [visible](#visible) | `v` | `true`, `false` | `bb.v` `not bb.v` | Attributes inherited from the [structuralGroup](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------------------------------- | ---------- | --------------- | ---------------------------------- | | [formalCharge](#formalcharge) | `fc` | integers | `bb.fc > 1` `bb.fc 6:8` | | [numberOfAtoms](#numberofatoms) | `nat` | integers | `bb.nat < 1000` `bb.nat 100:200` | | [numberOfCarbons](#numberofcarbons) | `nC` | integers | `bb.nC < 10` `bb.nC 10:20` | | [numberOfHydrogens](#numberofhydrogens) | `nH` | integers | `bb.nH < 10` `bb.nH 10:20` | | [numberOfNitrogens](#numberofnitrogens) | `nN` | integers | `bb.nN < 10` `bb.nN 10:20` | | [numberOfOxygens](#numberofoxygens) | `nO` | integers | `bb.nO < 10` `bb.nO 10:20` | | [numberOfSulfurs](#numberofsulfurs) | `nS` | integers | `bb.nS < 10` `bb.nS 10:20` | | [numberOfCoarseGrainedAtoms](#numberofcoarsegrainedatoms) | `ncga` | integers | `bb.ncga < 1000` `bb.ncga 100:200` | | [partialCharge](#partialcharge) | `pc` | floats | `bb.pc > 1.5` `bb.pc 1.5:2.0` | ## formalCharge Inherited from [structuralGroup.formalCharge](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#formalcharge). ## hasMaterial Inherited from [node.hasMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#hasmaterial). ## hidden Inherited from [node.hidden](https://documentation.samson-connect.net/users/latest/nsl/node/#hidden). ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## numberOfAtoms Inherited from [structuralGroup.numberOfAtoms](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofatoms). ## numberOfCarbons Inherited from [structuralGroup.numberOfCarbons](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofcarbons). ## numberOfCoarseGrainedAtoms Inherited from [structuralGroup.numberOfCoarseGrainedAtoms](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofcoarsegrainedatoms). ## numberOfHydrogens Inherited from [structuralGroup.numberOfHydrogens](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofhydrogens). ## numberOfNitrogens Inherited from [structuralGroup.numberOfNitrogens](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofnitrogens). ## numberOfOxygens Inherited from [structuralGroup.numberOfOxygens](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofoxygens). ## numberOfSulfurs Inherited from [structuralGroup.numberOfSulfurs](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofsulfurs). ## ownsMaterial Inherited from [node.ownsMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#ownsmaterial). ## partialCharge Inherited from [structuralGroup.partialCharge](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#partialcharge). ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). ## visibilityFlag Inherited from [node.visibilityFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#visibilityflag). ## visible Inherited from [node.visible](https://documentation.samson-connect.net/users/latest/nsl/node/#visible). # Bond attributes This reference page summarizes the `bond` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Bond attributes are defined in the `bond` attribute space (short name: `b`). Bond attributes may only match bond nodes. The following bond attributes are available in NSL: | Attribute name | Short name | Possible values | Examples | | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- | | [customType](#customtype) | `ct` | integers | `b.ct 1` `b.ct 1, 2` | | [length](#length) | `len` | [length](https://documentation.samson-connect.net/users/latest/nsl/#length-units) | `b.len > 1.2 A` `b.len 0.12nm:0.17nm` | | [order](#order) | `o` | floats | `b.o >= 1` `b.o 1:1.5` | | [type](#type) | `t` | `single` (`s`, `1`), `double` (`d`, `2`), `triple` (`t`, `3`), `amide` (`am`), `aromatic` (`ar`), `dummy` (`du`), `undefined` (`un`) | `b.t s` `b.t s, d` | ## customType The `bond.customType` attribute (short name: `b.ct`) matches bonds with specific custom types. Possible values: integers. Examples: - `bond.customType 0` (short version: `b.ct 0`): matches bonds with custom type 0 - `bond.customType >= 0` (short version: `b.ct >= 0`): matches bonds with custom type larger than 0 - `bond.customType 0:2` (short version: `b.ct 0:2`): matches bonds with custom type between 0 and 2 ## length The `bond.length` attribute (short name: `b.len`) matches bonds with specific bond length. Possible values: floating-point values. Examples: - `bond.length >= 1.5A` (short version: `b.len >= 1.5A`): matches bonds with length larger than 1.5 angstroms - `bond.length 1.2A:1.4A` (short version: `b.len 1.2A:1.4A`): matches bonds with length between 1.2 and 1.4 angstroms - `bond.length 0.15nm:2.1nm` (short version: `b.len 0.15nm:2.1nm`): matches bonds with length between 0.15 and 2.1 nanometers ## order The `bond.order` attribute (short name: `b.o`) matches bonds with specific orders. Possible values: floating-point values. Examples: - `bond.order >= 2` (short version: `b.o >= 2`): matches bonds with order larger than 2 - `bond.order 1.5:3` (short version: `b.o 1.5:3`): matches bonds with order between 1.5 and 3 ## type The `bond.type` attribute (short name: `b.t`) matches bonds with one of the specific types: | Attribute name | Short name | Meaning | | -------------- | ---------- | --------------- | | `single` | `s`, `1` | single bond | | `double` | `d`, `2` | double bond | | `triple` | `t`, `3` | triple bond | | `amide` | `am` | amide bond | | `aromatic` | `ar` | aromatic bond | | `dummy` | `du` | dummy bond | | `undefined` | `un` | undefined bonds | Note, that to use this a bond needs to have its bond type defined. Examples: - `bond.type single` (short name: `b.t s`): matches single bonds - `bond.type single, double` (short name: `b.t s,d`): matches single and double bonds - `bond.type dummy, undefined` (short name: `b.t du,un`): matches dummy and undefined bonds # Camera attributes This reference page summarizes the `camera` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Camera attributes are defined in the `camera` attribute space (short name: `ca`), that matches only camera nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | ------------------------------- | ---------- | ----------------- | ------------------------------- | | [name](#name) | `n` | strings in quotes | `ca.n "A"` `ca.n "L*"` | | [selected](#selected) | | `true`, `false` | `ca.selected` `not ca.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `ca.sf false` `ca.sf` | ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). # Chain attributes This reference page summarizes the `chain` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Chain attributes are defined in the `chain` attribute space (short name: `c`), that matches only chain nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------- | ---------- | ----------------- | ----------------------------- | | [hasMaterial](#hasmaterial) | `hm` | `true`, `false` | `c.hm` `not c.hm` | | [hidden](#hidden) | `h` | `true`, `false` | `c.h` `not c.h` | | [name](#name) | `n` | strings in quotes | `c.n "A"` `c.n "L*"` | | [ownsMaterial](#ownsmaterial) | `om` | `true`, `false` | `c.om` | | [selected](#selected) | | `true`, `false` | `c.selected` `not c.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `c.sf false` `c.sf` | | [visibilityFlag](#visibilityflag) | `vf` | `true`, `false` | `c.vf false` `c.vf` | | [visible](#visible) | `v` | `true`, `false` | `c.v` `not c.v` | Attributes inherited from the [structuralGroup](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------------------------------- | ---------- | --------------- | -------------------------------- | | [formalCharge](#formalcharge) | `fc` | integers | `c.fc > 1` `c.fc 6:8` | | [numberOfAtoms](#numberofatoms) | `nat` | integers | `c.nat < 1000` `c.nat 100:200` | | [numberOfCarbons](#numberofcarbons) | `nC` | integers | `c.nC < 10` `c.nC 10:20` | | [numberOfHydrogens](#numberofhydrogens) | `nH` | integers | `c.nH < 10` `c.nH 10:20` | | [numberOfNitrogens](#numberofnitrogens) | `nN` | integers | `c.nN < 10` `c.nN 10:20` | | [numberOfOxygens](#numberofoxygens) | `nO` | integers | `c.nO < 10` `c.nO 10:20` | | [numberOfSulfurs](#numberofsulfurs) | `nS` | integers | `c.nS < 10` `c.nS 10:20` | | [numberOfCoarseGrainedAtoms](#numberofcoarsegrainedatoms) | `ncga` | integers | `c.ncga < 1000` `c.ncga 100:200` | | [partialCharge](#partialcharge) | `pc` | floats | `c.pc > 1.5` `c.pc 1.5:2.0` | Attributes specific to the `chain` attribute space: | Attribute name | Short name | Possible values | Examples | | ----------------------------------------------------- | ---------- | --------------- | ---------------------------------- | | [chainID](#chainid) | `id` | integers | `c.id 1` `c.id <= 3` `c.id 2:4, 6` | | [numberOfResidues](#numberofresidues) | `nr` | integers | `c.nr > 130` `c.nr 100:130` | | [numberOfSegments](#numberofsegments) | `ns` | integers | `c.ns < 3` `c.ns 1:3` | | [numberOfStructuralGroups](#numberofstructuralgroups) | `nsg` | integers | `c.nsg > 10` `c.nsg 10:13` | ## chainID The `chain.chainID` attribute (short name: `c.id`) matches chains with specific chain ID. Possible values: integers. Examples: - `chain.id 1` (short version: `c.id 1`): matches chains with chain ID equal to 1 - `chain.id 2:4, 6` (short version: `c.id 2:4,6`): matches chains with chain ID between 2 and 4 and with chain ID equal to 6 ## formalCharge Inherited from [structuralGroup.formalCharge](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#formalcharge). ## hasMaterial Inherited from [node.hasMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#hasmaterial). ## hidden Inherited from [node.hidden](https://documentation.samson-connect.net/users/latest/nsl/node/#hidden). ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## numberOfAtoms Inherited from [structuralGroup.numberOfAtoms](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofatoms). ## numberOfCarbons Inherited from [structuralGroup.numberOfCarbons](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofcarbons). ## numberOfCoarseGrainedAtoms Inherited from [structuralGroup.numberOfCoarseGrainedAtoms](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofcoarsegrainedatoms). ## numberOfHydrogens Inherited from [structuralGroup.numberOfHydrogens](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofhydrogens). ## numberOfNitrogens Inherited from [structuralGroup.numberOfNitrogens](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofnitrogens). ## numberOfOxygens Inherited from [structuralGroup.numberOfOxygens](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofoxygens). ## numberOfResidues The `chainnumberOfResidues` attribute (short name: `c.nr`) matches chains with specific number of residues. Possible values: integers. Examples: - `chain.numberOfResidues > 100` (short version: `c.nr > 100`): matches chains with the number of residues greater than 100 - `chain.numberOfResidues 100:120` (short version: `c.nr 100:120`): matches chains with the number of residues between 100 and 120 ## numberOfSegments The `chain.numberOfSegments` attribute (short name: `c.ns`) matches chains with specific number of segments. Possible values: integers. Examples: - `chain.numberOfSegments > 2` (short version: `c.ns > 2`): matches chains with the number of segments greater than 2 - `chain.numberOfSegments 2:4` (short version: `c.ns 2:4`): matches chains with the number of segments between 2 and 4 ## numberOfStructuralGroups The `chain.numberOfStructuralGroups` attribute (short name: `c.nsg`) matches chains with specific number of structural groups. Possible values: integers. Examples: - `chain.numberOfStructuralGroups > 10` (short version: `c.nsg > 10`): matches chains with the number of structural groups greater than 10 - `chain.numberOfStructuralGroups 10:12` (short version: `c.nsg 10:12`): matches chains with the number of structural groups between 10 and 12 ## numberOfSulfurs Inherited from [structuralGroup.numberOfSulfurs](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofsulfurs). ## ownsMaterial Inherited from [node.ownsMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#ownsmaterial). ## partialCharge Inherited from [structuralGroup.partialCharge](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#partialcharge). ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). ## visibilityFlag Inherited from [node.visibilityFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#visibilityflag). ## visible Inherited from [node.visible](https://documentation.samson-connect.net/users/latest/nsl/node/#visible). ## Related pages - [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) - [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md) # Conformation attributes This reference page summarizes the `conformation` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Conformation attributes are defined in the `conformation` attribute space (short name: `co`), that matches only conformation nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | ------------------------------- | ---------- | ----------------- | ------------------------------- | | [name](#name) | `n` | strings in quotes | `co.n "A"` `co.n "L*"` | | [selected](#selected) | | `true`, `false` | `co.selected` `not co.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `co.sf false` `co.sf` | Attributes specific to the `conformation` attribute space: | Attribute name | Short name | Possible values | Examples | | ------------------------------- | ---------- | --------------- | ----------------------------- | | [numberOfAtoms](#numberofatoms) | `nat` | integers | `co.nat > 100` `co.n 100:200` | ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## numberOfAtoms The `conformation.numberOfAtoms` attribute (short name: `co.nat`) matches conformations with specific number of atoms. Possible values: integers. Examples: - `conformation.nat > 100` (short version: `co.nat > 100`): matches conformations with the number of atoms more than 100 - `conformation.nat 100:200` (short version: `co.nat 100:200`): matches conformations with the number of atoms between 100 and 200 ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). # NSL examples This reference page explains the `nsl examples` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md) and shows how to use it in selections and filters. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). ## Examples Below you can see a table of problem-oriented selection tasks with the corresponding NSL expressions. | Task | NSL expression | | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | Receptor residues within 6 Å of any ligand, excluding Gly/Ala (mutagenesis focus) | `((n.t r and not r.t GLY,ALA) in n.c rec) w 6A of n.c lig` | | Backbone nitrogen atoms contacting ligands within 3 Å | `(a.s N in n.t bb) w 3A of n.c lig` | | Ligand heavy atoms (non-hydrogen) for contact analysis | `(n.t a in n.c lig) and not a.s H` | | Water within 4 Å of any ligand (displaceable waters) | `n.c wat w 4A of n.c lig` | | Binding-pocket atoms: atoms in residues within 5 Å of a ligand | `n.t a in (n.t r w 5A of n.c lig)` | | Water oxygens bridging receptor and ligand (=3 Å to both) | `(a.s O in n.c wat) and (n.t a w 3A of n.c rec) and (n.t a w 3A of n.c lig)` | | Positively or negatively charged residues within 8 Å of ligand | `(r.c positive, negative) and (n.t r w 8A of n.c lig)` | | Receptor atoms within 5 Å of ligand but >3 Å from any water oxygen | `(n.t a in n.c rec) and (n.t a w 5A of n.c lig) and (n.t a b 3A of (a.s O in n.c wat))` | | Aromatic residues near ligand (p-stack candidates) within 5 Å | `(r.t PHE,TYR,TRP,HIS) and (n.t r w 5A of n.c lig)` | | Potential salt-bridge partners: positive residues within 3 Å of negative residues | `r.c positive w 3A of r.c negative` | | Polar heavy atoms (O/N) in receptor within 3 Å of ligand | `(a.s O,N in n.c rec) w 3A of n.c lig` | | Atoms in protein chain "A" within 5 Å of protein chain "B" (protein-protein interface), non-H | `(((n.t a in c.n "A") in n.c rec) and not a.s H) w 5A of (((n.t a in c.n "B") in n.c rec) and not a.s H)` | | Backbone atoms not contacting ligand (>6 Å away) | `(n.t a in n.t bb) b 6A of n.c lig` | | Residues coordinating metals: residues within 2.5 Å of metal ions | `n.t r w 2.5A of (a.transitionMetal or a.alkaliMetal)` | | Glycine alpha carbons within 5 Å of ligands | `("CA" in r.t GLY) w 5A of n.c lig` | | Helical residues contacting ligand (=5 Å) | `r.ss a w 5A of n.c lig` | | Chain "B" residues contacting glycans (=5 Å) | `(n.t r in c.n "B") w 5A of n.c gly` | | Negative receptor residues close to positive receptor residues (=4 Å) | `(r.c negative in n.c rec) w 4A of (r.c positive in n.c rec)` | | Ligand atoms within 3 Å of catalytic triad residues HIS, ASP, SER | `(n.t a in n.c lig) w 3A of ("HIS *" or "ASP *" or "SER *")` | | Pocket atoms defined by residues 30-50 in chain "A" | `n.t a in (r.id 30:50 in c.n "A")` | | Residues within 5 Å of ligand with pI < 6 (acidic environment) | `(n.t r w 5A of n.c lig) and (r.pI < 6.0)` | | Atoms in ligand within 2 Å of receptor atoms (tight contacts) | `(n.t a in n.c lig) w 2A of n.c rec` | | Side chains within 6 Å of ligand, excluding Gly/Ala side chains | `(n.t sc w 6A of n.c lig) and not (n.t sc in r.t GLY, ALA)` | | Receptor atoms with occupancy > 0.9 near ligand (=4 Å) | `((n.t a in n.c rec) and (a.oc > 0.9)) w 4A of n.c lig` | | Residues in receptor with =4 nitrogens within 6 Å of ligand | `((n.t r in n.c rec) and (r.nN 4)) w 6A of n.c lig` | | Ligand halogen atoms (F/Cl/Br) contacting receptor (=3 Å) | `(a.s F,Cl,Br in n.c lig) w 3A of n.c rec` | | Disulfide sulfur atoms (S-S) within 5 Å of ligand | `((a.s S in r.t CYS) l (a.s S in r.t CYS)) w 5A of n.c lig` | | Backbone atoms in helices that also contact ligand (=4 Å) | `(n.t a in (n.t bb in r.ss a)) w 4A of n.c lig` | | Receptor residues with at least one sulfur atom within 5 Å of ligand | `((n.t r in n.c rec) and (n.t r having a.s S)) w 5A of n.c lig` | | sp2 atoms within 3 Å of ligand | `a.hy sp2 w 3A of n.c lig` | | Acidic residues near metal ions (=3 Å) | `r.p acidic w 3A of (a.transitionMetal or a.alkaliMetal)` | | Atoms with x >= 2y within 4 Å of ligand (geometry filter) | `(a.x >= 2*a.y) and (n.t a w 4A of n.c lig)` | | Residues 50-80 in chain "B" contacting ligand (=4 Å) | `(r.id 50:80 in c.n "B") w 4A of n.c lig` | | Binding-site atoms in receptor with vdw radius 1.4-1.8 Å | `(a.vdwr 1.4A:1.8A in n.c rec) w 5A of n.c lig` | | Non-receptor residues (small peptides/ligands) =3 Å from ions | `(n.t r out of n.c rec) w 3A of n.c ion` | | Glycan atoms contacting receptor (=4 Å) | `(n.t a in n.c gly) w 4A of n.c rec` | | Aromatic residues near ligand (=5 Å) but >3 Å from any water | `(r.t PHE,TYR,TRP,HIS w 5A of n.c lig) and (n.t r b 3A of n.c wat)` | | Positive residues within 5 Å of acidic residues (protein interior networks) | `r.c positive w 5A of r.p acidic` | | Atoms with alternate locations A or B near ligand (=3 Å) | `a.alt A,B w 3A of n.c lig` | | Receptor atoms with low occupancy (< 0.3) near ligand (=4 Å) | `((n.t a in n.c rec) and (a.oc < 0.3)) w 4A of n.c lig` | | Side chains in chain "A" within 5 Å of glycans | `(n.t sc in c.n "A") w 5A of n.c gly` | | Ligand-adjacent residues not contacting metals (>3 Å from metals) | `(n.t r w 5A of n.c lig) and (n.t r b 3A of (a.transitionMetal or a.alkaliMetal))` | | Nitrogen sp2 atoms within 3 Å of ligand | `(a.s N and a.hy sp2) w 3A of n.c lig` | | Atoms from residues 25,30,35 near ligand (=4 Å) | `(n.t a in r.id 25,30,35) w 4A of n.c lig` | | Non-hydrogen receptor atoms in chain "A" contacting ligand (=4 Å) | `(n.t a in c.n "A") and (n.t a in n.c rec) and not a.s H and (n.t a w 4A of n.c lig)` | | Backbone alpha carbons (CA) in terminal residues near ligand (=5 Å) | `"CA" in r.ter w 5A of n.c lig` | | Side chains with sulfur within 3 Å of ligand (Cys/Met contacts) | `(n.t sc having a.s S) w 3A of n.c lig` | | Residues in loops contacting ligand (=6 Å) | `(r.ss l) w 6A of n.c lig` | | Ligand atoms within 2 Å of receptor O/N polar atoms | `(n.t a in n.c lig) w 2A of (a.s O,N in n.c rec)` | | Salt-bridge candidates bridging ligand and receptor: positive receptor residues within 4 Å of ligand and also within 4 Å of negative receptor residues | `((r.c positive in n.c rec) and (n.t r w 4A of n.c lig)) and (n.t r w 4A of (r.c negative in n.c rec))` | | Steric clashes: ligand heavy atoms within 2.2 Å of receptor heavy atoms | `((n.t a in n.c lig) and not a.s H) w 2.2A of ((n.t a in n.c rec) and not a.s H)` | | Bridging waters between chains "A" and "B": water =3.2 Å from both chains | `(n.c wat w 3.2A of c.n "A") and (n.c wat w 3.2A of c.n "B")` | | Side chains with =2 nitrogens inside 4 Å of ligand (chemistry hotspots) | `(sc.nN 2) w 4A of n.c lig` | | Binding site aromatics excluding histidine (=5 Å of ligand) | `r.t PHE,TYR,TRP w 5A of n.c lig` | | Ligand atoms near positive receptor residues (=3 Å) | `(n.t a in n.c lig) w 3A of (r.c positive in n.c rec)` | | High-B receptor atoms near ligand: a.tf > 20 within 6 Å | `((a.tf > 20) in n.c rec) w 6A of n.c lig` | | Alpha carbons of receptor residues contacting ligand (=5 Å) | `"CA" in ((n.t r in n.c rec) w 5A of n.c lig)` | | Protein-lipid contact atoms from chain "A" (=4 Å) | `(n.t a in c.n "A") w 4A of n.c lip` | | Loop residues near ligand (=5 Å) with pI < 6 | `((r.ss l) and (r.pI < 6.0)) w 5A of n.c lig` | | Halogenated ligand contacts not wetted: Cl/Br/I within 3 Å of receptor and >3 Å from any water oxygen | `((a.s Cl,Br,I in n.c lig) w 3A of n.c rec) and (n.t a b 3A of (a.s O in n.c wat))` | | Side chains containing sulfur within 3.5 Å of ligand | `((n.t sc having a.s S) w 3.5A of n.c lig)` | | Chain "B" residues with IDs 12-16 contacting glycans (=5 Å) | `(r.id 12:16 in c.n "B") w 5A of n.c gly` | | Ligand atoms within 2.5 Å of aromatic residues (p interactions) | `(n.t a in n.c lig) w 2.5A of r.t PHE,TYR,TRP,HIS` | | Polar receptor hydrogens within 2.2 Å of ligand | `(a.hp in n.c rec) w 2.2A of n.c lig` | | Alternate-location A receptor atoms contacting ligand (=3 Å) | `(a.alt A in n.c rec) w 3A of n.c lig` | | Receptor residues having an atom with exactly two bonded oxygens within 4 Å of ligand | `((n.t r in n.c rec) having a.nbo 2) and (n.t r w 4A of n.c lig)` | | Positive receptor residues near DNA residues (=6 Å) | `(r.c positive in n.c rec) w 6A of r.dna` | | sp3 carbon atoms of ligand within 3 Å of receptor | `((a.s C and a.hy sp3) in n.c lig) w 3A of n.c rec` | | Pocket rim residues: within 12 Å but beyond 7 Å from ligand | `(n.t r w 12A of n.c lig) and (n.t r b 7A of n.c lig)` | | Backbone atoms contacting ligand (=4 Å) | `a.aabb w 4A of n.c lig` | | Binding-site residues that are not glycosylation (=5 Å of ligand, excluding glycans) | `((n.t r in n.c rec) w 5A of n.c lig) and (n.t r out of n.c gly)` | | Non-water atoms within 5 Å of ligand | `((n.t a out of n.c wat) w 5A of n.c lig) and (n.t a out of n.c lig)` | | Ligand atoms near backbone nitrogens (=3 Å) | `(n.t a in n.c lig) w 3A of (a.s N in n.t bb)` | | Aromatic-bearing receptor residues near ligand (=4 Å) | `((n.t r having a.ar) in n.c rec) w 4A of n.c lig` | | Protein-protein interface residues between chains "A" and "B" (=4 Å) | `(n.t r in n.c rec) and (((n.t r in c.n "A") w 4A of (n.t r in c.n "B")) or ((n.t r in c.n "B") w 4A of (n.t r in c.n "A")))` | | Potential metal-binding triads: residues with at least one N within 2.5 Å of transition metals | `(n.t r having a.s N) and (n.t r w 2.5A of a.transitionMetal)` | | Ligand atoms near nucleic-acid backbones (=4 Å) | `(n.t a in n.c lig) w 4A of a.nabb` | | Hydrophobic shell: receptor residues with nonpolar side chains =5 Å from ligand | `(r.p nonpolar in n.c rec) w 5A of n.c lig` | | Removable waters: water =2.2 Å from ligand heavy atoms | `n.c wat w 2.2A of ((n.t a in n.c lig) and not a.s H)` | | High-electronegativity receptor atoms (>3.0) within 3 Å of ligand | `(a.en > 3 in n.c rec) w 3A of n.c lig` | | Positive receptor residues near ligand phosphate atoms (=4 Å) | `(r.c positive in n.c rec) w 4A of (a.s P,O in n.c lig)` | | Residues lining a named pocket group "Pocket" (=4 Å) | `n.t r w 4A of (n.t a in "Pocket")` | | Glycan atoms contacting receptor (=3 Å) but not ligand (>3 Å) | `((n.t a in n.c gly) w 3A of n.c rec) and (n.t a b 3A of n.c lig)` | | Chain "A" receptor atoms near ligand (=4 Å) with occupancy < 0.5 | `((a.oc < 0.5 in n.c rec) in c.n "A") w 4A of n.c lig` | | Chain "B" amino-acid residues near ligand (=5 Å) excluding cysteines | `((r.aa and not r.t CYS) in c.n "B") w 5A of n.c lig` | | Atoms with exactly three bonded hydrogens within 2.5 Å of ligand | `a.nbh 3 w 2.5A of n.c lig` | | Receptor residues having a polar hydrogen within 2 Å of ligand | `(n.t r in n.c rec) having (a.hp w 2A of n.c lig)` | | Ligand atoms within 3 Å of backbone carbonyl oxygens | `(n.t a in n.c lig) w 3A of (a.aabb and a.s O)` | | Non-standard residues near ligand (=6 Å) | `r.nsrn w 6A of n.c lig` | | Nucleic-acid atoms contacting ligand (=4 Å) | `(n.t a in r.na) w 4A of n.c lig` | | Ion atoms contacting receptor (=3 Å) | `(n.t a in n.c ion) w 3A of n.c rec` | | Positive receptor residues near ligand (=4 Å) but far from water (>5 Å) | `((r.c positive in n.c rec) w 4A of n.c lig) and (n.t r b 5A of n.c wat)` | | Alpha carbons from residues 1-10 and 40-50 within 6 Å of ligand | `("CA" in r.id 1:10,40:50) w 6A of n.c lig` | | Receptor atoms with vdw radius 1.6-1.9 Å within 3.5 Å of ligand | `((a.vdwr 1.6A:1.9A) in n.c rec) w 3.5A of n.c lig` | | Beta-strand residues near ligand (=5 Å) with at least one oxygen | `(r.ss b having a.s O) w 5A of n.c lig` | | Ligand atoms not contacting the receptor (>6 Å from any receptor atom) | `(n.t a in n.c lig) b 6A of n.c rec` | | Receptor atoms near ligand (=4 Å) excluding chain "C" | `(n.t a in n.c rec w 4A of n.c lig) and (n.t a out of c.n "C")` | | Non-terminal, nonpolar receptor residues within 4 Å of ligand (stabilizing shell) | `((r.p nonpolar and not r.ter) in n.c rec) w 4A of n.c lig` | | Chain "A"-"B" interface atoms that are sp2 hybridized (=4 Å across chains) | `(((n.t a in c.n "A") w 4A of c.n "B") or ((n.t a in c.n "B") w 4A of c.n "A")) and (a.hy sp2)` | ## Related pages - [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) # File attributes This reference page summarizes the `file` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). File attributes are defined in the `file` attribute space (short name: `fi`), that matches only file nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | ------------------------------- | ---------- | ----------------- | ------------------------------- | | [name](#name) | `n` | strings in quotes | `fi.n "A"` `fi.n "L*"` | | [selected](#selected) | | `true`, `false` | `fi.selected` `not fi.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `fi.sf false` `fi.sf` | ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). # Folder attributes This reference page summarizes the `folder` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Folder attributes are defined in the `folder` attribute space (short name: `f`), that matches only folder nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------- | ---------- | ----------------- | ------------------------------ | | [hasMaterial](#hasmaterial) | `hm` | `true`, `false` | `f.hm` `not fo.hm` | | [hidden](#hidden) | `h` | `true`, `false` | `f.h` `not fo.h` | | [name](#name) | `n` | strings in quotes | `f.n "A"` `f.n "L*"` | | [ownsMaterial](#ownsmaterial) | `om` | `true`, `false` | `f.om` | | [selected](#selected) | | `true`, `false` | `f.selected` `not fo.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `f.sf false` `f.sf` | | [visibilityFlag](#visibilityflag) | `vf` | `true`, `false` | `f.vf false` `f.vf` | | [visible](#visible) | `v` | `true`, `false` | `f.v` `not fo.v` | Attributes specific to the `folder` attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------------------------------- | ---------- | --------------- | -------------------------------- | | [formalCharge](#formalcharge) | `fc` | integers | `f.fc > 1` `f.fc 6:8` | | [numberOfAtoms](#numberofatoms) | `nat` | integers | `f.nat < 1000` `f.nat 100:200` | | [numberOfCarbons](#numberofcarbons) | `nC` | integers | `f.nC < 10` `f.nC 10:20` | | [numberOfChains](#numberofchains) | `nc` | integers | `f.nc < 3` `f.nc 2:4` | | [numberOfCoarseGrainedAtoms](#numberofcoarsegrainedatoms) | `ncga` | integers | `f.ncga < 1000` `f.ncga 100:200` | | [numberOfHydrogens](#numberofhydrogens) | `nH` | integers | `f.nH < 10` `f.nH 10:20` | | [numberOfMolecules](#numberofmolecules) | `nm` | integers | `f.nm < 3` `f.nm 2:4` | | [numberOfNitrogens](#numberofnitrogens) | `nN` | integers | `f.nN < 10` `f.nN 10:20` | | [numberOfOxygens](#numberofoxygens) | `nO` | integers | `f.nO < 10` `f.nO 10:20` | | [numberOfResidues](#numberofresidues) | `nr` | integers | `f.nr > 130` `f.nr 100:130` | | [numberOfSegments](#numberofsegments) | `ns` | integers | `f.ns < 3` `f.ns 1:3` | | [numberOfStructuralGroups](#numberofstructuralgroups) | `nsg` | integers | `f.nsg > 10` `f.nsg 10:13` | | [numberOfStructuralModels](#numberofstructuralmodels) | `nsm` | integers | `f.nsm > 4` `f.nsm 2:4` | | [numberOfSulfurs](#numberofsulfurs) | `nS` | integers | `f.nS < 10` `f.nS 10:20` | | [partialCharge](#partialcharge) | `pc` | floats | `f.pc > 1.5` `f.pc 1.5:2.0` | ## formalCharge The `folder.formalCharge` attribute (short name: `f.fc`) matches folders with structures having specific total formal charge. Possible values: integers. Examples: - `folder.fc 1` (short version: `f.fc 1`): matches folders with structures having formal charge equal to 1 - `folder.fc 6:8` (short version: `f.fc 6:8`): matches folders with structures having formal charge between 6 and 8 ## hasMaterial Inherited from [node.hasMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#hasmaterial). ## hidden Inherited from [node.hidden](https://documentation.samson-connect.net/users/latest/nsl/node/#hidden). ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## numberOfAtoms The `folder.numberOfAtoms` attribute (short name: `f.nat`) matches folders with specific number of atoms. Possible values: integers. Examples: - `folder.nat > 100` (short version: `f.nat > 100`): matches folders with the number of atoms more than 100 - `folder.nat 100:200` (short version: `f.nat 100:200`): matches folders with the number of atoms between 100 and 200 ## numberOfCarbons The `folder.numberOfCarbons` attribute (short name: `f.nC`) matches folders with specific number of **Carbon atoms**. It works in the similar way as the [numberOfAtoms](#numberofatoms) attribute. ## numberOfChains The `folder.numberOfChains` attribute (short name: `f.nc`) matches folders with specific number of chains. Possible values: integers. Examples: - `folder.numberOfChains < 3` (short version: `f.nc < 3`): matches folders with the number of chains less than 3 - `folder.numberOfChains 2:4` (short version: `f.nc 2:4`): matches folders with the number of chains between 2 and 4 ## numberOfCoarseGrainedAtoms The `folder.numberOfCoarseGrainedAtoms` attribute (short name: `f.ncga`) matches folders with specific number of **coarse-grained atoms**. It works in the similar way as the [numberOfAtoms](#numberofatoms) attribute. ## numberOfHydrogens The `folder.numberOfHydrogens` attribute (short name: `f.nH`) matches folders with specific number of **Hydrogen atoms**. It works in the similar way as the [numberOfAtoms](#numberofatoms) attribute. ## numberOfMolecules The `folder.numberOfMolecules` attribute (short name: `f.nm`) matches folders with specific number of molecules. Possible values: integers. Examples: - `folder.numberOfMolecules < 3` (short version: `f.nm < 3`): matches folders with the number of molecules less than 3 - `folder.numberOfMolecules 2:4` (short version: `f.nm 2:4`): matches folders with the number of molecules between 2 and 4 ## numberOfNitrogens The `folder.numberOfNitrogens` attribute (short name: `f.nN`) matches folders with specific number of **Nitrogen atoms**. It works in the similar way as the [numberOfAtoms](#numberofatoms) attribute. ## numberOfOxygens The `folder.numberOfOxygens` attribute (short name: `f.nO`) matches folders with specific number of **Oxygen atoms**. It works in the similar way as the [numberOfAtoms](#numberofatoms) attribute. ## numberOfResidues The `folder.numberOfResidues` attribute (short name: `f.nr`) matches folders with specific number of residues. Possible values: integers. Examples: - `folder.numberOfResidues > 100` (short version: `f.nr > 100`): matches folders with the number of residues greater than 100 - `folder.numberOfResidues 100:120` (short version: `f.nr 100:120`): matches folders with the number of residues between 100 and 120 ## numberOfSegments The `folder.numberOfSegments` attribute (short name: `f.ns`) matches folders with specific number of segments. Possible values: integers. Examples: - `folder.numberOfSegments > 2` (short version: `f.ns > 2`): matches folders with the number of segments greater than 2 - `folder.numberOfSegments 2:4` (short version: `f.ns 2:4`): matches folders with the number of segments between 2 and 4 ## numberOfStructuralGroups The `folder.numberOfStructuralGroups` attribute (short name: `f.nsg`) matches folders with specific number of structural groups. Possible values: integers. Examples: - `folder.numberOfStructuralGroups > 10` (short version: `f.nsg > 10`): matches folders with the number of structural groups greater than 10 - `folder.numberOfStructuralGroups 10:12` (short version: `f.nsg 10:12`): matches folders with the number of structural groups between 10 and 12 ## numberOfStructuralModels The `folder.numberOfStructuralModels` attribute (short name: `f.nsm`) matches folders with specific number of structural models. Possible values: integers. Examples: - `folder.numberOfStructuralModels > 4` (short version: `f.nsm > 4`): matches folders with the number of structural models greater than 4 - `folder.numberOfStructuralModels 2:4` (short version: `f.nsm 2:4`): matches folders with the number of structural models between 2 and 4 ## numberOfSulfurs The `folder.numberOfSulfurs` attribute (short name: `f.nS`) matches folders with specific number of **Sulfur atoms**. It works in the similar way as the [numberOfAtoms](#numberofatoms) attribute. ## ownsMaterial Inherited from [node.ownsMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#ownsmaterial). ## partialCharge The `folder.partialCharge` attribute (short name: `f.pc`) matches folders with structures having specific total partial charge. Possible values: real. Examples: - `folder.pc 1` (short version: `f.pc 1`): matches folders with structures having partial charge equal to 1 - `folder.pc 1.5:2.0` (short version: `f.pc 1.5:2.0`): matches folders with structures having partial charge between 1.5 and 2.0 ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). ## visibilityFlag Inherited from [node.visibilityFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#visibilityflag). ## visible Inherited from [node.visible](https://documentation.samson-connect.net/users/latest/nsl/node/#visible). ## Related pages - [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) - [Node attributes](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) - [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md) # Label attributes This reference page summarizes the `label` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Label attributes are defined in the `label` attribute space (short name: `la`), that matches only label nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------- | ---------- | ----------------- | ------------------------------- | | [hidden](#hidden) | `h` | `true`, `false` | `la.h` `not la.h` | | [name](#name) | `n` | strings in quotes | `la.n "A"` `la.n "L*"` | | [selected](#selected) | | `true`, `false` | `la.selected` `not la.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `la.sf false` `la.sf` | | [visibilityFlag](#visibilityflag) | `vf` | `true`, `false` | `la.vf false` `la.vf` | | [visible](#visible) | `v` | `true`, `false` | `la.v` `not la.v` | ## hidden Inherited from [node.hidden](https://documentation.samson-connect.net/users/latest/nsl/node/#hidden). ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). ## visibilityFlag Inherited from [node.visibilityFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#visibilityflag). ## visible Inherited from [node.visible](https://documentation.samson-connect.net/users/latest/nsl/node/#visible). # Light attributes This reference page summarizes the `light` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Light attributes are defined in the `light` attribute space (short name: `li`), that matches only light nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------- | ---------- | ----------------- | ------------------------------- | | [hidden](#hidden) | `h` | `true`, `false` | `li.h` `not li.h` | | [name](#name) | `n` | strings in quotes | `li.n "A"` `li.n "L*"` | | [selected](#selected) | | `true`, `false` | `li.selected` `not li.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `li.sf false` `li.sf` | | [visibilityFlag](#visibilityflag) | `vf` | `true`, `false` | `li.vf false` `li.vf` | | [visible](#visible) | `v` | `true`, `false` | `li.v` `not li.v` | ## hidden Inherited from [node.hidden](https://documentation.samson-connect.net/users/latest/nsl/node/#hidden). ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). ## visibilityFlag Inherited from [node.visibilityFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#visibilityflag). ## visible Inherited from [node.visible](https://documentation.samson-connect.net/users/latest/nsl/node/#visible). # Mesh attributes This reference page summarizes the `mesh` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Mesh attributes are defined in the `mesh` attribute space (short name: `me`), that matches only mesh nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------- | ---------- | ----------------- | ------------------------------- | | [hasMaterial](#hasmaterial) | `hm` | `true`, `false` | `me.hm` `not me.hm` | | [hidden](#hidden) | `h` | `true`, `false` | `me.h` `not me.h` | | [name](#name) | `n` | strings in quotes | `me.n "A"` `me.n "L*"` | | [ownsMaterial](#ownsmaterial) | `om` | `true`, `false` | `me.om` | | [selected](#selected) | | `true`, `false` | `me.selected` `not me.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `me.sf false` `me.sf` | | [visibilityFlag](#visibilityflag) | `vf` | `true`, `false` | `me.vf false` `me.vf` | | [visible](#visible) | `v` | `true`, `false` | `me.v` `not me.v` | ## hasMaterial Inherited from [node.hasMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#hasmaterial). ## hidden Inherited from [node.hidden](https://documentation.samson-connect.net/users/latest/nsl/node/#hidden). ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## ownsMaterial Inherited from [node.ownsMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#ownsmaterial). ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). ## visibilityFlag Inherited from [node.visibilityFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#visibilityflag). ## visible Inherited from [node.visible](https://documentation.samson-connect.net/users/latest/nsl/node/#visible). # Molecule attributes This reference page summarizes the `molecule` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Molecule attributes are defined in the `molecule` attribute space (short name: `mol`), that matches only molecule nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------- | ---------- | ----------------- | --------------------------------- | | [hasMaterial](#hasmaterial) | `hm` | `true`, `false` | `mol.hm` `not mol.hm` | | [hidden](#hidden) | `h` | `true`, `false` | `mol.h` `not mol.h` | | [name](#name) | `n` | strings in quotes | `mol.n "A"` `mol.n "L*"` | | [ownsMaterial](#ownsmaterial) | `om` | `true`, `false` | `mol.om` | | [selected](#selected) | | `true`, `false` | `mol.selected` `not mol.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `mol.sf false` `mol.sf` | | [visibilityFlag](#visibilityflag) | `vf` | `true`, `false` | `mol.vf false` `mol.vf` | | [visible](#visible) | `v` | `true`, `false` | `mol.v` `not mol.v` | Attributes inherited from the [structuralGroup](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------------------------------- | ---------- | --------------- | ------------------------------------ | | [formalCharge](#formalcharge) | `fc` | integers | `mol.fc > 1` `mol.fc 6:8` | | [numberOfAtoms](#numberofatoms) | `nat` | integers | `mol.nat < 1000` `mol.nat 100:200` | | [numberOfCarbons](#numberofcarbons) | `nC` | integers | `mol.nC < 10` `mol.nC 10:20` | | [numberOfHydrogens](#numberofhydrogens) | `nH` | integers | `mol.nH < 10` `mol.nH 10:20` | | [numberOfNitrogens](#numberofnitrogens) | `nN` | integers | `mol.nN < 10` `mol.nN 10:20` | | [numberOfOxygens](#numberofoxygens) | `nO` | integers | `mol.nO < 10` `mol.nO 10:20` | | [numberOfSulfurs](#numberofsulfurs) | `nS` | integers | `mol.nS < 10` `mol.nS 10:20` | | [numberOfCoarseGrainedAtoms](#numberofcoarsegrainedatoms) | `ncga` | integers | `mol.ncga < 1000` `mol.ncga 100:200` | | [partialCharge](#partialcharge) | `pc` | floats | `mol.pc > 1.5` `mol.pc 1.5:2.0` | Attributes specific to the `molecule` attribute space: | Attribute name | Short name | Possible values | Examples | | ----------------------------------------------------- | ---------- | --------------- | ------------------------------- | | [numberOfChains](#numberofchains) | `nc` | integers | `mol.nc < 3` `mol.nc 2:4` | | [numberOfResidues](#numberofresidues) | `nr` | integers | `mol.nr > 130` `mol.nr 100:130` | | [numberOfSegments](#numberofsegments) | `ns` | integers | `mol.ns < 3` `mol.ns 1:3` | | [numberOfStructuralGroups](#numberofstructuralgroups) | `nsg` | integers | `mol.nsg > 10` `mol.nsg 10:13` | ## formalCharge Inherited from [structuralGroup.formalCharge](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#formalcharge). ## hasMaterial Inherited from [node.hasMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#hasmaterial). ## hidden Inherited from [node.hidden](https://documentation.samson-connect.net/users/latest/nsl/node/#hidden). ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## numberOfAtoms Inherited from [structuralGroup.numberOfAtoms](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofatoms). ## numberOfCarbons Inherited from [structuralGroup.numberOfCarbons](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofcarbons). ## numberOfChains The `molecule.numberOfChains` attribute (short name: `mol.nc`) matches molecules with specific number of chains. Possible values: integers. Examples: - `molecule.numberOfChains < 3` (short version: `mol.nc < 3`): matches molecules with the number of chains less than 3 - `molecule.numberOfChains 2:4` (short version: `mol.nc 2:4`): matches molecules with the number of chains between 2 and 4 ## numberOfCoarseGrainedAtoms Inherited from [structuralGroup.numberOfCoarseGrainedAtoms](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofcoarsegrainedatoms). ## numberOfHydrogens Inherited from [structuralGroup.numberOfHydrogens](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofhydrogens). ## numberOfNitrogens Inherited from [structuralGroup.numberOfNitrogens](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofnitrogens). ## numberOfOxygens Inherited from [structuralGroup.numberOfOxygens](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofoxygens). ## numberOfResidues The `molecule.numberOfResidues` attribute (short name: `mol.nr`) matches molecules with specific number of residues. Possible values: integers. Examples: - `molecule.numberOfResidues > 100` (short version: `mol.nr > 100`): matches molecules with the number of residues greater than 100 - `molecule.numberOfResidues 100:120` (short version: `mol.nr 100:120`): matches molecules with the number of residues between 100 and 120 ## numberOfSegments The `molecule.numberOfSegments` attribute (short name: `mol.ns`) matches molecules with specific number of segments. Possible values: integers. Examples: - `molecule.numberOfSegments > 2` (short version: `mol.ns > 2`): matches molecules with the number of segments greater than 2 - `molecule.numberOfSegments 2:4` (short version: `mol.ns 2:4`): matches molecules with the number of segments between 2 and 4 ## numberOfStructuralGroups The `molecule.numberOfStructuralGroups` attribute (short name: `mol.nsg`) matches molecules with specific number of structural groups. Possible values: integers. Examples: - `molecule.numberOfStructuralGroups > 10` (short version: `mol.nsg > 10`): matches molecules with the number of structural groups greater than 10 - `molecule.numberOfStructuralGroups 10:12` (short version: `mol.nsg 10:12`): matches molecules with the number of structural groups between 10 and 12 ## numberOfSulfurs Inherited from [structuralGroup.numberOfSulfurs](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofsulfurs). ## ownsMaterial Inherited from [node.ownsMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#ownsmaterial). ## partialCharge Inherited from [structuralGroup.partialCharge](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#partialcharge). ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). ## visibilityFlag Inherited from [node.visibilityFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#visibilityflag). ## visible Inherited from [node.visible](https://documentation.samson-connect.net/users/latest/nsl/node/#visible). ## Related pages - [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) - [Node attributes](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) - [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md) # Node attributes This reference page summarizes the `node` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). ## What this reference covers This reference page explains the core node-level attributes in NSL that apply across many node types and are especially useful for hierarchy, identity, and state queries. ## List of node attributes Node attributes, defined in the `node` attribute space (short name: `n`), correspond to attributes defined in each node of the data graph or to other properties of nodes. For example, the [selection flag](#selectionflag) is a node attribute, since each node has a [selection flag](#selectionflag). Hence, the NSL expression `node.selectionFlag true` may match any node whose selection flag is true, regardless of its node type (atom, bond, etc.). The following node attributes are available in NSL: | Attribute name | Short name | Possible values | Examples | | --------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------ | ------------------------ | | [category](#category) | `c` | See [Structure categories](#structure-categories), [Visual model categories](#visual-model-categories) | `n.c lig` `n.c lip, gly` | | [hasMaterial](#hasmaterial) | `hm` | `true`, `false` | `n.hm` `not n.hm` | | [hidden](#hidden) | `h` | `true`, `false` | `n.h` `not n.h` | | [locked](#locked) | `l` | `true`, `false` | `n.l` `not n.l` | | [lockedFlag](#lockedflag) | `lf` | `true`, `false` | `n.lf true` | | [name](#name) | `n` | strings in quotes | `n.n "A"` `n.n "L*"` | | [ownsMaterial](#ownsmaterial) | `om` | `true`, `false` | `n.om` | | [selected](#selected) | `s` | `true`, `false` | `n.s` `not n.s` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `n.sf false` `n.sf` | | [type](#type) | `t` | See node [type](#type) | `n.t a` | | [visibilityFlag](#visibilityflag) | `vf` | `true`, `false` | `n.vf false` `n.vf` | | [visible](#visible) | `v` | `true`, `false` | `n.v` `not n.v` | ## category SAMSON's NSL supports the following node categories that might describe categories of nodes and groups of nodes: - [Structure categories](#structure-categories) - [Visual model categories](#visual-model-categories) ### Structure categories The following structure categories are available: | Attribute name | Short name | | ------------------------------------------------------------------ | ---------- | | [crystallizationBufferAgent](#crystallization-buffer-agent) | `cba` | | [glycan](#glycan) | `gly` | | [heavyAtomsWithLinkingBonds](#heavy-atoms-with-bonds-between-them) | `hawlb` | | [hydrogensWithBonds](#hydrogens-with-bonds) | `hwb` | | [ion](#ion) | `ion` | | [monatomicIon](#monatomic-ion) | `mIon` | | [polyatomicIon](#polyatomic-ion) | `pIon` | | [ligand](#ligand) | `lig` | | [lipid](#lipid) | `lip` | | [dna](#dna) | | | [rna](#rna) | | | [receptor](#receptor) | `rec` | | [water](#water) | `wat` | #### Crystallization buffer agent The `crystallizationBufferAgent` attribute (short name: `cba`) matches crystallization buffer agent structural groups based on their names. Examples: - `node.category crystallizationBufferAgent` (short version: `n.c cba`): matches crystallization buffer agents - `node.type atom in node.category crystallizationBufferAgent` (short version: `n.t a in n.c cba`): matches atoms in crystallization buffer agents #### Glycan The `glycan` attribute (short name: `gly`) matches glycan structural groups based on their names. Examples: - `node.category glycan` (short version: `n.c gly`): matches glycans - `node.type atom in node.category glycan` (short version: `n.t a in n.c gly`): matches atoms in glycans #### Heavy atoms with bonds between them The `heavyAtomsWithLinkingBonds` attribute (short name: `hawlb`) matches heavy atoms (non-hydrogen atoms) with bonds between them. Examples: - `node.category heavyAtomsWithLinkingBonds` (short version: `n.c hawlb`): matches heavy atoms (non-hydrogen atoms) with bonds between them - `node.category heavyAtomsWithLinkingBonds in node.category ligand` (short version: `n.c hawlb in n.c lig`): matches heavy atoms with bonds between them in ligands #### Hydrogens with bonds The `hydrogensWithBonds` attribute (short name: `hwb`) matches hydrogens with bonds to them. Examples: - `node.category hydrogensWithBonds` (short version: `n.c hwb`): matches hydrogens with bonds to them - `node.category hydrogensWithBonds in node.category ligand` (short version: `n.c hwb in n.c lig`): matches hydrogens with bonds to them in ligands #### Ion The `ion` attribute matches ions based on their names. Examples: - `node.category ion`: matches ions based on their names #### Monatomic ion The `monatomicIon` attribute (short name: `mIon`) matches monatomic ions. Examples: - `node.category monatomicIon` (short version: `n.c mIon`): matches monatomic ions #### Polyatomic ion The `polyatomicIon` attribute (short name: `pIon`) matches polyatomic ions based on their valence. Examples: - `node.category polyatomicIon` (short version: `n.c pIon`): matches polyatomic ions based on their valence #### Ligand The `ligand` attribute (short name: `lig`) matches ligands based on their structure. Examples: - `node.category ligand` (short version: `n.c lig`): matches ligands - `atom.symbol N in node.category ligand` (short version: `a.s N in n.c lig`): matches nitrogens in ligands #### Lipid The `lipid` attribute (short name: `lip`) matches lipid structural groups based on their names. Examples: - `node.category lipid` (short version: `n.c lip`): matches lipids - `atom.symbol C in node.category lipid` (short version: `a.s C in n.c lip`): matches carbons in lipids #### Receptor The `receptor` attribute (short name: `rec`, alias: `protein`) matches receptors. Examples: - `node.category receptor` (short version: `n.c rec`): matches receptors - `"CA" in node.category receptor` (short version: `"CA" in n.c rec`): matches "CA" nodes (e.g., alpha carbons) in receptors #### DNA The `dna` attribute matches DNA residues. #### RNA The `rna` attribute matches RNA residues. #### Water The `water` attribute (alias: `solvent`, short names: `wat`, `sol`) matches water structures. Examples: - `node.category water` (short version: `n.c wat`): matches water structures - `atom.symbol O in node.category water` (short version: `a.s O in n.c wat`): matches oxygens in water structures ### Visual model categories The following visual models categories are available: | Attribute name | Short name | Matches... | | -------------------------- | ---------- | ----------------------------------------------- | | `ballAndStick` | `bas` | ball-and-stick visual models | | `licorice` | `lic` | licorice visual models | | `vanDerWaals` | `vdw` | van der Waals visual models | | `cartoon` | `car` | cartoon style secondary structure visual models | | `ribbon` | `rib` | ribbon style secondary structure visual models | | `tube` | `tub` | tube style secondary structure visual models | | `gaussianSurface` | `gau` | gaussian surface visual models | | `solventAccessibleSurface` | `sas` | solvent accessible surface (SAS) visual models | | `solventExcludedSurface` | `ses` | solvent excluded surface (SES) visual models | | `surface` | `sur` | surface visual models | You can use them to select the corresponding types of visual models. Examples: - `node.category vanDerWaals` (short version: `n.c vdw`): matches van der Waals visual models - `node.category licorice, ribbon` (short version: `n.c lic, rib`): matches licorice and ribbon visual models ## hasMaterial The `node.hasMaterial` attribute (short name: `n.hm`) matches nodes that have a material, either because they own it (i.e. the material is applied to them) or because they inherit it (i.e. a material is applied to one of their ascendants). Possible values: `true`, `false`. Examples: - `node.hasMaterial` (short version: `n.hm`): matches nodes which have a material ## hidden The `node.hidden` attribute (short name: `n.h`) matches nodes that are hidden, either because their [visibility flag](#visibilityflag) is `false`, or because the [visibility flag](#visibilityflag) of one of their ancestors is `false`. Possible values: `true`, `false`. Examples: - `node.hidden` (short version: `n.h`): matches hidden nodes ## locked The `node.locked` attribute (short name: `n.l`) matches nodes that are locked, either because their locked flag is `true`, or because the locked flag of one of their ancestors is `true`. Possible values: `true`, `false`. Examples: - `node.locked` (short version: `n.l`): matches locked nodes ## lockedFlag The `node.lockedFlag` attribute (short name: `n.lf`) matches nodes based on their locked flag. Possible values: `true` or `false`. Examples: - `node.lockedFlag true` (short version: `n.lf true`): matches nodes with a locked flag set to `true` ## name The `node.name` attribute (short name: `n.n`) matches nodes based on their names. Possible values: names, you can use wildcard character (`*`). Examples: - `node.name "A"` (short version: `n.n "A"`): matches nodes with their names equal to `A` - `node.name "L*"` (short version: `n.n "L*"`): matches nodes with their names starting with `L` ## ownsMaterial The `node.ownsMaterial` attribute (short name: `n.om`) matches nodes that own a material (i.e. the material is applied to them). Possible values: `true`, `false`. Examples: - `node.ownsMaterial` (short version: `n.om`): matches nodes which own a material ## selected The `node.selected` attribute (short name: `n.s`) matches nodes that are selected, either because their [selection flag](#selectionflag) is `true`, or because the [selection flag](#selectionflag) of one of their ancestors is `true`. Possible values: `true`, `false`. Examples: - `node.selected` (short version: `n.s`): matches selected nodes ## selectionFlag The `node.selectionFlag` attribute (short name: `n.sf`) matches nodes based on their selection flag. Possible values: `true` or `false`. Examples: - `node.selectionFlag true` (short version: `n.sf true`): matches nodes with the selection flag set to `true` ## type The `node.type` attribute (short name: `n.t`) matches nodes by type. Possible values: - `animation` (short name: `an`) - `asset` (short name: `as`) - `atom` (short name: `a`) - `backbone` (short name: `bb`) - `bond` (short name: `b`) - `camera` (short name: `ca`) - `chain` (short name: `c`) - `conformation` (short name: `co`) - `document` (short name: `d`) - `dynamicalModelParticleSystem` (short name: `dmps`) - `file` (short name: `fi`) - `folder` (short name: `f`) - `hydrogenBondGroup` (short name: `hbg`) - `interactionModelParticleSystem` (short name: `imps`) - `label` (short name: `la`) - `light` (short name: `li`) - `mesh` (short name: `me`) - `molecule` (short name: `m`) - `nodeGroup` (short name: `ng`) - `note` (short name: `nt`) - `path` (short name: `p`) - `presentation` (short name: `pr`) - `propertyModel` (short name: `pm`) - `renderPreset` (short name: `rp`) - `residue` (short name: `r`) - `segment` (short name: `s`) - `sideChain` (short name: `sc`) - `simulatorParticleSystem` (short name: `sps`) - `stateUpdaterParticleSystem` (short name: `sups`) - `structuralGroup` (short name: `sg`) - `structuralModel` (short name: `sm`) - `visualModel` (short name: `vm`) Examples: - `node.type atom` (short version: `n.t a`): matches atoms - `node.type sideChain` (short version: `n.t sc`): matches side chain nodes - `node.type visualModel, mesh` (short version: `n.t vm, mesh`): matches visual models and meshes - `node.type atom, bond` (short version: `n.t a, b`): matches atoms and bonds ## visibilityFlag The `node.visibilityFlag` attribute (short name: `n.vf`) matches nodes based on their [visibility flag](#visibilityflag). Possible values: `true` or `false`. Examples: - `node.visibilityFlag true` (short version: `n.vf true`): matches nodes with the [visibility flag](#visibilityflag) set to `true` ## visible The `node.visible` attribute (short name: `n.v`) matches nodes that are visible, i.e. the nodes whose [visibility flag](#visibilityflag) is `true` and whose ancestors are visible. Possible values: `true`, `false`. Examples: - `node.visible` (short version: `n.v`): selects all visible nodes ## Related pages - [Atom attributes](https://documentation.samson-connect.net/users/latest/nsl/atom/index.md) - [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md) # Node group attributes This reference page summarizes the `node group` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Node group attributes are defined in the `nodeGroup` attribute space (short name: `ng`), that matches only node group nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | ------------------------------- | ---------- | ----------------- | ------------------------------- | | [name](#name) | `n` | strings in quotes | `ng.n "A"` `ng.n "L*"` | | [selected](#selected) | | `true`, `false` | `ng.selected` `not ng.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `ng.sf false` `ng.sf` | ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). # Note attributes This reference page summarizes the `note` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Note attributes are defined in the `note` attribute space (short name: `nt`), that matches only note nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------- | ---------- | ----------------- | ------------------------------- | | [hidden](#hidden) | `h` | `true`, `false` | `nt.h` `not nt.h` | | [name](#name) | `n` | strings in quotes | `nt.n "A"` `nt.n "L*"` | | [selected](#selected) | | `true`, `false` | `nt.selected` `not nt.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `nt.sf false` `nt.sf` | | [visibilityFlag](#visibilityflag) | `vf` | `true`, `false` | `nt.vf false` `nt.vf` | | [visible](#visible) | `v` | `true`, `false` | `nt.v` `not nt.v` | ## hidden Inherited from [node.hidden](https://documentation.samson-connect.net/users/latest/nsl/node/#hidden). ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). ## visibilityFlag Inherited from [node.visibilityFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#visibilityflag). ## visible Inherited from [node.visible](https://documentation.samson-connect.net/users/latest/nsl/node/#visible). # Path attributes This reference page summarizes the `path` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Path attributes are defined in the `path` attribute space (short name: `p`), that matches only conformation nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | ------------------------------- | ---------- | ----------------- | ----------------------------- | | [name](#name) | `n` | strings in quotes | `p.n "A"` `p.n "L*"` | | [selected](#selected) | | `true`, `false` | `p.selected` `not p.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `p.sf false` `p.sf` | Attributes specific to the `path` attribute space: | Attribute name | Short name | Possible values | Examples | | ------------------------------- | ---------- | --------------- | --------------------------- | | [numberOfAtoms](#numberofatoms) | `nat` | integers | `p.nat > 100` `p.n 100:200` | ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## numberOfAtoms The `path.numberOfAtoms` attribute (short name: `p.nat`) matches paths with specific number of atoms. Possible values: integers. Examples: - `path.nat > 100` (short version: `p.nat > 100`): matches paths with the number of atoms more than 100 - `path.nat 100:200` (short version: `p.nat 100:200`): matches paths with the number of atoms between 100 and 200 ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). # Presentation attributes This reference page summarizes the `presentation` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Presentation attributes are defined in the `presentation` attribute space (short name: `pr`), that matches only presentation nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------- | ---------- | ----------------- | ------------------------------- | | [hidden](#hidden) | `h` | `true`, `false` | `pr.h` `not pr.h` | | [name](#name) | `n` | strings in quotes | `pr.n "A"` `pr.n "L*"` | | [selected](#selected) | | `true`, `false` | `pr.selected` `not pr.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `pr.sf false` `pr.sf` | | [visibilityFlag](#visibilityflag) | `vf` | `true`, `false` | `pr.vf false` `pr.vf` | | [visible](#visible) | `v` | `true`, `false` | `pr.v` `not pr.v` | ## hidden Inherited from [node.hidden](https://documentation.samson-connect.net/users/latest/nsl/node/#hidden). ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). ## visibilityFlag Inherited from [node.visibilityFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#visibilityflag). ## visible Inherited from [node.visible](https://documentation.samson-connect.net/users/latest/nsl/node/#visible). # Property model attributes This reference page summarizes the `property model` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Property model attributes are defined in the `propertyModel` attribute space (short name: `pm`), that matches only property model nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------- | ---------- | ----------------- | ------------------------------- | | [hasMaterial](#hasmaterial) | `hm` | `true`, `false` | `pm.hm` `not pm.hm` | | [hidden](#hidden) | `h` | `true`, `false` | `pm.h` `not pm.h` | | [name](#name) | `n` | strings in quotes | `pm.n "A"` `pm.n "L*"` | | [ownsMaterial](#ownsmaterial) | `om` | `true`, `false` | `pm.om` | | [selected](#selected) | | `true`, `false` | `pm.selected` `not pm.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `pm.sf false` `pm.sf` | | [visibilityFlag](#visibilityflag) | `vf` | `true`, `false` | `pm.vf false` `pm.vf` | | [visible](#visible) | `v` | `true`, `false` | `pm.v` `not pm.v` | ## hasMaterial Inherited from [node.hasMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#hasmaterial). ## hidden Inherited from [node.hidden](https://documentation.samson-connect.net/users/latest/nsl/node/#hidden). ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## ownsMaterial Inherited from [node.ownsMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#ownsmaterial). ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). ## visibilityFlag Inherited from [node.visibilityFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#visibilityflag). ## visible Inherited from [node.visible](https://documentation.samson-connect.net/users/latest/nsl/node/#visible). # Render preset attributes This reference page summarizes the `render preset` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Render preset attributes are defined in the `renderPreset` attribute space (short name: `rp`), that matches only render preset nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | ------------------------------- | ---------- | ----------------- | ------------------------------- | | [name](#name) | `n` | strings in quotes | `rp.n "A"` `rp.n "L*"` | | [selected](#selected) | | `true`, `false` | `rp.selected` `not rp.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `rp.sf false` `rp.sf` | ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). # Residue attributes This reference page summarizes the `residue` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Residue attributes are defined in the `residue` attribute space (short names: `res`, `r`), that matches only residue noder. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------- | ---------- | ----------------- | ----------------------------- | | [hasMaterial](#hasmaterial) | `hm` | `true`, `false` | `r.hm` `not r.hm` | | [hidden](#hidden) | `h` | `true`, `false` | `r.h` `not r.h` | | [name](#name) | `n` | strings in quotes | `r.n "A"` `r.n "L*"` | | [ownsMaterial](#ownsmaterial) | `om` | `true`, `false` | `r.om` | | [selected](#selected) | | `true`, `false` | `r.selected` `not r.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `r.sf false` `r.sf` | | [visibilityFlag](#visibilityflag) | `vf` | `true`, `false` | `r.vf false` `r.vf` | | [visible](#visible) | `v` | `true`, `false` | `r.v` `not r.v` | Attributes inherited from the [structuralGroup](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------------------------------- | ---------- | --------------- | -------------------------------- | | [formalCharge](#formalcharge) | `fc` | integers | `r.fc > 1` `r.fc 6:8` | | [numberOfAtoms](#numberofatoms) | `nat` | integers | `r.nat < 1000` `r.nat 100:200` | | [numberOfCarbons](#numberofcarbons) | `nC` | integers | `r.nC < 10` `r.nC 10:20` | | [numberOfHydrogens](#numberofhydrogens) | `nH` | integers | `r.nH < 10` `r.nH 10:20` | | [numberOfNitrogens](#numberofnitrogens) | `nN` | integers | `r.nN < 10` `r.nN 10:20` | | [numberOfOxygens](#numberofoxygens) | `nO` | integers | `r.nO < 10` `r.nO 10:20` | | [numberOfSulfurs](#numberofsulfurs) | `nS` | integers | `r.nS < 10` `r.nS 10:20` | | [numberOfCoarseGrainedAtoms](#numberofcoarsegrainedatoms) | `ncga` | integers | `r.ncga < 1000` `r.ncga 100:200` | | [partialCharge](#partialcharge) | `pc` | floats | `r.pc > 1.5` `r.pc 1.5:2.0` | The following residue attributes depend on the structure of the residue or the whole system: | Attribute name | Short name | Possible values | Examples | | ------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------- | -------------------------------- | | [completeAminoAcidBackbone](#completeaminoacidbackbone) | `caab` | `true`, `false` | `r.caab` | | [residueSequenceNumber](#residuesequencenumber) | `id` | integers | `r.id == 42` `r.id 42:50, 60:70` | | [secondaryStructure](#secondarystructure) | `ss` | `alpha` (`a`, `helix`, `h`), `beta` (`b`, `strand`, `s`), `unstructured` (`u`, `loop`, `l`) | `r.ss alpha` `r.ss a, b` | | [standardResidueName](#standardresiduename) | `srn` | `true`, `false` | `r.srn` | | [nonStandardResidueName](#nonstandardresiduename) | `nsrn` | `true`, `false` | `r.nsrn` | | [terminal](#terminal) | `ter` | `true`, `false` | `r.ter` | | [type](#type) | `t` | See residue [type](#type) | `r.t ALA` `r.t ALA, LYS, VAL` | The following residue attributes depend only on the residue type (i.e. they are equal for residues of the same residue type): | Attribute name | Short name | Possible values | Examples | | --------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------- | ------------------------------------- | | [aminoAcid](#aminoacid) | `aa` | `true`, `false` | `r.aa` | | [dAminoAcid](#daminoacid) | `daa` | `true`, `false` | `r.daa` | | [nucleicAcid](#nucleicacid) | `na` | `true`, `false` | `r.na` | | [hydrophobicity](#hydrophobicity) | | floats | `r.hydrophobicity < 0` | | [dna](#dna) | | `true`, `false` | `r.dna` | | [rna](#rna) | | `true`, `false` | `r.rna` | | [charge](#charge) | `c` | `negative` (`neg`), `neutral` (`neu`), `positive` (`pos`), `undefined` (`un`) | `r.c neutral` `r.c neutral, positive` | | [polarity](#polarity) | `p` | `acidicPolar` (`acidic`), `basicPolar` (`basic`), `nonpolar`, `polar`, `undefined` (`un`) | `r.p polar` `r.p basic, polar` | | [isoelectricPointPH](#dissociation-constants) | `pI` | floats | `r.pI < 6.0` `r.pI 5:6` | | [pKa1](#dissociation-constants) | `pKa1` | floats | `r.pKa1 < 2.0` `r.pKa1 1.5:2.5` | | [pKa2](#dissociation-constants) | `pKa2` | floats | `r.pKa2 < 9.0` `r.pKa2 7.5:9.0` | ## aminoAcid The `residue.aminoAcid` attribute (short name: `r.aa`) matches amino acid residues. Possible values: `true`, `false`. Examples: - `node.type atom in residue.aminoAcid` (short version: `n.t a in r.aa`): matches atoms in amino acid residues ## charge The `residue.charge` attribute (short name: `r.c`) matches amino acid residues with specific charge: | Attribute name | Short name | Meaning | | -------------- | ---------- | ----------------------------------------------------------- | | `negative` | `neg` | matches amino acid residues with negative side chain charge | | `neutral` | `neu` | matches amino acid residues with neutral side chain charge | | `positive` | `pos` | matches amino acid residues with positive side chain charge | | `undefined` | `un` | matches residues with undefined side chain charge | Examples: - `residue.charge negative` (short version: `r.c neg`): matches amino acid residues with negative side chain charge - `residue.charge neutral, positive` (short version: `r.c neu, pos`): matches amino acid residues with neutral or positive side chain charge ## completeAminoAcidBackbone The `residue.completeAminoAcidBackbone` attribute (short name: `r.caab`) matches residues that have complete amino acid backboner. Possible values: `true`, `false`. Examples: - `residue.completeAminoAcidBackbone` (short version: `r.hcaab`): matches residues that have complete amino acid backbones ## dAminoAcid The `residue.dAminoAcid` attribute (short name: `r.daa`) matches D-amino acid residues. Possible values: `true`, `false`. Examples: - `node.type atom in residue.dAminoAcid` (short version: `n.t a in r.daa`): matches atoms in D-amino acid residues ## dna The `residue.dna` attribute (short name: `r.dna`) matches DNA residues. Possible values: `true`, `false`. ## formalCharge The `residue.formalCharge` attribute (short name: `r.fc`) matches residues with specific total formal charge. Possible values: integerr. Examples: - `residue.fc 1` (short version: `r.fc 1`): matches residues with formal charge equal to 1 - `residue.fc 6:8` (short version: `r.fc 6:8`): matches residues with formal charge between 6 and 8 ## hasMaterial Inherited from [node.hasMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#hasmaterial). ## hidden Inherited from [node.hidden](https://documentation.samson-connect.net/users/latest/nsl/node/#hidden). ## hydrophobicity The `residue.hydrophobicity` attribute matches amino acid residues with the given hydrophobicity (based on the hydrophobicity scale from [Kyte, Doolittle, 1982]()). Possible values: floating-point values. Examples: - `residue.hydrophobicity -60:-20` (short version: `r.hydrophobicity < 0`): matches amino acid residues with hydrophobicity in the range from -60 to -20 ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## nucleicAcid The `residue.nucleicAcid` attribute (short name: `r.na`) matches nucleic acid residues. Possible values: `true`, `false`. Examples: - `node.type atom in residue.nucleicAcid` (short version: `n.t a in r.na`): matches atoms in nucleic acid residues ## numberOfAtoms Inherited from [structuralGroup.numberOfAtoms](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofatoms). ## numberOfCarbons Inherited from [structuralGroup.numberOfCarbons](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofcarbons). ## numberOfCoarseGrainedAtoms Inherited from [structuralGroup.numberOfCoarseGrainedAtoms](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofcoarsegrainedatoms). ## numberOfHydrogens Inherited from [structuralGroup.numberOfHydrogens](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofhydrogens). ## numberOfNitrogens Inherited from [structuralGroup.numberOfNitrogens](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofnitrogens). ## numberOfOxygens Inherited from [structuralGroup.numberOfOxygens](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofoxygens). ## numberOfSulfurs Inherited from [structuralGroup.numberOfSulfurs](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofsulfurs). ## Dissociation constants The `residue.pKa1`, `residue.pKa2`, and `residue.isoelectricPointPH` (short name: `r.pI`) attributes matches amino acid residues with certain dissociation constants: - `pKa1` - the negative of the logarithm of the dissociation constant for the carboxyl functional group, -COOH - `pKa2` - the negative of the logarithm of the dissociation constant for the amino functional group, -NH3 - `pI` - the pH at the isoelectric point Reference: *D.R. Lide, Handbook of Chemistry and Physics, 72nd Edition, CRC Press, Boca Raton, FL, 1991*. Possible values: floating-point values. Examples: - `residue.pKa1 < 2.0` (short version: `r.pKa1 < 2.0`): matches amino acid residues with pKa1 values less than 2 - `residue.pKa2 < 9.5` (short version: `r.pKa2 < 9.5`): matches amino acid residues with pKa2 values less than 9.5 - `residue.isoelectricPointPH < 6.0` (short version: `r.pI < 6.0`): matches amino acid residues with pI values less than 6 - `residue.pKa1 1.5:2.0` (short version: `r.pKa1 1.5:2.0`): matches amino acid residues with pKa1 values between 1.5 and 2 ## ownsMaterial Inherited from [node.ownsMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#ownsmaterial). ## partialCharge Inherited from [structuralGroup.partialCharge](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#partialcharge). ## polarity The `residue.polarity` attribute (short name: `r.p`) matches amino acid residues with specific polarity: | Attribute name | Short name | Meaning | | -------------- | ---------- | ------------------------------------------------------ | | `acidicPolar` | `acidic` | matches amino acid residues with an acidic side chain | | `basicPolar` | `basic` | matches amino acid residues with a basic side chain | | `nonpolar` | - | matches amino acid residues with a nonpolar side chain | | `polar` | - | matches amino acid residues with a polar side chain | | `undefined` | `un` | matches residues with undefined side chain polarity | Examples: - `residue.polarity polar` (short version: `r.p polar`): matches amino acid residues with a polar side chain - `residue.polarity acidicPolar, basicPolar` (short version: `r.p acidic, basic`): matches amino acid residues with an acidic or basic side chain ## residueSequenceNumber The `residue.residueSequenceNumber` attribute (short name: `r.id`) matches residues with specific residue sequence number (structure ID). Possible values: integerr. Examples: - `residue.residueSequenceNumber == 42` (short version: `r.id == 42`): matches residues with residue sequence number equal to 42 - `residue.residueSequenceNumber 1:10, 20:30` (short version: `r.id 1:10, 20:30`): matches residues with residue sequence number between 1 and 10 and between 20 and 30 ## rna The `residue.rna` attribute (short name: `r.rna`) matches RNA residues. Possible values: `true`, `false`. ## secondaryStructure The `residue.secondaryStructure` attribute (short name: `r.ss`) matches residues with specific secondary structurer: | Attribute name | Aliases | Meaning | | -------------- | ------------------ | -------------------------- | | `alpha` | `a`, `helix`, `h` | alpha helix | | `beta` | `b`, `strand`, `s` | beta strand | | `unstructured` | `u`, `loop`, `l` | unstructured region (loop) | Examples: - `residue.secondaryStructure helix` (short version: `r.ss h`): matches residues in alpha helices - `residue.secondaryStructure alpha, beta` (short version: `r.ss a, b`): matches residues in alpha helices and in beta sheets ## standardResidueName The `residue.standardResidueName` attribute (short name: `r.srn`) matches residues that have the standard PDB residue namer. Possible values: `true`, `false`. Examples: - `residue.standardResidueName` (short version: `r.srn`): matches residues that have the standard PDB residue names ## nonStandardResidueName The `residue.nonStandardResidueName` attribute (short name: `r.nsrn`) matches residues that do not have the standard PDB residue namer. Possible values: `true`, `false`. Examples: - `residue.nonStandardResidueName` (short version: `r.nsrn`): matches residues that do not have the standard PDB residue names ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). ## terminal The `residue.terminal` attribute (short name: `r.ter`) matches residues that are terminal. Possible values: `true`, `false`. Examples: - `residue.terminal` (short version: `r.ter`): matches residues that are terminal - `"CA" in residue.terminal` (short version: `"CA" in r.ter`): matches alpha carbons (by name) in all terminal residues ## type The `residue.type` attribute (short name: `r.t`) matches residues with specific typer. Possible values: - `A`, `C`, `G`, `U`, `I` - `DA`, `DC`, `DG`, `DT`, `DI` - `ALA`, `ARG`, `ASP`, `ASN`, `VAL`, `HIS`, `GLY`, `GLU`, `GLN`, `ILE`, `LEU`, `LYS`, `MET`, `PRO`, `SER`, `TYR`, `THR`, `TRP`, `PHE`, `CYS`, `ASX`, `GLX`, `XLE`, `XAA`, `SEC`, `PYL` Examples: - `residue.type ALA` (short version: `r.t ALA`): matches alanines - `residue.type HIS` (short version: `r.t HIS`): matches histidines - `residue.type LYS, PRO` (short version: `r.t LYS, PRO`): matches lysines and prolines - `"CA" in residue.type VAL` (short version: `"CA" in r.t VAL`): matches alpha carbons (by name) in all valines ## visibilityFlag Inherited from [node.visibilityFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#visibilityflag). ## visible Inherited from [node.visible](https://documentation.samson-connect.net/users/latest/nsl/node/#visible). ## Related pages - [Atom attributes](https://documentation.samson-connect.net/users/latest/nsl/atom/index.md) - [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md) # Segment attributes This reference page summarizes the `segment` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Segment attributes are defined in the `segment` attribute space (short name: `s`), that matches only segment nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------- | ---------- | ----------------- | ----------------------------- | | [hasMaterial](#hasmaterial) | `hm` | `true`, `false` | `s.hm` `not s.hm` | | [hidden](#hidden) | `h` | `true`, `false` | `s.h` `not s.h` | | [name](#name) | `n` | strings in quotes | `s.n "A"` `s.n "L*"` | | [ownsMaterial](#ownsmaterial) | `om` | `true`, `false` | `s.om` | | [selected](#selected) | | `true`, `false` | `s.selected` `not s.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `s.sf false` `s.sf` | | [visibilityFlag](#visibilityflag) | `vf` | `true`, `false` | `s.vf false` `s.vf` | | [visible](#visible) | `v` | `true`, `false` | `s.v` `not s.v` | Attributes inherited from the [structuralGroup](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------------------------------- | ---------- | --------------- | -------------------------------- | | [formalCharge](#formalcharge) | `fc` | integers | `s.fc > 1` `s.fc 6:8` | | [numberOfAtoms](#numberofatoms) | `nat` | integers | `s.nat < 1000` `s.nat 100:200` | | [numberOfCarbons](#numberofcarbons) | `nC` | integers | `s.nC < 10` `s.nC 10:20` | | [numberOfHydrogens](#numberofhydrogens) | `nH` | integers | `s.nH < 10` `s.nH 10:20` | | [numberOfNitrogens](#numberofnitrogens) | `nN` | integers | `s.nN < 10` `s.nN 10:20` | | [numberOfOxygens](#numberofoxygens) | `nO` | integers | `s.nO < 10` `s.nO 10:20` | | [numberOfSulfurs](#numberofsulfurs) | `nS` | integers | `s.nS < 10` `s.nS 10:20` | | [numberOfCoarseGrainedAtoms](#numberofcoarsegrainedatoms) | `ncga` | integers | `s.ncga < 1000` `s.ncga 100:200` | | [partialCharge](#partialcharge) | `pc` | floats | `s.pc > 1.5` `s.pc 1.5:2.0` | Attributes specific to the `segment` attribute space: | Attribute name | Short name | Possible values | Examples | | ----------------------------------------------------- | ---------- | --------------- | --------------------------- | | [numberOfResidues](#numberofresidues) | `nr` | integers | `s.nr > 130` `s.nr 100:130` | | [numberOfStructuralGroups](#numberofstructuralgroups) | `nsg` | integers | `s.nsg > 10` `s.nsg 10:13` | ## formalCharge Inherited from [structuralGroup.formalCharge](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#formalcharge). ## hasMaterial Inherited from [node.hasMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#hasmaterial). ## hidden Inherited from [node.hidden](https://documentation.samson-connect.net/users/latest/nsl/node/#hidden). ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## numberOfAtoms Inherited from [structuralGroup.numberOfAtoms](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofatoms). ## numberOfCarbons Inherited from [structuralGroup.numberOfCarbons](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofcarbons). ## numberOfCoarseGrainedAtoms Inherited from [structuralGroup.numberOfCoarseGrainedAtoms](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofcoarsegrainedatoms). ## numberOfHydrogens Inherited from [structuralGroup.numberOfHydrogens](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofhydrogens). ## numberOfNitrogens Inherited from [structuralGroup.numberOfNitrogens](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofnitrogens). ## numberOfOxygens Inherited from [structuralGroup.numberOfOxygens](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofoxygens). ## numberOfResidues The `segment.numberOfResidues` attribute (short name: `s.nr`) matches segments with specific number of residues. Possible values: integers. Examples: - `segment.numberOfResidues > 100` (short version: `s.nr > 100`): matches segments with the number of residues greater than 100 - `segment.numberOfResidues 100:120` (short version: `s.nr 100:120`): matches segments with the number of residues between 100 and 120 ## numberOfStructuralGroups The `segment.numberOfStructuralGroups` attribute (short name: `s.nsg`) matches segments with specific number of structural groups. Possible values: integers. Examples: - `segment.numberOfStructuralGroups > 10` (short version: `s.nsg > 10`): matches segments with the number of structural groups greater than 10 - `segment.numberOfStructuralGroups 10:12` (short version: `s.nsg 10:12`): matches segments with the number of structural groups between 10 and 12 ## numberOfSulfurs Inherited from [structuralGroup.numberOfSulfurs](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofsulfurs). ## ownsMaterial Inherited from [node.ownsMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#ownsmaterial). ## partialCharge Inherited from [structuralGroup.partialCharge](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#partialcharge). ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). ## visibilityFlag Inherited from [node.visibilityFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#visibilityflag). ## visible Inherited from [node.visible](https://documentation.samson-connect.net/users/latest/nsl/node/#visible). ## Related pages - [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) - [Residue attributes](https://documentation.samson-connect.net/users/latest/nsl/residue/index.md) - [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md) # Side chain attributes This reference page summarizes the `side chain` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Side chain attributes are defined in the `sideChain` attribute space (short name: `s`), that matches only side chain nodesc. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------- | ---------- | ----------------- | ------------------------------- | | [hasMaterial](#hasmaterial) | `hm` | `true`, `false` | `sc.hm` `not sc.hm` | | [hidden](#hidden) | `h` | `true`, `false` | `sc.h` `not sc.h` | | [name](#name) | `n` | strings in quotes | `sc.n "A"` `sc.n "L*"` | | [ownsMaterial](#ownsmaterial) | `om` | `true`, `false` | `sc.om` | | [selected](#selected) | | `true`, `false` | `sc.selected` `not sc.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `sc.sf false` `sc.sf` | | [visibilityFlag](#visibilityflag) | `vf` | `true`, `false` | `sc.vf false` `sc.vf` | | [visible](#visible) | `v` | `true`, `false` | `sc.v` `not sc.v` | Attributes inherited from the [structuralGroup](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------------------------------- | ---------- | --------------- | ---------------------------------- | | [formalCharge](#formalcharge) | `fc` | integers | `sc.fc > 1` `sc.fc 6:8` | | [numberOfAtoms](#numberofatoms) | `nat` | integers | `sc.nat < 1000` `sc.nat 100:200` | | [numberOfCarbons](#numberofcarbons) | `nC` | integers | `sc.nC < 10` `sc.nC 10:20` | | [numberOfHydrogens](#numberofhydrogens) | `nH` | integers | `sc.nH < 10` `sc.nH 10:20` | | [numberOfNitrogens](#numberofnitrogens) | `nN` | integers | `sc.nN < 10` `sc.nN 10:20` | | [numberOfOxygens](#numberofoxygens) | `nO` | integers | `sc.nO < 10` `sc.nO 10:20` | | [numberOfSulfurs](#numberofsulfurs) | `nS` | integers | `sc.nS < 10` `sc.nS 10:20` | | [numberOfCoarseGrainedAtoms](#numberofcoarsegrainedatoms) | `ncga` | integers | `sc.ncga < 1000` `sc.ncga 100:200` | | [partialCharge](#partialcharge) | `pc` | floats | `sc.pc > 1.5` `sc.pc 1.5:2.0` | ## formalCharge Inherited from [structuralGroup.formalCharge](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#formalcharge). ## hasMaterial Inherited from [node.hasMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#hasmaterial). ## hidden Inherited from [node.hidden](https://documentation.samson-connect.net/users/latest/nsl/node/#hidden). ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## numberOfAtoms Inherited from [structuralGroup.numberOfAtoms](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofatoms). ## numberOfCarbons Inherited from [structuralGroup.numberOfCarbons](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofcarbons). ## numberOfCoarseGrainedAtoms Inherited from [structuralGroup.numberOfCoarseGrainedAtoms](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofcoarsegrainedatoms). ## numberOfHydrogens Inherited from [structuralGroup.numberOfHydrogens](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofhydrogens). ## numberOfNitrogens Inherited from [structuralGroup.numberOfNitrogens](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofnitrogens). ## numberOfOxygens Inherited from [structuralGroup.numberOfOxygens](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofoxygens). ## numberOfSulfurs Inherited from [structuralGroup.numberOfSulfurs](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#numberofsulfurs). ## ownsMaterial Inherited from [node.ownsMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#ownsmaterial). ## partialCharge Inherited from [structuralGroup.partialCharge](https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/#partialcharge). ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). ## visibilityFlag Inherited from [node.visibilityFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#visibilityflag). ## visible Inherited from [node.visible](https://documentation.samson-connect.net/users/latest/nsl/node/#visible). # Structural group attributes This reference page summarizes the `structural group` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Structural group attributes are defined in the `structuralGroup` attribute space (short name: `sg`), that matches only structural group nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------- | ---------- | ----------------- | ------------------------------- | | [hasMaterial](#hasmaterial) | `hm` | `true`, `false` | `sg.hm` `not sg.hm` | | [hidden](#hidden) | `h` | `true`, `false` | `sg.h` `not sg.h` | | [name](#name) | `n` | strings in quotes | `sg.n "A"` `sg.n "L*"` | | [ownsMaterial](#ownsmaterial) | `om` | `true`, `false` | `sg.om` | | [selected](#selected) | | `true`, `false` | `sg.selected` `not sg.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `sg.sf false` `sg.sf` | | [visibilityFlag](#visibilityflag) | `vf` | `true`, `false` | `sg.vf false` `sg.vf` | | [visible](#visible) | `v` | `true`, `false` | `sg.v` `not sg.v` | Attributes specific to the `structuralGroup` attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------------------------------- | ---------- | --------------- | --------------------------------------------- | | [formalCharge](#formalcharge) | `fc` | integers | `sg.fc > 1` `sg.fc 6:8` | | [numberOfAtoms](#numberofatoms) | `nat` | integers | `sg.nat < 1000` `sg.nat 100:200` | | [numberOfCarbons](#numberofcarbons) | `nC` | integers | `sg.nC < 10` `sg.nC 10:20` | | [numberOfCoarseGrainedAtoms](#numberofcoarsegrainedatoms) | `ncga` | integers | `sg.ncga < 1000` `sg.ncga 100:200` | | [numberOfHydrogens](#numberofhydrogens) | `nH` | integers | `sg.nH < 10` `sg.nH 10:20` | | [numberOfNitrogens](#numberofnitrogens) | `nN` | integers | `sg.nN < 10` `sg.nN 10:20` | | [numberOfOxygens](#numberofoxygens) | `nO` | integers | `sg.nO < 10` `sg.nO 10:20` | | [numberOfSulfurs](#numberofsulfurs) | `nS` | integers | `sg.nS < 10` `sg.nS 10:20` | | [partialCharge](#partialcharge) | `pc` | floats | `sg.pc > 1.5` `sg.pc 1.5:2.0` | | [structureID](#structureid) | `id` | integers | `sg.id 1` `sg.id >= 100` `sg.id 10:20, 30:40` | ## formalCharge The `structuralGroup.formalCharge` attribute (short name: `sg.fc`) matches structural groups with specific total formal charge. Possible values: integers. Examples: - `structuralGroup.fc 1` (short version: `sg.fc 1`): matches structural groups with formal charge equal to 1 - `structuralGroup.fc 6:8` (short version: `sg.fc 6:8`): matches structural groups with formal charge between 6 and 8 ## hasMaterial Inherited from [node.hasMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#hasmaterial). ## hidden Inherited from [node.hidden](https://documentation.samson-connect.net/users/latest/nsl/node/#hidden). ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## numberOfAtoms The `structuralGroup.numberOfAtoms` attribute (short name: `sg.nat`) matches structural groups with specific number of atoms. Possible values: integers. Examples: - `structuralGroup.nat > 100` (short version: `sg.nat > 100`): matches structural groups with the number of atoms more than 100 - `structuralGroup.nat 100:200` (short version: `sg.nat 100:200`): matches structural groups with the number of atoms between 100 and 200 ## numberOfCarbons The `structuralGroup.numberOfCarbons` attribute (short name: `sg.nC`) matches structural groups with specific number of **Carbon atoms**. It works in the similar way as the [numberOfAtoms](#numberofatoms) attribute. ## numberOfCoarseGrainedAtoms The `structuralGroup.numberOfCoarseGrainedAtoms` attribute (short name: `sg.ncga`) matches structural groups with specific number of **coarse-grained atoms**. It works in the similar way as the [numberOfAtoms](#numberofatoms) attribute. ## numberOfHydrogens The `structuralGroup.numberOfHydrogens` attribute (short name: `sg.nH`) matches structural groups with specific number of **Hydrogen atoms**. It works in the similar way as the [numberOfAtoms](#numberofatoms) attribute. ## numberOfNitrogens The `structuralGroup.numberOfNitrogens` attribute (short name: `sg.nN`) matches structural groups with specific number of **Nitrogen atoms**. It works in the similar way as the [numberOfAtoms](#numberofatoms) attribute. ## numberOfOxygens The `structuralGroup.numberOfOxygens` attribute (short name: `sg.nO`) matches structural groups with specific number of **Oxygen atoms**. It works in the similar way as the [numberOfAtoms](#numberofatoms) attribute. ## numberOfSulfurs The `structuralGroup.numberOfSulfurs` attribute (short name: `sg.nS`) matches structural groups with specific number of **Sulfur atoms**. It works in the similar way as the [numberOfAtoms](#numberofatoms) attribute. ## ownsMaterial Inherited from [node.ownsMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#ownsmaterial). ## partialCharge The `structuralGroup.partialCharge` attribute (short name: `sg.pc`) matches structural groups with specific total partial charge. Possible values: real. Examples: - `structuralGroup.pc 1` (short version: `sg.pc 1`): matches structural groups with partial charge equal to 1 - `structuralGroup.pc 1.5:2.0` (short version: `sg.pc 1.5:2.0`): matches structural groups with partial charge between 1.5 and 2.0 ## structureID The `structuralGroup.structureID` attribute (short name: `sg.id`) matches structural groups with specific structure ID. Possible values: integers. Examples: - `structuralGroup.id >= 10` (short version: `sg.id >= 10`): matches structural groups with structure ID greater or equal to 10 - `structuralGroup.id 5:10, 25:30` (short version: `sg.id 5:10, 25:30`): matches structural groups with structure ID between 5 and 10, and between 25 and 30 ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). ## visibilityFlag Inherited from [node.visibilityFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#visibilityflag). ## visible Inherited from [node.visible](https://documentation.samson-connect.net/users/latest/nsl/node/#visible). ## Related pages - [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) - [Node attributes](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) - [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md) # Structural model attributes This reference page summarizes the `structural model` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Structural model attributes are defined in the `structuralModel` attribute space (short name: `sm`), that matches only structural model nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------- | ---------- | ----------------- | ------------------------------- | | [hasMaterial](#hasmaterial) | `hm` | `true`, `false` | `sm.hm` `not sm.hm` | | [hidden](#hidden) | `h` | `true`, `false` | `sm.h` `not sm.h` | | [name](#name) | `n` | strings in quotes | `sm.n "A"` `sm.n "L*"` | | [ownsMaterial](#ownsmaterial) | `om` | `true`, `false` | `sm.om` | | [selected](#selected) | | `true`, `false` | `sm.selected` `not sm.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `sm.sf false` `sm.sf` | | [visibilityFlag](#visibilityflag) | `vf` | `true`, `false` | `sm.vf false` `sm.vf` | | [visible](#visible) | `v` | `true`, `false` | `sm.v` `not sm.v` | Attributes specific to the `structuralModel` attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------------------------------- | ---------- | --------------- | ---------------------------------- | | [formalCharge](#formalcharge) | `fc` | integers | `sm.fc > 1` `sm.fc 6:8` | | [numberOfAtoms](#numberofatoms) | `nat` | integers | `sm.nat < 1000` `sm.nat 100:200` | | [numberOfCarbons](#numberofcarbons) | `nC` | integers | `sm.nC < 10` `sm.nC 10:20` | | [numberOfChains](#numberofchains) | `nc` | integers | `sm.nc < 3` `sm.nc 2:4` | | [numberOfCoarseGrainedAtoms](#numberofcoarsegrainedatoms) | `ncga` | integers | `sm.ncga < 1000` `sm.ncga 100:200` | | [numberOfHydrogens](#numberofhydrogens) | `nH` | integers | `sm.nH < 10` `sm.nH 10:20` | | [numberOfMolecules](#numberofmolecules) | `nm` | integers | `sm.nm < 3` `sm.nm 2:4` | | [numberOfNitrogens](#numberofnitrogens) | `nN` | integers | `sm.nN < 10` `sm.nN 10:20` | | [numberOfOxygens](#numberofoxygens) | `nO` | integers | `sm.nO < 10` `sm.nO 10:20` | | [numberOfResidues](#numberofresidues) | `nr` | integers | `sm.nr > 130` `sm.nr 100:130` | | [numberOfSegments](#numberofsegments) | `ns` | integers | `sm.ns < 3` `sm.ns 1:3` | | [numberOfStructuralGroups](#numberofstructuralgroups) | `nsg` | integers | `sm.nsg > 10` `sm.nsg 10:13` | | [numberOfSulfurs](#numberofsulfurs) | `nS` | integers | `sm.nS < 10` `sm.nS 10:20` | | [partialCharge](#partialcharge) | `pc` | floats | `sm.pc > 1.5` `sm.pc 1.5:2.0` | ## formalCharge The `structuralModel.formalCharge` attribute (short name: `sm.fc`) matches structural models with specific total formal charge. Possible values: integers. Examples: - `structuralModel.fc 1` (short version: `sm.fc 1`): matches structural models with formal charge equal to 1 - `structuralModel.fc 6:8` (short version: `sm.fc 6:8`): matches structural models with formal charge between 6 and 8 ## hasMaterial Inherited from [node.hasMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#hasmaterial). ## hidden Inherited from [node.hidden](https://documentation.samson-connect.net/users/latest/nsl/node/#hidden). ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## numberOfAtoms The `structuralModel.numberOfAtoms` attribute (short name: `sm.nat`) matches structural models with specific number of atoms. Possible values: integers. Examples: - `structuralModel.nat > 100` (short version: `sm.nat > 100`): matches structural models with the number of atoms more than 100 - `structuralModel.nat 100:200` (short version: `sm.nat 100:200`): matches structural models with the number of atoms between 100 and 200 ## numberOfCarbons The `structuralModel.numberOfCarbons` attribute (short name: `sm.nC`) matches structural groups with specific number of **Carbon atoms**. It works in the similar way as the [numberOfAtoms](#numberofatoms) attribute. ## numberOfChains The `structuralModel.numberOfChains` attribute (short name: `sm.nc`) matches structural models with specific number of chains. Possible values: integers. Examples: - `structuralModel.numberOfChains < 3` (short version: `sm.nc < 3`): matches structural models with the number of chains less than 3 - `structuralModel.numberOfChains 2:4` (short version: `sm.nc 2:4`): matches structural models with the number of chains between 2 and 4 ## numberOfCoarseGrainedAtoms The `structuralModel.numberOfCoarseGrainedAtoms` attribute (short name: `sm.ncga`) matches structural groups with specific number of **coarse-grained atoms**. It works in the similar way as the [numberOfAtoms](#numberofatoms) attribute. ## numberOfHydrogens The `structuralModel.numberOfHydrogens` attribute (short name: `sm.nH`) matches structural groups with specific number of **Hydrogen atoms**. It works in the similar way as the [numberOfAtoms](#numberofatoms) attribute. ## numberOfMolecules The `structuralModel.numberOfMolecules` attribute (short name: `sm.nm`) matches structural models with specific number of molecules. Possible values: integers. Examples: - `structuralModel.numberOfMolecules < 3` (short version: `sm.nm < 3`): matches structural models with the number of molecules less than 3 - `structuralModel.numberOfMolecules 2:4` (short version: `sm.nm 2:4`): matches structural models with the number of molecules between 2 and 4 ## numberOfNitrogens The `structuralModel.numberOfNitrogens` attribute (short name: `sm.nN`) matches structural groups with specific number of **Nitrogen atoms**. It works in the similar way as the [numberOfAtoms](#numberofatoms) attribute. ## numberOfOxygens The `structuralModel.numberOfOxygens` attribute (short name: `sm.nO`) matches structural groups with specific number of **Oxygen atoms**. It works in the similar way as the [numberOfAtoms](#numberofatoms) attribute. ## numberOfResidues The `structuralModel.numberOfResidues` attribute (short name: `sm.nr`) matches structural models with specific number of residues. Possible values: integers. Examples: - `structuralModel.numberOfResidues > 100` (short version: `sm.nr > 100`): matches structural models with the number of residues greater than 100 - `structuralModel.numberOfResidues 100:120` (short version: `sm.nr 100:120`): matches structural models with the number of residues between 100 and 120 ## numberOfSegments The `structuralModel.numberOfSegments` attribute (short name: `sm.ns`) matches structural models with specific number of segments. Possible values: integers. Examples: - `structuralModel.numberOfSegments > 2` (short version: `sm.ns > 2`): matches structural models with the number of segments greater than 2 - `structuralModel.numberOfSegments 2:4` (short version: `sm.ns 2:4`): matches structural models with the number of segments between 2 and 4 ## numberOfStructuralGroups The `structuralModel.numberOfStructuralGroups` attribute (short name: `sm.nsg`) matches structural models with specific number of structural groups. Possible values: integers. Examples: - `structuralModel.numberOfStructuralGroups > 10` (short version: `sm.nsg > 10`): matches structural models with the number of structural groups greater than 10 - `structuralModel.numberOfStructuralGroups 10:12` (short version: `sm.nsg 10:12`): matches structural models with the number of structural groups between 10 and 12 ## numberOfSulfurs The `structuralModel.numberOfSulfurs` attribute (short name: `sm.nS`) matches structural groups with specific number of **Sulfur atoms**. It works in the similar way as the [numberOfAtoms](#numberofatoms) attribute. ## ownsMaterial Inherited from [node.ownsMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#ownsmaterial). ## partialCharge The `structuralModel.partialCharge` attribute (short name: `sm.pc`) matches structural models with specific total partial charge. Possible values: real. Examples: - `structuralModel.pc 1` (short version: `sm.pc 1`): matches structural models with partial charge equal to 1 - `structuralModel.pc 1.5:2.0` (short version: `sm.pc 1.5:2.0`): matches structural models with partial charge between 1.5 and 2.0 ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). ## visibilityFlag Inherited from [node.visibilityFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#visibilityflag). ## visible Inherited from [node.visible](https://documentation.samson-connect.net/users/latest/nsl/node/#visible). ## Related pages - [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) - [Atom attributes](https://documentation.samson-connect.net/users/latest/nsl/atom/index.md) - [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md) # Visual model attributes This reference page summarizes the `visual model` Node Specification Language (NSL) attribute space in [SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/index.md), including attribute names, short names, possible values, and example expressions. See also: [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md), [Examples](https://documentation.samson-connect.net/users/latest/nsl/examples/index.md). Visual model attributes are defined in the `visualModel` attribute space (short name: `vm`), that matches only visual model nodes. Attributes inherited from the [node](https://documentation.samson-connect.net/users/latest/nsl/node/index.md) attribute space: | Attribute name | Short name | Possible values | Examples | | --------------------------------- | ---------- | ----------------- | ------------------------------- | | [hasMaterial](#hasmaterial) | `hm` | `true`, `false` | `vm.hm` `not vm.hm` | | [hidden](#hidden) | `h` | `true`, `false` | `vm.h` `not vm.h` | | [name](#name) | `n` | strings in quotes | `vm.n "A"` `vm.n "L*"` | | [ownsMaterial](#ownsmaterial) | `om` | `true`, `false` | `vm.om` | | [selected](#selected) | | `true`, `false` | `vm.selected` `not vm.selected` | | [selectionFlag](#selectionflag) | `sf` | `true`, `false` | `vm.sf false` `vm.sf` | | [visibilityFlag](#visibilityflag) | `vf` | `true`, `false` | `vm.vf false` `vm.vf` | | [visible](#visible) | `v` | `true`, `false` | `vm.v` `not vm.v` | ## hasMaterial Inherited from [node.hasMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#hasmaterial). ## hidden Inherited from [node.hidden](https://documentation.samson-connect.net/users/latest/nsl/node/#hidden). ## name Inherited from [node.name](https://documentation.samson-connect.net/users/latest/nsl/node/#name). ## ownsMaterial Inherited from [node.ownsMaterial](https://documentation.samson-connect.net/users/latest/nsl/node/#ownsmaterial). ## selected Inherited from [node.selected](https://documentation.samson-connect.net/users/latest/nsl/node/#selected), but without the short name `s`. ## selectionFlag Inherited from [node.selectionFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#selectionflag). ## visibilityFlag Inherited from [node.visibilityFlag](https://documentation.samson-connect.net/users/latest/nsl/node/#visibilityflag). ## visible Inherited from [node.visible](https://documentation.samson-connect.net/users/latest/nsl/node/#visible). # User Guide - Path Analyzer References # Path Analyzer Reference This reference complements the main [Path Analyzer](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md) page. It contains one page per Path Analyzer analysis type, with the required inputs, supported card views, interpretation advice, and practical tips. ## When to use this Use this reference when you already have a path or trajectory and need to choose the correct Path Analyzer card. If you need to learn the workflow first, start with the main [Path Analyzer](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md) page. ## Geometry - [Angle](https://documentation.samson-connect.net/users/latest/references/path-analyzer/angle/index.md): measure a three-group angle along a path. - [Dihedral](https://documentation.samson-connect.net/users/latest/references/path-analyzer/dihedral/index.md): measure a four-group torsion angle along a path. - [Distance](https://documentation.samson-connect.net/users/latest/references/path-analyzer/distance/index.md): measure centroid or minimum distances between two groups. ## Structural and Trajectory Observables - [Asphericity](https://documentation.samson-connect.net/users/latest/references/path-analyzer/asphericity/index.md): monitor how far a selected group deviates from a spherical shape. - [Contact persistence](https://documentation.samson-connect.net/users/latest/references/path-analyzer/contact-persistence/index.md): inspect which contact pairs remain present over time and how persistent they are. - [Contacts](https://documentation.samson-connect.net/users/latest/references/path-analyzer/contacts/index.md): follow the number of contacts over time and inspect pair occupancies in a contact map. - [Ramachandran](https://documentation.samson-connect.net/users/latest/references/path-analyzer/ramachandran/index.md): inspect phi/psi conformational states of protein residues. - [Radius of gyration](https://documentation.samson-connect.net/users/latest/references/path-analyzer/radius-of-gyration/index.md): monitor compactness of a selected group. - [RMSD](https://documentation.samson-connect.net/users/latest/references/path-analyzer/rmsd/index.md): track structural deviation relative to the first frame after fitting. - [RMSD (pairwise)](https://documentation.samson-connect.net/users/latest/references/path-analyzer/rmsd-pairwise/index.md): compare every frame with every other frame. - [RMSF](https://documentation.samson-connect.net/users/latest/references/path-analyzer/rmsf/index.md): compute the fluctuation profile of the measured features after fitting. - [SASA](https://documentation.samson-connect.net/users/latest/references/path-analyzer/sasa/index.md): track solvent-accessible surface area. - [Secondary structure content](https://documentation.samson-connect.net/users/latest/references/path-analyzer/secondary-structure-content/index.md): follow alpha, beta, and unstructured fractions through time. - [Shape parameter](https://documentation.samson-connect.net/users/latest/references/path-analyzer/shape-parameter/index.md): inspect how elongated or flattened a selected group becomes. ## Distribution and Density - [2D density map](https://documentation.samson-connect.net/users/latest/references/path-analyzer/density-map-2d/index.md): combine two saved scalar analyses into a two-dimensional density estimate. - [Density curve](https://documentation.samson-connect.net/users/latest/references/path-analyzer/density-curve/index.md): estimate a smooth one-dimensional density from a saved scalar analysis. - [RDF](https://documentation.samson-connect.net/users/latest/references/path-analyzer/rdf/index.md): compute the radial distribution function between two groups. ## Energetics and Dynamics - [Average force](https://documentation.samson-connect.net/users/latest/references/path-analyzer/average-force/index.md): follow mean force magnitudes for a selected group. - [Average velocity](https://documentation.samson-connect.net/users/latest/references/path-analyzer/average-velocity/index.md): follow mean velocity magnitudes for a selected group. - [Energy](https://documentation.samson-connect.net/users/latest/references/path-analyzer/energy/index.md): inspect potential, kinetic, or total energy along the path. - [Energy landscape](https://documentation.samson-connect.net/users/latest/references/path-analyzer/energy-landscape/index.md): project path energy onto two saved scalar analyses. ## Comparative - [Custom scatter](https://documentation.samson-connect.net/users/latest/references/path-analyzer/custom-scatter/index.md): compare two saved scalar analyses directly against each other. ## Related pages - [Path Analyzer](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md): learn the analysis workflow and dashboard interactions. - [Simulate and analyze](https://documentation.samson-connect.net/users/latest/simulate-and-analyze/index.md): return to the simulation and analysis hub. # Angle The **Angle** analysis measures the angle formed by three selected groups along a path or trajectory. It is useful for tracking bending, hinge opening, and local geometric rearrangements. ## Adding the plot 1. Open [Path Analyzer](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md). 1. Choose **Angle** in **Observable**. 1. Choose a **Path**. 1. Define **Group A**, **Vertex**, and **Group C**. 1. Click **Add Time Series** or **Add Histogram**. ## Inputs - Three atom-containing selections are required. - The middle selection defines the vertex of the angle. - When the path provides time values, Path Analyzer uses time on the x-axis; otherwise it uses frame indices. ## How groups are converted to positions Path Analyzer converts each selected group to one representative position before computing the angle. If a group contains one atom, its atomic position is used directly. If a group contains several atoms, Path Analyzer uses the **center of mass** of that group. ## Views - **Time series**: follow the angle along the path. - **Histogram**: inspect the distribution of visited angles. ## Key equation If (\\mathbf{p}\_A(t)), (\\mathbf{p}\_V(t)), and (\\mathbf{p}\_C(t)) denote the representative positions of the three selected groups at frame (t), Path Analyzer follows [ \\theta(t)=\\arccos\\left( \\frac{(\\mathbf{p}\_A-\\mathbf{p}\_V)\\cdot(\\mathbf{p}\_C-\\mathbf{p}\_V)} {|\\mathbf{p}\_A-\\mathbf{p}\_V|,|\\mathbf{p}\_C-\\mathbf{p}\_V|} \\right) ] For multi-atom groups, the representative position is the center of mass: [ \\mathbf{p}\_{\\mathrm{group}}(t)= \\frac{\\sum_i m_i,\\mathbf{r}\_i(t)}{\\sum_i m_i} ] Tip - Use single atoms for highly local measurements. - Use larger groups when you want a coarse-grained structural descriptor. - If the angle is only one part of a larger motion, combine it later with another saved scalar analysis in [Custom scatter](https://documentation.samson-connect.net/users/latest/references/path-analyzer/custom-scatter/index.md) or [Energy landscape](https://documentation.samson-connect.net/users/latest/references/path-analyzer/energy-landscape/index.md). # Asphericity The **Asphericity** analysis reports how far a selected group deviates from a spherical shape along a path or trajectory. It is a compact way to monitor shape anisotropy without reducing the description to a single distance. ## Adding the plot 1. Open [Path Analyzer](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md). 1. Choose **Asphericity** in **Observable**. 1. Choose a **Path**. 1. Define the **Group** to analyze. 1. Click **Add Time Series** or **Add Histogram**. ## Inputs - One atom-containing selection is required. ## Views - **Time series**: follow the shape descriptor along the path. - **Histogram**: inspect the range of sampled values. Tip - Use asphericity when radius of gyration alone is too coarse. - Pair it with [Radius of gyration](https://documentation.samson-connect.net/users/latest/references/path-analyzer/radius-of-gyration/index.md) and [Shape parameter](https://documentation.samson-connect.net/users/latest/references/path-analyzer/shape-parameter/index.md) for a fuller picture of global shape changes. # Average Force The **Average force** analysis follows the mean force magnitude on a selected group along a path. It is useful for spotting strained regions, strongly driven motions, or frames where the system experiences unusually large forces. ## Adding the plot 1. Open [Path Analyzer](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md). 1. Choose **Average force** in **Observable**. 1. Choose a **Path**. 1. Define the **Group** to analyze. 1. Click **Add Force Series** or **Add Force Distribution**. ## Inputs - One atom-containing selection is required. - The chosen path must expose force data for the selected atoms. ## Views - **Force series**: follow the mean force magnitude over the path. - **Force distribution**: inspect the distribution of sampled force magnitudes. ## Key equation For a selected atom set (\\mathcal{A}), Path Analyzer computes the mean force magnitude at frame (t) as [ \\bar{F}(t)=\\frac{1}{|\\mathcal{A}|}\\sum\_{a\\in\\mathcal{A}}|\\mathbf{F}\_a(t)| ] ## Card settings - Units can be switched after creation between `Auto`, `pN`, and `nN`. Tip - Use a focused selection when you care about one interface, motif, or active site. - Use a broad selection when you want a whole-subsystem summary. - Pair average force with [Energy](https://documentation.samson-connect.net/users/latest/references/path-analyzer/energy/index.md) when you want to compare strong forces with the energetic profile. # Average Velocity The **Average velocity** analysis follows the mean velocity magnitude of a selected group along a path. It is useful for dynamical trajectories and for quickly spotting bursts of motion or unusually quiet regions. ## Adding the plot 1. Open [Path Analyzer](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md). 1. Choose **Average velocity** in **Observable**. 1. Choose a **Path**. 1. Define the **Group** to analyze. 1. Click **Add Velocity Series** or **Add Velocity Distribution**. ## Inputs - One atom-containing selection is required. - The chosen path must expose velocity data for the selected atoms. ## Views - **Velocity series**: follow the mean velocity magnitude over the path. - **Velocity distribution**: inspect the sampled distribution. ## Key equation For a selected atom set (\\mathcal{A}), Path Analyzer computes the mean velocity magnitude at frame (t) as [ \\bar{v}(t)=\\frac{1}{|\\mathcal{A}|}\\sum\_{a\\in\\mathcal{A}}|\\mathbf{v}\_a(t)| ] ## Card settings - Units can be switched after creation between `Auto`, `pm/fs`, `A/ps`, and `m/s`. Tip - Use average velocity for trajectories with meaningful dynamical information. - Compare it with [Average force](https://documentation.samson-connect.net/users/latest/references/path-analyzer/average-force/index.md) when you want to connect driving forces and resulting motion. # Contact Persistence The **Contact persistence** analysis resolves contacts pair by pair across the whole path. It can display a contact timeline heatmap and a persistence distribution, making it ideal for finding stable, intermittent, and transient interactions. ## Adding the plot 1. Open [Path Analyzer](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md). 1. Choose **Contact persistence** in **Observable**. 1. Choose a **Path**. 1. Define **Group A** and **Group B**. 1. Set the contact **Cutoff**. 1. Click **Add Contact Timeline** or **Add Persistence Distribution**. ## Inputs - Two atom-containing selections are required. - The cutoff is given in `A`. - Contact pairs are built from the selected feature groups rather than from a single pooled atom list. ## Views - **Contact timeline**: a heatmap showing whether each contact pair is present or absent at each frame. - **Persistence distribution**: a histogram of contact occupancies. ## Key equations For each contact pair ((u,v)), the timeline stores a binary state [ s\_{uv}(t)= \\begin{cases} 1, & d^{\\min}\_{uv}(t)\ Chemistry > Select using SMARTS**). - Select **D-amino acids** by their standard PDB names (**Select > Residues > D-amino acids** or [NSL](https://documentation.samson-connect.net/users/latest/nsl/residue/#daminoacid): `residue.daa`). - Select **crystallization buffer agents** by their standard names (**Select > Biology > Crystallization buffer agent** or [NSL](https://documentation.samson-connect.net/users/latest/nsl/node/#category): `node.category cba`). ## SAMSON Extensions **Updates:** - [**Python Scripting**](https://www.samson-connect.net/extensions/7b654ce6-e38c-b97f-6746-4fd6934487c2): You can now access exposed functionality from SAMSON Extensions via new bindings for the SAMSON API and its [Introspection mechanism](https://documentation.samson-connect.net/developers/latest/introspection/). New Python bindinds includes: `SBValue`, `SBProxy`, `SBFunction`. Learn more in the [Python Scripting Guide — Introspection: using extensions](https://documentation.samson-connect.net/scripting/latest/docs/Introspection.html). This release also includes minor improvements to the SAMSON API Python bindings. - [**Exposed Functionality Viewer**](https://www.samson-connect.net/extensions/92c88bef-d33d-3eab-2380-1d4b1788ac1b): Alongside improved C++ sample-code generation for exposed Extension functions, the tool now also generates **Python** sample code for use with integrated Python Scripting. Search performance has also been improved. - [**Importers Collection**](https://www.samson-connect.net/extensions/385fe362-adfd-ce55-95c0-4e63560efa29): When loading **XYZ** files, the structure hierarchy is now created from connected components. The same approach is applied to **PDB** files that contain no hierarchy. You can adjust this setting (and other importer options) in **Preferences > Importers**. **Minor improvements:** - [**Interaction designer**](https://www.samson-connect.net/extensions/52fe9e27-19f3-093b-4f4f-4c6aff880a77): We fixed several bugs, improved performance, and made quality-of-life enhancements to streamline the overall experience. ## Documentation updates We refreshed tutorials for SAMSON and SAMSON Extensions, and added/updated resources for developers: - [**Python Scripting Guide - Introspection: using extensions**](https://documentation.samson-connect.net/scripting/latest/docs/Introspection.html) - [**Developer Guide (C++) - Introspection**](https://documentation.samson-connect.net/developers/latest/introspection/) You can also find [**many focused SAMSON tips on the blog**](https://blog.samson-connect.net/)! ## What's coming next in SAMSON? We will introduce a few major developments soon, and we can't wait to announce them. Meanwhile, if you have feature requests or feedback, please [let us know](mailto:contact@samson-connect.net)! # December 2025 # December 2025 - 2025 Wrap-Up Welcome to the eighth edition of our monthly newsletter! For this December issue, we're taking a step back and highlighting the **biggest SAMSON milestones of 2025**. As always, make sure your SAMSON installation is up-to-date (from the menu: **Interface > Update SAMSON**, or with the [installer](https://www.samson-connect.net/download)). ## 2025 highlights ### SAMSON became free for non-commercial use One of the most impactful updates this year: **SAMSON and every SAMSON Extension on SAMSON Connect are now free for non-commercial use** (academic, nonprofit, education, and personal non-revenue projects). If you haven't switched yet, you can do it from the [Pricing page](https://www.samson-connect.net/pricing) on SAMSON Connect. ### Major releases: SAMSON 2025 R1, R2, and R3 2025 brought major core improvements across the platform: - **SAMSON 2025 R1** introduced major workflow upgrades for molecular design, including the **Interaction Designer**, **Pattern Builders**, an updated **Protein Aligner**, **Quick Groups**, and new visualization tooling and color schemes. - **SAMSON 2025 R2** expanded navigation and inspection with **Progressive Clipping**, plus new editors (including the **View editor** and **Point selection editor**). - **SAMSON 2025 R3** delivered quality-of-life enhancements like **Extended NSL**, improved Gaussian surfaces, and **clickable tooltips** with fast access to SAMSON AI. If you missed any of these releases, you can explore the full details in the release notes: - [SAMSON 2025 R1](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2025-r1/index.md) - [SAMSON 2025 R2](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2025-r2/index.md) - [SAMSON 2025 R3](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2025-r3/index.md) ## Platform & ecosystem highlights ### Better structure access and preparation workflows The redesigned **Structure Fetcher** (**Home > Fetch**) became a major productivity boost, expanding access to public databases and enabling **IUPAC/SMILES-to-3D conversion** directly into the document: [Structure Fetcher extension](https://www.samson-connect.net/extensions/6f5d45c5-e76e-cdc8-52d5-d2821c128be8) ### AI in SAMSON **SAMSON AI** kept improving throughout the year, including tighter integration with **NSL generation** and selection workflows: - [SAMSON AI](https://www.samson-connect.net/extensions/1bc73c8b-9bd3-802b-3630-6183b830db63) - [SAMSON AI commands](https://documentation.samson-connect.net/users/latest/samson-ai/index.md) - [Node Specification Language (NSL)](https://documentation.samson-connect.net/users/latest/nsl/index.md) ### Biomolecular structure prediction in a few clicks Structure prediction workflows continued to expand, including support for **Boltz-2** and streamlined job sharing and downstream interaction-diagram generation: - [Video tutorial: Boltz-2 in under five minutes](https://www.youtube.com/watch?v=KJVeCanq6AQ) ### Open science and community growth **Adenita** became **open source**, making it easier than ever for the community to contribute: - [Adenita on GitHub](https://github.com/1A-OneAngstrom/Adenita) - [Adenita extension](https://www.samson-connect.net/extensions/dda2a078-1ab6-96ba-0d14-ee1717632d7a) ## Partnerships and scientific extensions 2025 also reinforced SAMSON's mission as a platform connecting best-in-class tools and collaborators: - A new partnership with [**Prosilico AB**](https://prosilico.com/) brought ADME/PK modeling into SAMSON with [**ANDROMEDA Demo**](https://www.samson-connect.net/extensions/012af44d-f04d-5c31-0c32-7704800677a7). - The collaboration with the [**Orts group**](https://bionmr.univie.ac.at/) (Vienna University) delivered the [**Molecular Restrainer**](https://www.samson-connect.net/extensions/f09f42ea-0a8f-caa6-8497-dda5aefc0448) for streamlined postprocessing of NMR structures (see the [publication](https://www.mdpi.com/1422-0067/26/11/5091)). ## Recent updates A few noteworthy improvements that were recently shipped: - [**Interaction Designer**](https://www.samson-connect.net/extensions/52fe9e27-19f3-093b-4f4f-4c6aff880a77): you can now **rotate or flip interaction diagrams**, and diagram colors now match SAMSON's default atom colors using the **CPK** scheme. Check out [this short video](https://www.youtube.com/watch?v=o59A5U33OLI) to see it in action: - [**GROMACS Wizard**](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5): improved usability with **searchable advanced parameters** (name + description) and **direct links** to relevant GROMACS manual sections. - [**OpenMM Wizard**](https://www.samson-connect.net/extensions/b951ba8f-2f5e-d114-a635-f1c41af40fb7): updated to align with **OpenMM v8.4.0**. - [**NSL**](https://documentation.samson-connect.net/users/latest/nsl/index.md): new attributes for **D-amino acids** (`residue.dAminoAcid`) and **crystallization buffer agents** (`node.category crystallizationBufferAgent`). - [**Structure Validation**](https://www.samson-connect.net/extensions/d1bb4cfb-aeff-5ede-09dd-e59c722ac0cb): expanded aliases for better identification of non-standard amino acids on import. ## Documentation & learning resources To support faster onboarding, better workflows, and AI-enabled tooling, the documentation ecosystem continued to grow: - [Documentation Center](https://documentation.samson-connect.net/index.md) - [Tutorials](https://documentation.samson-connect.net/tutorials/index.md) - [User Guide: Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) - And plenty of focused tips on the blog: [blog.samson-connect.net](https://blog.samson-connect.net/) ## Coming next We're continuing to invest in major platform developments, with a focus on **workflow acceleration**, **automation**, and **new core capabilities**. If you have feature requests or feedback, please [let us know](mailto:contact@samson-connect.net)! Thank you for being part of our growing community! # November 2025 # November 2025 Welcome to the seventh edition of our monthly newsletter! We're here to keep you in the loop with the **latest SAMSON updates**, **new features**, and **what's coming next**. As always, make sure your SAMSON installation is up-to-date to benefit from the newest improvements (from the menu: **Interface > Update SAMSON**, or simply with the [installer](https://www.samson-connect.net/download)). ## Extension Updates - November Highlights We've rolled out several useful enhancements across SAMSON Extensions this month: - [**Interaction Designer**](https://www.samson-connect.net/extensions/52fe9e27-19f3-093b-4f4f-4c6aff880a77): You can now **rotate or flip interaction diagrams**. In addition, diagram colors now match the default SAMSON atom colors using the **Corey–Pauling–Koltun (CPK)** scheme. Check out [this short video](https://www.youtube.com/watch?v=o59A5U33OLI) to see it in action: - [**GROMACS Wizard**](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5): You can now **search advanced parameters** by name and description. We also added **direct links** to the relevant sections of the GROMACS manual for MD parameters. - [**OpenMM Wizard**](https://www.samson-connect.net/extensions/b951ba8f-2f5e-d114-a635-f1c41af40fb7): Updated (including new parameters) to reflect new features in **OpenMM v8.4.0**. - **Node Specification Language (NSL)**: New NSL attributes for **D-amino acids** (`residue.dAminoAcid`) and **crystallization buffer agents** (`node.category crystallizationBufferAgent`). - [**Structure validation**](https://www.samson-connect.net/extensions/d1bb4cfb-aeff-5ede-09dd-e59c722ac0cb): Expanded aliases for non-standard amino acid residues, improving identification when importing structures. ### Minor improvements We also shipped a number of smaller refinements and fixes, including updates in [**AutoDock Vina Extended**](https://www.samson-connect.net/extensions/1afc50e6-3567-fa25-1e09-415ebf4d05d7), [**PDB trajectory loader**](https://www.samson-connect.net/extensions/3cfd163d-9ea1-c195-60db-4bc38730850f), various importers, and other extensions. ## Documentation updates New and updated tutorials on SAMSON and SAMSON Extensions: - [**User Guide: Node Specification Language**](https://documentation.samson-connect.net/users/latest/nsl/index.md): descriptions of the new NSL attributes. You can also find [**many focused SAMSON tips on the blog**](https://blog.samson-connect.net/)! ## Coming next We will introduce a few major developments soon, and we can't wait to announce them. Meanwhile, if you have feature requests or feedback, please [let us know](mailto:contact@samson-connect.net)! Thank you for being part of our growing community! # October 2025 # October 2025 Welcome to the sixth edition of our monthly newsletter! We're here to keep you in the loop with the **latest SAMSON updates**, **new features**, and **what's coming next**. In case you missed it last month, **SAMSON 2025 R3** is out, and you can explore [what's new and enhanced](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2025-r3/index.md). Make sure to update to get the latest features (from the menu: **Interface > Update SAMSON**, or simply with the [installer](https://www.samson-connect.net/download)). We also made SAMSON and all extensions [free for non-commercial use](https://www.samson-connect.net/pricing), and we've been amazed by the incredible response from the community. **Please continue to spread the word**, as SAMSON is even better in [teams for collaborative work](https://documentation.samson-connect.net/users/latest/collaboration/index.md). ## Extension Updates - October Highlights We've rolled out several powerful updates to SAMSON Extensions this month: - [**Interaction Designer**](https://www.samson-connect.net/extensions/52fe9e27-19f3-093b-4f4f-4c6aff880a77): Improved interaction detection and enhanced stability. In particular, the new dynamic layout feature makes it easy (and very fun 😀) to customize interaction diagrams! Check out [this short video](https://www.youtube.com/watch?v=gHnIEBEj_wc) to see it in action: - [**SAMSON AI**](https://www.samson-connect.net/extensions/1bc73c8b-9bd3-802b-3630-6183b830db63): Smarter [NSL](https://documentation.samson-connect.net/users/latest/nsl/index.md) generation via the **Document View filter**, **Find** tool, and **AI Assistant** (through the [AI commands](https://documentation.samson-connect.net/users/latest/samson-ai/index.md) `/nsl` and `/select`). - [**GROMACS Wizard**](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5): Now makes it possible to perform batch calculations for different systems at the same time (for different conformations of the same system, this was already possible for [umbrella sampling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/umbrella-sampling/index.md)). - [**OpenMM Wizard**](https://www.samson-connect.net/extensions/b951ba8f-2f5e-d114-a635-f1c41af40fb7): Now supports **OpenMM v8.4.0** for improved performance and features. - [**PDBFixer**](https://www.samson-connect.net/extensions/c81b69fc-4df0-fe09-146c-3591b20ba609): Updated to **PDBFixer v1.12** for better structure correction and compatibility. - [**Glycans visualization**](https://www.samson-connect.net/extensions/df5fa444-ccba-499d-34d7-226132340a25): Better recognition and display of diverse **monosaccharide classes**. ### Minor improvements There were several improvements in [**Molecular Motif Grafter**](https://www.samson-connect.net/extensions/66e0ec76-b7e3-62e2-298f-ba5323167913), [**Brenner interaction model**](https://www.samson-connect.net/extensions/ad608cb6-6971-7cd4-6fcc-34531998e743), and various importers (e.g., to import coarse-grained systems). Also, the transparency of silhouettes is now **independent of the transparency of the contoured objects**: To control the transparency of silhouettes (and their color, thickness, etc.), head to **Interface > Preferences > Rendering > Silhouettes**. To learn more, head to the corresponding [documentation page](https://documentation.samson-connect.net/users/latest/rendering-effects/#silhouettes). ## Documentation updates Stay on top of your workflow with updated guides and tutorials: - [**Node Specification Language (NSL)**](https://documentation.samson-connect.net/users/latest/nsl/index.md): descriptions of new NSL attributes. - [**GROMACS Wizard: Preparing and simulating protein-ligand systems**](https://documentation.samson-connect.net/tutorials/gromacs-wizard/protein-ligand-systems/index.md). - [**GROMACS Wizard: Batch computations**](https://documentation.samson-connect.net/tutorials/gromacs-wizard/batch-computations/index.md). You can also find [**many focused SAMSON tips on the blog**](https://blog.samson-connect.net/)! ## Upcoming Events **Stephane Redon** (CEO) and **Dmitriy Marin** (CSO) will be at the [Drug Discovery Chemistry (Europe)](https://www.drugdiscoverychemistry.com/europe) conference in **Barcelona, Spain, November 11–13, 2025**. Want to discuss how SAMSON can integrate your resources and streamline molecular design? [Schedule a chat](https://calendly.com/oneangstrom/chat-with-stephane) with them. ## Coming next We will introduce a few major developments before the end of the year, and we can't wait to announce them. Meanwhile, if you have feature requests or feedback, please [let us know](mailto:contact@samson-connect.net)! Thank you for being part of our growing community! # September 2025 # September 2025 This is the fifth issue of our **new monthly newsletter**, and we have **a huge announcement** to make: ## SAMSON is now **free for non-commercial use!** Starting this week, we are making the entire SAMSON molecular design platform - **SAMSON + every SAMSON Extension on SAMSON Connect - free for non-commercial use**. This means you can now use SAMSON **at no cost** in academic and nonprofit settings for: - **Education** (teachers, students, classrooms) - **Academic & publicly funded research** - **Personal projects** (no revenue, no paid consulting) If this is your case, you can activate your free non-commercial license **yourself** by [visiting the Pricing page](https://www.samson-connect.net/pricing) on SAMSON Connect and clicking on the **Switch to free non-commercial license** button (which becomes visible when you sign in): This will grant you a **free Expert plan** (the new name of the Ensemble plan) and make all SAMSON Extensions free to add on SAMSON Connect. This includes extensions for docking, simulating, animating, scripting, etc. (as you know, most features run locally, but some optional calculations run in the cloud, such as structure prediction and cloud simulations - these require computing credits). When your work involves paid services, consulting, product development, or commercial R&D, just [visit the Pricing page](https://www.samson-connect.net/pricing) and select one of the commercial plans. You can later revert to non-commercial use. If you are unsure whether you are eligible for a free non-commercial license, please just reply to this email and we'll work it out with you. Of course, **feel free to share the news with your friends, students, and colleagues** (and everyone else 😊). ## SAMSON 2025 R3 is now available This is a small release, as the upcoming data science features are still in development, but it has several quality-of-life improvements, including: - **Extended NSL**: the Node Specification Language has more attribute spaces and attributes, to facilitate further advanced selections. You can learn more about this in the corresponding [documentation page](https://documentation.samson-connect.net/users/latest/nsl/index.md) (and **SAMSON AI** can convert your natural language queries into NSL expressions 😉 : just use the /nsl command, or even the **/select** command to directly select whatever is matched by the NSL expression). - **Improved Gaussian surfaces**: the surface topology has been improved when ligands are covalently bound to proteins. - **Clickable tooltips**: all links contained in tooltips are now clickable when the tooltips appear while hovering a command (before, the links were only clickable when the tooltips were shown as results of **Find everything**). We also added a shortcut to ask SAMSON AI in each tooltip: Clicking the tooltip automatically asks SAMSON AI for a description (in case the one in the tooltip is not sufficient), tips and examples: ## SAMSON Cloud SAMSON Cloud images now include **GROMACS 2025.3**. Want to run GROMACS in the cloud? Try our [**GROMACS Wizard**](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5) or [contact us](mailto:contact@samson-connect.net). We've also rolled out service updates for **Boltz 2** and **Chai-1**. ## SAMSON Extensions ### What's new Many SAMSON extensions were updated this month: - [**GROMACS Wizard**](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5): Now ships the **GROMACS 2025.3** + UI refinements. - [**Interaction Designer**](https://www.samson-connect.net/extensions/52fe9e27-19f3-093b-4f4f-4c6aff880a77): Cleaner layout; layout optimization can now run **interactively**. - [**Glycans visual model**](https://www.samson-connect.net/extensions/df5fa444-ccba-499d-34d7-226132340a25): Improved path-tracing; apply materials like **metal, glass**, and more for richer renders. - [**Martinize**](https://www.samson-connect.net/extensions/0753f4e9-00ce-ae5b-eefd-d95f3e0c29bd): Updated to **martinize2 v0.15.0**. - [**Batch Protein Prepare**](https://www.samson-connect.net/extensions/3f6ef072-517f-cdbe-ad3e-d8a33370d1ed): Better performance and reliability on large protein libraries. ### Minor improvements [**SAMSON AI Assistant**](https://www.samson-connect.net/extensions/1bc73c8b-9bd3-802b-3630-6183b830db63), **Secondary Structure visual models**, [**Polyhedral visual model**](https://www.samson-connect.net/extensions/34ac539f-a754-8f06-a1ed-540d25e9d0c7), [**AutoDock Vina Extended**](https://www.samson-connect.net/extensions/1afc50e6-3567-fa25-1e09-415ebf4d05d7), and various importers. ## Upcoming Events **Stephane Redon** (CEO) and **Dmitriy Marin** (CSO) will be at the [Drug Discovery Chemistry (Europe)](https://www.drugdiscoverychemistry.com/europe) conference in **Barcelona, Spain, November 11–13, 2025**. Want to discuss how SAMSON can integrate your resources and streamline molecular design? [Schedule a chat](https://calendly.com/oneangstrom/chat-with-stephane) with them. ## Coming next We will introduce a few major developments before the end of the year, and we can't wait to announce them. Meanwhile, if you have feature requests or feedback, please [let us know](mailto:contact@samson-connect.net)! Thank you for being part of our growing community! # August 2025 # August 2025 This is the fourth issue of our **new monthly newsletter**, designed to keep you up-to-date on the latest SAMSON developments, new features, collaborations, and upcoming events. ## Power Fetcher SAMSON's [**Structure Fetcher**](https://www.samson-connect.net/extensions/6f5d45c5-e76e-cdc8-52d5-d2821c128be8) (**Home > Fetch**) has been completely redesigned and significantly expanded. You can now download structures from the [RCSB Protein Data Bank](https://rcsb.org/), the [AlphaFold Protein Structure Database](https://alphafold.ebi.ac.uk/), the [ESM Metagenomic Atlas](https://esmatlas.com/), [PubChem](https://pubchem.ncbi.nlm.nih.gov/), and the [Crystallography Open Database](https://www.crystallography.net/cod/), directly from SAMSON. You can now also **convert IUPAC and SMILES** into 3D structures that are **automatically added to the document**. ## Extensions Updates ### Enhanced Features Many SAMSON extensions were updated this month: - [**SAMSON AI**](https://www.samson-connect.net/extensions/1bc73c8b-9bd3-802b-3630-6183b830db63) now embeds GPT-5 for all users. Professional and Enterprise users also benefit from [advanced AI commands for literature, scripting and modeling](https://documentation.samson-connect.net/users/latest/samson-ai/index.md). - [**Adenita**](https://www.samson-connect.net/extensions/dda2a078-1ab6-96ba-0d14-ee1717632d7a): this popular SAMSON extension for modeling and visualizing DNA nanostructures is now [open source](https://github.com/1A-OneAngstrom/Adenita)! Feel free to contribute! - [**3D-SNFG visualization for glycans**](https://www.samson-connect.net/extensions/df5fa444-ccba-499d-34d7-226132340a25): Now supports path-tracing with Cycles, the integrated renderer from Blender (**Visualization > Trace**). - [**Structure Validation**](https://www.samson-connect.net/extensions/d1bb4cfb-aeff-5ede-09dd-e59c722ac0cb): Handles more non-standard residue aliases (e.g., from CpHMD). - [**Pathlines**](https://www.samson-connect.net/extensions/d319e2f3-0afc-07ab-0b64-71eb19d7ee2f): Now supports transparency, path-tracing, and exposes new functionality. - [**Python Scripting**](https://www.samson-connect.net/extensions/7b654ce6-e38c-b97f-6746-4fd6934487c2): New functionality to fetch structures from data banks (`SAMSON.fetch()`) and select nodes in SAMSON (`SAMSON.select()`). ### Bug Fixes We've resolved issues across several extensions, including [**GROMACS Wizard**](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5) and [**OpenMM Wizard**](https://www.samson-connect.net/extensions/b951ba8f-2f5e-d114-a635-f1c41af40fb7), ensuring smoother performance. ## Documentation Updates A new tutorial is available to learn how to use AlphaFold 2, Boltz-2, and Chai-1x directly from SAMSON: [**Predict Biomolecular Structures**](https://documentation.samson-connect.net/tutorials/bsp/bsp/index.md). Explore more on our [Tutorials Page](https://documentation.samson-connect.net/tutorials/index.md). ## Webinar Recording Missed our Summer webinar introducing SAMSON 2025 R1 and R2? [Watch it on YouTube](https://www.youtube.com/watch?v=kGW1_t0GXYo&ab_channel=SAMSONConnect) . ## Upcoming Events **Stephane Redon**, CEO of OneAngstrom, will be introducing SAMSON in the [Seminar on Digitalisation and Automation in Chemistry](https://www.fhnw.ch/en/continuing-education/lifesciences/digitalisation-and-automation-in-chemistry) at FHNW in Muttenz, Switzerland (September 8–12, 2025). ## Coming Soon: SAMSON 2025 R3 We're preparing SAMSON 2025 R3! Your feedback is vital - [let us know](mailto:contact@samson-connect.net) your feature requests. Thank you for being part of our growing community! # July 2025 # July 2025 This is the third issue of our **new monthly newsletter**, designed to keep you up-to-date on the latest SAMSON developments, new features, collaborations, and upcoming events. ## Learn Boltz-2 in under five minutes **Boltz-2** is now available in SAMSON, and a new [video tutorial](https://www.youtube.com/watch?v=KJVeCanq6AQ) explains how to use it, how to share job results with colleagues, and how to generate protein-ligand interaction diagrams - all in under five minutes. ## Extensions Updates ### Enhanced Features Many SAMSON extensions were updated this month: - [**Biomolecular Structure Prediction**](https://www.samson-connect.net/extensions/775e79a8-6adc-09c5-081a-faf34c87dc93): besides now supporting the **Boltz-2** model, the different services feature enhanced input validation (including CCD codes via RCSB), and easy chain selection. - [**Interaction Designer**](https://www.samson-connect.net/extensions/52fe9e27-19f3-093b-4f4f-4c6aff880a77): View protein segments for residues in binding sites, enhancing clarity and analysis. - [**Batch Protein Prepare**](https://www.samson-connect.net/extensions/3f6ef072-517f-cdbe-ad3e-d8a33370d1ed): Now supports entire folders of structural files (PDB, PDBx/mmCIF, MMTF, MOL2). - [**Martinize**](https://www.samson-connect.net/extensions/0753f4e9-00ce-ae5b-eefd-d95f3e0c29bd): Integrated `vermouth-martinize` updated to v0.14.0. - [**OpenMM Wizard**](https://www.samson-connect.net/extensions/b951ba8f-2f5e-d114-a635-f1c41af40fb7): Updated to OpenMM v8.3.1, including CHARMM36 2024 and new water models. - [**Adenita**](https://www.samson-connect.net/extensions/dda2a078-1ab6-96ba-0d14-ee1717632d7a): New CanDo format exporter and standardized nucleic acid residue naming. - [**ARAP Interpolator**](https://www.samson-connect.net/extensions/d550a902-3427-8788-ddd7-14d6c0e2c140): Enhanced exporting, now includes the entire interpolation path in a single PDB file. - [**Fetch / Protein Structure Downloader**](https://www.samson-connect.net/extensions/6f5d45c5-e76e-cdc8-52d5-d2821c128be8): Supports extended PDB codes and offers a streamlined user interface. - [**3D-SNFG visualization for glycans**](https://www.samson-connect.net/extensions/df5fa444-ccba-499d-34d7-226132340a25): Consistent shape sizing improvements. - [**Default visual preset enhancements**](https://www.samson-connect.net/extensions/6e879690-8bfb-4e18-b3c5-1ac0c317e9dd): Quick-access node groups for ligands, water, ions, DNA, RNA, lipids, and glycans are now created automatically, with improved glycan visualization. ### Bug Fixes We've resolved issues across several extensions, including [**Python Scripting**](https://www.samson-connect.net/extensions/7b654ce6-e38c-b97f-6746-4fd6934487c2), [**AutoDock Vina Extended**](https://www.samson-connect.net/extensions/1afc50e6-3567-fa25-1e09-415ebf4d05d7), [**Adenita**](https://www.samson-connect.net/extensions/dda2a078-1ab6-96ba-0d14-ee1717632d7a), [**SMILES Manager**](https://www.samson-connect.net/extensions/ce09650a-c071-4e84-1f6a-b8706937d5c1), and [**ARAP Interpolator**](https://www.samson-connect.net/extensions/d550a902-3427-8788-ddd7-14d6c0e2c140), ensuring smoother performance. ## Documentation Updates Updated tutorials available: - [**Protein alignment**](https://documentation.samson-connect.net/tutorials/protein-aligner/protein-aligner/index.md) - [**Generate a transition path between protein structures with ARAP interpolation**](https://documentation.samson-connect.net/tutorials/arap/arap-interpolation-for-protein-structures/index.md) - [**Create molecular boxes with Molecular Box Builder**](https://documentation.samson-connect.net/tutorials/molecular-box-builder/molecular-box-builder/index.md) - [**Build custom polymers with Polymer Builder**](https://documentation.samson-connect.net/tutorials/polymer-builder/polymer-builder/index.md) Explore more on our [Tutorials Page](https://documentation.samson-connect.net/tutorials/index.md). ## Webinar Recording Missed our Summer webinar introducing SAMSON 2025 R1 and R2? [Watch it on YouTube](https://www.youtube.com/watch?v=kGW1_t0GXYo&ab_channel=SAMSONConnect) . ## Upcoming Events **Stephane Redon**, CEO of OneAngstrom, will be present at the ACS Fall Meeting in Washington, DC (August 17–21, 2025). To discuss how SAMSON can help you integrate all your resources and streamline your molecular design workflows, you can [schedule a chat](https://calendly.com/oneangstrom/chat-with-stephane) with him. ## Coming Soon: SAMSON 2025 R3 We're preparing SAMSON 2025 R3! Your feedback is vital - [let us know](mailto:contact@samson-connect.net) your feature requests. Thank you for being part of our growing community! # June 2025 # June 2025 This is the second issue of our **new monthly newsletter**, designed to keep you up-to-date on the latest SAMSON developments, new features, collaborations, and upcoming events. ## SAMSON 2025 R2 is now available Discover detailed improvements in the latest update by viewing the [Release Notes](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2025-r2/index.md). Update directly from SAMSON via **Interface > Update SAMSON**, or download the latest installer from the [SAMSON Connect website](https://www.samson-connect.net/download). For developers Developers, please refer to the [v8.0.0 changelog](https://documentation.samson-connect.net/developers/latest/changelog/8.0.0/) for important updates affecting SAMSON Extensions. ## SAMSON 2025 Webinar Recording Available Explore the new features introduced in **SAMSON 2025 R1 and R2**, including: - Utilizing the new **View and Point selection editors**. - Inspecting structures with **Progressive Clipping**. - Designing 2D and 3D protein-ligand interaction diagrams using the updated Interaction Designer. - Efficiently creating complex designs with **Pattern Builders**. - Aligning multiple protein sequences and structures using the updated Protein Aligner, now integrated by default. - Managing selections with **Quick Groups**. - Enhancing visualizations using the new **color schemes**. [Watch the full webinar on YouTube](https://www.youtube.com/watch?v=kGW1_t0GXYo&ab_channel=SAMSONConnect) . ## SAMSON Extensions Updates ### Enhanced Features - [**AutoDock Vina Extended**](https://www.samson-connect.net/extensions/1afc50e6-3567-fa25-1e09-415ebf4d05d7): Now automatically sets receptors and ligands. - [**OpenMM Wizard**](https://www.samson-connect.net/extensions/b951ba8f-2f5e-d114-a635-f1c41af40fb7): Updated for OpenMM 8.3.0 with new force fields. - [**Interaction Designer**](https://www.samson-connect.net/extensions/52fe9e27-19f3-093b-4f4f-4c6aff880a77): Improved label placement, easy hiding of interactions, and performance optimization. - [**PDB importer**](https://documentation.samson-connect.net/users/latest/supported-formats/index.md): Now supports a different order of atoms within residues in different models for trajectory loading. - [**Molecular Restrainer**](https://www.samson-connect.net/extensions/f09f42ea-0a8f-caa6-8497-dda5aefc0448): New generalized minimization stopping criteria. - [**Python Scripting**](https://www.samson-connect.net/extensions/7b654ce6-e38c-b97f-6746-4fd6934487c2): Updated API corresponding to updates in SAMSON v8.0.0 (see [changelog](https://documentation.samson-connect.net/scripting/latest/docs/changelog/Changelog-8.x.x.html)). ### Bug Fixes - Resolved various issues in [**Adenita**](https://www.samson-connect.net/extensions/dda2a078-1ab6-96ba-0d14-ee1717632d7a), [**SMILES Manager**](https://www.samson-connect.net/extensions/ce09650a-c071-4e84-1f6a-b8706937d5c1), and [**Twister**](https://www.samson-connect.net/extensions/8b38b2fd-de8d-f24a-36e7-7ac624173f9f). ## Documentation Updates New tutorials available: - [**Protein Preparation & Validation**](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md): Techniques for preparing and fixing protein systems prior to docking, simulations, and molecular-design tasks. - [**Molecular Restrainer: Energy Minimization of NMR-Derived Structures**](https://documentation.samson-connect.net/tutorials/molecular-restrainer/molecular-restrainer/index.md): Guide on rapid energy minimization of NMR-derived structures using the Universal Force Field (UFF) and NOE distance restraints. ## Coming Soon While **AlphaFold 2**, **Chai-1**, and **Boltz-1x** already make it possible to predict biomolecular structures in just a few clicks from SAMSON (**Home > Predict**), **Boltz 2**, the latest model that also **predicts binding affinities**, is being added right now and will become available very soon. As usual, you'll just have to restart your SAMSON to get the update. SAMSON 2025 R3, the upcoming release, will also introduce **major new core functionalities for data science**, and we can't wait to tell you more about it. Have suggestions or feature requests? [Let us know](mailto:contact@samson-connect.net). # May 2025 # May 2025 This is the first issue of our **new monthly newsletter**, designed to keep you up-to-date on the latest SAMSON developments, new features, collaborations, and upcoming events. ## New Partnership We're pleased to announce a new partnership between OneAngstrom and [**Prosilico AB**](https://prosilico.com/) to bring advanced ADME/PK modeling tools to SAMSON users. The first result of this collaboration is already available as a SAMSON Extension ([see below](#new)). ## SAMSON Extensions ### New - [**ANDROMEDA Demo**](https://www.samson-connect.net/extensions/012af44d-f04d-5c31-0c32-7704800677a7): developed with [Prosilico AB](https://prosilico.com/), this free extension predicts several human ADME/PK properties (3 of ~30 available in the full version). - [**Molecular Restrainer**](https://www.samson-connect.net/extensions/f09f42ea-0a8f-caa6-8497-dda5aefc0448): created with the [Orts group at Vienna University](https://bionmr.univie.ac.at/), this extension combines NMR restraints with interactive simulation to study protein-ligand interactions. [See publication](https://www.mdpi.com/1422-0067/26/11/5091). ### Updates - [**Importers Collection**](https://www.samson-connect.net/extensions/385fe362-adfd-ce55-95c0-4e63560efa29): you can now import `.smi` files with one SMILES code per line and optional molecule names. - [**Interaction Designer**](https://www.samson-connect.net/extensions/52fe9e27-19f3-093b-4f4f-4c6aff880a77): interactions are now shown in 3D and synchronized with the viewport. Interaction symbols are now also movable in 2D. - [**Python Scripting**](https://www.samson-connect.net/extensions/7b654ce6-e38c-b97f-6746-4fd6934487c2): new API features allow you to compute and manage hydrogen bonds programmatically. [See documentation](https://documentation.samson-connect.net/scripting/latest/docs/api/Modeling/StructuralModel/SBMStructuralModelNodeHydrogenBondGroup.html). - [**Animations**](https://www.samson-connect.net/extensions/1b8ac667-ccbf-9c80-8e28-a60565955273): the "Simulate" animation now exposes parameters like step size and frame steps in the Inspector. ### Bug Fixes - Resolved issues with the serialization of secondary structure visual models and animations, particularly when references to deleted nodes were present. ## SAMSON 2025 R1 (Patch v7.0.1) Available SAMSON v7.0.1 is now available. This patch includes: - Minor rendering improvements - Fixes for audio and microphone setup (especially on macOS) - Other small enhancements **To update**: use **Interface > Update SAMSON**, or [download the installer](https://www.samson-connect.net/download). For developers For developers of SAMSON Extensions: the [v7.0.1 changelog](https://documentation.samson-connect.net/developers/latest/changelog/7.0.0/) is available. ## Documentation Updates The [Documentation Center](https://documentation.samson-connect.net/index.md), [User Guide](https://documentation.samson-connect.net/users/latest/index.md), and [Developer Guide](https://documentation.samson-connect.net/developers/latest/) now include `llms.txt` and `llms-full.txt` files to support LLM-based tools and workflows. ## Upcoming Webinar: SAMSON 2025 We invite you to the upcoming [**SAMSON 2025 webinar**](https://1-a.io/samson2025), where we will introduce new features and workflows. **Highlights include**: - Creating 2D/3D protein-ligand interaction diagrams - Using Pattern Builders for faster design - Aligning protein sequences and structures with the updated Protein Aligner - Managing selections with Quick Groups - Applying new color schemes for better visualization **Date**: June 17, 2025. **Time**: 8 am PST, 11 am EST, 5 pm CET. [Register here](https://1-a.io/samson2025)! ## Coming Soon A preview of features currently in development: - **Progressive Clipping** for improved visibility control. [See post](https://x.com/StephaneRedon/status/1925763330934735138). > The upcoming release of SAMSON introduces progressive clipping, and I love using it. I think it enhances clarity even further, and the smooth transitions give a great sense of where you are. [pic.twitter.com/IfrW6bzpXX](https://t.co/IfrW6bzpXX) > > — Stephane Redon (@StephaneRedon) [May 23, 2025](https://twitter.com/StephaneRedon/status/1925763330934735138?ref_src=twsrc%5Etfw) - **New editors** for easier navigation: - **View editor** - **Point selection editor** Have suggestions or feature requests? [Let us know](mailto:contact@samson-connect.net). # Release Notes # SAMSON Release Notes Learn what's new in SAMSON from the release notes: - [SAMSON 2026 R1](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2026-r1/index.md) - [SAMSON 2025 R3](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2025-r3/index.md) - [SAMSON 2025 R2](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2025-r2/index.md) - [SAMSON 2025 R1](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2025-r1/index.md) - [SAMSON 2024](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2024/index.md) - [SAMSON 2023 R1](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2023-r1/index.md) - [SAMSON 2022 R2](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2022-r2/index.md) - [SAMSON 2022 R1](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2022-r1/index.md) - [SAMSON 2021](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2021/index.md) - [SAMSON 2020 R3](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2020-r3/index.md) - [SAMSON 2020 R2](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2020-r2/index.md) - [SAMSON 2020 R1](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2020-r1/index.md) # SAMSON 2026 R1 Release Notes # What's new in SAMSON 2026 R1 We are pleased to announce that **SAMSON 2026 R1 is out**! ## What's new **SAMSON 2026 R1** is a substantial update that expands what you can do in SAMSON and makes several existing workflows smoother and more robust. This release brings: - **Path Analyzer**: a new app for exploring paths and molecular dynamics trajectories; - support for **UMA Force Field** models directly in SAMSON; - smoother **SAMSON Cloud** workflows for jobs, downloads, and results; - richer handling of **periodic systems and path-based data**; - a broad set of usability, stability, and compatibility improvements. The follow-up **11.0.1** patch keeps the same overall scope while adding additional fixes and polish. ## Path Analyzer [**Path Analyzer**](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md) is a new SAMSON app for exploring paths and **molecular dynamics** trajectories directly inside your document. It combines an Analysis Builder, an Analysis Tray, and an interactive dashboard so you can go from a selection to useful plots **in just a few clicks**. Learn more Visit [User Guide - Path Analyzer](https://documentation.samson-connect.net/users/latest/path-analyzer/index.md) to learn more. ## Strain Explorer Use [**Strain Explorer**](https://www.samson-connect.net/extensions/e8137d0a-cefc-2e12-d436-97f831c0d4ad) to analyze how much a ligand relaxes from its starting conformation, compare local and global strain estimates, inspect a 2D strain map, and export results for reporting or further work in SAMSON. [**Strain Explorer**](https://www.samson-connect.net/extensions/e8137d0a-cefc-2e12-d436-97f831c0d4ad) is designed for ligand libraries stored in **SDF** files. It keeps the imported ligands in memory, computes strain values with either **UFF** or **UMA** backends, and displays the results in a sortable table with 2D depictions, SMILES, SDF properties, strain values, RMSDs, and status messages. Learn more Visit the [documentation page](https://documentation.samson-connect.net/tutorials/strain-explorer/strain-explorer/index.md) to learn more. ## UMA Force Fields [**UMA Force Field**](https://www.samson-connect.net/extensions/c5ec133e-ea81-74a0-3930-8c370acf4745) brings interactive energy and force evaluation with the UMA family of machine-learning atomistic models into SAMSON. This opens the door to more interactive workflows with modern ML-based atomistic models directly in the application. Learn more Visit the [UMA Force Fields tutorial](https://documentation.samson-connect.net/tutorials/uma-force-field/uma-force-field/index.md) to learn more. ## Webinar On **April 30**, a new **live webinar** will introduce **SAMSON 2026 R1** and its major features including in particular the [Path Analyzer](#path-analyzer), the [Strain Explorer](#strain-explorer), and the [UMA Force Fields](#uma-force-fields). To learn more and register, visit . **Date and time**: April 30, 2026, 8am PST, 11am EST, 5pm CET. ## SAMSON Cloud Working with cloud jobs is now smoother and more practical. SAMSON 2026 R1 improves the Job Manager so that tracking jobs, downloading logs and results, and reopening or importing downloaded outputs feels more integrated into the main workflow. These improvements are especially useful when you run remote computations and want to move quickly from a finished job to the corresponding results inside SAMSON. ## Improved path and trajectory workflows Beyond the new **Path Analyzer**, SAMSON 2026 R1 also improves the way path data is handled internally. Paths can now carry richer information, which benefits workflows involving trajectories, reaction paths, optimization paths, and other step-based structural data. In particular, path data can now retain more context related to masses, unit cells, and wrapped or unwrapped positions. In practice, this helps when reconstructing or analyzing structures across multiple steps. ## Handling of jobs, downloads, and results SAMSON 2026 R1 strengthens job-oriented workflows throughout the application. Jobs can be tracked more consistently, downloads are better integrated into the interface, and downloaded results can be opened or imported back into SAMSON more smoothly. These improvements are especially relevant when working with remote computations, fetched logs, or result files produced by extensions and services connected to SAMSON. ## Better support for periodic systems This release also improves support for structures that carry unit-cell information and use periodic boundary conditions. Workflows around periodic models are now more consistent across operations such as wrapping, centering, minimum-image calculations, and supercell-related manipulations. For users working with crystalline or otherwise periodic systems, this should make it easier for tools and extensions to preserve and reuse the relevant unit-cell context. ## Stability, usability, and compatibility This release also includes a set of smaller but important improvements throughout the application and bundled components, including: - smoother behavior in parts of the window and tooltip handling; - more complete built-in structural-model actions; - safer handling of some neighbor-search edge cases; - fixes so that built-in default animations no longer overload the undo history; - follow-up fixes in 11.0.1, including more reliable platform and GPU information reporting. ## Extensions and ecosystem updates **SAMSON 2026 R1** also comes with a broad set of updates across the extension ecosystem. Highlights include: - [**Python Scripting**](https://www.samson-connect.net/extensions/7b654ce6-e38c-b97f-6746-4fd6934487c2): exposes more SAMSON functionality and makes it easier to discover and reuse exposed extension functionality through the updated [**Exposed Functionality Viewer**](https://www.samson-connect.net/extensions/92c88bef-d33d-3eab-2380-1d4b1788ac1b). - **Importers**: several importers now reconstruct a more meaningful hierarchy from flat atomic file formats, and some of them also identify covalent bond types more accurately. - **Secondary Structure visual models**: improved support for DNA secondary structure and related refinements. - [**GROMACS Wizard**](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5): now supports user-provided index group files during preparation and subsequent steps. - [**Extension Generator**](https://www.samson-connect.net/extensions/b0d9900c-b058-e7fa-4c31-d85f18b9c4e2): updated for the new SAMSON SDK version. - [**Crystal Creator**](https://www.samson-connect.net/extensions/58a75a78-abbc-2c60-6214-e668b5c45a0d): improved crystal loading, preserved more export-relevant metadata, and significantly improved CIF export. - [**OpenMM Wizard**](https://www.samson-connect.net/extensions/b951ba8f-2f5e-d114-a635-f1c41af40fb7): updated to OpenMM v8.5.1 and improved GPU detection on Windows. Other improvements include updates in various importers and exporters, [**Interaction Designer**](https://www.samson-connect.net/extensions/52fe9e27-19f3-093b-4f4f-4c6aff880a77), [**Conformer Creator**](https://www.samson-connect.net/extensions/61904544-0f7f-d3ba-3cb3-6c517c4af9bf), [**Polymer Builder**](https://www.samson-connect.net/extensions/4593e178-6d31-49ba-f3bb-3a91215f7117), and more. ## Documentation The documentation has also been updated across the [User Guide](https://documentation.samson-connect.net/users/latest/index.md), [extension tutorials](https://documentation.samson-connect.net/tutorials/index.md), the [Python Scripting Guide](https://documentation.samson-connect.net/scripting/latest/index.html), and the [Developer Guide](https://documentation.samson-connect.net/developers/latest/). ## For developers The SAMSON SDK also evolves significantly in this release, with new APIs around periodic systems, richer path data, job integration, extension parameter handling, and introspection. See the [Developer Guide: Changelog](https://documentation.samson-connect.net/developers/latest/changelog/). ## Get SAMSON This is an overview, and **SAMSON 2026 R1** also provides a variety of new features and fixes of reported issues. **SAMSON 2026 R1** also incorporates updates in default extensions released after the previous release. Already have SAMSON? Just restart it and you will be offered to update: follow the steps and your installation will be upgraded to the latest SAMSON. Do not have SAMSON? [Create your free account](https://www.samson-connect.net/signUp) and download SAMSON. You'll be all set and ready to go within a few minutes. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # SAMSON 2025 R3 Release Notes # What's new in SAMSON 2025 R3 We are pleased to announce that **SAMSON 2025 R3** is out. ## What's new This is a small release, as the upcoming data science features are still in development, but it has several quality-of-life improvements, including: - **Extended NSL**: the Node Specification Language has more attribute spaces and attributes, to facilitate further advanced selections. You can learn more about this in the corresponding [NSL documentation page](https://documentation.samson-connect.net/users/latest/nsl/index.md) (and **SAMSON AI** can convert your natural language queries into NSL expressions 😉 : just use the /nsl command, or even the **/select** command to directly select whatever is matched by the NSL expression). - **Improved Gaussian surfaces**: the surface topology has been improved when ligands are covalently bound to proteins. - **Clickable tooltips**: all links contained in tooltips are now clickable when the tooltips appear while hovering a command (before, the links were only clickable when the tooltips were shown as results of **Find everything**). We also added a shortcut to ask SAMSON AI in each tooltip: Clicking the tooltip automatically asks SAMSON AI for a description (in case the one in the tooltip is not sufficient), tips and examples: ## For developers This release does not have major changes in SAMSON API - the changes are mainly internal improvements. See the [Developer Guide: Changelog](https://documentation.samson-connect.net/developers/latest/changelog/). ## Get SAMSON This is an overview, and **SAMSON 2025 R3** also provides a variety of new features and fixes of reported issues. **SAMSON 2025 R3** also incorporates updates in default extensions released after the previous release. Already have SAMSON? Just restart it and you will be offered to update: follow the steps and your installation will be upgraded to the latest SAMSON. Do not have SAMSON? [Create your free account](https://www.samson-connect.net/signUp) and download SAMSON. You'll be all set and ready to go within a few minutes. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # SAMSON 2025 R2 Release Notes # What's new in SAMSON 2025 R2 We are pleased to announce that **SAMSON 2025 R2** is out. ## Progressive clipping **SAMSON 2025 R2** features **progressive clipping**, a new way to automatically control visibility when visualizing structures: > The upcoming release of SAMSON introduces progressive clipping, and I love using it. I think it enhances clarity even further, and the smooth transitions give a great sense of where you are. [pic.twitter.com/IfrW6bzpXX](https://t.co/IfrW6bzpXX) > > — Stephane Redon (@StephaneRedon) [May 23, 2025](https://twitter.com/StephaneRedon/status/1925763330934735138?ref_src=twsrc%5Etfw) ## New editors **SAMSON 2025 R2** introduces **two new editors** for easier navigation: - the **View editor** (shortcut `V`) for only moving around (click to rotate the view), - the **Point selection editor** (shortcut `P`) for a balance between visualizing and editing. These complement the Rectangle selection editor (shortcut `R`) which was previously available. You will now be able to choose which of these three editors is active when you start SAMSON for the first time: ## Webinar: Introducing SAMSON 2025 These new features will also be described in [the upcoming webinar **introducing SAMSON 2025**](https://1-a.io/samson2025). In this webinar, you will learn in particular: - How to create and edit 2D and 3D **protein-ligand interaction diagrams** using the new **Interaction Designer**. - How to use the new **Pattern Builders** to rapidly create advanced designs. - How to use the updated **Protein Aligner**, now included by default in SAMSON, to align multiple sequences and structures of proteins. - How to use the new **Quick Groups** to store and control selections. - How to use the **new colors schemes** to rapidly create advanced visualizations. **Date**: June 17, 2025. **Time**: 8am PST, 11am EST, 5pm CET. [Register here](https://1-a.io/samson2025) ! ## For developers The SAMSON API has been upgraded to expose the new functionalities of this release and let developers create extensions that they can distribute on [SAMSON Connect](https://www.samson-connect.net/). See the [Developer Guide: Changelog](https://documentation.samson-connect.net/developers/latest/changelog/). ## Get SAMSON This is an overview, and **SAMSON 2025 R2** also provides a variety of new features and fixes of reported issues. **SAMSON 2025 R2** also incorporates updates in default extensions released after the previous release. Already have SAMSON? Just restart it and you will be offered to update: follow the steps and your installation will be upgraded to the latest SAMSON. Do not have SAMSON? [Create your free account](https://www.samson-connect.net/signUp) and download SAMSON. You'll be all set and ready to go within a few minutes. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # SAMSON 2025 R1 Release Notes # What's new in SAMSON 2025 R1 We're excited to introduce **SAMSON 2025 R1**, a **major release** that brings a ton of new features and improvements throughout SAMSON. ## Webinar: Introducing SAMSON 2025 R1 [**Register** for the upcoming webinar **introducing SAMSON 2025**](https://1-a.io/samson2025). In this webinar, you will learn in particular: - How to create and edit 2D and 3D **protein-ligand interaction diagrams** using the new **Interaction Designer**. - How to use the new **Pattern Builders** to rapidly create advanced designs. - How to use the updated **Protein Aligner**, now included by default in SAMSON, to align multiple sequences and structures of proteins. - How to use the new **Quick Groups** to store and control selections. - How to use the **new colors schemes** to rapidly create advanced visualizations. **Date and time**: June 17, 2025, 8am PST, 11am EST, 5pm CET. Visit  to register! ## Interaction Designer SAMSON 2025 R1 introduces the [Interaction Designer](https://documentation.samson-connect.net/users/latest/interaction-designer/index.md) to **visualize and design molecules and interactions**. You can use this extension to understand **interactions between ligands and other molecules**, including proteins, water, chemical groups, etc., as well as **create and edit molecules in 2D**. ### Create interaction diagrams and molecules The [Interaction Designer](https://documentation.samson-connect.net/users/latest/interaction-designer/index.md) has two main modes: - **Creating interaction diagrams**: use the **Home > Diagram** command to automatically create an interaction diagram based on the current selection, or the whole document if nothing is selected. - **Creating new molecules in 2D**: use the **Edit > Design** command to start a new molecule. The [Interaction Designer](https://documentation.samson-connect.net/users/latest/interaction-designer/index.md) keeps the 2D documents synchronized with the 3D viewport: selecting, adding and removing atoms and fragments is performed in both 2D and 3D. ### Everything is editable Everything in the 2D diagram is editable: - You can move all labels and interaction symbols to control the diagram layout, as well as the caption. - You can hide and show interactions by clicking on their name in the caption. - You can change the interaction colors by double-clicking on their name in the caption. ### Easily export interaction diagrams You can save your interaction diagrams in various image formats, including png, jpg, jpeg, bmp, and svg. ### Interactions The [Interaction Designer](https://documentation.samson-connect.net/users/latest/interaction-designer/index.md) determines ligand pockets and various atom-atom, atom-plane, plane-plane, and group-group/plane interactions. See [User Guide: Interaction Designer](https://documentation.samson-connect.net/users/latest/interaction-designer/index.md) for more information. ## New functionality for building The arsenal of tools to [build molecular systems](https://documentation.samson-connect.net/users/latest/building-molecules/index.md) in SAMSON has become even larger making it now possible to [easily create complex patterns](#pattern-creation), [align and distribute structures](#align-and-distribute-structures), and thanks to [quick groups](#quick-groups) quickly memorize selections to easily switch between selections and perform complex operations on them. ### Pattern creation SAMSON 2025 R1 introduces [pattern building editors](https://documentation.samson-connect.net/users/latest/creating-patterns/index.md) to rapidly build advanced patterns. > The three new editors in the upcoming release of SAMSON (Linear pattern, Curved pattern and Circular pattern) make it possible to build complex molecular shapes in just a few clicks. We're excited to see what people will build with it! CC [@mooreth42](https://twitter.com/mooreth42?ref_src=twsrc%5Etfw) [@mechadense](https://twitter.com/mechadense?ref_src=twsrc%5Etfw) [@somewhereville](https://twitter.com/somewhereville?ref_src=twsrc%5Etfw) [pic.twitter.com/N4aoBPpK6t](https://t.co/N4aoBPpK6t) > > — Stephane Redon (@StephaneRedon) [March 11, 2025](https://twitter.com/StephaneRedon/status/1899495914496028729?ref_src=twsrc%5Etfw) You can find the [three pattern builders](https://www.samson-connect.net/extensions/8d2e17bf-c8f4-2118-d9df-4143eef7023e) in the editors toolbar on the left side of the viewport or via the *Find everything...* on top of SAMSON: - **Create circular pattern** editor (shortcut: `W`) - **Create curved pattern** editor (shortcut: `Q`) - **Create linear pattern** editor (shortcut: `L`) These editors makes it possible to rapidly create advanced patterns from selections: 1. Select the structures you want to replicate. This can be any number of atoms and bonds. 1. Use the widgets to translate and rotate the copies. You can press the `Ctrl` / `Cmd` key and click on a widget to enter a precise value for a translation or rotation. You can also use snap displacements to chosen lengths and angles. 1. Control the number of copies by clicking on the main UI widget. You can use the mouse wheel to increase and decrease this number. You can also press the `Ctrl` / `Cmd` key while using the wheel to increase and decrease the number of copies faster. 1. Press accept () to complete the model. In the main **Preferences**, you can go to **Edit > Create circular/curved/linear pattern** to choose: - whether copies are automatically merged when they are nearby, - whether hydrogen atoms are automatically adjusted, - whether copies create new structures or are combined with existing ones. ### Align and distribute structures SAMSON 2025 R1 introduces new commands to **align and distribute** atomic structures, meshes, and lights. You can find them in **Edit > Align** and **Edit > Distribute**. > Coming up in SAMSON, new commands to align and distribute structures. [pic.twitter.com/LfGB4gqjQ0](https://t.co/LfGB4gqjQ0) > > — Stephane Redon (@StephaneRedon) [March 14, 2025](https://twitter.com/StephaneRedon/status/1900391284973486306?ref_src=twsrc%5Etfw) You can also align with axes and planes using the **compass actions** - simply right-click on a compass widget to access the related commands for alignement. ### Quick groups SAMSON 2025 R1 introduces **Quick groups** to store selections and perform operations on them. They can be easily accessed from the **Document view** or via numberic shortcuts (`1`, `2`, ...) and allow you to quickly select associated nodes and perform complex selections. ## Updates in the Interface The main **Preferences** window now integrates the search making it easier for you to find the settings you are looking for. Now, directly in the main **Preferences**, you can access the settings for apps, editors, importers, exporters, that expose them. For apps that expose such settings, you can also quickly access them via their window toolbar - simply click on the gear icon (). ## Updates in visualizations - New color schemes (you can find them in **Visualization > Color**): - *per structural model*, - *per structural model (illustrative)*, - *CPK with constant carbons per structural model*. - Improved performance: parallel implementation of *Solvent Excluded Surface (S.E.S.)* and *Solvent Accessible Surface (S.A.S.)* visual models. - The changes of default visual model properties are now undoable. - New color palette - *pLDDT* - for colorization of confidence of structures predicted with AlphaFold, etc. - Optimizations in rendering. - Fixes in the *Stereo mode*. ## Revised Protein Aligner SAMSON 2025 R1 comes with an updated [Protein Aligner](https://www.samson-connect.net/extensions/0bee42d5-181b-b366-39a5-36607f0b5731) that lets you align multiple sequences and structures of proteins. You can find it in **Home > Align**. ## Other updates Added support for [CALVADOS coarse grained models](https://github.com/KULL-Centre/CALVADOS) for protein and RNA systems. Imported structures, trajectories, conformations, and meshes now refer to the original, source, files, so you can better keep track of your work. Updated values for **fundamental physical constants** to the latest [2022 CODATA](https://codata.org/initiatives/data-science-and-stewardship/fundamental-physical-constants/). ## For developers The SAMSON API has been upgraded to expose the new functionalities of this release and let developers create extensions that they can distribute on [SAMSON Connect](https://www.samson-connect.net/). See the [Developer Guide: Changelog](https://documentation.samson-connect.net/developers/latest/changelog/). ## Get SAMSON This is an overview, and **SAMSON 2025 R1** also provides a variety of new features and fixes of reported issues. **SAMSON 2025 R1** also incorporates updates in default extensions released after the previous release. Already have SAMSON? Just restart it and you will be offered to update: follow the steps and your installation will be upgraded to the latest SAMSON. Do not have SAMSON? [Create your free account](https://www.samson-connect.net/signUp) and download SAMSON. You'll be all set and ready to go within a few minutes. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # SAMSON 2024 Release Notes # What's new in SAMSON 2024 **SAMSON 2024** is a **major release** that brings a ton of new features and improvements throughout SAMSON and [SAMSON Connect](https://www.samson-connect.net/): [Part I - ✨ Core updates](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2024/core-updates/index.md): SAMSON 2024 introduces interactive Sequence Views, integrates GPT4o as a foundation for SAMSON AI, and has an upgraded Job Manager to handle cloud calculations (AlphaFold, NVIDIA BioNeMo Services, GROMACS, etc.). [Part II - 🌟 Visualization and Animation](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2024/visualization-and-animation/index.md): SAMSON 2024 has a completely redesigned Visual Preset Editor, new color schemes and color palettes, and two new powerful animation templates that enable simulation-based design. [Part III - 💡 Modeling](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2024/modeling/index.md): SAMSON 2024 has a significantly enriched Node Specification Language to perform quick, advanced selections, and offers a variety of quality-of-life improvements to editors. [Part IV - 🐍 Coding](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2024/coding/index.md): SAMSON 2024 offers new facilities to rapidly write and run Python scripts. [Part V - 👥 Collaboration](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2024/collaboration/index.md): SAMSON 2024 and [SAMSON Connect](https://www.samson-connect.net/) introduce many novel functionalities for collaborative work, from the creation of public or private profiles, groups, documents, and jobs, as well as Advanced Permissions Management to controllably share data with users and groups. ## Webinar: Introducing SAMSON 2024 Learn more from this webinar: [Introducing SAMSON 2024](https://www.youtube.com/watch?v=9fWndkgPy1Q) ## Get SAMSON This is an overview, and **SAMSON 2024** also provides a variety of new features and fixes of reported issues. **SAMSON 2024** also incorporates updates in default extensions released after the previous release. Already have SAMSON? Just restart it and you will be offered to update: follow the steps and your installation will be upgraded to the latest SAMSON. Do not have SAMSON? [Create your free account](https://www.samson-connect.net/signUp) and download SAMSON. You'll be all set and ready to go within a few minutes. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # What's new in SAMSON 2024 - Coding This is Part IV of [What's new in SAMSON 2024](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2024/index.md), the release notes for SAMSON 2024. ## New Python templates SAMSON 2024 introduces new Python templates, accessible from the **Code editor** (`Ctrl` / `Cmd` + `9`): ## Python code for SAMSON commands SAMSON 2024 makes it very easy to get the Python code corresponding to SAMSON commands. For example, to know the code corresponding to the **Add hydrogens** command, begin by searching the command in the **Find everything** box (`Shift`+`E`): and click on the **Copy icon** next to the message "This command is available as Python code". You can then use the code in the **Code editor** or in the **Python console** (`Ctrl` / `Cmd` + `8`). ## Python code for colorization SAMSON 2024 also makes it easy to access Python code corresponding to **color bars**: as well as to **Visual Presets**, by clicking on the **Copy as Python code** button: ## Next Go to [Part V about Collaboration](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2024/collaboration/index.md). # What's new in SAMSON 2024 - Collaboration This is Part V of [What's new in SAMSON 2024](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2024/index.md), the release notes for SAMSON 2024. ## Accessing collaboration features on SAMSON Connect With SAMSON 2024, SAMSON Connect () introduces a series of new features for collaboration. These new features are accessible from your **User menu** on [SAMSON Connect](https://www.samson-connect.net/): Here is an overview of the new functionalities: - **Profile**: you now have the possibility to create a user profile and make it public. - **Groups**: you can create an unlimited number of public or private groups, invite others, manage applications, etc. - **Documents**: you can upload an unlimited number of public or private documents on [SAMSON Connect](https://www.samson-connect.net/) (the total size limit varies based on your SAMSON plan), and you can control who you share these documents with. - **Jobs**: the jobs you run in the cloud from SAMSON (e.g., using AlphaFold, NVIDIA BioNeMo services, GROMACS, etc.) are now accessible from [SAMSON Connect](https://www.samson-connect.net/), and you can control who has access to them. ## Editing your Profile You can now create a **public profile** with a **public handle of your choice** (act quickly to reserve yours!), an extensive bio (20,000 characters allowed!), and links to your social networks (LinkedIn, 𝕏, ResearchGate, GitHub, etc.). Go to **Profile** to edit your profile: You can use Markdown to format your biography and include titles, links, images, etc. If public, your profile becomes accessible on [SAMSON Connect](https://www.samson-connect.net/): ## Creating and managing groups You can now create an unlimited number of private or public groups to easily share documents, jobs, extensions, etc. Go to **Groups** to manage your groups, including the ones you own or the ones you belong to: Provided you are a **group owner**, editing a group is similar to editing your profile. You can control the **group visibility**, as well as **how others join your group**: Being a group owner also lets you **edit group memberships**. In particular, you can change **group roles** and **membership end dates**: To add a new member to the group, click the **Add a member** button and search by username, full name or email address: If the invitee does not yet have a SAMSON account, you can still invite them by **entering their email address** and clicking **Add**. ## Uploading and sharing documents SAMSON 2024 makes it possible to upload documents to [SAMSON Connect](https://www.samson-connect.net/) while controlling the **document visibility**: On [SAMSON Connect](https://www.samson-connect.net/), you can manage the documents you published and the ones that have been shared with you by clicking **Documents** in your user menu: If you are a **document owner** or **document editor**, you can edit the document settings: If you are a **document owner**, you can also edit who can access the document by controlling its visibility (Public, Hidden or Restricted): and grant **access rights** to users: or directly to **groups**: ## Viewing and sharing jobs on SAMSON Connect The jobs you run in the cloud from SAMSON (e.g., using AlphaFold, NVIDIA BioNeMo services, GROMACS, etc.) are **now accessible from SAMSON Connect**, and **you can control who has access to them**. Like documents, a job can either be **Public**, **Hidden** (a link is needed to download the files) or **Restricted** (specific access rights must be granted to access the files or edit the job details). **By default, a job visibility is automatically set to Restricted**. On [SAMSON Connect](https://www.samson-connect.net/), you can manage the jobs you created and the ones that have been shared with you by clicking **Jobs** in your user menu: By clicking on a job, you can directly access the job files: and you can use the context menu to download job files: As with documents, you can edit the job details (name and notes) when you are a **job owner** or **job editor**. Similarly, you can grant access rights to a user or a group when you are a **job owner**. ## Get SAMSON This is an overview, and **SAMSON 2024** also provides a variety of new features and fixes of reported issues. **SAMSON 2024** also incorporates updates in default extensions released after the previous release. Already have SAMSON? Just restart it and you will be offered to update: follow the steps and your installation will be upgraded to the latest SAMSON. Do not have SAMSON? [Create your free account](https://www.samson-connect.net/signUp) and download SAMSON. You'll be all set and ready to go within a few minutes. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # What's new in SAMSON 2024 - Core updates This is Part I of [What's new in SAMSON 2024](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2024/index.md), the release notes for SAMSON 2024. ## Interactive Sequence Views SAMSON 2024 introduces **interactive Sequence Views** which are in sync with the document: residues selected in a Sequence View become selected in the Document View and the 3D Viewport, and vice versa. Furthermore, Sequence Views let you colorize residues in the sequence based on biophysical properties, and these colors can be transferred to the residues in the 3D Viewport: To access Sequence Views, either click the **View sequence** command from the **Home** menu: or right-click on a structure and select **Structural model > View sequence** from the **Context menu**: If a structure contains multiple chains, a pop-up will appear to let you choose which sequence(s) to view: ## SAMSON AI ✨ SAMSON AI is now based on GPT4o in the Professional plan. Please refer to the [User Guide](https://documentation.samson-connect.net/users/latest/samson-ai/index.md) for more information. ## Job Manager improvements The **Job Manager**, which lets you manage cloud calculations (for e.g., protein structure prediction using AlphaFold and NVIDIA BioNeMo Services, or molecular dynamics simulations using GROMACS), now makes it possible to download all job files by double-clicking the job: The Job Details view has been reorganized: and it is easier to edit the Job name and notes: which are automatically synced with your [SAMSON Connect](https://www.samson-connect.net/) Account. Finally, a job **Context menu** now gives you rapid access to local files (the ones that have already been downloaded), remote files (the ones stored in the cloud), as well as the job view on [SAMSON Connect](https://www.samson-connect.net/) (refer to [Part V](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2024/collaboration/index.md) for more information about sharing Job results): ## New User Guide and Tutorials For SAMSON 2024, the [User Guide](https://documentation.samson-connect.net/users/latest/index.md) on [SAMSON Connect](https://www.samson-connect.net/) is now using a new framework that makes it easier to browse: Furthermore, search is now **blazingly fast** and **extremely powerful**: [Tutorials](https://documentation.samson-connect.net/tutorials/index.md) for SAMSON extensions also use the new framework: ## Increased portability SAMSON 2024 introduces increased support for glibc2.17 libraries, allowing it to run on older Linux environments. ## Next Go to [Part II about Visualization and Animation](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2024/visualization-and-animation/index.md). # What's new in SAMSON 2024 - Modeling This is Part III of [What's new in SAMSON 2024](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2024/index.md), the release notes for SAMSON 2024. ## New selection commands SAMSON 2024 introduces **new selection commands** (for example to select polar hydrogens, etc.). All commands can be found in the **Select menu**: ## New selection modifiers As seen in the image above, the behavior of selection commands and selection modifiers is changed in SAMSON 2024: - By default, clicking on a selection command **empties the current selection** and creates a new selection. - Holding `Ctrl` / `Cmd` while clicking on the command **adds** to the current selection. - Holding `Alt` / `Option` while clicking on the command **removes** from the current selection. - Holding `Shift` while clicking on the command **intersects** with the current selection. ## Updates to the Node Specification Language SAMSON has a very powerful **Node Specification Language** (NSL) to specify selections of nodes. In SAMSON 2024, the NSL syntax is **significantly expanded** : - **Nodes categories**: nodes can now be matched by categories. For example, `n.c lig` matches all ligands, `n.c rec` selects all receptors and `n.c dna` selects DNA. - **Wildcard matches**: nodes can now be matched by name using wildcard (`*`). For example, `AL*` matches all nodes whose name begins with *AL*. - **Lists and ranges**: where relevant (e.g., residue id, chain id, atom serial number, atom formal charge, etc.), nodes can now be matched by specifying lists or ranges. For example, `r.id 1, 5:10, 12` matches residues whose id is either 1, 5, 6, 7, 8, 9, 10 or 12. - **Mathematical expressions** can now be part of NSL expressions. For example, `r.id 3*4:5*4` matches residues 12 to 20. - **New node attributes** are available: - **For chains**: `chain.formalCharge, chain.numberOfAtoms, chain.numberOfCoarseGrainedAtoms, chain.numberOfResidues, chain.numberOfStructuralGroups` - **For residues**: `residue.dna, residue.rna, residue.formalCharge, residue.numberOfAtoms, residue.numberOfCoarseGrainedAtoms` - **For structural groups**: `structuralGroup.formalCharge, structuralGroup.numberOfAtoms, structuralGroup.numberOfCoarseGrainedAtoms` - **For atoms**: `atom.polarHydrogen, atom.nonPolarHydrogen, atom.atomicNumber, atom.covalentRadius, atom.vanDerWaalsRadius, atom.mass, atom.electronegativity` - **Boolean attributes** do not require using `==` or `!=` anymore. For example `atom.fixed false` matches all mobile atoms. ## Construction The **Add editor** (shortcut `A`) now automatically chooses where atoms and bonds are located in a structure hierarchy. For example, when adding a methyl group to a tyrosine side chain, the added atoms are placed in the same side chain: The **Local Move** editor (shortcut `M`) now makes it easier to edit **dihedral angles**: click on the half of the bond corresponding to the fragment that you want to rotate, and edit the angle using the widget that appears: The **Twister** editor (shortcut `T`) now makes it straightforward to create handles based on selections and twist any structures: ## Next Go to [Part IV about Coding](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2024/coding/index.md). # What's new in SAMSON 2024 - Visualization and animation This is Part II of [What's new in SAMSON 2024](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2024/index.md), the release notes for SAMSON 2024. ## Visual Presets In SAMSON, **Visual Presets** are a powerful way to create complex visualizations in a few clicks. In SAMSON 2024, Visual Presets have been redesigned and made even more flexible and powerful. Each Visual Preset consists of a series of **steps**, and each step is composed of **four choices**: - **A selection** of nodes to which the step applies (e.g., "Heavy atoms and polar atoms in ligands") - **An optional set of actions** applied to the selection (e.g., "Hide", "Label atoms", "Zoom to", etc.) - **An optional visual model** applied to the selection (e.g., "Van der Waals", "Licorice", etc.) - **An optional color scheme** applied to the selection or the visual model (if added) (e.g., "Per chain", "Per occupancy", etc.) Visual Presets can be easily customized or created from scratch, with any number of steps, using the **Visual Preset Editor**: Given the importance of Visual Presets, they were made accessible from both the **Visualization menu** and the **Home menu**: Here is how the **Protein-ligand preset** looks like on PDB code `1AA1`: ## Colorization SAMSON 2024 introduces new color schemes. For example, the **Per element (custom carbons)** color scheme lets you choose a custom color for carbon atoms, but uses the default colors for all other atoms: SAMSON 2024 also introduces **discrete palettes**: as well as a **Color Vision Deficiency Emulator** visible whenever you choose a color palette: ## New rendering defaults The default rendering settings have been updated to increase the shininess of objects: As before, go to **Preferences > Rendering > Lighting** to edit settings: ## Combining animation and simulation for physically-based design **SAMSON's Animator** might be the most advanced dedicated tool to create molecular animations, with the possibility to animate molecules, cameras, shapes, etc. by combining **animation tracks** and controlling their **keyframes**. SAMSON 2024 introduces two new animation tracks to perform simulations **during animation**. Precisely, a new **Simulate** track performs a number of simulation steps (with a custom force field) **at each frame of an animation**. Combined with the possibility of precisely controlling atom paths, this makes it possible to **analyze ligand paths**, **prepare trajectories for umbrella sampling simulations**, or even **design nanosystems in a physically-based way**, by easily testing design hypotheses: > Simulating nanosystems helps designing them. In this example, the actuated part (in blue) of the nano gripper moves down too fast (1.7nm over 2.5ps -> 680m/s) and the gripper fails to grasp the cylinder. (Gripper design by [@mooreth42](https://twitter.com/mooreth42?ref_src=twsrc%5Etfw), who showed a successful grasp at a different… [pic.twitter.com/M5yKD7uA8T](https://t.co/M5yKD7uA8T) > > - Stephane Redon (@StephaneRedon) [May 8, 2024](https://twitter.com/StephaneRedon/status/1788013540466442709?ref_src=twsrc%5Etfw) A new **Record path** track also makes it possible to "bake" animated motions (resulting from other animation tracks, including the Simulate one) and avoid recomputing trajectories. ## Viewport updates The **Viewport Toolbar** has an increased number of options to quickly control the visibility of nodes: There is also a new **Rock** command to rock the viewport: Finally, it is now possible to **zoom into something by double-clicking on it** (all other methods continue to exist: `Shift` + left-click, toolbar commands, etc.). ## Next Go to [Part III about Modeling](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2024/modeling/index.md). # SAMSON 2023 R1 Release Notes # What's new in SAMSON 2023 R1 **SAMSON 2023 R1** is a **major release** that brings a ton of new features and improvements throughout SAMSON and various SAMSON extensions. In fact, this release has so many new features that, for the first time, we are splitting release notes into multiple parts: [Part I - ✨ SAMSON AI](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2023-r1/samson-ai/index.md): Imagine an intelligent assistant that doesn't just answer your questions but executes commands for you, all within the SAMSON platform. From quick selections to generating Python scripts, SAMSON AI is your new go-to modeling companion. [Part II - 🌟 Molecular Cycles](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2023-r1/molecular-cycles/index.md): Unveil the artist in you! With the integration of the Cycles Renderer from Blender, create stunning, studio-quality images and animations. Control materials, lights, and more for unparalleled visuals. [Part III - 🐍 Integrated Python Dev Environment](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2023-r1/integrated-python-development-environment/index.md): SAMSON Documents just went from static to dynamic! Now embed Python scripts, research papers, machine learning apps, and so much more. Share your documents, and let your colleagues or students run your apps with a single click! [Part IV - 💡 Interface redesign, and so much more](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2023-r1/interface-redesign-and-so-much-more/index.md): SAMSON 2023 R1 features a major redesign of the interface to offer a more streamlined experience, with numerous quality-of-life improvements. [Part V - ✅ New Pricing Structure](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2023-r1/new-pricing-structure/index.md): To reflect the major changes introduced in this SAMSON release, we have updated and simplified our pricing structure, and it gives you even more insane value than before! ## Get SAMSON This is an overview, and **SAMSON 2023 R1** also provides a variety of new features and fixes of reported issues. **SAMSON 2023 R1** also incorporates updates in default extensions released after the previous release. Already have SAMSON? Just restart it and you will be offered to update: follow the steps and your installation will be upgraded to the latest SAMSON. Do not have SAMSON? [Create your free account](https://www.samson-connect.net/signUp) and download SAMSON. You'll be all set and ready to go within a few minutes. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # What's new in SAMSON 2023 R1 - Integrated Python Development Environment This is Part III of [What's new in SAMSON 2023 R1](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2023-r1/index.md), the release notes for SAMSON 2023 R1. ## Integrated Python Development Environment ### 🐍 The Future of Research and Collaboration with SAMSON Prepare for a radical shift in the way you conduct and share research with SAMSON: the 2023 R1 release goes far beyond the boundaries of typical molecular modeling platforms to bring you a fully integrated **Python Development Environment**. This is not just an addition; it's a transformation that empowers you to create, collaborate, and communicate like never before. ### Ship-Ready Python Interpreter and High-Quality Editor Get coding right away with SAMSON's ship-ready **Python interpreter**. Say goodbye to setup hassles and hello to immediate productivity. The integrated **Monaco Editor**, from the beloved Visual Studio Code, offers you an intuitive and powerful coding experience, complete with syntax highlighting, auto-completion, and more. Want to test a piece of code? Click **Run** or use the integrated **Jupyter Qt Console** right within SAMSON for quick and easy execution. You get access to the entire SAMSON Python API and can even rapidly create Graphical User Interfaces using PyQt. Of course, SAMSON AI ✨ is here to assist you. ### SAMSON Documents: From Static to Executable SAMSON Documents are no longer just about storing and sharing molecular models. They now enable **Universal File Embedding** and can embed Python scripts and any number of files and folders. In short, SAMSON Documents have evolved into **rich, executable environments**. Imagine distributing a SAMSON Document that not only contains molecular models but also **research papers**, **custom analysis scripts**, **machine learning applications and models**, **images**, **data files** (even other **SAMSON Documents**!), and much more! ### A Revolution in Research Communication and Reproducibility What does this mean for the molecular modeling community? A massive leap forward in research communication and reproducibility. **Develop** a Python app for data analysis, molecular simulation, or even machine learning, and **embed** it directly within a SAMSON Document. **Share** it via email, GitHub, or the [SAMSON Connect](https://www.samson-connect.net/) website. Your colleagues can then open the document and run the embedded app(s) seamlessly. Think of the possibilities: - Professors can distribute SAMSON Documents containing both lecture notes and interactive Python-based exercises for students. - Researchers can attach executable data analysis scripts to their published molecular models, increasing transparency and reproducibility. - Teams can collaborate more effectively by sharing SAMSON Documents that include project files, meeting notes, and automated workflow scripts. - Educational institutions can create comprehensive, interactive learning modules that students can execute directly within SAMSON. SAMSON 2023 R1 doesn't just offer new features; it offers a new paradigm in computational research and education. ## Next Go to [Part IV about the Interface Redesign, and so much more](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2023-r1/interface-redesign-and-so-much-more/index.md) in SAMSON 2023 R1! # What's new in SAMSON 2023 R1 - Interface redesign, and so much more! This is Part IV of [What's new in SAMSON 2023 R1](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2023-r1/index.md), the release notes for SAMSON 2023 R1. ## 💡 Interface redesign, and so much more! SAMSON 2023 R1 features a major redesign of the interface to offer a more streamlined experience, with numerous quality-of-life improvements. ### Context toolbar Now, when selecting nodes in SAMSON, a new context toolbar gives you direct access to the frequently used commands. The toolbar makes it possible to rapidly access SAMSON AI, operate on the selection (zoom on it, select parents, descendants and connected components), as well as apply labels, materials and visualizations, and access the Inspector. ### Editors Editors (to select, build, move, twist, erase, label, measure, etc.) are now all conveniently located in the top-left part of the viewport: ### A Simpler Menu The main menu has been completely redesigned and simplified. It is now more hierarchical and makes it easier to locate important commands. And of course SAMSON AI knows it by heart and gives you direct access to commands. ### Selections We added more types of nodes and structures in the Node Specification Language (NSL). Now, to select, for example, a receptor using NSL simply type: "node.category receptor" or "n.c rec" for short. The following node categories are available: *receptor, ligand, lipid, water, ion, monatomicIon, polyatomicIon, glycan, hydrogensWithBonds*. You can find them in the selection filter and in the **Find** window. We added **new selection commands** and added **new modifiers to selection commands** to provide you with more possibilities. Try holding `Shift` (select among visible nodes only), `Alt` (select among hidden nodes only), or `Ctrl` (add to the current selection) when clicking on a selection command in the **Select menu** - see tooltips of commands for more information. ### Improved Visual Presets We made it easier to edit and create **Visual Presets** - which make it possible to apply complex, custom visualizations of your systems in a few clicks. ### Render Presets SAMSON 2023 R1 now makes it possible to save rendering settings (for ambient occlusion, shadows, blur, background, etc.) as **Render Presets** stored directly in SAMSON documents! Render presets can be accessed and modified using the **Inspector**. You can have multiple render presets per document and transfer them between documents. Simply double-click on a render preset to apply it. This has huge implications for shareability and reproducibility of images! To try rendering presets, go to **Visualization > Presets**. ## For developers The SAMSON C++ API has been upgraded to expose the new functionalities of this release and let developers create extensions that they can distribute on [SAMSON Connect](https://www.samson-connect.net/). See the [Developer Guide: Changelog](https://documentation.samson-connect.net/developers/latest/changelog/). Of course, you can now also use the SAMSON Python API and directly ship your Python apps as part of SAMSON documents. ## Next Go to [Part V about the New Pricing Structure](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2023-r1/new-pricing-structure/index.md), which gives you even more insane value than before. # What's new in SAMSON 2023 R1 - Molecular Cycles This is Part II of [What's new in SAMSON 2023 R1](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2023-r1/index.md), the release notes for SAMSON 2023 R1. ## Molecular Cycles 🌟: Studio-Quality Visuals Right Inside SAMSON The SAMSON 2023 R1 release brings another groundbreaking feature that will redefine your visualization experience. We're proud to announce the integration of the **Cycles Renderer from Blender**, a renowned, open-source 3D computer graphics software, into SAMSON. ### Studio-Quality Rendering for Images and Animations For the first time in SAMSON, you can now have stunning, studio-quality rendering for images and animations right within the platform. No need for external tools or complicated workarounds: the Cycles Renderer offers you photorealistic rendering capabilities that will take your visualizations to an entirely new level. And the best part? You activate Cycles in **just one click**. ### Material Control: Metal, Glass, Emissive and More A vital aspect of high-quality rendering is the ability to control materials. With the integrated Cycles Renderer, you can now customize a range of materials, from metallic surfaces to glass translucency and even emissive materials that glow. The power to create visually rich and scientifically accurate models is now at your fingertips. Materials are easily controlled in the **Inspector**, and **Appearance Presets** make it possible to change the look of your models in just a few clicks. ### Illuminate Your Work The Cycles Renderer provides you with advanced light and shadow controls, allowing you to set the mood and atmosphere for your renders. Whether it's a soft ambient light to highlight subtle features, powerful lights to accentuate details, or even colored lights, you can do it all. ### Advanced Rendering Effects Enhance your visual storytelling with special rendering effects like depth of field, which adds a cinematic touch by blurring out-of-focus regions. This can be especially useful for emphasizing focal points in your molecular models or simulations. Oh, and you can import 3D objects into SAMSON to render them alongside your molecules and create complex scenes: We believe that the integration of the Cycles Renderer in SAMSON is a game changer for both researchers and educators alike, offering an unparalleled level of quality and realism in visualization. Whether you're communicating your research to your colleagues, publishing your findings, giving talks or teaching, SAMSON 2023 R1 empowers you to do it in style. ## Next Go to [Part III about Integrated Python Development Environment](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2023-r1/integrated-python-development-environment/index.md), the future of research and collaboration with SAMSON. # What's new in SAMSON 2023 R1 - New Pricing Structure This is Part V of [What's new in SAMSON 2023 R1](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2023-r1/index.md), the release notes for SAMSON 2023 R1. ## ✅ New Pricing Structure To reflect the major changes introduced in this SAMSON release, we have updated and simplified our pricing structure, and it gives you even more insane value than before! First, the **Free Starter Plan** lets you do even more than before, with SAMSON AI, Molecular Cycles, Integrated Python Development Environment, and so much more! Second, to make things simpler, the **Standard Plan** is gone. All users currently on a Standard plan are automatically upgraded to the Professional Plan at the Standard rate! That's our way to thank our amazing community! Third, the **Professional plan**, with advanced AI features and commands (**Literature Assistant**, **Scripting Assistant**, **Molecular Modeling Agent**, **Voice Control**, and overall **more AI answers**), **advanced animation features**, and the possibility to add an **unlimited number of free extensions**, now has a **90% discount for academia** (use your professional academic email address when signing up to benefit from it automatically). This is a no-brainer. Fourth, the **Enterprise plan** now includes the possibility to get fine-tuned models for AI. [Contact us](https://calendly.com/oneangstrom/services) for more information! ## Get SAMSON This is an overview, and **SAMSON 2023 R1** also provides a variety of new features and fixes of reported issues. **SAMSON 2023 R1** also incorporates updates in default extensions released after the previous release. Already have SAMSON? Just restart it and you will be offered to update: follow the steps and your installation will be upgraded to the latest SAMSON. Do not have SAMSON? [Create your free account](https://www.samson-connect.net/signUp) and download SAMSON. You'll be all set and ready to go within a few minutes. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # What's new in SAMSON 2023 R1 - SAMSON AI This is Part I of [What's new in SAMSON 2023 R1](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2023-r1/index.md), the release notes for SAMSON 2023 R1. ## SAMSON AI ✨: Your Next-Generation Modeling Assistant We are thrilled to announce one of the most exciting features in SAMSON 2023 R1: **SAMSON AI**, a cutting-edge assistant powered by an LLM-based architecture integrating the OpenAI API. SAMSON AI isn't just another chatbot; it's an intelligent agent designed to make your molecular modeling experience as intuitive, efficient, and rewarding as possible. Here's how SAMSON AI sets itself apart from traditional language models like ChatGPT. ### Executable Documentation SAMSON AI is your go-to source for all things related to SAMSON and its various extensions. Whether you have a question about the user guide, scripting guide, developer guide, or anything in between, SAMSON AI has you covered. Even better, its responses come packed with **clickable commands** that you can execute right from the chat window. Imagine asking how to apply a van der Waals model: SAMSON AI not only tells you how but provides you with a clickable command to get it done instantly. Moreover, you'll find **links to relevant documentation pages** embedded within the AI's responses, so you can dive deeper whenever you want. SAMSON AI can assist you through all modeling stages, from visualization, editing and construction to simulation and analysis: You can also use SAMSON AI directly from the context toolbar, the **Document View**, or the **Find** window to help you with performing selections or finding nodes and structures using natural language. ### SAMSON AI as an Agent: Beyond Q&A While most chatbots are limited to answering your questions, SAMSON AI takes assistance a step further with its unique **AI commands**. Here's a quick rundown of these groundbreaking features: **/select**: Simply type this command followed by your natural language instruction to make precise selections within SAMSON. For example, say "select all aromatic bonds that are inside residues that are within 5 angstrom of ligands", and watch it happen in real-time. **/script**: Generate Python scripts effortlessly. With this command, SAMSON AI can draft Python scripts using the SAMSON API, tailored to your specific needs. It's scripting made easy! **/do**: Delegate tasks to your AI assistant. Whether you need to select a group of atoms or apply a visual model, type `/do`, followed by your task, and SAMSON AI will handle it for you. ### SAMSON AI is your Literature Assistant Three AI commands turn SAMSON AI into a powerful **literature assistant**. **/learn**: Feed SAMSON AI a URL pointing to a webpage or a PDF to study. Once it has processed the information (generally in less than a minute), you can ask the AI questions based on the newly acquired knowledge. This powerful command helps you get up to speed quickly on any topic, whether it is a research paper, the Python API of a package you would like to use, scientific data, etc. **/refer**: Use this command to query SAMSON AI about the information it has previously learned. It's like having a digital researcher by your side. **/forget**: All data absorbed with the **/learn** command is privately associated to your personal account (and only your account) and persists between SAMSON sessions. This makes it easier to work on larger-scale projects over longer durations. Decided that the AI no longer needs to remember specific information? Use the **/forget** command to make SAMSON AI forget all information you asked it to learn. Say you are interested in protein design, and you want to dive into a recent preprint: From the webpage, you get the link to the PDF and you enter **/learn** followed by the link: SAMSON AI processes the 54 pages in the PDF in a few seconds: and then it indicates that it has finished processing it: You can then ask questions about the learned document thanks to the **/refer** command. For example, we can ask how new protein backbones are generated in the learned method: Or we can ask whether the method applies to higher order oligomers: The **/learn** command can be used for even longer papers, including supplementary information. Consider the Supplementary Information in the Martini 3 paper in Nature methods: The supplementary information has 117 pages (!): We simply use the **/learn** command again: We can now ask specific questions about the Martini 3 force field, for example the number of different bead types: We can even ask about the recipe of the official Martini 3 cocktail, which the authors hilariously managed to sneak past the reviewers: The **/learn** command also works for regular webpages, including, e.g., documentation of Python packages. Let's **/learn** the RDKit documentation: We can now ask SAMSON AI how to generate 2D images of molecules from SMILES codes, and we get Python code! When you want to delete your knowledge base, you simply use the **/forget** command: To check that the knowledge base has been cleared, we can ask again about the Martini 3 cocktail recipe. This time, SAMSON AI is confused by its own previous answer and answers with a classic Martini cocktail recipe: ### Voice Control Last, but not least, you can also **use your voice** to prompt SAMSON AI! ## Next Go to [Part II about Molecular Cycles](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2023-r1/molecular-cycles/index.md), which lets you produce studio-quality visuals right inside SAMSON. # SAMSON 2022 R2 Release Notes # What's new in SAMSON 2022 R2 **SAMSON 2022 R2** brings numerous new features and improvements throughout the core of SAMSON and various SAMSON extensions. ## Workspaces One of the main immediately visible features of SAMSON 2022 R2 is **Workspaces**. Workspaces allow you to switch between various sets of menus, depending on your needs. By default, SAMSON 2022 R2 provides three workspaces: Compact (for smaller screen resolutions), Complete (for general-purpose molecular design), and Visualizer (when you use SAMSON to import structures and make publication-quality images): Workspaces make it extremely easy to customize the SAMSON interface. If you need a custom workspace for you or your team, just [let us know](https://1-a.io/support). Similarly, if you're a developer and you want to create your own workspaces and distribute them on [SAMSON Connect](https://www.samson-connect.net/), [let us know](https://1-a.io/support) as well! ## Document management ### Improved document performance Bond nodes in the **Document View** do not show shortcuts to the bonded atoms anymore. This leads to improved performance in a number of tasks related to the data graph, including importing structures and documents, selecting nodes, modifying the visibility of nodes, etc. Note that you can still access the connected atoms via the Inspector (`Ctrl`/`Cmd` + `2`) or the context menu. Since a Bond node does not have children anymore, double-clicking the bond in the document view will select it and will zoom on it. ### Switch between documents You can now switch between documents not only from the Home menu or using the shortcut (`Ctrl`/`Cmd` + `Tab`), but also via the top-left corner of SAMSON: ## Visualization ### New visual presets We added more default visual presets and selectors allowing you to create more sophisticated visual presets for quick visualization. ### New color palettes SAMSON has a new color palette type - a flexible diverging HCL color palette - available to both users and developers, and a set of corresponding default color palettes. These color palettes are accessible when applying custom color schemes or visual presets: ## Selection ### New selection commands New selection commands have been added, including **Select lipids**: and **Select glycans**: ### New and improved selectors SAMSON 2022 R2 adds still more selectors. You can now select ions by their names, select lipids, select glycans, and perform various advanced selections (e.g. Select heavy atoms of residues within 5A of ligands): SAMSON 2022 R2 also improves previously existing selectors. For example, selecting receptors and ligands better handles the cases with multiple covalently bound ligands. This gives you many new possibilities to create sophisticated visual presets for quick visualization. ### Updates to the Node Specification Language SAMSON's Node Specification Language (NSL) has been expanded to include new node attributes, for example, to select atoms based on their element types (e.g., `atom.halogen`). Please refer to the [documentation](https://documentation.samson-connect.net/users/latest/nsl/index.md) for more information. ## Exporting presentations When you have multiple presentations in a document, SAMSON makes it easier to let you choose which presentation should be exported to a movie or to a series of animation frames. ## Tips You can now provide feedback on Tips and help us improve them and provide you with better guidance. ## Improved modularity and support SAMSON 2022 R2 became even more modular than before, allowing us to react and bring you new features faster than ever before. Have a request? Don't hesitate to tell us, either using the **Feedback button** or by [discussing with us](https://1-a.io/feedback)! ## And more This is just a brief overview and **SAMSON 2022 R2** also provides a variety of new features and fixes of reported issues. - Improved handling of multiple threads in the UI. - Improved handling and saving of animation nodes fixing an issue when reference nodes were modified. - Improved hydrogen adjustment in the **Add editor** and in the **Add hydrogens** commands. - Improved the speed of the various **Find commands**, **Apps**, and **Editors**. **SAMSON 2022 R2** also incorporates updates in default extensions released after SAMSON 2022 R1, including for example in rendering of moving surfaces. Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). ## For developers The SAMSON API has been upgraded to expose the new functionalities of this release and let developers create extensions that they can distribute on [SAMSON Connect](https://www.samson-connect.net/). See the [Developer Guide: Changelog](https://documentation.samson-connect.net/developers/latest/changelog/). ## Get SAMSON If you already have SAMSON, just restart it and you will be offered to update: follow the steps and your installation will be upgraded to SAMSON 2022 R2. If not, [create your free account](https://www.samson-connect.net/signUp) and download SAMSON! You'll be all set and ready to go within a few minutes. # SAMSON 2022 R1 Release Notes # What's new in SAMSON 2022 R1 **SAMSON 2022 R1** brings numerous new features and improvements throughout the core of SAMSON, with a strong focus on user experience! ## Blazing fast startup First things first, starting SAMSON. As the SAMSON platform is growing and many of you like to customize your environment and add [extensions](https://www.samson-connect.net/extensions) to their installations, we felt it was time to reduce the SAMSON startup time. We are happy to announce that SAMSON now starts *an order of magnitude faster*, in just a few seconds! Make sure you click the splash screen fast enough to learn more about the tips! ## Visualization ### One-click Illustrate style Like many, we love David Goodsell's artwork, and we wanted to make it easy to depict molecules in a similar style. The new **one-click Illustrate** command applies visual models and color schemes, and adjusts rendering effects to approach his unique style. Go to the **Visualization menu** to find this command: Load a structure (for example 6S7O, [molecule of the month in February 2022](https://pdb101.rcsb.org/motm/266)), click the **Illustrate** command and, *voila*: In effect, the command scans the document to find receptors, ligands, ions, etc., applies various visual models and color schemes to them, and modifies rendering settings as well: Of course, all rendering parameters and colors can be modified, in particular using the **Inspector** (more below). When you're happy with your results (and **if you want to**), you can even **share your document online** (using the **Home menu**, or the shortcut `Ctrl` / `Cmd` + `Alt`+`S`): This helps you **promote your work**, and **helps others build on it**. Here is how the [shared document](https://www.samson-connect.net/documents/e412ec53-d2e7-4069-ad54-ef936542a956) looks like: ### Lighting presets SAMSON has numerous rendering effects and settings that make it easy to create publication-quality [images](https://documentation.samson-connect.net/users/latest/visualizing/index.md) and [animations](https://documentation.samson-connect.net/users/latest/presenting/index.md). A new command in the Effects group of the Visualization menu makes it easy to switch between different rendering presets and modify multiple settings simultaneously (shadows, ambient occlusion, silhouettes, background, etc.): For now, the command features three rendering presets: - Default: to reset all settings to their default settings. - High quality: which activates shadows, ambient occlusion, etc. - Illustrative: the group of settings used by the Illustrate command (but this setting does not add visual models to the document). ### Illustrative color schemes Along with the **Illustrate command** and the **Illustrative style**, two new **Illustrative color schemes** have been added. The **Constant illustrative** color scheme lets you choose a color, and uses different intensities of this color to make it easy to differentiate between atom types. In the example below, a van der Waals visual model was applied to 1AF6, and a constant illustrative color scheme was applied: Similarly, the **Chain illustrative** color scheme applies a different color per chain ID, with different intensities according to atom types. Here is what happens when applying such a color scheme to the van der Waals model: ### New color palettes SAMSON has new color palettes available to both users and developers. These color palettes are accessible when applying custom color schemes: ### Editing color schemes with the Inspector Colors and color schemes can now be added, removed, and edited in the **Inspector**! This makes it easy to identify which nodes own materials (in SAMSON, a material attached to a node - say, a chain - applies to all its descendants - residues, atoms, bonds, etc.). For example, here is what the **Inspector** shows when selecting the van der Waals mentioned above: In this example, clicking on the color bar in the **Inspector** gives you the possibility to control all color parameters: ### One-click Orbit SAMSON now has a one-click **Orbit** command (shortcut `O`): The command can be found both in the **Visualization** menu: and at the bottom of the Viewport: When the grid is shown, the camera always stays at the same height above (or under) the grid. When the grid is not shown, the camera orbits around the vertical axis passing through its target. Go to **Preferences > Rendering > Cameras** to change the orbit period. ## Selection ### A new Select menu SAMSON has many different ways to find and select nodes, including through selection editors, filters, commands, the [Node Specification Language](https://documentation.samson-connect.net/users/latest/selecting/#selecting-using-nsl), etc. To make it easier to locate and use the various ways of selecting things in SAMSON, we created a new **Select** menu that groups all relevant commands. ### Selecting connected atoms The new **Select** menu features the **Selected connected** command (shortcut `Shift`+`C`), which finds and selects all atoms and bonds in the same connected component as the currently selected atoms. This makes it easy to work with large structures, chains, polymers, etc.: just select a few atoms, press `Shift`+`C` and the corresponding connected components are fully selected. ### Selecting similar structures A new command was added to **Select similar structures**, based on their names and hierarchy (shortcut `Shift`+`S`). This is very convenient when working with proteins, polymers, or with systems that involve lots of similar species. For example, select one arginine, press `Shift`+`S`, and all arginines will be selected. This is also useful in combination with the **Select parents** command (shortcut `Shift`+`P`), which selects parent nodes. For example, select an oxygen atom in a water molecule, press `Shift`+`P`, then `Shift`+`S`, and all water molecules are selected. ### Expand A new **Expand menu command** gives you easy access to frequently used expansion operations: and the **Advanced...** command makes it possible to search by proximity (and gives you the equivalent [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) expression): ### Selection statistics The **Document View** now shows structural statistics corresponding to the current selection, including the number of selected atoms, residues, etc., as well as mass and charge information: ### Dynamic command enabling For improved clarity, commands that depend on selections are now disabled when nothing is selected. This makes it easier to see which commands are immediately relevant to the current selection. Here is the Select menu when nothing is selected: ### Updates to the Node Specification Language SAMSON's Node Specification Language (NSL) has been expanded to include new node attributes, for example, to know whether a node has a material (node.hasMaterial) and owns a material (node.ownsMaterial), to search bonds based on their type (bond.type), etc. Please refer to the [documentation](https://documentation.samson-connect.net/users/latest/nsl/index.md) for more information. ## Labeling ### Easier and extended labeling Labeling commands have been permanently moved to the context menu, even when the Label editor is not active. This makes it easier to apply labels to selected nodes, whatever editor is currently active. New label commands are also available, for example, to display atom charges: ### Custom fonts and colors In SAMSON 2022, each label can now have its own font and color, which can be modified in the **Inspector**: When labels have decorations (for example for distances, angles, and dihedrals), the colors of these decorations can also be changed: and the change is performed in the **Inspector** as well: ### Viewing distances Labels in SAMSON are displayed based on the viewer distance to what is labeled. This makes it easy to create multilevel annotations in complex structures: label a structure, a residue, or an atom, and the different labels will appear progressively as you zoom on the structure (as is typically done when zooming on maps). SAMSON 2022 R1 now makes it possible to modify the view distances in the **Inspector**: ### Adjusting labels positions Label positions are automatically set based on what is labeled (an atom, a residue, etc.). SAMSON 2022 now makes it possible to *offset* a label position in the viewport, using either the inspector or the various move editors (make sure you can select labels in the viewport by setting the Selection filter to "Any node" or "Labels"): Note that offsets are in the screen plane, where X is the horizontal axis and Y is the vertical axis. For example, whatever the camera position and orientation, an offset of 1 Angstrom along the Y-axis will always show the label *above* its default position. ## Menus ### Compact menus In order to help with varying screen resolutions, SAMSON loads a compact version of its menu on smaller screen resolutions. Here is the compact version of the **Select** menu, for example: ### Menu information Most SAMSON menus now contain a *brief* that summarizes the menu contents, provides shortcuts to the most frequently used commands, or gives you a tip. For example, here is the brief on the Home menu: Click the icon to visit the corresponding documentation webpage. ### Fetch PDB The extension to download PDB models from the Protein Data Bank is now included by default with SAMSON, and has its own command at the beginning of the **Biology** menu: This makes it possible to use various formats, load biological assemblies, and search locally thanks to downloads being cached, for faster access: ## And more This is just a brief overview and **SAMSON 2022 R1** also provides a variety of new features and fixes of reported issues, including for example: - Windows cascading: a new command is available to quickly reorganize the SAMSON interface by cascading dock windows. - Coloring structures per partial charge, formal charge, and occupancy now handles situations where data is not available. - For increased clarity, the context menu now groups the commands that can be applied to selected nodes according to the node types (i.e, the commands for residues, the commands for atoms, etc.) into sub-menus. - SAMSON now checks whether alternate atom locations are present before minimization, and offers to check the system using the Structure Validation interface. - SAMSON's managed heap functionality has been expanded to ease memory management for developers. - The mmCIF importer now uses dictionaries when adding hydrogens and covalent bonds. - Structural models now include functionality to compute structural statistics (asphericity, solvent-accessible area, etc.). - Structural nodes can now be extracted to a new chain of the same structural model. Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). ## For developers The SAMSON API has been upgraded to expose the new functionalities of this release and let developers create their modules that they can distribute on [SAMSON Connect](https://www.samson-connect.net/). ## Get SAMSON If you already have SAMSON, just restart it and you will be offered to update: follow the steps and your installation will be upgraded to SAMSON 2022 R1. If not, create your free account on [SAMSON Connect](https://www.samson-connect.net/) and download SAMSON! You'll be all set and ready to go within a few minutes. # SAMSON 2021 Release Notes # What's new in SAMSON 2021 **SAMSON 2021** brings numerous new features and improvements throughout the core of SAMSON, so let's dive right in! ## Introducing the SAMSON Animator One of the most exciting features of the 2021 release of SAMSON is the introduction of the **SAMSON Animator**, which allows you to create presentations, animations, and movies. The Animator, visible below on the bottom part of the SAMSON interface, is composed of two main parts - the **Track view** on the left, and the **Animation panel** on the right: In SAMSON 2021, a **Presentation** is a new type of node, whose children are **Animation** nodes. Presentation and animation nodes are part of SAMSON documents, and are visible in the **Document view**: Presentation and animation nodes are saved with the document, which means that you can easily save, load, and share your presentations and animations. The file [2AZ8 - Dock animation.sam](https://www.samson-connect.net/documents/aad9c1a7-3200-48e9-8ee8-0d74bc59657b) being shown here is actually provided with SAMSON as a demonstration file. SAMSON 2021 includes **thirty-two types of animations** split into six categories: - **Motion animations**: for docking, assembling, etc. - **Camera animations**: orbit, custom paths, etc. - **Entrance effects**: appearing, showing, etc. - **Exit effects**: disappearing, hiding, etc. - **Highlighting effects**: e.g. pulsing effects - **Other animations**: e.g. to pause and stop a presentation, as well as to change backgrounds and display background images such as presentation slides When a presentation is being edited in the Animator, its animations are visible in the **Track view**. Each animation corresponds to a track, and may be composed of one or more **keyframes**, i.e. **key events that happen at specific frames of a presentation**: The Animator allows you to easily **preview the impact of your design decisions** by letting you interactively choose the current presentation frame: The **Track view** also lets you **add, remove and move keyframes around**, and the Animator automatically shows you the impact on the current frame: All types of animations can be applied in **just a few clicks**. To add a Dock animation, for example, **just select the receptor and the ligand** and click **Dock** in the **Animation menu**: The Animator also lets you create advanced, **keyframed camera motions** that you can directly edit in the **Viewport**. While editing camera positions, **Thumbnails** automatically appear to help you frame the best shots: Once you are happy with your presentation and have chosen rendering options, you can export it as a movie (GIF, MP4 or WEBM): Template animations make it easy to **assemble molecular structures**. To create an assembly animation of the SARS-CoV-2 Spike protein, for example (PDB code `6VYB`), select the three chains and click **Assemble** in the **Animation menu**: If you already have a molecular dynamics simulation trajectory, or a [computed path](https://www.linkedin.com/pulse/coronavirus-computing-opening-motion-sars-cov-2-spike-dmitriy-marin/), you can include it in the presentation and **freely adjust its length**. SAMSON will compute smooth interpolated trajectories: The SAMSON Animator also allows you to create **keyframed molecular animations** which interpolate between key poses obtained with the SAMSON editors (e.g. the **Move editors** and the **Twister editor**). You can **edit all your keyframes in the viewport**, and immediately see the impact on the animation: Of course, the Animator also includes template animations for cameras. For example, the classic **Orbit animation** can be added in one click, and can be easily edited in the viewport: Other camera animations include the **Follow atoms** animation, which follows around a selection of atoms: We will be covering the **SAMSON Animator** more extensively in **upcoming tutorials and webinars**, so stay tuned! **New:** Learn more from this tutorial video: [How to create molecular animations in SAMSON 2021](https://www.youtube.com/watch?v=41zg-DHXb2A). From it you will learn about: - the SAMSON Animator, - animating molecules, - creating different types of Motion animations (docking, assembly, move atoms, etc), - integrating molecular dynamics trajectories in an animation and creating custom molecular trajectories using, - creating different types of Camera animations (orbiting, zooming, following atoms with the camera, custom camera motions), - adding Entrance and Exit effects, - exporting movies, - pausing and stopping animations, - integrating slides and creating presentations, - modifying animations (Easing curves, etc), - sharing your animations. Check the video's description to navigate through the chapters. ## Visual presets SAMSON 2021 introduces **Visual presets**, an efficient way to apply multiple visual representations and color schemes simultaneously to a complex molecular system. Visual presets rely on **Selectors** to automatically determine where visual representations and color schemes are applied (e.g. the receptor, ligands, waters, etc.). In the example below, the first visual preset is selected in **just a few clicks** to show the receptor as ribbons, ligands and waters as licorice, and ions as a van der Waals representation. The corresponding nodes are added to the document in a new folder. SAMSON 2021 also gives you the possibility to modify the proposed visual presets and to **create your own visual presets from scratch**. ## New visual models We added three new visual models for Biology: **Cartoon, Tubes, and Trace**. Biomolecules can thus now be represented using a wide variety of representations. Furthermore, the three surface types (Gaussian Surface, Solvent Accessible Surface, and Solvent Excluded Surface) now make it possible to highlight and select atoms, residues, chains, etc. directly *via* surfaces. ## New rendering options We added two new rendering effects: **Bloom** and **Pinhole**. The **Bloom effect** adds a controllable "halo" around the brightest parts of the image to simulate imaging artefacts, which may add realism to images. The **Pinhole effect** simulates looking through a pinhole, which may be useful when you want to focus attention on the center of the image (for example, a ligand followed by the camera using the new Follow atoms animation). In SAMSON 2021, it becomes possible to change transparency for structural models, labels, and folders as well using the **Inspector**. Changing the transparency at the folder level, in particular, gives you the possibility to alter the rendering of multiple nodes simultaneously. We also added a new setting to enable **Soft shadows** in one click from the **Visualization menu**: ## Menu updates As described above, SAMSON 2021 has a new **Animation menu** that allows you to create animations, presentations, and movies. This menu gives you one-click access to the most common animations. The **Visualization menu** has been reorganized to give you rapid access to the new rendering effects, the most common visual representations, as well as the new **Visual presets**. The **Biology menu** has also been reorganized to provide easier access to preparation, selection, and visualization commands, including the new commands described below. ## Advanced selections We added more selection commands in the context menu of the **Document view**, where you can more easily expand selections. This includes the possibility to select covalently linked atoms, connected components, etc.: Furthermore, we introduced a new dialog for performing advanced selection expansion, which lets you control the type of selected nodes (e.g. residues, side chains, etc.), while showing you the corresponding Node Specification Language (NSL) expression: In the **redesigned Biology menu** (see above), as well, more selection options have been added: ## Expanded Node Specification Language We added many new attribute types to SAMSON's Node Specification Language, making it possible to search atoms according to their geometry (e.g. trigonal planar, trigonal pyramidal, tetrahedral, etc.), hybridization (SP, SP2, SP3, etc.), number of bonds, etc. New attributes have also been added for bonds (e.g. searching bonds through their lengths), residues (e.g. pkA, polarity, etc.), and chains. Of course, the NSL now makes it possible to search the new **Presentation** and **Animation** nodes. All new attributes are available through SAMSON's **Find Dialog**: Please visit [the NSL reference page](https://documentation.samson-connect.net/users/latest/nsl/index.md) for more information. ## Node locks Extensions now have the possibility to lock some nodes in the document in order to temporarily prevent modifications during calculations. This helps SAMSON extensions maintain consistency between the document state and their own state while you interact with document nodes. ## And more This is just a brief overview and **SAMSON 2021** also provides a variety of new features and fixes of reported issues, including for example: - Very significant performance improvements, sometimes resulting in orders of magnitude speedups, over the board. This includes working with conformations and nodes in general, minimization, surface calculations, etc. - Improved visual models: Solvent Accessible Surfaces and Solvent Excluded Surfaces can now be converted to meshes, and therefore exported to OBJ files (for example to use them in rendering software). - Improvements in drag-and-drop: you can now merge structural models by dragging structural models and dropping them onto another one. - New options are available to automatically erase bonded hydrogens when erasing atoms, as well as recursively erasing empty parent nodes. And, of course, we are always working on improving existing SAMSON Extensions and developing new ones (we'll be making new announcements about these very soon, so stay tuned!). Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). ## For developers The SAMSON API has been upgraded to expose the new functionalities of this release and let developers create their modules that they can distribute on [SAMSON Connect](https://www.samson-connect.net/). See the [Developer Guide: Changelog](https://documentation.samson-connect.net/developers/latest/changelog/). If you have any questions or feedback, please use the [SAMSON forum](https://forum.samson-connect.net/). ## Get SAMSON To start creating your own animations, create your free account on [SAMSON Connect](https://www.samson-connect.net/) and download SAMSON now! # SAMSON 2020 R3 Release Notes # What's new in SAMSON 2020 R3 The new **SAMSON 2020 R3** release brings numerous new features and improvements throughout the core of SAMSON, so let's dive right in! ## Cloud computing One of the most exciting features of SAMSON 2020 R3 is the introduction of **cloud computing capabilities**. In many design situations, a personal computer might have too little processing power to perform advanced calculations (e.g. high-throughput screening, some molecular dynamics simulations, etc.). In agreement with our vision of **democratizing molecular design**, we are introducing the possibility to perform cloud calculations directly from SAMSON. From the users' point of view, this means it will now be possible to use some **cloud-enabled SAMSON extensions** to perform calculations in the cloud with a unified, integrated approach, and **focus on science**. A typical usage scenario will be as follows: - You will construct a system in SAMSON. - You will set calculation parameters in the cloud-enabled SAMSON extension. - You will select the processing power you want to use in the cloud - different compute capabilities will require different amounts of [computing credits](https://www.samson-connect.net/computingCredits). - For security reasons, SAMSON will present you with a summary and will ask you to confirm the creation of the job. - You will start, pause, resume, stop the job from the SAMSON job manager (see the image below), and you will be able to track progress from SAMSON, as well as download processing logs while the job is being executed. - Once the job is complete, you will download results to your personal computer to proceed with visualization, analysis, other calculations, etc. An obvious immediate advantage is the access to raw computing power (based on existing and upcoming computing hardware), the possibility to run many jobs in parallel, compare numerical experiments, perform long calculations while still being able to use your personal computer, etc. Of course, **since SAMSON is a platform, other developers can develop cloud-enabled extensions**. Precisely, developers are going to be able to use the SAMSON SDK to make their extensions perform calculations in the cloud, while offering SAMSON users a unified, integrated way to manage all jobs. Furthermore, thanks to the SAMSON SDK, developers will be able to **charge computing credits to cover their own operating charges**. You will see the first cloud-enabled extensions arrive in the coming weeks, so stay tuned! If you are a developer interested in creating cloud-enabled services for thousands of SAMSON users, please contact us at [partner@oneangstrom.com](mailto:partner@oneangstrom.com). ## Research notes SAMSON 2020 R3 introduces a new type of document node called **Note**. As the name indicates, a note node can be used to add information to your documents: descriptions of systems, protocols, to-do lists, etc. This is particularly helpful to track your research progress **where you perform your research** (what better place to store information about your models and simulations than alongside these models and simulations), and ensure reproducibility. Notes appear with a text document icon in the **Document view**: You edit your notes in the **Inspector**: ## Advanced selections We added more selection commands in the context menu of the **Document view**, where you can more easily expand selections: as well as in the Biology menu where you can select residues based on their properties: You can also select atoms and bonds based on their properties: Automatic selection of ligands was also improved, and you can now use **keyboard modifiers** in combination with selection commands, i.e. hold `Ctrl`, `Alt`, or `Shift` when clicking on selection commands to perform advanced selections. The tooltips indicate the possible options: Finally, since documents are hierarchies of nodes, we added a new quick command to make it easy to **select parent nodes**: This makes it easy to go from e.g. atom to side chain, side chain to residue, etc. ## Exporting 3D models for presentations You can now use SAMSON to **export 3D models** of your structures to OBJ files! The OBJ format is widely supported, and you can import OBJ files in 3D programs, virtual reality software, and even in **your presentations**. Here is an example of a model prepared in SAMSON (PDB code `2AZ8`), with the receptor dimer represented through two colorized Gaussian surfaces: After exporting this structure from SAMSON as a 3D model (total export time: five seconds), here it is imported in a popular slide-making software: The ability to export 3D models from SAMSON in seconds - combined with the capabilities of some presentation software to animate views of these 3D models - feels like having a new presentation superpower ;). ## Dark mode SAMSON now has a dark mode! If you'd like to activate it, head to the **Preferences**. ## Inspector upgrade The **Inspector** now supports even more types of attributes (e.g. colors, color palettes, text editors, etc.) and can now be used to reset some parameters to default values: When an attribute can be reset to a default value, the mouse cursor changes on hovering the attribute label. ## New rendering options In the **Rendering preferences**, you can now choose between displaying atoms with constant radii (left image) or with radii proportional to van der Waals radii (right image). In the **Visualization menu**, a new command makes it quick to change anti-aliasing settings: ## And more This is just a brief overview and **SAMSON 2020 R3** also provides a variety of new features and fixes of reported issues, including for example: - You can now capture a screenshot of the viewport directly to the clipboard (`Shift`+`F10`). - The speed of showing and hiding nodes has been increased. - Special characters can now be included in file paths when importing and exporting. And, of course, we are always working on the improvement of existing SAMSON Elements and on the development of new SAMSON Elements (we'll be making new announcements about these very soon, so stay tuned!). Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). To find out more, create your free account on [SAMSON Connect](https://www.samson-connect.net/) and download SAMSON now! ## For developers The SAMSON API has been upgraded to expose the new functionalities of this release and let developers create their modules that they can distribute on [SAMSON Connect](https://www.samson-connect.net/). See the [Developer Guide: Changelog](https://documentation.samson-connect.net/developers/latest/changelog/). If you have any questions or feedback, please use the [SAMSON forum](https://forum.samson-connect.net/). # SAMSON 2020 R2 Release Notes # What's new in SAMSON 2020 R2 The new **SAMSON 2020 R2** release brings further improvements throughout the core of SAMSON: - Custom **color palettes** - **Cumulative updates** since [SAMSON 2020 R1](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2020-r1/index.md), including **quick minimization**, a new **displacer editor**, etc. - Support for a new type of node, **meshes**, i.e. textured triangular surfaces. - A variety of **new features and fixes** of reported issues. - For developers: **new functionality in the SAMSON API** and a new module that allows you to view the **functionality exposed by SAMSON Elements**, which you can use in your own Elements. ## Create your own color palettes You can now create and save your own custom color palettes based on the HCL (Hue-Chroma-Luminance) color space for each color scheme. The HCL color space is very useful because it matches particularly well the human visual system - it is more perceptually close to the human eye - Hue represents the type of color, i.e. the dominant wavelength, Chroma represents the colorfulness, and Luminance represents the brightness. For very nice descriptions of the HCL color space, please visit [hclwizard.org](https://hclwizard.org/) and [colorspace.r-forge.r-project.org/articles/hcl_palettes.html](https://colorspace.r-forge.r-project.org/articles/hcl_palettes.html). SAMSON provides you with a set of default color palettes. Now, you can customize them by creating your own color palettes and use any default and custom color palettes in different color schemes to better visualize the details of the systems you want to show. ## Cumulative updates since SAMSON 2020 R1 **SAMSON 2020 R2** also incorporates all the updates done after the [SAMSON 2020 R1](https://documentation.samson-connect.net/samson-release-notes/whats-new-in-samson-2020-r1/index.md) which were already automatically applied if you had the SAMSON 2020 R1 installed. Among many of them are: ### Quick minimization The **Quick minimization** feature allows for an **interactive user-friendly one-click minimization** of systems thanks to the Universal Force Field and the Interactive modeling state updater. This is particularly useful when building structures. ### Displacer editor The **displacer editor** allows for easy one-click displacement of structures according to the current selection filter which might be useful, for example, during interactive minimization and simulation. ## Meshes SAMSON now natively supports textured triangular meshes. This can be used to produce e.g. images and animations, courses, multilevel representations, etc. We put a few examples in [shared documents](https://www.samson-connect.net/documents) so you can play with them immediately, but we also released [OBJ Importer](https://www.samson-connect.net/extensions/5b539283-671e-5194-604b-041eb893b985), a new SAMSON Element that makes it possible to create meshes from obj files. Meshes are accessible to developers too, thanks to the SAMSON Software Development Kit, and we're excited to see what you will do with this. ## And more This is just a brief overview and **SAMSON 2020 R2** also provides a variety of new features and fixes of reported issues, including for example: - New interactive tutorials to rapidly learn how to **Build** and **Edit** molecules. - A new way to adjust hydrogen atoms, based on residue types. - The possibility to have multiple importers for the same file format. And, of course, we are always working on the improvement of existing SAMSON Elements and on the development of new SAMSON Elements (we'll be making new announcements about these very soon, so stay tuned!). Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). To find out more, sign up on [SAMSON Connect](https://www.samson-connect.net/signUp) (it's free!) and download SAMSON now! ## For developers The SAMSON API has been upgraded to expose the new functionalities of this release and let developers create their modules that they can distribute on [SAMSON Connect](https://www.samson-connect.net/). See the [Developer Guide: Changelog](https://documentation.samson-connect.net/developers/latest/changelog/). A new module called [Exposed functionality viewer](https://www.samson-connect.net/extensions/92c88bef-d33d-3eab-2380-1d4b1788ac1b) is available. It makes it possible to view the classes and functions exposed by other SAMSON Elements, so that you can use them in your own SAMSON Elements. You can learn more about how to use the exposed functionality of other SAMSON Elements in the [Developer Guide: Introspection](https://documentation.samson-connect.net/developers/latest/introspection/). If you have any questions or feedback, please use the [SAMSON forum](https://forum.samson-connect.net). # SAMSON 2020 R1 Release Notes # What's new in SAMSON 2020 R1 To get SAMSON, sign up on [SAMSON Connect](https://www.samson-connect.net/signUp) (it's free!) and download it now! In line with our vision of a platform democratizing access to molecular modeling, **SAMSON 2020** significantly improves the user experience and brings numerous, game-changing functionalities. ## As easy as "ABC" We've wanted to offer this in SAMSON for years, and it's finally here: a powerful yet easy-to-use **Molecular builder**. ### A is for "Atoms" and "Assets" Of course, we made it possible to build using individual atoms: You can choose which atoms you add using **Quick commands**... ... or using the **Periodic table**... ... but we're excited to announce that **SAMSON lets you build by assembling assets!** **Assets can be anything**: rings, fragments, radicals, whole molecules, proteins, nanoparticles, 2D materials, etc. Just assemble them in the document to rapidly set up complex models for analysis and simulation. The builder has several cool features to assist you: as shown above, in particular, it has options to **predict fragments orientations** and **prevent implausible substitutions**: acceptable substitutions or additions have a green overlay, while forbidden ones have a **red overlay** (you control in the **Preferences** whether you want to follow these recommendations or override them). Whether you're constructing with individual atoms or with assets, the builder can also **adjust hydrogens** for you, and **merge overlapping atoms**. By pressing and holding `Shift`, you can choose which atom and bond in the asset are used to replace the atoms and bonds you click in the document: Accordingly, the SAMSON interface has a new component, the **Asset Browser**, which gathers the assets included by default in SAMSON with the assets you obtain from [SAMSON Connect](https://www.samson-connect.net/): ### B is for "Bonds" Of course, we made it easy to edit bond orders: ### C is for "Charges" And it's as easy to change formal charges: ## You like to move it? Move it! You now have precise control over positions and orientations of molecules using the **Move editor**: You can also control the pivot of the **Move editor**: The **Move editor** can also be used to position parts of molecules. In this case, it does its best to automatically find the best pivot and orientation: You can also **snap translations and rotations** to precise values: Of course, you can use the **Move editor** when performing interactive energy minimization and simulation: And if you want to check how much things have moved, the **Measure editor** has been completely redesigned and makes it easy to measure distances, angles and dihedrals: ## An improved user experience Following user feedback, the menu was significantly updated to make frequent tasks easily accessible: ### Visualization menu The Visualization menu now makes it very easy to apply traditional molecular representations, change colors, and control advanced rendering options with a few clicks: ### Biology menu The **Biology menu** gathers specific commands for selection, visualization and per-attribute colorization of biomolecules: This menu is optional and can be hidden in the **Preferences**. ### Apps menu The **Apps menu** has been reorganized to show all your apps more clearly and make them more accessible. You can also use the menu to set apps as favorites and place them on the viewport overlay. ### Editors menu The new **Editors menu** is similar to the Apps menu and gathers all your editors. As with apps, you can set editors as favorites from this menu to make them accessible from the **Viewport overlay** (see below). ### Command Finder The **Command Finder** was improved to display icons, images, shortcuts and help: ### Viewport overlay The viewport now features overlay actions to speed up your workflow: On the top-left part, the **Selection filter** lets you control what you select in the viewport. The left part shows your **Favorite apps** (you choose which apps you set as favorites). The bottom part controls the **View**. The right part shows your **Favorite editors**. Finally, the top-right part is dynamically updated to provide **Quick access commands** related to the active editor. On the bottom-left part, you can use the **Compass** to know and set the camera orientation: On the bottom-right part, the **Scale** indicates the size of the objects shown in the viewport: Hovering nodes now displays information about them and their ascendants: As shown above, SAMSON now has two ways to display bond orders: either through their thickness (as before) or via multiple cylinders (new version). Some of you are doing simulations that involve continuous bond orders, so we decided to make rendering bond orders continuous as well: Try it yourself: select a bond and change its order in the **Inspector** (`Ctrl` / `Cmd` + `2`). ## An easier learning curve ### Interactive tutorials SAMSON now contains step-by-step **Interactive tutorials** that guide you through SAMSON's features at your own pace. At the moment, seven tutorials are already included (totalling dozens of steps), but more are coming, and we'll make it possible for developers to make their own and create new learning experiences, either about their own modules or about molecular science in general. ### Contextual tips The technology we developed for offering interactive tutorials is also used to provide **Contextual tips** which appear when they're most needed. You control in the **Preferences** the frequency at which these tips are displayed. ## And more This is just an overview, and **SAMSON 2020** includes even more new features and improvements, including for example: - The **Node Filter** can now be used to search All nodes, Visible nodes and/or Selected nodes, and it provides examples of search strings - The **Document view** is orders of magnitude faster than in the previous version - The **Node Finder**  has been simplified to make it easier to learn SAMSON's **Node Specification Language** - The **SAMSON API** has been upgraded to expose the new functionalities of this release and let developers create fantastic molecular modeling experiences that they can distribute on [SAMSON Connect](https://www.samson-connect.net/). To find out more, sign up on [SAMSON Connect](https://www.samson-connect.net/signUp) (it's free!) and download SAMSON now! If you have any questions or feedback, please use the [SAMSON forum](https://forum.samson-connect.net). # Extensions Tutorials # SAMSON Extensions Tutorials Use these tutorials to follow task-based workflows with SAMSON Extensions, from docking and molecular dynamics to materials science, DNA origami, modeling, and analysis. ## Before you start Most tutorials are hands-on. While you read, add the extension mentioned in the tutorial, open SAMSON, and load the sample system or input data when the page asks for it. If you are new to SAMSON itself, start with the [SAMSON User Guide](https://documentation.samson-connect.net/users/latest/index.md) before following advanced extension workflows. ## Find a tutorial by task | I want to... | Start with | Extension / tool | Level | Expected result | | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ----------------------- | -------------------------------------------------------- | | Dock ligands or ligand libraries | [Dock ligands and libraries of ligands with AutoDock Vina Extended](https://documentation.samson-connect.net/tutorials/adve/docking-libraries-of-ligands-with-autodock-vina-extended/index.md) | AutoDock Vina Extended | Beginner / intermediate | Docking poses and scores | | Dock protein-ligand complexes with covalent or non-covalent options | [Covalent and non-covalent protein-ligand docking with the Fitted Suite](https://documentation.samson-connect.net/tutorials/fitted/fitted-suite/index.md) | FITTED Suite | Intermediate | Protein-ligand docking results | | Dock two proteins | [Protein docking with Hex](https://documentation.samson-connect.net/tutorials/hex/protein-docking-with-hex/index.md) | Hex | Intermediate | Ranked protein-protein docking poses | | Run molecular dynamics | [GROMACS Wizard tutorials](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md) | GROMACS Wizard | Intermediate | Prepared, minimized, equilibrated, and simulated system | | Prepare a protein | [Protein preparation and validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) | Protein preparation tools | Beginner | Cleaned and validated protein structure | | Analyze ligand strain | [Strain Explorer](https://documentation.samson-connect.net/tutorials/strain-explorer/strain-explorer/index.md) | Strain Explorer | Beginner / intermediate | Local and global ligand strain estimates | | Build a crystal | [Generate crystal models](https://documentation.samson-connect.net/tutorials/crystal-creator/generating-crystal-models/index.md) | Crystal Creator | Beginner | Crystal structure in SAMSON | | Build nanotubes | [Build carbon nanotube models](https://documentation.samson-connect.net/tutorials/nanotubes/building-nanotubes-models/index.md) | Nanotube Creator | Beginner | Single-walled or multi-walled nanotube model | | Design DNA origami | [Design DNA nanostructures with Adenita](https://documentation.samson-connect.net/tutorials/adenita/adenita/index.md) | Adenita | Intermediate | DNA nanostructure model | | Build molecular boxes | [Create molecular boxes with Molecular Box Builder](https://documentation.samson-connect.net/tutorials/molecular-box-builder/molecular-box-builder/index.md) | Molecular Box Builder | Beginner / intermediate | Molecular box or lipid-layer system | | Assign molecular mechanics force fields | [Molecular Mechanics Force Fields](https://documentation.samson-connect.net/tutorials/force-fields/molecular-mechanics-force-field/index.md) | Molecular Mechanics Force Fields | Intermediate | Parameterized interaction model with energies and forces | | Compute transition paths | [Generate a transition path with ARAP Interpolation](https://documentation.samson-connect.net/tutorials/arap/arap-interpolation-for-protein-structures/index.md) | ARAP Interpolation | Intermediate | Smooth path between protein conformations | | Find ligand unbinding paths | [Ligand Path Finder](https://documentation.samson-connect.net/tutorials/ligand-path-finder/ligand-path-finder/index.md) | Ligand Path Finder | Intermediate | Candidate ligand unbinding pathways | ## Recommended first tutorials - [Protein preparation and validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) - start here before many protein modeling, docking, or simulation workflows. - [Dock ligands and libraries of ligands with AutoDock Vina Extended](https://documentation.samson-connect.net/tutorials/adve/docking-libraries-of-ligands-with-autodock-vina-extended/index.md) - follow a practical protein-ligand docking workflow. - [Generate crystal models](https://documentation.samson-connect.net/tutorials/crystal-creator/generating-crystal-models/index.md) - build and inspect crystal structures. - [Fast geometry optimization with FIRE minimizer](https://documentation.samson-connect.net/tutorials/fire/ready-set-fire/index.md) - learn a reusable minimization tool used in several workflows. ## Tutorial families - [GROMACS Wizard tutorials](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md) - prepare, minimize, equilibrate, simulate, and analyze molecular systems with GROMACS Wizard. - Docking tutorials: - [AutoDock Vina Extended](https://documentation.samson-connect.net/tutorials/adve/docking-libraries-of-ligands-with-autodock-vina-extended/index.md) for ligand and ligand-library docking. - [FITTED Suite](https://documentation.samson-connect.net/tutorials/fitted/fitted-suite/index.md) for covalent and non-covalent protein-ligand docking. - [Hex](https://documentation.samson-connect.net/tutorials/hex/protein-docking-with-hex/index.md) for protein-protein docking. - SMILES Manager tutorials: - [Using the RDKit - SMILES Manager](https://documentation.samson-connect.net/tutorials/smiles-manager/using-the-rdkit-smiles-manager/index.md) - [Perform Positional Analogue Scanning using the SMILES Manager](https://documentation.samson-connect.net/tutorials/smiles-manager/perform-positional-analogue-scanning-using-the-smiles-manager-element/index.md) - Symmetry tutorials: - [Generate symmetry mates for proteins](https://documentation.samson-connect.net/tutorials/symmetry/generating-symmetry-mates/index.md) - [Symmetry detection in biological assemblies](https://documentation.samson-connect.net/tutorials/symmetry/computing-axes-of-symmetry-of-biological-assemblies/index.md) ## Tutorials by domain ### Drug discovery and structural biology - [Compute normal modes that open a binding site](https://documentation.samson-connect.net/tutorials/nma/calculating-non-linear-normal-modes/index.md) - [Explore the SARS-CoV-2 spike opening motion](https://documentation.samson-connect.net/tutorials/sars-cov-2/coronavirus-computing-the-opening-motion-of-the-sars-cov-2-spike/index.md) - [Create coarse-grained models for the MARTINI force field using Martinize2](https://documentation.samson-connect.net/tutorials/martinize2/martinize2/index.md) - [Dock ligands and libraries of ligands with AutoDock Vina Extended](https://documentation.samson-connect.net/tutorials/adve/docking-libraries-of-ligands-with-autodock-vina-extended/index.md) - [Covalent and non-covalent protein-ligand docking with the Fitted Suite](https://documentation.samson-connect.net/tutorials/fitted/fitted-suite/index.md) - [Protein docking with Hex](https://documentation.samson-connect.net/tutorials/hex/protein-docking-with-hex/index.md) - [Prepare, minimize, equilibrate, and simulate using GROMACS Wizard](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md) - [Generate a transition path between protein structures with ARAP Interpolation](https://documentation.samson-connect.net/tutorials/arap/arap-interpolation-for-protein-structures/index.md) - [Ligand Path Finder](https://documentation.samson-connect.net/tutorials/ligand-path-finder/ligand-path-finder/index.md) - [Protein Path Finder](https://documentation.samson-connect.net/tutorials/protein-path-finder/protein-path-finder/index.md) - [Molecular Restrainer: energy minimization for NMR-derived structures](https://documentation.samson-connect.net/tutorials/molecular-restrainer/molecular-restrainer/index.md) - [Predict protein-ligand complexes using NMR2](https://documentation.samson-connect.net/tutorials/nmr2/predicting-protein-ligand-complexes-using-nmr2/index.md) - [Predict Biomolecular Structures](https://documentation.samson-connect.net/tutorials/bsp/bsp/index.md) - [Protein alignment](https://documentation.samson-connect.net/tutorials/protein-aligner/protein-aligner/index.md) - [Protein preparation and validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) - [Interactive Ramachandran Plot](https://documentation.samson-connect.net/tutorials/ramachandran/ramachandran-plot/index.md) - [Strain Explorer: analyze ligand strain and compare relaxed conformations](https://documentation.samson-connect.net/tutorials/strain-explorer/strain-explorer/index.md) - [Generate symmetry mates for proteins](https://documentation.samson-connect.net/tutorials/symmetry/generating-symmetry-mates/index.md) - [Symmetry detection in biological assemblies](https://documentation.samson-connect.net/tutorials/symmetry/computing-axes-of-symmetry-of-biological-assemblies/index.md) ### Materials science - [Build carbon nanotube models](https://documentation.samson-connect.net/tutorials/nanotubes/building-nanotubes-models/index.md) - [Generate crystal models](https://documentation.samson-connect.net/tutorials/crystal-creator/generating-crystal-models/index.md) ### DNA origami - [Design DNA nanostructures with Adenita](https://documentation.samson-connect.net/tutorials/adenita/adenita/index.md) ### Molecular modeling, force fields, and utilities - [Build custom polymers with Polymer Builder](https://documentation.samson-connect.net/tutorials/polymer-builder/polymer-builder/index.md) - [Create molecular boxes with Molecular Box Builder](https://documentation.samson-connect.net/tutorials/molecular-box-builder/molecular-box-builder/index.md) - [Export atoms trajectories along paths](https://documentation.samson-connect.net/tutorials/export-along-path/export-atoms-trajectories-along-paths/index.md) - [Fast geometry optimization with FIRE minimizer](https://documentation.samson-connect.net/tutorials/fire/ready-set-fire/index.md) - [Interactive Modeling Universal Force Field](https://documentation.samson-connect.net/tutorials/uff/im-uff/index.md) - [Making nano-batarangs and more with Simple Script](https://documentation.samson-connect.net/tutorials/simple-script/making-nano-batarangs-and-more/index.md) - [Molecular Mechanics Force Fields](https://documentation.samson-connect.net/tutorials/force-fields/molecular-mechanics-force-field/index.md) - [Optimize transition paths with P-NEB](https://documentation.samson-connect.net/tutorials/pneb/optimize-transition-paths-with-parallel-nudged-elastic-band/index.md) - [Pathlines: visualize motion of the center of mass of an atomic system](https://documentation.samson-connect.net/tutorials/pathlines/pathlines/index.md) - [UMA Force Field](https://documentation.samson-connect.net/tutorials/uma-force-field/uma-force-field/index.md) - [Universal Force Field](https://documentation.samson-connect.net/tutorials/uff/uff/index.md) ## Related resources - Open the [SAMSON User Guide](https://documentation.samson-connect.net/users/latest/index.md) for core SAMSON interface and workflow concepts. - Use the [Python Scripting Guide](https://documentation.samson-connect.net/scripting/latest/index.html) to automate SAMSON with Python. - Ask questions in the [Forum](https://forum.samson-connect.net/) when you need help with a tutorial or extension. ## Next step If you want a complete molecular dynamics route, start with the [GROMACS Wizard tutorials](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md). If you are choosing among several scientific tasks, use the tutorial finder above. # Design DNA nanostructures with Adenita Use [Adenita](https://www.samson-connect.net/extensions/dda2a078-1ab6-96ba-0d14-ee1717632d7a) in SAMSON to design, import, and inspect DNA nanostructures at multiple levels of detail. It is especially useful when you want to prototype DNA origami systems, combine them with proteins, or prepare a structure for later export and simulation. This quick-start tutorial helps you install the extension, find the main tools, and understand the interface before you start a real design project. Note Adenita is in alpha. It was originally developed by Elisa De Llano and Haichao Miao (see: [https://edellano.github.io/Adenita-SAMSON-Edition](https://edellano.github.io/Adenita-SAMSON-Edition/)). Porting Adenita to the latest versions of SAMSON and its support are done by the SAMSON team at [OneAngstrom](https://www.oneangstrom.com/). 1. [Before you start](#before-you-start) 1. [What you can do in Adenita](#what-you-can-do-in-adenita) 1. [Adenita interface](#adenitas-interface) 1. [Video tutorials](#video-tutorials) 1. [References](#references) ## What you will learn In this tutorial, you will learn how to design, import, edit, and export DNA nanostructures in SAMSON with Adenita. ## Before you start 1. Install SAMSON from [SAMSON Connect](https://www.samson-connect.net/). 1. Add [Adenita](https://www.samson-connect.net/extensions/dda2a078-1ab6-96ba-0d14-ee1717632d7a) from [SAMSON Connect - Marketplace](https://www.samson-connect.net/extensions), then restart SAMSON so it can be installed automatically. 1. Open Adenita from **Home > Apps** or via **Find everything...**. 1. Use this page as a guided orientation to the interface and the main capabilities before building a larger DNA origami project. If you encounter any problems, please let us know at [SAMSON Connect Forum](https://forum.samson-connect.net/). You can also join the Adenita community on Discord: . ## What you can do in Adenita ### Create DNA nanostructures Use different Adenita editors to create double-strand DNA (dsDNA), nanotubes, lattices, or wireframe nanostructures (uses [Daedalus](http://daedalus-dna-origami.org/) algorithm). ### Save components of your design or the entire design You can save the entire workspace into a SAMSON document. If you want to save components of your design for later reuse, use Adenita's saving function (it will save them in *.adnpart* format). ### Import a DNA nanostructure from Cadnano or load a previous design Through the Adenita interface, you can load a Cadnano design, or a component saved as *.adnpart*. You can combine as many components as your graphics card and CPU can afford. ### Where to find DNA origami structures You can start from existing DNA origami designs instead of building every structure from scratch. This is useful when you want to learn from published examples, reuse common motifs, or test Adenita's import and export workflows. Adenita can load **caDNAno designs** in `.json` format, as well as Adenita component files such as `.adnpart` and `.adn`. You can then inspect, edit, combine, save, or export the structures, including to **oxDNA** format for coarse-grained simulations. Some useful sources of DNA origami structures are: - [Nanobase](https://nanobase.org/) — a public repository for DNA, RNA, and hybrid nanostructures. Entries may include original design files, images, publication information, and, when available, oxDNA files for 3D visualization and simulation workflows. - [oxDNA.org example files](https://oxdna.org/example) — a small set of ready-to-use oxDNA topology and configuration files for testing oxDNA-based workflows. - [Oxford Research Archive: input files for example oxDNA simulations of DNA origami](https://ora.ox.ac.uk/objects/uuid:7a111527-3c1a-4c0f-af89-774b01f43abd) — example caDNAno `.json` files and oxDNA input files accompanying an oxDNA DNA-origami tutorial. - [The caDNAno Repository](https://github.com/edwardnianzhang/cadnano-repository) — a community GitHub repository of caDNAno v2 `.json` designs recreated from published DNA-origami research articles. Since these are recreated files, check the corresponding papers and validate the designs before using them in a research workflow. You can also find reusable DNA origami components directly on [SAMSON Connect > Shared documents](https://www.samson-connect.net/documents). For example, [Tom Moore's SAMSON Connect page](https://www.samson-connect.net/TomMoore) contains many published components and example structures, including DNA crossover motifs and mechanical components that can be downloaded and opened in SAMSON. For complementary video material and tutorials on DNA nanotechnology, you can also explore [Tom Moore's YouTube channel](https://www.youtube.com/@diamondoid). *Examples of reusable DNA origami components created and shared by Tom Moore on SAMSON Connect. See also Tom Moore's [post on X](https://x.com/mooreth42/status/2060697533546963065?s=20).* When reusing a structure from a repository, always check the associated license, citation, and publication information. For simulation workflows, make sure the structure is in a format supported by your tools, and relax or validate it when necessary before running production simulations. ### Export your design Besides being saved, you can export your design as a list of sequences or in oxDNA format for simulations. ## Adenita's interface Once you have installed Adenita, you can find it in **Home > Apps** or via **Find everything...**. Adenita provides a number of editors that can be accessed either via Adenita's interface or via the editors toolbar on the left side of the viewport (click on **...** at the bottom of the editors toolbar). You can also access Adenita's settings through its interface - click on **Settings**. ### Main interface The following functions can be accessed through the main UI: - Load a DNA nanostructure from a file. Possible choices are a cadnano design (for cadnano 2.5) as *.json*, a mesh in *.ply* (will be loaded using the [Daedalus](http://daedalus-dna-origami.org/) algorithm), or a *.adnpart* or *.adn* (custom Adenita formats). This option allows you to load a component into a workspace (loading using SAMSON files will create a new document). - The user can choose to save a component for later use in our custom format (.adnpart). - The user can save all current DNA nanostructures in a *.adn* file; systems not handled through Adenita won't be saved. - Options to export as a CSV sequence file or in a format appropriate for oxDNA are available here. - All scaffolds from the selection will be assigned a sequence specified through the 'Options' menu; scaffold nucleotide pairs will also be assigned the complementary base. - It is possible to set any nucleotide as the new 5' of its single strand. - If a path to [ntthal](https://primer3.org/) has been specified in the Options menu, it will be used to calculate the melting temperatures and Gibbs free energies of all binding regions of a selected component. ### Editors - Breaks the bond between two consecutive nucleotides of the same strand. - Deletes nucleotides or base pairs, depending on the chosen visualization scale. - Merges single or double strands. If strand ends are selected, they will be connected in the appropriate direction (5' to 3'). If nucleotides that are not 5' or 3' are selected, the strands will be broken in order to reconnect them at chosen points. It is also possible to insert a new double or single strand along the connection. - Reorganize several components into one, or reassign single and double strands to other components. The list of components and strands needs to be updated manually. - Modifies the twist angle of a double-strand along the helical axis. - Tag nucleotides or modify their base. - Remove the entire twist of a double strand locally to observe the single strands that compose it as parallel lines. - Add a new single or double strand as a component to the design. They can also be circular. - Add a lattice of double strands as a component. - Add a nanotube composed of double strands. - Generate a wireframe from the given shapes and add it to the design (uses the [Daedalus](http://daedalus-dna-origami.org/) algorithm). ## Video tutorials Note The videos below were recorded using an old version of SAMSON, so please be aware that some of the interface has changed. ### Getting started ### Creating ssDNA/dsDNA ### Creating nanotubes and untwisting ### Creating square/honeycomb lattices and connecting ssDNA ### Creating DNA wireframe structures and creating all-atom model ### Load and visualize proteins and connect to DNA wireframe ### Highlighting, tagging ### Coloring, melting temperature (Gibbs free energy) ### Creating superstructures (merging two DNA wireframe structures) ### Exporting for simulation (using oxDNA format for coarse-grained simulation) ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). ## Related tutorials - [SAMSON User Guide](https://documentation.samson-connect.net/users/latest/index.md) for core SAMSON interface and visualization concepts. ## Next step Follow the video tutorial that matches your DNA nanostructure task, then export the model in the format needed for your downstream workflow. ## References 1. Elisa de Llano, Haichao Miao, Yasaman Ahmadi, Amanda J. Wilson, Morgan Beeby, Ivan Viola, Ivan Barisic. Adenita: Interactive 3D modeling and visualization of DNA Nanostructures. *Nucleic Acids Research, Volume 48, Issue 15*, September 2020. \[[paper](https://doi.org/10.1093/nar/gkaa593)\] 1. Elisa de Llano, Haichao Miao, Yasaman Ahmadi, Amanda J. Wilson, Morgan Beeby, Ivan Viola, Ivan Barisic. Adenita: Interactive 3D modeling and visualization of DNA Nanostructures. *Pre-print at bioRxiv (849976)*; 2019. \[\] 1. Haichao Miao, Elisa de Llano, Johannes Sorger, Yasaman Ahmadi, Tadija Kekic, Tobias Isenberg, Meister Eduard Gröller, Ivan Barisic, Ivan Viola. Multiscale Visualization and Scale-adaptive Modification of DNA Nanostructures. *IEEE Transactions on Visualization and Computer Graphics*, 24(1), January 2018. \[[paper](https://www.cg.tuwien.ac.at/research/publications/2018/miao_tvcg_2018/miao_tvcg_2018-paper.pdf)\] 1. Haichao Miao, Elisa de Llano, Tobias Isenberg, Meister Eduard Gröller, Ivan Barisic, Ivan Viola. DimSUM: Dimension and Scale Unifying Maps for Visual Abstraction of DNA Origami Structures. *Computer Graphics Forum*, 24(1), 37(3), June 2018. \[[paper](https://www.cg.tuwien.ac.at/research/publications/2018/miao2018Dimsum/miao2018Dimsum-Paper.pdf)\] 1. Rémi Veneziano, Sakul Ratanalert, Kaiming Zhang, Fei Zhang, Hao Yan, Wah Chiu, Mark Bathe. Designer nanoscale DNA assemblies programmed from the top down. *Science*, 24 Jun 2016. \[[paper](http://science.sciencemag.org/content/352/6293/1534.full)\] 1. Shawn M. Douglas, Adam H. Marblestone, Surat Teerapittayanon, Alejandro Vazquez, George M. Church & William M. Shih. Rapid prototyping of 3D DNA origami shapes with cadnano. *Nucleic Acids Research*. \[[paper](https://academic.oup.com/nar/article/37/15/5001/2409858)\] # Dock ligands and libraries of ligands with AutoDock Vina Extended Use [AutoDock Vina Extended SAMSON Extension](https://www.samson-connect.net/extensions/1afc50e6-3567-fa25-1e09-415ebf4d05d7) to dock one ligand, a ligand library, or several receptors in SAMSON, then inspect and analyze the resulting poses in the same workspace. The [AutoDock Vina Extended SAMSON Extension](https://www.samson-connect.net/extensions/1afc50e6-3567-fa25-1e09-415ebf4d05d7) wraps the popular protein-ligand docking program [AutoDock Vina](https://vina.scripps.edu/) [1](#fn:1) and extends its functionality by providing the possibility to: - easily set up the system (a receptor or a receptor library, a ligand or a ligand library), including flexible side chains, rotatable bonds, and types of locked bonds; - easily set up the search domain based on the receptor, a ligand, or a binding site, or by manually adjusting it in the Viewport or in the interface; - perform the minimization of ligands; - specify multiple advanced parameters; - perform docking, re-scoring, or generate the project to run it on your cluster; - filter the results; - save the results, including automatic export of each mode into a separate MOL2 file; - analyze the results, export the results table and plots; - load the previously computed results. ## What you will learn In this tutorial, you will learn how to set up receptors and ligands, run docking with AutoDock Vina Extended in SAMSON, and inspect the results. ## Before you start - Add [AutoDock Vina Extended SAMSON Extension](https://www.samson-connect.net/extensions/1afc50e6-3567-fa25-1e09-415ebf4d05d7). - Download the [2AZ8 tutorial archive](https://documentation.samson-connect.net/wp-content/uploads/ADVE-2AZ8-tutorial.zip). - If your own system is not already clean, be ready to prepare it before docking. ## First steps Launch **SAMSON** and open the *2AZ8-tutorial.sam* file provided in the [archive](https://documentation.samson-connect.net/wp-content/uploads/ADVE-2AZ8-tutorial.zip). It will open structural models of a protein (2AZ8-A and 2AZ8-B) and of a ligand (2AZ8-IA) bound to the protein - for the sake of the tutorial, the protein is put in the `Receptor` folder and the ligand is put in the `Ligand` folder. Tip If you don't see the **Document view**, you can enable it in the **Interface** menu or via `Ctrl`/`Cmd` + `1`. ## Preparation of the system We need to prepare the system first: 1. Remove atoms with alternate locations. 1. Remove water and monatomic ions. This step is optional since water and monatomic ions will not be considered by AutoDock Vina Extended. 1. Remove ligands, co-factors, and other unnecessary small molecules present in the system. 1. Add hydrogens, if the system does not have them set. AutoDock Vina needs polar hydrogens to determine hydrogen bonds (H-bonds). Note that if the system has hydrogens added based on some protonation you should not modify hydrogens. To do all of this in a single step, go to **Home > Prepare** and check the above-mentioned options as shown in the image below. If your system has missing residues or heavy atoms (e.g., missing atoms in side chains), you can also use the [PDBFixer](https://www.samson-connect.net/extensions/c81b69fc-4df0-fe09-146c-3591b20ba609) extension to **fix a protein**. This extension can also be used to add hydrogens for specific pH. See also Please refer to the [Protein Preparation & Validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) tutorial for more information on how to prepare and fix protein systems. Note The system in the tutorial file has all the water already removed and hydrogens already added. Tip: visualization If there is no secondary structure shown in the Viewport, you can add it via **Visualization > Visual model > Ribbons** or **Visualization > Visualize > Protein-ligand**. You can also hide/show the atomistic representation by toggling the boxes in front of the protein structure in the **Document view**. To learn more about visual models in SAMSON please follow interactive tutorials in SAMSON (**Help > Tutorials**) or the [User guide: Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) tutorial. ## Setup of the system Let's now open the **AutoDock Vina Extended** app by clicking on it in the **Home > Apps > Biology** menu. You can also find it using the **Find everything...** search box (`Shift`+`E`) in the top menu of SAMSON - just start typing the name. Click on **New docking project**. Now we need to set up the system: 1. a receptor or a receptor library; 1. [optional] receptor's flexible side chains in case of a single receptor; 1. a ligand or a ligand library. ### Setup of the receptor Select the receptor - 2AZ8-A and 2AZ8-B structural models - in the **Document view** and then click on the **Set** button in the **Set receptor** part. You can also use **Select > Biology > Receptors** to automatically select receptors. You will see the search domain set based on the receptor, with its box shown in yellow in the **Viewport**. If you want to unset the receptor then just clear the selection and click on the **Set** button. #### Setup of the receptor's flexible side chains The setting of flexible side chains allows performing docking to a relatively flexible receptor with rotatable side chains. Note that having flexible side chains may result in more realistic docking but significantly increases the docking time. For simplicity, in this tutorial, we will not be specifying flexible side chains. But below you can find how to set up the receptor's flexible side chains. You can specify the receptor's flexible side chains using one of the following ways: - Select them in the **Document view**. - Select them in the **Viewport** by switching the **Selection filter** in the top-left corner of the **Viewport** to *Residues* and selecting residues one by one using `Ctrl` and `Alt` buttons to add/remove to the current selection. You will need to have the structural model visible in the **Viewport**. Tip See the [User Guide: Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) or interactive tutorials in SAMSON. - If you have a bound ligand and you want to specify residues around it as flexible, then select this ligand and go to **Select > Biology > Binding sites** and specify parameters as necessary and click OK: Once residues with flexible side chains are selected, click on the associated **Set** button in the **Set receptor** part. Once you set up flexible side chains, you will see in the **Viewport** the rotatable bond controllers represented by green cylinders superimposed with bonds. By clicking on them, you can switch the bonds from rotatable to not rotatable and back (green - rotatable, red - not rotatable). See more about it in the [Setup of rotatable bonds](#setup-of-rotatable-bonds) section. ### Setup of a ligand or a ligand library The AutoDock Vina Extended allows you to dock either a ligand or a library of ligands. ### Setup of the ligand Let's first see how to set up a ligand. First, check the **Single ligand** in the **Set ligand** part, then select the ligand - 2AZ8-IA - in the **Document view** and click on the associated **Set** button in the **Set ligand** part. #### Setup of rotatable bonds Once you set up a ligand, you should see in the **Viewport** the rotatable bond controllers represented by green cylinders superimposed with bonds. Zoom in on the ligand (select the ligand in the **Document view** and then press `Shift`+`Space`). By clicking on these controllers, you can activate or deactivate these rotatable bonds - switch the bonds from rotatable to not rotatable and back - they will change colors when you switch their state. Green means the bond can rotate, and red means the bond cannot rotate. Note that having rotatable bonds may result in more realistic docking but increases the docking time. You can also use the option to lock specific bond types (make them non-rotatable). For this, click on the **Locked bonds settings** and check the types of bonds that you want to be non-rotatable (locked) and click OK. Then check the **Lock specific ligand bonds** option. Note 1. Ligands should either be already minimized or minimization should be applied (see the Minimization of ligands section below). Locking of bonds does not affect minimization i.e., the locked bonds will be rotatable during minimization. 1. Cis-trans isomers will not be generated so it is necessary to provide all relevant cis-trans isomers in the ligand library. #### Setup of the ligand library In this tutorial, we will be docking not a single ligand but a ligand library, which is provided in the same archive. It is a small sample library with some random ligands obtained from the [ZINC library](https://zinc.docking.org/). In the library, you can provide files of different formats (e.g., MOL2, SDF) and multiple ligands per file. To dock a ligand library, check the **Ligand library** option and click on the button to browse the directory with the ligand library. Note that by default all the ligands in the library will be considered fully flexible (meaning that all the rotatable bonds will be active). You can lock specific bond types thanks to the aforementioned **Lock specific ligand bonds** option (first, verify the **Locked bonds settings**). Please see the [Setup of the rotatable bonds](#setup-of-rotatable-bonds) section. #### Minimization of ligands If you want to minimize ligands before docking, which might be necessary in some cases, for example, if ligands in the library are in 2D, then check the **Minimize** option and choose the preset (the maximum number of minimization steps and stopping criteria). Check the **Add missing hydrogens** option if ligands do not have hydrogens already set - hydrogens are necessary for detecting bond types during the minimization and polar hydrogens are necessary for docking. The minimization is stopped based on some stopping criteria - when either the energy difference between steps is less than some threshold during at least some consecutive minimization steps or the maximum number of minimization steps has been reached. These values are determined by the minimization preset. ## Setup of the search domain The next step is to set up the search domain. By default, the search domain is determined once you set the receptor based on the whole receptor. If you already know the binding site, you can specify the search domain that surrounds it - this will not only limit the search domain but will also lead to performing fewer computations decreasing the overall docking time. Tip If you want to hide/show the search domain in the **Viewport**, then toggle the **Show box** option. You can set up the search domain using one of the following ways: - Modify the center and the size of the domain in the interface. - Adjust the search domain box directly in the **Viewport** thanks to the controllers placed in the corners of the yellow search box visible in the **Viewport** - just press on the sphere in the corner of the box and drag it to modify its position. - Set it up based on the current selection: select nodes and choose the **Based on pocket/selection** option from the list and click **Set**. - Set it up based on the bound ligand/binding pocket: select the bound ligand and go to the **Select > Biology > Binding sites**, after the binding site is selected choose the **Based on pocket/selection** option from the list and click **Set**. See the example below. You can always just set the search domain directly in the **Viewport** thanks to the search box controllers. Let's set up the search domain based on the binding site of the 2AZ8-IA bound ligand. Select the 2AZ8-IA ligand in the **Document view** and go to **Select > Biology > Binding sites** and specify parameters as shown in the image below and click OK: This should select residues around the ligand. Now choose the **Based on pocket/selection** option from the list and click **Set**. Please note that the search domain is set in the global XYZ coordinates. If you want, you can always rotate or align the system using the [Move editors](https://documentation.samson-connect.net/users/latest/moving-objects/index.md) to better align the binding site in the global XYZ coordinates. ## Running the docking and more The next step is to run the docking! The **Dock part** provides the following options: - **Dock** - performs docking. - **Score only** - performs scoring of ligands in their current positions without minimization. - **Local optimization only** - performs local optimization only and scores ligands in their current positions. - **Generate PDBQT files only** - generates a project with PDBQT files for the receptor and ligands, and a configuration file - you can use these files to launch Vina computations on your own cluster. If the minimization option has been checked, the ligands will be minimized before generating PDBQT files. In the case of the use of a ligand library, the PDBQT files for ligands will be generated with keeping the same hierarchy as in the ligand library. Choose the **Dock** from the list since we want to perform the docking. To change exhaustiveness, the maximum number of modes, or other parameters click on **Options**: - Set the **Exhaustiveness** parameter (the higher the better, but the longer the search) to 8. - Set the **Max. number of generated binding modes** parameter (the maximum number of modes returned by the search algorithm) to 20. You can also modify other parameters, e.g., scoring function (vina or vinardo), the energy range for the resulting modes, grid spacing, weights of scoring functions, etc. We do not advise modifying the weights; if you modified them, you can always restore their default values by clicking on the **Restore default values** button. If you want your results to be automatically saved on disk, then check the **Save results** option and select the directory where you want your results to be saved. This will create a project directory with a timestamp in its name; this directory will contain the receptor and ligand files, generated PDBQT files, docked PDBQT files, and MOL2 files for each ligand's mode. You can later load these results back to AutoDock Vina Extended (see the [Loading previously computed results](#loading-previously-computed-results) section). Please note that you shouldn't modify the hierarchy of the project directory or remove files if you want to be able to load them back into AutoDock Vina Extended. Please check the **Save results** option and select the directory where you want your results to be saved. We will need these saved results in the [Loading previously computed results](#loading-previously-computed-results) section. Now, press the **Dock library** button and wait for the results - it should take a couple of minutes. There might be some pop-up dialogs asking for options to import ligands from the library folder. If you are docking a ligand library, you can always pause, resume, or stop the computations - the pause and stop will be applied only after the computations for the current ligand are finished. ## Visualizing results As soon as the computations are done, a new folder with the results should be added to the document containing the following: - A note called `Configuration` with the docking parameters. If you want to see the note with the docking parameters, right-click on it and choose **Inspect** in the context menu. - A subfolder called `Top ligands` with structural models of the top binding ligands (with the best ranked pose already displayed). - Top conformations of the top ligands allow you to display poses of these ligands. To restore a conformation, either double-click on it in the **Document view** or right-click on it and in the context menu choose **Restore conformation**. You can also create structures (structural models) from conformations, which makes it easier to see clusters of conformations. To achieve this, right-click on one or more conformations and choose **Create structural models from conformations**. This will create structural models for all selected poses, so you can see where clusters are. Note that you can hide structural models from displaying in the Viewport by unchecking them in the document. Note that all the conformations are stored in a directory with results if you choose to save the results, or if you loaded the previously computed results. You can also export the selection, for example as MOL2 or PDB files, by clicking on **Home > File > Save selection as...** (`Ctrl`/`Cmd` + E). To export the ligand's conformation in a separate file, restore this conformation by double-clicking on it and then select the ligand's structural model and click **Home > File > Save selection as...**. The **Results** tab in the AutoDock Vina Extended allows you to see the results table and plot, filter the results based on some parameters (e.g., name, affinity, RMSD, etc.), export the results table in a CSV file, export the affinity vs compounds plot as an image or in a CSV file. There is a horizontal splitter line between the results table and the plot that you can drag to modify the size of the results table and the plot. The results table allows you to sort by columns, copy the data, select ligands and conformations, restore conformations, and export ligands and conformations in the document that are not present among the top ligands and conformations. To do that, right-click on a row and choose a corresponding action from the context menu. The plot allows for selecting and restoring conformations. By clicking on a data point corresponding to a conformation present in the document, this conformation will be selected in the **Document view** and vice versa. By double-clicking on a data point, the corresponding conformation, if present in the document, will be restored. You can use the filter to modify what is shown both in the results table and in the plot. ## Loading previously computed results You can load the previously computed results obtained with AutoDock Vina Extended using the **Load** functionality in the **Results** tab. Please note that you shouldn't modify the hierarchy of the project directory or remove files if you want to be able to load them back into AutoDock Vina Extended. There are several options for loading the results: - **Only the table of results (fast)** - loads only the table of results without loading molecules and conformations. Ligands and their conformations can be loaded later from the results table. - **Top ligands** - loads results (molecules and conformations) only for the specified number of top ligands (by score). The other ligands and their conformations can be loaded later from the results table. - **Select results to load** - loads results (molecules and conformations) only for the selected ligands - a pop-up dialog will appear from which you can select the results to load. The other ligands and their conformations can be loaded later from the results table. - **All results (slow)** - loads all the modes for all the ligands. Please note that it might take time to load docking results for a big ligand library. Let's now try to load the results that we just computed. Open a new document (`Ctrl`/`Cmd` + `3` + `N`). Click on the **Load** button and navigate to the directory with the results: In the next pop-up dialog, select **Select results to load** from the list and check the **Load score results for other ligands** option to load score results for the non-selected ligands in the results table as well. Another dialog should appear with a list of ligands found in the results directory. You can deselect all of them by clicking on the **Deselect all** button and then check the ones which you want to load. Please note that loading results for many ligands might take some time. You can later load the other ligands and their conformations from the results table (see below). A new folder with the results should appear in the document, containing two subfolders: - `Receptors` with a receptor and groups with flexible residues and side chains if they were specified. - `Docked ligands` with subfolders for each loaded ligand, each containing a ligand and its conformations. If you do not see the loaded receptor or ligands in the document, please make sure that their structural models are checked in the **Document view** as shown in the image below. You can load results for other ligands in the results table by right-clicking on a ligand for which you want to load the results and choosing **Load ligand results** from the context menu. This will load the ligand and its conformations in a subfolder with the ligand's name in the `Docked ligands` folder. ## Performing further analysis SAMSON provides different tools to perform analysis of the results. You can add various visual models, measure distances, compute some parameters, and check for ligand-receptor interactions. Below you will find some examples. ### Visualizing Let's first add some visual models for the system. You can apply a visual preset in one click using **Visualization > Visual preset** - select *Protein-ligand* visual preset. Or you can apply visual models yourself - follow the instructions below. Tip You can learn more about visualization in SAMSON thanks to the interactive tutorials (**Help > Tutorials**) or from the [User guide: Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md). First, select the receptor and add a secondary structure visual model to it using **Visualization > Visual model > Ribbons**. This should add a new secondary structure visual model to the document. A hint: if you want to hide a visual model, simply uncheck it in the Document view; if you want to remove it then right-click on it and choose Erase from the context menu. Let's now add labels and a licorice visual model for residues surrounding the ligand. First, we need to select residues surrounding the ligand. For that, select the ligand and click on **Select > Biology > Binding sites** and set the parameters as in the image below, and click OK. This will select the residues surrounding the currently selected ligand. You can save this selection in a group by clicking on the **Current selection** button in the **Document view** and clicking on **Create group** in the context menu or on **Select > Group**. While having these residues selected, click in the context toolbar on to add labels and choose **Add label to... > Residues**. This will add in the document a new folder called `Residue labels`. You can easily hide labels by either unchecking them in the document or by deleting them. Tip See [User Guide: Labeling](https://documentation.samson-connect.net/users/latest/labeling/index.md). Let's now add a licorice visual for these residues. While having these residues selected, go to the **Visualization > Visual model > Licorice** - this will add a licorice visual model for the selected residues. If you want, you can colorize carbons in the receptor based on e.g. the residue sequence number. For that, select the receptor (**Select > Biology > Receptor**) and then go to **Select > Atoms > Carbons**. This will select all carbons in the current selection. Let's now colorize them by the residue sequence number such that their color would correspond to the default style of secondary structure colorization. For that, choose from the **Visualization > Color > Per attribute** menu the **Residue index** option. This should colorize both the carbons in the receptor's structural model and in the added licorice visual model since the licorice visual model doesn't have a specific color scheme applied to it. Now let's hide the receptor's structural model by unchecking it in the document. In the end, you should see something like in the image below: Please note that you can modify the appearance of visual models using the **Inspector**. ### Protein-Ligand Interaction Analyzer The [Protein-Ligand Interaction Analyzer](https://www.samson-connect.net/extensions/98bd1552-4642-9e86-6a78-83c9e96a63ee) SAMSON Extension allows for computing the contact area, H-bonds between a ligand and a receptor, ligand surrounding residues, and some other parameters. Check out its other tabs for more functionality. ### Hydrogen bonds The [Hydrogen Bond Finder](https://www.samson-connect.net/extensions/e0caae67-7422-ef1a-bf97-bcb88f1d2a11) SAMSON Extension allows one to find and visualize hydrogen bonds (H-bonds) inside a molecule or between molecules, e.g., between a ligand and a receptor. To find H-bonds between a ligand and a receptor, select the second option ("... in the current selection and the system"), then select the receptor and click on the **Set** button, modify parameters if necessary (you can later modify them in the created H-bond visual model using the **Inspector**), then select a ligand and click on the **Add hydrogen bond visual model** button. This will add a new H-bond visual model to the document. If you want to modify the H-bond detection parameters, right-click on the newly created H-bond visual model and choose **Inspect** from the context menu - this will open the **Inspector** in which you can modify parameters. That's all, thank you for completing this tutorial on the [AutoDock Vina Extended SAMSON Extension](https://www.samson-connect.net/extensions/1afc50e6-3567-fa25-1e09-415ebf4d05d7). ## Related tutorials - [Protein preparation and validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) for preparing protein structures before docking. - [Generate analogue series with positional analogue scanning](https://documentation.samson-connect.net/tutorials/smiles-manager/perform-positional-analogue-scanning-using-the-smiles-manager-element/index.md) for creating ligand analogs before docking. - [Strain Explorer](https://documentation.samson-connect.net/tutorials/strain-explorer/strain-explorer/index.md) for comparing ligand strain after docking or conformer generation. ## Next step Use the docking poses and scores to choose candidates for interaction analysis, ligand refinement, or molecular dynamics with [GROMACS Wizard protein-ligand systems](https://documentation.samson-connect.net/tutorials/gromacs-wizard/protein-ligand-systems/index.md). ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). ## References ______________________________________________________________________ 1. [O. Trott, A. J. Olson, AutoDock Vina: improving the speed and accuracy of docking with a new scoring function, efficient optimization and multithreading, Journal of Computational Chemistry 31 (2010) 455-461](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3041641/) [↩](#fnref:1 "Jump back to footnote 1 in the text") # Generate a Transition Path Between Protein Structures with ARAP Interpolation Use the [ARAP Interpolator](https://www.samson-connect.net/extensions/d550a902-3427-8788-ddd7-14d6c0e2c140) extension in SAMSON to generate, within a few seconds, a smooth, realistic path between two protein conformations using *As-Rigid-As-Possible (ARAP)*[1](#fn:1) interpolation. It can be used as part of the workflow for applications in conformational analysis, transition state modeling, or umbrella sampling setup. *This image is from the use case tutorial on [computing the opening motion of the SARS-CoV-2 spike](https://documentation.samson-connect.net/tutorials/sars-cov-2/coronavirus-computing-the-opening-motion-of-the-sars-cov-2-spike/#how-this-motion-was-computed) where ARAP Interpolation was used to generate an interpolated path between open and closed states of the spike protein.* ## Why Use It? - Compute continuous structural transitions in seconds. - Visualize and export intermediate conformations. - Build realistic reaction coordinates for free energy simulations. - Aligns and places conformers using a biologically meaningful geometric model. ## What you will learn In this tutorial, you will learn how to generate a smooth transition path between two protein conformations with ARAP Interpolation in SAMSON. ## Before you start 1. Log into [SAMSON Connect](https://www.samson-connect.net/). 1. Visit the [ARAP Interpolator](https://www.samson-connect.net/extensions/d550a902-3427-8788-ddd7-14d6c0e2c140) Extension page and click **Add**. 1. Restart SAMSON - your extension will be ready to use. ## Step 1 - Loading protein structures Fetch the example structures in SAMSON: - Open **Home > Fetch**. - Input `1DDT 1MDT` in **PDB** or **PDB (mmCIF)**. - Click the corresponding **Load** button. `1DDT` and `1MDT` represent two conformations of the *Diphtheria Toxin* (chains `A` and `B`). You'll work only with chain `A`: - Expand `1MDT` in the **Document view** to see the chain `B`. - Select and **delete chain `B`** (click `Del` or click **erase** in the pop-up context toolbar). Our goal is to generate a path from the chain `A` of `1DDT` to chain `A` of `1MDT`. Then run **Home > Prepare** to clean both structures (remove alternate locations, water, ligands, ions). Need Help Preparing Structures? Refer to the [Protein Preparation & Validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) tutorial for guidance. ## Step 2 - Create Conformations To use **ARAP Interpolator**, create **conformations** from the two cleaned structures: - Select the structure, e.g., `1DDT`, in the **Document view**. - Click **Edit > Conformation** and name it e.g., `1DDT A`. Do the same for `1MDT` and name its conformation as `1MDT A`. These conformations serve as the **start** and **goal** of the interpolation path. ## Step 3 - Run the ARAP Interpolation App Open the app via **Home > Apps > Biology > ARAP Path Interpolation**. **Choose Conformations:** - Click **Get conformations from the active document**. - Choose **Start**: `1DDT A` and **Goal**: `1MDT A`. **Matching Atoms:** For **Construct ARAP vertices by matching**, choose **All except hydrogens**. This option considers only non-hydrogen atoms for matching the atoms between the start and goal conformations. The matched atoms in the start conformation will be considered as ARAP vertices. Matching Atoms Options - **All atoms**: consider all the atoms for matching. - **All except hydrogens**: consider all the atoms except hydrogens for matching. - **Only α-carbons**: consider only α-carbon atoms for matching. - **Only backbone atoms**: consider only backbone atoms for matching. **Building ARAP Edges:** Check: - **from bonds in the Start structure** - creates ARAP edges considering all the bonds in the start structure. - **Try connecting α-carbons before and after missing residue segments** - creates an ARAP edge between the α-carbon atoms before and after each segment of missing residues in the start structure. These options define how connectivity and continuity are built across conformations. Under **Construct ARAP edges**, check the boxes of **from bonds in the Start structure** and **Try connecting α-carbons before and after missing residue segments**. The former creates ARAP edges considering all the bonds in the start structure. The latter creates an ARAP edge between the α-carbon atoms before and after each segment of missing residues in the start structure. Building ARAP Edges Options If multiple options are checked, the algorithm will add the ARAP edges in the order from top to bottom. - **from bonds in the Start structure**: create ARAP edges based on the covalent bonds in the start structure. - **from consecutive α-carbons**: create ARAP edges between α-carbons in consecutive residues of the start structure. - **from hydrogen bonds with cutoff distance**: create ARAP edges for hydrogen bonds whose lengths are shorter than the cutoff distance in the start structure. - **atom pairs whose distances are within a range**: create ARAP edges for atom pairs whose distances are within the specified range in the start structure. - **from α-carbon pairs whose distances are within a range**: create ARAP edges for α-carbon atom pairs whose distances are within the specified range in the start structure. - **Try connecting α-carbons before and after missing residue segments**: create ARAP edges for the α-carbon atoms before and after each segment of missing residues in the start structure. **Preprocessing:** Check **Perform alignment before interpolation**. This will align the start conformation with the goal conformation before performing ARAP interpolation. Set "**Number of path conformations**" to 20 to generate a path of 20 conformations (start and goal are included). You should have the settings as shown in the figure below. Click **Run** to compute the path interpolation. ## Step 4 - Analyze and Export Results After the interpolation is done, the computation information is summarized in the **Other information...** box at the bottom of the app. ### Visualize Pathlines Use the **slider** in the app to scrub through the interpolated conformations: ### Visualize Edge Construction A visual model *ARAP edges* is created. Colors correspond to the chosen construction types. - Toggle visibility in the **Document view**. - View edge colors to understand path construction logic. You can always show/hide the ARAP edges in the viewport by checking/unchecking the **ARAP edges** visual model in the **Document view**. Visualizations in SAMSON Learn more about visualizations in SAMSON from [User Guide: Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md). ### Export options - **Export path**: saves a *path* (trajectory) object in the current SAMSON document. - **Export PDB**: outputs the whole path into a PDB file and each conformation as a sequential PDB file. ## Troubleshooting If you get the following error when trying to run the computation with **ARAP interpolator**: *"Cannot proceed because the structure does not make one connected component"*. It means that you have one or more non-connected structures in one of the systems, e.g., because water, ions, or ligands were not removed. Run **Home > Prepare** to clean both structures (remove alternate locations, water, ligands, ions). ## Next Steps Use this ARAP-generated path as input for simulation techniques: - [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5) for [umbrella sampling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/umbrella-sampling/index.md). - Steered MD or [P-NEB](https://documentation.samson-connect.net/tutorials/pneb/optimize-transition-paths-with-parallel-nudged-elastic-band/index.md) refinement. - Visualization or dimensionality reduction of structural ensembles. ## Related tutorials - [Optimize transition paths with P-NEB](https://documentation.samson-connect.net/tutorials/pneb/optimize-transition-paths-with-parallel-nudged-elastic-band/index.md) for refining paths. - [Pathlines](https://documentation.samson-connect.net/tutorials/pathlines/pathlines/index.md) for visualizing center-of-mass motion along paths. - [Export atom trajectories along paths](https://documentation.samson-connect.net/tutorials/export-along-path/export-atoms-trajectories-along-paths/index.md) for exporting selected atoms along a path. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). ## References ______________________________________________________________________ 1. [Minh Khoa Nguyen, Léonard Jaillet, and Stéphane Redon. As-Rigid-As-Possible molecular interpolation paths. Journal of Computer-Aided Molecular Design (2017) 31: 403.](https://doi.org/10.1007/s10822-017-0012-y) [↩](#fnref:1 "Jump back to footnote 1 in the text") # Predict Biomolecular Structures Thanks to the [Biomolecular Structure Prediction](https://www.samson-connect.net/extensions/775e79a8-6adc-09c5-081a-faf34c87dc93) extension in SAMSON, you can launch cloud structure predictions using one of the following services: - **AlphaFold-2** - **Boltz-2** - **Chai-1** ## What you will learn In this tutorial, you will learn how to launch biomolecular structure predictions in SAMSON with AlphaFold-2, Boltz-2, and Chai-1. ## Before you start - Add the [Biomolecular Structure Prediction](https://www.samson-connect.net/extensions/775e79a8-6adc-09c5-081a-faf34c87dc93) extension. - Decide which prediction service matches your system and input type. - Keep your sequences, FASTA files, CCD codes, or SMILES strings ready before you open the app. You can access the prediction services through **Home > Predict**. The predictions are done in the cloud, and data are sent via a secure connection. You can view the results in SAMSON in **Interface > Cloud jobs** or on [SAMSON Connect > Account > Jobs](https://www.samson-connect.net/user/jobs). Note When prediction results are loaded in SAMSON, it will colorize the structures based on pLDDT values, if they are available in the files. ## Predicting with AlphaFold-2 Predict biomolecular structures using **AlphaFold-2** [1](#fn:1) in a few steps in SAMSON: - Open **Home > Predict**. - Choose **AlphaFold-2** service. - Enter one or more FASTA files. - Choose the AlphaFold model (monomer, multimer, etc.) and the database for multiple sequence alignment. - Click **Start prediction**. Note Predictions are performed using a choice of cloud machines with varying performance and costs, including powerful instances with A100 GPUs. [Contact us](mailto:contact@samson-connect.net) to request computing credits or [buy computing credits](https://www.samson-connect.net/computingCredits) directly. Any publication that discloses findings arising from using the AlphaFold service should cite the AlphaFold paper [1](#fn:1) and, if applicable, the AlphaFold-Multimer paper. ## Predicting with Boltz-2 Predict biomolecular structures using **Boltz-2** [2](#fn:2) in a few steps in SAMSON: - Open **Home > Predict**. - Choose **Boltz-2** service. - Click on **Add protein**, **Add DNA**, **Add RNA**, or **Add ligand** to enter the corresponding sequences, CCD codes, or ligand SMILES strings. - Click **Add modification** if you want to alter the sequences (for proteins, DNA, or RNA), and enter the position (the residue index) and the CCD code of the modification. - Click **Start prediction**. Note Calculations are performed on a dedicated A100 GPU in the cloud and use computing credits. A typical structure prediction with Boltz-2 will cost between 0.5 and 1 computing credit. [Contact us](mailto:contact@samson-connect.net) to request computing credits or [buy computing credits](https://www.samson-connect.net/computingCredits) directly. You can watch a [video tutorial](https://www.youtube.com/watch?v=KJVeCanq6AQ) and learn how to: - use **Boltz-2** in the [Biomolecular Structure Prediction](https://www.samson-connect.net/extensions/775e79a8-6adc-09c5-081a-faf34c87dc93), - share job results with colleagues, - generate protein-ligand interaction diagrams - all in under five minutes. ## Predicting with Chai-1 Predict biomolecular structures using **Chai-1** [3](#fn:3) in a few steps in SAMSON: - Open **Home > Predict**. - Choose **Chai-1** service. - Click on **Add protein**, **Add DNA**, **Add RNA**, or **Add ligand** to enter the corresponding sequences or SMILES strings. - Click **Add pocket restraint** if you want to add a distance restraint between a residue (for proteins, DNA, or RNA) and a chain. - Click **Add contact restraint** if you want to add a distance restraint between two residues. - Click **Start prediction**. Note Calculations are performed on a dedicated A100 GPU in the cloud and use computing credits. A typical structure prediction with Chai-1 will cost between 0.5 and 1 computing credit. [Contact us](mailto:contact@samson-connect.net) to request computing credits or [buy computing credits](https://www.samson-connect.net/computingCredits) directly. ## Related tutorials - [Protein preparation and validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) for cleaning protein structures before downstream work. - [Protein alignment](https://documentation.samson-connect.net/tutorials/protein-aligner/protein-aligner/index.md) for comparing predicted structures with known or related structures. - [GROMACS Wizard tutorials](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md) for preparing predicted structures for simulation when appropriate. ## Next step Inspect the predicted structures in SAMSON, compare candidates when needed, and prepare the chosen model for docking, simulation, or visualization. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). ## References ______________________________________________________________________ 1. [Jumper, J., Evans, R., Pritzel, A. et al. Highly accurate protein structure prediction with AlphaFold. Nature 596, 583–589 (2021). https://doi.org/10.1038/s41586-021-03819-2](https://www.nature.com/articles/s41586-021-03819-2) [↩](#fnref:1 "Jump back to footnote 1 in the text")[↩](#fnref2:1 "Jump back to footnote 1 in the text") 1. [Saro Passaro, et al. Boltz-2: Towards Accurate and Efficient Binding Affinity Prediction. bioRxiv 2025.06.14.659707](https://www.biorxiv.org/content/10.1101/2025.06.14.659707v1) [↩](#fnref:2 "Jump back to footnote 2 in the text") 1.  [↩](#fnref:3 "Jump back to footnote 3 in the text") # Generate crystal models Use the [Crystal Creator](https://www.samson-connect.net/extensions/58a75a78-abbc-2c60-6214-e668b5c45a0d) Extension in SAMSON to import CIF files, inspect crystal properties, cut crystal slabs, and build your own periodic models from unit-cell data. ## What you will learn In this tutorial, you will learn how to import CIF files, inspect crystals, and build crystal models in SAMSON with Crystal Creator. ## Before you start - Add [Crystal Creator](https://www.samson-connect.net/extensions/58a75a78-abbc-2c60-6214-e668b5c45a0d) from [SAMSON Connect - Marketplace](https://www.samson-connect.net/extensions) if it is not already installed. - If you want to follow the import workflow, download a CIF file from one of the sources listed below. - Use this page both as a first tutorial and as a reference when you need to build a custom crystal later on. ## Read a crystal structure To have your first crystal, you can import one. With the [Crystal Creator App](https://www.samson-connect.net/extensions/58a75a78-abbc-2c60-6214-e668b5c45a0d), you can load CIF (Crystallographic Information File) files. First, go fetch some nice crystals on those two websites: - The American Mineralogist Crystal Structure Database: - The RRUFF Project Database: I personally recommend testing Macdonaldite, Quartz, and Zorite, but if you have a favorite crystal and you find it, test it. Open your CIF file in SAMSON. A window lets you choose the number of crystal unit cells, if you prefer to import the mere data without the symmetries, and if you want to see the mesh. Click on **Open** and the structural model of the crystal and its property model appear in the data graph (see [User guide: Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md) if you have problems opening files in SAMSON). Depending on the crystal you have just read, the unit cells of your crystal can be different. Indeed, interesting properties of a crystal appear with randomly distributed defects or substitutions; those are described in the CIF file and are used by the app to create a crystal with proper defects and substitutions. ## Manipulate a crystal Right-click on the property model and select **properties**. The first tab of this property window has 4 tools: - A button to find back your crystal. - A checkbox to see its mesh. - A toolbox to cut your crystal. The first three boxes describe the cutting direction (the Miller indices) and the fourth is the distance from position 0 where the cut is done. - A toolbox to generate another crystal. The second tab is a tool to check if the generated crystal contains the proper amount of defects and substitutions. By clicking on **check atoms ratio**, you can see, for each atom site, whether its ratio of presence/absence is respected. Download and open a diamond crystal file and cut it in the direction `[111]` to see its compact hexagonal structure. ## Create your own crystal Open the Crystal Creator App via **Home > Apps > Materials > Crystal Creator** or search for it in the top search box (`Shift`+`E`). In this app, you can: - Choose the position 0 of your crystal. - Choose the unit cell shape. Either by writing its cell parameters (first tab) or directly by writing the unit cell vectors (second tab). The button **Write Matrix**/**Write Vectors** allows you to pass from one notation to the other. - Choose the atoms composing your unit cell. It should be written like this: ``` ... ``` The atom symbol has to start by its atomic element symbol (C, Al, Kr ...) that can be followed - without space - by other characters to identify it. Depending on the tab you are in, the atom coordinates are in 'relative position', i.e., a proportion of the unit cell vectors X, Y and Z, or in 'absolute position', in angstroms. - Choose the number of unit cells you want to generate. You can also save and load all your crystals by saving their settings ('save' icon on the property window). ### Examples For a Face-Centered Cubic (FCC) Aluminum crystal, take a cubic unit cell of lattice parameter 4.05 Å, and write in the 'relative position' tab: ``` Al 0 0 0 Al 0 0.5 0.5 Al 0.5 0 0.5 Al 0.5 0.5 0 ``` If you want a diamond crystal, you can choose a cubic unit cell of lattice parameter 3.60 Å and write in the 'relative position' tab: ``` C0 0 0 0 C1 0.25 0.25 0.25 C2 0 0.5 0.5 C3 0.5 0 0.5 C4 0.5 0.5 0 C5 0.25 0.75 0.75 C6 0.75 0.25 0.75 C7 0.75 0.75 0.25 ``` Now, try to create your own Sphalerite (SiZ) crystal, and use the SAMSON tool to create all the bonds. ## Defects in diamond We will see the effect of defects on the structure of diamond: - Load your diamond crystal (the .cif one) and create the bonds. - Minimize its structure with the Brenner interaction model. - Make a copy of the diamond file and open it in a text editor. - At the end of the new file, instead of ``` loop_ _atom_site_label _atom_site_fract_x _atom_site_fract_y _atom_site_fract_z C 0.00000 0.00000 0.00000 ``` copy and paste: ``` loop_ _atom_site_label _atom_site_fract_x _atom_site_fract_y _atom_site_fract_z _atom_site_occupancy C 0.00000 0.00000 0.00000 0.95 ``` The inserted line and the last figure mean our carbon atom has a probability of 0.95 to be present. - Load your diamond with defects, create the bonds. - See how the structure changed with defects. ## Related tutorials - [Build carbon nanotube models](https://documentation.samson-connect.net/tutorials/nanotubes/building-nanotubes-models/index.md) for another materials-science structure-building workflow. - [UMA Force Field](https://documentation.samson-connect.net/tutorials/uma-force-field/uma-force-field/index.md) if you want to use machine-learning atomistic models after building a structure. ## Next step Open the [Extensions Tutorials](https://documentation.samson-connect.net/tutorials/#materials-science) materials-science section when you want more structure-building workflows. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # Export atom trajectories along paths The [Export Along Paths](https://www.samson-connect.net/extensions/cc339322-498f-28e6-90b6-5e656cc345c3) extension in SAMSON allows you to export atomic coordinates (for all or only selected atoms) along defined paths - useful for preparing input files for reaction coordinate studies, free energy calculations, or extracting movement data from ligand pathways. ## What you will learn In this tutorial, you will learn how to export atomic coordinates along a path in SAMSON for later analysis or simulation workflows. ## Before you start 1. Log into [SAMSON Connect](https://www.samson-connect.net/). 1. Visit the [Export Along Paths](https://www.samson-connect.net/extensions/cc339322-498f-28e6-90b6-5e656cc345c3) Extension page and click **Add**. 1. Restart SAMSON - your extension will be ready to use. ## Step 1 - Load the Sample System Load the sample system: 1. Click **Home > Download**. 1. Paste (). 1. Click **Download**. This will load a document with this tutorial's sample from [SAMSON Connect](https://www.samson-connect.net/). The sample document contains a structural model of *Lactose permease* (`1PV7`) with its ligand *Thiodigalactosid* (`TDG`) and the unbinding paths generated with [Ligand Path Finder](https://www.samson-connect.net/extensions/280cac50-31cd-e0ad-76c3-d254cd736967) (see the [Ligand Path Finder tutorial](https://documentation.samson-connect.net/tutorials/ligand-path-finder/ligand-path-finder/index.md)). In the **Document view** (1), you can see the protein under the name `Protein_chain_A`, the ligand under the name `TDG`, and two paths. 1. **Interface menu > Document view** or\ , : `Ctrl`+`1`,\ : `Cmd`+`1` Note **Paths** are SAMSON nodes that store atomic trajectories of a group of atoms. Double-clicking on a path in the **Document view** starts/stops moving atoms along the path. For some applications, it is useful to export the coordinates of a subset of atoms along the path, for example, to generate a reaction coordinate. For example, once you have [computed an extraction path for a ligand](https://documentation.samson-connect.net/tutorials/ligand-path-finder/ligand-path-finder/index.md) (and optimized this path with e.g., the [parallel nudged elastic band method](https://documentation.samson-connect.net/tutorials/pneb/optimize-transition-paths-with-parallel-nudged-elastic-band/index.md)), you might want to export the coordinates of the ligand along the path in order to perform [free energy calculations](https://aip.scitation.org/doi/10.1063/1.2432340). ## Step 2 - Open the Export Along Paths App Open the **Export Along Paths** app via **Home > Apps > All > Export Along Paths** . You can also find it in the **Find everything...** (`Shift`+`E`). ## Step 3 - Export atom trajectories along a path ### Option 1 - Export All Atoms 1. [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) one or more paths in the **Document view**. 1. Choose export mode: - All frames in a single PDB file - Each frame as a separate PDB file 3. Click **Export atoms along paths to PDB files**. You'll be prompted to select a destination folder and file prefix. Optional: Expand the **Advanced** section to change frame export interval. ### Option 2 - Export a Subset of Atoms 1. Expand the **Advanced** panel. 1. [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a subset (e.g., ligand `TDG`) in the **Document view**. 1. Click **Add** to define this as a model to export. This adds a named model (i.e., a group of atoms) to the export list: You can: - Rename the model by double-clicking its name. - Add multiple sets of atoms. - Click **Select**/**Unselect** to highlight included atoms. Or use the context menu for the corresponding line. - Use the **Reset** () button to redefine. Or use the context menu for the corresponding line. You can rename the model (i.e., the set of atoms) by double-clicking on the corresponding line in the list of models. You can add more models via the same procedure. When ready: - Choose export format (single or multiple PDB files). - [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) the relevant path(s). - Click **Export atoms along paths to PDB files**. You'll be prompted to select a destination folder and file prefix. ## Use Cases in Molecular Modeling - Generate **reaction coordinate files** for free energy profiling. - Export **ligand exit/entry trajectories** for enhanced sampling. - Output intermediate states for visualization, etc. - Track only specific atoms (e.g., ligand, binding site, backbone). ## Related tutorials - [Ligand Path Finder](https://documentation.samson-connect.net/tutorials/ligand-path-finder/ligand-path-finder/index.md) for computing ligand unbinding paths. - [Protein Path Finder](https://documentation.samson-connect.net/tutorials/protein-path-finder/protein-path-finder/index.md) for computing protein transition paths. - [Optimize transition paths with P-NEB](https://documentation.samson-connect.net/tutorials/pneb/optimize-transition-paths-with-parallel-nudged-elastic-band/index.md) for refining path conformations before export. ## Next step Use the exported coordinates in your downstream analysis, visualization, or simulation workflow. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # Fast geometry optimization with FIRE minimizer **Geometry optimization** is a core task in molecular modeling, helping you reach stable, realistic molecular structures that correspond to energy minima. The FIRE Minimizer (Fast Inertial Relaxation Engine) is a fast, efficient algorithm - especially for large-scale molecular motions - that helps fine-tune 3D geometries for simulations and molecular design workflows. This tutorial shows how to use the [FIRE Minimizer](https://www.samson-connect.net/extensions/8ec255b0-7326-0bed-366e-40be71c1d160) SAMSON extension, based on the method by Bitzek et al.[1](#fn:1), to clean up a structure before simulation or interactive modeling. ## Why Use FIRE? - Faster than steepest descent, especially for collective motions. - Works with any SAMSON interaction model. - Ideal for pre-simulation cleanup and structural relaxation. ## What you will learn In this tutorial, you will learn how to use the FIRE minimizer in SAMSON for fast geometry optimization of molecular systems. ## Before you start 1. Log into [SAMSON Connect](https://www.samson-connect.net/). 1. Visit the [FIRE Minimizer](https://www.samson-connect.net/extensions/8ec255b0-7326-0bed-366e-40be71c1d160) Extension page and click **Add**. 1. Restart SAMSON - your extension will be ready to use. 1. Open a small test system first if you want to see the effect of the minimization settings clearly. ## How to Use the FIRE Minimizer ### Step 1 - Load a Molecular System You can load molecules from the PDB, MOL2, or other [supported formats](https://documentation.samson-connect.net/users/latest/supported-formats/index.md). Tip Learn more: [Loading Molecules Guide](https://documentation.samson-connect.net/users/latest/loading-molecules/index.md) ### Step 2 - Add a Simulator 1. Go to **Edit > Add Simulator**. 1. Choose the interaction model you want. 1. In the *State Updaters* list, choose **FIRE**. Tip Learn more: [Simulators Overview](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/#simulators) ## FIRE Minimizer Settings | Setting | Description | | ------------- | --------------------------------------------------- | | **Step size** | Initial integration step for minimization. | | **Steps** | Number of FIRE steps between updating the viewport. | | **Fixed** | Force the step size to remain constant (optional). | ### Resetting the History If you manually moved atoms while minimizing and want to clear the FIRE history, press **Reset**. ## FIRE vs. Steepest Descent **FIRE** offers significantly faster convergence than the steepest descent algorithm, especially when potential energy changes are small but geometry still evolves significantly (large-scale motions). FIRE Relaxation Steepest Descent Relaxation To visualize the progress more clearly, increase the **Steps** value for less frequent but more pronounced updates. ## Integration in SAMSON Workflows FIRE is implemented as a [SAMSON State Updater](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md), so it can work in any app or extension that needs to perform geometry optimization. For example, it is used in [Molecular Restrainer](https://www.samson-connect.net/extensions/f09f42ea-0a8f-caa6-8497-dda5aefc0448) Extension to perform energy minimization of NMR-derived structures. ## Related tutorials - [Molecular Restrainer](https://documentation.samson-connect.net/tutorials/molecular-restrainer/molecular-restrainer/index.md) uses FIRE for restrained minimization of NMR-derived structures. - [Interactive Modeling Universal Force Field](https://documentation.samson-connect.net/tutorials/uff/im-uff/index.md) shows another route for interactive force-field based modeling. ## Next step Continue with the [SAMSON User Guide: modeling and simulation](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/index.md) when you want to learn how simulators, interaction models, and state updaters work together in SAMSON. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). ## References ______________________________________________________________________ 1. [Erik Bitzek, Pekka Koskinen, Franz Gähler, Michael Moseler, and Peter Gumbsch, Structural Relaxation Made Simple. Physical Review Letters, Vol. 97, 170201 (2006)](https://doi.org/10.1103/PhysRevLett.97.170201) [↩](#fnref:1 "Jump back to footnote 1 in the text") # Covalent and non-covalent protein-ligand docking with the Fitted Suite by Molecular Forecaster Use the [FITTED Suite SAMSON Extension](https://www.samson-connect.net/extensions/b72505d0-6942-ac90-2a78-b81b9d0cc5a1) to run both covalent and non-covalent protein-ligand docking workflows in SAMSON. The [FITTED Suite SAMSON Extension](https://www.samson-connect.net/extensions/b72505d0-6942-ac90-2a78-b81b9d0cc5a1) was developed in partnership with [Molecular Forecaster](https://molecularforecaster.com/) and wraps their [Fitted Docking software](https://molecularforecaster.com/products/) [1](#fn:1), [2](#fn:2). > FITTED stands for Flexibility Induced Through Targeted Evolutionary Description. This fully automated docking software is unique in that it considers the flexibility of macromolecules, the presence of bridging "displaceable" water molecules, covalent functional groups, and proton shifts upon metal coordination. FITTED is based on a genetic algorithm with an emphasis on balancing speed and accuracy. It has excellent scoring functions and accuracy (see third-party studies) and can be applied to metalloenzymes, kinases, nucleic acids, NHRs, GPCRS, etc. [Molecular Forecaster](https://molecularforecaster.com/) The [FITTED Suite SAMSON Extension](https://www.samson-connect.net/extensions/b72505d0-6942-ac90-2a78-b81b9d0cc5a1) automates the protein-ligand docking by using the following accessory programs by [Molecular Forecaster](https://molecularforecaster.com/): - **PREPARE** (Protein Rotamers Evaluation and Protonation based on Accurate Residue Energy) automates protein preparation by cleaning up frequent liabilities, optimizing various physicochemical properties, and orienting water molecules. - **PROCESS** (Protein Conformational Ensemble System Setup) generates modified protein files for their use with FITTED. - **SMART** (Small Molecule Atom-typing and Rotatable Torsion assignment) characterizes small molecules for their use with FITTED and IMPACTS. - **CONVERT** (Conformational Optimization of Necessary Virtual Enantiomers, Rotamers, and Tautomers) transforms 2D small molecules into accurate 3D representations. ## What you will learn In this tutorial, you will learn how to set up and run covalent and non-covalent protein-ligand docking workflows with the FITTED Suite in SAMSON. ## Before you start - Add the [FITTED Suite SAMSON Extension](https://www.samson-connect.net/extensions/b72505d0-6942-ac90-2a78-b81b9d0cc5a1). - Download the [FITTED tutorial archive](https://documentation.samson-connect.net/wp-content/uploads/FITTED_tutorial.zip). - Keep in mind that the page covers two related workflows, so it is best followed from top to bottom the first time. ## Non-covalent docking: 1E2K Launch **SAMSON** and open the `1E2K-A.sam` file provided in the [archive](https://documentation.samson-connect.net/wp-content/uploads/FITTED_tutorial.zip). To open a file in SAMSON, click on **Home > Open** or simply drag-and-drop the file in SAMSON. You can also download this file directly in SAMSON from [SAMSON Connect - Assets](https://www.samson-connect.net/documents), by clicking on **Home > Download** and providing the following link: . This will open a structural model of a thymidine kinase protein (`1E2K`, chain `A`) with the *(N)-methanocarba-thymidine* ligand (`TMC 500`) bound to it. You should see the following in the **Document view**: The **Document view** is a panel that shows the data graph structure representation of the opened document. In SAMSON, documents are hierarchies of SAMSON [nodes](https://documentation.samson-connect.net/users/latest/node-types/index.md) (molecules, folders, visual models, cameras, etc.). A document hierarchy is visible in the [Document view](https://documentation.samson-connect.net/users/latest/interface/#document-view) and its 3D representation in the **Viewport** (see [User guide: Interface](https://documentation.samson-connect.net/users/latest/first-look/index.md) for more information). You can read more about documents in [User guide: Documents](https://documentation.samson-connect.net/users/latest/documents/index.md). Tip If you have the **Document view** closed, you can open it via **Interface > Document view** or via the `Ctrl`+`1` shortcut on Windows and Linux or `Cmd`+`1` on Mac. ### Preparation of the system There is no preparation needed for the system in the tutorial. The FITTED Suite will automatically deal with water molecules and will use PREPARE to adjust bond order, add hydrogens, generate the possible tautomers, and optimize the H-bond network by an iterative algorithm. But, generally, you would need to check if atoms in the system have alternate locations and remove them if necessary. For that, you can use **Home > Prepare**. Please refer to the [Protein Preparation & Validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) tutorial for more information on how to prepare and fix protein systems. ### Setup of the system Let's now open the **FITTED Suite** app by selecting it in the **Home > Apps > Biology**. You can also find it using the **Find everything...** search box in the top menu of SAMSON - just start typing the app's name. Now, to set up the system we need to define the following: 1. a receptor; 1. a binding site; 1. a ligand. #### Setup of the receptor Select the 1E2K structural model from the document. Then in the **Set receptor** part of the **FITTED Suite** select **From document** and click on the corresponding **Set** button. Leave the **Water molecules** parameter to its default value and the **Macromolecules** parameter to its default value as well (Protein). Note that if you would like to dock a metalloprotein, DNA, or RNA you should change the **Macromolecules** parameter accordingly. #### Setup of the binding site There are three options to specify the binding site: 1. From bound ligand - specify the binding site based on an already bound ligand. 1. From selection - specify the center of the search grid based on the centroid of the selected atoms. 1. From position - specify the center of the search grid using a sphere in the **Viewport** (the central panel with a 3D representation of the document). Since in this tutorial we will be performing self-docking (docking of the ligand in its own crystal structure receptor) and we already have a bound ligand (`TMC 500`), we can specify the binding site based on it. The `TMC 500` bound ligand is part of chain `A`. You can find it in the document by expanding chain `A` or simply by typing `TMC 500` in the search bar of the **Document view.** Select the `TMC 500` ligand: For the sake of simplicity, this ligand is also referred to by the `TMC 500` group. Double-click on the `TMC 500` group in the document to select the ligand. Now, in the **Define binding site** part of the **FITTED Suite** select **From bound ligand** and click on the corresponding **Set** button. If you do not have a bound ligand, you can specify the binding site based on its position by selecting the **From position** option and moving in the **Viewport** the sphere representing the center of the binding site. #### Setup of the ligand Select the `TMC 500` ligand. The `TMC 500` bound ligand is part of chain `A`. You can find it in the document by expanding the chain `A` or simply by typing `TMC 500` in the search bar of the **Document view.** Select the `TMC 500` ligand. For the sake of simplicity, the `TMC 500` ligand is also referred to by the `TMC 500` group - you can simply double-click on the `TMC 500` group in the document to select the ligand. Now, in the **Set ligand** part of the **FITTED Suite** select **From document** and click on the corresponding **Set** button. Leave the option to prepare the ligand (perceive bond order and add hydrogens) checked. ### Running the docking Now we are almost ready to launch the docking. We only need to specify some docking parameters (you can leave them by default): - Set the number of runs to 2. - Check the option to import the best pose only if you want to import only the best pose. - Set the docking mode to **Non-covalent**. At the top of the app, you can also select the **Output folder** where you would like the results to be saved. Once you have specified the necessary parameters, click on the **Dock** button. For the system in the tutorial, the docking may take a few minutes - the current stage is shown on this button and the logs can be seen below the results table. ### Results Once the docking calculations are done, the results should be shown in the results table and automatically loaded in the document. Please note that if you selected to import only the best pose then results only for this pose will be loaded in the table. You can export the table with results in a CSV file or copy each row separately via its context menu. When selecting a row in the results table it will also select the corresponding pose in the document. In the document, you should see a processed receptor (`1E2K_pro`) with added hydrogens and the resulting ligand pose. Let's now hide the initial structure by unchecking it in the **Document view** as follows: ## Performing further analysis SAMSON provides different tools to perform analysis of the results. You can add various visual models, measure distances, compute some parameters, and check for ligand-receptor interactions. Below you will find some examples. ### Visualizing Let's first add some visual models for the system. You can learn more about the visualization in SAMSON thanks to the interactive tutorials (**Help > Tutorials**) or to the [User guide: Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md). First, in the **Document view**, select the processed receptor (`1E2K_pro`) structural model and use the **Context Toolbar** or the **Visualization menu** to add a **Ribbons** structure. This should add a new secondary structure visual model to the document. Now you can hide the `1E2K_pro` structural model by unchecking it in the **Document view**. Tip If you want to hide a visual model, simply uncheck it in the **Document view**; if you want to remove it then right-click on it and choose **Erase** from the context menu. Let's now add labels and a licorice visual for residues surrounding the ligand. First, we need to select residues surrounding the ligand. For that, select the resulting ligand - `1E2K_log.mol2_DockingRun_*` - and click on **Select > Biology > Binding sites** and set the parameters as in the image below and click OK. This will select the residues surrounding the currently selected ligand. You can save this selection in a group by clicking on the **Current selection** button in the **Document view** and clicking on **Create group** in the context menu or on **Select > Group**. Name the group e.g. as "Binding site residues". Let's now add a licorice visual for these residues. While having these residues selected, go to the **Visualization menu** and click on the **Licorice** button - this will add a licorice visual model for the selected residues. If you want, you can colorize carbons in the receptor based on e.g. the residue sequence number. For that, select the receptor (`1E2K_pro`) and go to **Select > Atoms > Carbons**. This will select all carbons in the current selection. Let's now colorize them by the residue sequence number such that their color would correspond to the default style of secondary structure colorization. For that, choose from the **Visualization menu > Material > Per attribute** menu the **Residue index** option. This should colorize both the carbons in the receptor's structural model and in the added licorice visual model since the licorice visual model doesn't have a specific color scheme applied to it. Now let's hide the receptor's structural model by unchecking it in the document if you didn't already do it before. In the end, you should see something like in the image below: Please note that you can modify the appearance of visual models using the **Inspector**. If you want to learn more about visual models in SAMSON, please follow interactive tutorials in SAMSON (**Help > Tutorials**) or the [User guide: Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) tutorial. ### Protein-Ligand Interaction Analyzer The [Protein-Ligand Interaction Analyzer](https://www.samson-connect.net/extensions/98bd1552-4642-9e86-6a78-83c9e96a63ee) SAMSON Extension allows for computing the contact area, H-bonds between a ligand and a receptor, ligand surrounding residues, and some other parameters. Check out its other tabs for more functionality. Open the **Protein-ligand Interaction Analyzer** from the **Home > Apps > Biology** or simply by searching by its name in the **Find everything...** search bar in the top menu of SAMSON. Select the resulting receptor (`1E2K_pro`) and click on **Set** for Receptor. Choose the **Single ligand** option from the list. Select the resulting ligand (`1E2K_log.mol2_DockingRun_*`) and click on **Set** for Ligand. Now, click **Analyze**. ### Hydrogen bonds The [Hydrogen Bond Finder](https://www.samson-connect.net/extensions/e0caae67-7422-ef1a-bf97-bcb88f1d2a11) extension allows one to find and visualize hydrogen bonds (H-bonds) inside a molecule or between molecules, e.g. between a ligand and a receptor. To find H-bonds between a ligand and a receptor, select the second option ("**... in the current selection and the system**"), then select the resulting receptor (`1E2K_pro`) and click on the **Set** button, modify parameters if necessary (you can later modify them in the created H-bond visual model using the **Inspector**), then select the resulting ligand (`1E2K_log.mol2_DockingRun_*`) and click on the **Add hydrogen bond visual model** button. This will add a new H-bond visual model to the document. If you want to modify the H-bond detection parameters, right-click on the newly created H-bond visual model and choose **Inspect** from the context menu - this will open the **Inspector** in which you can modify parameters. ## Covalent docking: 5MAJ Please make sure to go through the [Non-covalent docking: 1E2K](#non-covalent-docking-1e2k) part of the tutorial first, since in this section we will be omitting some of the descriptions already mentioned in the section above. Launch **SAMSON** and open the 5MAJ.sam file provided in the [archive](https://documentation.samson-connect.net/wp-content/uploads/FITTED_tutorial.zip). To open a file in SAMSON, click on **Home > Open** or simply drag-and-drop the file in SAMSON. You can also download this file directly in SAMSON from [SAMSON Connect - Assets](https://www.samson-connect.net/documents), by clicking on **Home > Download** and providing the following link: . This will open a structural model of the human cathepsin L protein (`5MAJ`) with a *7KH* ligand (`7KH 301`) covalently bound to it. You should see the following in the **Document view**: Tip If you have the **Document view** closed, you can open it via **Interface > Document view** or via the `Ctrl`+`1` shortcut on Windows and Linux or `Cmd`+`1` on Mac. ### Preparation of the system There is no preparation needed for the system in the tutorial. The FITTED Suite will automatically deal with water molecules and will use PREPARE to adjust bond order, add hydrogens, generate the possible tautomers, and optimize the H-bond network by an iterative algorithm. But, generally, you would need to check if atoms in the system have alternate locations and remove them if necessary, and fix missing residues and heavy atoms. Please refer to the [Protein Preparation & Validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) tutorial for more information on how to prepare and fix protein systems. ### Modifying bond order and hybridization For some protein-ligand complexes where a ligand is already covalently bound to the protein, it might be necessary to modify some bond orders for an atom covalently bound to a receptor and specify the hybridization for some atoms in the ligand. This step is not necessary if you are docking a non-bound ligand. In the tutorial example, this has already been done, but we will describe here what has been done and how to do it. For convenience, the tutorial example has some saved groups in the document that link to a ligand and some other nodes. Let's zoom in on the part of the `7KH 301` ligand that needs a change in hybridization. Select the `C8` atom in the `7KH 301` ligand (expand chain `A` in the document and scroll down or type `7KH 301` in the search bar) or simply double-click on the `C8` in `7KH 301` group in the document - this will select the `C8` atom in it - and click `Shift`+`Space` to zoom on the selection: Here we have changed the bond order for the `C8-N7` bond to the triple bond as the ligand is nitrile when unbound. This can be done either using the **Edit > Edit bonds** editor or by selecting the bond and changing the corresponding parameters in the **Inspector**. Then we have set the hybridization for `C8` and `N7` atoms in the `7KH 301` ligand to **SP** by selecting them and modifying the corresponding parameters in the **Inspector**. ### Setup of the system Let's now open the **FITTED Suite** app by selecting it in the **Home > Apps > Biology**. You can also find it using the **Find everything...** search box in the top menu of SAMSON - just start typing the app's name. Now to set up the system we need to define the following: 1. a receptor; 1. a binding site; 1. a ligand. #### Setup of the receptor Select the 5MAJ structural model from the document and then in the **Set receptor** part of the **FITTED Suite** select **From document** and click on the corresponding **Set** button. Leave the **Water molecules** parameter to its default value and the **Macromolecules** parameter to its default value as well (Protein). Note that if you would like to dock a metalloprotein, DNA, or RNA you should change the **Macromolecules** parameter accordingly. #### Setup of the binding site Since in this tutorial we will be doing a self-docking and we already have a bound ligand (7KH 301), we can specify the binding site based on it. The `7KH 301` bound ligand is part of chain `A`. You can find it in the document by expanding chain `A` or simply by typing `7KH 301` in the search bar of the **Document view.** Select the `7KH 301` ligand: For the sake of simplicity, this ligand is also referred to by the `7KH 301` ligand group. Double-click on the `7KH 301` ligand group in the document to select the ligand. Now, in the **Define binding site** part of the **FITTED Suite** select **From bound ligand** and click on the corresponding **Set** button. If you do not have a bound ligand, you can specify the binding site based on its position by selecting the **From position** option and moving in the **Viewport** the sphere representing the center of the binding site. #### Setup of the ligand Select the `7KH 301` ligand. The `7KH 301` bound ligand is part of chain `A`. You can find it in the document by expanding chain `A` or simply by typing `7KH 301` in the search bar of the **Document view.** For the sake of simplicity, the `7KH 301` ligand is also referred to by the `7KH 301` ligand group. Double-click on the `7KH 301` ligand group in the document to select the ligand. Now, in the **Set ligand** part of the **FITTED Suite**, select **From document** and click on the corresponding **Set** button. Uncheck the option to prepare the ligand (perceive bond order and add hydrogens) since it has a modified bond order and hybridization. ### Running the docking Now we are almost ready to launch the docking. We only need to specify some parameters for covalent docking: - Set the number of runs to 2. - Check to import the best pose only if you want to import only the best pose. - Set the docking mode to **Covalent only**. Now we need to specify a covalent residue and a basic atom, the last one is optional. A covalent residue is a residue with which a covalent inhibitor will react. You can specify either the residue or an atom in it and the whole residue will be set automatically for you. In this protein-ligand complex, it is the sulfur atom (SG) in the `CYS 25` residue with which the `7KH 301` ligand covalently binds. The `CYS 25` residue is part of chain `A`. You can find it in the document by expanding chain `A` or simply by typing `CYS 25` in the search bar of the **Document view**. Select the `CYS 25` residue. Tip Click `Shift`+`Space` to zoom on the selection. For convenience, the `CYS 25` residue is also referred to by the `CYS 25` group. You can simply double-click on the `CYS 25` group - this should select the `CYS 25` residue - and then click on the **Set** button for **Covalent residue**. The setting of a basic atom is optional - it should be an atom in a residue adjacent to the covalent residue. Example: nitrogen in an adjacent histidine residue. We will specify the `ND1` nitrogen atom from the `HIS 163` residue which is adjacent to the covalent residue. The `HIS 163` residue is part of chain `A`. You can find it in the document by expanding chain `A` and then expanding the residue and its side chain to select the `ND1` nitrogen atom. You can also find it by typing `"ND1" in "HIS 163"` (note the quotes when searching by name) in the search bar of the **Document view**. Select the `ND1` atom. For convenience, the tutorial example has a group called `ND1` in `HIS 163` which refers to this atom. In the document, double-click on the `ND1` in `HIS 163` group - this should select the `ND1` atom in the `HIS 163` residue. Once you have the basic atom selected, click on the **Set** button for **Basic atom**. At the top of the app, you can also select the **Output folder** where you would like the results to be saved. Once you have specified the necessary parameters, click on the **Dock** button. For the system in the tutorial, the docking may take a few minutes - the current stage is shown on this button and the logs can be seen below the results table. ### Results Once the docking calculations are done, the results should be shown in the results table and automatically loaded in the document. You can export the table with results in a CSV file or copy each row separately via its context menu. When selecting a row in the results table it will also select the corresponding pose in the document. In the document, you should see a processed receptor (`5MAJ_pro`) with added hydrogens and the resulting ligand pose. In the case of the covalent docking, the resulting pose will also contain a part of the residue to which it is covalently docked. Let's now hide the initial structure by unchecking it in the **Document view** and the labels associated with the initial structure by unchecking the Labels folder as follows: For visualization purposes, let's now add a secondary structure visual model for the receptor. In the **Document view**, select the processed receptor (`5MAJ_pro`) structural model and then click on **Visualization > Visual model > Ribbons**. Now you can hide the `5MAJ_pro` structural model by unchecking it in the **Document view**. You can zoom in on the ligand by selecting it and pressing `Shift`+`Space`. You can see that the ligand is covalently bound to the sulfur atom from the `CYS 25` residue. Please check out the [Performing further analysis](#performing-further-analysis) section for more information on protein-ligand interaction analysis. If you want to learn more about visual models in SAMSON, please follow interactive tutorials in SAMSON (**Help > Tutorials**) or the [User guide: Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) tutorial. That's all, thank you for completing this tutorial on the [FITTED Suite SAMSON Extension](https://www.samson-connect.net/extensions/b72505d0-6942-ac90-2a78-b81b9d0cc5a1). ## Related tutorials - [Protein preparation and validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) for preparing protein inputs before docking. - [Dock ligands and libraries with AutoDock Vina Extended](https://documentation.samson-connect.net/tutorials/adve/docking-libraries-of-ligands-with-autodock-vina-extended/index.md) for another protein-ligand docking route. - [Strain Explorer](https://documentation.samson-connect.net/tutorials/strain-explorer/strain-explorer/index.md) for analyzing ligand strain in generated or docked conformations. ## Next step Compare the predicted binding modes, then continue with interaction analysis, analogue generation, or simulation of promising complexes. ## Video tutorial Learn more about the Fitted Suite from this video tutorial: [Protein-ligand docking with the FITTED Suite and the SAMSON molecular design platform](https://www.youtube.com/watch?v=rLKCTTPPKk0). ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). ## References ______________________________________________________________________ 1. [Moitessier N., Pottel J., Therrien E., Englebienne P., Liu Z., Tomberg A., Corbeil C.R. Medicinal Chemistry Projects Requiring Imaginative Structure-Based Drug Design Methods. Accounts of Chemical Research (2016), 49 (9), 1646-1657](https://pubs.acs.org/doi/abs/10.1021/acs.accounts.6b00185) [↩](#fnref:1 "Jump back to footnote 1 in the text") 1. [Therrien E., Englebienne P., Arrowsmith A.G., Mendoza-Sanchez R., Corbeil C.R., Weill N., Campagna-Slater V., Moitessier N. Integrating medicinal chemistry, organic/combinatorial chemistry, and computational chemistry for the discovery of selective estrogen receptor modulators with FORECASTER, a novel platform for drug discovery. Journal of Chemical Information and Modeling (2012), 52, 210-224](https://pubs.acs.org/doi/10.1021/ci2004779) [↩](#fnref:2 "Jump back to footnote 2 in the text") # Molecular Mechanics Force Fields Use this tutorial when you want to compute energies and forces with an Amber, CHARMM, or OpenFF-style molecular mechanics force field in SAMSON. You will create a **Molecular Mechanics Force Fields** interaction model, choose a force-field setup that matches your system, check that the selected force field can parameterize the target, then run or minimize the system interactively. ## What you will learn In this tutorial, you will learn how to: - choose between **Standard**, **Composite**, and **Advanced** setup workflows - install or update the local Amber, CHARMM, OpenFF, and reference Python bundles - prepare biomolecular targets before Amber or CHARMM typing - assign different force fields to different atom groups with NSL queries - inspect assigned atom types, per-atom parameters, warnings, energy, generated terms, and setup status ## Before you start Before creating a simulation in SAMSON, make sure that: - the **Molecular Mechanics Force Fields** extension is installed - the system you want to parameterize is loaded in the active document - the relevant atoms are selected if you want the simulator to target only part of the document For Amber or CHARMM protein and nucleic-acid workflows, prepare the structure first: choose one alternate location, add hydrogens after deciding protonation states, complete or cap termini, and remove unsupported heterogens unless they are intentionally parameterized. ## Choose the right setup Start from the system you have: | If your system is... | Use this setup | Typical choice | | --------------------------------------------------------------------- | -------------- | --------------------------------------------------------------- | | A protein, DNA, RNA, water, or ions | **Standard** | Amber 14, Amber 19, CHARMM 36, or CHARMM 36 2024 | | A small organic molecule | **Standard** | Sage or Parsley | | A protein-ligand complex where the ligand needs OpenFF parameters | **Composite** | Amber or CHARMM for the protein, Sage or Parsley for the ligand | | A system where different atom groups need different force-field files | **Advanced** | NSL groups, each with its own XML or OFFXML files | | A custom or experimental force-field workflow | **Advanced** | Official or local `.xml` / `.offxml` files | Use **Constrained** for routine minimization and interactive use. Use **Unconstrained** only when X-H bond flexibility needs to be preserved. ## Add the simulator 1. Open a document containing the molecular system you want to evaluate. 1. Add a simulator via **Edit > Simulate > Add simulator**. 1. Select **Molecular Mechanics Force Fields** as the interaction model. 1. Choose the state updater you want to use, for example [FIRE](https://documentation.samson-connect.net/tutorials/fire/ready-set-fire/index.md). 1. Press **OK**. The **Molecular Mechanics Force Fields** setup window appears. ## Install local bundles If no force-field choices appear yet, use the small reload button at the top of the setup window. This installs or updates the local Amber, CHARMM, OpenFF, and reference Python bundles used by the extension. The button tooltip tells you whether bundles will be installed or updated. During installation, the setup window shows a progress bar and a log area. When installation finishes, presets and official force-field files are refreshed automatically. Note You only need to install bundles when they are missing or when you want to update them. ## Set up a biomolecule or small molecule Use **Standard** for most single-force-field systems. 1. Open the **Standard** tab. 1. Choose a **Preset** that matches your system. 1. For Amber or CHARMM presets, choose the **Water / Ions** model when this option appears. 1. Enable **GLYCAM** or **Lipids** only when your system needs those extra parameter files. 1. Choose **Constrained** unless you specifically need an unconstrained model. 1. Wait for the status message. When the status says **Force field is ready for the current target**, press **OK** to create the interaction model. If the status reports warnings, inspect them before continuing. Warnings may still be acceptable for exploration, but they should be understood before relying on the result. ## Prepare a biomolecular target Use **Prepare** before Amber or CHARMM typing when the structure may need cleanup. The preparation guidance in the setup window focuses on common causes of typing failures: - alternate locations imported together - missing hydrogens or uncertain protonation states - incomplete peptide or nucleic-acid fragments - unsupported ligands, cofactors, crystallographic additives, or buffer molecules - waters and ions without a compatible water / ion model - accidental covalent bonds between protein, nucleic acids, ligands, waters, or ions In **Composite** mode, do not remove the ligand if it should be parameterized separately: ligand atoms must still match the `n.c lig` query. ## Set up a protein-ligand composite Use **Composite** when a biomolecular protein should use Amber or CHARMM and a ligand should use Sage or Parsley. 1. Assign the ligand atoms to the NSL class `lig`. 1. Open the **Composite** tab. 1. Choose a **Protein** preset. 1. Choose a **Ligand** force field. 1. Press **Refresh ligand query**. 1. Check that the **Ligand class** row reports the expected number of atoms for `n.c lig`. 1. Wait for the status message, then press **OK** when the setup is ready. Warning The `n.c lig` query must select only ligand atoms. If it selects no atoms, or every atom in the document, the composite setup cannot be created. Composite mode needs at least one protein atom outside the ligand selection, and it does not support covalent bonds between protein and ligand atoms. If the ligand is covalently attached, use a force field that represents the covalent chemistry directly. ## Use Advanced mode Use **Advanced** when you need direct control over force-field files or atom groups. Advanced mode has a **Groups** list. Each group has: - an **NSL** query - a **Selected files** list - file actions: **Add official...**, **Add custom...**, **Remove**, **Move up**, and **Move down** Explicit groups are evaluated in the order shown. Earlier explicit groups have priority. The default `*` group is always last and handles atoms not matched by earlier groups. To assign files manually: 1. Open the **Advanced** tab. 1. Select the group you want to edit. 1. For an explicit group, set the **NSL** query that selects the atoms in that group. 1. Press **Add official...** to choose Amber, CHARMM, or SMIRNOFF files from the local catalogs. 1. Press **Add custom...** to add local `.xml` or `.offxml` files. 1. Use **Move up** and **Move down** if file order matters. 1. Wait for the status message, then press **OK** when the setup is ready. Use **Add group** when you need a separate force field for a subset of atoms. Use **Remove** to delete an explicit group. The default `*` group cannot be removed. Warning Files within one group must come from one provider family: XML or OFFXML. To use XML for one part of the system and OFFXML for another, create separate groups. The status details may include **Group diagnostics** when an explicit group matches no atoms or when all of its atoms were already assigned by higher-priority groups. ## Add official or custom files The **Add official force-field files** dialog lets you filter by: - **Source**: AMBER, CHARMM, or SMIRNOFF - **Series** - **Category** Use **Add selected** to add the selected official files to the current group. Use **Add custom...** for local `.xml` or `.offxml` files. Custom files are useful when testing a force field that is not part of the installed bundles. ## Understand setup results The setup window checks the selected force field against the current target before creating the interaction model. **OK** is enabled only when the current setup can be used. If setup fails, the status message usually tells you what to fix. Common causes include: - missing hydrogens or incomplete terminal residues in biomolecules - alternate locations imported together - unsupported ligands or cofactors in an Amber or CHARMM-only setup - a ligand query that selects the wrong atoms in Composite mode - an Advanced group with an empty or overly broad NSL query - XML and OFFXML files selected together in a single group - a custom force-field file that uses unsupported constructs When only some atoms are problematic, the setup window may show **Exclude**. Use this only when it is scientifically appropriate to remove those atoms from the simulator target and retry the setup check. ## Run the simulation After the interaction model is created: 1. Press **Edit > Simulate > Start**. 1. Wait for the first energy and force evaluation. 1. Move atoms interactively or minimize the system with the chosen state updater. If the energy is not ready yet, wait for the first evaluation to finish and inspect the status in the properties window. ## Inspect the result Open the **Molecular Mechanics Force Fields** properties window to check what was created. Review: - **Provider** and **Parameter set** to confirm which force field was used; hover over **Parameter set** when you need the resolved source path - **Constraints** to confirm constrained or unconstrained mode - **Energy** and **Generated terms** to confirm that evaluation is active - **Details > Types** to inspect atom typing - **Details > Atoms** to inspect per-atom force-field parameters - **Details > Warnings** and **Details > Status** before interpreting the result ## Recommended workflow For practical work, use this sequence: 1. Prepare the molecular structure. 1. Choose **Standard** for single-force-field systems, **Composite** for protein-ligand systems, and **Advanced** for group-specific or custom files. 1. Use **Constrained** for routine interactive work. 1. Wait for setup validation before creating the model. 1. Read warnings before interpreting energies or forces. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). ## References - [OpenMM 7: Rapid development of high performance algorithms for molecular dynamics](https://doi.org/10.1371/journal.pcbi.1005659) - [SAMSON](https://www.samson-connect.net) # GROMACS Wizard tutorials Use these tutorials to prepare, minimize, equilibrate, simulate, and analyze molecular systems with GROMACS Wizard in SAMSON. [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5) integrates GROMACS workflows directly into SAMSON. It ships with a compatible GROMACS build, so you can start without installing GROMACS separately, and it can also use a custom local GROMACS installation when needed. ## Who this is for Use this tutorial family if you want to: - prepare molecular systems for GROMACS simulations - run energy minimization, equilibration, and production molecular dynamics - work with protein-ligand systems, periodic boundary conditions, batch computations, or cloud jobs - continue into advanced workflows such as center-of-mass pulling, umbrella sampling, and PMF analysis ## Before you start - Add the [GROMACS Wizard Extension](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5) from SAMSON Connect. - Restart SAMSON so the extension is downloaded and installed. - If you are new to molecular dynamics in SAMSON, follow the recommended path below in order. - The tutorials often use the `1AKI` structure as an example, but you can apply the same route to your own systems. ## Recommended path Follow this sequence for a standard molecular dynamics workflow: 1. [Pre-processing](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preprocess/index.md) - load and prepare the starting molecular system before GROMACS setup. 1. [Step 1: Prepare](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md) - define the model, simulation box, solvent, ions, and output files. 1. [Step 2: Energy Minimization](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md) - relax the prepared system before equilibration. 1. [Step 3: NVT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/nvt-equilibration/index.md) - equilibrate temperature at constant volume. 1. [Step 4: NPT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md) - equilibrate pressure and density. 1. [Step 5: Production Molecular Dynamics Simulation](https://documentation.samson-connect.net/tutorials/gromacs-wizard/production-md/index.md) - run the production molecular dynamics simulation and inspect results. ## Common workflows - [Periodic boundary conditions](https://documentation.samson-connect.net/tutorials/gromacs-wizard/periodic-boundary-conditions/index.md) - choose box shapes and satisfy minimum-image constraints during system preparation. - [Protein-ligand systems](https://documentation.samson-connect.net/tutorials/gromacs-wizard/protein-ligand-systems/index.md) - parametrize a ligand, combine it with a protein, and prepare the complex. - [Adding custom index groups](https://documentation.samson-connect.net/tutorials/gromacs-wizard/adding-custom-index-groups/index.md) - create custom groups for pulling, analysis, or advanced simulation setup. - [Batch computations](https://documentation.samson-connect.net/tutorials/gromacs-wizard/batch-computations/index.md) - prepare and run the same workflow across multiple systems or conformations. - [Launching computations in the Cloud](https://documentation.samson-connect.net/tutorials/gromacs-wizard/cloud/index.md) - submit, monitor, download, and import GROMACS Wizard cloud jobs. - [Using custom GROMACS version and performance parameters](https://documentation.samson-connect.net/tutorials/gromacs-wizard/settings/index.md) - configure a custom GROMACS installation and tune local performance. ## Advanced workflows - [Coarse-grained systems](https://documentation.samson-connect.net/tutorials/gromacs-wizard/coarse-grained-systems/index.md) - prepare coarse-grained systems for later minimization, equilibration, and simulation. - [COM pulling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/com-pulling/index.md) - perform center-of-mass pulling simulations. - [Umbrella Sampling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/umbrella-sampling/index.md) - generate umbrella sampling projects from trajectories, conformations, or paths. - [Potential of Mean Force analysis](https://documentation.samson-connect.net/tutorials/gromacs-wizard/pmf-analysis/index.md) - compute a PMF with weighted histogram analysis after umbrella sampling. - [Applying custom parameters](https://documentation.samson-connect.net/tutorials/gromacs-wizard/applying-custom-parameters/index.md) - apply custom parameters when the standard preparation workflow is not enough. ## What you can skip If you only need a specific task, such as cloud jobs, custom index groups, or custom performance settings, you can jump directly to that page. For simulation tasks that depend on prepared input files, complete the recommended path up to the required starting point first. ## Installing GROMACS Wizard To install GROMACS Wizard: 1. Sign in on [SAMSON Connect](https://www.samson-connect.net/). 1. Open the [GROMACS Wizard Extension page](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5). 1. Click **Add** to add the extension to your account. 1. Restart SAMSON so the extension is downloaded and installed. You can check whether GROMACS Wizard is installed in **Home > Apps > Biology**, in **Interface > Preferences > Updates > SAMSON Extensions**, or under **User > My Extensions** when you are signed in at SAMSON Connect. ## Related tutorials - [Protein preparation and validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) - prepare protein structures before simulation. - [Create molecular boxes with Molecular Box Builder](https://documentation.samson-connect.net/tutorials/molecular-box-builder/molecular-box-builder/index.md) - build molecular boxes and lipid-layer systems. - [Interactive Modeling Universal Force Field](https://documentation.samson-connect.net/tutorials/uff/im-uff/index.md) - perform interactive force-field based modeling. - [Pathlines](https://documentation.samson-connect.net/tutorials/pathlines/pathlines/index.md) - visualize motion of the center of mass of an atomic system. ## Next step Start with [Pre-processing](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preprocess/index.md) if you are following the full molecular dynamics path. # GROMACS Wizard - Adding custom index groups This section is part of the [GROMACS Wizard tutorial](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md). Use this page when the default GROMACS index groups are not enough for your workflow. Typical examples include defining pull groups, isolating a subset of residues, or preparing a later analysis step. GROMACS automatically generates standard index groups for your system based on its structure (e.g., protein, water, ions, etc.). GROMACS Wizard lets you add custom index groups using the selection tools already available in SAMSON (see [User Guide: Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md)). When dealing with a single project, you can add custom index groups at any of the following steps: preparation, equilibration, and simulation. However, when dealing with a batch project, it is preferable to add custom index groups at the preparation step - this way it will be done once for all subprojects. Note The new index groups are added using the `gmx make_ndx` command and are saved in the `index.ndx` file in the project folder. ## What you will learn In this tutorial, you will learn how to create custom index groups in GROMACS Wizard for pulling, analysis, and other advanced workflows. ## Before you start - Decide whether you need the new groups only for one prepared system or for an entire batch project. - If the group depends on default GROMACS-generated groups, add it later in the workflow after the system has already been prepared. - If your structure uses unusual residue or atom numbering, plan to verify the generated groups carefully after creation. ## Adding custom index groups at the preparation step Add custom index groups during the preparation step when you want them to be created once and reused by all later stages of the workflow. For the exact click path, see [Prepare: Adding custom index groups](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/#adding-custom-index-groups). One downside of adding index groups at the preparation step is that you cannot yet use the default index groups that will later be generated by GROMACS during the preparation. While at the next equilibration and simulation steps, you can use the default index groups since they were already generated. Warning When adding index groups at the preparation step, if your system has non-unique or non-consecutive indices for residues and atoms then in some cases there might be issues in indexing. So, it is better to verify afterward that the groups were generated as you wanted them, or, for a single project, to add these groups e.g. at the equilibration or simulation steps. ## Adding custom index groups at equilibration and simulation steps Use this route when the system has already been prepared and you want to build groups based on the index groups generated by GROMACS itself. First, the system must be loaded in SAMSON. If it is not already loaded, click **Load** next to the input path. Then, to add new index groups, click the **Edit index groups** button. This will open the GROMACS Index Groups window. You should see a list of default index groups that were generated by GROMACS. You can go through them - they are not modifiable, but you can click **Select in document based on selection string** to see the corresponding nodes. The same index groups should be available directly in your document in the folder; you can double-click on them to select the corresponding atomic structures. Let's now add a new index group. To specify new groups, you can either directly use the GROMACS selection syntax or use the extensive selection mechanisms available in SAMSON (see [User Guide: Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md)). In the latter case, the GROMACS selection string will be automatically generated for you based on your selection in SAMSON. Let's see **how to use the GROMACS selection syntax** on an example of **a selection string that uses existing index groups**. To use an existing index group, put its name into quotes, use `&` for *AND*, `|` for *OR*, and `!` for *NOT* operations. For example, the following selection string will select all non-C-alpha atoms in the protein: `*protein" & ! "C-alpha*`. You can test the selection string using **Test selection string** and select nodes in SAMSON based on it to verify it using **Select in document based on selection string**. Let's now see an example using the **selection in SAMSON**. First, [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) some nodes in your system. For the sake of the example, we will select all the neutrally charged residues using **Select > Residues > Amino acids > Side chain charge > Neutral**. Then, in the **GROMACS Index Groups** window - if it became hidden, click the **Edit index groups** button - click **+** under the list of index groups to initiate adding a new group and then click **Generate based on current selection in document**. GROMACS Wizard will automatically generate the corresponding GROMACS selection string using residue or atom selection syntax. Name the new group as you like. To register the new index group, click **Add index group to the list**. The new group will be added to the list. Click **Apply** to save the changes - they will be saved in the `index.ndx` file in the project folder. ## Related tutorials - [Step 1: Prepare](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md) for creating index groups during system preparation. - [COM Pulling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/com-pulling/index.md) for using index groups as pull coordinate groups. - [Umbrella Sampling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/umbrella-sampling/index.md) for using groups in free-energy workflows. ## Next step Return to the GROMACS Wizard step that needs the custom group, or continue with [Step 2: Energy Minimization](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md) if you are following the standard workflow. # GROMACS Wizard - Applying custom parameters This section is part of the [GROMACS Wizard tutorial](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md). Use this page when the default GROMACS Wizard settings are close to what you want, but you need to change one or more molecular dynamics parameters. For each of the [Energy Minimization](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md), [NVT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/nvt-equilibration/index.md), [NPT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md), and [Production Molecular Dynamics Simulation](https://documentation.samson-connect.net/tutorials/gromacs-wizard/production-md/index.md) steps, you can provide custom [molecular dynamics parameters](https://manual.gromacs.org/documentation/current/user-guide/mdp-options.html) (MDP) through the graphical interface or by loading an existing `.mdp` file. ## What you will learn In this tutorial, you will learn how to apply custom/advanced minimization, equilibration, and simulation parameters in GROMACS Wizard. ## Before you start - Begin from the step you actually want to run. - Keep the default settings unless you have a specific simulation reason to change them. - If you already have an `.mdp` file from a validated workflow, you can reuse it here. The tabs show the most commonly adjusted settings directly. For the full parameter editor, click **All...** (). When clicked, a window with advanced parameters will appear. As an example, you can see a window with the advanced parameters for the NVT Equilibration step in the image below. The parameters are grouped as in the [GROMACS documentation: Molecular dynamics parameters](https://manual.gromacs.org/documentation/current/user-guide/mdp-options.html). The set of available parameters is different for minimization, equilibration, and simulation steps. Tip Each parameter has a **tooltip** which you can see by hovering over the parameter. Not all [molecular dynamics parameters](https://manual.gromacs.org/documentation/current/user-guide/mdp-options.html) appear in the advanced parameter window. If a parameter is missing, add it in **Additional Parameters**. Values entered there take priority over overlapping values shown elsewhere in the interface. You can modify parameters yourself or you can also **load parameters** from an existing MDP file, e.g., from some other project. For this, click the **Load from file...** button and choose the .mdp file. Please note that the MDP file preferably should be for the same step. If the provided MDP file contains some parameters that are not present among the parameters in the advanced parameters window, then they will be automatically added to the **Additional Parameters** section where you can modify them if necessary. You can also copy and paste all the parameters present in your MDP file into the **Additional Parameters** section - they will overwrite those present in the advanced parameters window groups. You can also **export parameters to an MDP file** by clicking the **Save as…** button. To view all the parameters in a text window, click the **View as text** button. To **apply the modifications**, click the **OK** button. To **discard the modifications**, click the **Cancel** button - this will discard all the parameter modifications you have made except for resets to the default parameters. To **restore the parameters** to their default values, click on the **Reset** button. Note The modified parameters are saved when closing SAMSON, so the next time you open it, you will have the previously saved parameters. You can always find .mdp files with molecular dynamics parameters used for simulation in the simulation results folder. In addition to the comments provided, more explanations of the parameters can be found in the [GROMACS documentation: Molecular dynamics parameters](https://manual.gromacs.org/documentation/current/user-guide/mdp-options.html). ## Related tutorials - [Step 2: Energy Minimization](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md) for minimization parameters. - [Step 3: NVT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/nvt-equilibration/index.md) and [Step 4: NPT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md) for equilibration parameters. - [Step 5: Production Molecular Dynamics Simulation](https://documentation.samson-connect.net/tutorials/gromacs-wizard/production-md/index.md) for production simulation parameters. ## Next step Return to the GROMACS Wizard step where you opened the parameter editor and run the calculation with the reviewed settings. # GROMACS Wizard - Batch computations This section is part of the [GROMACS Wizard tutorial](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md). Use batch mode when you want to run the same GROMACS workflow on many starting states or many related systems without configuring each project by hand. This tutorial shows how to perform batch computations using [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5) for: - [A single molecular system with a set of initial conformations](#a-single-system-with-many-conformations). This can be useful, for example, for [Umbrella Sampling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/umbrella-sampling/index.md). - [A set of different molecular systems](#a-set-of-different-systems). This can be useful, for example, if you want to perform computations with the same parameters for a set of proteins. The resulting batch project lets you [launch the next steps (minimization, equilibration, simulation) for the whole batch](#minimize-equilibrate-and-simulate-in-batch), either locally or in the cloud. ## What you will learn In this tutorial, you will learn how to prepare and run batch computations using GROMACS Wizard. ## Before you start - Decide whether you are batching one system with many conformations or many different prepared systems. - If you need a reminder on the single-project workflow, review [Step 1: Prepare](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md) first. ## A single system with many conformations Use this route when you want to run the same workflow on several conformations of the same system. To use an existing trajectory, load it in SAMSON via **Home > File > Open** (`Ctrl`/`Cmd` + `O`) or simply drag-and-drop a trajectory into SAMSON. Creating a trajectory or conformations in SAMSON You can also create a trajectory or a set of conformations in SAMSON using various tools: - Editors: [Move editors](https://documentation.samson-connect.net/users/latest/moving-objects/index.md), [Twister](https://www.samson-connect.net/extensions/8b38b2fd-de8d-f24a-36e7-7ac624173f9f). - Various extensions: [AutoDock Vina Extended](https://www.samson-connect.net/extensions/1afc50e6-3567-fa25-1e09-415ebf4d05d7), [Normal Modes Analysis](https://www.samson-connect.net/extensions/589e13f2-183c-a8c4-3dcd-66b6b807520c), [Ligand Path Finder](https://www.samson-connect.net/extensions/280cac50-31cd-e0ad-76c3-d254cd736967), [Protein Path Finder](https://www.samson-connect.net/extensions/b6f693c9-2c71-7573-abdd-8d288a35383f), [Protein-protein docking with Hex](https://www.samson-connect.net/extensions/d53ab0d1-37bb-0fb9-0474-e090aa46af3e), [Python Scripting](https://www.samson-connect.net/extensions/7b654ce6-e38c-b97f-6746-4fd6934487c2), etc. - [Motion animations](https://documentation.samson-connect.net/users/latest/presenting/#animations) ([Assemble](https://documentation.samson-connect.net/users/latest/animations/assemble/index.md), [Dock](https://documentation.samson-connect.net/users/latest/animations/dock/index.md), [Move atoms](https://documentation.samson-connect.net/users/latest/animations/move-atoms/index.md), etc.) transformed into a path or a set of conformations. Getting conformations for specific frames of a trajectory If you want to use only some of the trajectory frames as initial conformations, then you can export conformations for specific frames using one of the two ways: - Go through the trajectory frames using the **Inspector** and create conformations via **Edit > Conformation** for your frames of choice. - Create conformations for all the frames in the trajectory - select the path in the **Document view**, right-click on it, and in the context menu click on **Path > Create conformations from path** - and then delete the unwanted conformations. ### Set up the preparation Once you have a trajectory or a set of conformations you want to use as initial frames, you are ready to go: 1. Open the **Prepare tab** in the GROMACS Wizard. 1. **Set molecular system**: [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a structural model from the **Document view** and set it as the system. Please refer to [Step 1: Prepare - Set the molecular system](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/#system). 1. Check the **[Optional] Batch preparation** box. 1. **Select initial conformations**: [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) in the **Document view** a set of conformations or a single trajectory (a path node) corresponding to the chosen system. To specify the initial conformations/states for subprojects in the batch project you have two options: - select **a set of conformations** - each conformation will act as an initial state for a subproject. - select **a path** - each frame will act as an initial state for a subproject. 1. Click the **Set conformations or a path** button. You should see the number of conformations next to it and you can use the slider to go through the conformations. 1. Follow the tutorial [Step 1: Prepare](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md): 1. **Choose the force field and solvent**. Please refer to [Step 1: Prepare - Choose the model](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/#model). 1. Optional: You can **add custom index groups** that might later be useful for analysis or during the simulation (e.g., as pull coordinate groups). Please refer to [Step 1: Prepare - Adding custom index groups](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/#adding-custom-index-groups). 1. **Specify ions**. Please refer to [Step 1: Prepare - Add ions](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/#ions). 1. **Specify the periodic box**: whether it should be based on all the conformations (option: **Box lengths**) or per conformation (option: **Solute-box distance**). Please refer to the [Define the periodic box](#define-the-periodic-box) section below. 1. Click **Prepare**. Note The prepared batch project will contain numbered subfolders each representing a fully separate project. You can [run the next steps](#minimize-equilibrate-and-simulate-in-batch) on the whole batch project or separate subfolders. ### Define the periodic box Please refer to [Step 1: Prepare - Define the periodic box](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/#box). For the batch project, the periodic box is set in one of the two ways: - **Based on all the conformations** via the **Box lengths** option. You can specify the box size. When fitted, it will fit tightly to your system – you will need to increase the size as needed to ensure the [minimum image convention](https://documentation.samson-connect.net/tutorials/gromacs-wizard/periodic-boundary-conditions/#minimum-image-convention). This option also allows you to move the box to position the system in it. For the batch project, the initial box size is determined based on all the conformations or the whole path – choose this option if you want the box size to be the same for the whole batch. - **Per conformation** via the **Solute-box distance** option. You can specify the distance between the system (solute) and the box. At least 1 nm is recommended to ensure the [minimum image convention](https://documentation.samson-connect.net/tutorials/gromacs-wizard/periodic-boundary-conditions/#minimum-image-convention). For the batch project, the box sizes will be different for each conformation or frame of the path. If you do not necessarily need to have the same box sizes for all the conformations, then you can choose the **Solute-box distance** option (set the distance to be at least 1 nm) to allow smaller boxes for more compact conformations, leading to a decrease in computational time. Tip Once you set the periodic box, you can use the slider in the **Batch preparation** box to see how the periodic box fits the conformations. ## A set of different systems You can also prepare a batch computation for different systems, for example several proteins that should all be processed with the same simulation settings: 1. [Prepare](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md) each system separately - please refer to the [Step 1: Preparation](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md). 1. Put all the resulting folders with prepared systems (they have the suffix "*-prepare*") in the same "batch" folder. You can rename the subfolders, if you wish (e.g., by PDB identifiers), or just leave them as is - the subfolder names will be preserved at the next steps. 1. In the [minimization step and other steps later](#minimize-equilibrate-and-simulate-in-batch), choose the input as **"From batch folder"** and select the "batch" folder (see the section below). Note When running batch computations on different systems, you should not use, in MD parameters, *index groups* or *position restraint (POSRES) records* specific to a particular system and not present in other systems in the same batch. Usually, these are used in some advanced options for complex systems and, for example, are not often used for just protein systems. ## Minimize, equilibrate, and simulate in batch Once the batch project has been prepared, the rest of the workflow is the same as for a single project: - [Step 2: Energy Minimization](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md) - [Step 3: NVT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/nvt-equilibration/index.md) - [Step 4: NPT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md) - [Step 5: Production Molecular Dynamics Simulation](https://documentation.samson-connect.net/tutorials/gromacs-wizard/production-md/index.md) Choose **From batch folder** as the input path (note: if you click the **auto-fill** button () it will be set automatically based on the previous run). You can launch the computations locally or in the Cloud (see [Launching computations in the Cloud](https://documentation.samson-connect.net/tutorials/gromacs-wizard/cloud/index.md)). When launching **local computations** for a batch project, they will be added as local jobs - a separate job per subfolder in the batch project - you can access them in the **Local jobs** window and see their status, change their priority (order), cancel or stop them, import them, or open their folders. When launching **Cloud computations** for a batch project, a separate Cloud job per subfolder in the batch project will be created - you can access them in the **Cloud jobs** window and see their status, cancel or stop them, download them, and import them. ## Related tutorials - [Step 1: Prepare](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md) for preparing a single system before extending the workflow to batches. - [Launching computations in the Cloud](https://documentation.samson-connect.net/tutorials/gromacs-wizard/cloud/index.md) for cloud job submission, monitoring, downloading, and importing. - [Adding custom index groups](https://documentation.samson-connect.net/tutorials/gromacs-wizard/adding-custom-index-groups/index.md) if each batch member needs analysis or pulling groups. ## Next step Continue through [Step 2: Energy Minimization](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md), [Step 3: NVT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/nvt-equilibration/index.md), [Step 4: NPT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md), and [Step 5: Production Molecular Dynamics Simulation](https://documentation.samson-connect.net/tutorials/gromacs-wizard/production-md/index.md) using **From batch folder** as the input type. # GROMACS Wizard - Computing in the Cloud This section is part of the [GROMACS Wizard tutorial](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md). Use this page when you want to run the heavier GROMACS stages on cloud hardware instead of your local machine. GROMACS Wizard allows you to launch cloud jobs for the [NVT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/nvt-equilibration/index.md), [NPT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md), and [Production Molecular Dynamics Simulation](https://documentation.samson-connect.net/tutorials/gromacs-wizard/production-md/index.md) steps. The screenshots below use the [NVT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/nvt-equilibration/index.md) step as an example, but the same job-submission pattern applies to the other supported stages. ## What you will learn In this tutorial, you will learn how to submit, monitor, and download GROMACS Wizard cloud jobs for equilibration and production simulations. ## Before you start Before going further, first read the local workflow for the stage you want to run: - [NVT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/nvt-equilibration/index.md) - [NPT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md) - [Production Molecular Dynamics Simulation](https://documentation.samson-connect.net/tutorials/gromacs-wizard/production-md/index.md) Before launching a computation in the Cloud, make sure that you have at least 1 computing credit in your [SAMSON Connect](https://www.samson-connect.net/) account. You can check the number of credits you have in two ways: 1. In SAMSON: open the **Job manager** (**Interface > Job manager** or `Ctrl`/`Cmd` + `6`) and click the **Show credits** button. 1. On [SAMSON Connect](https://www.samson-connect.net/): sign in and go to **My account** - you should see the number of credits you have on this page. If you need credits, you can always buy them on [SAMSON Connect](https://www.samson-connect.net/): [Buy computing credits](https://www.samson-connect.net/buyComputingCredits.html). ## Performing computations in the Cloud At this point, we assume that the input structure and simulation parameters are already defined. ### Check the system This step is optional but recommended. Before launching a computation in the Cloud, try to run the stage locally for a few tens or hundreds of steps to check for obvious issues. If your machine cannot run the job locally because the system is too large, click **Generate inputs** instead. This still validates part of the setup and can reveal common problems before you spend credits. ### Create the job To launch computations in the Cloud, click the **Equilibrate in the cloud / Simulate in the cloud** button for the current stage. The machine-selection dialog lets you choose: - the machine type - the storage size - the estimated cost of the machine and the storage Only machine and storage costs are charged; file transfer is free. Click the **Open details** button to see all the available machines: their characteristics and pricing. In the Performance column, you can see some hints. Click **OK** to close it. For the tutorial and for testing, we recommend selecting the machine with 4 vCPUs and no GPU. It is the slowest (but cheapest) and is suitable for testing. Select this machine as shown in the image below. Click *OK* to proceed. ### Confirm the job Once you have chosen the machine and clicked **OK**, a security dialog appears to confirm the cloud launch. This dialog summarizes the job details, including the expected pricing. In this dialog, you can also see how many computing credits remain in your account. Triggering a cloud job requires at least 1 credit to be available, but that does **not** mean that exactly 1 credit will be charged. It is only the minimum amount required to allow the job to start. In this dialog, you can also modify the job's name, description, and add some notes. Click *OK* to confirm the submission of the job to the Cloud. ### Job initialization Once you confirm the job, SAMSON will open the **Job manager** and automatically start the job initialization. During the initialization process, the job files are automatically prepared and copied to the Cloud storage. Please make sure to check the **Running** checkbox in the top part of the job manager to display all the jobs that are being initialized or running. You can sort the jobs by various columns. Note You can open the Job manager anytime you want via **Interface > Job manager** or via shortcut `Ctrl`/`Cmd` + `6`. In the **Job manager**, the jobs are listed on the left. You can access the job's details by clicking the **>>** button (to hide the part with details, click the same button again). In this part, you can see all the details on your job: creation date, current progress, description, notes, pricing. In the image above, you can see the Progress part highlighted in green. ### Start the job Once the job's initialization is finished and the job is ready to be started, a pop-up dialog will appear asking you to confirm the start. Click **Yes**. Now, in the **Job manager**, you should see that the status of the job has changed to **Starting**. After a little moment, it should change again to **Running**. In a moment, new messages should appear on the same line as the Progress indicators. Click the **Events** button to check them. This will open the **Job message history** window. In this window, you should see the estimated date and time when the job will be finished. This is a time estimated by GROMACS. Please note that this time might be updated. For the system in the tutorial, the simulation in the Cloud in the slow testing machine will take about 10 minutes. Usually, for such systems, short simulations like these are faster to perform locally, but we launch in the Cloud for the sake of the tutorial. While the computations are running in the Cloud, you can do other things in SAMSON or even close it - you will be able to access the jobs using the **Job manager** the next time you launch SAMSON. The job information is stored using the SAMSON Connect Cloud Service, and the job results will be stored in the Cloud storage. ### Pausing or canceling a job While the job is running in the Cloud, you can always **pause** it or **cancel** it. To do so, choose the job from the job list and click on the associated option in the context menu. You can **restart** a paused job at a later time. ### Completed job Once your job is completed, you will receive an email with a notification about that, as well as a new message in the **Home > News** inside SAMSON. Open the **Job manager** (**Interface > Job manager** or `Ctrl`/`Cmd` + `6`) and check your job in the job list - it should have the status **Completed**. Please make sure to check the **Non-running** checkbox in the top part of the job manager to display all the completed or canceled jobs. You can sort the jobs by various columns. You can see the cost of the job (in computing credits) in the respective column (in the image above: 0.18). In the job details, you should see that the Progress has changed to indicate that the job has finished. In the job details, click the **Events** button to check for the messages. From the messages, we can also see that the job has finished successfully. ### Download the results Now we can download the results of the computations from the Cloud. To download the job's results, open the **Job manager**, double-click on the job or click **Open result window** in the job's context menu. This will open the **Job files** window, allowing you to download the results and import them. First, choose the download folder where you would like the job results to be downloaded. You can use the **Copy** button to copy the path to the resulting folder later. You can use the **Job files** window to download results, in different ways: - Download one or more files via their context menu (choose files and click Download in the context menu). - Select files in the list and click the **Download selection** button. - Download all files by clicking the **Download all** button. We recommend downloading all the files since many of them are needed when processing the trajectory or importing results in SAMSON. Please note that the transfer of files is free. Now, click the **Download all** button. This will start the download process - you can see the download status for each file in the associated column (see the image below). The job files that were not downloaded will still be available next time you launch SAMSON - the results are stored in the Cloud storage. Once you have downloaded all results and you no longer need to keep them in the Cloud, we recommend deleting the job and its files (see below in the **Delete job** section). Once a file has been downloaded, you can access various commands in its context menu. **Show in folder** - opens the folder with the file in the default file explorer of your OS. **Open** - opens the file using the associated viewer in your OS, it is useful for opening text files (e.g. txt, log). **Import** - imports the file in SAMSON, it is applicable to all the files which can be opened in SAMSON, e.g. gro, xtc, trr, pdb. **Copy folder path** - copies the path to the folder containing the file to the clipboard. **Copy file path** - copies the path to the file to the clipboard. The latter command is useful, for example, to copy a path to the resulting GRO file to set it as the **Input structure** for the next step. ## Import results in GROMACS Wizard Once the results are downloaded, you can import them in GROMACS Wizard. In the **Job files** window, click the **Copy** button to copy the path to the folder with results. Now, in GROMACS Wizard, go to the tab associated with the job, e.g. for this *NVT Equilibration* job go to the *Equilibrate (NVT)* tab and click the associated **Import (\*) results** button. This will open a dialog where you will need to choose the folder from which you would like to import results. Paste the path you copied just before. This should immediately show the list of files that will be imported. Click *OK* to import the trajectory and create plots. Depending on the step (equilibration or production molecular dynamics simulation), there might be various pop-up dialogs asking for plotting and trajectory importing options - please see the associated [NVT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/nvt-equilibration/index.md), [NPT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md), [Production Molecular Dynamics Simulation](https://documentation.samson-connect.net/tutorials/gromacs-wizard/production-md/index.md) sections on importing results for more information. In the image below, you can see an example of a trajectory import dialog. Click **OK** if you would like to import the trajectory. This will load the trajectory as chosen by you and will generate plots depending on the step. You can apply a visual preset of your choice (**Biology > Visual preset**) or apply visual models directly. ## Delete the job Once you download results and you no longer need the job files to remain in the Cloud, you can delete the job using the **Job manager**. The job results are stored in Cloud storage and while the storage price is very low, we recommend deleting the jobs that you no longer need because the storage cost will start to be deducted from your computing credits after some time. You can see the storage cost in the job's details in the **Job manager**. To delete a job, open the **Job manager**, choose among the jobs the one that you would like to delete, right-click on it, and press **Delete** in the job's context menu. A pop-up dialog will appear asking you to confirm the action. Click *OK* if you really want to delete the job. In a moment, the job should be deleted and removed from the jobs list, but you might still be able to see the job's details on the right side of the **Job manager** - there you can see in the Progress that the job has been deleted (or is still in the process of being deleted), you can click **Details** to see more detailed information. ## Related tutorials - [Step 3: NVT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/nvt-equilibration/index.md), [Step 4: NPT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md), and [Step 5: Production Molecular Dynamics Simulation](https://documentation.samson-connect.net/tutorials/gromacs-wizard/production-md/index.md) for steps that can be run locally or in the cloud. - [Batch computations](https://documentation.samson-connect.net/tutorials/gromacs-wizard/batch-computations/index.md) for running many projects as separate local or cloud jobs. - [Using custom GROMACS version and performance parameters](https://documentation.samson-connect.net/tutorials/gromacs-wizard/settings/index.md) for local performance settings that do not apply to cloud jobs. ## Next step Import the downloaded result into SAMSON, then continue with the next GROMACS Wizard step or analyze the trajectory and plots. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # GROMACS Wizard - Coarse-grained systems This section is part of the [GROMACS Wizard tutorial](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md). Use this tutorial when you already have a coarse-grained (CG) model and want to prepare it for simulation in [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5). You will create a periodic box, solvate the system if needed, add ions, and prepare the project for minimization, equilibration, and production MD. In this tutorial, we will be using a CG system generated by the [Martinize2](https://www.samson-connect.net/extensions/0753f4e9-00ce-ae5b-eefd-d95f3e0c29bd) SAMSON Extension for the MARTINI v.3.0.0 force field, see the [Martinize2 tutorial](https://documentation.samson-connect.net/tutorials/martinize2/martinize2/index.md). Tip Before proceeding with the tutorial, we recommend that you first go through the [GROMACS Wizard - Step 1: Prepare](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md) tutorial. ## What you will learn In this tutorial, you will learn how to prepare a coarse-grained system with GROMACS Wizard. ## Before you start - Generate or obtain a valid CG model first. - If you use Martinize2, keep the generated topology and structure files together in one folder. ## Preparation step Below are the steps for preparing a CG system in GROMACS Wizard, using a soluble protein generated in the [Martinize2 tutorial](https://documentation.samson-connect.net/tutorials/martinize2/martinize2/index.md) as the example. 1. In GROMACS Wizard, go to the **Prepare** tab. 1. In the **Set system**, switch the **From** to **Folder**. 1. Choose a folder with input files: click **Browse…** and choose the folder with a CG model which contains structure and topology files (.pdb and .top). Note If you used [Martinize2](https://documentation.samson-connect.net/tutorials/martinize2/martinize2/index.md) to generate the CG model, then choose a folder with the generated output results - it should be a folder that contains the generated *\*\_CG.pdb*, *\*\_CG.top*, etc. 1. After you select the folder, you should see below the PDB, TOP, and ITP files detected in the folder. These files will be used for the system preparation in GROMACS Wizard. 1. Click the **Load** button next to the detected PDB file. This is necessary to compute the **periodic box** for the system. Once clicked, the system will be loaded into a new document and a periodic box will be computed for it as shown in the image below: 1. If the CG system was prepared by [Martinize2](https://documentation.samson-connect.net/tutorials/martinize2/martinize2/index.md), then GROMACS Wizard will automatically switch the **force field** to **martini_v.3.0.0** that it ships, and it will set the solvent model to the default Martini water. Please ensure that the force field was switched to **martini_v.3.0.0**. Note If you used another CG force field, then you will need to provide it, see [Step 1: Prepare - Using a custom force field](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/#using-a-custom-force-field). 1. If you want to **solvate** the CG system, then check the **Add solvent** options and then click on the options/gear button () next to it. In the pop-up window, **increase the default van der Waals distance** to avoid clashes and ensure proper solvent density – you need to increase it to e.g., 0.21 nm. This is necessary because GROMACS does not have van der Waals distances defined for CG models and, in this case, it will be using the default van der Waals distance value (0.105 nm), which might be too close for CG beads since each Martini water bead represents 4 water molecules. You can leave other options with their default values. Note You can also provide a custom CG solvent model, see [Step 1: Prepare - Using a custom solvent model](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/#using-a-custom-solvent-model). 1. Change the **periodic box** size if necessary. For example, you can increase the solute-box distance (note that it should be at least 1 nm to ensure the minimum distance between images) or change the unit cell type to **Rhombic dodecahedron**, the smallest and most regular space-filling unit cell. See also [Step 1: Prepare - Defining the box](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/#box) 1. **Neutralize / Add additional ions**. Choose positive and negative ions. Ions will be added to neutralize the system. If you want to add additional ions, e.g. via the salt concentration – choose the option and provide parameters. Note To neutralize the system or add ions, you need to check the option to add solvent, since ions are added by replacing solvent molecules. See also [Step 1: Prepare - Neutralizing the system](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/#ions) 1. Click **Prepare**. See also [Step 1: Prepare - Run preparation](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/#run-preparation) 1. You can choose to load the prepared structure and inspect it or proceed directly to [minimization](#minimization-equilibration-production-md). In the document, you can find a folder with the existing *index groups* created by GROMACS – you can double-click on them to select the associated atomic structures. Note SAMSON tries to detect CG systems when loading files to visualize them as connected beads. It also colorizes water in blue and ion beads with [CPK colors](https://documentation.samson-connect.net/users/latest/colorizing/#color-schemes) for their corresponding atoms. ## Minimization, Equilibration, Production MD Once you have prepared the system and verified it, switch to the **Minimize** tab and click on the **auto-fill** button () – this will set the results of the previous run as the input structure for this step. Access all the parameters by clicking on **All...** () in the *Parameters* box. In the advanced parameters window, you can also find the **position restraints** options in **Preprocessing** which are automatically filled based on your system (i.e., based on *POSRES\** defines in topology files). You can apply the position restraints for minimization and equilibration steps, in [COM Pulling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/com-pulling/index.md) or [Umbrella Sampling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/umbrella-sampling/index.md). Note If in [Martinize2](https://documentation.samson-connect.net/tutorials/martinize2/martinize2/index.md) you chose to generate position restraints based on *backbone* or *all*, then it generates separate position restraint records for each molecule (e.g., per protein chain) and places them in the corresponding topology files (.itp), numbering them from 0. So, the position restraint *POSRES_MOLECULE_0* corresponds to *molecule 0* and so on. If in Martinize2 you chose not to generate position restraints (option *none*), then there will be no position restraints. See also See more info in the tutorials dedicated to these steps: - [Step 2: Energy minimization](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md) - [Step 3: NVT equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/nvt-equilibration/index.md) - [Step 4: NPT equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md) - [Step 5: Production Molecular Dynamics Simulation](https://documentation.samson-connect.net/tutorials/gromacs-wizard/production-md/index.md) ## Related tutorials - [Martinize2](https://documentation.samson-connect.net/tutorials/martinize2/martinize2/index.md) for creating MARTINI coarse-grained models and topology files. - [Step 2: Energy Minimization](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md) for relaxing the prepared coarse-grained system. - [COM Pulling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/com-pulling/index.md) and [Umbrella Sampling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/umbrella-sampling/index.md) for advanced coarse-grained workflows. ## Next step Continue with [Step 2: Energy Minimization](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md), then equilibrate and simulate the coarse-grained system. # GROMACS Wizard - COM Pulling This section is part of the [GROMACS Wizard tutorial](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md). This tutorial shows how to perform **center-of-mass (COM) pulling** using [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5). By the end of this workflow, you should have a pulling-ready system, the relevant pulling parameters set in equilibration and production runs, and output that can later be reused for umbrella sampling. **Reference**: We will use the same system, 2BEG, as in the [Umbrella Sampling tutorial by Justin A. Lemkul](http://www.mdtutorials.com/gmx/umbrella/index.html). ## What you will learn In this tutorial, you will learn how to perform center-of-mass pulling with GROMACS Wizard. ## Before you start - Add GROMACS Wizard. - Be ready to follow the full sequence: prepare, minimize, equilibrate, and simulate. - If COM pulling is new to you, read [Periodic boundary conditions](https://documentation.samson-connect.net/tutorials/gromacs-wizard/periodic-boundary-conditions/index.md) as well, because box size matters here. ## 1. Loading the system First, load the system: - Open **Home > Fetch**. - Input `2BEG` in **PDB** or **PDB (mmCIF)**. - Click the corresponding **Load** button. Once imported, you should see in the **Document view** a *2BEG* structural model and a *2BEG* path (trajectory). The *2BEG* system contains 5 chains, and we will pull the chain `A` away while restraining the chain `B`. You can see these chains in the **Viewport** as separate secondary structures. You can reorient the system in the **Viewport** using the mouse or the *Compass* in the bottom-left corner of the *Viewport*. You can activate/deactivate the Compass using the bottom menu in the *Viewport*. Orient the system as shown in the image below. The *2BEG* system has a trajectory with multiple conformations of the system. To go through conformations, select the path node in the **Document view** and click **Inspect** in the context toolbar as shown in the image below. In the **Inspector**, you can go through the trajectory's frames using the controllers. You can use any conformation as the starting one for the tutorial. ## 2. Pre-processing Some systems require pre-processing, for example removing alternate locations or waters. For the `2BEG` example, you can skip this step. If your own system needs cleanup first, see [GROMACS Wizard - Pre-processing](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preprocess/index.md). ## 3. Preparation Open the [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5) in SAMSON - go to **Home > Apps > Biology > GROMACS Wizard** or use **Find everything...** in the top menu of SAMSON. Now set up the system for the **Prepare** step. The instructions below summarize only the settings that matter for COM pulling. For the full base workflow, see [GROMACS Wizard - Step 1: Prepare](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md). ### Specifying the model 1. Choose the force field: *AMBER03* 1. Activate the **Add solvent** option and choose the solvent model: *TIP3P*. 1. Activate the **Ignore existing hydrogens** option. ### Choosing the system Next, we need to specify the molecular system: 1. Select the *2BEG* structural model in the **Document view** and click **Set system**. 1. Leave the **Batch preparation** option non-active. ### Defining the box When setting the box for a pulling simulation, you need to **take into account the pulling by leaving enough space in the pulling direction** while taking into account the [minimum image convention](https://documentation.samson-connect.net/tutorials/gromacs-wizard/periodic-boundary-conditions/#minimum-image-convention). The pull distance must always be less than half the length of the box along the pulling direction including the periodicity. Tip If the pulling direction in your system is not aligned with axes, then you can easily orient the system in SAMSON either using [move editors](https://documentation.samson-connect.net/users/latest/moving-objects/index.md) or by right-clicking on the structure and, in the context menu, clicking on **Move selection > Align...** (choose the suitable axis or a plane). So, in this simulation, we will pull chain `A` by 5 nm from chain `B` in the z-direction. Hence, we need to set the length of the box along the z-axis to be at least twice larger than the pulling distance (i.e. at least 10 nm) and we add some additional distance (1 nm on each side) to better ensure the [minimum image convention](https://documentation.samson-connect.net/tutorials/gromacs-wizard/periodic-boundary-conditions/#minimum-image-convention) if parts of the pulled chain go above 5 nm. Thus, we set the box length in the pulling direction (z-direction) to be 12 nm. 1. Choose the **Orthorhombic** unit cell and click **Compute fitted box**. This will compute the box based on the system. 1. Choose the **Box lengths** option that allows you to set the box size and set the system size as shown below: `6.5 nm x 4.5 nm x 12 nm`. 1. Change the center of mass of the system: deactivate the **Center in box** option and set the center to `0.5 x 0.5 x 0.2` of the box size (the values change from 0 to 1). You can see the visualization of the box directly in the **Viewport**. ### Neutralizing the system We need to make sure the system is neutral (has zero charge), by adding positive or negative ions. Choose Na and Cl ions and activate the **Neutralize system** option. The simulation will be done in the presence of 100 mM NaCl, on top of neutralizing counterions. For that, activate the **Add additional ions** option, choose **Salt concentration** and set it to 0.1 mol/liter. ### Run preparation You can remove the initial structure by checking the **Remove initial structure** option. Now everything should be set to prepare the system – click the **Prepare** button to run the preparation step. Some pop-ups might appear informing you about the current steps or possible warnings/issues, if any. To view the log/output, click on the **Output** button at the top of the GROMACS Wizard: ### Results Once the preparation is finished, an import dialog will appear asking whether you want to import the prepared system into SAMSON. You can import the system to verify if everything is as you expected (box, ions, etc.). ## 4. Energy Minimization Switch to the **Minimize** tab. To learn more about the minimization step, please see: [GROMACS Wizard - Step 2: Energy Minimization](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md) To proceed from the previous step, click the **auto-fill** button () highlighted in the image below. ### Minimization parameters Open the advanced parameters window by clicking the **All...** button () in the **Parameters** box. In the **Preprocessing** section, you can see the position restraint options for chains and water - leave them unchecked. For the sake of this tutorial, leave the parameters to their default values. You can reset the parameters to the default ones by clicking on the **Reset** button at the bottom-left of the window. ### Run minimization Click on the **Minimize locally** button to launch the Energy Minimization calculations on your PC. Some pop-ups might appear informing you about the current steps or possible warnings/issues if there are any. Depending on your PC, the energy minimization of the system in the tutorial might take several seconds to about one minute. You can see the current progress in the Output window, which should pop up. In the Output window, you can check the output for the potential energy and maximum force – they should be written per step and at the very end of the output. Once the computation is done, you can skip importing the results. You can check the plot describing the evolution of the system's potential energy, Epot, over the Energy Minimization steps at the bottom of the tab in the **Plots** section. ## 5. NPT Equilibration Switch to the **Equilibrate (NPT)** tab. To learn more about the NPT equilibration step, please see: [GROMACS Wizard - Step 4: NPT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md) To proceed from the previous step, click the **auto-fill** button () highlighted in the image below. ### Equilibration parameters Set the parameters as shown in the image below: Open the advanced parameters window by clicking the **All...** button () in the **Parameters** box. You can reset the parameters to the default ones by clicking on the **Reset** button at the bottom-left of the window. In the **Preprocessing** section, you can see the position restraint (POSRES\*) options for chains and water - they are filled automatically based on the input system. Activate them for chains as shown in the image below. Set the **Temperature Coupling** parameters as shown in the image below (`T = 310 K`). In the **Velocity Generation** section, set the temperature to correspond to the temperature in the **Temperature Coupling** section. Leave the **Pressure Coupling** parameters with their default values. ### Run equilibration Click on the **Equilibrate locally** button to launch the calculations on your PC. For larger systems, you can run the equilibration in the Cloud. Some pop-ups might appear informing you about the current steps or possible warnings/issues, if any. Depending on your PC, the equilibration of the system in the tutorial might take a few minutes. You can see the current progress in the Output window, which should pop up. During these calculations, you can still use SAMSON and GROMACS Wizard thanks to the job manager of the GROMACS Wizard Extension. You can always access the list of local GROMACS jobs and their status via the **Local jobs** button. Once the computation is done, you can skip importing the results. In the **Plots** section, you can check the plots describing the evolution of the system's pressure, density, and temperature. ## 6. Production MD Switch to the **Simulate** tab. To learn more about the Production MD step, please see: [GROMACS Wizard - Step 5: Production Molecular Dynamics Simulation](https://documentation.samson-connect.net/tutorials/gromacs-wizard/production-md/index.md) To proceed from the previous step, click the **auto-fill** button () highlighted in the image below. ### Add index groups for pulling If the groups you would like to pull are not present among the default index groups generated by GROMACS, then you need to add them. To see the available index groups and to add custom index groups, click the **Edit index groups** button. This will open a window with a list of available default index groups generated by GROMACS. Such groups include, for example, Protein, Water, Ions, etc. You can also add new index groups using this window. To learn how to add new index groups please refer to: [GROMACS Wizard - Adding custom index groups](https://documentation.samson-connect.net/tutorials/gromacs-wizard/adding-custom-index-groups/index.md) Important To add new index groups, it is necessary to load the system in SAMSON - use the **Load** button in the **Input** section to import the structure. This will facilitate the creation of index groups based on the selections in SAMSON. For this tutorial, we need to add 2 new index groups: chain `A` and chain `B` - since we will be pulling chain `A` from chain `B`. Let's add the first group with chain `A`: 1. Select chain `A` in the Document view. 1. In the **Index Groups** window (open the window again if it becomes hidden), click **Generate based on current selection in document**. This will generate a selection string for you. 1. Set the name to "ChainA". 1. Click **Add index group to the list**. Let's now add the second group with chain `B`. 1. Select chain `B` in the Document view. 1. In the **Index Groups** window (open the window again if it becomes hidden), click **Generate based on current selection in document**. This will generate a selection string for you. 1. Set the name to "ChainB". 1. Click **Add index group to the list**. You should now see two groups in the list of custom groups. You can check index groups - select one from the list and click **Select in document based on selection string**. ### Production MD parameters Set the parameters as shown in the image below - we will simulate for 0.5 ns with the 2 fs timestep. Open the advanced parameters window by clicking the **All...** button () in the **Parameters** box. You can reset the parameters to the default ones by clicking on the **Reset** button at the bottom-left of the window. In the **Preprocessing** section, you can see the position restraint (`POSRES*`) options for chains and water - they are filled automatically based on the input system. Activate position restraint for chain `B` such that it stays in place when chain `A` is pulled away. Set temperature and pressure coupling parameters as in the NPT equilibration step. You can set the output control parameters as in the image below. Now we need to specify the COM pulling parameters to do the pulling! Switch to the **COM pulling** section and click the plus button highlighted in the image below to add a new COM pulling group. We will pull chain `A` from chain `B` in the z-direction for 5 nm in 0.5 ns. Populate the COM pulling parameters as follows: - type: umbrella - geometry: distance - group 1: chain A - group 2: chain B - start: yes - distance: N N Y (i.e. pulling in the z-direction) - init: 0 nm - rate: 0.01 nm/ps (i.e. 5 nm in 0.5 ns) - force constant: 1000 kJ mol^-1 nm^-2 Click **OK** to save the parameters. ### Run production MD You can simulate locally or in the Cloud. Click the **Simulate locally** button to launch the calculations on your PC. Some pop-ups might appear informing you about the current steps or possible warnings/issues, if any. Depending on your PC, the simulation of the system in the tutorial might take some time - on a machine with 32 cores it took about 12 minutes. You can see the current progress in the Output window, which should pop up. During these calculations, you can still use SAMSON and GROMACS Wizard thanks to the job manager of the GROMACS Wizard Extension. You can always access the list of local GROMACS jobs and their status via the **Local jobs** button. If you have only a single project launched, then once it is finished, you will be asked whether you want to import it. You can load the resulting trajectory in SAMSON to visualize the pulling. Two additional plots will be generated showing the pull force and coordinates. From these plots, you can see the displacement along the pull coordinate over time - the force builds up until it is sufficient to overcome internal restoring forces between chains. You can use the results for [Umbrella Sampling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/umbrella-sampling/index.md). ## Related tutorials - [Adding custom index groups](https://documentation.samson-connect.net/tutorials/gromacs-wizard/adding-custom-index-groups/index.md) for defining pull groups. - [Umbrella Sampling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/umbrella-sampling/index.md) for using pulling results to generate umbrella windows. - [Potential of Mean Force analysis](https://documentation.samson-connect.net/tutorials/gromacs-wizard/pmf-analysis/index.md) for analyzing umbrella sampling results. ## Next step Continue with [Umbrella Sampling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/umbrella-sampling/index.md) if you want to compute a free-energy profile from the pulling workflow. # GROMACS Wizard - Step 2: Energy Minimization This section is part of the [GROMACS Wizard tutorial](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md). Once a system or batch project has been successfully [prepared](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md), run **Energy Minimization (EM)** to relax steric clashes and poor local geometry before equilibration. ## What you will learn In this tutorial, you will learn how to perform energy minimization with GROMACS Wizard. ## Before you start - Complete [Step 1: Prepare](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md). - Keep the prepared project folder available. - If you are working on many conformations at once, you can use the same workflow with a batch project. ## What success looks like At the end of this step, you should have: - a minimized structure or minimized batch project - an energy plot showing convergence - output values that let you check whether the minimization was good enough to continue ## Start here Switch to the **Minimize** tab. ## Selecting input structure When launching the *Energy Minimization* step, GROMACS Wizard requires one of the following inputs: - **The path to a GRO file** resulting from the previous step: either a GRO file resulting from the [Preparation step](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md) or the previous launch of the *Energy Minimization step*. - **The path to a batch project** that has been [prepared](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md) or resulted from one of the other steps. Please refer to the [Batch computations](https://documentation.samson-connect.net/tutorials/gromacs-wizard/batch-computations/#minimize-equilibrate-and-simulate-in-batch) tutorial. If you want to proceed from the previous step, you can simply click on the **auto-fill** button () highlighted in the image below. This will automatically fill the path based on the previous project, whether a GRO file or a batch project from the previous successful run (e.g. from the [Preparation step](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md)). You can also choose the input GRO file yourself by clicking on the **...** button. ## Choosing parameters [GROMACS molecular dynamics parameters](https://manual.gromacs.org/documentation/current/user-guide/mdp-options.html) for energy minimization are present in the **Parameters** section of the **Minimize** tab. By default, these parameters are populated with default values that are suitable for typical energy minimization runs. You can modify these parameters as needed. In the **Parameters** section, you will find the parameters that are most likely to be changed often, like the energy minimization tolerance. The other GROMACS molecular dynamics parameters can be accessed by clicking on the **All...** button () highlighted in the image above. To learn more about how to apply custom parameters, please check the [Applying custom parameters](https://documentation.samson-connect.net/tutorials/gromacs-wizard/applying-custom-parameters/index.md) section. For this tutorial, leave the parameters at their default values. Tip To **restore the parameters** to their default values, click on the **Reset** button in the *Advanced parameters window*. To **load the parameters from an MDP file** from some other project, click the **Load from file...** button. To **save the parameters in an MDP file**, click the **Save as...** button. Note The modified parameters are saved when closing SAMSON, so the next time you open it, you will have the previously saved parameters. ## Run energy minimization GROMACS Wizard gives you several possibilities: - **Generate inputs** - generates a ready-to-use project that you can, for example, run on your local cluster. - **Minimize locally** - launches the computations locally on your PC using the shipped GROMACS or the version you specified in the settings (see [Using custom GROMACS version and performance parameters](https://documentation.samson-connect.net/tutorials/gromacs-wizard/settings/index.md)). - **Minimize in the cloud** - launches the computations in the cloud. This is suitable for minimizing big systems that would otherwise require too many resources to minimize locally. This will prompt you to select the Cloud machine, etc. Note that launching in the Cloud requires computing credits. See [Launching Computations in the Cloud](https://documentation.samson-connect.net/tutorials/gromacs-wizard/cloud/index.md) for more information. Click **Minimize locally** to launch the Energy Minimization job on your PC. Some pop-ups may appear to report progress, warnings, or input issues. Depending on your PC, the energy minimization of the system in the tutorial might take several seconds to about one minute. You can see the current progress in the Output window, which should pop up. During these calculations, you can still use SAMSON and GROMACS Wizard thanks to the GROMACS Wizard Extension job manager. You can always access the list of local GROMACS jobs and their status via the **Local jobs** button. ### Importing the results If you launched a single project and there are no other projects in the local job queue, then after the computations are done, a pop-up will appear asking for import options. If you launched multiple jobs or a batch job, then you can check their state in **Local jobs**. You can choose whether to import the whole trajectory, only the last frame, or some range of frames, and what type of Periodic Boundary Condition treatment to apply, and on what to center the system. For example, as shown in the image below, you can choose to import only the last frame and to center the system on the Protein. If you do not want to import the trajectory, you can simply click **Cancel** - this will not delete any results and will still generate the plot. You can access the results in the *results folder* specified at the top of the GROMACS Wizard. The folders with results are named with the launch date and time, and the step description (for the Energy Minimization step, the folder suffix is `_em`). ### Plots You can check the plot describing the evolution of the system's potential energy, `Epot`, over the Energy Minimization steps at the bottom of the tab in the **Plots** section. In this example, this plot demonstrates a nice, steady convergence of the potential energy. The plots are automatically generated and saved when the job is finished and the results are loaded. This plot is also generated for each subproject in a batch automatically. If you would like to save the plot, click on the **Save** button () at the top of the figure. ### Checking results There are two main things to check before moving on: - **Potential energy** - `Epot`, which should be negative, and (for a simple protein in water) on the order of 105-106, depending on the system size and number of water molecules. - **Maximum force** - `Fmax`, the target for which is set in the advanced parameters of the Energy Minimization step (see the description below). For example, `emtol = 1000.0` indicates a target `Fmax` of no greater than 1000 kJ mol^-1 nm^-1. Please see the tooltips in the advanced parameters. Please check the output for the potential energy and maximum force - they should be written per step and at the end of the output. You can check them in the Output window. It is possible that Energy Minimization may reach the given maximum number of minimization steps and arrive at a reasonable `Epot` but with `Fmax > emtol`. If this happens, your system may not be stable enough for further equilibration and simulation. You might need to evaluate why it is happening and, for example, increase the number of minimization steps (or run minimization again by providing the input data from the previous minimization step), decrease the minimization step size, or change the minimization parameters (*integrator*, etc.). ## Related tutorials - [Applying custom parameters](https://documentation.samson-connect.net/tutorials/gromacs-wizard/applying-custom-parameters/index.md) if you need to adjust minimization parameters. - [Batch computations](https://documentation.samson-connect.net/tutorials/gromacs-wizard/batch-computations/index.md) if you need to minimize many prepared systems or conformations. ## Next step Continue with [Step 3: NVT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/nvt-equilibration/index.md) once the potential energy and maximum force are acceptable for your system. # GROMACS Wizard - Step 4: NPT Equilibration This section is part of the [GROMACS Wizard tutorial](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md). Once the system has been [minimized](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md) and its temperature has stabilized during [NVT equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/nvt-equilibration/index.md), the next goal is to stabilize the density. This second equilibration phase uses the *NPT ensemble* (constant Number of particles, Pressure, and Temperature). ## What you will learn In this tutorial, you will learn how to perform NPT Equilibration with GROMACS Wizard. ## Before you start - Complete [NVT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/nvt-equilibration/index.md). - Reuse the same temperature-coupling choices unless you have a clear reason to change them. ## What success looks like At the end of this step, the system density should have reached a stable regime and the project should be ready for production MD. ## Start here Switch to the **Equilibrate (NPT)** tab. ## Selecting input structure When launching the *NPT Equilibration* step, GROMACS Wizard requires one of the following inputs: - **The path to a GRO file** resulting from the previous step: either a GRO file resulting from the [Minimization step](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md), [NVT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/nvt-equilibration/index.md) step, or the previous launch of an equilibration step. - **The path to a batch project** that has been [minimized](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md) and/or [equilibrated using the NVT ensemble](https://documentation.samson-connect.net/tutorials/gromacs-wizard/nvt-equilibration/index.md) or resulted from one of the other steps. Please refer to the [Batch computations](https://documentation.samson-connect.net/tutorials/gromacs-wizard/batch-computations/#minimize-equilibrate-and-simulate-in-batch) tutorial. If you want to proceed from the previous step, you can simply click on the **auto-fill** button () highlighted in the image below. This will automatically fill the path based on the previous project, whether a GRO file or a batch project from the previous successful run (e.g. from the [NVT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/nvt-equilibration/index.md)). You can also choose the input GRO file yourself by clicking on the **...** button. ## Choosing parameters [GROMACS molecular dynamics parameters](https://manual.gromacs.org/documentation/current/user-guide/mdp-options.html) for NPT equilibration are present in the **Parameters** section of the **NPT Equilibration** tab. By default, these parameters are populated with default values that are suitable for typical NPT equilibration runs. You can modify these parameters as needed. In the **Parameters** section, you will find the parameters that are most likely to be changed often, like the integration time step and the number of steps. The timeframe for such a procedure depends on the size and contents of the system, but in NPT, the running average of the density of the system should reach a plateau at the desired value. Typically, 100 ps should be a good start. Please note that pressure is a quantity that might fluctuate widely throughout equilibration or simulation. If the density has not yet stabilized (i.e., the pressure-related terms are slow to converge) in the given timeframe, additional time will be required - you can simply run the NPT equilibration step again by providing the input data from the previous NPT equilibration step. The other GROMACS molecular dynamics parameters can be accessed by clicking on the **All...** button () highlighted in the image above. To learn more about how to apply custom parameters, please check the [Applying custom parameters](https://documentation.samson-connect.net/tutorials/gromacs-wizard/applying-custom-parameters/index.md) section. Note The **position restraint (POSRES\*)** options are filled automatically based on the input system. In the **Pressure coupling** section, you can modify the corresponding parameters, e.g., barostat, time constant, and the reference pressure. For most projects, you can use the exponential relaxation pressure coupling with a time constant that includes a stochastic term (c-rescale) and the time constant of about 5 ps, as shown in the image below. Important Please ensure that the **temperature coupling** parameters correspond to the ones from the NVT equilibration, and the temperature in the velocity generation (if it is on) as well. For this tutorial, reset the parameters to their default values. Tip To **restore the parameters** to their default values, click on the **Reset** button in the *Advanced parameters window*. To **load the parameters from an MDP file** from some other project, click the **Load from file...** button. To **save the parameters in an MDP file**, click the **Save as...** button. Note The modified parameters are saved when closing SAMSON, so the next time you open it, you will have the previously saved parameters. ## Run NPT Equilibration GROMACS Wizard gives you several possibilities: - **Generate inputs** - generates a ready-to-use project that you can, for example, run on your local cluster. - **Equilibrate locally** - launches the computations locally on your PC using the shipped GROMACS or the version you specified in the settings (see [Using custom GROMACS version and performance parameters](https://documentation.samson-connect.net/tutorials/gromacs-wizard/settings/index.md)). - **Equilibrate in the cloud** - launches the computations in the cloud. This is suitable for big systems that would otherwise require too many resources to do it locally. This will prompt you to select the Cloud machine, etc. Note that launching in the Cloud requires computing credits. See [Launching Computations in the Cloud](https://documentation.samson-connect.net/tutorials/gromacs-wizard/cloud/index.md) for more information. Click **Equilibrate locally** to launch the job on your PC. Some pop-ups may appear to report progress, warnings, or input issues. Depending on your PC, the equilibration of the system in the tutorial might take a few minutes. You can see the current progress in the Output window, which should pop up. During these calculations, you can still use SAMSON and GROMACS Wizard thanks to the GROMACS Wizard Extension job manager. You can always access the list of local GROMACS jobs and their status via the **Local jobs** button. ### Importing the results If you launched a single project and there are no other projects in the local job queue, then after the computations are done, a pop-up will appear asking for import options. If you launched multiple jobs or a batch job, then you can check their state in **Local jobs**. You can choose whether to import the whole trajectory, only the last frame, or some range of frames, and what type of Periodic Boundary Condition treatment to apply, and on what to center the system. For example, as shown in the image below, you can choose to center the system on the Protein. If you do not want to import the trajectory, you can simply click **Cancel** - this will not delete any results and will still generate the plot. You can access the results in the *results folder* specified at the top of the GROMACS Wizard. The folders with results are named with the launch date and time, and the step description (for the NPT Equilibration step, the folder suffix is `_npt`). ### Plots You can check the plots describing the evolution of the system's pressure and density over simulation time at the bottom of the tab in the **Plots** section. In this example, this plot shows that the density has stabilized at 1030 kg/m3, which is close to the experimental value of 1000 kg/m3, and the expected density of the SPC/E model is about 1008 kg/m3. We can see that the density values are stable over time, indicating that the system is now well equilibrated with respect to pressure and density. The plots are automatically generated and saved when the job is finished and the results are loaded. If you would like to save the plot, click on the **Save** button () at the top of the figure. ### Checking results Check whether the system has reached the desired density and whether that density looks stable enough to continue. Density may fluctuate around the target value. If it has not stabilized yet, run additional NPT equilibration starting from the current NPT results. Once the system's density has stabilized at the desired value, we will proceed to the actual simulation. ## Related tutorials - [Applying custom parameters](https://documentation.samson-connect.net/tutorials/gromacs-wizard/applying-custom-parameters/index.md) if you need to change barostat or equilibration parameters. - [Launching computations in the Cloud](https://documentation.samson-connect.net/tutorials/gromacs-wizard/cloud/index.md) if you want to run NPT equilibration as a cloud job. ## Next step Continue with [Step 5: Production Molecular Dynamics Simulation](https://documentation.samson-connect.net/tutorials/gromacs-wizard/production-md/index.md) once the density is stable enough for your system. # GROMACS Wizard - Step 3: NVT Equilibration This section is part of the [GROMACS Wizard tutorial](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md). Once the system has been successfully [minimized](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md), the next goal is to bring it to the target temperature in a controlled way. Equilibration is often performed in two phases. In this first phase, you run an *NVT ensemble* simulation (constant Number of particles, Volume, and Temperature) to stabilize the temperature. After the system reaches the desired temperature, continue with [NPT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md) to stabilize the density. ## What you will learn In this tutorial, you will learn how to perform NVT Equilibration with GROMACS Wizard. ## Before you start - Complete [Energy Minimization](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md). - Make sure the minimized system looks reasonable and the minimization output does not show unresolved problems. ## What success looks like At the end of this step, the system temperature should fluctuate around the target value and the temperature plot should look stable enough to continue. ## Start here Switch to the **Equilibrate (NVT)** tab. ## Selecting input structure When launching the *NVT Equilibration* step, GROMACS Wizard requires one of the following inputs: - **The path to a GRO file** resulting from the previous step: either a GRO file resulting from the [Minimization step](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md) or the previous launch of an equilibration step. - **The path to a batch project** that has been [minimized](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md) or resulted from one of the other steps. Please refer to the [Batch computations](https://documentation.samson-connect.net/tutorials/gromacs-wizard/batch-computations/#minimize-equilibrate-and-simulate-in-batch) tutorial. If you want to proceed from the previous step, you can simply click on the **auto-fill** button () highlighted in the image below. This will automatically fill the path based on the previous project, whether a GRO file or a batch project from the previous successful run (e.g. from the [Minimization step](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md)). You can also choose the input GRO file yourself by clicking on the **...** button. ## Choosing parameters [GROMACS molecular dynamics parameters](https://manual.gromacs.org/documentation/current/user-guide/mdp-options.html) for NVT equilibration are present in the **Parameters** section of the **NVT Equilibration** tab. By default, these parameters are populated with default values that are suitable for typical NVT equilibration runs. You can modify these parameters as needed. In the **Parameters** section, you will find the parameters that are most likely to be changed often, like the integration time step and the number of steps. The timeframe for such a procedure depends on the size and contents of the system, but in NVT, the running average of the temperature of the system should reach a plateau at the desired value. Typically, 50-100 ps should be sufficient. If the desired temperature has not been achieved or has not yet stabilized, additional time will be required - you can simply run the NVT equilibration step again by providing the input data from the previous NVT equilibration step. The other GROMACS molecular dynamics parameters can be accessed by clicking on the **All...** button () highlighted in the image above. To learn more about how to apply custom parameters, please check the [Applying custom parameters](https://documentation.samson-connect.net/tutorials/gromacs-wizard/applying-custom-parameters/index.md) section. Note The **position restraint (POSRES\*)** options are filled automatically based on the input system. In the **Temperature coupling** section, you can modify the corresponding parameters, such as the thermostat, systems to couple, time constant, and the reference temperature. For most projects, you can use temperature coupling using velocity rescaling with a stochastic term, v-rescale, and the time constant of about 1 ps, as shown in the image below. Please note that the temperature for the velocity generation (specified in the **Velocity generation** section) should correspond to the coupling temperature. You can specify the groups to couple other than the `System`, for example, `Protein non-Protein`. For that, click on the **+** button () next to the groups to couple - a pop-up dialog will appear from which you can select index groups available in your system. Please note that the number of time constants and reference temperatures should correspond to the number of groups as shown, for example, in the image below. Note You can **add custom index groups** directly from the **NVT Equilibration** tab by first loading the system (click the **Load** button next to the chosen input GRO file) and then clicking the **Edit index groups** button in the **Parameters** section. See [Adding custom index groups](https://documentation.samson-connect.net/tutorials/gromacs-wizard/adding-custom-index-groups/index.md) for more information. You can reset to the default `System` coupling by clicking on the reset button. For this tutorial, reset the parameters to their default values. Tip To **restore the parameters** to their default values, click on the **Reset** button in the *Advanced parameters window*. To **load the parameters from an MDP file** from some other project, click the **Load from file...** button. To **save the parameters in an MDP file**, click the **Save as...** button. Note The modified parameters are saved when closing SAMSON, so the next time you open it, you will have the previously saved parameters. ## Run NVT Equilibration GROMACS Wizard gives you several possibilities: - **Generate inputs** - generates a ready-to-use project that you can, for example, run on your local cluster. - **Equilibrate locally** - launches the computations locally on your PC using the shipped GROMACS or the version you specified in the settings (see [Using custom GROMACS version and performance parameters](https://documentation.samson-connect.net/tutorials/gromacs-wizard/settings/index.md)). - **Equilibrate in the cloud** - launches the computations in the cloud. This is suitable for big systems that would otherwise require too many resources to do it locally. This will prompt you to select the Cloud machine, etc. Note that launching in the Cloud requires computing credits. See [Launching Computations in the Cloud](https://documentation.samson-connect.net/tutorials/gromacs-wizard/cloud/index.md) for more information. Click **Equilibrate locally** to launch the job on your PC. Some pop-ups may appear to report progress, warnings, or input issues. Depending on your PC, the equilibration of the system in the tutorial might take a few minutes. You can see the current progress in the Output window, which should pop up. During these calculations, you can still use SAMSON and GROMACS Wizard thanks to the GROMACS Wizard Extension job manager. You can always access the list of local GROMACS jobs and their status via the **Local jobs** button. ### Importing the results If you launched a single project and there are no other projects in the local job queue, then after the computations are done, a pop-up will appear asking for import options. If you launched multiple jobs or a batch job, then you can check their state in **Local jobs**. You can choose whether to import the whole trajectory, only the last frame, or some range of frames, and what type of Periodic Boundary Condition treatment to apply, and on what to center the system. For example, as shown in the image below, you can choose to center the system on the Protein. If you do not want to import the trajectory, you can simply click **Cancel** - this will not delete any results and will still generate the plot. You can access the results in the *results folder* specified at the top of the GROMACS Wizard. The folders with results are named with the launch date and time, and the step description (for the NVT Equilibration step, the folder suffix is `_nvt`). ### Plots You can check the plot describing the evolution of the system's temperature over simulation time at the bottom of the tab in the **Plots** section. In this example, this plot shows that the temperature has stabilized around 300 K as set by default in the advanced parameters. The plots are automatically generated and saved when the job is finished and the results are loaded. If you would like to save the plot, click on the **Save** button () at the top of the figure. ### Checking results Check that the system has reached the desired temperature and that the running behavior looks stable enough to continue. Small fluctuations around the target value are normal. If the temperature has not yet stabilized, run additional NVT equilibration starting from the current NVT results. Once the system's temperature has stabilized at the desired value, we will apply the [NPT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md) step for the system to reach the desired density. ## Related tutorials - [Applying custom parameters](https://documentation.samson-connect.net/tutorials/gromacs-wizard/applying-custom-parameters/index.md) if you need to change thermostat or equilibration parameters. - [Launching computations in the Cloud](https://documentation.samson-connect.net/tutorials/gromacs-wizard/cloud/index.md) if you want to run equilibration as a cloud job. ## Next step Continue with [Step 4: NPT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md) after the temperature is stable enough for your workflow. # GROMACS Wizard - Periodic boundary conditions This page explains the box shapes available in GROMACS Wizard and the minimum-image rule you need to keep in mind when choosing box dimensions. Use it together with [Step 1: Prepare](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md) when you are deciding how to build the simulation box. ## What you will learn In this tutorial, you will learn how to choose box shapes and satisfy minimum-image constraints when preparing systems in GROMACS Wizard. ## Before you start - Read this page alongside [Step 1: Prepare](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md), because box-shape choices matter while you are setting up the system. - Focus first on two decisions: which unit-cell shape best fits your solute, and whether the box leaves enough distance to satisfy the minimum image convention. - If you are preparing a spherical solute in solvent, pay special attention to the rhombic dodecahedron and truncated octahedron examples below. ## Unit cells > "GROMACS uses periodic boundary conditions, combined with the minimum image convention: only one – the nearest – image of each particle is considered for short-range non-bonded interaction terms. For long-range electrostatic interactions, this is not always accurate enough, and GROMACS therefore also incorporates lattice sum methods such as Ewald Sum, PME and PPPM." ([GROMACS Manual: Periodic boundary conditions](https://manual.gromacs.org/documentation/current/reference-manual/algorithms/periodic-boundary-conditions.html)) [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5) supports the following shapes for space-filling unit cells: | Unit cell shape | Representation | | -------------------- | -------------- | | Cubic | | | Orthorhombic | | | Triclinic | | | Rhombic dodecahedron | | | Truncated octahedron | | You choose the unit cell shape and its size when [preparing a system](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md): The **rhombic dodecahedron** and the **truncated octahedron** are closer to being a sphere than a cube is, and are therefore better suited to the study of an approximately spherical macromolecule in solution since fewer solvent molecules are required to fill the box given a minimum distance between macromolecular images. The rhombic dodecahedron is the smallest and most regular space-filling unit cell. The volume is 71% of the volume of a cube having the same image distance. This saves about 29% of CPU time when simulating a spherical or flexible molecule in a solvent. Two options for initial fitting of the box based on the system are available: - **Box lengths** – specify the box size. When fitted, it will fit tightly to your system – you will need to increase the size as needed to ensure the [minimum image convention](#minimum-image-convention). This option also allows you to move the box to position the system in it. For the batch project, the initial box size is determined based on all the conformations or the whole path – choose this option if you want the box size to be the same for the whole batch. - **Solute-box distance** – specify the distance between the system (solute) and the box. At least 1 nm is recommended to ensure the [minimum image convention](#minimum-image-convention). For the batch project, the box sizes will be different for each conformation or frame of the path. Note GROMACS always keeps the particles in a brick-shaped volume for efficiency. When loading GROMACS results, SAMSON will try to automatically detect the type of the unit cell of the system, but you can always modify it in the importer dialog that appears when loading GROMACS trajectories. Please refer to [GROMACS Manual: Periodic boundary conditions](https://manual.gromacs.org/documentation/current/reference-manual/algorithms/periodic-boundary-conditions.html) for more information on periodic boundary conditions and unit cell shapes. ## Minimum image convention When periodic boundary conditions are used, it is crucial to satisfy the **minimum image convention**. In practice, your solute should never interact with its own periodic image; otherwise the forces may be wrong. A practical rule of thumb is to leave at least `1.0 nm` between the solute and the box boundary, which creates at least `2.0 nm` between periodic images of the solute. Please refer to [GROMACS Manual: Cut-off restrictions](https://manual.gromacs.org/documentation/current/reference-manual/algorithms/periodic-boundary-conditions.html#cut-off-restrictions) for more information. ## Related tutorials - [Step 1: Prepare](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md) for applying box settings during system preparation. - [Protein-ligand systems](https://documentation.samson-connect.net/tutorials/gromacs-wizard/protein-ligand-systems/index.md) for preparing complexes that need a simulation box. ## Next step Return to [Step 1: Prepare](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/#box) and define a box that leaves enough distance between the solute and its periodic images. # GROMACS Wizard - PMF Analysis This section is part of the [GROMACS Wizard tutorial](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md). Use this page after an umbrella-sampling workflow when you want to convert the windowed simulation data into a **Potential of Mean Force** (PMF) profile. In GROMACS Wizard, PMF analysis is performed with the **Weighted Histogram Analysis Method** (WHAM). ## What you will learn In this tutorial, you will learn how to compute the Potential of Mean Force using the Weighted Histogram Analysis Method with GROMACS Wizard. ## Before you start - Finish an [Umbrella Sampling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/umbrella-sampling/index.md) workflow first. - Make sure the input folder contains matching subprojects for the same system and reaction-coordinate setup. ## Compute the PMF Switch to the **WHAM Analysis** tab in [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5). 1. Choose the project path, or click **auto-fill** () if the previous project you ran was the [Umbrella Sampling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/umbrella-sampling/index.md) simulation. 1. Confirm that the project folder contains numbered subfolders for the same system and the same reaction-coordinate definition. GROMACS Wizard loads the reaction-coordinate information, time range, and temperature from the project automatically. 3. Choose the reaction coordinate from the list. 1. Adjust optional settings such as custom bounds, custom time range, or energy units if needed. 1. Click **Compute**. GROMACS Wizard then generates two plots: - the PMF profile - the histogram showing how well the coordinate space is covered For large trajectories, the computation may take several seconds or minutes. ## Interpreting the result The histogram shows how well the reaction-coordinate space is covered and helps you spot regions where additional sampling may be needed. Once the computation is finished, GROMACS Wizard saves the profiles, histograms, and plots in the `wham_results` subfolder of the project. If you switch between reaction coordinates later, the tool reuses the already computed data for the same parameters. ## Related tutorials - [Umbrella Sampling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/umbrella-sampling/index.md) for generating the umbrella sampling data used by PMF analysis. - [COM Pulling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/com-pulling/index.md) for preparing pulling trajectories that can seed umbrella sampling windows. ## Next step Inspect the PMF profile and histogram coverage. If sampling is insufficient in some regions, return to [Umbrella Sampling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/umbrella-sampling/index.md) and add or extend simulations for those windows. # GROMACS Wizard - Step 1: Prepare This section is part of the [GROMACS Wizard tutorial](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md). Once the system has been [pre-processed](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preprocess/index.md) and checked, the next step is to build a simulation-ready project. In this tutorial, you will choose the system, select the force field and solvent model, define the periodic box, and prepare the solvated or ionized system that later steps will use. ## What you will learn In this tutorial, you will learn how to prepare a system for simulations with GROMACS Wizard. ## Before you start - Complete the [Pre-processing](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preprocess/index.md) step first. - Keep your topology files ready if your system contains ligands or other non-standard molecules. - Decide whether you are preparing a single system or a batch project based on multiple conformations. ## What you will do To launch GROMACS simulations, first prepare the system: 1. [Choose the molecular system](#system) and, optionally, [choose a set of conformations or a path for a batch project](#batch-preparation). 1. [Specify the model](#model): [force field](#choosing-the-force-field) and [solvent](#choosing-solvent). 1. [Define the periodic box](#box). 1. [Choose what and how many ions should be added](#ions). 1. [Run preparation](#run-preparation) During the preparation step, GROMACS Wizard will generate a model, and add solvent and ions if necessary. The **Prepare** step allows you to prepare either: - a **single model**; - a **batch project** for the same molecular structure based on a set of conformations or a trajectory that might be useful, e.g., for [Umbrella Sampling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/umbrella-sampling/index.md). Below, we first show the single-project workflow. If you need many conformations or many related systems, you can branch into [Batch preparation](#batch-preparation). Note To learn how to prepare a coarse-grained model, please refer to the [Coarse-grained systems](https://documentation.samson-connect.net/tutorials/gromacs-wizard/coarse-grained-systems/index.md) tutorial. ## Choosing the results folder Start by choosing the folder where GROMACS Wizard should save the generated project and later results. Click the **...** button to choose that folder. The **Open** button allows you to open this folder in your default file explorer. ## 1. Choosing the system Now specify the molecular system that you want to prepare: 1. In **From**, choose **Document**. 1. Select the system in the **Document view**. If there are several structural models in the active document, then [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) in the Document view the ones that you would like to prepare. If the active document contains only the system you would like to prepare, then there is no need to select it - it will be selected automatically. 1. Click the **Set system** button. If the selection was left empty and there are several structural models in the active document, it will ask you to choose whether you want to include all the structural models when preparing the system. Once you set the system, it should look like this: ### Adding custom index groups This is an **optional step**. GROMACS will automatically generate standard index groups for your system based on its structure (e.g., protein, solvent, ions, etc.). However, you can **add custom index groups** that might later be useful for analysis or during the simulation (e.g., as pull coordinate groups). This allows you to use the extensive selection mechanisms available in SAMSON (see [User Guide: Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md)). **Requirement**: This step requires that the system has unique and consecutive indices for residues and atoms. Note The new index groups are added using the `gmx make_ndx` command and are saved in the `index.ndx` file in the project folder. Note You can add new index groups in the next steps (minimization, equilibration, simulation). To add a custom index group, click the **Add/edit index groups** button. This will open a pop-up window in which you can specify the new index groups. To specify new groups, you can use either the GROMACS selection syntax or the extensive selection mechanisms available in SAMSON (see [User Guide: Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md)). In the latter case, the GROMACS selection string will be automatically generated for you based on your selection in SAMSON. Let's see an example: we will add an index group for residues that are in alpha helices. First, we will perform the selection in SAMSON using **Select > Residues > Amino acids > Secondary structure > Alpha helices**. Then, in the Index Groups window, click the **Generate based on current selection in document** button. This will automatically generate a GROMACS selection string using residue or atom selection syntax. Name the new group, e.g., `HELICES`. You can also test the selection string and select nodes in SAMSON based on it. To register the new index group, click the **Add index group to the list** button. The new group will be added to the list: ### Batch preparation This is an **optional step** if you want to **prepare a batch project for a system based on a set of conformations or a trajectory** (this can be useful, for example, for [Umbrella Sampling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/umbrella-sampling/index.md)) or **a batch project for different systems** (e.g., to run the same computations for different proteins). The batch project allows you to easily launch the next steps (minimization, equilibration, simulation) for the whole batch (locally or in the cloud) with the same parameters. Please refer to the [Batch computations](https://documentation.samson-connect.net/tutorials/gromacs-wizard/batch-computations/index.md) tutorial for more information on how to set up a batch project. ## 2. Specifying the model Next, specify the model: 1. [Choose the force field](#choosing-the-force-field). 1. Optionally, [provide additional topology files](#providing-additional-topology-files) if your system contains ligands or other molecules/residues not described by the force field. 1. [Choose the solvent model](#choosing-solvent). ### Choosing the force field Choose the force field that you want to use for the simulation. Please note that **the choice of the force field is important** and might significantly influence the simulation. Refer to publications on the force fields and select the most applicable to your system. For this tutorial, we will be using the all-atom OPLS-AA/L force field. Please choose it from the available force fields in the **Model** section. Note that the force field list contains standard force fields shipped with GROMACS and custom force fields you might have provided in GROMACS Wizard before. If you would like to use a custom force field, please refer to the [Using a custom force field](#using-a-custom-force-field) section below. ### Providing additional topology files The `1AKI` example used in this tutorial has no arbitrary molecules, so you do not need to provide any additional topology files. If your system has any arbitrary molecules that you would like to include in the simulation and for which GROMACS cannot generate the topology itself, then you will need to provide the *include topology files* for them (.itp files). You can generate the topology files for arbitrary molecules using various servers, e.g., the [ATB Server](https://atb.uq.edu.au/) or CGenFF server. If you have them, you only need to provide them in GROMACS Wizard, and it will do the rest for you. Please note that if you provide additional topology files, then it is necessary to provide the force field with which they were parametrized. For example, if you generated ITP files using the ATB server, then download the corresponding force field from this server (e.g., *gromos54a7_atb*). See the [Using a custom force field](#using-a-custom-force-field) section to learn how to provide a custom force field. See also [Simulating protein-ligand systems with GROMACS Wizard](https://documentation.samson-connect.net/tutorials/gromacs-wizard/protein-ligand-systems/index.md). ### Using a custom force field If you want to use a custom force field, then you can easily provide it by clicking on the **Add** button () for force fields. To remove an added force field from the list, click the **Remove** button (). Please note that it will remove all the added custom force fields, but the standard force fields will not be removed. ### Choosing solvent Each force field provides one or more water models that you can use if you want an explicit-solvent simulation. In this tutorial, we will be using the SPC/E water model. Please choose the SPC/E model from the water model list: Note that if you choose "none" as the water model, then it will not be possible to add solvent and ions. To add explicit solvent to the system, check the **Add solvent** option as shown below: Note You can access the **Add solvent** options by clicking on the options/gear button () next to it. It is rarely necessary to modify these options, so leave them as is. One case when it might be necessary to modify them is when [preparing a coarse-grained system](https://documentation.samson-connect.net/tutorials/gromacs-wizard/coarse-grained-systems/index.md). ### Using a custom solvent model If you want to use a solvent model that is not included with the chosen force field, then you can easily provide it by clicking on the corresponding **Add** button () for the water model. In the pop-up dialog, you can provide a topology file (.itp) for a new solvent model and, if necessary, a coordinate file (.gro), see the description below. #### How to choose the solvent structure type If the solvent is a 3-, 4-, or 5-site water model, then you can choose the corresponding type from the list without the need to provide the corresponding structure file; in this case, the corresponding standard coordinate files shipped with GROMACS will be used. Otherwise, you will need to provide a custom coordinate file (.gro) that corresponds to this solvent model. **The coordinate structure file should contain a box of solvent molecules equilibrated in periodic boundary conditions** to ensure good alignment of molecules on the stacking interfaces. The box of solvent is then built by stacking the coordinates read from the coordinate file. To remove an added solvent model from the list, click the corresponding **Remove** button (). Please note that it will remove all the added custom solvent models from the chosen force field, but the standard water models provided with the force field will not be removed. ### Existing hydrogens If your system contains hydrogens, you might choose to ignore them by checking the associated box in the **Model** section. This is especially useful for NMR structures. Otherwise, if hydrogen atoms are present, they must be named exactly how the chosen force field expects them to be named (please check the chosen force field conventions). If you need to preserve hydrogens in the system as they are, then do not apply this option and make sure that all the hydrogens in the system are set and named properly. We recommend ignoring existing hydrogens; GROMACS will then add them using the selected force field naming convention (note that not all force fields use the same H-atom naming convention). ## 3. Defining the box Define the periodic box before proceeding with the preparation step. To define the box, [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) the system from the **Document view** or leave the selection empty if you would like to prepare the whole system in your document. Several types of unit cells are supported: - Cubic, - Orthorhombic, - Triclinic, - Rhombic dodecahedron, - Truncated octahedron. Tip Please refer to [GROMACS Wizard: Periodic boundary conditions](https://documentation.samson-connect.net/tutorials/gromacs-wizard/periodic-boundary-conditions/index.md) for more information. Two options for initial fitting of the box based on the system are available: - **Box lengths** - specify the box size. When fitted, it will fit tightly to your system - you will need to increase the size as needed to ensure the [minimum image convention](https://documentation.samson-connect.net/tutorials/gromacs-wizard/periodic-boundary-conditions/#minimum-image-convention). This option also allows you to move the box to position the system in it. For the batch project, the initial box size is determined based on all the conformations or the whole path - choose this option if you want the box size to be the same for the whole batch. - **Solute-box distance** - specify the distance between the system (solute) and the box. At least 1 nm is recommended to ensure the [minimum image convention](https://documentation.samson-connect.net/tutorials/gromacs-wizard/periodic-boundary-conditions/#minimum-image-convention). For the batch project, the box sizes will be different for each conformation or frame of the path. For the sake of the tutorial, choose the **Orthorhombic** unit cell, then click **Compute fitted box**, and choose the **Solute-box distance** option, as shown below. This will automatically generate the chosen box (its position and size) for your system. All the atoms of your selected system will be included in the box because the box dimensions are determined based on the size of your system (in x, y, and z). Once you have generated your box, you can easily change its size by modifying the corresponding unit cell parameters. Important The box has to include all the structures selected for the preparation. In the case of the **Box lengths** option, it is necessary to **increase the box size** to add enough additional space between the system (without solvent) and the box edges. When the periodic boundary conditions are used, it is crucial to satisfy the *minimum image convention*. This means that, for example, a protein should never see its periodic image; otherwise, the calculated forces might be wrong. We recommend adding a distance of at least 1.0 nm - which means that there is at least 2.0 nm between any two periodic images of a protein or other non-solvent molecules (please note that molecules in the system, e.g., a protein, might go through various conformations). This distance should be sufficient for just about any cutoff scheme commonly used in simulations, but you might need to verify with the force field paper if you are using a custom force field. Note When loading GROMACS results, SAMSON will try to automatically detect the type of the unit cell of the system, but you can always modify it in the importer dialog that appears when loading GROMACS trajectories. ## 4. Neutralizing the system If needed, neutralize the system by adding positive or negative ions. Note Ions are added to the system as a replacement for water molecules, so adding solvent is required if you want to add ions. To neutralize the system, check the **Neutralize system** option as shown below: The neutralization will be done automatically by GROMACS. Each force field proposes a set of positive and negative ions for neutralizing your system with GROMACS. You can choose them from the associated lists. Note that only one type of ion (positive or negative), or none of them, will be added by GROMACS based on the total charge of your system. If you want to know the total charge of your system before running the preparation step, you can compute it by selecting the system and pressing the **Update** button. For example, if your system's total charge is 8, GROMACS will add 8 negative ions to neutralize the system. ### Additional ions You can **increase the ion concentration** in your system by adding more ions. To do so, check the **Add additional ions** box. Two options are available: - **Number of ions** - specify the number of additional positive and negative ions that you would like to be added to the system. For example, if your system's total charge is 8, you can ask GROMACS to add 12 additional positive ions, bringing the total charge of the system to 20. Since GROMACS needs to neutralize the system, it will add 20 negative ions during the preparation stage. Therefore, the ions added to your system to neutralize its total charge go from 8 negative ions to 20 negative ions and 12 positive ions. - **Salt concentration** - specify salt concentration (mol/liter). This will add sufficient ions to reach the specified concentration as computed from the volume of the cell in the input .tpr file. If you specify a salt concentration, existing ions are not taken into account. In effect, you therefore specify the amount of salt to be added on top of neutralizing counterions. These ions will be added on top of neutralizing counterions to reach the specified concentration. A concentration of 0.15 M of NaCl is a popular choice because it is a good representation of physiologic conditions. Note Ions are added to the system as a replacement for water molecules, so adding solvent is required if you want to add ions. ## Run preparation You can remove the initial structure by checking the **Remove initial structure** option. Now everything should be set to prepare the system; click the **Prepare** button to run the preparation step. Some pop-ups might appear informing you about the current steps or possible warnings/issues, if any. To view the log/output, click the **Output** button at the top of the GROMACS Wizard: ### Results Once the preparation is finished, an import dialog will appear asking whether you want to import the prepared system into SAMSON. If you choose to load it, a new structural model representing the prepared system should be visible in the **Document view** and the **Viewport**. In the document, you can find a folder with the available *index groups* created by GROMACS (including custom index groups) – you can double-click on them to select the associated atomic structures. ### Visualization SAMSON automatically applies visualization for proteins in your system: it adds the *Ribbons* visual model and hides protein residues. You can apply more visualizations via the **Visualization menu**, for example via **Visualization > Visual model** or **Visualization > Visual preset**. Please check out the [User Guide: Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) to learn more about how to add visual models, change rendering, and create publication-quality images. ## Related tutorials - [Periodic boundary conditions](https://documentation.samson-connect.net/tutorials/gromacs-wizard/periodic-boundary-conditions/index.md) for choosing an appropriate simulation box. - [Adding custom index groups](https://documentation.samson-connect.net/tutorials/gromacs-wizard/adding-custom-index-groups/index.md) for groups used later in pulling, analysis, or custom workflows. - [Protein-ligand systems](https://documentation.samson-connect.net/tutorials/gromacs-wizard/protein-ligand-systems/index.md) for preparing complexes with parametrized ligands. ## Next step Continue with [Step 2: Energy Minimization](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md) to relax the prepared system before equilibration. # GROMACS Wizard - Pre-processing of the system In this tutorial, you will clean a molecular system before sending it to the main GROMACS preparation workflow. This step helps you remove data that often causes confusion later, such as alternate locations, waters you do not need, ligands you do not want to simulate, and monatomic ions. ## What you will learn In this tutorial, you will learn how to pre-process systems for later GROMACS simulations. ## Before you start - Add [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5). - For this walkthrough, use the `1AKI` structure or a similar protein system. - If your system contains ligands or cofactors that you do want to simulate, do not remove them during cleanup. This section is part of the [GROMACS Wizard tutorial](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md). ## Load the system In this tutorial, we will use the [1AKI](https://www.rcsb.org/structure/1aki) structure. - Open **Home > Fetch**. - Input `1AKI` in **PDB** or **PDB (mmCIF)**. - Click the corresponding **Load** button. Depending on the format, a pop-up dialog might appear asking about import parameters; you can leave them at their default values. If you downloaded the system from the Protein Data Bank website and have it locally on your PC, you can load your system using **Home > Open** (`Ctrl`/`Cmd` + `O`). ## Pre-process the system Before applying the [Preparation step](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md), clean the system with **Home > Prepare**: - **Remove alternate locations**. - Remove unnecessary small molecules (check the **Remove ligands** option). Make sure not to remove ligands that you want to simulate. Note If your system contains any cofactors or other arbitrary molecules for which GROMACS cannot generate topology, and you do not need them in the simulation, you can remove them either by selecting them in the **Document view** and erasing them or by going to **Select > Biology > Ligands**. This should select all small molecules from the current selection or the document if nothing is selected. Verify the selection and erase the molecules you do not need in the simulation. - **Remove water**. Note Please note that this procedure might not be universally applicable. See the [How to delete existing crystal waters outside of the active site](#how-to-delete-existing-crystal-waters-outside-of-the-active-site) section to delete only some water molecules and preserve water molecules that are functional in the system, e.g., tightly bound or active-site waters. - **Remove monatomic ions**. - The **Add hydrogens** option is optional since GROMACS can add hydrogens as well. After this step, you should have a cleaner starting structure with only the molecules you want to keep for simulation. See also Please refer to the [Protein Preparation & Validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) tutorial for more information on how to prepare and fix protein systems. ### How to delete existing crystal waters outside of the active site Please note that if the system contains tightly bound or otherwise functional active-site water molecules, then the procedure described above might not be appropriate. To remove only water outside of the active site, follow the steps described below. 1. Select structures (e.g., ligand, water), residues, or atoms in the active site. 1. Right-click on the current selection in the **Document view** or the **Viewport** and in the context menu go to **Expand selection > Advanced**. 1. In the pop-up dialog, set **Water** as the Node type and choose **beyond** a distance outside of the active site. You can click on the **auto-update** option to see the selection. Click **OK** to select. Verify the selection. 1. Right-click on the selection in the **Document view** or the **Viewport** and click **Erase selection**. ## Parametrization of arbitrary molecules If your system contains arbitrary molecules that you want to keep in the simulation, you will need topology files (`.itp`) for them. You can generate those files with external tools such as the [ATB Server](https://atb.uq.edu.au/) or CGenFF. Once you have them, you can provide them later in the [Preparation step](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md). ## Related tutorials - [Protein preparation and validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) for fixing protein structures before simulation. - [Prepare protein-ligand systems with GROMACS Wizard](https://documentation.samson-connect.net/tutorials/gromacs-wizard/protein-ligand-systems/index.md) when your model contains a ligand that needs parametrization. ## Next step Continue with [Step 1: Prepare](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md) to define the simulation model, box, solvent, ions, and project files. # GROMACS Wizard - Step 5: Production Molecular Dynamics Simulation This section is part of the [GROMACS Wizard tutorial](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md). Once the equilibration steps are complete and the system temperature and density are stable, you can launch the production molecular dynamics (MD) run. ## What you will learn In this tutorial, you will learn how to perform production molecular dynamics simulations with GROMACS Wizard. ## Before you start - Complete [NPT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md) successfully. - Make sure the equilibrated system is the one you want to simulate further. - Decide whether you want to run locally, generate inputs, or send the job to the cloud. ## What success looks like At the end of this step, you should have: - a production MD project with trajectories and plots - output files ready for analysis or follow-up simulations - a stable workflow you can rerun with adjusted parameters if needed ## Start here Switch to the **Simulate** tab. ## Selecting input structure When launching the *Production MD* step, GROMACS Wizard requires one of the following inputs: - **The path to a GRO file** resulting from the previous step: either a GRO file resulting from the [NPT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md) step, or the previous production MD launch. - **The path to a batch project** that has been [equilibrated](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md) or resulted from one of the previous production MD runs. Please refer to the [Batch computations](https://documentation.samson-connect.net/tutorials/gromacs-wizard/batch-computations/#minimize-equilibrate-and-simulate-in-batch) tutorial. If you want to proceed from the previous step, you can simply click on the **auto-fill** button () highlighted in the image below. This will automatically fill the path based on the previous project, whether a GRO file or a batch project from the previous successful run (e.g. from the [NPT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md)). You can also choose the input GRO file yourself by clicking on the **...** button. ## Choosing parameters [GROMACS molecular dynamics parameters](https://manual.gromacs.org/documentation/current/user-guide/mdp-options.html) for production MD are present in the **Parameters** section of the **Simulate** tab. By default, these parameters are populated with default values that are suitable for typical production runs. You can modify these parameters as needed. In the **Parameters** section, you will find the parameters that are most likely to be changed often, like the integration time step and the number of steps. The other GROMACS molecular dynamics parameters can be accessed by clicking on the **All...** button () highlighted in the image above. To learn more about how to apply custom parameters, please check the [Applying custom parameters](https://documentation.samson-connect.net/tutorials/gromacs-wizard/applying-custom-parameters/index.md) section. Note The **position restraint (POSRES\*)** options are filled automatically based on the input system. Important Please ensure that the **temperature coupling** parameters correspond to the ones from the NVT equilibration, and the temperature in the velocity generation (if it is on) as well. Please ensure that the **pressure coupling** parameters correspond to the ones from the NPT equilibration. For this tutorial, reset the parameters to their default values and set the maximum number of steps to `50,000` so the run finishes quickly. Tip To **restore the parameters** to their default values, click on the **Reset** button in the *Advanced parameters window*. To **load the parameters from an MDP file** from some other project, click the **Load from file...** button. To **save the parameters in an MDP file**, click the **Save as...** button. Note The modified parameters are saved when closing SAMSON, so the next time you open it, you will have the previously saved parameters. ## Run Production MD GROMACS Wizard gives you several possibilities: - **Generate inputs** - generates a ready-to-use project that you can, for example, run on your local cluster. - **Simulate locally** - launches the computations locally on your PC using the shipped GROMACS or the version you specified in the settings (see [Using custom GROMACS version and performance parameters](https://documentation.samson-connect.net/tutorials/gromacs-wizard/settings/index.md)). - **Simulate in the cloud** - launches the computations in the cloud. This is suitable for simulating big systems that would otherwise require too many resources to do it locally. This will prompt you to select the Cloud machine, etc. Note that launching in the Cloud requires computing credits. See [Launching Computations in the Cloud](https://documentation.samson-connect.net/tutorials/gromacs-wizard/cloud/index.md) for more information. Click **Simulate locally** to launch the job on your PC. Some pop-ups may appear to report progress, warnings, or input issues. Depending on your PC, the simulation of the system in the tutorial might take a few minutes. You can see the current progress in the Output window, which should pop up. During these calculations, you can still use SAMSON and GROMACS Wizard thanks to the GROMACS Wizard Extension job manager. You can always access the list of local GROMACS jobs and their status via the **Local jobs** button. ## Results ### Importing the results If you launched a single project and there are no other projects in the local job queue, then after the computations are done, a pop-up will appear asking for import options. If you launched multiple jobs or a batch job, then you can check their state in the **Local jobs**. When importing the production MD results, several pop-up dialogs will appear asking for import options and plotting options. The first pop-up asks about options for creating the RMSD plot. The second pop-up asks about options for creating the gyration radius plot. You can choose whether to import the whole trajectory, only the last frame, or some range of frames, and what type of Periodic Boundary Condition treatment to apply, and on what to center the system. For example, as shown in the image below, you can choose to center the system on the Protein. If you do not want to import the trajectory, you can simply click **Cancel** - this will not delete any results and will still generate the plot. You can access the results in the *results folder* specified at the top of the GROMACS Wizard. The folders with results are named with the launch date and time, and the step description (for the Production MD step, the folder suffix is `_md`). ### Plots After the simulation is finished, two plots will be generated to help you analyze your production simulation. The first one shows the evolution of the radius of gyration and the second plot is the RMSD of the chosen structures, e.g. the structure's backbone relative to the structure's backbone present in the initial equilibrated system. If you performed a pulling simulation, e.g. for Umbrella Sampling, then two more plots will be generated showing the pull force and coordinates. The plots are automatically generated and saved when the job is finished and the results are loaded. If you would like to save a plot, click on the **Save** button at the top of the figure. ## Related tutorials - [Launching computations in the Cloud](https://documentation.samson-connect.net/tutorials/gromacs-wizard/cloud/index.md) if you want to run production simulations remotely. - [Pathlines](https://documentation.samson-connect.net/tutorials/pathlines/pathlines/index.md) for visualizing center-of-mass motion along paths. - [Umbrella Sampling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/umbrella-sampling/index.md) if your production or pulling trajectories are part of a free-energy workflow. ## Next step Inspect the trajectory and plots in SAMSON, then continue with the analysis or advanced workflow that matches your simulation goal. # GROMACS Wizard - Protein-ligand systems Use this tutorial to prepare and simulate a non-covalent protein-ligand complex with GROMACS Wizard. By the end, you should know how to parametrize the ligand, combine it with the protein model, and prepare the full complex for the standard GROMACS Wizard workflow. Note This tutorial covers the case of non-covalently linked complexes. For a covalently linked protein-ligand complex, additional special treatment for parametrization of the linking bond is required. ## What you will learn In this tutorial, you will learn how to parametrize a ligand, combine it with a protein, and prepare a protein-ligand system for GROMACS Wizard workflows. ## Before you start Before proceeding, review the following tutorials: - [Pre-processing](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preprocess/index.md) - [Step 1: Prepare](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md) - Make sure the ligand name in the structure file will match the name used in the topology data you import later. ## 1. Ligand parametrization If your ligand is not already available as a standard residue in the target force field, you first need to parametrize it. In practice, this means choosing a server or tool that matches the force field you plan to use later in GROMACS Wizard. You can **parametrize your ligand using automated tools/servers**, for example, the following ones depending on the chosen force field: - [Antechamber](https://ambermd.org/) - parametrizes molecules for **AMBER**. - [ATB](https://atb.uq.edu.au/) - a topology generation server for **GROMOS96 54A7** force field. - [CGenFF](https://cgenff.com/) - a topology generation server for **CHARMM** force field. - [LigParGen](http://zarbi.chem.yale.edu/ligpargen/) - a topology generation server for **OPLS-AA** force field. Before you export anything from SAMSON, check which file formats the chosen server accepts as input. Note Please refer first to the [Pre-processing of the system for GROMACS Wizard](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preprocess/index.md) tutorial. ### Add hydrogens Most of the parametrization tools/servers **require a ligand to have all hydrogens properly set**. You can **add hydrogens** directly in SAMSON (**Edit > Add hydrogens**): - For standard ligands present in the **Chemical Component Dictionary (CCD)** it will add all hydrogens with their proper names as described in the CCD. If you downloaded the system from the Protein Data Bank, then, mostly likely, its ligands are present in the CCD. - For ligands that are not present in the CCD it will add hydrogens based on valences. So, your ligand should have aromatic rings and charges already specified. If you have a non-standard ligand in a file format that contains this info (e.g., .mol2), prefer to use this file for adding hydrogens in SAMSON. You can also use any other external tools to add hydrogens, e.g. Open Babel. ### Extract ligand from structure If your ligand is part of a protein-ligand complex, extract it first so you can submit it to the parametrization tool or server. To do that, [select](https://documentation.samson-connect.net/users/latest/selecting/#selecting-using-the-document-view) the ligand in the **Document view**, go to **Home > File > Save selection as...**, and choose a file format accepted by the parametrization workflow you selected. If you already have a ligand file with all the hydrogens added, then you can directly use it in the parametrization tool/server of your choice. Tip If the parametrization tool/server requires another file format, you can use SAMSON to convert between formats: load the file in SAMSON and save it into the required format. ### Parametrization Use the parametrization tool or server of your choice to obtain the ligand topology. At the end, you should have: - **include topology file (.itp)**; - if available, an updated structure file for checking the structure; - optionally, the force field, if it uses some modified one (e.g., *gromos54a7_atb* from the ATB server). Note Some of these servers have a limit on the maximum ligand size. If your ligand has more atoms, then you can try to subdivide the ligand into chunks (sub-residues), possibly overlapping ones, and parametrize them separately with taking into account the connection between chunks. For this, please refer to the documentation and/or papers for the tool/server you are using. ## 2. Combine protein and ligand Now that the ligand is parametrized, download an updated structure file from the server if one is available. This makes it easier to verify whether the parametrization tool changed atom names, hydrogens, or other structural details. If you already had your protein-ligand complex together and **the ligand structure hasn't changed** (i.e., no atom name changes or new hydrogens added), then you can skip this step. If you already have a ligand in the protein-ligand complex and want to replace it, then you can first position the new/updated ligand at the old ligand's position and then delete the old ligand. If you don't have the ready-to-use protein-ligand complex, then you will need to **add your ligand to the system** using one of the following ways: - Use any of the [move objects functionalities](https://documentation.samson-connect.net/users/latest/moving-objects/#move-editors) available in SAMSON, e.g., use [Move editors](https://documentation.samson-connect.net/users/latest/moving-objects/#move-editors) to manually place the ligand in the desired location. - Use [AutoDock Vina Extended](https://documentation.samson-connect.net/tutorials/adve/docking-libraries-of-ligands-with-autodock-vina-extended/index.md) to dock the ligand into a binding pocket. - Append the ligand structure into the protein structure file - make sure the structures do not overlap in positions and are either placed in separate chains or have consecutive sequence numbering. If you need to convert file formats, you can load a file in SAMSON and save it in the required format. **Ensure that the ligand is named the same in the structure file and in the topology file** (.itp) provided by a parametrization tool/server. ## 3. Prepare the protein-ligand system Open the GROMACS Wizard in SAMSON (**Home > Apps > Biology > GROMACS Wizard**) and switch to the **Prepare** tab. Choose the protein-ligand system in the **Document view** in SAMSON and set it in GROMACS Wizard via **Set system**. Tip Please refer to the [GROMACS Wizard - Step 1: Prepare](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md) tutorial for more information. ### Provide ligand topology file Now, you need to provide the *include topology file* (.itp file) for the ligand, and GROMACS Wizard will do the rest for you. For that, click on the **Edit** button for *include topology files (itp)* in the **Choose model** section: In the pop-up dialog, click on **Browse** and choose the necessary .itp file(s). Please note that when you provide additional topology files, then it might be necessary to provide the force field with which they were parametrized if it is not provided with the GROMACS Wizard by default. For example, if you generated ITP files using the ATB server then download the corresponding force field from this server (e.g., *gromos54a7_atb* from the ATB server). Please see the [Provide custom force field](#provide-custom-force-field) section. ### Provide custom force field If the parametrization server you used provides a **custom force field** (e.g., *gromos54a7_atb* from the ATB server) that is not available in GROMACS by default, then you will need to provide it in GROMACS Wizard. First download this custom force field from the server you used and then, in GROMACS Wizard, simply click on the **Add** button () for force fields. You need to do it only once - the added force field will be stored by the GROMACS Wizard. To remove an added force field from the list, click the **Remove** button (). Please note that it will remove all the added custom force fields, but the standard force fields will not be removed. ### Prepare Please refer to the [GROMACS Wizard - Step 1: Prepare](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md) tutorial for the other steps (choosing the solvent model, the periodic boundary box, ions, etc.), if you haven't already done them. Once you have finished setting up the preparation parameters, click the **Prepare** button at the bottom of the tab to run the preparation step. Note Some pop-ups might appear informing you about the current steps or possible warnings/issues, if any. For example, a warning if using the *gromos54a7* force field from the ATB server. Tip To view the log/output, click on the **Output** button at the top of the GROMACS Wizard: Once the preparation has been successfully done, the resulting system will be saved in the results folder, you will be asked whether you would like to load it in SAMSON (optional, if you want to check the prepared system), and you can proceed to the [next steps](#next-steps). ## Next steps For the next steps, please refer to the corresponding general tutorials: - [Step 2: Energy Minimization](https://documentation.samson-connect.net/tutorials/gromacs-wizard/energy-minimization/index.md) - [Step 3: NVT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/nvt-equilibration/index.md) - [Step 4: NPT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md) - [Step 5: Production Molecular Dynamics Simulation](https://documentation.samson-connect.net/tutorials/gromacs-wizard/production-md/index.md) ## Related tutorials - [Protein preparation and validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) for cleaning the protein before ligand setup. - [Step 1: Prepare](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md) for the general GROMACS Wizard preparation workflow. - [Periodic boundary conditions](https://documentation.samson-connect.net/tutorials/gromacs-wizard/periodic-boundary-conditions/index.md) for choosing an appropriate simulation box. # GROMACS Wizard - Using custom GROMACS version and performance parameters This section is part of the [GROMACS Wizard tutorial](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md). Use this page when the default packaged GROMACS setup is not the one you want to run locally. ## What you will learn In this tutorial, you will learn how to use a custom GROMACS installation and tune local performance settings in GROMACS Wizard. ## Before you start - Use this page only for **local** computations. Cloud jobs ignore the local performance parameters described below. - Open GROMACS Wizard first so you can access its **Settings** button and compare the packaged version with your local installation. - If reproducibility matters, decide in advance which exact GROMACS version and force-field directory you want to use. ## Using a custom GROMACS version [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5) comes with one of the latest versions of GROMACS, but it also lets you use your own version of GROMACS for local computations. This might be useful if you would like to use the GROMACS package installed on your system or use a specific GROMACS version for reproducibility reasons. To use a locally installed version of GROMACS, click the **Settings** button at the top of GROMACS Wizard. There, you can see the version of the shipped GROMACS package. If you would like to use another version of GROMACS that is installed on your machine, then check the **Use a different GROMACS version** option and provide two paths: 1. A path to the GROMACS executable (`gmx.exe` on Windows or `gmx` for Linux and macOS) by clicking on the button. Note that the version of the chosen GROMACS package will also be displayed (if the executable was not recognized, then "invalid" will be displayed instead). 1. A path to the force fields folder where all the *forcefield.ff* folders are present (e.g., *$HOME/gromacs/share/top/* on Linux and macOS). ## Maximum warnings option The `-maxwarn` option can be used to override warnings printed by `gmx grompp` that otherwise halt execution. In some cases, warnings are harmless, but usually they are not. It is advisable to carefully interpret the output messages before attempting to bypass them with this option. Please note that this is not for normal use and may generate unstable systems. One of the possible uses is when you simulate a system with a GROMOS force field that leads to a warning; to bypass it, you can set the `-maxwarn` option to 1. Note This option applies both to local and cloud jobs. ## Additional performance parameters > "The GROMACS build system and the gmx mdrun tool have a lot of built-in and configurable intelligence to detect your hardware and make pretty effective use of it. For a lot of casual and serious use of gmx mdrun, the automatic machinery works well enough." (source: GROMACS Manual) Note These options apply only to local jobs; they are not transmitted to Cloud jobs. By default, GROMACS Wizard sets the **number of threads** for **local jobs** lower than the absolute maximum so that your machine stays responsive while the job is running. If it is set to `0`, GROMACS will guess the number of threads automatically. If it is set to a non-zero value below the number of logical cores, GROMACS Wizard also uses `-pin on` to improve thread placement. The **Settings** provide you with the possibility to specify additional performance parameters that will be used when running GROMACS locally. For example, you can specify the level of parallelization, control parameters of domain decomposition, and PME algorithms. The possible options include, but are not limited to: `ntmpi`, `ntomp`, `pme`, `maxh`. Please see the following link for more information and more options: [GROMACS Manual - Getting good performance from mdrun](https://manual.gromacs.org/documentation/current/user-guide/mdrun-performance.html). ## Related tutorials - [Launching computations in the Cloud](https://documentation.samson-connect.net/tutorials/gromacs-wizard/cloud/index.md) for jobs where local GROMACS and local performance settings do not apply. - [Step 5: Production Molecular Dynamics Simulation](https://documentation.samson-connect.net/tutorials/gromacs-wizard/production-md/index.md) for long jobs where local performance tuning can matter most. ## Next step Return to the GROMACS Wizard calculation you want to run locally and launch it with the selected executable and performance settings. # GROMACS Wizard - Umbrella Sampling This section is part of the [GROMACS Wizard tutorial](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md). Use this tutorial when you want to turn a reaction-coordinate pathway into umbrella-sampling windows that can later be analyzed as a PMF. This tutorial demonstrates how to perform Umbrella Sampling using [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5). ## What you will learn In this tutorial, you will learn how to perform Umbrella Sampling with GROMACS Wizard. ## Before you start - Decide how you will obtain the starting conformations for the windows. - If you already have a pulling trajectory, follow **Option 1**. - If you already have conformations or a path in SAMSON, follow **Option 2**. To perform Umbrella Sampling, first obtain a set of initial conformations. You can do that in one of the following ways: - [From GROMACS trajectory](#option-1-from-gromacs-trajectory) obtained from some simulation, e.g., by performing [COM pulling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/com-pulling/index.md) simulation. - [From a set of conformations or a path (trajectory)](#option-2-from-conformations-or-path) created outside SAMSON or in SAMSON. Then you need to [perform NPT equilibration and production MD simulation](#npt-equilibration-and-simulation) with specific COM pulling parameters for the reaction coordinate or coordinates you want to analyze. Once the simulation is done, you can perform [PMF analysis](#pmf-analysis). ## Option 1: From GROMACS Trajectory Use this route if you already have a GROMACS trajectory and want to pick frames from it as the initial conformations for umbrella windows. For this tutorial, we use the results from the [COM Pulling tutorial](https://documentation.samson-connect.net/tutorials/gromacs-wizard/com-pulling/index.md). ## Generate Umbrella Sampling Project Switch to the **Umbrella Sampling** tab in the GROMACS Wizard. Choose the input project - this will automatically identify the trajectory file from the project folder. Then specify the **reaction coordinate** by choosing two index groups. Note You can **add custom index groups** that might later be useful for analysis or during the simulation (e.g., as pull coordinate groups). Please refer to [Step 1: Prepare - Adding custom index groups](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/#adding-custom-index-groups). You should see the reaction coordinate plot showing distance vs. time with the suggested initial conformations depicted via vertical and horizontal dashed lines. Now, specify the spacing between initial conformations. You have two options: - **Number of conformations** - the conformations will be equidistributed along the reaction coordinate. - **Minimum COM spacing** - the conformations will be chosen to satisfy the specified center of mass (COM) distance. Note You can also specify the start and end frames between which the initial conformations should be chosen. Once you choose the spacing for initial conformations, click **Generate project**. This creates a **batch project** folder with a timestamp and `_umbrella` suffix. Each subfolder corresponds to one umbrella window, and `frames.ndx` records which original frames were chosen. ## Option 2: From Conformations or Path Use this route when the starting states already exist in SAMSON as conformations or a path. Follow the [Batch computations](https://documentation.samson-connect.net/tutorials/gromacs-wizard/batch-computations/index.md) tutorial until the NVT equilibration step. For NPT equilibration and production MD, you will need to add the umbrella-specific COM pulling parameters described below. ## NPT Equilibration and Simulation Now, you can perform **NPT equilibration** (see [Step 4: NPT Equilibration](https://documentation.samson-connect.net/tutorials/gromacs-wizard/npt-equilibration/index.md)) and then **production MD simulation** (see [Step 5: Production Molecular Dynamics Simulation](https://documentation.samson-connect.net/tutorials/gromacs-wizard/production-md/index.md)) for this batch project. Note You need to run NPT equilibration with the added COM Pulling parameters since they modify the system's behavior. In these steps, choose the batch project as the input path (if you click the **auto-fill** button () it will be set automatically based on the previous run). Apart from other parameters, you need to set the **COM pulling parameters for the reaction coordinate** or coordinates you want to analyze. For each of the steps, NPT equilibration and simulation, in the advanced parameters window, set the COM pulling parameters as needed and set the rate to 0. For this tutorial, we set them as follows - we use a single reaction coordinate for the distance between the center of masses of chain `A` and chain `B` while setting the rate to 0 to omit the actual pulling itself: - type: umbrella - geometry: distance - group 1: chain A - group 2: chain B - start: yes - distance: N N Y (i.e., pulling in the z-direction) - init: 0 nm - **rate: 0 nm/ps (i.e. no pulling)** - force constant: 1000 kJ mol^-1 nm^-2 Once you have specified the parameters, launch the computations locally or in the Cloud (see [Launching computations in the Cloud](https://documentation.samson-connect.net/tutorials/gromacs-wizard/cloud/index.md)). Note that when launching local computations for a batch project, they will be added as local jobs - a separate job per subfolder in the batch project - you can access them in the **Local jobs** window and see their status, change their priority (order), cancel or stop them, import them, or open their folders. ## PMF Analysis Once the umbrella-sampling simulations are complete, continue with [Potential of Mean Force (PMF) analysis](https://documentation.samson-connect.net/tutorials/gromacs-wizard/pmf-analysis/index.md) to compute the PMF using WHAM. ## Related tutorials - [COM Pulling](https://documentation.samson-connect.net/tutorials/gromacs-wizard/com-pulling/index.md) for creating pulling trajectories that can seed umbrella sampling windows. - [Potential of Mean Force analysis](https://documentation.samson-connect.net/tutorials/gromacs-wizard/pmf-analysis/index.md) for computing the PMF from completed umbrella sampling simulations. - [Batch computations](https://documentation.samson-connect.net/tutorials/gromacs-wizard/batch-computations/index.md) for managing repeated simulations across windows. ## Next step Run or finish the umbrella sampling simulations, then continue with [Potential of Mean Force analysis](https://documentation.samson-connect.net/tutorials/gromacs-wizard/pmf-analysis/index.md). # Protein docking with Hex Use the [Hex SAMSON Extension](https://www.samson-connect.net/extensions/d53ab0d1-37bb-0fb9-0474-e090aa46af3e) to prepare two proteins, configure the docking search, and run a protein-protein docking workflow in SAMSON. The [Hex Extension](https://www.samson-connect.net/extensions/d53ab0d1-37bb-0fb9-0474-e090aa46af3e) wraps the protein docking program [Hex](https://hex.loria.fr/) developed by [David Ritchie](https://scholar.google.co.in/citations?user=fUBkvj4AAAAJ) ([Protein Docking Using Case-Based Reasoning. A.W. Ghoorah, M. Smail-Tabbone, M.-D. Devignes, D.W. Ritchie, (2013). Proteins: Structure, Function, Bioinformatics](https://dx.doi.org/10.1002/prot.24433)) ## What you will learn In this tutorial, you will learn how to prepare two proteins, configure Hex in SAMSON, and run a protein-protein docking workflow. ## Before you start - Add the [Hex Extension](https://www.samson-connect.net/extensions/d53ab0d1-37bb-0fb9-0474-e090aa46af3e). - Open the sample document from SAMSON Connect, or load your own receptor and ligand proteins. - If you use your own structures, clean and protonate them before docking. ## First steps In SAMSON, go to **Home > Download** and insert () - this will load a document with this tutorial's sample from [SAMSON Connect](https://www.samson-connect.net/). The sample document contains structural models of two proteins: `2PTC_E` and `2PTC_I`. Note If you cannot see the **Document view**, you can enable it in the **Interface** menu or by using the shortcut: `Ctrl`/`Cmd` + `1`. ## Preparation of the system Now, we need to prepare the system: 1. Remove atoms with alternate locations. 1. Remove water, monatomic ions, ligands, if they are present. 1. Add hydrogens, if they are not present. Note that if the system has hydrogens added based on some protonation you should not modify hydrogens. To do all of this in a single step, go to **Home > Prepare** and check the above-mentioned options as shown in the image below. If your system has missing residues or heavy atoms (e.g., missing atoms in side chains), you can also use the [PDBFixer](https://www.samson-connect.net/extensions/c81b69fc-4df0-fe09-146c-3591b20ba609) extension to **fix a protein**. This extension can also be used to add hydrogens for specific pH. See also Please refer to the [Protein Preparation & Validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) tutorial for more information on how to prepare and fix protein systems. Note The system in the tutorial file has all the water already removed and hydrogens already added. Tip: visualization If you do not have secondary structures shown, you can add them for each of the two proteins by first selecting their structural model in the **Document view** and then clicking on **Visualization > Visual model > Ribbons**. You can hide/show the atomistic representation by toggling the boxes in front of the protein structure in the **Document view**. To learn more about visual models in SAMSON, please follow interactive tutorials in SAMSON (**Help > Tutorials**) or the [User guide: Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) tutorial. ## Setup of the system Open the **Hex** app via **Home > Apps > Biology > Hex**. You can also find it using the **Find everything...** search box in the top menu of SAMSON - just start typing the name. Let's now set one protein as the receptor and another one as the ligand. Select the `2PTC_E` protein in the document and click **Set** as the receptor. Select the `2PTC_I` protein in the document and click **Set** as the ligand. Let's save the initial ligand conformation. For that, select the ligand, `2PTC_I`, in the document and click **Edit > Conformation**. This will be useful if you want to redo the docking with different parameters for the same initial conformation. ## Hex parameters Below is a brief description of the main Hex parameters. To learn more about them and other parameters, please see their tooltips in the Hex interface and the [Hex manual](https://hex.loria.fr/manual800/hex_manual.pdf). Below we list some of the main parameters. You can always reset parameters to their default values by clicking on the **Reset parameters** button. ### Correlation type The *Correlation type* is used to specify the type of docking calculation to be performed (*Shape-only*, *Shape + electrostatics*, etc). Requesting electrostatics can be beneficial if the proteins have complementary formal charges. Electrostatics should not be used when docking DNA or RNA molecules. ### Sampling method Choose the type of sampling method. It is used to restrict the docking search. ### Range angles The docking search may be restricted by defining *range angles* for the receptor and/or ligand orientations. If range angles are defined, then the interface residues will always be constrained to appear within a spherical cone (with its axis being an intermolecular axis between origins of both proteins) defined by the corresponding range angle. You can define the range angles in the **Advanced parameters**. If the interface residues of a receptor or a ligand are known, you can orient them pointing at each other and limit the receptor and ligand range in the **Advanced parameters** to reduce the number of false-positive or incorrect docking predictions and to reduce the search time. See below how to specify the range angles in the [Setup of the search domain](#setup-of-the-search-domain) section. ### Post-processing Following the basic docking correlation algorithm, candidate docking orientations may be filtered and refined using one of the Post-processing options. Post-processing is applied to the user-selected number of top-scoring solutions from the correlation search. #### Bumps counts The simplest option is to enable a bumps counter, in which the number of steric clashes between non-bonded pairs of heavy atoms in each solution is calculated. An option in the *Results table* may then be used to filter out solutions with a specified number of steric clashes. #### Molecular Mechanics Refinement This is in an alpha stage in Hex. In addition to the bumps counter, a single (rigid body) molecular mechanics energy may be calculated for each docking solution (MM Energies), or a Newton-like energy minimization (MM Minimisation) can be applied to each docking solution. These energies are calculated using "soft" Lennard-Jones and hydrogen bond potentials, adapted from the OPLS forcefield parameters, along with an explicit charge-charge electrostatic contribution. When docking complexes where conformational changes are known to be small, this gives an effective way to prune many "false-positive" orientations and to enhance the energy of the "right answer". However, this rigid-body refinement procedure should not be used if conformational changes are expected to be large because (despite using soft potentials) it tends to eject ligands with incorrect conformations from the binding site. ### Steric scan Performs the fast low-resolution *Steric scan* phase before the high-resolution *Final search*. Hex performs the high-resolution *Final search* correlation using smaller distance increments than are used for the fast low-resolution *Steric scan* phase. This allows the search space to be covered more rapidly (coarsely) in the first phase, but more finely in the final phase. Together with the *Final search*, this allows the search space to be covered more rapidly (coarsely) in the first phase (the *Steric scan* phase), but more finely in the final phase. The *Steric scan* order equal to 16-18 should be sufficient in most cases. In this mode, almost all but the top 10,000-30,000 orientations (depending on other advanced parameters) are discarded after the *Steric scan*. The *Steric scan* may be toggled off, in which case every orientation is evaluated using a steric correlation (and optionally an electrostatic correlation) to order `N`, as given the *Final search* slider. However, this can significantly increase total docking times. Using the two-step search with `N=16` for *Steric scan* and `N=25` for *Final search* (or `N=20` for *Steric scan* and `N=30` for Final search) is found to work well in practically all cases. See also the *Final search* parameter. ### Final search order This is the order of 3D expansion. The *Final search* order should be higher than the *Steric scan* order if the *Steric scan* is used. Hex performs the high-resolution *Final search* correlation using smaller distance increments than are used for the fast low-resolution *Steric scan* phase. This is used to specify the main expansion order `N`, although the default value of `N=25` is usually sufficient for most purposes. However, performing the full docking calculation with `N=25` is time-consuming. Generally, `N=30` is recommended when docking high-resolution crystal structures for which the conformational change on the binding is expected to be small. `N=25` should be used when docking model-built structures or structures which are expected to be more flexible. ## Setup of the search domain The **Sampling method** needs to be set to **Range angles**. To specify the search area (range angles), click **Advanced parameters**. In Hex the docking search is done in spherical coordinates and the search domain is determined by the rotational angles of the receptor and the ligand around the intermolecular axis that connects centers of the receptor and the ligand. By default, the angles are set to 180 degrees meaning that the whole sphere of the molecule is accessible to the search. Please note that only the ligand is rotated and positioned around the receptor. If you already know the location of the binding site, you should manually move and orient the ligand to be close to the binding site and then restrict the receptor rotation angle range to a small value, say 45 degrees. This should limit the search domain and improve the search time. To align (translate and rotate) the ligand towards the receptor you can use one of the [Move editors](https://documentation.samson-connect.net/users/latest/moving-objects/index.md). **Range angles of the receptor and the ligand:** In the case of the rotational search - the sampling method is set to range angles - the angular search may easily be constrained using the Range angle parameter for each protein, which essentially defines a spherical cone centered on the intermolecular axis that goes through the origins of both proteins. Only angular samples that fall within the Range Angle cone are used for the docking search. A Range angle of 180 degrees corresponds to using no angular constraints, whereas a range angle of 45 degrees would typically be a good choice to loosely limit the search about the starting orientation. **Twist angle range:** A twist rotation about the intermolecular axis (an axis between origins of the proteins). Let's now specify the receptor angle range and the ligand angle range. Set the receptor angle range to 45 degrees and the ligand angle range to 45 degrees. You should see two cones with their apexes placed in the centers of two proteins and an axis connecting the centers of two proteins. In the same way, you can limit the twist rotation angle of the ligand about the intermolecular axis. ## Running the docking Once you have specified the necessary parameters, click on the **Run docking** button. For the system in the tutorial, the docking should take several minutes. Tip To see logs, start the **Log viewer** module (**Home > Apps > All > Log viewer**). ## Results Once the docking search is done, you can view the results in the **Results** tab. The modes are clustered together and you can view either the best mode (the lowest energy solution) per cluster or all the modes. By clicking on a row in the table, the corresponding conformation of the ligand will be restored. You can also export this conformation in the document by right-clicking on the row[s] and choosing **Create conformation**. You can also launch an animation of all the modes at the bottom of the **Results** tab. In the GIF below, we have applied the Gaussian surface to the receptor and colorized it based on the residue hydrophobicity. ## Performing further analysis SAMSON provides different tools to perform analysis of the results. You can add various visual models, measure distances, compute some parameters, and check for ligand-receptor interactions. Below you will find some examples. The [Protein-Ligand Interaction Analyzer](https://www.samson-connect.net/extensions/98bd1552-4642-9e86-6a78-83c9e96a63ee) Extension allows for computing the contact area, H-bonds between a ligand and a receptor, ligand surrounding residues, and some other parameters. The [Hydrogen Bond Finder](https://www.samson-connect.net/extensions/e0caae67-7422-ef1a-bf97-bcb88f1d2a11) Extension allows one to find and visualize hydrogen bonds (H-bonds) inside a molecule or between molecules, e.g., between a ligand and a receptor. To find H-bonds between a ligand and a receptor, select the second option (**... in the current selection and the system**), then select the receptor and click on the **Set** button, modify parameters if necessary (you can later modify them in the created H-bond visual model using the **Inspector**), then select a ligand and click on the **Add hydrogen bond visual model** button. Please see the [AutoDock Vina Extended tutorial - Performing analysis](https://documentation.samson-connect.net/tutorials/adve/docking-libraries-of-ligands-with-autodock-vina-extended/#performing-further-analysis) for more details on different tools for analysis. That's all, thank you for completing this tutorial on the [Hex Extension](https://www.samson-connect.net/extensions/d53ab0d1-37bb-0fb9-0474-e090aa46af3e). ## Related tutorials - [Protein preparation and validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) for cleaning structures before docking. - [Symmetry detection in biological assemblies](https://documentation.samson-connect.net/tutorials/symmetry/computing-axes-of-symmetry-of-biological-assemblies/index.md) for analyzing symmetric protein assemblies. - [Protein alignment](https://documentation.samson-connect.net/tutorials/protein-aligner/protein-aligner/index.md) for comparing related protein structures before or after docking. ## Next step Inspect the most relevant docking poses with visual models, measurements, or interaction analysis tools before choosing candidates for further modeling. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # Ligand Path Finder Use the [Ligand Path Finder](https://www.samson-connect.net/extensions/280cac50-31cd-e0ad-76c3-d254cd736967) app to search for possible ligand unbinding pathways from a protein and inspect the resulting candidate routes directly in SAMSON. The **Ligand Path Finder** uses the **ART-RRT** approach, which combines **T-RRT** for pathway search and **ARAP modeling** for ligand motion generation [1](#fn:1). During the search, the method also uses constrained minimization to adapt the protein as the ligand moves. ## What you will learn In this tutorial, you will learn how to set up Ligand Path Finder, define the ligand and search region, and compute possible unbinding pathways. ## Before you start - Add [Ligand Path Finder](https://www.samson-connect.net/extensions/280cac50-31cd-e0ad-76c3-d254cd736967). - Add the [FIRE](https://www.samson-connect.net/extensions/8ec255b0-7326-0bed-366e-40be71c1d160) state updater. - Use the sample system first if this is your first time with the workflow. ## Requirements - [SAMSON](https://www.samson-connect.net) version 2020 R1 or higher - [Ligand Path Finder](https://www.samson-connect.net/extensions/280cac50-31cd-e0ad-76c3-d254cd736967) app - [FIRE](https://www.samson-connect.net/extensions/8ec255b0-7326-0bed-366e-40be71c1d160) state updater ## Load the input model Load the sample system: 1. Click **Home > Download**. 1. Paste (). 1. Click **Download**. This will load a document with this tutorial's sample from [SAMSON Connect](https://www.samson-connect.net/). The sample document contains a structural model of *Lactose permease* with its ligand *Thiodigalactosid (TDG)*. In the **Document view** (1), you can see the protein under the name `Protein_chain_A` and the ligand under the name `TDG` as shown in the picture below. You can also see one conformation named `bound_minimized` which is the minimized conformation of the protein-ligand complex. 1. **Interface menu > Document view** or , : `Ctrl`+`1`, : `Cmd`+`1` Note For your own model, you might need to first prepare it (remove alternate locations, water, and ions, and add hydrogens) - for that you can use **Home > Prepare** - and, possibly, fix it. Please refer to the [Protein Preparation & Validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) tutorial for more information on how to prepare and fix protein systems. ## Launch the Ligand Path Finder app Open the **Ligand Path Finder** app via **Home > Apps > Biology** or find it via **Find everything**. In the app, you can see two tabs: the **Settings** tab is for configuring the search and the **Results** tab is for visualizing results. ## Setup interaction and state updater models for energy evaluation Note The system needs to be already minimized. You can [minimize the system](https://documentation.samson-connect.net/users/latest/minimizing/index.md) using **Edit > Minimize** which uses Universal Force Field (UFF). First, in the **Settings** tab, we need to specify an interaction model and a state updater which will be used in the computations. For the **Interaction model** select **Universal Force Field** (UFF) in the drop-down list, and for the **State updater** select **FIRE**. If you do not see the **FIRE** state updater, please check the [requirements](#requirements) section and make sure you installed it from [SAMSON Connect](https://www.samson-connect.net/). A window will pop up asking if you want to apply a new model, click **Yes**. The **Universal Force Field (UFF)** setup will then ask whether to use existing bonds - choose to use existing bonds and click OK. Two windows should appear: the **Universal Force Field** properties window showing its parameters and UFF energies of the current state of the system and the **FIRE Properties** window showing the state updater parameters. Set the parameters for FIRE as in the picture below (the step size to 1 fs and the number of steps to 1). ## Setup the system Let's now set up the system. Expand the **Set up the system** box. Note During the setup of the system, a new visual model should appear for showing the sampling box and atom types: blue for passive ARAP atoms, green for active ARAP atoms, and red for fixed atoms. ### Define the bound state Let's choose the starting conformation. Select the `bound_minimized` conformation in the **Document view** and then, in the App, click **Set** as starting conformation. The chosen conformation will be considered as the starting state for the search tree. Note Before creating a conformation for your system, make sure the system is oriented/aligned in such a way that the search domain efficiently encapsulates the possible unbinding pathways since the search domain is defined as a box in Cartesian coordinates. You can orient the system using [Move editors](https://documentation.samson-connect.net/users/latest/moving-objects/index.md) and you can align the system with respect to Cartesian coordinates by selecting a structural model and in its context menu going to **Move selection > ...**. The system in this tutorial sample is already aligned with Z-axis. Tip To create a conformation for your system, use **Edit > Conformation**. ### Define the ligand atoms Now we need to define the ligand. Select `TDG` in the **Document view**, this will select all the ligand atoms (see [User guide: Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md)). Then, in the App, click the **Set** button to set the ligand atoms. The rest of the atoms will be considered as protein atoms. In the **Advanced information** box, a new line should appear: "31 atoms set as ligand atoms". ### Define the active ARAP atoms Now we need to specify which ligand atoms will be considered by the ARAP method as **active atoms** used for controlling the ligand motion. The motions of the rest of the ligand atoms (also called passive ARAP atoms) will follow active atoms. Let's choose the Sulfur atom from the `TDG` ligand: `S1`. For simplicity, the document contains a group named **S1 from TDG** that refers to this atom. In the **Document view**, double-click on this **S1 from TDG** group. This will select nodes in the group, i.e. the `S1` atom. Tip For your system, you can select atoms both in the **Document view** and in the **Viewport** using the selection editor. See [User guide - Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md). Then, in the App, click the **Add** button to set the active ARAP atoms. ### Define the fixed ARAP atoms Finally, we need to specify which protein atoms will be considered by the ARAP method as having a fixed position. This is to ensure that the protein will not drift along with the ligand (note that this choice may influence the resulting unbinding pathways, so in general you should choose atoms from parts of the protein that are expected to be rather static). Let's choose the **CA** atom in the **Backbone** of **HIS 205** residue of the protein as the fixed ARAP atom. For simplicity, the Document has a group named **CA from HIS 205** that refers to this atom. In the **Document view**, double-click on this group to select the corresponding atom. Tip For your system, you can select atoms both in the **Document view** and in the **Viewport** using the selection editor. See [User guide - Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md). Then, in the App, click the **Add** button to set the fixed ARAP atom. In the **Advanced information** box, you should see the number of added active and fixed ARAP atoms. You can see which atoms were chosen as ligand, active or fixed ARAP atoms by clicking the corresponding **Select** buttons. If you are not satisfied with the starting conformation selection, ligand atom selection, or atom type assignment, you can reset your choices by clicking the corresponding **Reset** () button. ## Define the sampling box Let's now define the sampling region (the sampling box for the active ARAP atoms). Expand the **Set the sampling region** box. The sampling box defines the sampling region for the chosen active ARAP atoms. The size and position of the box biases the ligand motion and therefore the resulting unbinding pathways. The app suggests the sampling box size which encloses the ligand and protein atoms. Let's set the sampling box dimension as shown below - this box dimension biases the ligand motion towards the periplasmic side of the protein: A green box visualizes the sampling box. ## Define the search parameters Let's now define the parameters. Expand the **Set parameters** box and set them as in the following figure: - **Use seed**: use the specified seed number for the planner and after each run the seed value is incremented by 1. If the box is unchecked, a random seed is used. The specified seed number is needed if you want to reproduce the results later for the same seed. - **Runs** = 2: we run the method 2 times to extract a maximum of 2 paths. - **ARAP-modeling iterations** = 20: the number of iterations for the ARAP modeling method. - **Minimization iterations** = 20: apply 20 steps of constrained minimization with FIRE each time a new state is sampled to minimize it. - **Initial temperature (T)** = 0.001 K, **Temperature factor** = 2, **Failures before increase of T** = 1: parameters for T-RRT. - **Max. ligand displacement** = 40 A: each run is stopped as soon as the center of the ligand is displaced by 40 angstrom from its original position. - **RRT extension step size** = 1 A: the size of the extension step is 1 angstrom. This affects how fast the conformation space is sampled. - **Maximum time per run**: each run is stopped as soon as the elapsed time reaches this value. ## Run the planner Once you set up the system, the sampling box, and specified the parameters, you can launch the search for ligand unbinding pathways. Click the **Run** button to start the planner. Note The search process can be paused by clicking the **Pause** button and resumed after that by clicking on the **Resume** button (these buttons are located at the same place as the **Run** button while the planner is running). To stop the process, click the **Stop** button. During the search, in the **Advanced information** box under the **Planning information**, you can observe the elapsed time for the current run (**Current running time**), the elapsed time for all of the runs (**Total running time**), the number of nodes of the tree in the current run (**Nodes**), the run number (**Run**), and the number of paths found (**Paths found**). ## Results As soon as a path is found, it is added to the list in the **Results** tab. For example, the following figure shows two paths found. Each path contains the following fields: - **id**: the path id - **# states**: the number of conformations in the path. - **MinE (kcal/mol)**: the minimum energy of the path conformations. - **MaxE (kcal/mol)**: the maximum energy of the path conformations. - **Saddle (kcal/mol)**: the difference between **MaxE** and **MinE**. - **Barrier (kcal/mol)**: the difference between **MaxE** and **First**. - **Time (s)**: time elapsed for searching this path. - **First (kcal/mol)**: the energy of the first conformation in the path. - **Last (kcal/mol)**: the energy of the last conformation in the path. - **Remarks**: comments on the path (editable). - **Color**: the color of the energy curve for this path. ### View conformation energies along the path To view the energy curve of the path, select a path by clicking on it in the path table. To plot several energy curves, select several paths (`Ctrl`/`Cmd` + left-click for multi-selection). After selecting a path, you can move the slider to see a particular conformation in the path as shown in the picture below. The corresponding conformation is reflected in the structural model in SAMSON and its corresponding energy is shown in the **Universal Force Field** window. ### Export the results: paths, conformations, path table content You can copy the content of the path table to the clipboard by selecting the paths for which you want to export data and pressing `Ctrl`/`Cmd` + `C` or right-clicking and choosing **Copy table content**. You can also copy path energy values along the selected paths via right-clicking and choosing **Copy path energy**. To export paths from the path table into the document as trajectories, select the paths you are interested in and press the **Export paths** button. To export conformations along the path into SAMSON, select the paths from the path table, choose the export interval and click the **Export** button. Tip You can double-click on a path in the document to start/stop it. To access the path controllers, select the path and open the **Inspector** (1). If you right-click on a path, you can also access some of its options via **Path > ...**. 1. **Interface > Inspector**, , : `Ctrl`+`2`, : `Cmd`+`2` ## Next steps ### Create pathlines Check the [Pathlines tutorial](https://documentation.samson-connect.net/tutorials/pathlines/pathlines/index.md) to learn about how to create pathlines to visualize the movement of the center of mass of a ligand. ### Improve paths with P-NEB The resulting paths can be significantly improved with the help of the parallel Nudged Elastic Band (NEB) method implemented in the [P-NEB app](https://www.samson-connect.net/extensions/4d3a7d66-0e60-b9d4-b84e-71f00595bfda). Please check out the [P-NEB tutorial](https://documentation.samson-connect.net/tutorials/pneb/optimize-transition-paths-with-parallel-nudged-elastic-band/index.md) for more information. ### Export atoms trajectories along paths The resulting paths can be saved in the .sam and .samx formats. If you want to export only trajectories of some atoms along the path, you can use the [Export Along Paths app](https://www.samson-connect.net/extensions/cc339322-498f-28e6-90b6-5e656cc345c3). Please refer to the [tutorial on how to use the Export Along Paths app](https://documentation.samson-connect.net/tutorials/export-along-path/export-atoms-trajectories-along-paths/index.md) for more information. ## Related tutorials - [Optimize transition paths with P-NEB](https://documentation.samson-connect.net/tutorials/pneb/optimize-transition-paths-with-parallel-nudged-elastic-band/index.md) for refining computed unbinding paths. - [Pathlines](https://documentation.samson-connect.net/tutorials/pathlines/pathlines/index.md) for visualizing path motion. - [Protein Path Finder](https://documentation.samson-connect.net/tutorials/protein-path-finder/protein-path-finder/index.md) for transition paths between protein conformations. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). ## References ______________________________________________________________________ 1. [Nguyen MK, Jaillet L, Redon S. ART-RRT: As-Rigid-As-Possible exploration of ligand unbinding pathways. J Comput Chem. 2018 Apr 30;39(11):665-678. doi: 10.1002/jcc.25132. Epub 2018 Jan 5. PMID: 29315658.](https://doi.org/10.1002/jcc.25132) [↩](#fnref:1 "Jump back to footnote 1 in the text") # Create coarse-grained models for the MARTINI force field using Martinize2 Use the [Martinize2](https://www.samson-connect.net/extensions/0753f4e9-00ce-ae5b-eefd-d95f3e0c29bd) SAMSON Extension to turn an atomistic structure into a *coarse-grained* (CG) MARTINI model [2](#fn:2) together with the topology files needed for GROMACS. The extension uses [Martinize2 and Vermouth](https://github.com/marrink-lab/vermouth-martinize) [1](#fn:1) to automate the conversion workflow inside SAMSON. A CG structure is a simplified representation of an all-atom structure achieved by grouping multiple atoms into CG beads (e.g., all amino acid backbone atoms are represented by a single bead). This reduces the complexity of a modeled system, allowing you to speed up simulations by several times. ## What you will learn In this tutorial, you will learn how to generate MARTINI coarse-grained models and GROMACS topology files from atomistic structures with Martinize2 in SAMSON. ## Before you start - Add [Martinize2](https://www.samson-connect.net/extensions/0753f4e9-00ce-ae5b-eefd-d95f3e0c29bd) from [SAMSON Connect - Marketplace](https://www.samson-connect.net/extensions). - Start with a clean atomistic structure. If needed, use [Protein Preparation & Validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) before coarse graining. - This tutorial uses the Ubiquitin protein (`1UBQ`) as an example, but the same setup applies to your own structure. ## Create a CG model from an atomic structure Let's see how to create CG structures and topologies using an example of the Ubiquitin protein ([1UBQ](https://www.rcsb.org/structure/1UBQ)). 1. Load into SAMSON the atomic system(s) for which you want to create CG model(s) (structures and topologies). Tip To download a PDB structure from RCSB PDB, go to **Home > Fetch** and provide the PDB code, you can choose any source: **PDB** or **PDB (mmCIF)**. 1. Prepare the protein system(s) using **Home menu > Prepare**. Choose to remove alternate locations, water, ions, ligands, and other molecules used for crystallization. See also Please refer to the [Protein Preparation & Validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) tutorial for more information on how to prepare and fix protein systems. 1. Open **Martinize2** (**Home > Apps** or via **Find everything...**) 1. Select the system in the document. Note Each structural model (the top-level structural node as shown in the image above) will be treated as a separate input model by Martinize2, i.e., separate coarse-grained models will be generated. 1. Click **Set** in Martinize2. 1. Check the **Martinize2 options**, e.g.: - The *force field* to use: **martini3001**. - The *position restraints* (they will be added in the generated include topology files (`.itp`)): - **backbone** - create position restraints for backbone beads in proteins, - **all** - create position restraints for all beads, - **none** - no position restraints will be generated in the output `.itp` file. - *Apply side chain corrections*. - *Set neutral termini*, charged is the default. - etc. Tips Hover above options to check the tooltips. Scroll to see all the options. You can always click **Restore default values** to reset options to default. 1. Specify the results folder where the project folders should be created. 1. Click **Create coarse-grained models**. You should see the progress in the log output. The results should appear in a timestamped project subfolder in the chosen results folder. The project subfolder contains: - The `inputs` subfolder with input PDB structures, one per input structural model. - A log file. - The `outputs` subfolder with the generated CG models, one subfolder per input model. There you can find PDB and GRO files for the CG model, the topology files (`.top` and `.itp` file(s)) for GROMACS, and a log file with the *martinize2* command info. If you generated a CG model for a single structure, then it will be loaded in SAMSON. Note SAMSON tries to detect CG systems when loading files to visualize them as connected beads. ## Creating CG model for multiple replicas Let's say you want to create a CG model for a system that contains multiple replicas of the same protein. We will be using the same example of the Ubiquitin protein ([1UBQ](https://www.rcsb.org/structure/1UBQ)). ### Creating replicas You can create copies of your system using the [Molecular Box Builder](https://documentation.samson-connect.net/tutorials/molecular-box-builder/molecular-box-builder/index.md), some [Python script](https://documentation.samson-connect.net/scripting/latest/index.html), or manually in SAMSON. If you already have your replicas created, please go to the [Renumber chains and residues](#renumber-chains-and-residues) section. #### Creating replicas manually Let's see how to create replicas manually. First, let's **ensure that all atoms are visible** - this will help us in copying and placing the replicas. Toggle the structural model visibility by unchecking and checking the checkbox of the structural model as shown in the image below: This should result in the fully visible atomic structure of the structural model. Let's now create replicas: 1. Select the chain(s) from the structural model. 1. Do a copy-paste: press `Ctrl`/`Cmd` + `C` and then `Ctrl`/`Cmd` + `V`. This should create a new copy of the chain in place, i.e., in the same structure and at the same position. 1. While having the newly copied chain selected in the document view, as shown in the image above, switch to one of the [move editors](https://documentation.samson-connect.net/users/latest/moving-objects/#move-editors) via the editors toolbar on the left side of the viewport, e.g., use the [global move editor](https://documentation.samson-connect.net/users/latest/moving-objects/#global-move-editor) (shortcut: `K`) and [move](https://documentation.samson-connect.net/users/latest/moving-objects/index.md) the newly created chain. Tip You can specify the [translational and rotational snapping](https://documentation.samson-connect.net/users/latest/moving-objects/#moving-objects-with-snapping) in the top-left corner of the viewport. See the gif below. 1. Proceed with steps 1-3 until you have the desired number of replicas. Tip You can copy and move multiple chains at the same time. Tip Once you're done, you can switch back to the [rectangle selection editor](https://documentation.samson-connect.net/users/latest/selecting/#selecting-using-editors) (shortcut: `R`). ### Renumber chains and residues Once you have all the replicas created, you need to **ensure that residues have unique IDs and chains have unique IDs and names**. Otherwise, there might be issues when creating topologies. 1. **Renumber residue IDs**: right-click on the structural model and, in the context menu, go to *Structural model > Renumber residues and structural groups*: In the pop-up dialog, leave the default value to 1 and click *OK*. 1. **Renumber chain IDs**: right-click on the structural model and, in the context menu, go to *Structural model > Renumber chain IDs*: In the pop-up dialog, leave the default value to 0 and click *OK*. 1. **Rename chains to ensure unique names**. You can rename chains directly in the document via `F2` or right-click and *Rename*: or via the [Inspector](https://documentation.samson-connect.net/users/latest/inspecting/index.md) Tip Save the system into a file to store your work. ### Next Once you have your [replicas created](#creating-replicas) and [ensured unique numbering and naming](#renumber-chains-and-residues), you can then proceed with the same steps as in the [Create a CG model from an atomic structure](#create-a-cg-model-from-an-atomic-structure) section. ## See also For the documentation on [Martinize2 and Vermouth](https://github.com/marrink-lab/vermouth-martinize) see . ## Related tutorials - [GROMACS Wizard coarse-grained systems](https://documentation.samson-connect.net/tutorials/gromacs-wizard/coarse-grained-systems/index.md) for preparing the generated coarse-grained model for simulation. - [GROMACS Wizard tutorials](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md) for the full minimization, equilibration, and production MD route. - [Protein preparation and validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) for cleaning atomistic input structures before coarse-graining. ## Next step Continue with [GROMACS Wizard coarse-grained systems](https://documentation.samson-connect.net/tutorials/gromacs-wizard/coarse-grained-systems/index.md) to prepare and simulate the coarse-grained model. ## References ______________________________________________________________________ 1. Peter C. Kroon, Fabian Grunewald, Jonathan Barnoud, Marco van Tilburg, Paulo C. T. Souza, Tsjerk A. Wassenaar, Siewert-Jan Marrink. Martinize2 and Vermouth: Unified Framework for Topology Generation.  [↩](#fnref:1 "Jump back to footnote 1 in the text") 1. P.C.T. Souza, R. Alessandri, J. Barnoud, S. Thallmair, I. Faustino, F. Grünewald, et al., Martini 3: a general purpose force field for coarse-grained molecular dynamics, Nat. Methods. 18 (2021) 382–388. DOI:  [↩](#fnref:2 "Jump back to footnote 2 in the text") # Create molecular boxes with Molecular Box Builder The [Molecular Box Builder](https://www.samson-connect.net/extensions/3d8237a4-d3a0-942b-a6b0-9baa049cb195) extension for SAMSON allows you to fill a 3D box with molecules - you can build solvent boxes, lipid layers, and custom molecular assemblies. Use this tutorial when you want to populate a box with repeated molecules, estimate how many copies fit, or quickly build a simple solvent or membrane-like environment. The [Molecular Box Builder](https://www.samson-connect.net/extensions/3d8237a4-d3a0-942b-a6b0-9baa049cb195) app can be found in the **Home > Apps > Assembly** or via the **Find everything...** (`Shift`+`E`) in the top menu of SAMSON. ## What you will learn In this tutorial, you will learn how to fill a 3D box with molecules in SAMSON using Molecular Box Builder. ## Before you start 1. Log into [SAMSON Connect](https://www.samson-connect.net/). 1. Visit the [Molecular Box Builder](https://www.samson-connect.net/extensions/3d8237a4-d3a0-942b-a6b0-9baa049cb195) Extension page and click **Add**. 1. Restart SAMSON - your extension will be ready to use. 1. Keep the molecule you want to replicate open in the document so you can set it directly from the selection. ## Launch the App Access [Molecular Box Builder](https://www.samson-connect.net/extensions/3d8237a4-d3a0-942b-a6b0-9baa049cb195) via **Home > Apps > Assembly > Molecular Box Builder**. Or use **Find everything...** (`Shift`+`E`) at the top of SAMSON and search "*Molecular Box Builder*". ## Step 1 - Set the Molecule to Insert 1. [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a molecule or molecular system with which you would like to populate a box in the **Document view** or **Viewport**. This can be one or several molecules, structural models, structural groups, or residues, or even just atoms. 1. Click **Set** in the app. Tip Click **Select** in the app to highlight the structure. Click **X** in the app to clear the currently set molecule. ### Optional: Define Orientation You can specify how molecules should be oriented when added: - **No alignment** - use original orientation. - **Align to +X / -X / +Y / -Y / +Z / -Z** - align the molecule's first principal axis (the first eigenvector of the moment of inertia) with the selected direction. Note You can always **move and rotate** the system in SAMSON using the [Move editors](https://documentation.samson-connect.net/users/latest/moving-objects/index.md). SAMSON automatically calculates the bounding box of the molecule based on the chosen alignment. ## Step 2 - Define the Box 1. Enter box dimensions `(X, Y, Z)`. 1. Optional: to center the box around the origin or a specific point, check **Center** and adjust the center coordinates. By default, the box is positioned in such a way that its corner is aligned with the origin. 1. Optional: specify the **margin between inserted molecules** (positive or negative). By default, molecules will be added in the box such that there will be no clashes between them. **Molecular Box Builder** predicts how many molecules can fit along each axis and their total number (shown in the **Generate** part). Adjusting the box size or molecule's margin updates this prediction. You can toggle visibility of the box as needed by pressing the corresponding buttons in the app. ## Step 3 - Generate the System To cap the total number of inserted molecules, check **Maximum number of molecules to generate** and specify a limit. Otherwise, it will place as many molecules as possible in the box, which should be equivalent to the predicted number. Click **Generate**. Depending on the size of the system, the generation should take a few seconds. Result: a filled box populated with non-overlapping copies of the selected molecule. ## Build a Lipid Layer Around a Protein You can also use **Molecular Box Builder** to generate lipid membranes around proteins. Tip You can also use the [PDBFixer](https://www.samson-connect.net/extensions/c81b69fc-4df0-fe09-146c-3591b20ba609) extension to **build a membrane** (from a list of available lipids) around a protein with water and neutralize the system with specified ions. Let's, for example, build a single layer of lipids around the copper-transporting PIB-ATPase [4BBJ](https://www.rcsb.org/structure/4bbj). ### Step 1 - Align the Protein First, we need to reorient the protein: 1. Right-click the protein in **Document view**. 1. In the context menu, choose: **Move selection > Align with Z axis**. 1. Then: **Move selection > Center on the origin**. ### Step 2 - Set the Lipid Molecule 1. Import a lipid molecule. 1. Select it and click **Set**. 1. Align its principal axis to the `+Z` axis. ### Step 3 - Define the Box 1. Center the box around the protein. 1. Adjust the size to contain a single lipid layer. 1. Specify the margin between the inserted molecules if needed. ### Step 4 - Generate 1. Enable **Consider existing molecules in the box** so lipids are placed only in available space. 1. Click **Generate**. Now you should have a single layer of lipids around the protein: ### Optional: Create a Lipid Bilayer 1. Add the first layer with `+Z` alignment. 1. Shift the box center in the `Z`-direction. 1. Add the second layer with `-Z` alignment. Now you have a full lipid bilayer. ## Next Steps Minimize, equilibrate, and simulate the system using, for example, [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5) (see the [GROMACS Wizard tutorial](https://documentation.samson-connect.net/tutorials/gromacs-wizard/)). ## Related tutorials - [GROMACS Wizard tutorials](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md) for preparing, minimizing, equilibrating, and simulating the generated system. - [Step 1: Prepare with GROMACS Wizard](https://documentation.samson-connect.net/tutorials/gromacs-wizard/preparation/index.md) for turning the generated structure into simulation files. - [UMA Force Field](https://documentation.samson-connect.net/tutorials/uma-force-field/uma-force-field/index.md) for machine-learning based atomistic evaluation. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # Molecular Restrainer: Energy Minimization of NMR-Derived Structures [Molecular Restrainer](https://www.samson-connect.net/extensions/f09f42ea-0a8f-caa6-8497-dda5aefc0448) is a SAMSON Extension that lets you **quickly refine NMR-derived molecular structures** - including protein-ligand complexes with non-standard residues - without the need for custom force-field files. It combines the [Universal Force Field (UFF)](https://www.samson-connect.net/extensions/8cbdc8b1-59e1-6459-d68f-b840275dd5e9) with **NOE-derived distance restraints** to deliver publication-ready models for the Protein Data Bank (PDB) deposition or your next molecular-design project. **Key Benefits**: - Seamless post-processing of CYANA outputs. - **No topology or parameter files needed** thanks to UFF. - Works with **any molecule type**: standard and non-standard residues, ligands. - **Batch processing**: minimize entire NMR ensembles in one run. - Delivers **high-quality, energy-minimized structures** ready for journals, PDB deposition, and downstream molecular-design workflows. - Can later be easily adapted to other restraint formats beyond CYANA. Reference To learn about methods and the validation used in the **Molecular Restrainer**, please refer to the paper[1](#fn:1). Note This SAMSON Extension is a collaboration between the [Orts Group](https://bionmr.univie.ac.at/) (University of Vienna) and [OneAngstrom](https://www.oneangstrom.com/), the provider of the SAMSON platform. ## What you will learn In this tutorial, you will learn how to refine NMR-derived structures in SAMSON with Molecular Restrainer and NOE-based restraints. ## Before you start - Prepare an NMR-derived structure or ensemble in SAMSON. - Keep the matching CYANA `.upl` file ready. - If this is your first run, follow the quick-start once before changing advanced settings. ## Requirements - SAMSON 2024 or newer. - [FIRE optimizer module](https://www.samson-connect.net/extensions/8ec255b0-7326-0bed-366e-40be71c1d160). ## Quick-Start Tutorial All you need is your NMR ensemble and the corresponding, NOE-derived, [upper-distance-limit file](https://cyana.org/wiki/Distance_restraint_file) (`.upl`) generated by CYANA. - Open **Molecular Restrainer**: **Home > Apps > Biology > Molecular Restrainer** (or use **Find everything...**). - **Load your NMR structure** into SAMSON. Multiple conformations will appear as a path (trajectory) plus one corresponding structure. - Click **Set** inside **Molecular Restrainer** to select the structure and, optionally, a path you wish to minimize. - **Choose your .upl file** under *Restraints*. - **Press Start**. Done! ## Detailed Setup ### 1. Set the Input Structure Load into SAMSON an NMR-derived structure or ensemble that you would like to minimize. Note The input file can contain an **ensemble (multiple conformations)** - it will appear as a path (a trajectory) and a single structure. The **Molecular Restrainer** can perform a **batch minimization** of the whole ensemble. Input Structure Must Be Complete UFF, used by the **Molecular Restrainer**, expects the input structure to be valid, i.e., **there should be no missing atoms (neither heavy atoms nor hydrogens), and no alternate locations**. Usually, the NMR-derived structures should be OK, but they might be missing atoms in terminal residues (the N-terminal amine protons and C-terminal "OXT" oxygen) - for that the **Molecular Restrainer** provides the **Fix N- and C-termini** option that checks and fixes the termini (only termini with standard amino acid residues would be fixed) in the initial structure and for all the conformations along the path with respect to the new positions. You can just keep this option checked at all times. Need extra structure validation? See [Protein Preparation & Validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md). But note that adding hydrogens using SAMSON might change the names of hydrogens (if they were not named with the standard convention in the first place) which might influence the restraints loaded from an `.upl` file since they are done based on the atom names. Also, if you have a path, the adding of hydrogens will not add them along the path but only based on the positions of the initial structure and you will lose the hydrogens in the path. Now, you need to set the structure in the **Molecular Restrainer**: - If nothing is selected in the document, and you click **Set**, then it will choose the whole document as the input, i.e., all the structures and paths, if present. - If you want to minimize only a specific structure (e.g., without a path), then select it in the **Document view** and click **Set**. You should see a brief description of the specified input structure: ### 2. Load NOE Restraints Accepted format: NOE-derived **upper-distance-limit** (`.upl`) files. Restraints are matched by residue ID and atom name - including pseudoatoms (see below). UPL Format For the format of the **upper distance limit file** (`.upl`) please see [CYANA wiki - Distance restraint file](https://cyana.org/wiki/Distance_restraint_file). ### Pseudoatoms **Molecular Restrainer builds pseudoatoms internally on-the-fly** from hydrogen positions using these rules: | Pseudoatom | Parent atoms | | ---------- | --------------------------------------------------------------------- | | `Q` | `H1`, `H2`, `H3` | | `QX` | `HX1`, `HX2`, `HX3`, where `X` is a letter | | `QQX` | `HX11`, `HX12`, `HX13`, `HX21`, `HX22`, `HX23`, where `X` is a letter | Partial sets (e.g., only `HX2` and `HX3` for a `CH2` group) are accepted. Example: `QA` would be formed from `HA1`, `HA2`, `HA3`, if these are present. These rules correctly create most pseudoatoms of the standard residues. Ligand Pseudoatoms CYANA pseudoatom names for ligands and non-standard residues may not follow standard rules and might not be compatible with the above-mentioned rules; hence, they might not be identified. If such restraints cannot be applied, then they are reported in `restraints.log`. ## Energy Minimization ### Minimization parameters To perform the energy minimization with restraints, the **Molecular Restrainer** uses a **combined potential** of the UFF and the restraints (see the paper[1](#fn:1)) based on the specified weights: | Parameter | Default | Purpose | | ------------------- | ------- | ------------------------------------------------------------ | | UFF weight | 0.2 | Balances generic force-field terms | | Restraints weight | 1.0 | Keeps NOE distances satisfied | | Random force weight | 0.0 | Helps escape local minima during the minimization (optional) | Leave defaults unless you have a specific need. ### Stopping criteria Minimization stops when either the **restraint energy** or the **total energy** plateaus - i.e., the *relative energy change* ((\\Delta E\_{\\text{rel}})) between successive iterations stays below the given **energy tolerance** for a set number of iterations (**plateau threshold**). You can leave the parameters set by default. Relative Energy Change Formula The **relative energy change** is computed as follows: [ \\Delta E\_{\\text{rel}} = \\frac{|E\_{n+1} - E_n|}{|E\_{n+1}|} ] where (E) is either the restraints energy or the full energy and (n) is the integration step. Tip You can adjust plateau threshold or energy tolerance during the minimization if needed. ### Run the minimization - Pick an output folder - each run creates a timestamped subfolder. - Click **Start**. After a quick initialization, the energy minimization will start. The log window shows progress per conformation, and the progress bar shows the progress if there are multiple initial conformations. Note Need to abort? Click **Stop**; the current structure is still saved both in the results folder and as a conformation in the document. The results folder will contain the following files per conformation: - `input.pdb` - original system, - `energy.csv` - table with energies vs iteration, - `minimized.pdb` or `stopped.pdb` - final coordinates, and the following global files: - `output.log` - full console log, - `restraints.log` - restraints that could not be applied because the atoms corresponding to a restraint were not found in the system, - `minimized_path.pdb` - all minimized conformations as a single trajectory (if applicable). ## Visualization of the restraints During a run, **Molecular Restrainer** adds to the document a simulator with an **interaction model** that represents the **combined potential** of the UFF and the restraints. This model also visualizes the restraints - they are shown as additional "bonds" with their colors ranging from red (unsatisfied restraint, large energy) to green (satisfied restraint, small energy). Want to modify how restraints are visualized (e.g., transparency, radius)? Selecting this interaction model in the **Document view**: …then change settings in the **Inspector**. ## Further Reading & Validation For algorithm details, benchmarks, and validation, see the original paper[1](#fn:1). ## Related tutorials - [Fast geometry optimization with FIRE minimizer](https://documentation.samson-connect.net/tutorials/fire/ready-set-fire/index.md) for the state updater used in restrained minimization. - [Universal Force Field](https://documentation.samson-connect.net/tutorials/uff/uff/index.md) and [Interactive Modeling Universal Force Field](https://documentation.samson-connect.net/tutorials/uff/im-uff/index.md) for related force-field workflows. - [Protein preparation and validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) for checking protein structures before or after refinement. ## Next step Inspect the refined model and restraint visualization, then validate the structure or export it for deposition or downstream modeling. ## References ______________________________________________________________________ 1. Jiří Mareš, Guneet Singh Tarang, Dmitriy Marin, Mehdi Mobli, Stephane Redon and Julien Orts. Streamlined Postprocessing of NMR Structures with the Molecular Restrainer: A Universal Tool for High-Quality Protein–Ligand Models and Non-Standard Amino Acid Residues. Int. J. Mol. Sci. 2025, 26(11), 5091.  [↩](#fnref:1 "Jump back to footnote 1 in the text")[↩](#fnref2:1 "Jump back to footnote 1 in the text")[↩](#fnref3:1 "Jump back to footnote 1 in the text") # Build carbon nanotube models This tutorial shows how to easily generate single-walled and multi-walled **carbon nanotube (CNT)** models in SAMSON using the [Nanotube Creator](https://www.samson-connect.net/extensions/1ebd1e1c-2f89-62bd-02c2-08216dcbd60b) Extension - a useful tool in molecular design, nanotechnology, and computational materials science. ## Where Can It Be Used? - Design CNT-based nanodevices or sensors. - Build nanostructures for molecular simulations. - Study mechanical or electronic properties of CNTs. - Use CNTs in molecular transport, drug delivery, or membrane modeling. ## What you will learn In this tutorial, you will learn how to generate single-walled and multi-walled carbon nanotube models with Nanotube Creator in SAMSON. ## Before you start 1. Log into [SAMSON Connect](https://www.samson-connect.net/). 1. Visit the [Nanotube Creator](https://www.samson-connect.net/extensions/1ebd1e1c-2f89-62bd-02c2-08216dcbd60b) Extension page and click **Add**. 1. Restart SAMSON - your extension will be ready to use. 1. Decide whether you want a quick interactive build in the viewport or a more controlled setup through the graphical interface. ## Activate the Nanotube Creator This extension provides an [editor](https://documentation.samson-connect.net/users/latest/editors/index.md) - an interactive tool that lets you build CNTs using the mouse or a graphical interface. You can **activate the editor** in two ways: - From the viewport left-side menu: **... > Materials > Nanotube Creator**. - Or use the *Find everything...* (`Shift`+`E`) and search "Nanotube Creator". Note Only one editor can be active at a time in SAMSON. ## Building nanotubes You have two modes to create nanotubes: - interactively in the viewport with the mouse, - using the nanotube creator's graphical interface. ### Method 1 - Create Nanotubes Interactively You can interactively build nanotubes in the viewport in two steps: 1. Set the nanotube axis and length (defines `n` parameter) - press and drag the **left mouse button** in the viewport: Watch the **status bar** for live feedback on axis orientation and tube length: 1. Set the nanotube radius (defines `m` parameters): 1. Release the mouse button 1. Move the mouse to adjust the radius (changes `m` parameter) 1. Click the left mouse button again to confirm Check the status bar during building to precisely choose the `n` and `m` parameters. ### Method 2 - Use the Graphical Interface Prefer precise control? Open the editor's graphical interface (GUI) by activating the editor. If the interface is hidden, reselect the editor to toggle visibility. Using the GUI, you can easily create multi-walled nanotubes. ### Parameters - **Start / End Position** - define the nanotube's axis in 3D space and its start and end positions. - **n / m values** - define the chiral vector (structure and radius). Click **Build** to generate a nanotube using current parameters. ### Example - Multi-Walled Nanotube Try building three concentric CNTs: 1. Start/end positions: `(0, 0, 0)` and `(40, 0, 0)` to create a CNT with length of 40 Å along the x-axis. 1. CNT 1: `n = 6`, `m = 6`. Click **Build**. 1. CNT 2: `n = 10`, `m = 10`. Click **Build**. 1. CNT 3: `n = 14`, `m = 14`. Click **Build**. This will produce the multi-walled nanotube below: ## What's Next? Once you've created your CNTs, you can: - Export images: [Visualization Guide](https://documentation.samson-connect.net/users/latest/visualizing/index.md). - [Interactively simulate nanotubes in real-time, e.g. using the Brenner potential](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/#building-a-carbon-nanopore). - Combine CNTs with other molecules for hybrid nanostructures. Example: [Building and modeling a Carbon Nanopore](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/#building-a-carbon-nanopore) ## Applications in Molecular Design & Nanoscience - Design molecular transport systems or channels. - Build nanoelectromechanical systems (NEMS). - Integrate CNTs into advanced material simulations. - Explore electronic/thermal properties of CNTs. ## Related tutorials - [Generate crystal models](https://documentation.samson-connect.net/tutorials/crystal-creator/generating-crystal-models/index.md) for another materials-science modeling workflow. - [Universal Force Field](https://documentation.samson-connect.net/tutorials/uff/uff/index.md) when you want to continue with force-field based modeling. ## Next step Use the [SAMSON User Guide: visualizing](https://documentation.samson-connect.net/users/latest/visualizing/index.md) to create images of the nanotube model, or return to the [Extensions Tutorials](https://documentation.samson-connect.net/tutorials/#materials-science) materials-science section. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # Compute normal modes that open a binding site Use the [Normal Modes Advanced](https://www.samson-connect.net/extensions/589e13f2-183c-a8c4-3dcd-66b6b807520c) (*NMA*) extension when you want to explore large-scale biomolecular motions, such as opening a binding site or connecting two nearby conformations. It extends the [Normal Modes Analysis](https://www.samson-connect.net/extensions/4bd07765-ab03-bade-11d6-35c1c8739fbf) extension with richer controls for nonlinear motion analysis in SAMSON. This extension computes nonlinear normal modes of a biomolecular system (protein, RNA, DNA) using the NOLB algorithm developed by Alexandre Hoffmann and Sergei Grudinin ([J. Chem. Theory Comput., 2017, 13 (5), pp 2123-2134](https://doi.org/10.1021/acs.jctc.7b00197)). ## What you will learn In this tutorial, you will learn how to compute nonlinear normal modes in SAMSON to explore binding-site opening and large-scale biomolecular motions. ## Before you start - Add [Normal Modes Advanced](https://www.samson-connect.net/extensions/589e13f2-183c-a8c4-3dcd-66b6b807520c) from [SAMSON Connect - Marketplace](https://www.samson-connect.net/extensions). - Open a biomolecular structure in SAMSON before launching the extension. The examples on this page use the `1VPK` PDB entry. - Use this page when you want to explore motions interactively, define a target opening/closing objective, or save interesting conformations for later work. ## Compute and explore the modes Start by importing a structure. This tutorial uses [1VPK](https://www.rcsb.org/structure/1vpk), but you can use your own protein, RNA, or DNA model. Then launch the NMA module and choose the main calculation settings: - the number of modes to compute - the interaction cutoff distance - the potential function to use At the moment, the elastic network model potential is the one available in the interface. You can run the calculation on the full structure or only on a selected subset of residues by using SAMSON's [selection tools](https://documentation.samson-connect.net/users/latest/selecting/index.md) before starting the computation. During computation, a progress bar is displayed and the computation steps are shown in the SAMSON status bar. A few seconds later, the result of the computations is displayed in the **Output** box: Moving a slider will instantaneously display the mode-specific motion of the structure: Note how each mode also has a specific **checkbox** and **reset** button. Modes can be combined (when their *checkbox* is checked) and applied to the structure using the **play**/**pause** button. Note that, during motion, the unchecked sliders can still be manually modified. Therefore, the motion obtained from this modification will also be displayed during the trajectory: While the mode motions are applied to the structure, real-time minimization can be activated, using one of three available minimization algorithms: Mode sliders can be reset to zero either independently using their corresponding **reset** button or all simultaneously using the **reset all** button. Also, all checked modes can be unchecked using the **clear** button, while the **update** button applies the values of the sliders to the structure: During motion, the type of transformation applied can be either linear (translations only) or nonlinear (translations and rotations). And the *scaling factor* can be increased or decreased to change the amplitudes of the motion: The motion speed can be modified while the motion type can be *harmonic* or not. **Forward and backward steps** buttons can be used to navigate through the trajectory step by step: ## Structure definition In the Normal Modes Advanced module, you can find the best combination of normal modes that can open/close a defined pocket. This definition can contain residues or atoms. In the **Structure Definition** tab, you can define a target structure and find the best combination of modes that will reach this target structure. ## Save/export a resulting conformation When an interesting conformation of the structure is found, you can save it in different ways. First, you can store a conformation of the structure in the document (shortcut `S`). With SAMSON conformations you can quickly restore the saved conformation of the structure: However, using SAMSON conformations, you will not be able to superpose several states of the structure. For this kind of operation, you need to create a SAMSON structural model. To do that, select the entire structure, or only part of it, then click on the **create** button of the NMAL app. You can also export the current structure as a PDB file using the **export** button: You can store the entire trajectory by going to the **save frames** tab of the module. Once the *saving interval* has been set, you can either store the trajectory as a set of conformations by clicking on the **store** button or export the trajectory as PDB files using the **export** button. By double-clicking on the conformation node, you can directly display it. Also, the SAMSON conformations that represent the trajectory can be removed using the **remove** button: It is also possible, by clicking on the **Path** button, to store the entire trajectory in the new SAMSON trajectory node. You can start and pause the playing of the trajectory by double-clicking on the trajectory node. Finally, note that the trajectory and the conformations will be saved using the current settings of the **calculations** tab. These settings include the motions corresponding to the checked modes, the current slider value of the checked modes, the value of the scaling factor, the motion type (harmonic or not), and, of course, the saving interval. ## Related tutorials - [Interactive Ramachandran Plot](https://documentation.samson-connect.net/tutorials/ramachandran/ramachandran-plot/index.md) for inspecting backbone conformations after moving a protein. - [Generate transition paths with ARAP Interpolation](https://documentation.samson-connect.net/tutorials/arap/arap-interpolation-for-protein-structures/index.md) for creating paths between protein conformations. - [Protein Path Finder](https://documentation.samson-connect.net/tutorials/protein-path-finder/protein-path-finder/index.md) for searching transition paths between conformations. ## Next step Save the conformations or trajectory you need, then continue with path generation, analysis, or simulation. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # Predict protein-ligand complexes using NMR2 Use [NMR2](https://www.samson-connect.net/extensions/6150c6f4-d891-b58b-a8b5-dbc197087841) in SAMSON to combine NMR-derived information with a guided protein-ligand complex prediction workflow. This tutorial walks through the sample PIN1 system and shows you how to connect SAMSON to Cyana, load the tutorial document, and define the receptor, ligand, and binding-site inputs. NMR spectroscopy is particularly useful for studying protein-ligand interactions in solution. SAMSON's NMR2 integration, developed with [Prof. Dr. Julien Orts](https://pharmchem.univie.ac.at/research/staff-members-by-name/orts-julien/) from Vienna University, helps you move from that experimental information to a working structural model. ## What you will learn In this tutorial, you will learn how to set up NMR2 in SAMSON, load the sample data, and configure an NMR-guided protein-ligand complex prediction workflow. ## Before you start - Add [the NMR2 extension](https://www.samson-connect.net/extensions/6150c6f4-d891-b58b-a8b5-dbc197087841) to your account and restart SAMSON so it is installed locally. - Make sure you have access to **Cyana** before launching the extension. - Keep a local folder ready for NMR2 results, because each run creates its own project subfolder. Important The NMR2 extension requires an active license of **Cyana**, which is available from [L.A. Systems](https://www.las.jp/english/cyana.html). ## Open the tutorial document You can then import the **NMR2 Tutorial** document into SAMSON. To do this, click on **Home > Download**, paste the following identifier: (), and press Enter. This will directly import this shared document into SAMSON. Here is how the tutorial document looks like: The document contains: - **PIN1**: the protein structure - **Ligand**: the ligand structure - **Binding site**: a group containing 4 residues (`LEU 61`, `LEU 122`, `MET 130`, and `LEU 141`) ## Set up NMR2 To find the **NMR2** extension, type NMR2 into the **Find everything** box in the top part of SAMSON (shortcut: `Shift`+`E`): and press Enter. The NMR2 interface will appear: When you start NMR2 for the first time, you need to indicate the path to your **Cyana** executable. For this, click on the **Browse...** button in part **1 - Set Cyana executable path** and select the corresponding file on your computer. Then, select the folder in which all NMR2 jobs will be created by clicking the **Browse...** button in part **2 - Set results folder**. For each job, NMR2 will create a new subfolder which will indicate the time at which the job was started, as well as the names of the protein and the ligand. For example, a job folder could be named `2024.03.04-10h17m38s-PIN1-Ligand`. Note The NMR2 extension will save these settings, so you will not need to re-enter them the next time you start SAMSON. ## Set up the calculation parameters ### Structures To predict the structure of a protein-ligand complex, the NMR2 algorithm needs to know: - The protein structure - The ligand structure - The list of residues that may contain (or may be close to) methyls observed by NMR This can be easily defined using the **Document view**: and the **NMR2** interface: Precisely: 1. Click on the `PIN1` structure (with the blue icon) in the **Document view** to select it, then click on **Set** for the Receptor part in the **NMR2** interface. 1. Click on the **Ligand** structure in the **Document view** to select it, then click on **Set** for the Ligand part in the **NMR2** interface. Setting the ligand automatically renames its atoms and potentially adds **pseudo-atoms**. The atoms and pseudo-atoms names are the ones that should be used in the distance restraints (see below). 1. Click on the **Binding site** group in the **Document view**, then click on **Set** for the **Binding site** part in the **NMR2** interface. This group contains four residues of the protein among which (or close to which) we expect the unassigned methyls to be found. Note The group node is a saved selection which has been created to make it easy to reproduce this tutorial. In practice, you would select residues directly from the **Document view** or using the **Find command**. ### Distances Distance restraints (i.e., lower and upper bounds on distances between atoms or groups) are the most important set of parameters in NMR2. After deducing them for the NOESY peaks, you must enter them in the following format: ``` SITE_1 SITE_2 = LOWER_BOUND UPPER_BOUND ``` where a site can be a proton (e.g., `H1`, `H2`, etc.), a pseudo-atom (e.g., `Q`, `Q4`, etc.), or a methyl group (e.g., `M1`, `M2`, etc.), and lower and upper bounds are expressed in angstroms. For this tutorial, copy the list of distance restraints below and paste it in the **Distances** box of the **NMR2** interface: ``` Q4 M5 = 2.18 3.88 H8 M5 = 3.80 5.70 Q4 M1 = 3.73 6.64 H7 M3 = 4.42 6.62 H5 M2 = 2.36 3.54 Q M3 = 2.88 5.12 H7 M4 = 2.91 4.36 H7 M1 = 4.63 6.94 H5 M4 = 2.17 3.25 Q4 M4 = 2.81 4.99 H8 M4 = 3.92 5.88 H7 M5 = 3.56 5.34 Q4 M2 = 3.52 6.25 H8 M1 = 3.58 5.36 ``` Notice that the restraints involve five different methyls in the protein. ### Assigned methyls The NMR2 algorithm will automatically determine which combination of methyl assignments best satisfies the restraints. When numerous methyls are involved, though, this can lead to a combinatorial explosion of possibilities, which may take a long time to solve. When you have some information about specific methyls (for example thanks to other NMR experiments), you can enter this information to speed up the search. For this tutorial, enter the following assignment in the **Assigned methyls** box, to specify that we force methyl 5 to be pseudo-atom `QE` on residue 130: ``` M5 = 130 QE ``` ### Partial assignment In some cases, even though you may not have enough information to exactly assign a methyl, you may still make *partial assignments*. For example, you may still specify in the **Partial assignment** box that two methyls are on the same residue using the `same_res` keyword: ``` same_res = M1 M2 same_res = M3 M4 ``` or that a methyl belongs to certain residue types: ``` M1 = MET ILE ``` For this tutorial, just leave the **Partial assignment** box empty. ### Other options The NMR2 extension allows you to add several other options to control the search. For example, the protein is considered rigid by default. If you want to allow for a 20-degree tolerance in the side chain of residue 130 and a 10-degree tolerance in the side chain of residue 61, you can add the following line in the **Options** box: ``` SC = 130 20; 61 10 ``` If you want to give a 20-degree tolerance to all side chains considered in the binding site, simply enter: ``` SC = site 20 ``` If you want to allow for a tolerance in the backbone as well, enter similar lines with `BB` instead of `SC` (`BB` stands for backbone and `SC` - for side chain). For this tutorial, just leave the **Options** box empty. ## Starting calculations You can now click on the **Predict structures** button. **NMR2** will first regularize the protein structure, then will compute a series of structures with different methyl assignments to determine the combinations that best satisfy the distance restraints. For the structures and the parameters in this tutorial, the whole process should take a few minutes. Since the method is highly parallelizable (methyl combinations can be tested in parallel), **NMR2** detects how many cores are available, and uses all but one (to keep your computer responsive). When the method completes, a summary of the obtained structures will be displayed, with the best methyls assignments, the resulting value of the **Target function** (TF), which expresses how well distance restraints are satisfied (the lower, the better) and the **Van der Waals** (VDW) function, which indicates potential steric clashes (the lower, the better): The predicted structures are saved in the **output** subfolder of the job in the **PDB** format: You can then import these structures using **Home > File > Open...** or simply by dropping the files into SAMSON. For example, you can import the 10 predicted structures `1_pdb_7-5-2-6-1.pdb, 2_pdb_7-6-2-5-1.pdb, ...` at the same time: Then use the **Document view** to remove the **pseudo-atoms** that were added by **Cyana** for the calculations. Precisely, type `un` in the Filter to find these pseudo-atoms (they have **unknown** type), press **Enter** to select them, then press **Delete** to erase them: Then, select all structures and, in the context menu, align them using the alpha carbons: This will align all structures and will show the different predictions for the ligand positions: You can then hide and show these structures using the **Document view**, and use other extensions for analysis, simulation, etc. ## Related tutorials - [Protein preparation and validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) for preparing protein structures before prediction or analysis. - [Dock ligands and libraries with AutoDock Vina Extended](https://documentation.samson-connect.net/tutorials/adve/docking-libraries-of-ligands-with-autodock-vina-extended/index.md) for a docking-based protein-ligand workflow. - [GROMACS Wizard protein-ligand systems](https://documentation.samson-connect.net/tutorials/gromacs-wizard/protein-ligand-systems/index.md) for preparing a selected complex for simulation. ## Next step Compare the predicted ligand positions, then choose structures for interaction analysis, docking comparison, or simulation setup. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # Visualize center-of-mass motion with Pathlines Use the [Pathlines](https://www.samson-connect.net/extensions/d319e2f3-0afc-07ab-0b64-71eb19d7ee2f) visual model to display the center-of-mass (COM) trajectory of selected atoms along a path. This is ideal for visualizing ligand unbinding, macromolecular conformational changes, or tracking atomic motion across simulations. ## Why Use Pathlines? - Track motion of ligands, residues, or atom groups over a path. - Visualize center-of-mass displacement in complex systems. - Analyze unbinding, diffusion, or domain movement. ## What you will learn In this tutorial, you will learn how to visualize the center-of-mass motion of selected atoms along a path in SAMSON with the Pathlines visual model. ## Before you start 1. Log into [SAMSON Connect](https://www.samson-connect.net/). 1. Visit the [Pathlines](https://www.samson-connect.net/extensions/d319e2f3-0afc-07ab-0b64-71eb19d7ee2f) Extension page and click **Add**. 1. Restart SAMSON - your extension will be ready to use. 1. If you want to reproduce the example exactly, also keep the related [Ligand Path Finder tutorial](https://documentation.samson-connect.net/tutorials/ligand-path-finder/ligand-path-finder/index.md) available for context. ## Step 1 - Load the Sample System Load the sample system: 1. Click **Home > Download**. 1. Paste (). 1. Click **Download**. This will load a document with this tutorial's sample from [SAMSON Connect](https://www.samson-connect.net/). The sample document contains a structural model of *Lactose permease* (`1PV7`) with its ligand *Thiodigalactosid* (`TDG`) and the unbinding paths generated with [Ligand Path Finder](https://www.samson-connect.net/extensions/280cac50-31cd-e0ad-76c3-d254cd736967) (see the [Ligand Path Finder tutorial](https://documentation.samson-connect.net/tutorials/ligand-path-finder/ligand-path-finder/index.md)). In the **Document view** (1), you can see the protein under the name `Protein_chain_A`, the ligand under the name `TDG`, and two paths. 1. **Interface menu > Document view** or\ , : `Ctrl`+`1`,\ : `Cmd`+`1` ## Step 2 - Select Atoms and Paths To create pathlines, [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) in the **Document view** a group of atoms for which you want to visualize the motion of their center of mass and one or more paths (to select more than one node, hold the `Ctrl` / `Cmd` key). If no atoms are selected, the entire system is used. If no paths are selected, all paths in the document are used. ## Step 3 - Create a Pathline Visual Model To create a [visual model](https://documentation.samson-connect.net/users/latest/models/#visual-models): 1. Go to **Visualization > Visual model > More...** (shortcut: `Ctrl`/`Cmd` + `Shift`+`V`). 1. In the dialog, choose **Pathline of the center of mass** and click **OK**. This creates a visual pathline showing the COM motion of the selected atoms along the selected path(s). ## Step 4 - Explore and Customize - **Double-click** a path in the **Document view** to start/stop it. - **Right-click** a path to access **Path > ...** options in its context menu. - To access the path controllers, select the path and open the [Inspector](https://documentation.samson-connect.net/users/latest/inspecting/index.md) (`Ctrl`/`Cmd` + `2`). - Adjust the visual model properties (color, thickness) in the [Inspector](https://documentation.samson-connect.net/users/latest/inspecting/index.md) by [selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md) the pathline visual model. Note If you delete a path, the associated pathline will also be removed. Deleting atoms used for a pathline will modify the visualization. ## Use Cases - Display **ligand unbinding/rebinding routes**. - Analyze **collective domain motions** in protein complexes. - Visualize **center-of-mass movement** in reaction coordinate workflows. ## Next Steps Now that you know how to visualize paths, you might want to use the [P-NEB](https://www.samson-connect.net/extensions/4d3a7d66-0e60-b9d4-b84e-71f00595bfda) app to optimize them - see the tutorial on how to [optimize transition paths with the Parallel Nudged Elastic Band (P-NEB) method](https://documentation.samson-connect.net/tutorials/pneb/optimize-transition-paths-with-parallel-nudged-elastic-band/index.md). ## Related tutorials - [Ligand Path Finder](https://documentation.samson-connect.net/tutorials/ligand-path-finder/ligand-path-finder/index.md) for computing ligand unbinding paths. - [Protein Path Finder](https://documentation.samson-connect.net/tutorials/protein-path-finder/protein-path-finder/index.md) for computing protein transition paths. - [Export atom trajectories along paths](https://documentation.samson-connect.net/tutorials/export-along-path/export-atoms-trajectories-along-paths/index.md) for exporting path data. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # Optimize transition paths with the Parallel Nudged Elastic Band method Use the [P-NEB](https://www.samson-connect.net/extensions/4d3a7d66-0e60-b9d4-b84e-71f00595bfda) app in SAMSON when you already have a rough path or a set of conformations and want to relax that path into a more physically meaningful transition. The **Nudged Elastic Band** (NEB) method does this by optimizing intermediate images while keeping neighboring states evenly distributed with spring forces. The NEB method can be used, for example, to determine transition paths between already obtained structures corresponding to local energy minima (obtained using, e.g., the [FIRE minimizer](https://www.samson-connect.net/extensions/8ec255b0-7326-0bed-366e-40be71c1d160)). The [P-NEB](https://www.samson-connect.net/extensions/4d3a7d66-0e60-b9d4-b84e-71f00595bfda) app implements the climbing image nudged elastic band method [1](#fn:1). The P-NEB app can be applied to both a path and a set of conformations. Note **Conformations** are SAMSON nodes that store the positions of a selected group of atoms. Conformations can be created by selecting atoms and clicking **Edit > Conformation**. If atoms are moved, double-clicking on a conformation in the document view restores the saved positions. **Paths** are SAMSON nodes that store trajectories of a selected group of atoms. Paths are typically created by apps or loaded from trajectory files. Double-clicking on a path in the document view starts/stops moving atoms along the path. Note If you want to apply P-NEB to determine a path between two relaxed states of a given system, you first need to generate a sequence of conformations between them, for example with linear interpolation, or with other [SAMSON Extensions](https://www.samson-connect.net/extensions), e.g., [Ligand Path Finder](https://documentation.samson-connect.net/tutorials/ligand-path-finder/ligand-path-finder/index.md). ## What you will learn In this tutorial, you will learn how to optimize a transition path in SAMSON with the Parallel Nudged Elastic Band method. ## Before you start - Add the [P-NEB](https://www.samson-connect.net/extensions/4d3a7d66-0e60-b9d4-b84e-71f00595bfda) extension and the [FIRE](https://www.samson-connect.net/extensions/8ec255b0-7326-0bed-366e-40be71c1d160) state updater. - Bring in a sample path or a set of conformations before launching the app. - Use this tutorial when you already have a candidate path and want to improve it, not when you still need to generate the initial pathway itself. ## Requirements - [P-NEB](https://www.samson-connect.net/extensions/4d3a7d66-0e60-b9d4-b84e-71f00595bfda) Extension - [FIRE](https://www.samson-connect.net/extensions/8ec255b0-7326-0bed-366e-40be71c1d160) state updater ## Load the input model In SAMSON, go to **Home > Download** and insert one of the following sample documents: - () - an example of a Zinc ligand unbinding trajectory (a smaller system for tests). - () - a protein-ligand complex of *Lactose permease* (`1PV7`) and *Thiodigalactosid* (`TDG`) with unbinding paths obtained using the [Ligand Path Finder tutorial](https://documentation.samson-connect.net/tutorials/ligand-path-finder/ligand-path-finder/index.md). This will load a document with this tutorial's sample from [SAMSON Connect](https://www.samson-connect.net/). The goal of this tutorial is to improve these ligand unbinding pathways by applying P-NEB to them. ## Start the P-NEB app Open the **P-NEB** app via **Home > Apps > All > P-NEB** . You can also find it in the **Find everything...** search box. The P-NEB app has the following settings: - **Spring constant**: the spring coefficient. Enter 1.00. - **Number of loops**: the number of optimizations of the transition path. Enter 100. - **Interaction model**: the interaction model (force field) used to compute energies and forces. Select "Universal Force Field". - **Optimizer**: the algorithm used to optimize the transition path. Select "FIRE". - **Climbing image method**: if checked, the P-NEB app will use the climbing image strategy to find the saddle point. Leave this box unchecked for now. You can try again later with the box checked. - **Parallel execution**: if checked, the P-NEB app will run in parallel (one thread per conformation). Check this box. - **Suffix name**: the suffix used to name the final path or the set of generated conformations. Enter "NEB". As noted above, the P-NEB app can be applied to either paths or groups of conformations. ## Apply P-NEB to a path In the **Document view** (1), select a path node. 1. **Interface menu > Document view** or , : `Ctrl`+`1`, : `Cmd`+`1` Then, in the P-NEB app, click on the **Run** button. The **Universal Force Field (UFF)** setup will ask whether to use existing bonds - choose to use existing bonds and click OK. Then P-NEB initialization and computation will start. You can see the computation progress in the status bar: Once the optimization is complete, a new path will appear in the **Document view**: A summary of the computation is given in the interface of the P-NEB app: You may now select the new path in the document and examine it with the **Inspector** (1). You can also double-click the path to start and stop its animation. If you right-click on a path, you can also access some of its options via **Path > ...**. 1. **Interface menu > Inspector** or , : `Ctrl`+`3`, : `Cmd`+`3` ## Apply P-NEB to a set of conformations Note For the same system, applying P-NEB to a set of conformations will take longer than directly applying P-NEB to a path (consisting of the same steps). So, **prefer using a path**. You can **combine conformations into a path** by selecting them in the document and in the context menu clicking on **Conformation > Create path from conformations**. In the **Document view**, select a set of conformations. Then, click on the **Run** button in the P-NEB app. The **Universal Force Field (UFF)** setup will ask whether to use existing bonds - choose to use existing bonds and click OK. Once the optimization is done, a P-NEB produced set of conformations will appear in the **Document view**: You can double-click on these conformations to modify the corresponding atoms' positions in the document. ## Related tutorials - [Generate transition paths with ARAP Interpolation](https://documentation.samson-connect.net/tutorials/arap/arap-interpolation-for-protein-structures/index.md) for creating initial paths between protein conformations. - [Ligand Path Finder](https://documentation.samson-connect.net/tutorials/ligand-path-finder/ligand-path-finder/index.md) and [Protein Path Finder](https://documentation.samson-connect.net/tutorials/protein-path-finder/protein-path-finder/index.md) for generating paths that can be refined with P-NEB. - [Export atom trajectories along paths](https://documentation.samson-connect.net/tutorials/export-along-path/export-atoms-trajectories-along-paths/index.md) for exporting selected atoms along a path. ## Next step Inspect the optimized conformations, then export the path or continue with a simulation or free-energy workflow. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). ## References ______________________________________________________________________ 1. [G. Henkelman, B. P. Uberuaga, and H Jónsson. "A climbing image nudged elastic band method for finding saddle points and minimum energy paths." The Journal of Chemical Physics 113, 9901 (2000)](https://dx.doi.org/10.1063/1.1329672) [↩](#fnref:1 "Jump back to footnote 1 in the text") # Build Custom Polymers with Polymer Builder The [Polymer Builder](https://www.samson-connect.net/extensions/4593e178-6d31-49ba-f3bb-3a91215f7117) extension in SAMSON lets you build flexible, complex polymers using **custom monomers** or **sequences**. It's ideal for constructing synthetic chains, biopolymers, and custom molecular scaffolds for molecular design, simulation, or property prediction. By the end of the tutorial, you will know how to register monomers, define reusable sequences, and generate a polymer directly inside SAMSON. ## Why Use Polymer Builder? - Create linear or branched polymers using real chemical fragments. - Mix & match monomers and sequences. - Control bond types (single, double, triple). - Automatically detect connection atoms and avoid clashes. - Can be used for polymer design, coarse-grained modeling, etc. ## What you will learn In this tutorial, you will learn how to assemble custom polymers from monomers and sequences with Polymer Builder in SAMSON. ## Before you start 1. Log into [SAMSON Connect](https://www.samson-connect.net/). 1. Visit the [Polymer Builder](https://www.samson-connect.net/extensions/4593e178-6d31-49ba-f3bb-3a91215f7117) Extension page and click **Add**. 1. Restart SAMSON - your extension will be ready to use. 1. If you already have candidate monomer fragments, keep them in the document so you can register them directly from the selection. ## Step 1 - Launch the Polymer Builder App Find it in **Home > Apps > Assembly > Polymer Builder** or via the **Find everything...** (`Shift`+`E`) in the top menu of SAMSON. ## Step 2 - Register New Monomers 1. [Select](https://documentation.samson-connect.net/users/latest/selecting/index.md) a molecule (monomer unit) in the [Document view](https://documentation.samson-connect.net/users/latest/first-look/index.md) or [Viewport](https://documentation.samson-connect.net/users/latest/first-look/index.md). 1. Click **Register monomer from selection** to add a new monomer based on the current selection. - The tool automatically picks **start and end atoms** at opposite ends of the fragment. - You can override these using: - **S**: Set atom from current selection (first, select a single atom in the Document view or in the Viewport). - **P**: Pick atom from a list of atoms in the structure. - **V**: Highlight structure or atoms. Each monomer is automatically given a **unique letter** (`A`, `B`, `C`, ...). You can modify the already registered monomers right in the table and expand them if necessary. Note If the structure has a single residue or a structural group, then the monomer's name will be based on it, else you can provide the name if you would like this monomer to be placed in a separate structural group in the resulting polymer, i.e., having each monomer in a separate structural group. You can see in the table the molecular weight (in Daltons) and the distance between the start and the end atoms for each monomer. To **remove a monomer from the table**, right-click on it and click **Delete monomer** in the context menu. To **clear the whole table**, click **Clear all**. Note If the structure of the added monomer has been modified in SAMSON (e.g., an atom has been added or removed from it) then it will be deregistered from the list. ## Step 3 - Register Monomer Sequences If your polymer has repeating **sequence patterns**, you can also **register such patterns as sequences** of monomers: - Click **Add new sequence**. - Enter sequence using registered monomer IDs (e.g., `ABBA`). Click the associated **V** button to highlight the monomers used in the sequence. If the sequence is incorrect, then the error message will be shown in the **Status** property; otherwise, it will be shown as **Valid**: Each sequence is labeled automatically with unique identifiers (`S1`, `S2`, etc.). You can **specify the bond types between monomers**. By default, the monomers are connected with a single bond. Use `=` for **double bonds**, `#` for **triple bonds**. Examples: - `A=B` - `A` connected by a double bond with `B`. - `A#B` - `A` connected by a triple bond with `B`. If you would like the monomers in a sequence to be arranged into a common parent structural group in a generated polymer, then assign a name in the **Name** property. You can modify registered sequences of monomers (names and sequences) right in the table. The table also shows approximate molecular weights and lengths for each sequence of monomers. To remove a sequence from the table, right-click on it and click **Delete sequence**. To clear the whole table, click **Clear all**. ## Step 4 - Generate a Polymer Enter a custom sequence expression combining monomers and sequences: The sequence expression has the following format: `S1 + 2*S2 + 3*AB + AB=BA + A#B` where you can **provide identifiers for both monomers and sequences** of monomers, the number of repeats (e.g., `3*AB` – 3 repeats of `AB`, i.e., `ABABAB`), and the bond type ('`=`' for the double bond, '`#`' for the triple bond). Examples: `AB=BA` - `AB` connected by a double bond with `BA` `AB#BA` - `AB` connected by a triple bond with `BA` `2*AB` - 2 repeats of `AB`, i.e., `ABAB` `2*S1 + 2*S2` - 2 repeats of `S1` and 2 repeats of `S2` Predicted molecular weight and length will be shown below. Click **Generate polymer**. The app generates a polymer with a shape based on directions between the start and end atoms of each monomer. Excess hydrogens at connection sites are removed. ### Advanced Options - **Adjust Hydrogens on connection atoms** – Automatically adjust (add/remove) hydrogens for each connection atom (start and end atoms of monomers) based on valence. This is also done to adjust their positions. If you would like to adjust hydrogens later, you can use **Edit > Add hydrogens**. You can also add hydrogens manually using the **Add** editor (see [User Guide: Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md) for more information). - **Adjust for clashes** – Tries to avoid steric overlaps when connecting monomers (may cause slight curvature). Tip You can use a generated polymer as a new monomer to build **block copolymers** or extended chains. ## Minimize the Polymer Use SAMSON's built-in minimizer: **Edit > Minimize**. Click again to stop minimization. Note SAMSON uses the [Universal Force Field](https://www.samson-connect.net/extensions/8cbdc8b1-59e1-6459-d68f-b840275dd5e9) in its built-in minimizer. ## Saving and Loading Projects If you would like to save/export the resulting polymer, [select](https://documentation.samson-connect.net/users/latest/selecting/index.md) it and then click **Home > File > Save selection as...**. You can also **save the full project** to preserve monomer and sequence tables and load it later. ## Use Cases - Build synthetic or biopolymers for material property prediction. - Model conjugated polymers for electronic applications. - Generate drug-polymer conjugates or molecular brushes. - Use with simulation tools like GROMACS, LAMMPS, OpenMM, or SAMSON's own engines. ## Related tutorials - [Create molecular boxes with Molecular Box Builder](https://documentation.samson-connect.net/tutorials/molecular-box-builder/molecular-box-builder/index.md) for building larger molecular systems around generated molecules. - [GROMACS Wizard tutorials](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md) for preparing and simulating molecular systems. - [Generate crystal models](https://documentation.samson-connect.net/tutorials/crystal-creator/generating-crystal-models/index.md) for another materials and structure-building workflow. ## Next step Save the generated polymer or continue preparing it for simulation with the toolchain that matches your system. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # Protein Preparation & Validation Before you run docking, simulation, or any other molecular design workflow, make sure your protein model is valid. SAMSON gives you fast, reliable tools to **prepare, validate, and fix proteins** so you can focus on science, not file wrangling. ## What you will learn In this tutorial, you will learn how to clean, validate, and fix protein structures in SAMSON before docking, simulation, or other downstream workflows. ## Before you start - Use this page when you are preparing a protein for docking, simulation, or structure analysis. - If your system already looks clean, you can go straight to the quick preparation step. - If the structure has missing residues, missing atoms, or protonation issues, continue to the deeper-fix section later on this page. ## Why Preparation Matters A well-prepared and validated structure avoids bugs and boosts the accuracy of downstream protein-modeling tasks such as molecular dynamics, drug-design screening, and binding-energy calculations. - Remove alternate locations and molecules unnecessary for downstream tasks, e.g., solvent, cofactors, etc. - Add missing atoms - both heavy atoms and hydrogens. - Check geometry - avoid simulation crashes. ## One-Click Protein Preparation Use **Home > Prepare** to prepare your structure in a single step: - **Remove alternate locations** (keeps the highest-occupancy atoms). This will remove lower-occupancy atoms, or if atoms have the same occupancy or no occupancy specified, then it will leave atoms with the alternate location `A`, if present, else with `B`, and so on. - **Delete ligands** you don't need, including covalently attached ligands, co-factors and other small molecules. - **Strip water** molecules. - **Clear monatomic ions**. - **Add hydrogens** by residue type (for standard residues) or valence. More Control? Each option above can be run manually via **Home > Validate** or the **Select** menu. See details below in [Manual Checks and Fixes](#manual-checks-and-fixes). ### Batch preparation Want to prepare many PDB files or codes? Or want to just download many PDB files based on their PDB codes? Try the [Batch Protein Prepare](https://www.samson-connect.net/extensions/3f6ef072-517f-cdbe-ad3e-d8a33370d1ed) extension. It automatically downloads structures, if necessary, and applies the same cleaning steps you see in **Home > Prepare**. With [Batch Protein Prepare](https://www.samson-connect.net/extensions/3f6ef072-517f-cdbe-ad3e-d8a33370d1ed), you can: - Prepare structures in a folder (it will preserve the internal subfolder structure for the output). It supports the following formats as inputs: PDB, PDBx/mmCIF, MMTF, MOL2. - Download and prepare structures based on their PDB identifiers by supplying them as a string or as a list in a text file. It supports both old and extended PDB IDs. ## Manual Checks and Fixes ### Remove alternate locations 1. Open **Home > Validate** and go to *Alt. locations* tab. 1. Click **Find alternate locations** and review the list. 1. Press **Remove alt. locations** to keep only the highest-occupancy atoms. Tip You can also perform other checks for your system if necessary, e.g., check bond lengths, non-standard residues, and clashes. See details below in [Validate a protein system](#validate-a-protein-system). ### Strip Ligands, Water, or Ions 1. **Select > Biology > Ligands** (or **Water** / **Ions**). 1. In the pop-up context toolbar, click on delete () or in **Document view**, click **Current selection > Erase selection**. ### Add hydrogens - **Edit > Add hydrogens** adds standard hydrogens at pH 7 based on amino and nucleic acid types for standard residues and based on valences for the rest. - Select a sub-structure first to limit the scope. Protonation States Need pH-specific hydrogens? [Use PDBFixer (see below) to protonate at any pH](#fixing-deeper-problems-with-pdbfixer). Minimizing after adding hydrogens For some downstream tasks, you might need to minimize the system after adding hydrogens. But you don't necessarily always need to minimize the structure after adding hydrogens - for example, [AutoDock Vina](https://documentation.samson-connect.net/tutorials/adve/docking-libraries-of-ligands-with-autodock-vina-extended/index.md) needs only polar hydrogens for determining hydrogen bonds. ## Validate a protein system The **Structure Validation** module (**Home > Validate**) lets you inspect and repair specific issues: - **Alternate locations** - find & remove lower-occupancy atoms. - **Bond lengths** - find bonds outside expected ranges. - **Non-standard residues** - detect and relabel aliases. Note that when loading e.g., a PDB file, SAMSON tries to process the known aliases for non-standard residues and associates the proper residue types while keeping the non-standard residue names intact. - **Clashes and contacts** - highlight steric clashes. If you have clashes between side chains and want to fix them, you can use the [Rotamers editor](https://www.samson-connect.net/extensions/7cc74ea8-c24b-78fa-49a6-a75562902a12) to change the side chains based on the backbone-dependent rotamer library[1](#fn:1). - Tools to keep atom and node lists neat for simulations: - **Merge nodes**. - **Reorder atoms in a connected component**. - **Renumber atom serial numbers**. ## Fixing Deeper Problems with PDBFixer When a protein structure is missing residues or atoms, use the [PDBFixer](https://www.samson-connect.net/extensions/c81b69fc-4df0-fe09-146c-3591b20ba609) extension (powered by the [PDBFixer Python package](https://github.com/openmm/pdbfixer)[2](#fn:2),[3](#fn:3)). It can fix problems in proteins loaded in SAMSON, in PDB and mmCIF/PDBx files, and do it for a batch of files in a folder. It can do the following: - **Remove water and/or heterogens** (ligands, co-factors, ions). - **Add missing residues** based on SEQRES records (build missing loops). - **Convert non-standard residues** to their standard equivalents. - **Add missing heavy atoms** and side chains. - **Add hydrogens for specified pH**. - **Resolve alternate locations automatically** leaving only atoms with higher occupancy. - **Build explicit-solvent water boxes** neutralized with specified ions. - **Build lipid membranes** (from a list of available lipids) around membrane proteins with water and neutralized with specified ions. ## Related tutorials - [Dock ligands and libraries with AutoDock Vina Extended](https://documentation.samson-connect.net/tutorials/adve/docking-libraries-of-ligands-with-autodock-vina-extended/index.md) for protein-ligand docking after preparation. - [Protein-ligand systems with GROMACS Wizard](https://documentation.samson-connect.net/tutorials/gromacs-wizard/protein-ligand-systems/index.md) for preparing complexes for molecular dynamics. - [Interactive Ramachandran Plot](https://documentation.samson-connect.net/tutorials/ramachandran/ramachandran-plot/index.md) for inspecting protein backbone conformations. ## Next step Continue with the docking, molecular dynamics, or validation workflow that motivated the protein cleanup. ## References ______________________________________________________________________ 1. Shapovalov, M.S., and Dunbrack, R.L., Jr. (2011). A smoothed backbone-dependent rotamer library for proteins derived from adaptive kernel density estimates and regressions. Structure, 19, 844-858.  [↩](#fnref:1 "Jump back to footnote 1 in the text") 1. PDBFixer Python package.  [↩](#fnref:2 "Jump back to footnote 2 in the text") 1. Eastman P. et al. (2017). OpenMM 7: Rapid development of high performance algorithms for molecular dynamics. PLOS Computational Biology, 13(7), e1005659.  [↩](#fnref:3 "Jump back to footnote 3 in the text") # Align protein sequences and structures in SAMSON Use SAMSON's [Protein Aligner](https://www.samson-connect.net/extensions/0bee42d5-181b-b366-39a5-36607f0b5731) to compare protein sequences, inspect conserved residues, and superimpose structures in one workflow. This tutorial uses two hemoglobins as an example, but the same steps apply to your own proteins. ## What you will learn In this tutorial, you will learn how to align protein sequences and superimpose structures in SAMSON with the Protein Aligner extension. ## Before you start - Protein Aligner is included with SAMSON plans and is available through **Home > Align** . - Fetch or open the proteins you want to compare before you start the alignment workflow. - If the structures still contain extra solvent or ligands, clean them first with [Protein Preparation & Validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md). Watch a quick demo: ## Video tutorial You can learn how to use the **Protein Aligner** from the following extract of the SAMSON 2025 webinar: ## Why Align Proteins? - Identify conserved residues that drive function or ligand binding. - Compare conformations across species or mutants. - Assist in building accurate homology models for downstream molecular design workflows. ## Load example proteins We'll align two hemoglobins from different organisms: `1DLW` and `1RTX`. - Open **Home > Fetch**. - Input `1DLW 1RTX` in **PDB** or **PDB (mmCIF)**. - Click the corresponding **Load** button. Clean Up the System First? Use **Home > Prepare** to strip water, ligands, or alternate locations. See the [Protein Preparation & Validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) guide for details. ## Launch Protein Aligner Click **Home > Align** to open the **Protein Aligner**. ## Sequence Alignment You can align sequences in two modes: - **Align sequences (by structure)** - aligns one model to another (per structural model). - **Align sequences (by chain)** - aligns individual chains (there can be multiple chains per model); useful for oligomers. Click either **Align sequences** button to generate the alignment: To see if the corresponding amino acids have the same properties, you can toggle **amino acid property options** via **Highlight residues**. For example, on the image below, we can see the comparison of two sequences based on the similarity (shows the conserved residues) and polarity of amino acid residues: Note If a residue matches multiple selected properties, its color blends the corresponding shades, as can be seen from the image above. ## Interacting with the Alignment - Hover over a residue in the sequences to see its name and ID and highlight it in the viewport: - Click on a residue - selects that residue and its aligned partners. - Hold `Shift` to select multiple consecutive residues. - Hold `Ctrl`/`Cmd` to select non-consecutive residues. - Hold `Alt` to remove from the selection. To clear the selection, click anywhere in the viewport or press `Ctrl`/`Cmd` + `D`. Tip Selecting a residue in the **Document view** or in the **viewport** automatically highlights it - and all aligned residues - in the Protein Aligner. ## Aligning structures Whole-Protein Superposition: - Make sure no residues are selected. - Click **Align to this** on the first model's row. The button on the other model now reports the RMSD (e.g., 3.27 Å): Your proteins are now superimposed: Visual Aids If you do not have secondary structures shown, you can add them via **Visualization > Visual model > Ribbons**. Create separate ribbon models per protein to color them differently. For that, select a structure first and then apply a visual model. This should help to differentiate the aligned structures. Toggle atomistic views via checkboxes in **Document view**. ### Region-Specific Alignment Sometimes only part of the protein is of interest. You can also **align based only on the selected part of the structure**. From the picture above, we can see that the two pink alpha-helices in the beginning of the protein sequence look very similar but are not well aligned. To align those two parts in particular, go back to **Protein Aligner** and select the first 20 residues in both sequences: Click the alignment button next to the selection (e.g., the 0.0 Å button) to superimpose *only* those residues. ## Next Steps - Export the alignment for homology modeling. - Map conserved residues onto ligand-binding sites for molecular design projects. - Repeat with additional chains or related proteins. ## Related tutorials - [Predict Biomolecular Structures](https://documentation.samson-connect.net/tutorials/bsp/bsp/index.md) for generating structures that can be compared with known proteins. - [Protein preparation and validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) for cleaning structures before comparison or modeling. - [Symmetry detection in biological assemblies](https://documentation.samson-connect.net/tutorials/symmetry/computing-axes-of-symmetry-of-biological-assemblies/index.md) for analyzing repeated protein assemblies. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # Protein Path Finder Use the [Protein Path Finder](https://www.samson-connect.net/extensions/b6f693c9-2c71-7573-abdd-8d288a35383f) app to search for possible transition paths between two conformations of the same protein and review the resulting motion in SAMSON. The **Protein Path Finder** uses the **ART-RRT** method, which combines **T-RRT** for pathway search and **ARAP** for motion generation [1](#fn:1). During the search, constrained minimization is used to keep the motions physically reasonable. ## What you will learn In this tutorial, you will learn how to set up Protein Path Finder, choose start and goal conformations, and compute transition paths between them. ## Before you start - Add [Protein Path Finder](https://www.samson-connect.net/extensions/b6f693c9-2c71-7573-abdd-8d288a35383f). - Add the [FIRE](https://www.samson-connect.net/extensions/8ec255b0-7326-0bed-366e-40be71c1d160) state updater. - Use the sample document first if you are new to this workflow. ## Requirements - [Protein Path Finder](https://www.samson-connect.net/extensions/b6f693c9-2c71-7573-abdd-8d288a35383f) app - [FIRE](https://www.samson-connect.net/extensions/8ec255b0-7326-0bed-366e-40be71c1d160) state updater ## Load the input model In SAMSON, go to **Home > Download** and insert () - this will load a document with this tutorial's sample from [SAMSON Connect](https://www.samson-connect.net/). In the **Document view** (1), you should see a structural model of *Adenylate Kinase*, chain `A`, with two conformations corresponding to `4AKE` and `1AKE` structures: *start* and *goal*. Our aim is to find a path between the *start* and *goal* conformations. 1. **Interface menu > Document view** or , : `Ctrl`+`1`, : `Cmd`+`1` ### Prepare the system For your own model, you might need to first prepare it using **Home > Prepare**: - remove alternate locations - remove ligands, solvent, and ions. - add hydrogens. If your system has missing residues or heavy atoms (e.g., missing atoms in side chains), you can also use the [PDBFixer](https://www.samson-connect.net/extensions/c81b69fc-4df0-fe09-146c-3591b20ba609) extension to **fix a protein**. This extension can also be used to add hydrogens for specific pH. See also Please refer to the [Protein Preparation & Validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) tutorial for more information on how to prepare and fix protein systems. If you have conformations for your system in two different files, then you will need to first prepare and, optionally, fix each system. Please note that two systems need to have the same structure, i.e., chains, residues, and atoms. Then you will need to concatenate them in a single PDB file as different models, i.e.: ``` MODEL 1 ... ENDMDL MODEL 2 ... ENDMDL END ``` Note The system in the tutorial file has already been prepared and combined in a single SAMSON document. ## Launch the Protein Path Finder app Open the **Protein Path Finder** app via **Home > Apps > Biology** or find it via **Find everything...**. In the app's window, you will see two tabs: the **Settings** tab is for setting up the search parameters and the **Results** tab is for collecting the results. ## Setup energy evaluation Note The system needs to be already minimized. You can [minimize the system](https://documentation.samson-connect.net/users/latest/minimizing/index.md) using **Edit > Minimize** which uses Universal Force Field (UFF). First, in the **Settings** tab, we need to specify an interaction model and a state updater which will be used in the computations. For the **Interaction model** select **Universal Force Field** (UFF) in the drop-down list, and for the **State updater** select **FIRE**. If you do not see the **FIRE** state updater, please check the [requirements](#requirements) section and make sure you installed it from [SAMSON Connect](https://www.samson-connect.net/). A window will pop up asking if you want to apply a new model; click **Yes**. The **Universal Force Field (UFF)** setup will then ask whether to use existing bonds - choose to use existing bonds and click OK. Two windows should appear: the **Universal Force Field** properties window showing its parameters and UFF energies of the current state of the system and the **FIRE Properties** window showing the state updater parameters. Set the parameters for FIRE as in the picture below (the step size to 1 fs and the number of steps to 1). ## Setup the system Let's now set up the system. Expand the **Set up the system** box. ### Set the start and goal conformations Let's choose the start and goal conformations. Click **Get conformations from the active document** to obtain all the conformations present in the active document. Then, select the **start** conformation in the **Start conformation** list and the **goal** conformation in the **Goal conformation** list as shown below. These two conformations will be used to seed the search process. ### Define the active ARAP atoms Now we need to specify which protein atoms will be considered by the ARAP method as **active atoms**, i.e., atoms that control the protein motion. The other atoms will be passive: their motion will follow active atoms according to the ARAP method. Let's choose two alpha-Carbon (`CA`) atoms from backbones of the residue **GLY 12** and the residue **ARG 123**. For simplicity, the document has a group named `CA in GLY 12 and CA in ARG 123` that refers to these atoms. In the **Document view**, double-click on this group, this action will select nodes in the group. Tip We selected these atoms using the following [Node Specification Language](https://documentation.samson-connect.net/users/latest/nsl/index.md) expression: `("CA" in "GLY 12") or ("CA" in "ARG 123")`. See also [User guide - Selecting](https://documentation.samson-connect.net/users/latest/selecting/index.md). Then, in the App, click the **Add** button to set the active ARAP atoms. In the **Advanced information** box, you should see the number of added active ARAP atoms. You can see which atoms were chosen as active ARAP atoms by clicking the **Select** buttons. If you are not satisfied with the active ARAP atoms assignment, you can reset your choices by clicking the **Reset** () button. During the setup of the system, a new visual model should appear in the document to show the sampling box and atom types (green for active ARAP atoms). ## Define the sampling box Let's now define the sampling box for the active ARAP atoms. Expand the **Set the sampling box for the active ARAP atoms** box. The sampling box defines the sampling region for the chosen active ARAP atoms. The size and position of the box biases their motion and therefore the resulting pathways. The App starts with a sampling box size which encloses all protein atoms in both start and goal conformations. Let's set the sampling box to be a cube of 200 angstroms along each dimension (see picture below). A green box visualizes the sampling box. ## Define the search parameters Let's now define the search parameters. Expand the **Set parameters** box and set them as in the following figure: - **Use seed**: use the specified seed number for the planner and after each run the seed value is incremented by 1. If the box is unchecked, a random seed is used. The specified seed number is needed if you want to reproduce the results later for the same seed. - **Runs** = 2, we run the method 2 times to extract a maximum of 2 paths. - **ARAP-modeling iterations** = 20: the number of iterations for the ARAP method. - **Minimization iterations** = 20: we apply 20 steps of constrained minimization with FIRE each time a new state is generated in order to minimize it. - **Initial temperature (T)** = 0.001 K, **Temperature factor** = 2, **Failures before increase of T** = 1: the parameters for the T-RRT sampling algorithm. - **RRT extension step size** = 1 A: the extension step size for the sampling algorithm. - **Use alignment strategy**: if this box is checked, each accepted state of the protein during the search will be aligned with the start conformation. This strategy tends to make the search faster, but in rare cases it produces some artifacts. - **Max. elapsed time per run**: each run is stopped as soon as the elapsed time reaches this value. ## Run the planner Once you set up the system, the sampling box, and the search parameters, you can launch the search for transition pathways. Click the **Run** button to start computing paths. The search process can be paused by clicking the **Pause** button and resumed with the **Resume** button (these buttons are located at the same place as the **Run** button while the planner is running). To stop the process, click the **Stop** button. During the search, in the **Advanced information** box under the **Planning information**, you can observe the elapsed time for the current run (**Current running time**), the elapsed time for all of the runs (**Total running time**), the number of tree nodes in the current run (**Nodes**), the run number (**Run**), and the number of paths found (**Paths found**). ## Results As soon as a path is found, it is added to a list in the **Results** tab. For example, the following figure shows two paths found. Each path contains the following fields: - **id**: the path id - **# states**: the number of conformations in the path. - **MinE (kcal/mol)**: the minimum energy of the path conformations. - **MaxE (kcal/mol)**: the maximum energy of the path conformations. - **Saddle (kcal/mol)**: the difference between **MaxE** and **MinE**. - **Barrier (kcal/mol)**: the difference between **MaxE** and **First**. - **Time (s)**: time elapsed for searching this path. - **First (kcal/mol)**: the energy of the first conformation in the path. - **Last (kcal/mol)**: the energy of the last conformation in the path. - **Remarks**: comments on the path (editable). - **Color**: the color of the energy curve for this path. ### View conformation energies along the path To view the energy curve of the path, select a path by clicking on it in the path table. To plot several energy curves, select several paths (`Ctrl`/`Cmd` + left-click for multi-selection). After selecting a path, you can move the slider to see a particular conformation in the path as shown in the picture below. The corresponding conformation is shown in the viewport and its corresponding energy is shown in the **Universal Force Field** window. ### Export the results: paths, conformations, path table content You can copy the content of the path table to the clipboard by selecting the paths for which you want to export data and pressing `Ctrl`/`Cmd` + `C` or right-clicking and then selecting **Copy table content**. You can also copy path energy values along the selected paths via right-clicking and selecting **Copy path energy**. To export paths from the path table into the document as trajectories, select the paths you are interested in and press the **Export paths** button. To export conformations along the path into the document, select the paths from the path table, choose the export interval and click the **Export** button. Tip You can double-click on a path in the document to start/stop it. To access the path controllers, select the path and open the **Inspector** (1). If you right-click on a path, you can also access some of its options via **Path > ...**. 1. **Interface > Inspector**, , : `Ctrl`+`2`, : `Cmd`+`2` ## Next steps ### Create pathlines Check the [Pathlines tutorial](https://documentation.samson-connect.net/tutorials/pathlines/pathlines/index.md) to learn about how to create pathlines to visualize the movement of the center of mass of a molecule. ### Improve paths with P-NEB The resulting paths can be significantly improved with the help of the parallel Nudged Elastic Band (NEB) method implemented in the [P-NEB app](https://www.samson-connect.net/extensions/4d3a7d66-0e60-b9d4-b84e-71f00595bfda). Please check out the [P-NEB tutorial on exploring transition paths](https://documentation.samson-connect.net/tutorials/pneb/optimize-transition-paths-with-parallel-nudged-elastic-band/index.md) for more information. ### Export atom trajectories along paths The resulting paths can be saved in .sam or .samx formats. If you want to export only trajectories of some atoms along the path, you can use the [Export Along Paths app](https://www.samson-connect.net/extensions/cc339322-498f-28e6-90b6-5e656cc345c3). Please refer to the [tutorial on how to use the Export Along Paths app](https://documentation.samson-connect.net/tutorials/export-along-path/export-atoms-trajectories-along-paths/index.md) for more details. ## Related tutorials - [Generate transition paths with ARAP Interpolation](https://documentation.samson-connect.net/tutorials/arap/arap-interpolation-for-protein-structures/index.md) for another route to protein conformational paths. - [Optimize transition paths with P-NEB](https://documentation.samson-connect.net/tutorials/pneb/optimize-transition-paths-with-parallel-nudged-elastic-band/index.md) for refining paths. - [Pathlines](https://documentation.samson-connect.net/tutorials/pathlines/pathlines/index.md) for visualizing path motion. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). ## References ______________________________________________________________________ 1. [Nguyen MK, Jaillet L, Redon S. ART-RRT: As-Rigid-As-Possible search for protein conformational transition paths. J Comput Aided Mol Des. 2019 Aug;33(8):705-727. doi: 10.1007/s10822-019-00216-w. Epub 2019 Aug 21. PMID: 31435895.](https://doi.org/10.1007/s10822-019-00216-w) [↩](#fnref:1 "Jump back to footnote 1 in the text") # Inspect protein backbone conformations with the Ramachandran Plot Use the [Interactive Ramachandran Plot](https://www.samson-connect.net/extensions/dc71fbbe-4289-759b-2369-9ebb29e3c3fb) SAMSON Extension to **explore and edit protein backbone conformations using φ (phi) and ψ (psi) dihedral angles**. This powerful tool lets you validate, select, and manipulate residues directly from the plot - you can use it in your protein-modeling workflows, e.g., for structure refinement. ## What Is a Ramachandran Plot? A Ramachandran plot shows the **energetically allowed regions for backbone dihedral angles** (ψ vs. φ) in amino acid residues. It highlights favored and disallowed conformations based on steric and energetic constraints. ## What you will learn In this tutorial, you will learn how to inspect and edit protein backbone conformations with the Interactive Ramachandran Plot in SAMSON. ## Before you start 1. Log into [SAMSON Connect](https://www.samson-connect.net/). 1. Visit the [Interactive Ramachandran Plot](https://www.samson-connect.net/extensions/dc71fbbe-4289-759b-2369-9ebb29e3c3fb) Extension page and click **Add**. 1. Restart SAMSON - your extension will be ready to use. 1. Open a protein structure in SAMSON so you can update the plot immediately after launching the app. ## Visualizing a Protein ### Load a Structure Open any protein of your choice - this tutorial uses PDB ID `1YRF`: - Open **Home > Fetch**. - Input `1YRF` in **PDB** or **PDB (mmCIF)**. - Click the corresponding **Load** button. ### Open the Ramachandran Plot App Open the Ramachandran Plot app via **Home > Apps > Biology >** **Ramachandran plot** . Click **Update** to generate the Ramachandran plot: - **Yellow areas** - energetically favorable regions. - **White areas** - energetically unfavorable conformations. Here, all the residues are well placed. Tabs let you filter residues by category: - **All** - **General** - **Glycine** - **Proline** - **Pre-proline** - residues that are just before a proline in the amino acid chain ### Explore Individual Residues Click on a dot (e.g., a proline residue): To visualize one particular residue, let's click on it directly on the plot (here with the proline): - The residue is selected in the viewport. - The status bar shows dihedral angles (φ and ψ values): ## Interactive Editing ### Option 1: Drag in the Plot - Drag a point on the plot to update dihedral angles in real time. - The 3D structure updates instantly. - Press `Ctrl`/`Cmd` + `Z` to undo, e.g., if you're not satisfied with the result. ### Option 2: Use the Twister Editor 1. Select the **Twister editor** from the left-hand menu in the viewport. 1. Twist the protein in 3D space and observe the plot update live: ## Bonus Challenge - Fixing with Normal Modes 1. Reload `1YRF`. 1. Compute the first 10 **nonlinear normal modes** (see [Calculating nonlinear normal modes](https://documentation.samson-connect.net/tutorials/nma/calculating-non-linear-normal-modes/index.md) tutorial). 1. Set the scaling factor to 1 and shift the first mode fully left: 1. Use the **Ramachandran plot** to tweak conformations so all residues fall in favored regions. This is a powerful exercise to combine global motion and local conformation optimization - valuable for simulation and molecular design readiness. ## Applications in Protein Modeling - Detect strained residues before simulation. - Refine homology models by editing outliers. - Understand conformational flexibility in active or binding sites. ## Related tutorials - [Protein preparation and validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) for preparing protein structures before modeling. - [Compute normal modes that open a binding site](https://documentation.samson-connect.net/tutorials/nma/calculating-non-linear-normal-modes/index.md) for a related protein-conformation workflow. ## Next step Continue with [Protein preparation and validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) if your goal is to clean and validate a protein before docking or simulation. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # Explore the SARS-CoV-2 spike opening motion This page is a guided scientific walkthrough rather than a button-by-button app tutorial. It introduces the SARS-CoV-2 spike, shows the computed opening motion from the closed to the receptor-binding state, and summarizes how the example trajectory was generated in SAMSON. Use it if you want to: - understand what the spike opening motion represents - explore the downloadable trajectory files - see which SAMSON modules were used to compute the example path ## What you will learn In this tutorial, you will learn how the SARS-CoV-2 spike opens, explore the computed motion, and review the workflow used to generate the example trajectory. ## Before you start - You can read this page on its own; no extension is required just to follow the explanation. - If you want to inspect the downloadable trajectory in SAMSON, keep a recent SAMSON installation ready. - If you want to reproduce the workflow later, the relevant modules are listed in [Accessing the modules](#accessing-the-modules). ## Why the spike opening motion matters The SARS coronavirus 2 (SARS-CoV-2) – the virus that causes the COVID-19 disease – has transmembrane spikes (S proteins on the image below) attached to its lipid membrane. It is because of these spikes - their relatively large number - that this type of virus is called a coronavirus. The coronavirus uses its spikes to recognize a host cell, then attach to it and infect it with its viral RNA, which encodes the virus instructions. This strategy is used by many viruses, including other coronaviruses, influenza viruses, and HIV. Once the viral RNA is inside the host cell, the host cell starts to produce copies of the virus based on the instructions stored in the viral RNA thus leading to virus propagation. The SARS-CoV-2 spike is considered one of the main targets of antibodies [1](#fn:1). An illustrated visualization of the SARS-CoV-2. Image credits: CDC/Alissa Eckert. Let's see how the spike looks from the side and top views. *The side view of the spike ([Source: PDB 6VXX](https://www.rcsb.org/structure/6vxx)): the spike is represented via its Gaussian surface (left) and via its secondary structure (right), the molecules around are sugars. The bottom part of the spike would be attached to the virus capsid. Click on an image to open its full-size version in a new window.* *The top view of the spike ([Source: PDB 6VXX](https://www.rcsb.org/structure/6vxx)): the spike is represented via its Gaussian surface (left) and via its secondary structure (right), the molecules around are sugars. The bottom part of the spike would be attached to the virus capsid. Click on an image to open its full-size version in a new window.* The spike consists of glycoproteins and promotes entry into human cells by binding to a receptor molecule (see the following section). As you can see, the spike is covered with other small molecules - these are sugar molecules. Many viruses use sugars to defend themselves from the host immune system because many of our own cells are coated with sugars as well. That disguise helps the virus avoid immune recognition. The SARS-CoV-2 spike cannot fully cover the receptor-binding region with sugars because that upper region still needs to recognize and bind the host receptor. This leaves the top part of the spike exposed and makes it a major target for neutralizing antibodies. The spike of the SARS-CoV-2 is formed by three copies of the S protein which form the C3 symmetry. You can see them in the image below colored in three colors. The top view of the spike in the closed state. Different colors designate proteins in the spike. Small molecules around the spike are sugars. ## The receptor-binding domain of the SARS-CoV-2 The SARS-CoV-2 spike promotes entry into human cells by binding to a receptor molecule – an enzyme called Angiotensin-Converting Enzyme 2 (ACE2) [1](#fn:1), [2](#fn:2), [3](#fn:3). The secondary structure representation of the ACE2 molecule. The ACE2 molecule is a natural protein present on the surface of some of our cells. It is present in epithelial cells of the **lungs** (in the airways and alveoli) and the intestine, and in endothelial cells of the heart and the kidneys. The ACE2 molecule is vital to our body because it is, for example, used together with the ACE molecule to regulate blood pressure by converting angiotensin molecules. The coronavirus which caused the SARS outbreak in 2002 also binds to the same ACE2 molecule. But researchers have found that "the SARS-CoV-2 spikes were 10 to 20 times more likely to bind ACE2 on human cells than the spike from the SARS virus from 2002. This may enable SARS-CoV-2 to spread more easily from person to person than the earlier virus" [4](#fn:4). One part of the SARS-CoV-2 spike protein, positioned on the top of the spike, recognizes and grabs a receptor molecule (i.e., ACE2) on the host cell membrane and another part fuses to the host cell membrane [3](#fn:3). Only one out of the three spike proteins binds to the ACE2 receptor molecule at a time. The images below show the receptor-binding domain of the SARS-CoV-2 spike in its open state bound with the human ACE2 ([Source: PDB 6VW1](https://www.rcsb.org/structure/6VW1)). The secondary structure representation of the receptor-binding domain of the SARS-CoV-2 spike (blue) complexed with its receptor human ACE2 (white). As you can see, the receptor-binding site of the SARS-CoV-2 spike tries to "complete" the receptor molecule, ACE2. This can be better seen from a movie below: ## The SARS-CoV-2 spike in motion Let's see how the SARS-CoV-2 spike operates in motion. The movies below show how the spike goes from the closed state (the down state) to the open state (the up state). The open state is the state that can recognize the ACE2 molecule, leading the virus particle to fuse with a human cell. The side view of the spike. The view of the spike from another angle. The top view of the spike. You can download the computed trajectory in different formats below (in zipped archives): - [a set of PDB trajectory files](https://documentation.samson-connect.net/wp-content/uploads/6VYB_open_close_trajectory_files.zip); - [a single PDB file with the trajectory](https://documentation.samson-connect.net/wp-content/uploads/6VYB_open_close_trajectory.zip); - [a SAMSON format file](https://documentation.samson-connect.net/wp-content/uploads/6VYB_open_close_trajectory_sam.zip). *The SAMSON file integrates the structure of the spike, the open and closed conformations (double-click to restore them) as well as the path computed by the ARAP module and the path post-processed by the P-NEB module (double-click to start and stop animation).* Please note that these trajectories are provided *as is*. They have not been experimentally verified, but could serve as an illustration of the spike motion, and might be useful in further calculations. They might have to be post-processed and/or further validated before being used. All images, animations, structures and trajectories provided here are being released under the open [CC BY 4.0 license](https://creativecommons.org/licenses/by/4.0/). Please email [contact@oneangstrom.com](mailto:contact@oneangstrom.com) for more information. ## How this motion was computed To determine this motion in SAMSON, we took two known states of the spike [1](#fn:1): - closed state: PDB [6VXX](https://www.rcsb.org/structure/6vxx); - open state: PDB [6VYB](https://www.rcsb.org/structure/6vyb). These two structures differ in the number of residues, which made the pipeline more complex. Thus, we performed the following pipeline: 1. For both structures, 6VXX and 6VYB, we modified the bond orders in sugars using [a python script](https://documentation.samson-connect.net/wp-content/uploads/set_bond_order_for_NAG.zip) and the [Python scripting module](https://www.samson-connect.net/extensions/7b654ce6-e38c-b97f-6746-4fd6934487c2). It is necessary for the next step consisting of adding hydrogens. For residues, SAMSON sets bond orders when importing. 1. For both structures, 6VXX and 6VYB, we added hydrogens and performed some minimization steps. 1. We used the [ARAP Interpolation Path module](https://www.samson-connect.net/extensions/d550a902-3427-8788-ddd7-14d6c0e2c140) to generate an interpolated path between these two states: as the starting conformation, we set the open state (6VYB) and as the goal conformation, we set the closed state (6VXX). The generation of this path took less than half a minute on a laptop. The [ARAP Interpolation Path module](https://www.samson-connect.net/extensions/d550a902-3427-8788-ddd7-14d6c0e2c140) produces the path for the structure of the starting conformation. 1. Because the closed state (6VXX) and the open state (6VYB) differ in the number of residues, we took a conformation for the closed state from the path obtained with the [ARAP Interpolation Path module](https://www.samson-connect.net/extensions/d550a902-3427-8788-ddd7-14d6c0e2c140) since the path corresponds to the structure from the open state conformation and minimized it. 1. We did step 3 but with this newly obtained closed state conformation as the goal conformation. 1. We used the [P-NEB (Parallel Nudged Elastic Band) module](https://www.samson-connect.net/extensions/4d3a7d66-0e60-b9d4-b84e-71f00595bfda) to improve the path obtained in step 4. The P-NEB step took about 15 minutes on a laptop. ## Accessing the modules We are making the [ARAP Interpolation Path module](https://www.samson-connect.net/extensions/d550a902-3427-8788-ddd7-14d6c0e2c140) and the [P-NEB module](https://www.samson-connect.net/extensions/4d3a7d66-0e60-b9d4-b84e-71f00595bfda) free for everyone during the outbreak. To use them, sign up on [SAMSON Connect](https://www.samson-connect.net/signUp.html) (it's free), download and install SAMSON (it's free as well), and click the Add button on the modules pages. Many other modules are [free as well](https://www.samson-connect.net/extensions). If you would like to have *free access to paid modules* in your research against SARS-CoV-2 / COVID-19, please contact us at [contact@oneangstrom.com](mailto:contact@oneangstrom.com). ## Related tutorials - [Generate transition paths with ARAP Interpolation](https://documentation.samson-connect.net/tutorials/arap/arap-interpolation-for-protein-structures/index.md) for creating transition paths between protein conformations. - [Optimize transition paths with P-NEB](https://documentation.samson-connect.net/tutorials/pneb/optimize-transition-paths-with-parallel-nudged-elastic-band/index.md) for refining paths. - [Compute normal modes that open a binding site](https://documentation.samson-connect.net/tutorials/nma/calculating-non-linear-normal-modes/index.md) for another protein-motion workflow. ## Next step Use the ARAP Interpolation or P-NEB tutorials when you want to reproduce a similar path workflow on your own protein system. ## References ______________________________________________________________________ 1. Structure, function and antigenicity of the SARS-CoV-2 spike glycoprotein. Walls AC, Park YJ, Tortorici MA, Wall A, McGuire AT, Veesler D. Cell (2020), doi:  [↩](#fnref:1 "Jump back to footnote 1 in the text")[↩](#fnref2:1 "Jump back to footnote 1 in the text")[↩](#fnref3:1 "Jump back to footnote 1 in the text") 1. Zhou P, Yang XL, Wang XG, Hu B, Zhang L, Zhang W, et al. (March 2020). "A pneumonia outbreak associated with a new coronavirus of probable bat origin". Nature. 579 (7798): 270–273. doi:  [↩](#fnref:2 "Jump back to footnote 2 in the text") 1. Lewis R (2020-02-20). "COVID-19 Vaccine Will Close in on the Spikes". DNA Science Blog. Public Library of Science.  [↩](#fnref:3 "Jump back to footnote 3 in the text")[↩](#fnref2:3 "Jump back to footnote 3 in the text") 1. Novel coronavirus structure reveals targets for vaccines and treatments,  [↩](#fnref:4 "Jump back to footnote 4 in the text") # Making nano-batarangs (and more) Have you ever thought about how you could create Batman's batarang at the nanoscale? Maybe it will not fight cancer or viruses, but it is a memorable way to learn how scripted atom selection and atom editing work in SAMSON. In this tutorial, we introduce two tools that can be used to create nano-batarangs and other complex-shaped atomic objects by selecting atoms and modifying their properties with mathematical expressions and a scripting language. ## What you will learn In this tutorial, you will learn how to use simple scripting in SAMSON to select atoms, modify them, and build custom nanoscale shapes. ## Before you start - Add the [Simple Script](https://samson-connect.net/extensions/ff77d9b8-bdc7-3587-c2b0-68f8447f1d27) Extension. - Follow the examples in order the first time, because later examples build on the earlier syntax. - Use this tutorial as a practical introduction rather than a full language reference. ## Simple Script Extension The [Simple Script](https://samson-connect.net/extensions/ff77d9b8-bdc7-3587-c2b0-68f8447f1d27) Extension allows you to modify some properties of atoms (positions, visibility, element type, *etc*) in the active document according to a script provided by you. To do so, predefined variables, mathematical and logical expressions can be used in the script. Below is a description of the app's functionality. ## I. Variables Variables are defined as in the [SAMSON Node Specification Language (NSL)](https://documentation.samson-connect.net/users/latest/nsl/index.md), but only for atoms. The difference between this Extension's scripting language and the NSL is that all characters (*i.e.*, names and symbols for elements) should be used within single quotation marks, *e.g.*: `'Carbon'`, `'Fe'`. Below is a list of variables that are possible to use in the script. ### Node attributes - `n.selectionFlag` (short name `n.sf`) - `true`/`1` if node is selected, `false`/`0` if node is not selected ### Atom attributes - `a.x`, `a.y`, \`a.z - atom's positions - `a.visibilityFlag` (short name `a.vf`) - `true`/`1` if atom is visible, `false`/`0` if atom is invisible - `a.aminoAcidBackbone` (short name `a.aabb`) - `true`/`1` if atom belongs to an amino acid backbone - `a.aromatic` (short name `a.ar`) - `true`/`1` if atom is aromatic - `a.chainID` (short name `a.ci`) - index of a chain to which atoms belong to (`a.ci==0` matches atoms from chain ID 0) - `a.formalCharge` (short name `a.fc`) - atom's formal charge - `a.nucleicAcidBackbone` (short name `a.nabb`) - `true`/`1` if atom belongs to a nucleic acid backbone - `a.occupancy` (short name `a.oc`) - atom's occupancy - `a.partialCharge` (short name `a.pc`) - atom's partial charge - `a.residueSequenceNumber` (short name `a.resi`) - index of a residue to which atom belongs to (`a.resi==12` matches atoms in residue 12) - `a.resonance` (short name `a.reso`) - `true`/`1` if atom is resonant - `a.serialNumber` (short name `a.sn`) - atom's serial number (`a.sn>=500` matches atoms with serial number larger than 500) - `a.temperatureFactor` (short name `a.tf`) - atom's temperature factor - `a.water` (short name `a.w`) - `true`/`1` if atom belongs to water molecule - `a.element` (short name `a.e`) - element name of atom (`a.e=='Carbon'` matches carbon atoms) - `a.symbol` (short name `a.s`) - element symbol of atom (`a.s=='H'` matches hydrogen atoms) - `a.elementID` (short name `a.ei`) - element index of atom in the periodic table - `a.vdwr` - van der Waals radius of atom It is possible to change only the following properties of atoms: `n.selectionFlag`, `a.x`, `a.y`, `a.z`, `a.visibilityFlag`, `a.chainID`, `a.formalCharge`, `a.occupancy`, `a.partialCharge`, `a.serialNumber`, `a.temperatureFactor`, `a.elementID`. ## II. Capabilities: operators, functions, structures It is possible to use standard mathematical operators and functions, and C-like structures and statements. 1. Basic operators: `+, -, *, /, %, ^` 1. Assignment: `:=, +=, -=, *=, /=, %=` 1. Equalities and inequalities: `\=, ==, <>, !=, <, <=, >, >=` 1. Logic operators: `and, mand, mor, nand, nor, not, or, shl, shr, xnor, xor, true, false` 1. Functions: `abs, avg, ceil, clamp, equal, erf, erfc, exp, expm1, floor, frac, log, log10, log1p, log2, logn, max, min, mul, ncdf, nequal, root, round, roundn, sgn, sqrt, sum, swap, trunc` 1. Trigonometry: `acos, acosh, asin, asinh, atan, atanh, atan2, cos, cosh, cot, csc, sec, sin, sinc, sinh, tan, tanh, hypot, rad2deg, deg2grad, deg2rad, grad2deg` 1. Control structures: if-then-else, ternary conditional, switch-case, return-statement 1. Loop statements: while, for, repeat-until, break, continue 1. Comments: ``` # this is a comment // another comment /* this is also a comment */ ``` Parsing and evaluation of expressions are done thanks to the C++ Mathematical Expression Parsing And Evaluation Library ['exprtk'](https://github.com/ArashPartow/exprtk) by Arash Partow. See the list of possible operators, structures, and other capabilities here: [exprtk](https://github.com/ArashPartow/exprtk) by Arash Partow. Note: all variable and function names are case-insensitive. ## III. Examples In this section, a brief introduction to the scripting language is given in several examples. 1. Set z-coordinate equal to `sin(a.x * π / 12)` for all atoms in the active document: ``` a.z:=sin(a.x * pi / 12); ``` 1. Shift all atoms with type 2 in y-direction by 5.25 (in the selected length units): ``` if (a.elementID==2) a.y+=5.25; ``` or the same expression using short names: ``` if (a.ei==2) a.y+=5.25; ``` 1. Select all atoms with x and y coordinates greater than 0: ``` if (a.x > 0 and a.y > 0) n.selectionFlag:=1; else n.selectionFlag:=0; ``` or the same using ternary conditional statement: ``` ( (a.x > 0) and (a.y > 0) ) ? n.sf:=1 : n.sf:=0; ``` 1. Select all Carbon and Hydrogen atoms: ``` if (a.element=='Carbon' or a.symbol=='H') n.selectionFlag:=1; else n.selectionFlag:=0; ``` 1. Show only atoms inside a sphere with radius 10 and center in (0, 0, 2) (in the selected length units): ``` if ((a.x^2 + a.y^2 + (a.z - 2)^2) < 100) a.visibilityFlag:=1; else a.visibilityFlag:=0; ``` 1. Change elementID of atoms from 1 to 2 (works only with a.elementID): ``` if (a.elementID==1) a.elementID:=2; ``` 1. Shift atoms with elementID equal to 1 and with x-coordinate `|x|>10` by 5 in the y-direction (in the selected length units): ``` if (a.ei==1 and abs(a.x) > 10) a.y+=5; ``` 1. Rotate all atoms about the x-axis by an angle `θ=π/4`: ``` var theta:=pi/4; # create variable, the same as: theta:=deg2rad(45); var y_old:=a.y; var z_old:=a.z; a.y:=y_old * cos(theta) - z_old * sin(theta); a.z:=y_old * sin(theta) + z_old * cos(theta); ``` 1. Switch operator: ``` switch { case a.x < -1 : a.y += 1.5; case a.x > 1 : a.y -= 1.5; default : a.y:=a.y; }; ``` 1. Modify z-coordinate for atoms with `|x|>10` and highlight them: ``` if ( abs(a.x) > 10 ) { n.sf := 1; a.z := sin( a.x * pi / 12); } else { n.sf:=0; }; ``` 1. Example on nested for-loops: ``` for (var i:=0; i < 4; i+=1) { a.y -= 1; if (a.y < 0) continue; for (var j := 0; j < 4; j += 1) { a.z += 2; if (a.z > 10) break; }; }; ``` 1. This scripting language can be used for complex selection of atoms in the active document. For example, one can cut nano-tiles from graphene: 1. And, finally, one can create Batman's nano-batarang out of graphene. Script for creating the nano-batarang out of graphene sheet placed in the z-plane: ``` /* Batman's sign */ var x:=a.x / 2; // positions should be at least in nanometers var y:=a.y / 2; var iambatman:=false; if ( (abs(x)>3 and y>=0) or (abs(x)>4 and y<0)){ // wings, ellipsoidal sides if( (x/7)^2+(y/3)^2 < 1 ) iambatman:=true; } else if (abs(x)<=4 and y<0) { // central bottom part if (y >= (abs(x/2) - (3*sqrt(33)-7)*x^2/112 - 3) + sqrt(1-(abs(abs(x)-2)-1)^2) ) iambatman:=true; } else if (abs(x)<=1 and abs(x)>0.75 and y>=0) { // sides of the head if (y <= 9 - 8*abs(x) ) iambatman:=true; } else if (abs(x)<=0.75 and abs(x)>0.5 and y>=0) { // pointy ears if (y <= 3*abs(x) + 0.75 ) iambatman:=true; } else if (abs(x)<=0.5 and y>=0) { // top of the head if (y <= 2.25) iambatman:=true; } else if (abs(x)<=3 and abs(x)>1 and y>=0) { // from head to wings if (y <= 6*sqrt(10)/7 + (1.5-0.5*abs(x)) - 6*sqrt(10)/14*sqrt(4-(abs(x)-1)^2)) iambatman:=true; }; if (iambatman) { // set selectionFlag and visibilityFlag to 1 if atom is selected n.sf:=1; a.vf:=1; } else { // set selectionFlag and visibilityFlag to 0 if atom is not selected n.sf:=0; a.vf:=0; }; ``` 1. Let's now use switch instead of multiple if-statements to create a graphene batarang from Nolan's trilogy. Script for creating the nano-batarang out of graphene sheet placed in the z-plane: ``` /* Batarang from Nolan's trilogy */ var x:=a.x / 2; // positions should be at least in nanometers var y:=a.y / 2; var iambatman:=false; if (y >= 0 and y <= 3) { switch { // wings, top case (abs(x)>4 and abs(x)<10) : if( ((abs(x)-14)/4)^2+((y+2)/3)^2 > 4 ) { iambatman:=true; }; // from head to wings case (abs(x)>1 and abs(x)<=4) : if( ((abs(x)-1)/1.75)^2+(y-3)^2 > 3 ) { iambatman:=true; }; // sides of the head case (abs(x)<=1 and abs(x)>0.75) : if( y <= 9 - 8*abs(x) ) { iambatman:=true; }; // pointy ears case (abs(x)<=0.75 and abs(x)>0.5) : if( y <= 3*abs(x) + 0.75 ) { iambatman:=true; }; // top of the head case abs(x)<=0.5 : if( y <= 2.25 ) { iambatman:=true; }; default : iambatman:=false; }; } else if (y < 0 and y > -3.5){ switch { case (abs(x)<=6) : if( ((abs(x)-8)/4)^2+((y+3.5)/1.5)^2>4 ) { iambatman:=true; }; case (abs(x)<=10 and abs(x)>6) : if( ((abs(x)-14)/4)^2+((y+2)/3)^2>4 and y>-0.5 ) { iambatman:=true; }; default : iambatman:=false; }; } if (iambatman) { // set selectionFlag and visibilityFlag to 1 if atom is selected n.sf:=1; a.vf:=1; } else { // set selectionFlag and visibilityFlag to 0 if atom is not selected n.sf:=0; a.vf:=0; }; ``` ## Atoms Selector Extension If you want to just select atoms using a mathematical expression, the [Atoms Selector](https://www.samson-connect.net/extensions/ac55f6bc-25e3-10cf-ed0a-bb1cdbf1044b) Extension might be of help. The same variables, operators and functions as in the [Simple Script](https://samson-connect.net/extensions/ff77d9b8-bdc7-3587-c2b0-68f8447f1d27) Extension can be used. In [Atoms Selector](https://samson-connect.net/extensions/ac55f6bc-25e3-10cf-ed0a-bb1cdbf1044b) Extension, you only need to provide an expression according to which you want atoms in the active document to be selected. An additional keyword can be used: - `all` - select all atoms in the active document. For example, to cut a cylinder with radius 10Å out of quartz crystal (given known positions of the crystal): ``` ((a.x-15)^2 + (a.y-15)^2) < 100 ``` Please let us know in the comments below what you'd like to see in SAMSON or if you have any questions. And, to paraphrase Bruce Wayne, an App developer can be anyone! You can [develop your own Apps](https://documentation.samson-connect.net/users/latest/extending-samson/#develop-a-samson-extension) for your needs in SAMSON thanks to the powerful [SAMSON SDK](https://documentation.samson-connect.net/developers/latest/getting-started/#what-is-samson-sdk). ## Related tutorials - [Python Scripting Guide](https://documentation.samson-connect.net/scripting/latest/index.html) for automating SAMSON with Python. - [Developing SAMSON Extensions](https://documentation.samson-connect.net/developing-samson-extensions/index.md) when you want to build reusable functionality beyond simple scripts. - [Generate crystal models](https://documentation.samson-connect.net/tutorials/crystal-creator/generating-crystal-models/index.md) for source structures that can be modified with selection expressions. ## Next step Use Simple Script on your own structure, or move to the Python Scripting Guide when you need a more programmable workflow. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # Generate analogue series with positional analogue scanning Use positional analogue scanning in the [SMILES Manager](https://www.samson-connect.net/extensions/ce09650a-c071-4e84-1f6a-b8706937d5c1) to generate analogue series directly in SAMSON from a starting molecule and a SMARTS pattern. This workflow is useful when you want to quickly explore substitutions, compare analogue properties, or prepare structures for docking and interaction analysis. The feature was inspired by Pat Walters' [blog post](https://practicalcheminformatics.blogspot.com/2020/04/positional-analogue-scanning.html) and the cited [paper](https://pubs.acs.org/doi/10.1021/acs.jmedchem.9b02092) from Lewis Pennington, Ingo Muegge, and coworkers. In this tutorial, we use the same example molecule from that paper: `CN1C=C(C(=O)Nc2ccc(-c3ccccc3)c(c2)C(F)(F)F)C(=O)c2ccccc12`. ## What you will learn In this tutorial, you will learn how to generate analogue series in SAMSON with positional analogue scanning in the SMILES Manager. ## Before you start - Add the [SMILES Manager](https://www.samson-connect.net/extensions/ce09650a-c071-4e84-1f6a-b8706937d5c1) extension. - Open the extension and switch to the **Positional Analogue Scanning** tab before following the steps below. - Use the companion [SMILES Manager tutorial](https://documentation.samson-connect.net/tutorials/smiles-manager/using-the-rdkit-smiles-manager/index.md) if you first need help importing or organizing SMILES data. ## Start from a single molecule Let's begin by defining our starting molecule. You can do that in two different ways: either you enter the SMILES code of your molecule of interest or you select it in the SAMSON document and you press the **Use selection** button like in the gif below. ## Define your searched pattern Search the initial structure for the pattern you want to replace or to which you want to attach a new atom or group. In our example, we will use aromatic carbon as a pattern by entering the SMARTS code `[cH]` in the corresponding field. As shown in the following gif, we can see that the found pattern in the initial molecule was highlighted a number of times. ## Replace or attach Now that we specified the pattern we want to scan, we choose the first option in order to replace it with a nitrogen atom (N). If you like, you can choose to attach to your pattern a fluorine atom (F) or a methyl group (CH3). Then we only have to click **Run** to generate the analogs and display them in the results section of the interface. As you can see, it was quite fast to generate the SMILES codes and the 2D depiction of the analogs. ## Modify your results In the results table you can do many actions: - Modify the generated analogs: change the name or the SMILES code of the analogue of your choice by double-clicking on the corresponding cell in the results table. - Open the 2D depiction image: double-click on the 2D depiction image to open it in a larger window. You can also do that by right-clicking on the image and clicking **Open** in the context menu. - Hide/show the analogs' images in the results table: click on the **2D** cell of the table's header to hide or show the 2D images in the results table. - Generate a 3D structure of a specific analogue: right-click on the image of your analogue of interest and choose generate a 3D structure in the opened context menu. - Remove only selected results: select the lines of the analogs you want to remove from the results table and click the **Remove selected results** button. - Clear results table content: click on the **Clear results** button to remove all the generated analogs from the table. ## Generate 3D structures of your analogs and study them Finally, let's generate the 3D structures of our generated analogs by clicking on the **Convert to 3D** button. Now, you can proceed in the study of your molecules, for example, by performing a docking of the generated analogs using the [Autodock Vina Extended](https://www.samson-connect.net/extensions/1afc50e6-3567-fa25-1e09-415ebf4d05d7) extension. You can then examine which changes preserve key interactions with your target protein and which ones make new interactions. ## Related tutorials - [Using the RDKit - SMILES Manager](https://documentation.samson-connect.net/tutorials/smiles-manager/using-the-rdkit-smiles-manager/index.md) for broader SMILES import, management, and fragment replacement workflows. - [Dock ligands and libraries with AutoDock Vina Extended](https://documentation.samson-connect.net/tutorials/adve/docking-libraries-of-ligands-with-autodock-vina-extended/index.md) for docking generated analogs. - [Strain Explorer](https://documentation.samson-connect.net/tutorials/strain-explorer/strain-explorer/index.md) for analyzing ligand strain in generated structures. ## Next step Convert promising analogs to 3D structures, then dock, filter, or analyze them with the workflow that matches your design goal. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # Manage and transform SMILES data with the SMILES Manager Use the [SMILES Manager](https://www.samson-connect.net/extensions/ce09650a-c071-4e84-1f6a-b8706937d5c1) in SAMSON to import SMILES datasets, review 2D depictions, edit entries, and create 3D-ready structures. The extension is based on [RDKit](https://www.rdkit.org/docs/index.html), a widely used open-source cheminformatics toolkit. This tutorial covers the **Manage SMILES** and **Replace fragments** tabs. For the third tab, see the separate [Positional Analogue Scanning tutorial](https://documentation.samson-connect.net/tutorials/smiles-manager/perform-positional-analogue-scanning-using-the-smiles-manager-element/index.md). In each section, the SMILES codes are displayed in a table together with names and generated 2D depictions, so you can move quickly from string manipulation to structure generation. ## What you will learn In this tutorial, you will learn how to import, manage, and transform SMILES data in SAMSON with the RDKit-based SMILES Manager. ## Before you start - Add the [SMILES Manager](https://www.samson-connect.net/extensions/ce09650a-c071-4e84-1f6a-b8706937d5c1) extension from [SAMSON Connect - Marketplace](https://www.samson-connect.net/extensions). - Prepare one or more SMILES strings, or a `.smi` / `.txt` file, if you want to follow along with your own data. - Use this page when you want to organize or edit a SMILES collection; use the companion tutorial when you want to generate analogue series. ## Manage SMILES strings ### Import SMILES Import data by clicking **Open** in the **File** menu. The extension accepts the most common text-based SMILES inputs: - RDKit-style `.smi` files with the SMILES string in the first column and the molecule name in the second column - `.txt` files that contain one SMILES string per line - RDKit `.smi` files with extra attributes, which are ignored during import The standard `.smi` layout is shown below. ``` SMILES Name COc1cc(CNS(=O)(=O)CCCCC=CC(C)C)ccc1O Mol1 COc1cc(CNC(CCCCC=CC(C)C)C(F)(F)F)ccc1O Mol2 COc1cc(CNC2CC2CCCCC=CC(C)C)ccc1O Mol3 COc1cc(CC=C(F)CCCCC=CC(C)C)ccc1O Mol4 COc1cc(CNC2OCC2CCCCC=CC(C)C)ccc1O Mol5 COc1cc(COC2OCC2CCCCC=CC(C)C)ccc1O Mol6 ``` If your RDKit SMILES file contains additional attributes, the extension still imports it, but only the SMILES code and molecule identifier are used. `SMILES Attribute Name CC 2 Mol1 C=C 5 Mol2 [CH+2]C[CH+2] 100 Mol3` Plain-text `.txt` files containing only SMILES strings can also be imported. ``` COc1cc(CNC(=O)CCCC/C=C/C(C)C)ccc1O COc1cc(CNS(=O)(=O)CCCCC=CC(C)C)ccc1O COc1cc(CNC(CCCCC=CC(C)C)C(F)(F)F)ccc1O COc1cc(CNC2CC2CCCCC=CC(C)C)ccc1O ``` ### Adding, modifying, and removing SMILES You can manually add SMILES strings with the *Add line* action from the **Edit** menu or with the **Add** button below the table. In the same way, you can remove individual entries or clear the table entirely. To edit an entry, modify the corresponding **Code** cell directly. Also, a name can be assigned to each SMILES string. If no name has been assigned, the name will be the same as its SMILES code. ### Generating, opening, updating, and saving 2D depictions Using RDKit functions, 2D depictions of the SMILES strings are generated on the fly. When a SMILES string is invalid, the corresponding line is highlighted and an error image is attributed instead of the 2D depiction. You can open a large view of the 2D depiction by either double-clicking on the 2D depiction or by right-clicking on the image and choosing the **Open** action in the context menu. At any time, the 2D depictions presented in the table can be hidden by clicking on the **Hide 2D image** action of the **View** drop-down menu or by clicking on the 2D header cell of the table. Note that even when 2D depictions are hidden it is possible to open them using the aforementioned ways. You can create several open windows to compare several molecules or navigate through all of them in a single window using the navigation buttons. For large molecules, it is possible to zoom in or out of the images. Note that when the SMILES code of a molecule is modified the corresponding image is automatically updated (the same for the molecule's name as well). Finally, you can save the 2D depiction as a single PNG or SVG image either from the right-click context menu or from the large view window. ### Grid images of 2D depictions It is also possible to save the 2D depictions in a grid in an SVG file by clicking on the **Save as grid image** action of the **File** drop-down menu. You can also save only the selected 2D depictions by choosing the **Save selection as grid image** action. A popup window will appear where you will be able to set the parameters of the grid (number of columns, size of a single panel, and whether the molecule's name should be displayed or not). ### Generating 3D structures The main feature of this SAMSON module is to generate 3D structures from SMILES codes. After selecting molecules in the table, you can click on the **Selected SMILES string to Document** action in the **Export** drop-down menu. The 3D structures of the selected molecules with their corresponding names will be added to the active document. The generation of the 3D structure can also be done for a single SMILES string either by clicking on the **Generate 3D structure** action in the right-click context menu or by clicking on the **Generate 3D structure** button in the large view window. ### Substructure search One interesting feature that I have improved in this new version is the substructure search. It is now possible to do a more advanced search using a given combination of patterns. For example, let us generate only the molecules that have a fluorine atom and a nitrogen atom separated in space. For that, in the **Search** bar enter `F` for fluorine then press **Select visible**. This will select SMILES strings having a fluorine atom (two SMILES strings in the animation below). Then we clear the search bar. Note that our selection remains unchanged (in the animation below, two SMILES strings are still selected). Now we enter `N` for nitrogen and we can see in the result of our search that only one selected SMILES string is present (the other one does not have nitrogen). So we press the **Unselect hidden** button in order to unselect the molecule that is not displayed and keep only the ones presenting the nitrogen atom. Note that by default, in RDKit, information about stereochemistry is not used in substructure searches but this can be changed by enabling the chirality. ## Replace fragments The **Replace fragments** tab allows for quick and easy generation of thousands of different molecules by replacing a specified fragment of the initial molecule with various fragments. This feature provides isosteric replacement and can be useful for quickly generating a library of slightly different molecules to test their properties. Note that each table is presented in the same way as the SMILES table in the **Manage SMILES** tab with the same buttons. One difference is the saving of the table as a grid or as a file which is present as buttons at the bottom right of each table. Let's try to generate a library of fragments for a molecule: 1. First, we need to specify one or several initial molecules in which we would like to replace a fragment. You can import initial molecules from a file by clicking **Open initial molecules** in the **File** drop-down menu, add them manually, import from a SAMSON Document by clicking **SAMSON Selection as initial molecule** in the **Import** drop-down menu. In this tutorial, we will use the following initial molecule (load it from a file or add it manually): `COc1cc(CNC(=O)CCCC/C=C/C(C)C)ccc1O` 1. Enter the fragment that you want to be replaced in the initial molecules either by entering it manually or by importing it from the active SAMSON Document by going to the **SAMSON Selection as replaced fragment** action in the **Import** drop-down menu. In this tutorial, the target fragment to replace is: `[*:1]C(=O)NC[*:2]` 1. Provide one or more "Replaced with fragments" (fragments with which you want to make a replacement) by importing from a file (click **Open fragments to replace with...** in the **File** drop-down menu) or by adding them manually. In this tutorial, we will be using the following fragments: ``` [*:1]S(=O)(=O)NC[*:2] [*:1]C(C(F)(F)(F))NC[*:2] [*:1]C1CC1NC[*:2] [*:1]C(F)=CC[*:2] [*:1]C1COC1NC[*:2] [*:1]C1COC1OC[*:2] [*:1]C1=NN=C([*:2])N1 [*:1]C1=NN=C([*:2])O1 [*:1]N1N=NC([*:2])=C1 [*:1]N1N=NC([*:2])=N1 [*:1]C1=NOC([*:2])=N1 ``` 1. In the **Run** drop-down menu, click on the **Replace fragments**. 1. Results of the replacements are stored in the **Results** table. You can view them in the active document - check out the **Export** drop-down menu. Note that in RDKit the fragments must have the following syntax: `[*:1]C(=O)NC[*:2]` with `[*:1]` and `[*:2]` at the two extremities of the pattern. The resulting molecules can then be converted into 3D structures, modified, or saved in a file or a grid image. That's all for this tutorial about the SMILES Manager module of SAMSON. You can check out the [Positional Analogue Scanning using the SMILES Manager Extension tutorial](https://documentation.samson-connect.net/tutorials/smiles-manager/perform-positional-analogue-scanning-using-the-smiles-manager-element/index.md). ## Related tutorials - [Generate analogue series with positional analogue scanning](https://documentation.samson-connect.net/tutorials/smiles-manager/perform-positional-analogue-scanning-using-the-smiles-manager-element/index.md) for a focused analogue-generation workflow. - [Dock ligands and libraries with AutoDock Vina Extended](https://documentation.samson-connect.net/tutorials/adve/docking-libraries-of-ligands-with-autodock-vina-extended/index.md) for docking generated or imported molecules. - [Strain Explorer](https://documentation.samson-connect.net/tutorials/strain-explorer/strain-explorer/index.md) for analyzing generated ligand conformations. ## Next step Use the SMILES Manager results to generate 3D structures, build analogue series, or prepare molecules for docking and analysis. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # Explore ligand strain with Strain Explorer in SAMSON Use [**Strain Explorer**](https://www.samson-connect.net/extensions/e8137d0a-cefc-2e12-d436-97f831c0d4ad) to analyze how much a ligand relaxes from its starting conformation, compare **local** and **global** strain estimates, inspect a **2D strain map**, and export results for reporting or further work in SAMSON. Strain Explorer is designed for ligand libraries stored in **SDF** files. It keeps the imported ligands in memory, computes strain values with either **UFF** or **UMA** backends, and displays the results in a sortable table with 2D depictions, SMILES, SDF properties, strain values, RMSDs, and status messages. ## What Strain Explorer does Strain Explorer can help you: - load one or many ligands from an SDF file; - compute **local strain** from the imported pose; - compute **global strain** using a torsional search over rotatable bonds; - compare ligands in a table with sorting and quick filtering; - visualize a ligand-specific strain map in a side panel; - send selected ligands to the SAMSON document as aligned conformations; - export selected or all ligands to **SDF**; - export a ligand report to **PDF**. ## What you will learn In this tutorial, you will learn how to load ligands in Strain Explorer, compute local and global strain, inspect the strain map, and export results to SAMSON, SDF, and PDF. ## Before you start - Add the **Strain Explorer** SAMSON Extension. - Make sure the required computation backend is available: - **UFF** for the default workflow. See [Universal Force Field](https://documentation.samson-connect.net/tutorials/uff/uff/index.md). - **UMA** if you want to use the UMA backend and have it installed. See [UMA Force Field](https://documentation.samson-connect.net/tutorials/uma-force-field/uma-force-field/index.md). - Prepare an **SDF** file containing one or more ligands. Input requirements Strain Explorer supports **V2000** and **V3000** SDF files and preserves the SDF properties as table columns. Each ligand must contain a **SMILES** property. Strain Explorer uses it for the 2D depiction and the strain panel. If a ligand is missing SMILES, loading is aborted. Use 3D coordinates when possible Strain is computed from the **imported coordinates**. In practice, **3D ligand conformations** are the most meaningful input. If you import flat 2D coordinates, the computed strain mostly reflects how far that drawing is from a relaxed 3D geometry. ## Open the app and load an SDF file Open **Strain Explorer** from **Home > Apps > Biology** or by using **Find everything...**. Then: 1. Click **Browse...** and select your SDF file. 1. Click **Load SDF**. After loading: - the ligands appear in the results table; - the table includes the ligand name, SMILES, 2D depiction, computed metrics, status, and all imported SDF properties; - the **Quick filter** lets you search across all visible columns; - the ligands are **not** added to the SAMSON document yet. ## Understand the two strain calculations Strain Explorer reports how much the ligand energy decreases when the imported conformation is relaxed. - **Local strain** = `E(initial) - E(local minimum)` - **Global strain** = `E(initial) - E(global minimum estimate)` Higher strain usually means the starting conformation stores more conformational tension and relaxes more strongly during optimization. ### Local strain The **local** calculation starts from the imported ligand coordinates and runs a local minimization with the selected force field. You can adjust: - **Max steps** - **Plateau steps** - **Energy diff threshold** The minimization stops when one of these conditions is met: - the maximum number of steps is reached; - the energy change remains below the chosen threshold for enough consecutive steps. This is useful when you want to know whether the imported ligand is already close to a nearby minimum. ### Global strain The **global** calculation tries to find a lower-energy conformer that may not be reachable by a purely local relaxation. Strain Explorer does this in several stages: 1. It detects **rotatable single bonds**. 1. It builds an articulated rigid-body model of the ligand. 1. It samples torsion angles using either: - **Exhaustive** search, or - **Monte Carlo** search. 1. It keeps the lowest-energy sampled conformers. 1. It can optionally **refine the best sampled conformer with a local minimization**. Important The global result is a **global minimum estimate**, not a mathematical guarantee of the absolute global minimum. The quality of the estimate depends on the search mode and the chosen sampling settings. If a ligand has **no rotatable bonds**, the global stage becomes trivial and optional refinement is usually all that remains. ### Exhaustive vs Monte Carlo Use **Exhaustive** when the ligand has only a limited number of rotatable bonds and you want systematic sampling. Use **Monte Carlo** when the ligand is more flexible and exhaustive sampling would become too expensive. The main global settings are: - **Exhaustive angles per bond**: how finely each torsion is discretized; - **Exhaustive max evaluations**: safety cap on the total number of scored conformers; - **Monte Carlo attempts**: number of random torsional samples; - **Monte Carlo seed**: fixed seed for reproducible random sampling; - **Top samples kept**: number of low-energy candidates retained during the search; - **Refine best global sample with local minimization**: performs a final local relaxation of the best sampled pose. ## Run the computation Once your ligands are loaded: 1. Select **Compute local strain**, **Compute global strain**, or both. 1. Open **Settings** if you want to change the force field or the local/global parameters. 1. Click **Compute strains**. During the run: - the progress bar reports the current ligand and stage; - **Cancel** stops the run cooperatively; - errors on one ligand do not necessarily stop the whole batch; - each ligand receives its own status such as **Completed**, **Completed with warnings**, **Cancelled**, or **Error**. ## Read the results table After the run, the table becomes the main comparison view. The most important columns are: - **E initial (kcal/mol)**: force-field energy of the imported conformation; - **Local strain (kcal/mol)**: energy released by local minimization; - **Local RMSD (A)**: structural change after local minimization, after rigid alignment; - **Global strain (kcal/mol)**: energy released relative to the best global conformer found; - **Global RMSD (A)**: structural change after the global stage, after rigid alignment; - **Status**: summary of success, warnings, or failure for that ligand. You can: - sort numerically by strain or RMSD; - filter by ligand name, SMILES, status, or any SDF property; - select one or more rows for visualization or export. How to interpret local vs global strain - If **local strain** and **global strain** are both small, the imported conformation is already close to a relaxed state. - If **global strain** is much larger than **local strain**, the ligand likely has a lower-energy torsional arrangement outside the local basin. - If **local strain** is already large and **global strain** is similar, the ligand may simply need local relaxation rather than a fundamentally different torsional state. ## Use the strain panel When you select a row, the right-hand panel shows a ligand summary with: - a 2D depiction generated from the ligand SMILES; - local and global strain bars; - a ranked list of the most displaced atoms; - a color overlay on the 2D depiction. What the strain map represents The current strain map is a **displacement-based visualization**. It highlights how much atoms move between the original conformation and the minimized conformation after alignment. If global results are available, the panel uses the **global** minimized structure. Otherwise, it falls back to the **local** minimized structure. This makes the panel very useful for spotting where the ligand geometry changes the most, for example around flexible substituents or strained ring-adjacent atoms. ## View ligands in the SAMSON document Right-click in the results table to open the context menu, then choose: - **View selected molecules in document** - **View all molecules in document** Strain Explorer adds one folder per ligand to the active document and creates aligned structural models for: - the **original** imported conformation; - the **locally minimized** conformation; - the **globally minimized** conformation. This is useful when you want to compare conformers directly in 3D, add visual models, or continue analysis with other SAMSON tools. ## Export results ### Export to SDF From the same context menu, you can export the selected or all ligands to **SDF**. The exported file contains: - the ligand structure; - the original imported coordinates; - the original SDF properties; - computed properties such as **Local strain**, **Local RMSD**, **Global strain**, and **Global RMSD** when available. This is convenient for downstream filtering or for sharing annotated ligand libraries. ### Export to PDF You can also export a **PDF report** for the selected or all ligands. The report includes: - a cover summary for the exported ligand set; - counts of local and global successes; - the ligand with the lowest strain in the exported batch; - one card per ligand with a depiction, strain values, RMSDs, and SMILES. This is useful for medicinal-chemistry review meetings or quick project reports. ## Practical tips - Start with **local strain only** if you want a fast first pass. - Use **Monte Carlo** for flexible ligands with many rotatable bonds. - Use **Exhaustive** only when the torsional search space remains manageable. - Keep **global refinement** enabled if you want the best sampled conformer to be relaxed before reporting strain. - Use the **Quick filter** to narrow a large library by status, ID, scaffold, or assay property. ## Current limitations to keep in mind - Input is currently **SDF only**. - A **SMILES property is required** for each ligand. - The strain panel is currently **displacement-based**, not a full per-atom energy decomposition. - Global strain is a **search-based estimate** and depends on sampling quality. That is all you need to start using **Strain Explorer** for ligand strain analysis in SAMSON. ## Related tutorials - [Dock ligands and libraries with AutoDock Vina Extended](https://documentation.samson-connect.net/tutorials/adve/docking-libraries-of-ligands-with-autodock-vina-extended/index.md) for docking workflows where ligand strain can help prioritize poses. - [Generate analogue series with positional analogue scanning](https://documentation.samson-connect.net/tutorials/smiles-manager/perform-positional-analogue-scanning-using-the-smiles-manager-element/index.md) for creating ligand libraries to analyze. - [UMA Force Field](https://documentation.samson-connect.net/tutorials/uma-force-field/uma-force-field/index.md) for machine-learning based atomistic energy and force evaluation. ## Next step Use the strain values and status messages to choose ligands for refinement, docking review, or additional conformer analysis. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # Symmetry detection in biological assemblies The [Symmetry Detection](https://samson-connect.net/extensions/0a53a840-a147-12f8-29b1-b074a4041978) extension in SAMSON **finds and visualizes the axes of symmetry** in protein complexes, viral capsids, and other large biological assemblies. Understanding symmetry accelerates many molecular design and protein-modeling tasks - from building coarse-grained models to setting up efficient simulations. ## What you will learn In this tutorial, you will learn how to detect and visualize symmetry axes in biological assemblies with the Symmetry Detection extension in SAMSON. ## Before you start - Add the [Symmetry Detection](https://samson-connect.net/extensions/0a53a840-a147-12f8-29b1-b074a4041978) extension. - Open a biological assembly or multimeric complex in SAMSON before starting the examples below. - Use this page when you want to discover symmetry axes, confirm expected symmetry, or prepare a system for a symmetry-aware workflow. ## Why Detect Symmetry? - **Identify functional interfaces** that repeat across symmetric copies. - **Validate experimental structures** by checking expected symmetry elements. - **Reduce computational cost** by simulating only the unique asymmetric unit. - **Guide molecular design** of symmetric nanomaterials or mutagenesis targets. ## Supported Symmetry Types | Category | Supported symmetry types | | ------------- | ------------------------------------ | | Cyclic (Cn) | Any order (C2, C3, ...) | | Dihedral (Dn) | Any order (D2, D3, ...) | | Cubic | Tetrahedral, Octahedral, Icosahedral | Note The app may detect multiple symmetry groups at the same time. ## Quick-Start Tutorial 1. Open SAMSON. 1. Fetch (**Home > Fetch**) or load your assembly (e.g., PDB `3NQ4` or `1CHP` or `1B4B`). Note that depending on the chosen importer you might need to check an option to import biological assemblies. 1. Launch **Home > Apps > Biology > Symmetry Detection**. 1. Click **Compute symmetry**. 1. Review detected groups and choose the axis of interest. ## Example 1 - Icosahedral Capsid (3NQ4) The extension identifies the full icosahedral symmetry, displaying all 2-, 3-, and 5-fold axes. You can use this visualization to select a unique asymmetric unit before running heavy simulations. ## Example 2 - 1CHP For large assemblies, the app may propose one or more symmetry groups. ## Working with Multiple Symmetries Automatic detection may return multiple plausible symmetries - especially for large complexes. ### Choosing the best group 1. Prefer higher-order groups with **small RMSD** values. 1. Click a group to highlight its primary axis in the viewport. For example, the `1B4B` system has a dihedral symmetry of order 3 (`D3`): ### Specifying a Group Manually If you know the expected symmetry (e.g., `D3` for `1B4B`), pick it from the symmetry group and order drop-down lists: ### Exploring Axes and RMSD Each symmetry group can contain several axes. Expand the group to list them with their individual RMSD scores. - **Single-click** an axis -> highlights it in bold in the viewport. - **Double-click** an axis -> aligns the camera so you look straight down that axis. ## Tips for Better Visualization - Combine symmetry axes with Ribbons or Surface visual models for clear context. - Color asymmetric units differently to emphasize repeats (e.g., colorize per chain). - Use Viewport snapshots to capture figures for publications or presentations. ## Next Steps - Export the asymmetric unit for focused protein-modeling simulations. - Design symmetric mutations or ligands that exploit the detected symmetry. - Apply the same workflow to nanoparticle design or other studies. ## Related tutorials - [Generate symmetry mates for proteins](https://documentation.samson-connect.net/tutorials/symmetry/generating-symmetry-mates/index.md) for building complete assemblies from symmetry records. - [Protein docking with Hex](https://documentation.samson-connect.net/tutorials/hex/protein-docking-with-hex/index.md) for protein-protein docking workflows. - [Protein alignment](https://documentation.samson-connect.net/tutorials/protein-aligner/protein-aligner/index.md) for comparing related protein structures. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # Generate symmetry mates for proteins The [Symmetry Mate Editor](https://www.samson-connect.net/extensions/d5c311da-ad75-2934-8845-79b38b289ff8) extension in SAMSON lets you recreate symmetric replicas of proteins using transformation data found in PDB files. These replicas reveal how proteins are arranged in their **crystal structures** and **biological assemblies** - a crucial step for many protein-modeling and molecular design workflows. ## What you will learn In this tutorial, you will learn how to generate symmetry mates from PDB symmetry data with the Symmetry Mate Editor in SAMSON. ## Before you start - Add the [Symmetry Mate Editor](https://www.samson-connect.net/extensions/d5c311da-ad75-2934-8845-79b38b289ff8) extension if it is not already installed. - Open a PDB structure that contains symmetry information when you are ready to follow the workflow. - Use this tutorial when you want to reconstruct a crystal packing or biological assembly from the metadata already stored in a structure file. Note PDB files often provide very interesting information on how proteins are organized in their [crystal structure and biological assembly](https://pdb101.rcsb.org/learn/guide-to-understanding-pdb-data/biological-assemblies). ## Why Generate Symmetry Mates? - Visualize **biological assemblies** from crystallographic units. - Explore protein-protein interfaces and potential binding sites. - Reconstruct **quaternary structures** for simulations and design. - Create symmetric protein complexes or nanostructures in design pipelines. ## Activating the Editor Open the editor using either: - **Find everything**: Press `Shift`+`E` and search for "Symmetry Mate Editor". - **Editors menu**: Left-side viewport menu **... > General > Symmetry Mate Editor**. Once activated, control nodes appear in the viewport representing symmetry transformations. ## Exploring Symmetry Mates Use `Ctrl`/`Cmd` + `mouse wheel` to scale the number of visible control nodes. Here's an example with `1BRE`: **Hover** over a control node to **preview the replica** in real time. **Left-click** a node to permanently **generate that replica**. This way, in a few clicks, you can generate a complex structure: ## CRYST1 vs. BIOMT Records The **Symmetry Mate Editor** supports both: | Record type | Description | Widget color | | ----------- | --------------------------------------------- | ------------ | | CRYST1 | Symmetry from crystal lattice | White | | BIOMT | Symmetry from biological assembly annotations | Yellow | You can toggle between the two using the editor's interface. Here's an example with `1B5S`: ## Generating All Replicas at Once Hold `Ctrl`/`Cmd` before hovering and clicking a control node to preview and generate all symmetry mates in one action: To preview and create all replicas simultaneously, press and hold `Ctrl`/`Cmd` before hovering and left-clicking a control node: ## Applications in Molecular Design - Build complete oligomeric assemblies from asymmetric units. - Design symmetric protein cages or scaffolds. - Test how binding sites repeat across symmetry mates. - Simulate interactions between symmetric chains in molecular dynamics. ## Tips - Use the **Ribbons** visual model to clearly distinguish chains. You can colorize per chain. - Combine with [Symmetry Detection](https://documentation.samson-connect.net/tutorials/symmetry/computing-axes-of-symmetry-of-biological-assemblies/index.md) to analyze axes and RMSD. - Use **Undo** (`Ctrl`/`Cmd` + `Z`) to remove unwanted replicas. ## Related tutorials - [Symmetry detection in biological assemblies](https://documentation.samson-connect.net/tutorials/symmetry/computing-axes-of-symmetry-of-biological-assemblies/index.md) for analyzing axes and RMSD after building assemblies. - [Protein preparation and validation](https://documentation.samson-connect.net/tutorials/prepare-protein/prepare-protein/index.md) for cleaning protein structures before or after generating mates. - [GROMACS Wizard tutorials](https://documentation.samson-connect.net/tutorials/gromacs-wizard/index.md) for preparing selected assemblies for simulation. ## Next step Inspect the generated assembly, remove unwanted replicas if needed, and continue with symmetry analysis, visualization, or simulation preparation. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). # Interactive Modeling Universal Force Field In this tutorial, you will learn how to use the [Interactive Modeling Universal Force Field (IM-UFF) interaction model](https://www.samson-connect.net/extensions/27d95098-31ee-df2b-e559-af1bc98a3500) for interactive editing of molecular systems in SAMSON. We previously proposed [1](#fn:1) [a new implementation of the Universal Force Field (UFF) interaction model](https://documentation.samson-connect.net/tutorials/uff/uff/index.md) introduced by Rappe et al. [2](#fn:2), combined with an automatic scheme to perceive the molecular system in order to compute the bonds, bond orders, and atom types. If you are interested, please refer to the [UFF tutorial](https://documentation.samson-connect.net/tutorials/uff/uff/index.md). This tutorial is about the [Interactive Modeling Universal Force Field (IM-UFF) interaction model](https://www.samson-connect.net/extensions/27d95098-31ee-df2b-e559-af1bc98a3500) that was published in [3](#fn:3) and which extends the [UFF](https://www.samson-connect.net/extensions/8cbdc8b1-59e1-6459-d68f-b840275dd5e9) for performing interactive modeling. IM-UFF is able to smoothly handle topological changes of the modeled systems. More specifically, IM-UFF allows for the creation and breaking of covalent bonds, changes in the order of covalent bonds as well as changes in atom typizations. With this extension, molecular structures can go through significant modifications while being simulated or edited, in order to reach a topology that better reflects the current organization of the involved atoms. Incorporated in an interactive modeling process, this lets you easily build and edit molecular systems while being guided by physically-based inter-atomic forces. ## What you will learn In this tutorial, you will learn how to set up and use IM-UFF in SAMSON for interactive modeling with bond formation and bond breaking. ## Before you start - Add [IM-UFF](https://www.samson-connect.net/extensions/27d95098-31ee-df2b-e559-af1bc98a3500). - If you want the static, non-reactive workflow, see the companion [UFF tutorial](https://documentation.samson-connect.net/tutorials/uff/uff/index.md). - Use a small or medium test system first so it is easier to see how the topology updates during manipulation. ## Requirements - [IM-UFF](https://www.samson-connect.net/extensions/27d95098-31ee-df2b-e559-af1bc98a3500) Extension ## Setting IM-UFF The Interactive Modeling Universal Force Field (IM-UFF) [1] extends the Universal Force Field (UFF), a full periodic table force field proposed by Rappe et al. [2], for performing interactive modeling. The setting of IM-UFF interaction model is very close to the setting of UFF. - Open a document with a molecular system you want to simulate with IM-UFF. - Add a simulator via **Edit > Simulate > Add simulator** (or use the shortcut `Ctrl`+`Shift`+`M` / `Cmd`+`Shift`+`M`). - Select **Interactive Modeling Universal Force Field** in the list of interaction models. - Choose the state updater you want to rely on for the simulation (e.g., [FIRE](https://documentation.samson-connect.net/tutorials/fire/ready-set-fire/index.md)). - Press the **OK** button. Unlike UFF, there is no setup window in IM-UFF. You should now see the parameter window of IM-UFF. The parameter window of IM-UFF is close to the one of UFF. The main difference is the **Interactive modeling options** group on the top of the window which proposes two options: - **Static topology (UFF only)**. This option allows one to switch between standard UFF when the checkbox is checked and IM-UFF when it is not. Important note: there is one major difference between "standard UFF" as implemented here in the IM-UFF interaction model and UFF in the previous Universal Force Field interaction model. It is that the bond energy in "standard UFF" is equal to "zero" when the atoms are at the infinite distance, whereas in UFF they are equal to "zero" when they are at equilibrium distance. This shift of energy was added to have equal energies with UFF and with IM-UFF for a given equilibrium state and because "zero" energy reference in IM-UFF corresponds to atoms non-interacting together. For more details, see [3](#fn:3). - **Keep vdW for manipulated**. This option is active only with IM-UFF (i.e., when **Static topology** is unchecked). When it is checked, all the vdW energy and forces are computed whereas when it is unchecked, the atoms manipulated with the mouse are not considered while computing vdW interactions. This last setting makes manipulations easier since typically when you want to connect the manipulated atom to other atoms and vdW repulsive forces may hinder these connections. ## Running IM-UFF simulation - Be sure that the **Static topology (UFF only)** and the **Keep vdW for manipulated** options are unchecked. - Press the **Edit > Simulate > Start** button. IM-UFF simulation is now running. You can see at the bottom of the IM-UFF parameter window the total energy of the system as well as each individual energy term. Try to displace the atoms with the mouse. You see that when you move the atoms slightly, the bonds are not broken and the system moves in order to locally adjust the structure while the topology is preserved. However, if you displace an atom a lot, it breaks the bonds to its neighbors and the topology is updated as a consequence. On the contrary, when the atom location gets closer to some atoms, bonds can form to create a new topology. ## Customizing UFF and IM-UFF The IM-UFF interaction model allows one to set the van der Waals cutoff, the van der Waals switching distance, and the periodicity of the neighbor list construction for the two simulation modes: UFF only and IM-UFF. For details about these parameters, see our [previous post](https://documentation.samson-connect.net/tutorials/uff/uff/index.md) describing the UFF interaction model. The IM-UFF interaction model also offers several options to customize the automatic typization in UFF/IM-UFF. The description of these options can once again be found in our [previous post](https://documentation.samson-connect.net/tutorials/uff/uff/index.md) describing the UFF interaction model. However, note that when IM-UFF is running (i.e., when the static topology is unchecked), only the maximum coordination and maximum valence can be set. In this mode, the bond order and typization cannot be directly set since they take continuous values in function of the current positions of the atoms, to allow smooth transitions between different topologies. For more details, see our reference article [3](#fn:3). Finally, atoms can also be deleted from the model and added to the model "on the fly" i.e., the typization is then updated automatically as in the UFF interaction model. For more details, see once again our [previous post](https://documentation.samson-connect.net/tutorials/uff/uff/index.md) describing the UFF interaction model. ## Related tutorials - [Universal Force Field](https://documentation.samson-connect.net/tutorials/uff/uff/index.md) for the underlying UFF interaction model. - [Fast geometry optimization with FIRE minimizer](https://documentation.samson-connect.net/tutorials/fire/ready-set-fire/index.md) for a reusable minimization state updater. - [UMA Force Field](https://documentation.samson-connect.net/tutorials/uma-force-field/uma-force-field/index.md) for machine-learning based atomistic evaluation. ## Next step Use IM-UFF while interactively editing a small structure, then compare the behavior with standard UFF or another interaction model. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). ## References ______________________________________________________________________ 1. [A. K. Rappe, C. J. Casewit, K. S. Colwell, W. A. Goddard III and W. M. Skiff. UFF, a full periodic table force field for molecular mechanics and molecular dynamics simulations. Journal of the American Chemical Society 114.25 (1992): 10024-10035](https://doi.org/10.1021/ja00051a040). [↩](#fnref:1 "Jump back to footnote 1 in the text") 1. [S. Artemova, L. Jaillet and S. Redon. Automatic molecular structure perception for the universal force field. J. Comput. Chem. 2016, 37, 1191-1205](https://doi.org/10.1002/jcc.24309). [↩](#fnref:2 "Jump back to footnote 2 in the text") 1. [L. Jaillet, S. Artemova and S. Redon. IM-UFF: extending the Universal Force Field for interactive molecular modeling. Journal of Molecular Graphics and Modelling, 77 (2017): 350-362](https://doi.org/10.1016/j.jmgm.2017.08.023). [↩](#fnref:3 "Jump back to footnote 3 in the text")[↩](#fnref2:3 "Jump back to footnote 3 in the text")[↩](#fnref3:3 "Jump back to footnote 3 in the text") # Universal Force Field In this tutorial, you will learn how to set up and use the [Universal Force Field (UFF) interaction model](https://www.samson-connect.net/extensions/8cbdc8b1-59e1-6459-d68f-b840275dd5e9) in SAMSON. This [interaction model](https://documentation.samson-connect.net/users/latest/models/#interaction-models) implements the Universal Force Field (UFF) proposed by Rappe et al. [1](#fn:1). It also includes an automatic scheme to perceive the molecular system in order to compute the bonds, bond orders, and atom types, so that UFF can be applied directly to a given molecular system. For more details regarding this UFF implementation and the approach used to automatically perceive the molecular structure, please refer to publication [2](#fn:2). ## What you will learn In this tutorial, you will learn how to set up, run, and customize the Universal Force Field interaction model in SAMSON. ## Before you start - Open a molecular system that you want to simulate or edit interactively. - If you are new to SAMSON simulation tools, keep the workflow simple the first time and use the default settings. - Use this page as a practical getting-started guide; the references remain the best source for the deeper theory. ## Setting UFF 1. Open a document with a molecular system you want to simulate with UFF. 1. Add a simulator via **Edit > Simulate > Add simulator** (or use the shortcut `Ctrl`+`Shift`+`M` / `Cmd`+`Shift`+`M`). 1. Select *Universal Force Field* in the list of interaction models. 1. Choose the state updater you want to rely on for the simulation (e.g., [FIRE](https://documentation.samson-connect.net/tutorials/fire/ready-set-fire/index.md)). 1. Press the **OK** button. The UFF setup window now appears. - Check **Use existing bonds** if you want to rely on the existing bonds of the model. Otherwise, UFF will recompute the bonds from the atom types and positions. - Press the **OK** button. The module now initializes the system for UFF by performing the following operations: - Compute the covalent bonds if **Use existing bonds** was not checked earlier. - Compute the bond orders. - Compute the atom types. In case of detected inconsistencies, a warning message describing these inconsistencies may appear. At this stage, you should now see the parameter window of UFF. ## Running the UFF simulation You can now run the UFF simulation: - Press the **Edit > Simulate > Start** button. A UFF simulation is now running. At the bottom of the UFF window, you can see the energy of each UFF term as well as the total UFF energy. You can [interactively move atoms](https://documentation.samson-connect.net/users/latest/moving-objects/index.md) and see how the UFF model reacts by updating the position of the other atoms as a consequence. The UFF interface allows you to modify the following UFF parameters: - the type of bond stretch interaction: it is possible to switch between **Harmonic** and **Morse** for this interaction by selecting the corresponding radio button (see the detail of the difference between these modes in [1](#fn:1)). - the **van der Waals cutoff** distance that limits the distance for which vdW interactions are considered. - the **switching distance** from which the vdW term is weighted so that it smoothly reaches zero at the cutoff distance. - the **periodicity of neighbor lists construction**, that may be modified to recompute the neighbor lists used in vdW more or less often (by default it is recomputed at each time step). ## Customizing the typization Several options are offered to customize the typization of UFF in SAMSON. Note that such customization is recommended for advanced users only since it can easily lead to incorrect structures in case of misuse. Below we describe the options proposed to customize the UFF typization. - Some default maximum coordination (i.e., the number of neighbors) and maximum Valence (i.e., the number of neighbors weighted by their bond order) are set for the atoms (see [2](#fn:2) for more details). These default values can be modified for each atom by selecting the new value in the corresponding combo box and pushing the **Set** button. This new value is then taken into account in the new round of automatic atom perception. Note that these values are effective only if the new maximum coordination of valence is lower than the default one. - The bond order of the bonds can be forced. For this, first, select the bond (or set of bonds) you are interested in, then select a bond order value (between 0.1 and 3.9) in the UFF parameter window, finally, push the **Set** button in the bond order group. You can also force a bond order to not change after a new round of perception. For this, first, select the bond(s) and then press the **Freeze** button of the Bond order group in the UFF parameter window. Note that non-integer bond orders are possible. - Similarly, the UFF types of atoms can be forced. For this, first, select the atom (or set of atoms) you are interested in, then select the UFF type you want to assign to the atom(s). Finally, push the **Set** button to force the type. You can also force a given type to not change after a new round of perception. For this, select the atom(s) and press the **Freeze** button of the Typization group in the UFF parameter window. You can reset all of the previously mentioned customizations by pressing the corresponding **Reset all** buttons. Finally, you can recompute a new perception from the current customized settings and current atom positions (since bond creations depend on atomic distances) by pushing the **Reset perception** button. ## Deleting and adding atoms Atoms can be deleted from the model and added to the model "on the fly" i.e., the typization is then recomputed automatically accordingly. - Deleting an atom: select the eraser editor (rubber icon), then, select the atoms you want to delete. - Adding an atom. Add atoms connected to this system by creating them as bonded to an existing atom of the model. e.g.: select an atom element in the periodic table, editor; click on a simulated atom, move the mouse, you should see an atom bonded to the initial atom appearing in transparency, then release the button of the mouse after moving the mouse. The atom should be part of the simulated model. Tip You can learn more about how to build systems from [User Guide: Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/index.md) or the *Building with atoms* interactive tutorial in SAMSON (**Help > Tutorials**). That's all for this tutorial. For more details about the UFF implementation, please see reference [2](#fn:2). ## Related tutorials - [Interactive Modeling Universal Force Field](https://documentation.samson-connect.net/tutorials/uff/im-uff/index.md) for interactive atom typing during model editing. - [Fast geometry optimization with FIRE minimizer](https://documentation.samson-connect.net/tutorials/fire/ready-set-fire/index.md) for geometry optimization with a state updater. - [UMA Force Field](https://documentation.samson-connect.net/tutorials/uma-force-field/uma-force-field/index.md) for a machine-learning based alternative to classical force fields. ## Next step Continue with [Interactive Modeling Universal Force Field](https://documentation.samson-connect.net/tutorials/uff/im-uff/index.md) if you want a more interactive UFF-based workflow. ## Need Help? Have questions or feedback? Feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), via the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). ## References ______________________________________________________________________ 1. [A. K. Rappe, C. J. Casewit, K. S. Colwell, W. A. Goddard III and W. M. Skiff. UFF, a full periodic table force field for molecular mechanics and molecular dynamics simulations. Journal of the American Chemical Society 114.25 (1992): 10024-10035](https://doi.org/10.1021/ja00051a040). [↩](#fnref:1 "Jump back to footnote 1 in the text")[↩](#fnref2:1 "Jump back to footnote 1 in the text") 1. [S. Artemova, L. Jaillet and S. Redon. Automatic molecular structure perception for the universal force field. J. Comput. Chem. 2016, 37, 1191-1205](https://doi.org/10.1002/jcc.24309). [↩](#fnref:2 "Jump back to footnote 2 in the text")[↩](#fnref2:2 "Jump back to footnote 2 in the text")[↩](#fnref3:2 "Jump back to footnote 2 in the text") # UMA Force Field This tutorial shows how to use the UMA Force Field interaction model in SAMSON for interactive energy and force evaluation with the UMA family of machine-learning atomistic models. UMA is well suited to fast geometry refinement, exploratory relaxation, and qualitative force analysis. In the current extension, you can choose between: - **UMA-S (2.3 GB, v1.2)** for the default fast workflow - **UMA-S (1.1 GB, v1.1)** for a lighter legacy option - **UMA-M (11.7 GB, v1.1)** for a larger model when you want more capacity ## What you will learn In this tutorial, you will learn how to set up and use the UMA Force Field interaction model in SAMSON for machine-learning-based atomistic energy and force evaluation. ## Before you start Before creating a UMA simulation in SAMSON, make sure that: - the **UMA Force Field** extension is installed - the **Python Scripting** extension is installed and up to date - your machine can install Python packages on first use Note On first use, UMA prepares a dedicated Python environment and may request access to the UMA models. Follow the instructions shown in SAMSON carefully. It is normal for this first setup to take some time, and you may need to create the interaction model again once the setup is complete. ## Set up UMA Force Field 1. Open a document containing the molecular or materials system you want to evaluate with UMA. 1. Add a simulator via **Edit > Simulate > Add simulator**. 1. Select **UMA Force Field** in the list of interaction models. 1. Choose the state updater you want to use for the simulation, for example [FIRE](https://documentation.samson-connect.net/tutorials/fire/ready-set-fire/index.md). 1. Press the **OK** button. The **UMA Force Field Setup** window then appears. In this window, choose: - the **Model** - the **Task** The available tasks correspond to different application domains: - **OMOL - Molecules** for molecular systems; this is the only task that uses total charge and spin multiplicity in the UI - **OMAT - Inorganic materials** for bulk inorganic materials workflows - **ODAC - MOFs** for MOF and direct-air-capture style adsorption workflows - **OC20 - Catalysis** for catalytic surfaces and adsorbates - **OMC - Molecular crystals** for molecular-crystal systems Tip Start with **UMA-S** unless you already know that you need the larger **UMA-M** model. ## Run the UMA simulation After the environment is ready and the model can be accessed, SAMSON starts the UMA backend and loads the selected model. Once the **UMA Properties** window appears, you can start the simulation: 1. Press **Edit > Simulate > Start**. 1. Wait for the first UMA evaluation to complete. 1. Interactively move atoms or refine the structure while UMA updates energies and forces. At startup, the properties window may briefly show that the energy is not available yet. Once the first evaluation succeeds, the total energy is displayed in the window. ## Adjusting UMA properties While the simulation is running, you can modify the main UMA controls from the **UMA Properties** window. ### Bond update mode The **Bond update** list lets you choose how the bond graph is handled during the simulation: - **Covalent** recomputes covalent bonds from the current structure - **Wiberg bond order (estimated)** estimates Wiberg bond orders with a deep-learning model - **Mayer bond order (estimated)** estimates Mayer bond orders with a deep-learning model - **Off** leaves the current bond graph unchanged Note The Wiberg and Mayer modes are estimated bond-order visualizations. Use them for interactive exploration, but confirm important conclusions with your reference method. ### Charge and spin multiplicity For the **OMOL - Molecules** task, the properties window also lets you edit: - **Spin multiplicity** - **Total charge** Use values consistent with the system you want to model. For molecular systems, these settings are part of the request sent to UMA. ### Periodic boundary conditions The properties window also includes a **Periodic boundary conditions** group with: - a checkbox to enable or disable periodic boundary conditions - a 3 x 3 cell matrix in angstroms For periodic workflows, verify the cell carefully before interpreting the results. ## Recommended workflow For practical use, the following workflow works well: 1. Choose the task that matches your system type. 1. Start with **UMA-S** for rapid feedback. 1. For **OMOL**, set total charge and spin multiplicity consistently. 1. For periodic systems, check the unit cell before interpreting the result. 1. Use UMA to screen, refine, and explore structures, then confirm final results with a higher-accuracy reference method when needed. ## Related tutorials - [Generate crystal models](https://documentation.samson-connect.net/tutorials/crystal-creator/generating-crystal-models/index.md) for building periodic or crystalline inputs. - [Create molecular boxes with Molecular Box Builder](https://documentation.samson-connect.net/tutorials/molecular-box-builder/molecular-box-builder/index.md) for preparing larger molecular systems. - [Universal Force Field](https://documentation.samson-connect.net/tutorials/uff/uff/index.md) for a classical force-field based route. ## Next step Use UMA on a small representative system first, then apply the workflow to the structure or screening task you want to study. ## References - [B. M. Wood et al. UMA: A Family of Universal Models for Atoms (2025)](https://arxiv.org/abs/2506.23971) - [facebook/UMA model repository on Hugging Face](https://huggingface.co/facebook/UMA) # Developing extensions # Developing SAMSON Extensions SAMSON has an open architecture: you can extend it with your own tools, workflows, and interfaces, then distribute them privately or publicly through [SAMSON Connect](https://www.samson-connect.net/). Use this section if you want to: - build new SAMSON Extensions in C++ - find the right developer guide before starting a new extension project Note SAMSON Extensions are modules for SAMSON, developed thanks to the SAMSON SDK, and distributed on SAMSON Connect. SAMSON Extensions are what makes SAMSON useful: without any extension, SAMSON cannot even create an atom, open a file, etc. Learn more from [Developer Guide: SAMSON Extensions](https://documentation.samson-connect.net/developers/latest/extensions/) ## Developing SAMSON Extensions in C++ Use the SAMSON C++ SDK when you want to build native extensions such as apps, editors, force fields, visualizations, or parsers. This page is a short entry point: it helps you get to the right installation, generation, build, and distribution guide quickly. See the [SAMSON Developer Guide](https://documentation.samson-connect.net/developers/latest/) for the full reference. ## Get started - [**Install SAMSON SDK**](https://documentation.samson-connect.net/developers/latest/installation/) ______________________________________________________________________ Download and install SAMSON SDK. - [**Generate SAMSON Extensions**](https://documentation.samson-connect.net/developers/latest/extension-generator/) ______________________________________________________________________ Learn how to generate SAMSON Extensions using the Extension Generator provided with SAMSON. - [**Build SAMSON Extensions**](https://documentation.samson-connect.net/developers/latest/building/) ______________________________________________________________________ Learn how to build SAMSON Extensions on various OS. - [**Distribute SAMSON Extensions**](https://documentation.samson-connect.net/developers/latest/distributing/) ______________________________________________________________________ Learn how to distribute SAMSON Extensions on [SAMSON Connect](https://www.samson-connect.net/). ## Tutorials and examples - [**Developer Tutorials**](https://documentation.samson-connect.net/developers/latest/tutorials/) ______________________________________________________________________ Learn how to create SAMSON Extensions from developer tutorials. - [**Samples**](https://github.com/1A-OneAngstrom/SAMSON-Developer-Tutorials) ______________________________________________________________________ Get code for developer tutorials on GitHub. ## References - [**Developer Guide**](https://documentation.samson-connect.net/developers/latest/tutorials/) ______________________________________________________________________ Learn how to develop SAMSON Extensions and use SAMSON SDK. - [**Intro to OOP in C++**](https://documentation.samson-connect.net/wp-content/uploads/OneAngstrom-Object-oriented-programming-in-C.pdf) ______________________________________________________________________ Learn about object-oriented programming in C++. # Python # Accessing SAMSON functionality via Python The [Python Scripting extension](https://www.samson-connect.net/extensions/7b654ce6-e38c-b97f-6746-4fd6934487c2) gives you Python bindings for the SAMSON API together with an integrated Python console. Use this page if you want to: - write Python scripts that control SAMSON - automate workflows with Python in SAMSON - build tools or apps directly in Python - expose parts of your own extensions through Python bindings Get started [User Guide: Scripting](https://documentation.samson-connect.net/users/latest/scripting/index.md) You can use the SAMSON Python API in several ways: - Write Python scripts utilizing SAMSON Python API, see [Examples](https://documentation.samson-connect.net/scripting/latest/docs/Examples.html). - Run Python scripts as part of your SAMSON Extensions via [`SAMSON::runPythonCode`](https://documentation.samson-connect.net/developers/latest/api/classSAMSON/#function-runpythoncode) or [`SAMSON::runPythonFile`](https://documentation.samson-connect.net/developers/latest/api/classSAMSON/#function-runpythonfile). - Create apps fully in Python, see [Embedded app: a simple GUI with buttons](https://documentation.samson-connect.net/scripting/latest/docs/examples/Example_EmbeddedApp.html). - [Create Python bindings for your own SAMSON Extensions](https://documentation.samson-connect.net/developers/latest/tutorials/python-bindings-for-extensions) to expose their functionality in Python for others to use. - [**Python Scripting Guide**](https://documentation.samson-connect.net/scripting/latest/) ______________________________________________________________________ Learn about SAMSON Python API. - [**Examples**](https://documentation.samson-connect.net/scripting/latest/docs/Examples.html) ______________________________________________________________________ Examples of using the SAMSON Python API.