Skip to content

Workflow Convergence

Purpose: Convergence target classes and workflow-level convergence result structures

Relationship map

Hold "Alt" / "Option" to enable pan & zoom 
classDiagram
    class ChargeConvergenceTarget
    class EnergyConvergenceTarget
    class ForceConvergenceTarget
    class GeometryOptimizationModel
    class GeometryOptimizationResults
    class PotentialConvergenceTarget
    class SimulationWorkflowModel
    class SimulationWorkflowResults
    class WavefunctionConvergenceTarget
    class WorkflowConvergenceResults
    class WorkflowConvergenceTarget
    WorkflowConvergenceTarget <|-- ChargeConvergenceTarget
    WorkflowConvergenceTarget <|-- EnergyConvergenceTarget
    WorkflowConvergenceTarget <|-- ForceConvergenceTarget
    SimulationWorkflowResults <|-- GeometryOptimizationResults
    WorkflowConvergenceTarget <|-- PotentialConvergenceTarget
    WorkflowConvergenceTarget <|-- WavefunctionConvergenceTarget
    GeometryOptimizationModel *-- WorkflowConvergenceTarget : single_point_convergence_targets
    SimulationWorkflowModel *-- WorkflowConvergenceTarget : convergence_targets
    SimulationWorkflowResults *-- WorkflowConvergenceResults : convergence

Legend

inheritance (is-a)
composition (has-a)

Quantities by Key Sections

WorkflowConvergenceTarget

