turboflow.pysolver_view.nonlinear_system module

class turboflow.pysolver_view.nonlinear_system.NonlinearSystemProblem

Bases: ABC

Abstract base class for root-finding problems.

Derived root-finding problem objects must implement the following method:

• residual: Evaluate the system of equations for a given set of decision variables.

Additionally, specific problem classes can define the gradient method to compute the Jacobians. If this method is not present in the derived class, the solver will revert to using forward finite differences for Jacobian calculations.

Examples

Here’s an example of how to derive from RootFindingProblem:

class MyRootFindingProblem(RootFindingProblem):
    def residual(self, x):
        # Implement evaluation logic here
        pass

Methods

residual(x)

Evaluate the system of equations for a given set of decision variables.

abstract residual(x)

Evaluate the system of equations for given decision variables.

Parameters:

xarray-like

Vector of decision variables.

Returns:

array_like

Vector containing the values of the system of equations for the given decision variables.

class turboflow.pysolver_view.nonlinear_system.NonlinearSystemSolver(problem, method='hybr', tolerance=1e-06, max_iterations=100, options={}, derivative_method='2-point', derivative_abs_step=1e-06, print_convergence=True, plot_convergence=False, plot_scale='log', logger=None, update_on='function', callback_func=None)

Bases: object

Solver class for nonlinear systems of equations.

The solver is designed to handle system of nonlinear equations of the form:

\[F(x) = 0\]

where \(F: \mathbb{R}^n \rightarrow \mathbb{R}^n\) is a vector-valued function of the vector \(x\).

The class interfaces with the root method from scipy.optimize to solve the equations and provides a structured framework for initialization, solution monitoring, and post-processing.

Parameters:

problemNonlinearSystemProblem

An instance of a problem defining the system of equations to be solved.

methodstr, optional

Method to be used by scipy’s root for solving the nonlinear system. Available solvers are:

• hybr: Uses MINPACK’s ‘hybrd’ method, which is is a modification of Powell’s hybrid method.

• lm: The Levenberg-Marquardt method, which blends the steepest descent and the Gauss-Newton methods.

The choice between hybr and lm largely depends on the specifics of the problem at hand. The hybr usually requires less gradient evaluations and it is often faster when analytic gradients are not available. It is advisable to experiment with both methods to determine the most appropriate choice for a given problem.

Defaults to ‘hybr’.

tolfloat, optional

Tolerance for the solver termination. Defaults to 1e-9.

max_iterinteger, optional

Maximum number of function evaluations for the solver termination. Defaults to 100.

optionsdict, optional

Additional options to be passed to scipy’s root.

derivative_methodstr, optional

Finite difference method to be used when the problem Jacobian is not provided. Defaults to ‘2-point’

derivative_abs_stepfloat, optional

Finite difference absolute step size to be used when the problem Jacobian is not provided. Defaults to 1e-6

print_convergencebool, optional

If True, displays the convergence progress. Defaults to True.

plot_convergencebool, optional

If True, plots the convergence progress. Defaults to False.

loggerlogging.Logger, optional

Logger object to which logging messages will be directed. Defaults to None.

update_onstr, optional

Specifies if the convergence report should be updated on a new function evaluations (“function”) or on gradient evaluations (“gradient”). Defaults to “function”.

Methods

solve(x0)	Solve the system of nonlinear equations using the specified initial guess x0.
residual(x)	Evaluate the vector of residuals of the at a given point x.
gradient(x)	Evaluate the Jacobian of the system at a given point x.
print_convergence_history()	Print the convergence history of the problem.
plot_convergence_history()	Plot the convergence history.

gradient(x)

Evaluates the Jacobian of the nonlinear system of equations at the specified point x.

This method will use the gradient method of the NonlinearSystemProblem class if it exists. If the gradient method is not implemented the Jacobian is appoximated using forward finite differences.

Parameters:

xarray-like

Vector of independent variables.

Returns:

array-like

Jacobian matrix of the residual vector formatted as a 2D array.

plot_convergence_history(savefile=False, filename=None, output_dir='output')

Plot the convergence history of the problem as the two-norm of the residual vector versus the number of iterations.

This method should be called only after the optimization problem has been solved, as it relies on data generated by the solving process.

Parameters:

savefilebool, optional

If True, the plot is saved to a file instead of being displayed. Default is False.

filenamestr, optional

The name of the file to save the plot to. If not specified, the filename is automatically generated using the problem name and the start datetime. The file extension is not required.

output_dirstr, optional

The directory where the plot file will be saved if savefile is True. Default is “output”.

Returns:

matplotlib.figure.Figure

The Matplotlib figure object for the plot. This can be used for further customization or display.

Raises:

ValueError

If this method is called before the problem has been solved.

print_convergence_history(savefile=False, filename=None, output_dir='output')

Print the convergence history of the problem.

The convergence history includes:

• Number of function evaluations

• Number of gradient evaluations

• Two-norm of the residual vector

• Two-norm of the solution step

The method provides a detailed report on:

• Exit message

• Success status

• Execution time

This method should be called only after the optimization problem has been solved, as it relies on data generated by the solving process.

Parameters:

savefilebool, optional

If True, the convergence history will be saved to a file, otherwise printed to standard output. Default is False.

filenamestr, optional

The name of the file to save the convergence history. If not specified, the filename is automatically generated using the problem name and the start datetime. The file extension is not required.

output_dirstr, optional

The directory where the plot file will be saved if savefile is True. Default is “output”.

Raises:

ValueError

If this method is called before the problem has been solved.

residual(x, called_from_jac=False)

Evaluate the nonlinear system residuals.

Parameters:

xarray_like

Independent variable vector.

Returns:

array_like

Residuals of the problem.

solve(x0)

Solve the nonlinear system using the specified solver.

Parameters:

x0array-like

Initial guess for the solution of the nonlinear system.

Returns:

RootResults

A result object from scipy’s root detailing the outcome of the solution process.