OptimizeGeometry(configuration, max_forces=None, max_stress=None, max_steps=None, max_step_length=None, constraints=None, trajectory_filename=None, disable_stress=None, optimizer_method=None, target_stress=None, pre_step_hook=None, post_step_hook=None, constrain_bravais_lattice=None, trajectory_interval=None, restart_strategy=None, remove_drift=None, enable_optimization_stop_file=None)

Function for optimizing the geometry and/or the unit cell of the given configuration.

  • configuration (MoleculeConfiguration | BulkConfiguration | DeviceConfiguration | SurfaceConfiguration) – The configuration to be optimized.
  • max_forces (PhysicalQuantity of type force) – The convergence criterion for the atomic forces.
    Default: 0.05*eV/Angstrom
  • max_stress (PhysicalQuantity of type pressure) – The convergence criterion for the maximum difference between the internal stress and the target stress.
    Default: 0.1*GPa
  • max_steps (int) – The maximum number of optimization steps.
    Default: 200
  • max_step_length (PhysicalQuantity of type length) – The maximum step length the optimizer may take.
    Default: 0.2*Ang
  • constraints (list of integers and Constraints objects) – A list of indices of the atom with fixed positions and Constraints objects.
    Default: []
  • trajectory_filename (str) – The filename used to store the trajectory. If the value is None then no trajectory file will be written.
    Default: None
  • disable_stress (bool) – Disable the stress calculation for bulk configurations. This means that the lattice vectors will be change during the optimization.
    Default: False for BulkConfigurations otherwise True
  • optimizer_method (FIRE | LBFGS) – The optimization algorithm to use.
    Default: LBFGS
  • target_stress (PhysicalQuantity of type pressure) – The target internal stress (tensor) of the system. Can be given as a single value in case of isotropic pressure, or as an internal stress vector in Voigt notation or as a 3x3-matrix.
    Default: 0*GPa
  • pre_step_hook (A callable function or method) – An optional user-defined function which will be called just before each optimization step. The signature of the function requires the arguments (step, configuration). The return status is ignored. Unhandled exceptions will abort the optimization.
    Default: None
  • post_step_hook (A callable function or method) – An optional user-defined function which will be called just after each optimization step. The signature of the function requires the arguments (step, configuration). The return status is ignored. Unhandled exceptions will abort the optimization.
    Default: None
  • constrain_bravais_lattice (bool) – Enable preserving the Bravais lattice symmetry of the configuration.
    Default: True if the target_stress is commensurate with the lattice symmetries
  • trajectory_interval (int | PhysicalQuantity of type time) – The resolution used in saving steps to a trajectory file. This can either be given as an integer (a value of 1 results in all steps being saved; a value of 2 results in every second step being saved; etc.) or as a time interval.
    Default: 1
  • restart_strategy (NoRestart | RestartFromTrajectory) – The restart mechanism based on trajectory data saved in a given file.
    Default: RestartFromTrajectory()
  • remove_drift (bool) – In ab-initio calculations, the sum of the forces along each Cartesian direction does not necessarily sum to zero due to numerical inaccuracies. This option controls if the “drift” in the forces should be removed by subtracting the average force along each Cartesian direction from all atoms.
    Default: True
  • enable_optimization_stop_file (bool) – Determines whether to enable a file for stopping the geometry optimization. If True, creation of the stop file will stop the optimization at the next step. The name of the stop file will be shown in the log output; it will be stop-geometry-optimization-uniqueID, where uniqueID is a randomly generated identifier for this optimization. The file must be created in the current working directory.
    Default: True

The optimized configuration. The returned configuration is assigned the self-consistent calculation associated with the final step of the optimization loop.

Return type:

MoleculeConfiguration | BulkConfiguration | DeviceConfiguration | SurfaceConfiguration

Usage Examples

Optimize the geometry of a water molecule:

# Define elements
elements = [Oxygen, Hydrogen, Hydrogen]

# Define coordinates
cartesian_coordinates = [[  0.0,  -1.70000000e-05,   1.20198000e-01],
                         [  0.0,   7.59572000e-01,  -4.86714000e-01],
                         [  0.0,  -7.59606000e-01,  -4.86721000e-01]]*Angstrom

# Set up configuration
molecule_configuration = MoleculeConfiguration(

# Define a calculator

# Perform optimization and store the relaxation trajectory
optimized_configuration = OptimizeGeometry(molecule_configuration,

# Save the relaxed configuration
nlsave('optimized_configuration.nc', optimized_configuration)


Optimize a silicon unit cell under a uniaxial tensile stress:

# Set up lattice
vector_a = [0.0, 2.7153, 2.7153]*Angstrom
vector_b = [2.7153, 0.0, 2.7153]*Angstrom
vector_c = [2.7153, 2.7153, 0.0]*Angstrom
lattice = UnitCell(vector_a, vector_b, vector_c)

# Define elements
elements = [Silicon, Silicon]

# Define coordinates
fractional_coordinates = [[ 0.  ,  0.  ,  0.  ],
                          [ 0.25,  0.25,  0.25]]

# Set up configuration
bulk_configuration = BulkConfiguration(

# -------------------------------------------------------------
# Calculator
# -------------------------------------------------------------

potentialSet = StillingerWeber_Si_1985()
calculator = TremoloXCalculator(parameters=potentialSet)


# -------------------------------------------------------------
# Optimize Geometry
# -------------------------------------------------------------

bulk_configuration = OptimizeGeometry(
        target_stress=[2.0, 0.0, 0.0, 0.0, 0.0, 0.0]*GPa,

# Save the relaxed configuration
nlsave('optimized_configuration2.nc', bulk_configuration)



By default, all cell optimizations are performed under zero stress.

The definition of target stress is that if a single value is given, it will be interpreted as an external pressure value from which the internal target stress tensor is calculated as

\[\begin{split}\sigma = \left( \begin{matrix} -p & 0 & 0 \\ 0 & -p & 0 \\ 0 & 0 & -p \end{matrix}\right) \, .\end{split}\]

If a target stress tensor is given, it will be interpreted as internal stress of the system, meaning that a negative entry on the diagonal will result in a compression in the corresponding direction and vice versa. The target stress may also be specified in Voigt notation.

By default constrain_bravais_lattice is True when the target_stress is commensurate with the lattice symmetries. This means that the Bravais lattice type will not change unless a symmetry breaking internal stress is applied. If a symmetry breaking target_stress is used then the Bravais Lattice of the configuration is automatically converted to a UnitCell, to enable changes in the shape of the cell.


The last line of the logging output of OptimizeGeometry provides the tag OPT which can be used to grep for the current step, volume, max. force, max. stress error and energy / enthalpy.