A molecular model can be easy to share while the steps that produced or analyzed it are much harder to reproduce. A script may live in a separate folder, input files may be scattered across a project directory, and a colleague may not know which file to open first. Keeping relevant files together in a SAMSON document offers a practical way to make a workflow easier to inspect and pass along.
SAMSON documents can contain molecular models as well as embedded Python scripts, files, and folders. That means a document can serve as a compact handoff: the model and the materials needed to understand or continue the work can travel together. It does not remove the need to explain what the workflow does, but it can reduce the friction of finding its parts.
Build a document that explains itself
Before embedding files, decide what a colleague will need to make sense of the project. A useful starting set might include the molecular model, the script used for a particular task, and relevant input data or notes. Keep the contents focused: a small, clearly named set of files is generally easier to navigate than an unexplained collection.
To add files or folders, drag and drop them into SAMSON and respond to the prompt, or use Home > Embed files or Home > Embed folders. The selected material is stored inside the document. Once a Python script is embedded, double-click it to open it in the Code Editor.
Make the script easier to run and review
The Code Editor can open and modify text files, including Python scripts, and run Python files. Use Run in the editor or its Run menu to execute a script; for quick tests, you can also use the integrated Python Console. Both routes give access to the SAMSON Python API. The Console integrates a Jupyter Qt Console and is opened through Interface > Python Console.
For a handoff, add brief comments to the script explaining its purpose and any assumptions a reader should check, such as which model or input file it expects. This is good general scripting practice rather than a special SAMSON feature. If the workflow uses Python packages, make those requirements clear too: SAMSON’s Package Manager can install packages using pip, but embedding a script or folder is not the same as documenting how to install its package dependencies.
Use the handoff as a reproducibility check
Before sharing, try opening the document as if you were receiving it for the first time. Can you find the script? Is its purpose apparent? Are the inputs included or clearly identified? Is it clear how to run the code and where to look for its output? This simple review can reveal missing context before a colleague, student, or future version of you encounters it.
Embedded files and folders are stored within the document, which makes the document self-contained with respect to those embedded items. You can share it through email, GitHub, or SAMSON Connect Documents. Recipients can open the document, inspect its contents, and open an embedded Python script in the Code Editor. For teaching, the same approach can bring together a model, notes, and an interactive exercise; for research, it can keep analysis code close to the molecular structure it relates to.
For a broader scripting workflow—including the Python API, package management, templates, and ways to run scripts—see the SAMSON Scripting documentation.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON at samson-connect.net.