Skip to content

workflow #

Implements the overall workflow for fitting a bespoke force field.

Functions:

get_bespoke_force_field #

get_bespoke_force_field(
    settings: WorkflowSettings, write_settings: bool = True
) -> ForceField

Fit a bespoke force field.

This involves:

  • Parameterising a base force field for the target molecule and generating specific tagged SMARTS parameters
  • Generating training data (e.g. from high-temperature MD simulations)
  • Optimising the parameters of the force field to reproduce the training data
  • Validating the fitted force field against test data

Parameters:

  • settings (WorkflowSettings) –

    The workflow settings to use for fitting the force field.

  • write_settings (bool, default: True ) –

    Whether to write the settings to a YAML file in the output directory, by default True.

Returns:

ForceField The fitted bespoke force field.

Source code in presto/workflow.py
def get_bespoke_force_field(
    settings: WorkflowSettings, write_settings: bool = True
) -> ForceField:
    """Fit a bespoke force field.

    This involves:

    - Parameterising a base force field for the target molecule and generating
      specific tagged SMARTS parameters
    - Generating training data (e.g. from high-temperature MD simulations)
    - Optimising the parameters of the force field to reproduce the training data
    - Validating the fitted force field against test data

    Parameters
    ----------
    settings : WorkflowSettings
        The workflow settings to use for fitting the force field.

    write_settings : bool, optional
        Whether to write the settings to a YAML file in the output directory, by default True.

    Returns:
    -------
    ForceField
        The fitted bespoke force field.
    """
    path_manager = settings.get_path_manager()
    # Refuse to run if generated output from an earlier fit is still present.
    path_manager.require_clean()
    stage = OutputStage(StageKind.BASE)
    path_manager.mk_stage_dir(stage)

    if write_settings:
        settings_output_path = path_manager.get_output_path(
            stage, OutputType.WORKFLOW_SETTINGS
        )
        logger.info(f"Writing workflow settings to {settings_output_path}.")
        # Copy the settings and change the output directory to be "." as we save
        # to the output directory already
        output_settings = copy.deepcopy(settings)
        output_settings.output_dir = pathlib.Path(".")
        output_settings.to_yaml(settings_output_path)

    # Parameterise the base force field for all molecules
    off_mols, initial_off_ff, tensor_tops, tensor_ff = parameterise(
        settings.param_settings, device=settings.device_type
    )

    pruned_parameter_configs = {
        p_type: p_config
        for p_type, p_config in settings.training_settings.parameter_configs.items()
        if p_type in tensor_ff.potentials_by_type
    }

    trainable = Trainable(
        tensor_ff,
        pruned_parameter_configs,
        settings.training_settings.attribute_configs,
    )

    trainable_parameters = trainable.to_values().to(settings.device)

    # Get a copy of the initial trainable parameters for regularisation
    initial_parameters = trainable_parameters.clone().detach()

    # Persist the initial force field before sampling so spawned workers
    # reconstruct their own OpenFF/OpenMM state from disk.
    initial_stage = OutputStage(StageKind.INITIAL_STATISTICS)
    path_manager.mk_stage_dir(initial_stage)
    initial_offxml_path = path_manager.get_output_path(initial_stage, OutputType.OFFXML)
    initial_off_ff.to_file(str(initial_offxml_path))

    # Generate the test data for all molecules
    stage = OutputStage(StageKind.TESTING)
    path_manager.mk_stage_dir(stage)
    logger.info("Generating test data")
    test_output_paths = {
        output_type: path_manager.get_output_path(stage, output_type)
        for output_type in settings.testing_sampling_settings.output_types
    }
    datasets_test = sample_ligands(
        mols=off_mols,
        offxml_path=initial_offxml_path,
        device_type=settings.device_type,
        sampling_settings=settings.testing_sampling_settings,
        output_paths=test_output_paths,
        dataset_output_paths=[
            path_manager.get_output_path_for_mol(
                stage, OutputType.ENERGIES_AND_FORCES, i
            )
            for i in range(len(off_mols))
        ],
        n_processes=settings.n_sampling_processes,
    )

    # Write out statistics on the initial force field
    stage = OutputStage(StageKind.INITIAL_STATISTICS)
    path_manager.mk_stage_dir(stage)

    # Write scatter plots for each molecule
    for mol_idx, (dataset_test, tensor_top) in enumerate(
        zip(datasets_test, tensor_tops, strict=True)
    ):
        scatter_path_mol = path_manager.get_output_path_for_mol(
            stage, OutputType.SCATTER, mol_idx
        )
        energy_mean, energy_sd, forces_mean, forces_sd = write_scatter(
            dataset_test,
            tensor_ff,
            tensor_top,
            settings.device,
            str(scatter_path_mol),
        )
        logger.info(
            f"Molecule {mol_idx} initial force field statistics: Energy (Mean/SD): {energy_mean:.3e}/{energy_sd:.3e} kcal/mol, Forces (Mean/SD): {forces_mean:.3e}/{forces_sd:.3e} kcal/mol/Å"
        )

    off_ff = convert_to_smirnoff(
        trainable.to_force_field(trainable_parameters), base=initial_off_ff
    )
    off_ff.to_file(str(path_manager.get_output_path(stage, OutputType.OFFXML)))

    train_fn = _TRAINING_FNS_REGISTRY[settings.training_settings.optimiser]

    # Train the force field
    progress = Progress(
        TextColumn("[progress.description]{task.description}"),
        BarColumn(),
        MofNCompleteColumn(),
        TimeRemainingColumn(),
    )

    previous_datasets = None  # Only None for the first iteration

    def process_training_dataset(
        mol_idx: int, dataset: datasets.Dataset
    ) -> datasets.Dataset:
        if settings.outlier_filter_settings is not None:
            logger.info(
                f"Applying outlier filtering to molecule {mol_idx} training data"
            )
            dataset = filter_dataset_outliers(
                dataset=dataset,
                force_field=tensor_ff,
                topology=tensor_tops[mol_idx],
                settings=settings.outlier_filter_settings,
                device=settings.device,
            )
        if settings.memory and previous_datasets is not None:
            dataset = datasets.combine.concatenate_datasets(
                [previous_datasets[mol_idx], dataset]
            )
        return dataset

    with progress:
        for iteration in progress.track(
            range(1, settings.n_iterations + 1),  # Start from 1 (0 is untrained)
            description="Iterating the Fit",
        ):
            stage = OutputStage(StageKind.TRAINING, iteration)
            path_manager.mk_stage_dir(stage)

            sampling_output_paths = {
                output_type: path_manager.get_output_path(stage, output_type)
                for output_type in settings.training_sampling_settings.output_types
            }

            # Workers load the force field produced by the previous iteration.
            sampling_offxml_path = (
                initial_offxml_path
                if iteration == 1
                else path_manager.get_output_path(
                    OutputStage(StageKind.TRAINING, iteration - 1), OutputType.OFFXML
                )
            )
            datasets_train = sample_ligands(
                mols=off_mols,
                offxml_path=sampling_offxml_path,
                device_type=settings.device_type,
                sampling_settings=settings.training_sampling_settings,
                output_paths=sampling_output_paths,
                dataset_output_paths=[
                    path_manager.get_output_path_for_mol(
                        stage, OutputType.ENERGIES_AND_FORCES, i
                    )
                    for i in range(len(off_mols))
                ],
                n_processes=settings.n_sampling_processes,
                process_dataset=process_training_dataset,
            )

            train_output_paths = {
                output_type: path_manager.get_output_path(stage, output_type)
                for output_type in settings.training_settings.output_types
            }

            trainable_parameters, trainable = train_fn(
                trainable_parameters=trainable_parameters,
                initial_parameters=initial_parameters,
                trainable=trainable,
                topologies=tensor_tops,
                datasets=datasets_train,
                datasets_test=datasets_test,
                settings=settings.training_settings,
                output_paths=train_output_paths,
                device=settings.device,
            )

            for potential_type in trainable._param_types:
                tensor_ff.potentials_by_type[potential_type].parameters = copy.copy(
                    trainable.to_force_field(trainable_parameters)
                    .potentials_by_type[potential_type]
                    .parameters
                )

            off_ff = convert_to_smirnoff(
                trainable.to_force_field(trainable_parameters), base=initial_off_ff
            )
            off_ff.to_file(str(path_manager.get_output_path(stage, OutputType.OFFXML)))

            # Write scatter plots for each molecule
            for mol_idx, (dataset_test, tensor_top) in enumerate(
                zip(datasets_test, tensor_tops, strict=True)
            ):
                scatter_path_mol = path_manager.get_output_path_for_mol(
                    stage, OutputType.SCATTER, mol_idx
                )
                energy_mean_new, energy_sd_new, forces_mean_new, forces_sd_new = (
                    write_scatter(
                        dataset_test,
                        tensor_ff,
                        tensor_top,
                        settings.device,
                        str(scatter_path_mol),
                    )
                )
                logger.info(
                    f"Iteration {iteration} Molecule {mol_idx} force field statistics: Energy (Mean/SD): {energy_mean_new:.3e}/{energy_sd_new:.3e} kcal/mol, Forces (Mean/SD): {forces_mean_new:.3e}/{forces_sd_new:.3e} kcal/mol/Å"
                )

            previous_datasets = datasets_train  # Carry into the next iteration

    # Plot
    analyse_workflow(settings)

    return off_ff