schrodinger.application.jaguar.ffbuilder module¶

Shared FFBuilder support for Jaguar workflow drivers.

This module deliberately has no dependency on jaguar-src. Workflow drivers choose when their structures are ready for parameterization, call run_ffbuilder, and then make the returned OPLS archive available to their subjobs through OPLS_DIR.

exception schrodinger.application.jaguar.ffbuilder.FFBuilderError¶

Bases: RuntimeError

Raised when the FFBuilder job does not complete successfully.

class schrodinger.application.jaguar.ffbuilder.FFBuilderResult(opls_archive: pathlib.Path | None, input_archive: pathlib.Path | None, generated_parameters: bool, skipped_reason: str | None = None, *, analyze_only: bool = False, project_archive: pathlib.Path | None = None, elapsed_seconds: float)¶

Bases: object

Result of an FFBuilder refinement run.

Variables:

opls_archive – Newly generated custom OPLS archive. It is None when FFBuilder creates no new parameters, when analyze-only mode is used, or when availability checks skip FFBuilder.
input_archive – Custom OPLS archive that was present before this run, if any.
generated_parameters – Whether FFBuilder produced a new OPLS output directory.
skipped_reason – Why FFBuilder was skipped, if its installation or the default MLFF path was unavailable.
analyze_only – Whether this result came from a coverage analysis without parameter generation.
project_archive – Project ZIP produced by FFBuilder and copied to the workflow output directory, if available. It contains the input structures and parameter database. Open it in the Force Field Builder GUI to inspect missing parameters or refinement results.
elapsed_seconds – Wall-clock time spent preparing and running FFBuilder. This is required for every returned result.

opls_archive: pathlib.Path | None¶

input_archive: pathlib.Path | None¶

generated_parameters: bool¶

skipped_reason: str | None = None¶

analyze_only: bool = False¶

project_archive: pathlib.Path | None = None¶

elapsed_seconds: float¶

__init__(opls_archive: pathlib.Path | None, input_archive: pathlib.Path | None, generated_parameters: bool, skipped_reason: str | None = None, *, analyze_only: bool = False, project_archive: pathlib.Path | None = None, elapsed_seconds: float) → None¶

Publish the active custom OPLS archive under a predictable name.

Write <jobname>_ffbuilder.opls so a parent workflow can find and merge the parameters generated by its subjobs. The source defaults to OPLS_DIR. The caller decides whether to set OPLS_DIR to the returned archive.

Parameters:

jobname – Workflow job name used for the published archive name.
source – Active OPLS archive to publish, or OPLS_DIR when omitted.
output_directory – Directory in which to create the published archive.

Returns:

Published archive path, or None when no source is available.

Raises:

FFBuilderError – If the source is invalid or publication fails.

schrodinger.application.jaguar.ffbuilder.merge_opls_archives(archives: Iterable[str | pathlib.Path], jobname: str, *, output_directory: str | pathlib.Path | None = None) → pathlib.Path | None¶

Merge child workflow OPLS archives into one parent archive.

Start with the current OPLS_DIR, if set, and add the subjob archives in the supplied order. Write <jobname>_ffbuilder.opls only after all merges succeed; a failed merge leaves any existing output file unchanged. The caller is responsible for updating OPLS_DIR.

Parameters:

archives – Child workflow archives to merge in order.
jobname – Parent workflow job name used for the output archive name.
output_directory – Directory in which to create the combined archive.

Returns:

Path to the combined archive, or None if no child archives were supplied.

Raises:

FFBuilderError – If an input archive is invalid or merging fails.

schrodinger.application.jaguar.ffbuilder.run_ffbuilder(structures: Iterable[Structure], jobname: str, *, additional_args: Sequence[str] = (), host: str | None = None, sub_host: str | None = None, output_directory: str | pathlib.Path | None = None, analyze_only: bool = False) → FFBuilderResult¶

Refine custom OPLS parameters for structures.

Run the RunFFBuilder transform after checking the FFLD installation, required licenses, and MLFF support. Include the existing custom OPLS archive when generating parameters, and return the new archive without changing OPLS_DIR. Analysis mode reports coverage without generating parameters.

Parameters:

structures – Structures requiring force-field coverage.
jobname – Workflow job name used for FFBuilder files and outputs.
additional_args – Extra FFBuilder command-line arguments.
host – Optional FFBuilder -HOST override.
sub_host – Optional FFBuilder -SUBHOST override.
output_directory – Directory for the OPLS archive, project ZIP, and log files returned to the user.
analyze_only – Run coverage analysis without generating parameters.

Returns:

FFBuilder result, including archive and elapsed-time information.

Raises:

ValueError – If reserved arguments are supplied.
FFBuilderError – If FFBuilder or archive handling fails.

schrodinger.application.jaguar.ffbuilder.format_failure(exception: Exception) → str¶

Format a recoverable FFBuilder failure for workflow output.

FFBuilder is an optional enhancement to Jaguar workflows. Keep the inherited OPLS archive visible when the enhancement cannot be completed, so users can distinguish a failed refinement from a force-field change.

Parameters:: exception – The exception raised by FFBuilder.
Returns:: A warning message describing the recoverable failure.

schrodinger.application.jaguar.ffbuilder.format_archive_failure(exception: Exception, action: str = 'publication') → str¶

Format a recoverable failure while publishing an OPLS archive.

The archive is a secondary FFBuilder output. A workflow should retain the active archive and continue when publishing, merging, or registering that output fails.

Parameters:

exception – The exception raised while handling the archive.
action – The archive operation that failed.

Returns:

A warning message describing the recoverable failure.

schrodinger.application.jaguar.ffbuilder.format_result(result: FFBuilderResult) → str¶

Report force-field status and the project ZIP for GUI inspection.

Parameters:: result – Result returned by an FFBuilder run.
Returns:: Human-readable force-field status text.