ngsPETSc.snes
=============

.. py:module:: ngsPETSc.snes

.. autoapi-nested-parse::

   This module contains all the functions related to the PETSc SNES



Classes
-------

.. autoapisummary::

   ngsPETSc.snes.NonLinearSolver


Module Contents
---------------

.. py:class:: NonLinearSolver(fes, a=None, residual=None, objective=None, jacobian=None, solverParameters={}, optionsPrefix='')

   This class creates a PETSc Non-Linear Solver (SNES) from a callback to
   a NGSolve residual vector

   :arg fes: the finite element space over which the non-linear problem
             is defined

   :arg a: the variational form reppresenting the non-linear problem

   :arg residual: callback to the residual for the non-linear solver,
                  this fuction is used only if the argument a is None.

   :arg objective: callback to the objective for the non-linear solver,
                  this fuction is used only if the argument a is None,
                  if False the PETSSc default is norm 2.

   :arg jacobian: callback to the Jacobian for the non-linear solver,
                  this fuction is used only if the argument a is None.


   .. py:attribute:: fes


   .. py:attribute:: second_order
      :value: False



   .. py:attribute:: snes


   .. py:attribute:: vectorMapping


   .. py:method:: setup(x0)

      This is method is used to setup the PETSc SNES object

      :arg x0: NGSolve grid function reppresenting the initial guess



   .. py:method:: solve(x0)

      This is method solves the non-linear problem

      :arg x0: NGSolve grid function reppresenting the initial guess



   .. py:method:: petscResidual(snes, x, f)

      This is method is used to wrap the callback to the resiudal in
      a PETSc compatible way

      :arg snes: PETSc SNES object reppresenting the non-linear solver

      :arg x: current guess of the solution as a PETSc Vec

      :arg f: residual function as PETSc Vec



   .. py:method:: residual()
      :abstractmethod:


      Callback to the residual of the non-linear problem

      :arg x: current guess of the solution as a PETSc Vec

      :return: the residual as an NGSolve grid function



   .. py:method:: petscObjective(snes, x)

      This is method is used to wrap the callback to the objetcive in
      a PETSc compatible way

      :arg snes: PETSc SNES object reppresenting the non-linear solver

      :arg x: current guess of the solution as a PETSc Vec

      :arg energy: energy as a PETSc Scalar



   .. py:method:: objective()
      :abstractmethod:


      Callback to the objective of the non-linear problem

      :arg x: current guess of the solution as a PETSc Vec

      :return: the energy



   .. py:method:: petscJacobian(snes, x, J, P)

      This is method is used to wrap the callback to the Jacobian in
      a PETSc compatible way

      :arg snes: PETSc SNES object reppresenting the non-linear solver

      :arg x: current guess of the solution as a PETSc Vec

      :arg J: Jacobian computed at x as a PETSc Mat

      :arg P: preconditioner for the Jacobian computed at x
              as a PETSc Mat



   .. py:method:: jacobian()
      :abstractmethod:


      Callback to the Jacobian of the non-linear problem

      :arg x: current guess of the solution as a PETSc Vec

      :return: the Jacobian as an NGSolve matrix