ThresholdSearch2D
-----------------

.. xml:tag:: <meta solver="ThresholdSearch2D"> [ThresholdSearch2D]

   Corresponding Python class: :py:class:`meta.shockley.ThresholdSearch2D`.

   Solver for threshold search of semiconductor laser in 2D Cartesian geometry.

   This solver performs thermo-electrical computations followed by determination ot threshold current and optical analysis in order to determine the threshold of a semiconductor laser. The search is performed by ``scipy`` root finding algorithm in order to determine the voltage and electric current ensuring no optical loss in the laser cavity.

   The optical computations are done with effective index method.

   :attr required name: Solver name.

   .. xml:contents::

      .. xml:tag:: <geometry> [in meta.ThresholdSearch2D]

         Geometry settings for all solvers.

         :attr required thermal: Geometry used by the thermal solver. (Cartesian2D geometry)
         :attr required electrical: Geometry used by the electrical, diffusion, and gain solvers. (Cartesian2D geometry)
         :attr required optical: Geometry used by the optical solver. (Cartesian2D geometry)

      .. xml:tag:: <mesh> [in meta.ThresholdSearch2D]

         Mesh settings for all solvers.

         :attr required thermal: Mesh used by the thermal solver. (mesh)
         :attr required electrical: Mesh used by the electrical solver. (mesh)
         :attr diffusion: Mesh used by the carriers diffusion solver. (mesh)
         :attr optical: Mesh used by the optical solver. (mesh)
         :attr empty-elements: Should empty regions (e.g. air) be included into electrical computations? (\ ``default``\ , \ ``include``\ , or \ ``exclude``\ , default is \ ``default``\ )

      .. xml:tag:: <optical> [in meta.ThresholdSearch2D]

         Configuration of the optical solver

         :attr polarization: Mode polarization. (\ ``TE``\  or \ ``TM``\ , default is \ ``TE``\ )
         :attr mn: Lateral mode number (int, default 0)
         :attr required lam: Emission wavelength. The effective index is searched for this wavelength. (float (nm))
         :attr dneff: Step, by which the effective index is swept while searching for the approximate mode. (float, default 0.02)
         :attr vneff: "Vertical effective index" i.e. the effective index what would be in the absence of lateral confinement; setting this value helps to find modes in very long resonators. (float)
         :attr vat: Horizontal position of at which the vertical part of the field is calculated. (float (µm))
         :attr emission: Direction of the useful light emission. Necessary for the over-threshold model to correctly compute the output power. (\ ``front``\  or \ ``back``\ , default is \ ``front``\ )

      .. xml:tag:: <root> [in meta.ThresholdSearch2D]

         Configuration of the root-finder used in threshold search.

         :attr required bcond: Number of the voltage boundary condition to vary during the threshold search. (int)
         :attr vmin: Minimum voltage to search threshold for. It should be below the threshold. (float)
         :attr vmax: Maximum voltage to search threshold for. It should be above the threshold. (float)
         :attr vtol: Tolerance on voltage in the root search. (float (V), default 1e-05 V)
         :attr maxiter: Maximum number of root finding iterations. (int, default 50)

      .. xml:tag:: <voltage> [in meta.ThresholdSearch2D]

         Voltage boundary conditions. See subsection :ref:`sec-xpl-Boundary-conditions`.

      .. xml:tag:: <temperature> [in meta.ThresholdSearch2D]

         Temperature boundary conditions. See subsection :ref:`sec-xpl-Boundary-conditions`.

      .. xml:tag:: <heatflux> [in meta.ThresholdSearch2D]

         Heat Flux boundary conditions. See subsection :ref:`sec-xpl-Boundary-conditions`.

      .. xml:tag:: <convection> [in meta.ThresholdSearch2D]

         Convective boundary conditions. See subsection :ref:`sec-xpl-Boundary-conditions`.

         This boundary condition does not have \ *value*\  attribute. Use \ *coeff*\  for convection coefficient and \ *ambient*\  for ambient temperature instead.

      .. xml:tag:: <radiation> [in meta.ThresholdSearch2D]

         Radiative boundary conditions. See subsection :ref:`sec-xpl-Boundary-conditions`.

         This boundary condition does not have \ *value*\  attribute. Use \ *emissivity*\  for surface emissivity and \ *ambient*\  for ambient temperature instead.

      .. xml:tag:: <junction> [in meta.ThresholdSearch2D]

         Configuration of the effective model of p-n junction.

         :attr beta#: Junction coefficients. This is an inverse of the junction thermal voltage. (float (1/V))
         :attr js#: Reverse bias current densities. (float (A/m\ :sup:`2`\ ))
         :attr pnjcond: Initial vertical conductivity of the junctions. (float (S/m), default 5.0 S/m)

      .. xml:tag:: <contacts> [in meta.ThresholdSearch2D]

         Properties of the contact layers.

         :attr pcond: p-contact conductivity. (float (S/m), default 5.0 S/m)
         :attr ncond: n-contact conductivity. (float (S/m), default 50.0 S/m)

      .. xml:tag:: <loop> [in meta.ThresholdSearch2D]

         Configuration of the self-consistent thermo-electric loop.

         :attr skip-thermal: Skip thermal computations. The structure is assumed to have a constant temperature \ *inittemp*\ . This can be used to look for the threshold under pulse laser operation. (bool, default is \ ``no``\ )
         :attr tfreq: Number of electrical iterations per single thermal step. As temperature tends to converge faster, it is reasonable to repeat thermal solution less frequently. (int, default 6)
         :attr inittemp: Initial temperature used for the first computation. (float (K), default 300 K)
         :attr maxterr: Maximum allowed temperature error. (float (K), default 0.05 K)
         :attr maxcerr: Maximum allowed current density error. (float (%), default 0.05 %)

      .. xml:tag:: <tmatrix> [in meta.ThresholdSearch2D]

         Matrix configuration for the thermal solver.

         :attr algorithm: Algorithm used for solving set of linear positive-definite equations. (\ ``cholesky``\ , \ ``gauss``\ , or \ ``iterative``\ , default is \ ``cholesky``\ )

         .. xml:tag:: <iterative> [in meta.ThresholdSearch2D]

            Parameters for iterative matrix solver. PLaSK uses `NSPCG`_ package for performing iterations. Please refer to its documentation for explanation of most of the settings.

            .. _NSPCG: https://web.ma.utexas.edu/CNA/NSPCG/

            :attr maxit: Maximum number of iterations. (int, default 1000)
            :attr maxerr: Maximum iteration error. (float, default 1e-6)
            :attr noconv: Desired behavior if the iterative solver does not converge. (\ ``error``\ , \ ``warning``\ , or \ ``continue``\ , default is \ ``warning``\ )
            :attr accelerator: Accelerator used for iterative matrix solver. (\ ``cg``\ , \ ``si``\ , \ ``sor``\ , \ ``srcg``\ , \ ``srsi``\ , \ ``basic``\ , \ ``me``\ , \ ``cgnr``\ , \ ``lsqr``\ , \ ``odir``\ , \ ``omin``\ , \ ``ores``\ , \ ``iom``\ , \ ``gmres``\ , \ ``usymlq``\ , \ ``usymqr``\ , \ ``landir``\ , \ ``lanmin``\ , \ ``lanres``\ , \ ``cgcr``\ , or \ ``bcgs``\ , default is \ ``cg``\ )
            :attr preconditioner: Preconditioner used for iterative matrix solver. (\ ``rich``\ , \ ``jac``\ , \ ``ljac``\ , \ ``ljacx``\ , \ ``sor``\ , \ ``ssor``\ , \ ``ic``\ , \ ``mic``\ , \ ``lsp``\ , \ ``neu``\ , \ ``lsor``\ , \ ``lssor``\ , \ ``llsp``\ , \ ``lneu``\ , \ ``bic``\ , \ ``bicx``\ , \ ``mbic``\ , or \ ``mbicx``\ , default is \ ``ic``\ )
            :attr nfact: This number initializes the frequency of partial factorizations. It specifies the number of linear system evaluations between factorizations. The default value is 1, which means that a factorization is performed at every iteration. (int, default 10)
            :attr ndeg: Degree of the polynomial to be used for the polynomial preconditioners. (int, default 1)
            :attr lvfill: Level of fill-in for incomplete Cholesky preconditioners. Increasing this value will result in more accurate factorizations at the expense of increased memory usage and factorization time. (int, default 0)
            :attr ltrunc: Truncation bandwidth to be used when approximating the inverses of matrices with dense banded matrices. An increase in this value means a more accurate factorization at the expense of increased storage. (int, default 0)
            :attr omega: Relaxation parameter. (float, default 1.0)
            :attr nsave: The number of old vectors to be saved for the truncated acceleration methods. (int, default 5)
            :attr nrestart: The number of iterations between restarts for the restarted acceleration methods. (int, default 100000)

            .. list-table:: Preconditioner choices:

             * - ``rich``

               - Richardson's method

             * - ``jac``

               - Jacobi method

             * - ``ljac``

               - Line Jacobi method

             * - ``ljacx``

               - Line Jacobi method (approx. inverse)

             * - ``sor``

               - Successive Overrelaxation

             * - ``ssor``

               - Symmetric SOR (can be used only with SOR accelerator)

             * - ``ic``

               - Incomplete Cholesky (default)

             * - ``mic``

               - Modified Incomplete Cholesky

             * - ``lsp``

               - Least Squares Polynomial

             * - ``neu``

               - Neumann Polynomial

             * - ``lsor``

               - Line SOR

             * - ``lssor``

               - Line SSOR

             * - ``llsp``

               - Line Least Squares Polynomial

             * - ``lneu``

               - Line Neumann Polynomial

             * - ``bic``

               - Block Incomplete Cholesky (ver. 1)

             * - ``bicx``

               - Block Incomplete Cholesky (ver. 2)

             * - ``mbic``

               - Modified Block Incomplete Cholesky (ver. 1)

             * - ``mbicx``

               - Modified Block Incomplete Cholesky (ver. 2)

            

            .. list-table:: Accelerator choices:

             * - ``cg``

               - Conjugate Gradient acceleration (default)

             * - ``si``

               - Chebyshev acceleration or Semi-Iteration

             * - ``sor``

               - Successive Overrelaxation (can use only SOR preconditioner)

             * - ``srcg``

               - Symmetric Successive Overrelaxation Conjugate Gradient Algorithm (can use only SSOR preconditioner)

             * - ``srsi``

               - Symmetric Successive Overrelaxation Semi-Iteration Algorithm (can use only SSOR preconditioner)

             * - ``basic``

               - Basic Iterative Method

             * - ``me``

               - Minimal Error Algorithm

             * - ``cgnr``

               - Conjugate Gradient applied to the Normal Equations

             * - ``lsqr``

               - Least Squares Algorithm

             * - ``odir``

               - ORTHODIR, a truncated/restarted method useful for nonsymmetric systems of equations

             * - ``omin``

               - ORTHOMIN, a common truncated/restarted method used for nonsymmetric systems

             * - ``ores``

               - ORTHORES, another truncated/restarted method for nonsymmetric systems

             * - ``iom``

               - Incomplete Orthogonalization Method

             * - ``gmres``

               - Generalized Minimal Residual Method

             * - ``usymlq``

               - Unsymmetric LQ

             * - ``usymqr``

               - Unsymmetric QR

             * - ``landir``

               - Lanczos/ORTHODIR

             * - ``lanmin``

               - Lanczos/ORTHOMIN or Biconjugate Gradient Method

             * - ``lanres``

               - Lanczos/ORTHORES or “two-sided” Lanczos Method

             * - ``cgcr``

               - Constrained Generalized Conjugate Residual Method

             * - ``bcgs``

               - Biconjugate Gradient Squared Method

      .. xml:tag:: <ematrix> [in meta.ThresholdSearch2D]

         Matrix configuration for the electrical solver.

         :attr algorithm: Algorithm used for solving set of linear positive-definite equations. (\ ``cholesky``\ , \ ``gauss``\ , or \ ``iterative``\ , default is \ ``cholesky``\ )

         .. xml:tag:: <iterative> [in meta.ThresholdSearch2D]

            Parameters for iterative matrix solver. PLaSK uses `NSPCG`_ package for performing iterations. Please refer to its documentation for explanation of most of the settings.

            .. _NSPCG: https://web.ma.utexas.edu/CNA/NSPCG/

            :attr maxit: Maximum number of iterations. (int, default 1000)
            :attr maxerr: Maximum iteration error. (float, default 1e-6)
            :attr noconv: Desired behavior if the iterative solver does not converge. (\ ``error``\ , \ ``warning``\ , or \ ``continue``\ , default is \ ``warning``\ )
            :attr accelerator: Accelerator used for iterative matrix solver. (\ ``cg``\ , \ ``si``\ , \ ``sor``\ , \ ``srcg``\ , \ ``srsi``\ , \ ``basic``\ , \ ``me``\ , \ ``cgnr``\ , \ ``lsqr``\ , \ ``odir``\ , \ ``omin``\ , \ ``ores``\ , \ ``iom``\ , \ ``gmres``\ , \ ``usymlq``\ , \ ``usymqr``\ , \ ``landir``\ , \ ``lanmin``\ , \ ``lanres``\ , \ ``cgcr``\ , or \ ``bcgs``\ , default is \ ``cg``\ )
            :attr preconditioner: Preconditioner used for iterative matrix solver. (\ ``rich``\ , \ ``jac``\ , \ ``ljac``\ , \ ``ljacx``\ , \ ``sor``\ , \ ``ssor``\ , \ ``ic``\ , \ ``mic``\ , \ ``lsp``\ , \ ``neu``\ , \ ``lsor``\ , \ ``lssor``\ , \ ``llsp``\ , \ ``lneu``\ , \ ``bic``\ , \ ``bicx``\ , \ ``mbic``\ , or \ ``mbicx``\ , default is \ ``ic``\ )
            :attr nfact: This number initializes the frequency of partial factorizations. It specifies the number of linear system evaluations between factorizations. The default value is 1, which means that a factorization is performed at every iteration. (int, default 10)
            :attr ndeg: Degree of the polynomial to be used for the polynomial preconditioners. (int, default 1)
            :attr lvfill: Level of fill-in for incomplete Cholesky preconditioners. Increasing this value will result in more accurate factorizations at the expense of increased memory usage and factorization time. (int, default 0)
            :attr ltrunc: Truncation bandwidth to be used when approximating the inverses of matrices with dense banded matrices. An increase in this value means a more accurate factorization at the expense of increased storage. (int, default 0)
            :attr omega: Relaxation parameter. (float, default 1.0)
            :attr nsave: The number of old vectors to be saved for the truncated acceleration methods. (int, default 5)
            :attr nrestart: The number of iterations between restarts for the restarted acceleration methods. (int, default 100000)

            .. list-table:: Preconditioner choices:

             * - ``rich``

               - Richardson's method

             * - ``jac``

               - Jacobi method

             * - ``ljac``

               - Line Jacobi method

             * - ``ljacx``

               - Line Jacobi method (approx. inverse)

             * - ``sor``

               - Successive Overrelaxation

             * - ``ssor``

               - Symmetric SOR (can be used only with SOR accelerator)

             * - ``ic``

               - Incomplete Cholesky (default)

             * - ``mic``

               - Modified Incomplete Cholesky

             * - ``lsp``

               - Least Squares Polynomial

             * - ``neu``

               - Neumann Polynomial

             * - ``lsor``

               - Line SOR

             * - ``lssor``

               - Line SSOR

             * - ``llsp``

               - Line Least Squares Polynomial

             * - ``lneu``

               - Line Neumann Polynomial

             * - ``bic``

               - Block Incomplete Cholesky (ver. 1)

             * - ``bicx``

               - Block Incomplete Cholesky (ver. 2)

             * - ``mbic``

               - Modified Block Incomplete Cholesky (ver. 1)

             * - ``mbicx``

               - Modified Block Incomplete Cholesky (ver. 2)

            

            .. list-table:: Accelerator choices:

             * - ``cg``

               - Conjugate Gradient acceleration (default)

             * - ``si``

               - Chebyshev acceleration or Semi-Iteration

             * - ``sor``

               - Successive Overrelaxation (can use only SOR preconditioner)

             * - ``srcg``

               - Symmetric Successive Overrelaxation Conjugate Gradient Algorithm (can use only SSOR preconditioner)

             * - ``srsi``

               - Symmetric Successive Overrelaxation Semi-Iteration Algorithm (can use only SSOR preconditioner)

             * - ``basic``

               - Basic Iterative Method

             * - ``me``

               - Minimal Error Algorithm

             * - ``cgnr``

               - Conjugate Gradient applied to the Normal Equations

             * - ``lsqr``

               - Least Squares Algorithm

             * - ``odir``

               - ORTHODIR, a truncated/restarted method useful for nonsymmetric systems of equations

             * - ``omin``

               - ORTHOMIN, a common truncated/restarted method used for nonsymmetric systems

             * - ``ores``

               - ORTHORES, another truncated/restarted method for nonsymmetric systems

             * - ``iom``

               - Incomplete Orthogonalization Method

             * - ``gmres``

               - Generalized Minimal Residual Method

             * - ``usymlq``

               - Unsymmetric LQ

             * - ``usymqr``

               - Unsymmetric QR

             * - ``landir``

               - Lanczos/ORTHODIR

             * - ``lanmin``

               - Lanczos/ORTHOMIN or Biconjugate Gradient Method

             * - ``lanres``

               - Lanczos/ORTHORES or “two-sided” Lanczos Method

             * - ``cgcr``

               - Constrained Generalized Conjugate Residual Method

             * - ``bcgs``

               - Biconjugate Gradient Squared Method

      .. xml:tag:: <diffusion> [in meta.ThresholdSearch2D]

         Diffusion solver configuration.

         :attr fem-method: Order of the finite-element method. (\ ``linear``\  or \ ``parabolic``\ , default is \ ``parabolic``\ )
         :attr accuracy: Required relative accuracy. (float (%), default 0.01 %)
         :attr abs-accuracy: Required absolute minimal concentration accuracy. (float (cm\ :sup:`-3`\ ), default 5000000000000000.0 cm\ :sup:`-3`\ )
         :attr maxiters: Maximum number of allowed iterations before attempting to refine mesh. (int, default 20)
         :attr maxrefines: Maximum number of allowed mesh refinements. (int, default 5)
         :attr interpolation: Current density interpolation method name. (\ ``linear``\  or \ ``spline``\ , default is \ ``spline``\ )

      .. xml:tag:: <gain> [in meta.ThresholdSearch2D]

         Gain solver parameters.

         :attr lifetime: Average carriers lifetime. This parameter is used for gain spectrum broadening. (float (ps), default 0.1 ps)
         :attr matrix-elem: Value of the squared matrix element in gain computations. If it is not set it is estimated automatically. (float (eV×m\ :sub:`0`\ ))
         :attr strained: Boolean attribute indicating if the solver should consider strain in the active region. If set to \ *yes*\  then there must a layer with the role "\ *substrate*\ " in the geometry. The strain is computed by comparing the atomic lattice constants of the substrate and the quantum wells. (bool, default is \ ``no``\ )

      .. xml:tag:: <optical-root> [in meta.ThresholdSearch2D]

         Parameters of the horizontal root-finding algorithm.

         :attr method: Root finding algorithm. (\ ``muller``\ , \ ``broyden``\ , or \ ``brent``\ , default is \ ``muller``\ )
         :attr tolx: Maximum change of the effective frequency parameter which is allowed for convergent solution. (float, default 1e-06)
         :attr tolf-min: Minimum value of the determinant sufficient to assume convergence. (float, default 1e-07)
         :attr tolf-max: Maximum value of the determinant required to assume convergence. (float, default 2e-05)
         :attr maxstep: Maximum step in one iteration of root finding. Significant for the Broyden's method only. (float, default 0.1)
         :attr maxiter: Maximum number of root finding iterations. (int, default 500)
         :attr alpha: Parameter ensuring sufficient decrease of determinant in each step (Broyden method only). (float, default 1e-07)
         :attr lambda: Minimum decrease ratio of one step (Broyden method only). (float, default 1e-08)
         :attr initial-range: Initial range size (Muller method only). (complex, default 0.001)

      .. xml:tag:: <optical-stripe-root> [in meta.ThresholdSearch2D]

         Parameters of root-finding algorithm for one stripe.

         :attr method: Root finding algorithm. (\ ``muller``\ , \ ``broyden``\ , or \ ``brent``\ , default is \ ``muller``\ )
         :attr tolx: Maximum change of the effective frequency parameter which is allowed for convergent solution. (float, default 1e-06)
         :attr tolf-min: Minimum value of the determinant sufficient to assume convergence. (float, default 1e-07)
         :attr tolf-max: Maximum value of the determinant required to assume convergence. (float, default 1e-05)
         :attr maxstep: Maximum step in one iteration of root finding. Significant for the Broyden's method only. (float, default 0.1)
         :attr maxiter: Maximum number of root finding iterations. (int, default 500)
         :attr alpha: Parameter ensuring sufficient decrease of determinant in each step (Broyden method only). (float, default 1e-07)
         :attr lambda: Minimum decrease ratio of one step (Broyden method only). (float, default 1e-08)
         :attr initial-range: Initial range size (Muller method only). (complex, default 0.001)

      .. xml:tag:: <output> [in meta.ThresholdSearch2D]

         Settings for the solver output.

         :attr optical-res-x: Number of points along the horizontal axis for the saved and plotted optical field. (int, default 800)
         :attr optical-res-y: Number of points along the vertical axis for the saved and plotted optical field. (int, default 600)
