desc.equilibrium.Equilibrium.solve

Equilibrium.solve(objective='force', constraints=None, optimizer='lsq-exact', ftol=None, xtol=None, gtol=None, maxiter=None, x_scale='auto', options=None, verbose=1, copy=False)Source

Solve to find the equilibrium configuration.

Parameters:

  • objective ({"force", "forces", "energy"}) – Objective function to solve. Default = force balance on unified grid. ObjectiveFunction can also be passed.

  • constraints (Tuple) – set of constraints to enforce. Default = fixed boundary/profiles

  • optimizer (str or Optimizer (optional)) – optimizer to use

  • ftol (float) – stopping tolerances. None will use defaults for given optimizer.

  • xtol (float) – stopping tolerances. None will use defaults for given optimizer.

  • gtol (float) – stopping tolerances. None will use defaults for given optimizer.

  • maxiter (int) – Maximum number of solver steps.

  • x_scale (array, list[dict | 'ess'], 'ess' or 'auto', optional) – Characteristic scale of each variable. Setting x_scale is equivalent to reformulating the problem in scaled variables xs = x / x_scale. An alternative view is that the size of a trust region along jth dimension is proportional to x_scale[j]. Improved convergence may be achieved by setting x_scale such that a step of a given size along any of the scaled variables has a similar effect on the cost function. Default is 'auto', which iteratively updates the scale using the inverse norms of the columns of the Jacobian or Hessian matrix. If set to 'ess', the scale is set using Exponential Spectral Scaling, this scaling is set with two parameters, ess_alpha and ess_order which are passed through options. ess_alpha is the decay rate of the scaling, and ess_order is the norm order for multi-index modes, which can be 1, 2, or np.inf. If not provided in options, the defaults are: ess_alpha=1.2, ess_order=np.inf' and ess_min_value=1e-7 (minimum allowed scale value). If an array, should be the same size as sum(thing.dim_x for thing in things). If a list, the list should have 1 element for each thing, and each element should either be 'ess' to use exponential spectral scaling for that thing, or a dict with the same keys and dimensions as thing.params_dict to specify scales manually.

  • options (dict) – Dictionary of additional options to pass to optimizer.

  • verbose (int) – Level of output.

  • copy (bool) – Whether to return the current equilibrium or a copy (leaving the original unchanged).

Returns:

  • eq (Equilibrium) – Either this equilibrium or a copy, depending on “copy” argument.

  • result (OptimizeResult) – The optimization result represented as a OptimizeResult object. Important attributes are: x the solution array, success a Boolean flag indicating if the optimizer exited successfully and message which describes the cause of the termination. See OptimizeResult for a description of other attributes. Additionally, stores the before and after values of the objectives and constraints in the Objective values key.