Before You Trust the Energy: A Practical UMA Checklist

A molecular structure can look reasonable and still produce a result that is hard to interpret. The task may not match the system, a molecule’s charge or spin may be wrong, or a periodic cell may need checking. And when a machine-learning model first starts up, an energy value may not appear immediately. These details can turn a useful exploratory calculation into a confusing one.

UMA Force Field in SAMSON provides interactive energy and force evaluation with the UMA family of models. It can help with geometry refinement, exploratory relaxation, and qualitative force analysis. A reliable workflow starts not with pressing “Start,” but with checking that the model setup matches the system you want to study.

Match the task to the system

When you add a simulator through Edit > Simulate > Add simulator and select UMA Force Field, the setup window asks you to choose a model and a task. The task is an important part of the setup:

  • 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.

Choosing a task that sounds broadly relevant is not a substitute for checking the system category. Before starting, ask: Is this a molecule, a bulk material, a surface with an adsorbate, or a crystal? Making that decision explicitly helps you avoid treating a setup choice as an inconsequential dropdown.

UMA Force Field setup window showing model and task choices
Choose the model and task that correspond to the system you are evaluating.

Start with the model that fits an exploratory workflow

The available options include UMA-S (2.3 GB, v1.2), UMA-S (1.1 GB, v1.1), and UMA-M (11.7 GB, v1.1). The documented recommendation is to start with UMA-S unless you already know you need the larger UMA-M model. This gives you a practical starting point for rapid feedback without assuming that the largest option is automatically the right choice.

On first use, SAMSON prepares a dedicated Python environment and may request access to UMA models. Package installation and model access can take time. Follow the prompts in SAMSON; after setup completes, you may need to create the interaction model again. A brief wait during this first setup is expected, rather than a reason to interpret the initial lack of an energy as a failed scientific result.

Check molecular and periodic settings

For OMOL, verify that Total charge and Spin multiplicity match the molecular system you intend to model. These values are part of the request sent to UMA, so they should not be treated as decorative interface settings. If you are unsure of the appropriate values, resolve that question before interpreting the output.

For periodic workflows, inspect the periodic-boundary-conditions control and the 3 × 3 cell matrix, which is given in angstroms. Confirm that the intended periodic setting and cell are represented before drawing conclusions about the system. The properties window provides these controls while the simulation is running.

Periodic boundary condition controls and cell matrix in UMA Properties
For periodic systems, check both whether periodic boundary conditions are enabled and the cell values.

Know what bond updates do—and do not tell you

The Bond update menu offers four choices: Covalent recomputes covalent bonds from the current structure; Wiberg bond order (estimated) and Mayer bond order (estimated) use a deep-learning model to estimate bond orders; and Off leaves the current bond graph unchanged.

The estimated Wiberg and Mayer modes can help you explore how bonding representations respond as you move atoms or refine a structure. They are estimates for interactive exploration, not a reason to skip validation. If a bond-order interpretation matters to a conclusion, confirm it with your reference method.

Read the first result in context

Once the environment is ready and the selected model is accessible, start the simulation with Edit > Simulate > Start. Wait for the first UMA evaluation to finish. The properties window may briefly report that energy is not available; the total energy is displayed after the first successful evaluation. Then you can interactively move atoms or refine the structure while UMA updates energies and forces.

A useful habit is to separate exploration from confirmation. Use UMA to screen, refine, and investigate structures, while keeping track of the task, model, charge and spin where applicable, and periodic cell. For final conclusions that require higher accuracy, confirm with an appropriate reference method. This makes the interactive result useful without asking it to answer more than the workflow supports.

UMA Properties window after startup
The energy can appear after the first successful evaluation.

For the full setup instructions and related details, read the UMA Force Field documentation.

Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.

Comments are closed.