# SAMSON Documentation Center > The Documentation Center contains information about using SAMSON and SAMSON extensions, as well as guides about developing with SAMSON in Python or C++. # Home # SAMSON Documentation Center The *Documentation Center* contains information about using [SAMSON](https://www.samson-connect.net/) and [SAMSON extensions](https://www.samson-connect.net/extensions), as well as guides about [developing with SAMSON in Python or C++](developing-samson-extensions/). ## Get started [Create an account](https://www.samson-connect.net/signUp) and learn how to use SAMSON for molecular design. - [**Install SAMSON**](https://documentation.samson-connect.net/users/latest/getting-started/#installing-samson) ______________________________________________________________________ Start with installing SAMSON on your PC. - [**Release Notes**](samson-release-notes/) ______________________________________________________________________ What's new in SAMSON. ## Guides - [**Quick Start Guide**](https://documentation.samson-connect.net/wp-content/uploads/SAMSON-Quick-Start-Guide.pdf) ______________________________________________________________________ Get up to speed with SAMSON. - [**User Guide**](https://documentation.samson-connect.net/users/latest/) ______________________________________________________________________ Learn how to use SAMSON. - [**Extensions Tutorials**](tutorials/) ______________________________________________________________________ Learn how to use various SAMSON Extensions. - [**YouTube channel**](https://www.youtube.com/@samsonconnect) ______________________________________________________________________ Check out video tutorials and webinar recordings. - [**Blog**](https://blog.samson-connect.net/) ______________________________________________________________________ Check out the latest posts. - [**Forum**](https://forum.samson-connect.net/) ______________________________________________________________________ Have questions? - [**Scripting**](https://documentation.samson-connect.net/users/latest/scripting/) ______________________________________________________________________ How to use Python API, script, and develop apps in Python. - [**Developing extensions**](developing-samson-extensions/cpp/) ______________________________________________________________________ Get started with SAMSON C++ SDK. ## Social media Follow us on social media to learn first what's new in SAMSON: ## Links - [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) - a single text file with a packed representation of this Documentation Center, excluding User Guide, Scripting Guide, and Developer Guide. # Release Notes # SAMSON Release Notes Learn what's new in SAMSON from the release notes: - [SAMSON 2025 R1](whats-new-in-samson-2025-r1/) - [SAMSON 2024](whats-new-in-samson-2024/) - [SAMSON 2023 R1](whats-new-in-samson-2023-r1/) - [SAMSON 2022 R2](whats-new-in-samson-2022-r2/) - [SAMSON 2022 R1](whats-new-in-samson-2022-r1/) - [SAMSON 2021](whats-new-in-samson-2021/) - [SAMSON 2020 R3](whats-new-in-samson-2020-r3/) - [SAMSON 2020 R2](whats-new-in-samson-2020-r2/) - [SAMSON 2020 R1](whats-new-in-samson-2020-r1/) # 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 Coming soon! Register on [SAMSON Connect](https://www.samson-connect.net/) or follow us on social media to get notified about the upcoming webinars and other updates. ## Interaction Designer SAMSON 2025 R1 introduces the [Interaction Designer](https://documentation.samson-connect.net/users/latest/interaction-designer/) 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/) 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/) 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/) 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/) for more information. ## New functionality for building The arsenal of tools to [build molecular systems](https://documentation.samson-connect.net/users/latest/building-molecules/) 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/) 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. If you have any feedback or suggestions feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), by using the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). 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 the latest SAMSON. 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 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](core-updates/): 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](visualization-and-animation/): 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](modeling/): 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](coding/): SAMSON 2024 offers new facilities to rapidly write and run Python scripts. [Part V - 👥 Collaboration](collaboration/): 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. If you have any feedback or suggestions feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), by using the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). 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 the latest SAMSON. 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. # What’s new in SAMSON 2024 - Coding This is Part IV of [What’s new in SAMSON 2024](../), 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](../collaboration/). # What’s new in SAMSON 2024 - Collaboration This is Part V of [What’s new in SAMSON 2024](../), 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. If you have any feedback or suggestions feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), by using the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). 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 the latest SAMSON. 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. # What’s new in SAMSON 2024 - Core updates This is Part I of [What’s new in SAMSON 2024](../), 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/) 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](../collaboration/) 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/) 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/) 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](../visualization-and-animation/). # What’s new in SAMSON 2024 - Modeling This is Part III of [What’s new in SAMSON 2024](../), 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](../coding/). # What’s new in SAMSON 2024 - Visualization and animation This is Part II of [What’s new in SAMSON 2024](../), 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](../modeling/). # 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](samson-ai/): 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](molecular-cycles/): 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](integrated-python-development-environment/): 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](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. [Part V - ✅ New Pricing Structure](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! ## 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. If you have any feedback or suggestions feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), by using the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). 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 the latest SAMSON. 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. # What’s new in SAMSON 2023 R1 - Integrated Python Development Environment This is Part III of [What’s new in SAMSON 2023 R1](../), 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 Document 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](../interface-redesign-and-so-much-more/) 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](../), 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](../new-pricing-structure/), 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](../), 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](../integrated-python-development-environment/), 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](../), 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. If you have any feedback or suggestions feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), by using the **Feedback** button in SAMSON, or by [directly discussing with us](https://1-a.io/feedback). 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 the latest SAMSON. 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. # What’s new in SAMSON 2023 R1 - SAMSON AI This is Part I of [What’s new in SAMSON 2023 R1](../), 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 an 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 quickly up to speed 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., documentations 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](../molecular-cycles/), 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/) 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? Do not hesitate and 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. If you have any feedback or suggestions feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), by using 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 their 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/) and [animations](https://documentation.samson-connect.net/users/latest/presenting/). 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 regroups 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/) 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/) 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 it 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. If you have any feedback or suggestions feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), by using 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 you 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 settings 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 reference page](https://documentation.samson-connect.net/users/latest/nsl/) 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!). If you have any feedback or suggestions feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), by using 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 amount 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!). If you have any feedback or suggestions feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), by using 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](../whats-new-in-samson-2020-r1/), including **quick minimization**, a new **displacer editor**, etc. - Support for a new type of nodes, **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](../whats-new-in-samson-2020-r1/) 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!). If you have any feedback or suggestions feel free to reach out via the [Forum](https://forum.samson-connect.net/), via [e-mail](mailto:contact@samson-connect.net), by using 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). # User Guides # User Guides Learn how to use SAMSON for molecular design - build, simulate, analyze, visualize, and render molecular systems. [User Guide for the latest SAMSON 2025 R1 (v. 7.0.0)](https://documentation.samson-connect.net/users/latest/) User Guides for older versions of SAMSON - [User Guide for SAMSON 2024 R1 (v. 6.0.0)](https://documentation.samson-connect.net/users/6.0.0/) - [User Guide for SAMSON 2023 R1 (v. 5.0.0)](https://documentation.samson-connect.net/users/5.0.0/) - [User Guide for SAMSON 2022 R2 (v. 4.0.0)](https://documentation.samson-connect.net/users/4.0.0/) - [User Guide for SAMSON 2022 R1 (v. 3.0.0)](https://documentation.samson-connect.net/users/3.0.0/) - [User Guide for SAMSON 2021 R1 (v. 2.0.0)](https://documentation.samson-connect.net/users/2.0.0/) - [User Guide for SAMSON 2020 R3 (v. 1.0.0)](https://documentation.samson-connect.net/users/1.0.0/) - [User Guide for SAMSON 2020 R2 (v. 0.12.0)](https://documentation.samson-connect.net/users/0.12.0/) - [User Guide for SAMSON 2020 R1 (v. 0.11.0)](https://documentation.samson-connect.net/users/0.11.0/) - [User Guide for SAMSON 2020 R1 (v. 0.10.0)](https://documentation.samson-connect.net/users/0.10.0/) - [User Guide for SAMSON 2020 R1 (v. 0.9.0)](https://documentation.samson-connect.net/users/0.9.0/) - [User Guide for SAMSON 0.8.5](https://documentation.samson-connect.net/users/0.8.5/) - [User Guide for SAMSON 0.8.4](https://documentation.samson-connect.net/users/0.8.4/) - [User Guide for SAMSON 0.8.3](https://documentation.samson-connect.net/users/0.8.3/) - [User Guide for SAMSON 0.8.2](https://documentation.samson-connect.net/users/0.8.2/) - [User Guide for SAMSON 0.8.1](https://documentation.samson-connect.net/users/0.8.1/) - [User Guide for SAMSON 0.8.0](https://documentation.samson-connect.net/users/0.8.0/) - [User Guide for SAMSON 0.7.0](https://documentation.samson-connect.net/users/0.7.0/) User Guides for older versions were archived. # Extensions Tutorials # SAMSON Extensions Tutorials SAMSON is an integrated molecular design platform with an open architecture: you can customize your SAMSON by adding free or paid extensions from the [Marketplace](https://www.samson-connect.net/extensions). Below are tutorials detailing how to use some of the most popular extensions. ## Drug discovery and structural biology - [Aligning proteins](protein-aligner/protein-aligner/) - [Computing axes of symmetry of biological assemblies](symmetry/computing-axes-of-symmetry-of-biological-assemblies/) - [Computing normal modes that open a binding site](nma/calculating-non-linear-normal-modes/) - [Coronavirus: computing the opening motion of the SARS-CoV-2 spike](sars-cov-2/coronavirus-computing-the-opening-motion-of-the-sars-cov-2-spike/) - [Covalent and non-covalent protein-ligand docking with the Fitted Suite by Molecular Forecaster](fitted/fitted-suite/) - [Creating coarse-grained models for the MARTINI force field using Martinize2](martinize2/martinize2/) - [Docking ligands and ligand libraries with AutoDock Vina Extended](adve/docking-libraries-of-ligands-with-autodock-vina-extended/) - [Generating a path between protein structures](arap/arap-interpolation-for-protein-structures/) - [Generating symmetry mates](symmetry/generating-symmetry-mates/) - [Interactive Ramachandran Plot](ramachandran/ramachandran-plot/) - [Ligand Path Finder](ligand-path-finder/ligand-path-finder/) - [Perform Positional Analogue Scanning using the SMILES Manager](smiles-manager/perform-positional-analogue-scanning-using-the-smiles-manager-element/) - [Predicting protein-ligand complexes using NMR2](nmr2/predicting-protein-ligand-complexes-using-nmr2/) - [Prepare, minimize, equilibrate and simulate using GROMACS Wizard](gromacs-wizard/) - [Protein docking with Hex](hex/protein-docking-with-hex/) - [Protein Path Finder](protein-path-finder/protein-path-finder/) - [Running simulations in the cloud](gromacs-wizard/cloud/) - [Using the RDKit - SMILES Manager](smiles-manager/using-the-rdkit-smiles-manager/) ## Materials science - [Building carbon nanotube models](nanotubes/building-nanotubes-models/) - [Construct polymers with Polymer Builder](polymer-builder/polymer-builder/) - [Generating crystal models](crystal-creator/generating-crystal-models/) ## DNA origami - [Adenita SAMSON Edition: Interactive 3D modeling and visualization of DNA Nanostructures](adenita/adenita/) ## Multi-domain extensions - [Create molecular boxes with Molecular Box Builder](molecular-box-builder/molecular-box-builder/) - [Export atoms trajectories along paths](export-along-path/export-atoms-trajectories-along-paths/) - [Fast geometry optimization with the FIRE minimizer](fire/ready-set-fire/) - [Interactive Modeling Universal Force Field (IM-UFF)](uff/im-uff/) - [Making nano-batarangs (and more)](simple-script/making-nano-batarangs-and-more/) - [Optimize transition paths with P-NEB](pneb/optimize-transition-paths-with-parallel-nudged-elastic-band/) - [Pathlines: show a path of the center of mass of an atomic system](pathlines/pathlines/) - [Universal Force Field](uff/uff/) # Adenita [Adenita](https://www.samson-connect.net/extensions/dda2a078-1ab6-96ba-0d14-ee1717632d7a) is a 3D visualization and modeling toolkit for the in-silico design of static and dynamic DNA nanostructures. Based on a multiscale data model, it visualizes DNA-based structures on different abstraction levels and enable users to load and create DNA origami structures and combine them with proteins. Note Adenita is in the alpha version. 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 of Adenita to the latest versions of SAMSON and its support are done by the SAMSON team at [OneAngstrom](https://www.oneangstrom.com/). This tutorial is a quick-start guide to get you started designing DNA nanostructures on Adenita. 1. [First steps](#first-steps) 1. [Features](#features) 1. [Adenita interface](#adenitas-interface) 1. [Video tutorials](#video-tutorials) 1. [References](#references) ## First steps 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) and then restart SAMSON - it will automatically download and install Adenita for you. 1. You can find Adenita in **Home > Apps** or via **Find everything...**. 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 at . ## Features ### 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 component saved as *.adnpart*. You can combine as many components as your graphics card and CPU can afford. ### 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 to load a component into a workspace (loading using SAMSON files will create a new document). - The user can chose 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 CSV sequence file or in a format appropiate for oxDNA are available here. - All scaffolds from the selection will be assigned a sequence specified through the 'Options' menu, scaffold nucleotide's 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 appropiate 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. 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 its base. - Remove entire the 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) ## 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)\] # Docking ligands and libraries of ligands with AutoDock Vina Extended From this tutorial you will learn how to dock ligands or libraries of ligands into proteins or libraries of proteins using [AutoDock Vina Extended SAMSON Extension](https://www.samson-connect.net/extensions/1afc50e6-3567-fa25-1e09-415ebf4d05d7) and how to visualize and analyze the results. 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 results table, plots; - load the previously computed results. ## Requirements - [AutoDock Vina Extended SAMSON Extension](https://www.samson-connect.net/extensions/1afc50e6-3567-fa25-1e09-415ebf4d05d7). After adding a new extension from SAMSON Connect, it is necessary to restart SAMSON for it to automatically download and install the newly added extension. - Please download the [2AZ8 tutorial archive](https://documentation.samson-connect.net/wp-content/uploads/ADVE-2AZ8-tutorial.zip) which contains protein-ligand complex used in this tutorial and a sample ligand library. ## 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. 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 co-factors and other unnecessary small molecules present in the system. 1. Add hydrogens, if the system doesn't 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 shouldn't 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. Please note, that the system in the tutorial file has all the water already removed and hydrogens already added. Tip: remove alternate locations Alternatively, you can check the system for **alternate locations** using **Home > Validate** - this will launch the **Structure validation** module. There in the **Alt. locations** tab, click **Find alternate locations**. If there are any, they will be shown in the table. If there were any it is necessary to remove them by clicking on **Remove alt. locations**. You can also perform other checks for your system if necessary, e.g. check bond lengths, non-standard residues, and clashes. Tip: remove water Alternatively, you can **remove water** as follows: click on **Select > Water** to select it in the document, and then click on the **Current selection** in the **Document view** and choose **Erase selection** in the context menu or click on delete in the pop-up context toolbar. Tip: remove ions Alternatively, you can **remove monatomic ions** as follows: click on **Select > Ions > Monatomic ions** to select them in the document and then click on the **Current selection** in the **Document view** and choose **Erase selection** in the context menu or click on delete in the pop-up context toolbar. Tip: add hydrogens Alternatively, you can **add hydrogens** to a system using **Edit > Add hydrogens** - this will add hydrogens for the standard pH based on amino acid types and valences. To add hydrogens to only to a part of the system, select this part and then click on **Edit > Add hydrogens**. Note, that we don't necessarily need to minimize the structure after adding hydrogens since AutoDock Vina needs only polar hydrogens for determining hydrogen bonds. Tip: visualization If there is no secondary structure shown in the Viewport, you can add it via **Visualization > Visual model > Ribbons**. 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/) 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 and 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/) 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 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 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 that, 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 don't 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 from 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. Note, 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/) 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 a 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 in 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 by dragging which you can 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 in the document ligands and conformations 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 in AutoDock Vina Extended. There are several options to load 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 from the list the **Select results to load** 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 be loaded. 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 don't 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 isntructions 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/). 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/). 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). Please do not hesitate to write on our [Forum](https://forum.samson-connect.net/) if you have any questions or 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") # Generating a path between protein structures From this tutorial you will learn how to use the [ARAP Interpolation Path](https://www.samson-connect.net/extensions/d550a902-3427-8788-ddd7-14d6c0e2c140) Extension to generate a path between two protein structures or conformations within a few seconds thanks to ARAP (As-Rigid-As-Possible) interpolation [1](#fn:1). ## Requirements - [ARAP Interpolation Path](https://www.samson-connect.net/extensions/d550a902-3427-8788-ddd7-14d6c0e2c140) Extension Before starting the tutorial, we would like to ask you to download this file ([ArapInterpolation](https://documentation.samson-connect.net/wp-content/uploads/ArapInterpolation.zip)) which contains the necessary files for this tutorial. After extracting it, you will have two PDB files: `1ddt_A.pdb` and `1mdt_A.pdb`. ## Loading protein structures Our goal is to use the **ARAP Path** app to generate a path from `1ddt_A.pdb` to `1mdt_A.pdb`. These are two conformations from chain A of the PDB entries 1DDT and 1MDT in the Protein Data Bank, respectively, for Diphtheria Toxin. Run SAMSON. Load `1ddt_A.pdb` and `1mdt_A.pdb` files from the provided archive. In the **Document View**, select the `1ddt_A` structural model and if the structure contains non-protein nodes then in the main menu click **Select > Biology > Receptors** to select only the receptor/protein (see the note below). Then in the main menu click **Edit > Conformation**, and name the new conformation `1ddt_A`. Do the same for the `1MDT_A` structural model and name the conformation as `1mdt_A`. Note If your system has non-protein structures then you will need to either delete them or select only protein structures for the conformation creation via **Select > Biology > Receptors**. To delete non-protein structures you can use the Select menu to select them (e.g., water, ligands, ions) and then delete selections. See [User Guide: Selecting](https://documentation.samson-connect.net/users/latest/selecting/) for more information. The files in the archive were already prepared for you to contain only protein structures. ## Executing ARAP Path app Open the **ARAP Path** app via **Home > Apps > Biology > ARAP Path Interpolation**. In the app, click **Get conformations from the active document**. Then, in the **Start** and **Goal** lists, select `1ddt_A` and `1mdt_A`, respectively. Under **Construct ARAP vertices by matching**, check **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. The descriptions of all the options are as follows: - **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. 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. The descriptions of all the options are as follows (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. Check the box of **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 (note that the start and goal conformations are also included in the path). Now click **Apply** to run the ARAP interpolation In the end, you should have the settings as shown in the below figure. ## Results ### Viewing the edge construction type After the interpolation, the information of the run will be summarized in the **box** at the bottom of the app (the text area marked with **Other information...** in the last figure). A new visual model (named **ARAP edges** in the **Document View**) is also created to show the ARAP edges. In this visual model, the colors of the edges are the same as the squares that are beside the checkboxes of ARAP edge construction types in the app window. You can always show/hide the ARAP edges in the viewport by checking/unchecking the **ARAP edges** visual model in the Document View. To better see the ARAP edges, you can hide the stick-and-ball representation of `1DDT_A` and `1MDT_A` in the **Document View** by unchecking their boxes. ### Adding the secondary structure visualization If you haven't chosen to create a secondary structure visual model on loading of PDB files, then you can easily add them by selecting a structural model and clicking **Visualization > Visual model > Ribbons**. See [User Guide: Visualizing](https://documentation.samson-connect.net/users/latest/visualizing/) for more information. ### Viewing the path conformations In the **ARAP Path** app, manipulate the **slider** or the **number in the box** next to it for viewing the conformations along the path (see the animation below). #### Exporting the path For exporting as a **SAMSON path**, click the **Export path** button, and a path node with the name "*Path*" will be created in the **Document View**. For exporting as **PDB files**, click **Export pdb**, then select a folder you want to export them to. Each conformation will be saved as a PDB file with a sequence ID at the end of the file name. ## What's next? You can, for example, perform Umbrella Sampling based on the generated path using [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5) (see [GROMACS Wizard tutorial](../../gromacs-wizard/)). If you have any questions or feedback, please use the [SAMSON Connect Forum](https://forum.samson-connect.net/). ## 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") # Generating crystal models The [Crystal Creator](https://www.samson-connect.net/extensions/58a75a78-abbc-2c60-6214-e668b5c45a0d) Extension contains the basic tools to write and manipulate crystals as well as load crystals from CIF files. If you don't have this extension, then log in on [SAMSON Connect](https://www.samson-connect.net) and add it from the Marketplace. ## 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 2 websites: - The American Mineralogist Crystal Structure Database: - The RRUFF Project Database: I personally advise you to test Macdonaldite, Quartz, and Zorite, but please if you have a favourite crystal and you find it, test it. Open in SAMSON your '.cif' file. 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 appears in the data graph (see [User guide: Loading molecules](https://documentation.samson-connect.net/users/latest/loading-molecules/) 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 appears 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 tabulation of this property window has 4 tools: - A button to find back your crystal. - A check-box to see its mesh. - A tool box to cut your crystal. The 3 first boxes describe the cutting direction (the Miller indexes) and the 4th one the distance, from the position 0, where the cut is done. - A tool box to generate another crystal. The second tabulation 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, if 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 tabulation) or directly by writing the unit cell vectors (second tabulation). 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 the tabulation you are in, the atom coordinates are in 'relative position', ie a proportion of the unit cell vectors X, Y and Z, or in 'absolute position', in angstrom. - 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' tabulation: ``` 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 write choose a cubic unit cell of lattice parameter 3.60 Å and write in the 'relative position' tabulation: ``` 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 means our atom carbon have a probability of 0.95 to be present. - Load your diamond with defects, create the bonds. - See how the structure changed with defects. If you have any questions or feedback, please use the [SAMSON Connect Forum](https://forum.samson-connect.net/). # Export atom trajectories along paths From this tutorial you will learn how to export atoms positions (for all atoms in the system or for a selection of atoms) along paths in PDB files thanks to the [Export Along Paths](https://www.samson-connect.net/extensions/cc339322-498f-28e6-90b6-5e656cc345c3) app. This could be useful for example if you want to export only a part of the system or to generate reaction coordinates for free energy calculations. ## Requirements - [Export Along Paths](https://www.samson-connect.net/extensions/cc339322-498f-28e6-90b6-5e656cc345c3) Extension - Before starting the tutorial, please download the [1pv7_ligand_complex_with_paths](https://documentation.samson-connect.net/wp-content/uploads/1pv7_ligand_complex_with_paths.zip) (~13 MB) which contains files for this tutorial. ## Getting started Launch **SAMSON**. Load `1pv7_ligand_complex_with_paths.sam` file provided in the archive. It will open a structural model of **Lactose permease** with its ligand **Thiodigalactosid**. In the **Document View** (if you do not see it, enable it in the **Interface menu**, or press `Ctrl`/`Cmd` + `1`), you can see the protein under the name `Protein_chain_A`, the ligand under the name `TDG`, and several paths. Note **Paths** are SAMSON nodes that store trajectories of a selected group of atoms. Paths are typically created by apps. 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](../../ligand-path-finder/ligand-path-finder/) (and optimized this path with e.g. the [parallel nudged elastic band method](../../pneb/optimize-transition-paths-with-parallel-nudged-elastic-band/)), 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). ## Launching 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**. ## Export atoms trajectories along a path ### Export trajectory for all atoms If you want to export all atoms trajectories, just select a path (or paths) in the **Document view**, choose in the app how you want them to be exported (each step to a separate PDB file or all steps in one PDB file), and click the **Export atoms along paths to PDB files** button in the app. A window will appear asking you to provide a path and a prefix name for exported files. You can specify the interval at which path steps will be exported in the **Advanced** box of the app. ### Export trajectory for a set of atoms If you want to export the coordinates of some atoms only, expand the **Advanced** box. Let's export the trajectory of the ligand atoms to PDB files. Select the `TDG` ligand in the **Document view** (see [User guide: Selecting](https://documentation.samson-connect.net/users/latest/selecting/)): Then click the **Add** button to add models to export. A new line in the list of models to be exported will be added. 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. You can see which atoms belong to a model in the model list by clicking the **Select** and **Unselect** buttons or via the context menu for the corresponding line. If you are not satisfied with the chosen set of atoms, you can reset by choosing the line and clicking the **Reset** () button, or again via the context menu for the corresponding line. Now, you can choose how you want these sets of atoms to be exported (each step to a separate PDB file or all steps in one PDB file), select a path (or paths) in the **Document view**, and click the **Export atoms along paths to PDB files** button in the app. A window will appear asking you to provide a path and a prefix name for exported files. If you have any questions or feedback, please use the [SAMSON Connect Forum](https://forum.samson-connect.net/). # Fast geometry optimization with the FIRE minimizer Geometry optimization is a fundamental step in many molecular modeling applications, used to produce stable, realistic structures which correspond to energy minima. In this tutorial, we introduce a [SAMSON Extension that implements the FIRE minimizer](https://samson-connect.net/extensions/8ec255b0-7326-0bed-366e-40be71c1d160) described by Bitzek et al. [1](#fn:1). FIRE, which stands for Fast Inertial Relaxation Engine, is an efficient optimizer for molecular structures. Add the [FIRE State Updater](https://www.samson-connect.net/extensions/8ec255b0-7326-0bed-366e-40be71c1d160) Extension it to your SAMSON installation by clicking the **Add** button (you need to be signed in). Then, restart SAMSON and the newly added SAMSON Extensions will be automatically installed. In order to use FIRE, [open a molecular system](https://documentation.samson-connect.net/users/latest/loading-molecules/) and [apply a new simulator](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/#simulators) to it via **Edit > Add simulator**. [Select](https://documentation.samson-connect.net/users/latest/selecting/) the interaction model you want to use, and select FIRE in the list of state updaters. Three settings are available: 1. **Step size** - the initial step size given to the algorithm 1. **Steps** - the number of steps between two successive viewport updates 1. **Fixed** - it forces the time step to be constant (not necessarily needed) You may press the 'Reset' button if you manually move atoms during energy minimization and want to clear the FIRE history. FIRE is significantly faster than the steepest descent algorithm, in particular for large-scale motions that do not affect much the potential energy: FIRE Relaxation Steepest Descent Relaxation In the example above, you need to increase the 'Steps' parameter (i.e. the number of minimization steps between two viewport updates) in order to be able to see minimization happen. Since the [FIRE minimizer](https://samson-connect.net/extensions/8ec255b0-7326-0bed-366e-40be71c1d160) is implemented as a [SAMSON state updater](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/#simulators), you may use it in any application that relies on an optimization algorithm. If you have any questions or feedback, please use the [SAMSON Connect Forum](https://forum.samson-connect.net/). ______________________________________________________________________ 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 From this tutorial you will learn how to perform covalent and non-covalent protein-ligand docking with the [FITTED Suite SAMSON Extension](https://www.samson-connect.net/extensions/b72505d0-6942-ac90-2a78-b81b9d0cc5a1). The [FITTED Suite SAMSON Extension](https://www.samson-connect.net/extensions/b72505d0-6942-ac90-2a78-b81b9d0cc5a1) was done 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. ## Requirements - **SAMSON version 2020 R3 or newer** - [FITTED Suite SAMSON Extension](https://www.samson-connect.net/extensions/b72505d0-6942-ac90-2a78-b81b9d0cc5a1). After adding a new extension from SAMSON Connect, it is necessary to restart SAMSON for it to automatically download and install the newly added extension. - Please download the [FITTED tutorial archive](https://documentation.samson-connect.net/wp-content/uploads/FITTED_tutorial.zip) which contains the files used in this tutorial (click on the [link](https://documentation.samson-connect.net/wp-content/uploads/FITTED_tutorial.zip) to download the archive). ## 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) (click on the [link](https://documentation.samson-connect.net/wp-content/uploads/FITTED_tutorial.zip) to download the archive). 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/) (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/) for more information). You can read more about documents in [User guide: Documents](https://documentation.samson-connect.net/users/latest/documents/). Note, 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** or **Home > Validate**. This will also allow you to perform other checks for your system if necessary, e.g. check bond lengths, non-standard residues, and clashes. ### 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 don't 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 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/). 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 m\*\*\*\*enu > 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/) 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) 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 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) (click on the [link](https://documentation.samson-connect.net/wp-content/uploads/FITTED_tutorial.zip) to download the archive). 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**: Note, 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 > Validate**. The Structure Validation module also allows you to perform other checks for your system if necessary, e.g. check bond lengths, non-standard residues, and clashes. ### 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 don't 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 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 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 the visualization purpose, 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/) 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). Please do not hesitate to write on our [Forum](https://forum.samson-connect.net/) if you have any questions or feedback. ## 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). ## 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") # GROMACS Wizard This tutorial presents the [GROMACS Wizard Extension](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5), a [SAMSON](https://www.samson-connect.net) extension for system preparation and simulation locally and in the Cloud using the well-known [GROMACS](https://www.gromacs.org) package. The [GROMACS Wizard Extension](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5) integrates the main GROMACS features into SAMSON - it provides the possibilities to easily prepare systems for simulation with GROMACS, run GROMACS simulations locally or in the Cloud, and get the results as simulation trajectories and plots. It ships [GROMACS](https://www.gromacs.org) (the latest version of the extension ships GROMACS 2021.3) meaning that you do not need to compile and install the GROMACS package yourself. And it also provides the possibility to use your local installation of GROMACS (e.g., build specifically on your PC for performance reasons) if you would like to. This extension is available on Windows, Linux, and MacOS. ## Tutorial content - [Installation](#installing-gromacs-wizard) - [Pre-processing](preprocess/) - [Step 1: Prepare](preparation/) - [Step 2: Energy Minimization](energy-minimization/) - [Step 3: NVT Equilibration](nvt-equilibration/) - [Step 4: NPT Equilibration](npt-equilibration/) - [Step 5: Production Molecular Dynamics Simulation](production-md/) - [Periodic boundary conditions](periodic-boundary-conditions/) - [Applying custom parameters](applying-custom-parameters/) - [Adding custom index groups](adding-custom-index-groups/) - [Batch computations](batch-computations/) - [Coarse-grained systems](coarse-grained-systems/) - [COM pulling](com-pulling/) - [Umbrella Sampling](umbrella-sampling/) - [Potential of Mean Force (PMF) analysis](pmf-analysis/) - [Launching computations in the Cloud](cloud/) - [Using custom GROMACS version and performance parameters](settings/) ## Installing GROMACS Wizard To install the [GROMACS Wizard Extension](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5), sign in on the [SAMSON Connect](https://www.samson-connect.net) website and go to [SAMSON Extensions](https://www.samson-connect.net/extensions) where you can find the GROMACS Wizard, or open this link: [GROMACS Wizard Extension](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5). Once you are signed in, you can [add a SAMSON Extension](https://documentation.samson-connect.net/users/latest/samson-connect/#marketplace) in one click (see [User guide: installing SAMSON Extensions](https://documentation.samson-connect.net/users/latest/extending-samson/) if you need help installing a new SAMSON Extension). On the next launch of SAMSON, the newly added extension will be automatically downloaded and installed for you. If you need help installing SAMSON, please visit the [User Guide: Installing SAMSON](https://documentation.samson-connect.net/users/latest/getting-started/#installing-samson). Note: you can check whether you have this SAMSON Extension in at least three different ways: - In **Home > Apps > Biology** - In the **Interface > Preferences > Updates > SAMSON Extensions** list in SAMSON - Under **User > My Extensions** when you are signed in at [SAMSON Connect](https://www.samson-connect.net) # GROMACS Wizard - Adding custom index groups This section is part of the [GROMACS Wizard tutorial](../). GROMACS automatically generates standard index groups for your system based on its structure (e.g., protein, water, ions, etc.). But sometimes you might want to **add custom index groups** that we later be useful for analysis or during the simulation (e.g., as pull coordinate groups). You can do this thanks to GROMACS Wizard which allows you to use the extensive selection mechanisms available in SAMSON (see [User Guide: Selecting](https://documentation.samson-connect.net/users/latest/selecting/)). When dealing with a single project, you can add custom index groups at any step of the following steps: preparation, equilibration, and simulation. But 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 the subprojects. Note The new index groups are added using `gmx make_ndx` command and are saved in the `index.ndx` file in the project folder. ## Adding custom index groups at the preparation step To learn how to add custom index groups during the preparation step please refer to [Prepare: Adding custom index groups](../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 First, it requires that the system is loaded in SAMSON. If it is not already loaded, you can simply click the **Load** button 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/)). 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 ADD, | 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 using SAMSON**. First, [select](https://documentation.samson-connect.net/users/latest/selecting/) some nodes in your system. For the sake of the example, we will select all the neutral 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 syntaxes. Name the new group as you want. 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. # GROMACS Wizard - Applying custom parameters This section is a part of the [GROMACS Wizard tutorial](../). For each of the [Energy Minimization](../energy-minimization/), [NVT Equilibration](../nvt-equilibration/), [NPT Equilibration](../npt-equilibration/), and [Production Molecular Dynamics Simulation](../production-md/) steps you can provide custom [molecular dynamics parameters](https://manual.gromacs.org/documentation/current/user-guide/mdp-options.html) (MDP) using the graphical user interface or by loading them from an existing GROMACS molecular dynamics parameter file (an .mdp file). These parameters are populated with their default values. You can see some of the parameters directly in the tabs and the other parameters can be accessed by clicking on the **All...** button () present in each of the aforementioned tabs (steps). Once 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 above the parameter. Not all of the [molecular dynamics parameters](https://manual.gromacs.org/documentation/current/user-guide/mdp-options.html) might be present in these advanced parameters windows, but parameters can be added or modified in the **Additional Parameters** section. Note that the parameters provided there have priority over the same parameters present 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 that, 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 in the **Additional Parameters** section where you can modify them if necessary. You can also copy-paste all the parameters present in your MDP file in the **Additional Parameters** section - they will overwrite those present in the advanced parameters window groups. You can also **export parameters in 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 modifications of parameters that you have done except the resetting to the default parameters. To **restore the parameters** to their default values click on the **Reset** button. Note The modified parameters are saved on closing SAMSON, so the next time you will have the previously saved parameters. You can always find .mdp files with molecular dynamics parameters used for simulation in the simulation result 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). # GROMACS Wizard - Batch Computations This section is a part of the [GROMACS Wizard tutorial](../). This tutorial demonstrates how to perform batch computations using [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5) for a set of initial conformations of a single molecular system. To use an existing trajectory, load it in SAMSON. You can also create a trajectory or a set of conformation in SAMSON using various tools: - editors ([Move editors](https://documentation.samson-connect.net/users/latest/moving-objects/), Twister), - 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, Protein Path Finder, [protein-protein docking with Hex](https://www.samson-connect.net/extensions/d53ab0d1-37bb-0fb9-0474-e090aa46af3e), etc.), - [animations](https://documentation.samson-connect.net/users/latest/presenting/#animations) (Dock, Undock, Move, etc.) transformed into a path or a set of conformations. If you do not want to use all of the trajectory frames as initial conformations then you can create conformations for specific frames as follows: - 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. Once you have a trajectory or a set of conformations you want to use as initial frames you are ready to go! Open the **Prepare tab** in the GROMACS Wizard and follow the tutorial [Step 1: Prepare](../preparation/) by choosing the **batch preparation** and setting the conformations or a path. Please see below the brief description of the steps from the mentioned tutorial. Note The prepared batch project will contain numbered subfolders each representing a fully separate project. You can run the next steps on the whole batch project or separate subfolders. ## Choose the model Choose the force field and solvent. Please refer to [Step 1: Prepare - Choose the model](../preparation/#model). ## Set system Choose the structural model from the document and set it as the system. Please refer to [Step 1: Prepare - Set the molecular system](../preparation/#system). ### Add index groups 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](../preparation/#adding-custom-index-groups). ### Set initial conformations Activate the batch project by toggling **[Optional] Batch project** box. 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. Once you [selected](https://documentation.samson-connect.net/users/latest/selecting/) a set of conformation or a path from the document, click **Set conformations or a path**. You should see the number of conformations next to it and you can use the slider to go through the conformations. ## Define the periodic box Please refer to [Step 1: Prepare - Define the periodic box](../preparation/#box). For the batch project, the periodic box is set in one of two ways: - **Based on all the conformations** via the **Box lengths** option. You can specify the box size. On fitting it will fit the box tightly to your system – you will need to increase the size as needed to ensure the [minimum image convention](../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** **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](../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) allowing you to have smaller boxes for more compact conformations leading to a decrease in the 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. ## Add ions Choose ions as described in [Step 1: Prepare - Add ions](../preparation/#ions). ## Minimize, equilibrate, and simulate Once the batch project has been prepared, you can follow the same steps as for a single project: - [Step 2: Energy Minimization](../energy-minimization/) - [Step 3: NVT Equilibration](../nvt-equilibration/) - [Step 4: NPT Equilibration](../npt-equilibration/) - [Step 5: Production Molecular Dynamics Simulation](../production-md/) Please 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). You can launch the computations locally or in the Cloud (see [Launching computations in the Cloud](../cloud/)). Note that when launching local computations for a batch project they will be added as local jobs - a separate job per a 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. # GROMACS Wizard - Computing in the cloud This section is part of the [GROMACS Wizard tutorial](../). GROMACS Wizard allows you to launch GROMACS computations for [NVT Equilibration](../nvt-equilibration/), [NPT Equilibration](../npt-equilibration/), [Production Molecular Dynamics Simulation](../production-md/) steps in the Cloud in just a few clicks. In this section, you will learn how to launch GROMACS computations in the Cloud from GROMACS Wizard on an example of the [NVT Equilibration](../nvt-equilibration/) step. This procedure is the same for [NPT Equilibration](../npt-equilibration/) and [Production Molecular Dynamics Simulation](../production-md/) steps. ## Prerequisites Before going further, please first read the associated sections of the tutorial on launching local computations: [NVT Equilibration](../nvt-equilibration/), [NPT Equilibration](../npt-equilibration/), [Production Molecular Dynamics Simulation](../production-md/). Before launching a computation in the Cloud, please 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 In this section, we assume that the Input structure and the equilibration/simulation parameters were specified. If not, then please first read the following sections of the tutorial: [NVT Equilibration](../nvt-equilibration/), [NPT Equilibration](../npt-equilibration/), [Production Molecular Dynamics Simulation](../production-md/). ### Check the system This step is optional but recommended. Before launching a computation in the Cloud, we recommend trying to launch it locally for a few tens or hundreds of steps to verify whether there are any issues with the system. If your machine does not support launching the job locally, e.g. due to the system's size, you can click **Generate inputs** to try to generate input files - this will also check for some possible issues. ### Create the job To launch computations in the Cloud, click the **Equilibrate in the cloud / Simulate in the cloud** button (depending on the step). A dialog will pop up, asking you to choose the machine type. In this dialog, you can choose the machine that you would like to use for computations, the storage size, and the costs of the machine and the storage. Please note that only machine and storage costs are charged, the transfer of files 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 will appear asking you to confirm the launch of the job in the Cloud. This is a special security dialog that provides you with the job's details, including the pricing. In this dialog, you can see the number of computing credits you have. Please note that triggering a job in the Cloud needs you to have at least 1 computing credit in your account, but this doesn't mean that 1 credit will be withdrawn (this is a precaution to ensure the launching of the job in the Cloud), it can be less. 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 any time 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 e-mail 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, also, we can 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 be still available next time you launch SAMSON - the results are stored in the Cloud storage. One you have downloaded all results and you no longer need to keep them in the cloud, however, 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](../nvt-equilibration/), [NPT Equilibration](../npt-equilibration/), [Production Molecular Dynamics Simulation](../production-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 do not need the job files to remain in the cloud anymore, 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, a 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. If you have any questions, please do not hesitate to contact us via our [Forum](https://forum.samson-connect.net/). # GROMACS Wizard - Coarse-grained systems This section is a part of the [GROMACS Wizard tutorial](../). From this tutorial you will learn how to prepare a coarse-grained (CG) system with [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5), i.e. create a periodic box, solvate it, and add ions, to later be able to run 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](../../martinize2/martinize2/). Tip Before proceeding with the tutorial, we recommend you to first go through the [GROMACS Wizard - Step 1: Prepare](../preparation/) tutorial. ## Preparation step Below are the steps showing how to prepare a CG system in GROMACS Wizard on an example of a soluble protein for which a CG system has been generated in the [Martinize2 tutorial](../../martinize2/martinize2/). 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](../../martinize2/martinize2/) 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 selected 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](../../martinize2/martinize2/), 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 switch 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](../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 default values. Note You can also provide a custom CG solvent model, see [Step 1: Prepare - Using a custom solvent model](../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 the most regular space-filling unit cell. See also [Step 1: Prepare - Defining the box](../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](../preparation/#ions) 1. Click **Prepare**. See also [Step 1: Prepare - Run preparation](../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 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](../com-pulling/) or [Umbrella Sampling](../umbrella-sampling/). Note If in [Martinize2](../../martinize2/martinize2/) you chose to generate position restraints based on *backbone* or *all*, then it generates a separate position restraint records per separate molecule (e.g., per separate protein chain) in 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 to not 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](../energy-minimization/) - [Step 3: NVT equilibration](../nvt-equilibration/) - [Step 4: NPT equilibration](../npt-equilibration/) - [Step 5: Production Molecular Dynamics Simulation](../production-md/) # GROMACS Wizard - COM Pulling This section is a part of the [GROMACS Wizard tutorial](../). This tutorial demonstrates how to perform **center-of-mass (COM) pulling** using [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5). **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). ## 1. Loading the system First, load the system: go to **Home > Fetch** and load **2BEG** from the RCSB PDB in *mmCIF* or *PDB* format. 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 *chain A* away while restraining *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, e.g., removing alternate locations and waters. For the system in the tutorial, you can skip this step since there is no need for such pre-processing. To learn more about this step, please refer to the following tutorial: [GROMACS Wizard - Pre-processing](../preprocess/) ## 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 we need to set up the system for the **Prepare step**. Below we will briefly cover the steps. To learn more about the preparation step, please refer to the following tutorial: [GROMACS Wizard - Step 1: Prepare](../preparation/) ### 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](../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/) 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 (1nm by each side) to better ensure the [minimum image convention](../periodic-boundary-conditions/#minimum-image-convention) if parts of the pulled chain went 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 it should be all 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 there are 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](../energy-minimization/) 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 that 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](../npt-equilibration/) 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 there are 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 that 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 the local GROMACS jobs and their state 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](../production-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 group 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](../adding-custom-index-groups/) 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 there are 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 that 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 the local GROMACS jobs and their state 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 them. 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 in time - the force builds up until it is sufficient enough to overcome internal restoring forces between chains. You can use the results for [Umbrella Sampling](../umbrella-sampling/). # GROMACS Wizard - Step 2: Energy Minimization This section is part of the [GROMACS Wizard tutorial](../). Once a system or a batch project has been successfully [prepared](../preparation/), it is necessary to perform the **Energy Minimization (EM)** step to ensure that the system has no steric clashes or inappropriate geometry. Switch to the **Minimize** tab. ## Selecting input structure When launching the *Energy Minimization step*, GROMACS Wizard requires you to provide one of the following: - **The path to a GRO file** resulting from the previous step: either a GRO file resulting from the [Preparation step](../preparation/) or the previous launch of the *Energy Minimization step*. - **The path to a batch project**, that has been [prepared](../preparation/) or resulted from one of the other steps. 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](../preparation/)). 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 usual 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 on how to apply custom parameters please check the [Applying custom parameters](../applying-custom-parameters/) section. For the sake of this tutorial, leave 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 on closing SAMSON, so the next time 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 one you specified in the settings (see [Using custom GROMACS version and performance parameters](../settings/)). - **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](../cloud/) for more information. Now, simply 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 from several seconds to about one minute. You can see the current progress in the Output window that 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 the local GROMACS jobs and their state 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 the **Local jobs**. You can choose whether to import the whole trajectory, only the last frame, or some range of frames, 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 the 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 () on top of the figure. ### Checking results There are two important factors to check to determine if Energy Minimization was successful and has converged: - **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 very end of the output. You can check them in the Output window. It is possible that Energy Minimization would reach the given maximum number of minimization steps and will 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 may be 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.). # GROMACS Wizard - Step 4: NPT Equilibration This section is part of the [GROMACS Wizard tutorial](../). Once the system has been successfully [minimized](../energy-minimization/) and the [system's temperature has stabilized](../nvt-equilibration/) at the desired value, it is necessary to apply pressure to the system until it reaches the correct density. This second equilibration phase is aimed at stabilizing the system's density at the desired value by performing equilibration using the *NPT ensemble* (constant Number of particles, Pressure, and Temperature) also known as *isothermal-isobaric*. Switch to the **Equilibrate (NPT)** tab. ## Selecting input structure When launching the *NPT Equilibration step*, GROMACS Wizard requires you to provide one of the following: - **The path to a GRO file** resulting from the previous step: either a GRO file resulting from the [Minimization step](../energy-minimization/), [NVT Equilibration](../nvt-equilibration/) step, or the previous launch of an equilibration *step*. - **The path to a batch project**, that has been [minimized](../energy-minimization/) and/or equilibrated using NVT ensemble or resulted from one of the other steps. 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](../nvt-equilibration/)). 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 usual 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 integration time step and the number of steps. The timeframe for such a procedure depends upon 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 on how to apply custom parameters please check the [Applying custom parameters](../applying-custom-parameters/) 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 time constant including 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 the sake of 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 on closing SAMSON, so the next time 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 one you specified in the settings (see [Using custom GROMACS version and performance parameters](../settings/)). - **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](../cloud/) for more information. Now, simply click on the **Equilibrate 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 there are 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 that 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 the local GROMACS jobs and their state 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 the **Local jobs**. You can choose whether to import the whole trajectory, only the last frame, or some range of frames, 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 demonstrates that the density is 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 well-equilibrated now 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 () on top of the figure. ### Checking results It is important to check whether the system has reached the desired density and whether that density stabilized. Please note, that density might fluctuate around the desired value. If the system has not reached the desired density or has not yet stabilized at it then you would need to launch additional NPT Equilibration starting from the results of this NPT Equilibration. For that, set the input GRO file to the current NPT Equilibration results (you can simply click on the **auto-fill** button () to set it to the latest results). Once the system's density has stabilized at the desired value, we will proceed to the actual simulation. # GROMACS Wizard - Step 3: NVT Equilibration This section is part of the [GROMACS Wizard tutorial](../). Once the system has been successfully [minimized](../energy-minimization/), it is necessary to **Equilibrate** the system to bring it to the desired temperature and pressure/density and stabilize it. Equilibration is often conducted in two phases. The first one is aimed at bringing the system to the desired temperature (the one that you would like to simulate) and stabilizing it by performing equilibration using the *NVT ensemble* (constant Number of particles, Volume, and Temperature) also referred to as*isothermal-isochoric* or *canonical* ensemble. After the system reaches the desired temperature we will apply the [NPT Equilibration](../npt-equilibration/) step for the system to reach the desired density. Switch to the **Equilibrate (NVT)** tab. ## Selecting input structure When launching the *NVT Equilibration step*, GROMACS Wizard requires you to provide one of the following: - **The path to a GRO file** resulting from the previous step: either a GRO file resulting from the [Minimization step](../energy-minimization/) or the previous launch of an equilibration *step*. - **The path to a batch project**, that has been [minimized](../energy-minimization/) or resulted from one of the other steps. 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](../energy-minimization/)). 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 usual 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 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 on how to apply custom parameters please check the [Applying custom parameters](../applying-custom-parameters/) 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 of the 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](../adding-custom-index-groups/) for more information. You can reset back to the default `System` coupling by clicking on the reset button. For the sake of 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 on closing SAMSON, so the next time 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 one you specified in the settings (see [Using custom GROMACS version and performance parameters](../settings/)). - **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](../cloud/) for more information. Now, simply click on the **Equilibrate 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 there are 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 that 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 the local GROMACS jobs and their state 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 the **Local jobs**. You can choose whether to import the whole trajectory, only the last frame, or some range of frames, 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 demonstrates that the temperature is 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 () on top of the figure. ### Checking results It is important to check whether the system has reached the desired temperature (based on kinetic energy) and that the temperature is stabilized at it. Please note, that the temperature might fluctuate around the desired value. If the system has not reached the desired temperature or has not yet stabilized at it then you would need to launch additional NVT Equilibration starting from the results of this NVT Equilibration. For that, set the input GRO file to the current NVT Equilibration results (you can simply click on the **auto-fill** button () to set it to the latest results). Once the system's temperature has stabilized at the desired value, we will apply the [NPT Equilibration](../npt-equilibration/) step for the system to reach the desired density. # GROMACS Wizard - Periodic boundary conditions ## 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 can choose which unit cell to use for the periodic boundary conditions and its size when [preparing a system](../preparation/): 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. On fitting it will fit the box 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 per 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 which appears on loading of 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 the periodic boundary conditions are used it is crucial to satisfy the **minimum image convention**. This means that, for example, a solute should never see its periodic image, otherwise the calculated forces might be wrong. We recommend adding a distance of at least 1.0 nm between a solute and the box - that would mean that there is at least 2.0 nm between any two periodic images of solute 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. 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. # GROMACS Wizard - PMF Analysis This section is a part of the [GROMACS Wizard tutorial](../). This tutorial demonstrates how to compute the **Potential of Mean Force** (PMF) using the **Weighted Histogram Analysis Method** (WHAM) in [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5). Switch to the **WHAM Analysis** tab in [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5). Choose the project path or click on the **auto-fill** button () if the previous project you ran was the [Umbrella Sampling](../umbrella-sampling/) simulation. The project folder might be a result of the [batch computation](../batch-computations/), and it needs to contain numbered subfolders each containing simulation results done for the same system with the same reaction coordinates. GROMACS Wizard will load the information from the project on reaction coordinates (names and bounds), time, and temperature. Choose the reaction coordinate from the list, modify the other options (custom bounds, custom time, energy units) if needed, and click **Compute**. Two graphs will be produced showing the PMF and the histogram. For big trajectories, the computation might take several seconds or minutes. The histogram graph demonstrates how well the reaction coordinate space is covered and where additional computations might be needed. Once the computation is done for the given reaction coordinate and parameters, the computed profiles, histograms, and plots are automatically saved in the `wham_results` subfolder in the project folder. So, when you switch between reaction coordinates in the list, it will use the already computed data for the given parameters. # GROMACS Wizard - Step 1: Prepare This section is part of the [GROMACS Wizard tutorial](../). Once the system has been [preprocessed and validated](./), we can start the preparation step. To launch GROMACS simulations, we first need to 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](../umbrella-sampling/). Below we first show how to prepare a single project, the batch project can be prepared in the same way by additionally specifying a set of conformations or a trajectory (path) corresponding to the system, see [Batch preparation](#batch-preparation). Note To learn how to prepare a coarse-grained model please refer to the [Coarse-grained systems](../coarse-grained-systems/) tutorial. ## Choosing the results folder First, let's choose a folder where we want the results to be saved. Click on the **...** button to choose the folder. The **Open** button allows you to open this folder in your default file explorer. ## 1. Choosing the system We need to specify the molecular system that we would like 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/) 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). But 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/)). **Requirement**: This step requires that the system has unique and consecutive indices for residues and atoms. Note The new index groups are added using `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/)). 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 syntaxes. Name the new group, e.g. `HELICES`. You can also test the selection string and select nodes in SAMSON based on it to test 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](../umbrella-sampling/). The batch project allows you to easily launch the next steps (minimization, equilibration, simulation) for the whole batch (locally or in the cloud) and not per project. To set up the batch project: 1. Check the **Batch preparation** box. 1. Select in the **Document view** a set of conformations or a single trajectory (a path node) corresponding to the chosen system. 1. Click the **Set conformations or a path** button. Please note that for the batch project, the periodic box is set either based on all the conformations (option: **Box lengths**) or per conformation (option: **Solute-box distance**). See the next section for more information. Note The prepared batch project will contain numbered subfolders each representing a fully separate project. You can run the next steps on the whole batch project or separate subfolders. ## 2. Specifying the model The next step is to 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 Now, we need to choose the force field with which we would like to simulate the system. Please note, that **the choice of the force field is important** and might significantly influence the simulation. Please 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 system 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 then you just 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*). Please see the [Using a custom force field](#using-a-custom-force-field) section to see how to provide a custom force field. ### 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 proposes water models that can be used to describe water molecules if you want to simulate your structure using explicit water. 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 won't be possible to add solvent and ions. To add explicit solvent in 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 required to modify these options, so leave them as is. One of the cases when it might be necessary to modify them is when [preparing a coarse-grained systems](../coarse-grained-systems/). ### 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 a good alignment of molecules on the stacking interfaces. The box of solute 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 the present force fields might have the same H atoms naming convention). ## 3. Defining the box Now we need to define the box before proceeding with the preparation step. To define the box, [select](https://documentation.samson-connect.net/users/latest/selecting/) 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](../periodic-boundary-conditions/) for more information. Two options for initial fitting of the box based on the system are available: - **Box lengths** - specify the box size. On fitting it will fit the box tightly to your system - you will need to increase the size as needed to ensure the [minimum image convention](../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](../periodic-boundary-conditions/#minimum-image-convention). For the batch project, the box sizes will be different per 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 positions 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, 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 - that would mean 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 which appears on loading of GROMACS trajectories. ## 4. Neutralizing the system We need to make sure the system is neutral (has zero charge) 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 the neutralization of your system by GROMACS. You can choose them from the associated lists. Note that only one type of ions (positive or negative) or none of them will be added by GROMACS based on the total charge of your system. If you would like 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 thus bearing 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 that would be 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 up to 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 conterions. This will add sufficient ions to reach up to the specified concentration as computed from the volume of the cell. These ions will be added on top of neutralizing counterions to reach up to the specified concentration as computed from the volume of the cell. A concentration of 0.15 M of NaCl is a popular choice given that is a good representation of the 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 it should be all 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 there are 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. 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 add 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/) to learn more about how to add visual models, change rendering, and create publication-quality images. # GROMACS Wizard - Pre-processing of the system This section is a part of the [GROMACS Wizard tutorial](../). ## Load the system In this tutorial, we will be using the [1AKI](https://www.rcsb.org/structure/1aki) structure. You can download it from the RCSB Protein Data Bank website by clicking on **Home > Fetch**. Enter the PDB code 1AKI (you can select any format: PDB, PDBx/mmCIF, or MMTF), and click **Load**. Depending on the format, a pop-up dialog might appear asking about import parameters - you can leave them to their default values. If you downloaded the system from the Protein Data Bank website and you have it locally on your PC, then you can load your system using the **Home > Open** (`Ctrl`/`Cmd` + `O`). ## Pre-process the system Before applying the [Preparation step](../preparation/) in GROMACS Wizard, we first need to pre-process the system, i.e. remove alternate locations, existing water, ligands, ions. You can easily do it using **Home > Prepare**: The **Add hydrogens** option is optional since GROMACS can add hydrogens as well. If you want to have more control please check the section below. ## Advanced: Validation of the system ### Checking for alternate locations If the system contains atoms with **alternate locations**, then they need to be removed. Tip You can remove alternate locations in a single step via **Home > Prepare** and checking the **Remove alternate locations** option. You can check the system for alternate locations using **Home > Validate** - this will launch the **Structure validation** module. There in the **Alt. locations** tab, click **Find alternate locations**. If there are any, they will be shown in the table. If there are any, you can remove them by clicking on **Remove alt. locations**. You can also perform other checks for your system if necessary, e.g. check bond lengths, non-standard residues, and clashes. ### Removing existing water Now we will delete the existing water molecules from the system. Tip You can remove water in a single step via **Home > Prepare** and checking the **Remove water** option. Please note, that this procedure is not universally applicable. Please 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 on how to delete only some water molecules and to preserve water molecules that are functional in the system, e.g. water molecules that are tightly bound or functional in the active site. Tip Alternatively, you can **remove water** as follows: click on **Select > Water** to select it in the document, then in the pop-up context menu click on the Delete button (with the trash bin icon). ### How to delete existing crystal waters outside of the active site Please note, 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** some distance that is 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**. ### Removing arbitrary molecules Tip You can remove non-protein molecules in a single step via **Home > Prepare** and checking the **Remove ligands** and **Remove ions** options. If your system contains any cofactors or other arbitrary molecules for which GROMACS cannot generate topology and if you do not need them in the simulation then 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 arbitrary molecules that you do not need in the simulation. ## Parametrization of arbitrary molecules If your system contains arbitrary molecules that you would like to simulate, then you will need to provide topology files (itp files) for them. 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 then you just need to provide them in GROMACS Wizard and it will do the rest for you. # GROMACS Wizard - Step 5: Production Molecular Dynamics Simulation This section is part of the [GROMACS Wizard tutorial](../). Once the equilibration of the system is completed - the system's temperature and density have stabilized at the desired values - we can finally run a production molecular dynamics (MD) simulation. Switch to the **Simulate** tab. ## Selecting input structure When launching the *Production MD step*, GROMACS Wizard requires you to provide one of the following: - **The path to a GRO file** resulting from the previous step: either a GRO file resulting from the [NPT Equilibration](../npt-equilibration/) step, or the previous production MD launch. - **The path to a batch project**, that has been [equilibrated](../npt-equilibration/) or resulted from one of the previous production MD run. 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](../npt-equilibration/)). 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 usual 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 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 on how to apply custom parameters please check the [Applying custom parameters](../applying-custom-parameters/) 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 the sake of this tutorial, reset the parameters to their default values and set the maximum number of steps to 50,000 as shown in the image above so that the simulation would not take long. For example, the simulation of the system in the tutorial that has approximately 19,000 atoms for 50,000 timesteps takes about a couple of minutes on a machine with 18 cores. 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 on closing SAMSON, so the next time 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 one you specified in the settings (see [Using custom GROMACS version and performance parameters](../settings/)). - **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](../cloud/) for more information. Now, simply click on 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 there are any. 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 that 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 the local GROMACS jobs and their state 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, 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 on top of the figure. # GROMACS Wizard - Using custom GROMACS version and performance parameters This section is a part of the [GROMACS Wizard tutorial](../). ## 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 provides you with the possibility to 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 output. 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, so to bypass this warning 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 the local jobs, they are not transmitted to the Cloud jobs. By default, GROMACS Wizard sets the **number of threads** to be used for **running local jobs** to be lower than the maximum number of threads so that when performing computations it won't block your OS and other programs. If it is set to 0 then GROMACS will guess the number of threads, i.e. it will use the maximum available number of threads. If set to a non-zero value that is less than the number of (logical) cores then it will also use the `-pin on` parameter to pin threads to cores for better performance. 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, for example: `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). # GROMACS Wizard - Umbrella Sampling This section is a part of the [GROMACS Wizard tutorial](../). This tutorial demonstrates how to perform Umbrella Sampling using [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5). To perform Umbrella Sampling you first need to **obtain a set of initial conformations**. You can do it in one of the following ways: - [From GROMACS trajectory](#option-1-from-gromacs-trajectory) obtained from some simulation, e.g. by performing [COM pulling](../com-pulling/) 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 If you already have a GROMACS trajectory from which you would like to use frames as initial conformations for Umbrella Sampling then read this section. For the tutorial's sake, we will use the results obtained from the [COM Pulling tutorial](../com-pulling/). ## 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](../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 conformation click **Generate project**. This will generate a **batch project** folder with a timestamp and `_umbrella` suffix that contains subfolders with individual projects per initial conformation and `frames.ndx` file with information on which frames from the original trajectory were chosen as the initial conformations for Umbrella Sampling. ## Option 2: From Conformations or Path Please refer to the [Batch computations](../batch-computations/) tutorial and follow it until the NVT equilibration step including. For NPT equilibration and production MD simulation you need to specify in COM pulling the reaction coordinates you want to analyze - see the next section. ## NPT Equilibration and Simulation Now, you can perform **NPT equilibration** (see [Step 4: NPT Equilibration](../npt-equilibration/)) and then **production MD simulation** (see [Step 5: Production Molecular Dynamics Simulation](../production-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 specified parameters, launch the computations locally or in the Cloud (see [Launching computations in the Cloud](../cloud/)). Note that when launching local computations for a batch project they will be added as local jobs - a separate job per a 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 you performed the Umbrella Sampling simulation, you can use [GROMACS Wizard](https://www.samson-connect.net/extensions/02407d21-0490-30ba-d20f-2e88db100fc5) to compute the **Potential of Mean Force** (PMF) using the **Weighted Histogram Analysis Method** (WHAM). Please refer to the [Potential of Mean Force (PMF) analysis](../pmf-analysis/) tutorial. # Protein docking with Hex From this tutorial you will learn how to perform protein docking with the [Hex SAMSON Extension](https://www.samson-connect.net/extensions/d53ab0d1-37bb-0fb9-0474-e090aa46af3e). 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)) ## Requirements - **SAMSON version 2020 R3 or newer** - [Hex Extension](https://www.samson-connect.net/extensions/d53ab0d1-37bb-0fb9-0474-e090aa46af3e). Note After adding a new extension from SAMSON Connect, it is necessary to restart SAMSON for it to automatically download and install the newly added extension. ## 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 shouldn't 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. Please note, that the system in the tutorial file has all the water already removed and hydrogens already added. Tip: remove alternate locations Alternatively, you can check the system for **alternate locations** using **Home > Validate** - this will launch the **Structure validation** module. There in the **Alt. locations** tab, click **Find alternate locations**. If there are any, they will be shown in the table. If there were any it is necessary to remove them by clicking on **Remove alt. locations**. You can also perform other checks for your system if necessary, e.g. check bond lengths, non-standard residues, and clashes. Tip: remove water Alternatively, you can **remove water** as follows: click on **Select > Water** to select it in the document, and then click on the **Current selection** in the **Document view** and choose **Erase selection** in the context menu or click on delete in the pop-up context toolbar. Tip: remove ions Alternatively, you can **remove monatomic ions** as follows: click on **Select > Ions > Monatomic ions** to select them in the document and then click on the **Current selection** in the **Document view** and choose **Erase selection** in the context menu or click on delete in the pop-up context toolbar. Tip: add hydrogens Alternatively, you can **add hydrogens** to a system using **Edit > Add hydrogens** - this will add hydrogens for the standard pH based on amino acid types and valences. To add hydrogens to only to a part of the system, select this part and then click on **Edit > Add hydrogens**. Note, that we don't necessarily need to minimize the structure after adding hydrogens since AutoDock Vina needs only polar hydrogens for determining hydrogen bonds. Tip: visualization If you don't 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/) 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 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 of the cases. In this mode, about 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 on **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/). **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 specified the necessary parameters click on the **Run docking** button. For the system in the tutorial the docking should take about 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](../../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). Please do not hesitate to write on our [Forum](https://forum.samson-connect.net/) if you have any questions or feedback. # Ligand Path Finder From this tutorial you will learn how to use the [Ligand Path Finder](https://www.samson-connect.net/extensions/280cac50-31cd-e0ad-76c3-d254cd736967) app for finding possible ligand unbinding pathways from a protein. The **Ligand Path Finder** applies the **ART-RRT method** for finding ligand unbinding pathways from a protein. The ART-RRT method is a combination of the **T-RRT** method and the **ARAP modeling** method [1](#fn:1). The T-RRT method is used for finding possible pathways and the ARAP modeling method is for generating possible ligand motions. Moreover, a **constrained minimization** is used for adapting the motion of the protein with the ligand. ## 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 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 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 also can 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, add hydrogens) - for that you can use **Home > Prepare**. ## 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/) 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, 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/) 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/)). 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/). 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 unbindings 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/). 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 unbindings 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](../../pathlines/pathlines/) 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](../../pneb/optimize-transition-paths-with-parallel-nudged-elastic-band/) 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](../../export-along-path/export-atoms-trajectories-along-paths/) for more information. If you have any questions or feedback, please use the [SAMSON Connect Forum](https://forum.samson-connect.net/). ## 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") # Creating coarse-grained models for the MARTINI force field using Martinize2 The [Martinize2](https://www.samson-connect.net/extensions/0753f4e9-00ce-ae5b-eefd-d95f3e0c29bd) SAMSON Extension uses [Martinize2 and Vermouth](https://github.com/marrink-lab/vermouth-martinize) [1](#fn:1) and makes it possible to create coarse-grained (CG) structures and topologies (e.g., for GROMACS) from an atomistic structures for the MARTINI force field [2](#fn:2). 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 to speed up simulations by several times. ## Creating CG model from atomic structure Let's see how to create CG structures and topologies on an example of the Ubiquitin protein ([1UBQ](https://www.rcsb.org/structure/1UBQ)). 1. Load in 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 format: PDB, mmCIF/PDBX, mmTF. 1. Prepare the protein system(s) using **Home menu > Prepare**. Choose to remove alternate locations, water, ions, ligands, and other molecules used for crystallization. 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 tool tips. 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](../../molecular-box-builder/molecular-box-builder/), 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 check box of the structural model as shown on 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/) 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've 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/) Tip Save the system into a file to store your work. ### Next Once you have your [replicas created](#creating-replicas) and [ensure unique numbering and naming](#renumber-chains-and-residues), you can then proceed with the same steps as in the [Creating CG model from atomic structure](#creating-cg-model-from-atomic-structure) section. ## See also For the documentation on [Martinize2 and Vermouth](https://github.com/marrink-lab/vermouth-martinize) see . ## 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 [Molecular Box Builder](https://www.samson-connect.net/extensions/3d8237a4-d3a0-942b-a6b0-9baa049cb195) makes it possible to construct systems by placing molecules in a box or filling a box with molecules. 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. ## Setting a molecule [Select](https://documentation.samson-connect.net/users/latest/selecting/) a system with which you would like to populate a box in the **Document view** or in the *Viewport*. The system can be a single molecule or a set of molecules (structural models, molecules, chains, structural groups, residues, or atoms). Click on the **Set** button. Click the **Select** buttons to highlight the structure or start/end atoms. Click the **X** button to clear the currently set molecule. You can specify how to align a molecule when adding it to the box. If no alignment is chosen, then the molecule will be duplicated in its original orientation. When alignment is chosen then it aligns the molecule’s first principal axis (the first eigenvector of the moment of inertia) with the chosen axis direction. Note that you can choose, for example, +X/-X to change the orientation along the axis. The *molecule box size* is automatically computed based on the bounding box of the molecule in the chosen alignment or in its original orientation if no alignment was chosen. ## Setting a box Specify the size of the box. By default, the box is positioned in such a way that its corner is aligned with the origin. If you want to move the box, check the **Center** option, and move the center of the box. The molecule will be placed in the box such that there will be no clashes between them. If you would like, you can specify the margin between the molecules – it can be positive or negative. When you change the size of the box or the margin between molecules, the predicted number of molecules that can be placed in the box in each direction (and their total number) is updated in the **Generate** part. You can always show/hide the box by pressing the corresponding buttons. ## Generating a system The predicted number of molecules that can be placed in the box in each direction (and their total number) is shown in the *Generate* part. If you would like to limit the number of molecules that will be put in the box, then check the **Maximum number of molecules to generate** option and specify this number. Else, it will place as many molecules as possible in the box, which should be equivalent to the predicted number. To generate a system, press the **Generate** button. Depending on the size of the system, the generation should take a few seconds. ## Generating a lipid layer around a protein This app can also be used to generate lipid membranes around proteins. Let's for example build a single layer of lipids around the copper-transporting PIB-ATPase ([4BBJ](https://www.rcsb.org/structure/4bbj)). First, we need to reorient the protein. For that, right-click on the protein in the **Document view**, and in the context menu click on **Move selection > Align with Z axis**. Then in the same context menu click on **Move selection > Center on the origin**. Now, import a lipid. Then select it and set it as the molecule in the **Molecular Box Builder** app and choose to align its principal axis with the Z axis (e.g., +Z). Now, we need to specify the box. Set the size of the box and click to center it and move the center to position the box where you would like lipids to be generated with respect to the protein. You can also specify the margin between the inserted molecules if needed. Note: the predicted number of molecules that can be placed in the box in each direction is shown in the **Generate** part. In the Generate part, choose the **Consider existing molecules in the box** option to not put lipids on top of the protein. Now, click **Generate**. And you should have a single layer of lipids around the protein. Now, you can 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](../../gromacs-wizard/)). If you would like to create a **lipid bilayer**, then, first, add one layer with e.g. +Z alignment of molecules and then add another layer with the center of the box shifted in Z-direction with the opposite alignment (e.g., -Z). Note You can always **move and rotate** the system in SAMSON using the [Move editors](https://documentation.samson-connect.net/users/latest/moving-objects/). If you have any questions, please do not hesitate to contact us via our [forum](https://forum.samson-connect.net/). # Building carbon nanotube models From this tutorial you will learn how to easily generate carbon nanotube (CNT) models within SAMSON. ## Nanotube creator Carbon nanotubes (CNT) can be generated in SAMSON using the [Nanotube Creator](https://www.samson-connect.net/extensions/1ebd1e1c-2f89-62bd-02c2-08216dcbd60b) SAMSON Extension. If you don't have it installed, log in on [SAMSON Connect](https://www.samson-connect.net) and install it from the Markeplace. The [Nanotube Creator](https://www.samson-connect.net/extensions/1ebd1e1c-2f89-62bd-02c2-08216dcbd60b) provides an *editor*, i.e. a tool that [responds to mouse and keyboard events](https://documentation.samson-connect.net/users/latest/editors/), that allows you to create carbon nanotubes with two mouse clicks. In SAMSON, only one editor is active at any time, so you first need to activate the nanotube creator editor via the left-side menu in the viewport **... > Materials > Nanotube creator** or using the *Find everything...* (`Shift`+`E`) search box in the top menu of SAMSON. ## Building nanotubes You have two main ways to create nanotubes: - interactively in the viewport with the mouse, - with the nanotube creator graphical interface. ### Interactive nanotubes building You can interactively build nanotubes in the viewport in two steps: 1. Set the nanotube axis and length (`n` parameter): press and drag the left mouse button inside the viewport: During this step, the status bar gives you some information about the current structure, e.g.: 1. Set the nanotube radius (`m` parameters): 1. release the left mouse button, 1. move the mouse to change `m`, 1. click the left mouse button again to accept Make sure you check the status bar during this step as well to precisely choose the `n` and `m` parameters. ### Building nanotubes using graphical interface If you want to precisely control the axis position, length, and radius, thenthe best option might be to directly enter parameters in the editor's interface. To show the editor's interface (if it is not already visible), activate the editor. You should see the following: Note: selecting an editor alternatively shows and hides its GUI. Using the GUI, you may easily create multi-walled nanotubes. For example, try `(0, 0, 0)` and `(40, 0, 0)` for the beginning and end positions of the nanotube's axis, respectively, to produce a nanotube with length of 40 Å. Then: 1. Set `n` and `m` to 6. Click *Build*. 1. Set `n` and `m` to 10. Click *Build*. 1. Set `n` and `m` to 14. Click *Build*. This will produce the multi-walled nanotube below: ## To go further Now that you know how to produce nanotubes models, you may want to produce [images of them for publications](https://documentation.samson-connect.net/users/latest/visualizing/), or [interactively simulate nanotubes with the Brenner potential](https://documentation.samson-connect.net/users/latest/modeling-and-simulation/#building-a-carbon-nanopore) to build more complex objects. Have fun, and don't hesitate to use the [SAMSON Connect Forum](https://forum.samson-connect.net/) if you have any questions! # Computing normal modes that open a binding site In this tutorial, we will present you the functionalities of the [Normal Modes Advanced](https://www.samson-connect.net/extensions/589e13f2-183c-a8c4-3dcd-66b6b807520c) (*NMA*) SAMSON Extension. This SAMSON Extension is an advanced version of the [Normal Modes Analysis](https://www.samson-connect.net/extensions/4bd07765-ab03-bade-11d6-35c1c8739fbf) SAMSON Extension also available on [SAMSON Connect](https://www.samson-connect.net). This SAMSON Extension computes nonlinear normal modes of a biomolecular system (protein, RNA, DNA) very quickly 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)). First, you have to import a structure. For this tutorial we used the [1VPK](https://www.rcsb.org/structure/1vpk) PDB entry. Then, you launch the NMA module and indicate the desired number of modes, interactions cutoff distance, and potential function. For now, the elastic network model potential is the one that is available but more potential functions, like the Gaussian network model, will be added in the future. You can compute normal modes on a group of residues (that may be easily selected using SAMSON's [selection filter](https://documentation.samson-connect.net/users/latest/selecting/)) or on the entire structure by [selecting](https://documentation.samson-connect.net/users/latest/selecting/) the structure in the **Document view**. 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 modes 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 non-linear (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 we 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. We 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. If you have any questions or feedback, please use the [SAMSON Connect Forum](https://forum.samson-connect.net/). # Predicting protein-ligand complexes using NMR2 Nuclear Magnetic Resonance (NMR) spectroscopy is a powerful and versatile analytical tool extensively used in chemistry and biology to determine the structure of molecules, including protein-ligand complexes. Unlike X-ray crystallography that requires crystalline samples, NMR spectroscopy can analyze molecules in solution, closely mimicking physiological conditions. This makes NMR particularly suited for studying interactions between proteins and ligands. This tutorial demonstrates how to use [the integration of NMR2](https://www.samson-connect.net/extensions/6150c6f4-d891-b58b-a8b5-dbc197087841), a method developed by [Prof. Dr. Julien Orts](https://pharmchem.univie.ac.at/research/staff-members-by-name/orts-julien/) from Vienna University, into SAMSON. By leveraging NMR2 within SAMSON, researchers can more easily interpret NMR data to elucidate the structure of protein-ligand complexes, advance the understanding of molecular interactions, and facilitate the development of novel therapeutics. ## Adding the NMR2 extension To follow this tutorial, make sure you [add the NMR2 extension](https://www.samson-connect.net/extensions/6150c6f4-d891-b58b-a8b5-dbc197087841) to your account, and restart your SAMSON to have it automatically installed. Important The NMR2 extension requires an active license of **Cyana**, which is available from [L.A. Systems](https://www.las.jp/english/cyana.html). ## Obtaining 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) ## Setting 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 reenter them the next time your start SAMSON. ## Setting up 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 which 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 Angstrom. 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 how 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 degrees tolerance in the side chain of residue 130 and a 10 degrees 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 degrees 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. 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 methyls 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 (methyls 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 ligands positions: You can then hide and show these structures using the **Document view**, and use other extensions for analysis, simulation, etc. Congrats on completing this tutorial! Let us know if you have any questions. # Pathlines: show a path of the center of mass of an atomic system From this tutorial you will learn how to create pathlines thanks to the [Pathlines](https://www.samson-connect.net/extensions/d319e2f3-0afc-07ab-0b64-71eb19d7ee2f) visual model. Pathlines are [visual models](https://documentation.samson-connect.net/users/latest/models/#visual-models) which represent the trajectory of the center of mass of the selected atoms along selected trajecotories (paths). Pathlines may be used to understand the motion of a group of atoms (or a single atom) along a path/trajectory. 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 a structural model of *Lactose permease* 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](../../ligand-path-finder/ligand-path-finder/)). 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` To create pathlines, select in the **Document view** a group of atoms for which you want to visualize the motion of their center of mass and select one or more paths (to select more than one node, use the `Ctrl` / `Cmd` key). If no path is chosen, all the paths from the active document will be used. If no atoms are selected, all atoms from the active document will be used. Select the ligand named *TDG*. Go to **Visualization > Visual model > More...** (1) to create a [visual model](https://documentation.samson-connect.net/users/latest/models/#visual-models). In the pop-up window, choose **Pathline of the center of mass** and press **OK**. 1. , : ++ctrl+shiftv++, : `Cmd`+`Shift`+`V` The new pathline will show how the center of mass of the *TDG* ligand moves alongside the chosen path. 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`""" You can modify the thickness and color of a pathline in the [Inspector](https://documentation.samson-connect.net/users/latest/inspecting/) by [selecting](https://documentation.samson-connect.net/users/latest/selecting/) a pathline. Note If you delete a Path, the corresponding pathline will be deleted too. If you delete some of the atoms for which a pathline was created, the pathline will be modified. 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](../../pneb/optimize-transition-paths-with-parallel-nudged-elastic-band/). If you have any questions or feedback, please use the [SAMSON Connect Forum](https://forum.samson-connect.net/). # Optimize transition paths with the Parallel Nudged Elastic Band method The **Nudged Elastic Band** (NEB) method allows for finding saddle points and minimum energy paths between known conformations. The method optimizes a number of intermediate images along the path by finding the lowest possible energy for each image while maintaining equal spacing between neighboring images. This constrained optimization is done by adding 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) (Parallel Nudged Elastic Band) app implements the climbing image nudged elastic band (NEB) 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](../../ligand-path-finder/ligand-path-finder/). ## 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](../../ligand-path-finder/ligand-path-finder/). 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**. The P-NEB app has the following settings: - **Spring constant**: the spring coefficient. Enter 1.00. - **Number of loops**: the number of optimisations 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 optimisation 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 optimisation 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. If you have any questions or feedback, please use the [SAMSON Connect Forum](https://forum.samson-connect.net/). ## 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") # Construct polymers with Polymer Builder [Polymer Builder](https://www.samson-connect.net/extensions/4593e178-6d31-49ba-f3bb-3a91215f7117) makes it possible to construct polymers out of various building blocks: individual monomers and sequences of monomers. The [Polymer Builder](https://www.samson-connect.net/extensions/4593e178-6d31-49ba-f3bb-3a91215f7117) app can be found in the **Home > Apps > Assembly** or via the **Find everything...** (`Shift`+`E`) in the top menu of SAMSON. ## Registering new monomers In the [Document view](https://documentation.samson-connect.net/users/latest/first-look/) or in the [Viewport](https://documentation.samson-connect.net/users/latest/first-look/), [select](https://documentation.samson-connect.net/users/latest/selecting/) a monomer that you would like to add. Click on the **Register monomer from selection** button to add a new monomer based on the current selection. It will automatically set the structure and start and end atoms based on the connected component such that the start and end atoms would be at the opposite ends of the component. Click the associated **V** buttons to highlight the structure or start/end atoms. You can **modify the start and end atoms** by choosing another atom of this monomer from the **Document view** or from the **Viewport** and clicking on the corresponding **S** (*set*) button. Or, you can click on the associated **P** (*pick*) buttons to pick an atom from the list of atoms in the structure. 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. The molecular weight (in Daltons) and the distance between the start and the end atoms will be shown in the table for each monomer. The added monomers are automatically given unique identifiers based on Latin letters. 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 due to these changes. You can modify the already registered monomers right in the table, expand them if necessary. To remove a monomer from the table, right-click on it and click **Delete monomer**. To clear the whole table, click on the **Clear all** button. ## Registering sequences of monomers If the polymer sequence that you would like to generate has repeating patterns, then you can also register such patterns as sequences of monomers. To register a new sequence of monomers, click on the **Add new sequence** and provide the sequence in the **Sequence** property based on identifiers of the registered monomers, e.g., `ABBA`: Click the associated **V** button to highlight the monomers used in the sequence. If the sequence is not correct, then the error message will be shown in the **Status** property, else it will be shown as **Valid**: The added sequences are automatically given unique identifiers that start with the letter S and follow with a number, e.g., S1, S2, etc. If you would like the monomers in a sequence to be arranged into a common parent structural group in a generated polymer, then provide a name in the **Name** property. You can specify the bond types between monomers. By default, the monomers are connected with a single bond. To connect them with a double bond, use '`=`', and for a triple bond use '`#`': `A=B` - A connected by a double bond with B `A#B` - A connected by a triple bond with B 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 on the **Clear all** button. ## Generating polymers To generate a polymer, provide its sequence based on registered monomers and sequences of monomers. 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 For a provided sequence, its approximate molecular weight and length and predicted that are based on each monomer. Click the **Generate polymer** button to generate a polymer based on the provided sequence. The app will generate a polymer with a shape based on directions between the start and end atoms of each monomer. Excessive hydrogens are removed from the start and end atoms that participate in connections. There are 2 additional options that can be used when generating a polymer: - **Adjust Hydrogens on connection atoms** – if checked then hydrogens will be adjusted for each connection atom (start and end atoms of monomers) to adjust their positioning. Note: this will remove and add hydrogens based on the valences of the start and end atoms of the monomers. 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/) for more information). - **Adjust for clashes** – if checked then each next monomer will be added in such a way that it has minimum clashes with other already placed monomers of the polymer. Note: this might lead to non-linear polymers. Tip You can use the generated polymer as a monomer for building longer polymers. ## Minimizing structures Once you built the polymer, you might want to minimize it. You can do it using the built-in minimizer in SAMSON. For that, simply click on **Edit > Minimize**, and click it once again to stop the minimization. Note The built-in minimizer in SAMSON uses the [Universal Force Field](https://www.samson-connect.net/extensions/8cbdc8b1-59e1-6459-d68f-b840275dd5e9). ## Saving and loading projects If you would like to export the resulting structure, [select](https://documentation.samson-connect.net/users/latest/selecting/) it and then click on **Home > File > Save selection as...**. You can also save the project and load it later. This will save/load monomers and sequences of monomers. If you have any questions, please do not hesitate to contact us via our [forum](https://forum.samson-connect.net/). # Aligning proteins From this tutorial you will learn how to use the [Protein Aligner](https://www.samson-connect.net/extensions/0bee42d5-181b-b366-39a5-36607f0b5731) extension to **align both sequences and structures of proteins**. Note This extension is included with all the plans and can be accessed via **Home > Align**. Open SAMSON and use **Home > Fetch** to fetch two proteins: `1DLW` and `1RTX`. Those two are hemoglobin proteins from different organisms. Tip If you want to remove water, ligands, alternate locations, you can use **Home > Prepare**. To open the **Protein Aligner**, click **Home > Align** . ## Aligning sequences You can align sequences in two ways: - **Align sequences (by structure)** - aligns the sequences per structural model. - **Align sequences (by chain)** - aligns the sequences per chain (there can be multiple chains per model). Click on any **Align sequences** button and you should see the sequence alignment has been made like this: 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 the conserved residues) and polarity of amino acid residues. Note If a residue has multiple properties that are currently checked, then its color will be a combination of the colors of these properties, as can be seen from the image above. You can hover above the sequences to see the residue name and ID: When you hover above a sequence, the corresponding structure is highlighted in the viewport. The residues in the shown sequences are selectable and are linked to the residues in the viewport: - click on a residue in the sequence for it and resiudes aligned to it to be selected; - hold `Shift` to select multiple residues consecutively; - 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 will automatically highlight this residue in the Protein Aligner and all the residues aligned to it. ## Aligning structures Now, let's perform a structural alignment of these two proteins. Make sure that no residue is selected then click on **Align to this**, on the first row. Now, the other button indicates the distance between the two proteins: 3.27 Å. The two structures should be superimposed like this: Tip If you don't have secondary structures shown, you can add them via **Visualization > Visual model > Ribbons**. To add a separate Ribbons visual model per structure, e.g. for the sake of colorizing them in different color, select the structure first and then apply a visual model. This should help to differentiate the aligned structures. You can also hide/show the atomistic representation by toggling the boxes in front of the protein structure in the **Document view**. 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 the Protein Aligner and select the twenty first residues like this: Click on any button for alignment on the right-side of the sequence (e.g., click on the button with 0.0 Å) to superimpose specifically those residues of the structure. If you have any questions or feedback, please use the [SAMSON Connect Forum](https://forum.samson-connect.net/). # Protein Path Finder From this tutorial you will learn how to use the [Protein Path Finder](https://www.samson-connect.net/extensions/b6f693c9-2c71-7573-abdd-8d288a35383f) app for finding possible paths between two conformations of a protein. The **Protein Path Finder** applies the **ART-RRT method** for finding protein conformational transition paths of a protein. The ART-RRT method is a combination of the **T-RRT method** and the **ARAP methods** [1](#fn:1). The T-RRT method is used for finding possible pathways and the ARAP modeling method is for probing possible protein motions. Moreover, a **constrained minimization** is used for minimizing protein motions. ## 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` Note For your own model, you might need to first prepare it (remove alternate locations, add hydrogens, remove solvent) - for that you can use **Home > Prepare**. ## 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/) 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, 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/) expression: `("CA" in "GLY 12") or ("CA" in "ARG 123")`. See also [User guide - Selecting](https://documentation.samson-connect.net/users/latest/selecting/). 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](../../pathlines/pathlines/) 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 Bands (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](../../pneb/optimize-transition-paths-with-parallel-nudged-elastic-band/) for more information. ### Export atoms trajectories along paths The resulting paths can be saved in .sam or .samx format. 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](../../export-along-path/export-atoms-trajectories-along-paths/) for more details. If you have any questions or feedback, please use the [SAMSON Connect Forum](https://forum.samson-connect.net/). ## 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") # Interactive Ramachandran Plot The Ramachandran plot is a way to **visualize energetically allowed regions for backbone dihedral angles ψ against φ of amino acid residues** in protein structure. From this tutorial, you will learn how to use the [Interactive Ramachandran Plot](https://www.samson-connect.net/extensions/dc71fbbe-4289-759b-2369-9ebb29e3c3fb) SAMSON extension. First, go to [SAMSON Connect](https://www.samson-connect.net), log in, and add the [Interactive Ramachandran Plot](https://www.samson-connect.net/extensions/dc71fbbe-4289-759b-2369-9ebb29e3c3fb) SAMSON extension from the Markeplace. For this tutorial, you can open any protein you like. We will be using 1YRF. You can use **Home > Fetch** to fetch structures from the RCSB Protein Data Bank. Once you loaded a protein, open the Ramachandran Plot app (**Home > Apps > Biology >** **Ramachandran plot** ) and click *Update* to obtain a plot like this one: The white regions represent the energetically unfavoured conformations, and the yellow regions - the favored ones. There are four tabs to represent different categories of residues: the glycine and the proline that take specific conformations, the pre-proline residues are the ones just before a proline in the amino acid chain, which generally means every other type of residue. Here, all the residues are well placed. To visualize one particular residue let's click on it directly on the plot (here with the proline): The residue become selected in the viewport and the status bar displays information about the dihedral angles of the residue: If you drag and drop the residue on this plot window, the dihedral angles are updated in the viewport, and the protein is transformed. This is an undoable action so if you're not satisfied with the result, just press `Ctrl`+`Z`. The other way also works: select the Twister editor from the left-side menu in the viewport and then play with the protein and see what happens to the plot. A small challenge to finish, reload 1YRF, compute the 10 first normal modes (see the tutorial on [Calculating non-linear normal modes](../../nma/calculating-non-linear-normal-modes/) to learn how to use the [NMA SAMSON Extension](https://www.samson-connect.net/extensions/4bd07765-ab03-bade-11d6-35c1c8739fbf)), put the scaling factor to 1, and the first mode completely to the left like this: Then try to adjust all modes so that all the residues are in favored configurations in the [Ramachandran Plot](https://www.samson-connect.net/extensions/dc71fbbe-4289-759b-2369-9ebb29e3c3fb). If you have any questions or feedback, please use the [SAMSON Connect Forum](https://forum.samson-connect.net/). # Coronavirus: computing the opening motion of the SARS-CoV-2 spike In this small article, we provide a brief introduction about the way the SARS coronavirus 2 (SARS-CoV-2) operates, and we provide results of our computations of the motion of its spike from its closed state to its open, receptor-binding state. ## Introduction 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 as 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 like from the side view and from the top view. *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 are using sugars to defend themselves from the host immune system. This works as a disguise because many of our cells are coated with sugars and our immune system recognizes these sugars and does not attack them. But the SARS-CoV-2 does not have sugars on top of its spikes to be able to recognize the receptor molecule and bind to it. This makes the top part of the spike – the binding part – the main target of antibodies. Neutralizing antibodies bind to the top part of the spike and once the neutralizing antibodies are there, the virus can no longer recognize the receptor molecule and infiltrate the host cell, and thus it can no longer reproduce itself. 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 which 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). ## 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 the Batman's batarang at the nanoscale? Maybe it won't fight cancer or viruses, but every scientist, like a hero, needs tools to work on their cause. In this tutorial, we introduce two such tools that can be used for creating nano-batarangs and other complex-shaped objects at the atomic level by selecting atoms and modifying some of their properties using mathematical expressions and scripting language. ## 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/), but only for atoms. The difference of this Extension's scripting language with 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 belongs 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 next 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 an 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). If you have any questions or feedback, please use the [SAMSON Connect Forum](https://forum.samson-connect.net/). # Perform Positional Analogue Scanning using the SMILES Manager From this tutorial you will learn how to run a simple but powerful technique, called positional analogue scanning, in order to generate new analogs of your molecules directly in SAMSON using the [SMILES Manager](https://www.samson-connect.net/extensions/ce09650a-c071-4e84-1f6a-b8706937d5c1) extension. This new functionality was inspired by the Pat Walter's [blog post](https://practicalcheminformatics.blogspot.com/2020/04/positional-analogue-scanning.html) and this [paper](https://pubs.acs.org/doi/10.1021/acs.jmedchem.9b02092) from Lewis Pennington, Ingo Muegge, and coworkers. It will allow you to evaluate the effects of newly introduced changes of your molecules on their properties, like the binding affinity (using [Autodock Vina Extended](https://www.samson-connect.net/extensions/1afc50e6-3567-fa25-1e09-415ebf4d05d7) SAMSON extension) or by looking at their key interactions with a target protein directly in SAMSON. For the purpose of this tutorial, let's consider the case presented in the previously cited paper with the corresponding SMILES code: `CN1C=C(C(=O)Nc2ccc(-c3ccccc3)c(c2)C(F)(F)F)C(=O)c2ccccc12`. ## 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 on the *Use selection* button like in the gif below. ## Define your searched pattern Search in the initial structure the pattern you want to replace or to which you want to attach new a 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 on 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 bigger window. You can also do that by right clicking on the image and clicking on 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 3D structure of a specific analogue: right-click on the image of your analogue of interest and choose generate 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 on *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. Don't hesitate to give us your feedback on this new feature either on the [forum](https://forum.samson-connect.net/) or by reaching out to us by [email](mailto:contact@samson-connect.net). # Using the SMILES Manager From this tutorial you will learn how to use the [SMILES Manager](https://www.samson-connect.net/extensions/ce09650a-c071-4e84-1f6a-b8706937d5c1) extension of SAMSON. This extension is based on [RDKit](https://www.rdkit.org/docs/index.html). RDKit is a widely used open-source toolkit for cheminformatics. One of its features is the conversion of molecules SMILES strings to 2D and 3D structures. The extension interface presents three tabs: *Manage SMILES*, *Replace fragments*, and *Positional Analogue Scanning*. In this tutorial, we will present the first two sections one by one as they are totally independent. For the Positional Analogue Scanning, please check the [Positional Analogue Scanning using the SMILES Manager Extension tutorial](../perform-positional-analogue-scanning-using-the-smiles-manager-element/). In each of the first two tabs, you can find a menu bar that contains all the actions with corresponding shortcuts. SMILES strings are presented in a table with their corresponding names and 2D conformation images. ## Manage SMILES ### Import SMILES You can import SMILES files (.smi) or text files (.txt) containing SMILES strings by clicking on *Open* from the *File* drop-down menu located in the menu bar of the extension. The SMILES files must have the RDKit .smi format (image below) with a SMILES string in the first column and a molecule name in the second column. ``` 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 ``` RDKit SMILES files containing additional attributes (as in the image below) are also supported but these attributes will be ignored. `SMILES Attribute Name CC 2 Mol1 C=C 5 Mol2 [CH+2]C[CH+2] 100 Mol3` Also, text files (.txt) containing SMILES strings as shown below can 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 It is possible to manually add SMILES strings using the *Add line* action from the *Edit* drop-down menu or using the *Add* button just below the SMILES table. In the same way, each line can be removed and the table can be cleared. The SMILES string can be easily modified by modifying the corresponding *Code* cell in the table. 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 unique window using the navigation buttons. For large molecules, it is possible to zoom in/out 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 on *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 on 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 very useful to quickly generate 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 right bottom 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 be using 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 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](../perform-positional-analogue-scanning-using-the-smiles-manager-element/). If you have any questions or feedback, please use the [SAMSON Connect Forum](https://forum.samson-connect.net/). # Computing axes of symmetry of biological assemblies The [Symmetry Detection](https://samson-connect.net/extensions/0a53a840-a147-12f8-29b1-b074a4041978) Extension computes the axes of symmetry of biological assemblies. It supports detection of cyclic and dihedral symmetries of any order, as well as cubic symmetries (tetrahedral, octahedral, and icosahedral). Here is an example with an icosahedral capsid `3NQ4`: Here with `1CHP`, just start the [Symmetry Detection App](https://samson-connect.net/extensions/0a53a840-a147-12f8-29b1-b074a4041978) and compute the symmetry: For large assemblies, automatic symmetry detection may detect several different symmetries. Click on the one that is interesting (typically the one with the higher order and a small RMSD) to visualize the axis. In this example, we use `1B4B` which has a dihedral symmetry of order 3: Another possibility is to provide the symmetry group: Such a symmetry group has several axes which can be browsed by expanding the symmetry group. For each axis, the corresponding RMSD is computed. To visualize a particular axis, click on it in the App interface, and it becomes bold in the viewport. A double-click aligns the camera axis with the symmetry axis: If you have any questions or feedback, please use the [SAMSON Connect Forum](https://forum.samson-connect.net/). # Generating symmetry mates The [Symmetry Mate Editor](https://www.samson-connect.net/extensions/d5c311da-ad75-2934-8845-79b38b289ff8) helps to generate symmetric replicas of a protein based on the information contained in a PDB file. 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). To add the [Symmetry Mate Editor](https://www.samson-connect.net/extensions/d5c311da-ad75-2934-8845-79b38b289ff8) to your SAMSON, sign in on [SAMSON Connect](https://www.samson-connect.net) and click the 'Add' button on the [extension page](https://www.samson-connect.net/extensions/d5c311da-ad75-2934-8845-79b38b289ff8). Then, simply restart your SAMSON to have the extension automatically installed. Once in SAMSON, use the top search box (`Shift`+`E`) to find the editor or access it via the left-side menu in the viewport (**... > General > Symmetry Mate Editor**): When this editor is selected, control nodes appear in the viewport. Use `Ctrl`/`Cmd` + `mouse wheel` to see more or fewer of these control nodes. Here is an example with `1BRE`: When the mouse moves over a control node, a preview of the corresponding replica is shown: By left clicking on a control node, the replica is created. This way, in a few clicks, you can generate a complex structure: This editor handles CRYST1 (white widgets) and BIOMT (yellow widget) records. Switch from one to the other with the editor GUI. Here is an example with `1B5S`: To preview and create all replicas simultaneously, press and hold `Ctrl`/`Cmd` before hovering and left-clicking a control node: If you have any questions or feedback, please use the [SAMSON Connect Forum](https://forum.samson-connect.net/). # Interactive Modeling Universal Force Field From this tutorial you will learn the basics about the [Interactive Modeling Universal Force Field (IM-UFF) interaction model](https://www.samson-connect.net/extensions/27d95098-31ee-df2b-e559-af1bc98a3500). We previously proposed [1](#fn:1) [a new implementation of the Universal Force Field (UFF) interaction model](../uff/) 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 interested, please refer to the [UFF tutorial](../uff/). 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 of 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. ## 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](../../fire/ready-set-fire/)). - Press the **OK** button. Contrarily to 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 slightly the atoms, 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 in consequence. On the contrary, when the atom location gets closer to some atoms, bonds can form to create and a new topology can appear. ## 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](../uff/) 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 ones again be found in our [previous post](../uff/) describing the UFF interaction model. However, note that when IM-UFF is running (ie. 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](../uff/) describing the UFF interaction model. If you have any questions or feedback, please use the [SAMSON Connect Forum](https://forum.samson-connect.net/). ## 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 From this tutorial you will learn the basics about the [Universal Force Field (UFF) interaction model](https://www.samson-connect.net/extensions/8cbdc8b1-59e1-6459-d68f-b840275dd5e9). 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 directly be applied on 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). ## Setting UFF - Open a document with a molecular system you want to simulate with UFF. - Add a simulator via **Edit > Simulate > Add simulator** (or use the shortcut `Ctrl`+`Shift`+`M` / `Cmd`+`Shift`+`M`). - Select *Universal Force Field* in the list of interaction models. - Choose the state updater you want to rely on for the simulation (e.g., [FIRE](../../fire/ready-set-fire/)). - 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 to 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/) and see how the UFF model reacts by updating the position of the other atoms in consequence. The UFF interface allows you to modify the following UFF parameters: - the type of bond stretch interaction: tt 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 bonds the distance for which vdW interaction 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 do 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" ie. 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 on how to build systems from [User Guide: Building molecules](https://documentation.samson-connect.net/users/latest/building-molecules/) 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). If you have any questions or feedback, please use the [SAMSON Connect Forum](https://forum.samson-connect.net/). ## 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") # Scripting Guides # Python Scripting Guides Learn how to use SAMSON's functionality through the integrated Python console and the SAMSON Python API: [Python Scripting Guide for the latest version (v.7.x.x)](https://documentation.samson-connect.net/scripting/latest/) Python Scripting Guides for older versions - [6.x.x](https://documentation.samson-connect.net/scripting/6.0.0/) - [5.0.0](https://documentation.samson-connect.net/scripting/5.0.0/) - [4.0.3](https://documentation.samson-connect.net/scripting/4.0.3/) - [1.0.1](https://documentation.samson-connect.net/scripting/1.0.1/) - [0.12.2](https://documentation.samson-connect.net/scripting/0.12.2/) - [0.11.0](https://documentation.samson-connect.net/scripting/0.11.0/) - [0.8.5](https://documentation.samson-connect.net/scripting/0.8.5/) - [0.8.4](https://documentation.samson-connect.net/scripting/0.8.4/) - [0.8.1](https://documentation.samson-connect.net/scripting/0.8.1/) - [0.7.5](https://documentation.samson-connect.net/scripting/0.7.5/) Guides for older versions of the Python Scripting Extension were archived. # Developing extensions # Developing SAMSON Extensions SAMSON has an open architecture which allows anyone to extend it - and adapt it to their needs - by downloading SAMSON Extensions (modules) from the [SAMSON Connect](https://www.samson-connect.net/) website or by developing your own SAMSON Extensions and distributing them privately or publicly. 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/) - [**C++**](cpp/) ______________________________________________________________________ Get started with SAMSON C++ SDK. - [**Python**](python/) ______________________________________________________________________ Get started with SAMSON Python API. # C++ # Developing SAMSON Extensions in C++ SAMSON provides a powerful C++ SDK that lets you develop extensions of various types: apps, editors, force fields, visualizations, parsers, etc. See the [SAMSON Developer Guide](https://documentation.samson-connect.net/developers/latest/). ## 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 in 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++. # C++ Developer Guides # Developer Guides Learn how to create your own SAMSON Extensions in C++ and distribute them via [SAMSON Connect](https://www.samson-connect.net/). [Developer Guide for the latest SAMSON SDK 2025 R1 (v. 7.0.0)](https://documentation.samson-connect.net/developers/latest/) Developer Guides for older versions of SAMSON SDK - [Developer Guide for SAMSON SDK 2024 R1 (v. 6.0.0)](https://documentation.samson-connect.net/developers/6.0.0/) - [Developer Guide for SAMSON SDK 2023 R1 (v. 5.0.0)](https://documentation.samson-connect.net/developers/5.0.0/) - [Developer Guide for SAMSON SDK 2022 R2 (v. 4.0.0)](https://documentation.samson-connect.net/developers/4.0.0/) - [Developer Guide for SAMSON SDK 2022 R1 (v. 3.0.0)](https://documentation.samson-connect.net/developers/3.0.0/) - [Developer Guide for SAMSON SDK 2021 R1 (v. 2.0.0)](https://documentation.samson-connect.net/developers/2.0.0/) - [Developer Guide for SAMSON SDK 2020 R3 (v. 1.0.0)](https://documentation.samson-connect.net/developers/1.0.0/) - [Developer Guide for SAMSON SDK 2020 R2 (v. 0.12.0)](https://documentation.samson-connect.net/developers/0.12.0/) - [Developer Guide for SAMSON SDK 2020 R1 (v. 0.11.0)](https://documentation.samson-connect.net/developers/0.11.0/) - [Developer Guide for SAMSON SDK 2020 R1 (v. 0.10.0)](https://documentation.samson-connect.net/developers/0.10.0/) - [Developer Guide for SAMSON SDK 0.8.5](https://documentation.samson-connect.net/developers/0.8.5/) - [Developer Guide for SAMSON SDK 0.8.4](https://documentation.samson-connect.net/developers/0.8.4/) - [Developer Guide for SAMSON SDK 0.8.3](https://documentation.samson-connect.net/developers/0.8.3/) - [Developer Guide for SAMSON SDK 0.8.2](https://documentation.samson-connect.net/developers/0.8.2/) - [Developer Guide for SAMSON SDK 0.8.1](https://documentation.samson-connect.net/developers/0.8.1/) - [Developer Guide for SAMSON SDK 0.7.0](https://documentation.samson-connect.net/developers/0.7.0/) Developer Guides for older versions were archived. # Python # Accessing SAMSON functionality via Python The [Python Scripting extension](https://www.samson-connect.net/extensions/7b654ce6-e38c-b97f-6746-4fd6934487c2) in SAMSON provides Python bindings for SAMSON API and an integrated Python console. It provides you with an access to most of the SAMSON SDK allowing you to access most of SAMSON’s functionality through Python scripting. Get started [User Guide: Scripting](https://documentation.samson-connect.net/users/latest/scripting/) You can use SAMSON Python API in multiple 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 on using SAMSON Python API.