===================
API for solution methods
===================

The package offers a few different ways to interact with the fast direct solvers generated by HPS algorithms.

Building the Fast Direct Solver
==================================

In many use cases, one wants to construct a direct solver and then apply it to many different boundary conditions sequentially. The pair of functions :func:`jaxhps.build_solver` and :func:`jaxhps.solve` are designed to facilitate this.

.. note::
   :func:`jaxhps.build_solver` by default moves data from the GPU to the CPU while building the solution operator. This can significantly slow down the time required to build the solver. If only one solution is required, the subtree recomputation methods may be preferrable.


.. autofunction:: jaxhps.build_solver

.. autofunction:: jaxhps.solve


Subtree-Recomputation Solution Methods
========================================

To take full advantage of hardware acceleration, we designed subtree-recomputation methods. These methods are useful when you want to solve the PDE for a single right-hand-side very quickly. If you want to impose a Dirichlet or Robin boundary condition and know the boundary data at runtime, you can use :func:`jaxhps.solve_subtree`. 
Otherwise, you can use the pair of functions :func:`jaxhps.upward_pass_subtree` and :func:`jaxhps.downward_pass_subtree`. The upward pass returns the domain's Poincare--Steklov operator, which can be used, for example, to define a boundary integral equation specifying boundary data. The downward pass uses the partially-saved solution operators and performs recomputation where necessary.

.. autofunction:: jaxhps.solve_subtree

.. autofunction:: jaxhps.upward_pass_subtree

.. autofunction:: jaxhps.downward_pass_subtree