Section Description MetaInfo
WorkflowConvergenceTarget Base section for defining convergence targets. Open in MetaInfo browser
Quantity Type Description
threshold m_float_bounded(float)
Convergence threshold.Convergence threshold. Must be non-negative.
When threshold_type is 'relative', must be dimensionless.
When threshold_type is 'absolute', 'maximum', or 'rms', must have physical units.
Child classes override this to add convergence path annotations.
threshold_type Enum
Specifies the mathematical method used to evaluate convergence between successive iterations.Specifies the mathematical method used to evaluate convergence between successive iterations. Supported methods include:
| Name | Description |
| --------- | -------------------------------- |
| 'absolute' | Difference in absolute terms between two subsequent iterations (e.g., \

EnergyConvergenceTarget

Section Description MetaInfo
EnergyConvergenceTarget Convergence target for total energy differences. Open in MetaInfo browser
Quantity Type Description
threshold m_float_bounded(float)
Convergence threshold.Convergence threshold. Must be non-negative.
When threshold_type is 'relative', must be dimensionless.
When threshold_type is 'absolute', 'maximum', or 'rms', must have physical units.
Child classes override this to add convergence path annotations.

ForceConvergenceTarget

Section Description MetaInfo
ForceConvergenceTarget Convergence target for atomic forces. Open in MetaInfo browser
Quantity Type Description
threshold m_float_bounded(float)
Convergence threshold.Convergence threshold. Must be non-negative.
When threshold_type is 'relative', must be dimensionless.
When threshold_type is 'absolute', 'maximum', or 'rms', must have physical units.
Child classes override this to add convergence path annotations.

PotentialConvergenceTarget

Section Description MetaInfo
PotentialConvergenceTarget Convergence target for potential energy differences. Open in MetaInfo browser
Quantity Type Description
threshold m_float_bounded(float)
Convergence threshold.Convergence threshold. Must be non-negative.
When threshold_type is 'relative', must be dimensionless.
When threshold_type is 'absolute', 'maximum', or 'rms', must have physical units.
Child classes override this to add convergence path annotations.

ChargeConvergenceTarget

Section Description MetaInfo
ChargeConvergenceTarget Convergence target for electron density/charge differences. Open in MetaInfo browser
Quantity Type Description
threshold m_float_bounded(float)
Convergence threshold.Convergence threshold. Must be non-negative.
When threshold_type is 'relative', must be dimensionless.
When threshold_type is 'absolute', 'maximum', or 'rms', must have physical units.
Child classes override this to add convergence path annotations.

WavefunctionConvergenceTarget

Section Description MetaInfo
WavefunctionConvergenceTarget Convergence target for wavefunction coefficient differences. Open in MetaInfo browser
Quantity Type Description
threshold m_float_bounded(float)
Convergence threshold.Convergence threshold. Must be non-negative.
When threshold_type is 'relative', must be dimensionless.
When threshold_type is 'absolute', 'maximum', or 'rms', must have physical units.
Child classes override this to add convergence path annotations.

WorkflowConvergenceResults

Section Description MetaInfo
WorkflowConvergenceResults Results of workflow convergence checks. Open in MetaInfo browser
Quantity Type Description
convergence_target_ref Reference Reference to the workflow convergence target that this result corresponds to.
is_reached m_bool(bool) Indicates whether this convergence target was reached (True) or not (False).

SimulationWorkflowModel

Section Description MetaInfo
SimulationWorkflowModel Base class for simulation workflow model sub-section definition. Open in MetaInfo browser
Quantity Type Description
initial_system Reference Reference to the input model_system.
initial_method Reference Reference to the input model_method.

SimulationWorkflowResults

Section Description MetaInfo
SimulationWorkflowResults Base class for simulation workflow results sub-section definition. Open in MetaInfo browser
Quantity Type Description
finished_normally m_bool(bool) Indicates if calculation terminated normally.
is_converged m_bool(bool) Represents if the convergence targets have been reached (True) or not (False).

GeometryOptimizationModel

Section Description MetaInfo
GeometryOptimizationModel Workflow model describing a geometry optimization. Open in MetaInfo browser
Quantity Type Description
optimization_type Enum
The type of geometry optimization, which denotes what is being optimized.The type of geometry optimization, which denotes what is being optimized.
Allowed values are:
| Type | Description |
| ---------------------- | ----------------------------------------- |
| "static" | no optimization |
| "atomic" | the atomic coordinates alone are updated |
| "cell_volume" | "atomic" + cell lattice parameters are updated isotropically |
| "cell_shape" | "cell_volume" but without the isotropic constraint: all cell parameters are updated |
optimization_method m_str(str) The method used for geometry optimization. Some known possible values are: "steepest_descent", "conjugate_gradient", "low_memory_broyden_fletcher_goldfarb_shanno".
n_steps_maximum m_int32(int) Maximum number of optimization steps.
sampling_frequency m_int32(int) The number of optimization steps between saved outputs.

GeometryOptimizationResults

Section Description MetaInfo
GeometryOptimizationResults Open in MetaInfo browser
Quantity Type Description
is_single_point_converged m_bool(bool)
Aggregated SCF convergence status across all optimization steps.Aggregated SCF convergence status across all optimization steps.
Returns True if all SCF runs in all optimization steps converged to their
specified targets (defined in method.single_point_convergence_targets).
Returns False if any SCF run failed to converge. Returns None if no
convergence data is available.
This value is computed during normalization by aggregating convergence results
from all SinglePoint tasks using the JMESPath query:
workflow2.tasks[*].results.convergence[*].is_reached
The aggregation logic is: all(all(step_results) for step_results in all_results)
Example:
For a geometry optimization with 3 steps:
- Step 0: [True, True] (2 SCF targets, both converged)
- Step 1: [True, True]
- Step 2: [True, False] (second target failed)
→ is_single_point_converged = False
Note: This field currently provides only aggregate information. Per-step
convergence status should be retrieved from individual task results:
workflow2.tasks[step_index].results.convergence
See also:
- method.single_point_convergence_targets: SCF convergence criteria
- is_converged: Geometry-level convergence status
- convergence: Per-target geometry convergence results
n_steps m_int32(int) Number of saved optimization steps.
energies m_float64(float64) (shape: ['n_steps']) List of energy_total values gathered from the single configuration calculations that are a part of the optimization trajectory.
steps m_int32(int32) (shape: ['n_steps']) The step index corresponding to each saved configuration.
final_energy_difference m_float64(float64) The difference in the energy_total between the last two steps during optimization.
final_force_maximum m_float64(float64) The maximum net force in the last optimization step.
final_displacement_maximum m_float64(float64) The maximum displacement in the last optimization step with respect to previous.