Failing to get somd2 to run after API setup

[jasmin-guven]

Hi again!

I'm trying to setup a somd2 RBFE run from the API. I'm following the BioSimSpace tutorials on how to setup somd2 runs:

elif engine_query == "SOMD2":
    os.makedirs(
        f"{main_dir}/outputs/{engine_query}/{lig_0}~{lig_1}/bound", exist_ok=True
    )
    BSS.Stream.save(
        system_bound,
        f"{main_dir}/outputs/{engine_query}/{lig_0}~{lig_1}/bound/{lig_0}~{lig_1}",
    )
    with open(f"{main_dir}/outputs/{engine_query}/{lig_0}~{lig_1}/bound/config.yaml", 'w') as yaml_file:
        _yaml.dump(somd2_config, yaml_file)

I've done a similar thing where I create the config file directly by constructing a config object, saving it as a yaml file (as above) and then saving my merged BioSimSpace system as a sire object:

        merged_ligand_system = self.create_hybrid_molecule()
        
        somd2_config_file = os.path.join(self.working_directory, "config.yaml")
        
        somd2_config = config.Config(
            runtime=str(self.recipe.sampling_time),
            num_lambda=self.recipe.n_lambdas,
            log_file=f"{self.transformation}_somd2_log.txt",
            timestep=str(self.recipe.dt),
            temperature=str(self.recipe.temperature),
            pressure=str(self.recipe.pressure),
            integrator="langevin",
            cutoff_type="pme",
            cutoff=str(self.recipe.nb_cutoff),
            platform=compute_platform,
            hmr=False,
            restraints=None, #how to do this???
            constraint="h_bonds",
            perturbable_constraint="h_bonds_not_heavy_perturbed",
            minimise=True,
            minimisation_constraints=False,
            minimisation_errors=False,
            equilibration_time=str(self.recipe.lambda_equilibration_time),
            equilibration_timestep=str(self.recipe.lambda_equilibration_dt),
            equilibration_constraints=True,
            opencl_platform_index=0,
            restart=False,
            use_backup=False,
            write_config=True,
            overwrite=False,
            somd1_compatibility=False,
            pert_file=None,
            output_directory=self.working_directory
        )

        config_dictionary = somd2_config.as_dict()

        with open(somd2_config_file, "w") as ofile:
            yaml.dump(config_dictionary, ofile)

        sire_system = sire.system.System(merged_ligand_system._sire_object)

        sire.stream.save(
            obj=sire_system,
            filename=f"{self.working_directory}/merged_system.bss"
        )

I then tried running somd2 with:

somd2 merged_system.bss --config config.yaml 

but I get this error:

2026-06-26 13:30:34.088 | INFO     | somd2.runner._base:__init__:105 - somd2 version: 2025.2.0.dev+268.gfdad810
2026-06-26 13:30:34.088 | INFO     | somd2.runner._base:__init__:106 - sire version: 2025.4.0+8c20f50
2026-06-26 13:30:34.088 | INFO     | somd2.runner._base:__init__:107 - biosimspace version: 2025.4.0
2026-06-26 13:30:34.089 | INFO     | somd2.runner._base:__init__:109 - ghostly version: 2025.2.0
2026-06-26 13:30:34.338 | INFO     | somd2.runner._base:__init__:325 - Applying modifications to ghost atom bonded terms
2026-06-26 13:30:34.383 | WARNING  | ghostly._ghostly:_check_rotamer_anchors:2378 - Potential rotamer anchor at λ = 0: bond 12-0 is a rotatable sp3 bond. Surviving anchor dihedrals may allow rotameric transitions of ghost atoms.
2026-06-26 13:30:34.489 | ERROR    | somd2.runner._base:_prepare_output:1343 - The following files already exist, use --overwrite to overwrite them: ['/Users/af25016/projects/meze/data/outputs/model_0/vim2/ligand_11~ligand_12/bound/config.yaml'] 

I don't want to overwrite the file as I have setup the config in a specific way. I also don't see how somd2 would know my config settings if I overwrite/delete the saved config file?

I'm sure I'm not using the scripts/package the right way, so any help with this would be really appreciated, thanks!

