effluent.solver
===============

.. py:module:: effluent.solver

.. autoapi-nested-parse::

   The module contains the :class:`Solver <effluent.solver.Solver>` class, which performs
   numerical integration of the differential equations described in :doc:`/algorithm`.



Classes
-------

.. autoapisummary::

   effluent.solver.Solver


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

.. py:class:: Solver(beta_n=0.34, beta_t=0.17, mass_n=1.0, mass_t=0.18, method='RK45', rtol=0.001, atol=1e-06, first_step=0, max_step=0, start=0, stop=60, step=1)

   The class contains methods for solving the model equations.

   The constructor contains many adjustable parameters, related to the numerical
   solution procedure, the physical model parametrization and the density of output
   points. A more detailed description of each parameter is given in
   :doc:`/config/solver`, :doc:`/config/model` and :doc:`/config/output`.

   :param beta_n: Entrainment rate coefficient in the normal (across-jet) direction
   :param beta_t: Entrainment rate coefficient in the tangential (along-jet) direction
   :param mass_n: Added mass coefficient in the orthogonal direction
   :param mass_t: Added mass coefficient in the tangential direction
   :param method: Integration method to use
   :param rtol: Relative tolerance
   :param atol: Absolute tolerance
   :param first_step: Initial step size
   :param max_step: Maximum allowed step size
   :param start: Time (in seconds) of first trajectory point
   :param stop: Time (in seconds) of last trajectory point
   :param step: Time (in seconds) between trajectory points


   .. py:method:: odefunc(t, y)

      ODE function to be solved by scipy methods

      The order of the variables is (x, y, z, u, v, w, density, radius)

      :param t: Vectorized time parameter of shape (n_times, )
      :param y: Input vector of shape (n_vars, n_times)
      :return: Time derivative of the primary variables (n_vars, n_times)



   .. py:method:: set_ambient(ambient, time)

      Set ambient conditions

      Set ambient conditions of the initial value problem by sampling ocean data
      at a specific point in time.

      :param ambient: Properties of the ambient ocean
      :param time: Sampling time



   .. py:method:: set_init(pipe, time)

      Set initial conditions

      Set initial conditions of the initial value problem by sampling pipe parameters
      at a specific point in time.

      :param pipe: Properties of the pipe and effluent discharge
      :param time: Sampling time



   .. py:method:: solve()

      Solve the differential equations described in :doc:`/algorithm`.

      Internally, this function uses ``scipy.integrate.solve_ivp`` to compute the
      solution. Solver properties are set using the class constructor.

      The returned dataset contains the value of each primary variable at the
      pre-determined output points. The variable names are ``x``, ``y``, ``z``, ``u``,
      ``v``, ``w``, ``density``, ``radius``, all indexed by the coordinate ``t``.

      The returned dataset also contains the secondary variable ``dilution``,
      indexed by the coordinate ``t``.

      :return: An xarray.Dataset containing the solution



   .. py:method:: volume_change_ratio(t, y)

      Compute the time derivative of log(V) according to :eq:`sol_voldef`.

      This function is required to determine when the simulation should be terminated.

      :param t: Seconds since release
      :param y: Tuple of primary variables: ``x``, ``y``, ``z``, ``u``, ``v``, ``w``, ``density``, ``radius``
      :return: Time derivative of log(V)