A molecular structure can look ready for evaluation and still produce confusing results: the wrong model task may be selected, a molecule’s charge or spin may be inconsistent with the intended system, or a periodic cell may need checking. Even the first run can cause uncertainty if the energy is temporarily unavailable while UMA starts up.
UMA in SAMSON offers interactive energy and force evaluation for geometry refinement, exploratory relaxation, and qualitative force analysis. A reliable workflow starts by matching the setup to the system, then checking the assumptions that most affect how you interpret the result.
1. Choose the task by system type
When you add a simulator through Edit > Simulate > Add simulator, select UMA Force Field and choose a state updater. The setup window then asks you to choose a model and a task. The task is not just a label: it should correspond to the kind of system you are evaluating.
- OMOL – Molecules: molecular systems. This is the only task whose interface uses total charge and spin multiplicity.
- OMAT – Inorganic materials: bulk inorganic materials workflows.
- ODAC – MOFs: MOFs and direct-air-capture-style adsorption workflows.
- OC20 – Catalysis: catalytic surfaces and adsorbates.
- OMC – Molecular crystals: molecular-crystal systems.
If you are unsure which model size to start with, the default practical choice is UMA-S (2.3 GB, v1.2). The extension also offers a lighter legacy UMA-S model (1.1 GB, v1.1) and the larger UMA-M model (11.7 GB, v1.1). Starting with UMA-S keeps the first workflow straightforward; choose UMA-M when you already have a reason to use the larger model.
2. Treat first-run setup as part of the workflow
Before creating the simulation, make sure the UMA Force Field and Python Scripting extensions are installed, and that the machine can install Python packages on first use. UMA may prepare a dedicated Python environment and request access to its models. That setup can take time. Follow the instructions displayed in SAMSON, and be prepared to create the interaction model again after setup finishes.
Once the environment is ready, start the simulation using Edit > Simulate > Start. The properties window may initially report that the energy is not available. Wait for the first evaluation to complete before treating that display as a problem: the total energy appears after a successful evaluation.
3. Check the inputs that change interpretation
For an OMOL calculation, set total charge and spin multiplicity to values consistent with the molecular system you intend to model. These are part of the request sent to UMA, so they should be deliberate rather than left as an afterthought.
For periodic workflows, inspect the periodic-boundary-conditions setting and the 3 × 3 cell matrix, expressed in angstroms. A cell that does not represent the system you mean to study can make the resulting evaluation difficult to interpret. Check it before drawing conclusions about a periodic structure.
4. Use bond updates as an exploration aid
The Bond update control determines how the bond graph is handled as the structure changes. Covalent recomputes covalent bonds from the current structure; Off leaves the existing graph unchanged. The estimated Wiberg and Mayer bond-order modes use a deep-learning model to estimate bond orders. They can help visualize changes during interactive exploration, but they are estimates—not a substitute for confirming important conclusions with a reference method.
This distinction is useful when moving atoms or refining geometry: a changing visualization can help you inspect what is happening, but it should not be treated on its own as proof of a chemical conclusion.
A compact pre-flight checklist
- Choose the task that matches the system.
- Start with UMA-S unless you have a reason to select UMA-M.
- For OMOL, verify charge and spin multiplicity.
- For periodic systems, verify the cell and boundary-condition setting.
- Allow the initial environment setup and first evaluation to finish.
- Use UMA to screen, refine, and explore; confirm final results with a higher-accuracy reference method when needed.
This checklist helps separate setup issues from scientific interpretation. It also keeps the role of the tool clear: UMA is useful for interactive feedback and exploration, while conclusions that matter should be checked with an appropriate reference method.
For the complete setup instructions and additional controls, see the UMA Force Field tutorial.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.