[lohedges]

It looks like you are writing the config file to the same directory where the output of the run would be written. On startup, it will see this file is already present, then raise the error, since it would be overwritten by the run. Even if it overwrites things, it will use the exact values from the specified config, so it should be identical to the original one. You could confirm this by first copying your config elsewhere, e.g. to a backup file, then running with --overwrite, then diffing the files.

Are you planning to split the setup and simulation running like you are doing above, or is it easier to just create the Runner/RepexRunner in your script and launch it directly?

Just a note on this comment in your code:

restraints=None, #how to do this???

Yes, if specified as None then no restraints will be used. Currently we require that restraints are generated outside of somd2, i.e. using the Sire API (sire.restraints) directly, then passed in. If you do need to use them, then I can give examples.

[jasmin-guven]

It looks like you are writing the config file to the same directory where the output of the run would be written. On startup, it will see this file is already present, then raise the error, since it would be overwritten by the run. Even if it overwrites things, it will use the exact values from the specified config, so it should be identical to the original one. You could confirm this by first copying your config elsewhere, e.g. to a backup file, then running with --overwrite, then diffing the files.

I see that makes sense. I'm now saving the config in a parent folder and it seems to be running now! I had misunderstood how the config should be setup.

Are you planning to split the setup and simulation running like you are doing above, or is it easier to just create the Runner/RepexRunner in your script and launch it directly?

I think for now I'm going to keep them separate to make it more flexible.

Just a note on this comment in your code:

restraints=None, #how to do this???

Yes, if specified as None then no restraints will be used. Currently we require that restraints are generated outside of somd2, i.e. using the Sire API (sire.restraints) directly, then passed in. If you do need to use them, then I can give examples.

Yes, I'll need to setup some restraints at some point! Yesterday I had a look at the sire.restraints and I think I'll need to use the BondRestraints class. This is for metal coordination, and currently I'm defining them with MDAnalysis and then AMBER for equilibrium MD, but will need to convert them to the sire ones. Do you know how to convert the atom indices from MDAnalysis/Amber to Sire? Is it 0-indexed or 1-indexed in Sire?

Also, now that the test somd2 run is running, I'm noticing there are no separate folders/outputs for each of the lambda runs at least for the minimisation and equilibrations. Is there a way to output these as they are ready?

Finally, I noticed that somd2 creates a system0.prm7 and a system1.prm7 but no coordinates. Is that intentional, and if so, what coordinates can I use to visualise these topologies in e.g. VMD?

Thanks a lot again for your help!

[lohedges]

Yes, I'll need to setup some restraints at some point! Yesterday I had a look at the sire.restraints and I think I'll need to use the BondRestraints class. This is for metal coordination, and currently I'm defining them with MDAnalysis and then AMBER for equilibrium MD, but will need to convert them to the sire ones. Do you know how to convert the atom indices from MDAnalysis/Amber to Sire? Is it 0-indexed or 1-indexed in Sire?

Sire is zero-indexed, but the API takes atom objects in this case, i.e. you pass it atoms0 and atoms1 and it will create distance restraints between all of the atoms in atoms0 and all of those in atoms1. (Here sire.restraints.bond is just an alias for sire.restraints.distance.)

Also, now that the test somd2 run is running, I'm noticing there are no separate folders/outputs for each of the lambda runs at least for the minimisation and equilibrations. Is there a way to output these as they are ready?

All of the output is placed in a single output directory. You'll get updates at the checkpoint_frequency, with the first as a post-equilibration checkpoint.

Finally, I noticed that somd2 creates a system0.prm7 and a system1.prm7 but no coordinates. Is that intentional, and if so, what coordinates can I use to visualise these topologies in e.g. VMD

These are intended to be used for post-simulation visualisation and analysis of the trajectory files, i.e. you can load the trajectory using the topology of either end-state. While running, the simulation will write trajectory "chunk" files at each checkpoint. It's only at the end of the simulation that these are reconstructed into a single trajectory. We do it that way to save memory, i.e. otherwise we need to keep the entire trajectory in memory for each replica throughout. It also makes things more crash resilient.