# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401

import builtins
import typing
from symbolica.core import Expression

@typing.final
class Vakint:
    r"""
    Vakint engine and settings used for matching, reduction, and evaluation.

    Construct one instance and reuse it: initialization processes the complete topology library.
    """
    def __new__(cls, run_time_decimal_precision: typing.Optional[builtins.int] = None, evaluation_order: typing.Optional[typing.Sequence[VakintEvaluationMethod]] = None, epsilon_symbol: typing.Optional[Expression] = None, mu_r_sq_symbol: typing.Optional[Expression] = None, form_exe_path: typing.Optional[builtins.str] = None, python_exe_path: typing.Optional[builtins.str] = None, verify_numerator_identification: typing.Optional[builtins.bool] = None, integral_normalization_factor: typing.Optional[builtins.str] = None, allow_unknown_integrals: typing.Optional[builtins.bool] = None, clean_tmp_dir: typing.Optional[builtins.bool] = None, number_of_terms_in_epsilon_expansion: typing.Optional[builtins.int] = None, use_dot_product_notation: typing.Optional[builtins.bool] = None, temporary_directory: typing.Optional[builtins.str] = None) -> Vakint:
        r"""
        Create a new Vakint instance, specifying details of the evaluation stack. Note that the same instance can be recycled across multiple evaluations.
        Note that the creation of a Vakint instance involves the processing and creation of the library of all known topologies, which can be time consuming.

        ## Examples
        ```python
        >>> from symbolica.community.vakint import Vakint
        >>> vakint = Vakint(evaluation_order=[])
        >>> vakint is not None
        True
        ```

        An empty evaluation order is appropriate for matching, canonicalization, and tensor
        reduction. Add explicit `VakintEvaluationMethod` entries before evaluating an integral;
        construction validates the executables required by those entries.

        Parameters
        ----------

        run_time_decimal_precision : Optional[int]
            The decimal precision to be used during the evaluation. Default is 17.
        evaluation_order : Optional[Sequence[VakintEvaluationMethod]]
            A list of `VakintEvaluationMethod` instances specifying the order in which evaluation methods are to be applied. Default is all available methods in a sensible order.
        epsilon_symbol : Optional[Expression]
            The symbol to be used for the dimensional regularisation parameter epsilon. Default is "ε".
        mu_r_sq_symbol : Optional[Expression]
            The symbol to be used for the renormalisation scale squared. Default is "mursq".
        form_exe_path : Optional[str]
            The path to the FORM executable. Default is "form".
        python_exe_path : Optional[str]
            The path to the Python executable. Default is "python3".
        verify_numerator_identification : Optional[bool]
            Whether to verify the identification of numerator structures. Default is True.
        integral_normalization_factor : Optional[str]
            The normalization factor to be used for integrals. Can be "MSbar", "pySecDec", "FMFTandMATAD" or a custom string. Default is "MSbar".
        allow_unknown_integrals : Optional[bool]
            Whether to allow unknown integrals to be processed. Default is True.
        clean_tmp_dir : Optional[bool]
            Whether to clean the temporary directory after evaluation. Default is True, unless the environment variable VAKINT_NO_CLEAN_TMP_DIR is set.
        number_of_terms_in_epsilon_expansion : Optional[int]
            The number of terms in the epsilon expansion to be computed. Default is 4.
        use_dot_product_notation : Optional[bool]
            Whether to use dot product notation for scalar products. Default is False.
        temporary_directory : Optional[str]
            The path to the temporary directory to be used. Default is None, in which case a system temporary directory will be used.
        """
    def numerical_result_from_expression(self, expr: Expression) -> VakintNumericalResult:
        r"""
        Interpret a Symbolica expression as a numerical Laurent series in epsilon.

        ## Examples
        ```python
        >>> from symbolica import E
        >>> from symbolica.community.vakint import Vakint
        >>> vakint = Vakint(evaluation_order=[])
        >>> result = vakint.numerical_result_from_expression(
        ...     E("vakint::ε^-2 + 1 + 0.12*vakint::ε^-1")
        ... )
        >>> sorted(exponent for exponent, _ in result.to_list())
        [-2, -1, 0]
        ```

        Parameters
        ----------

        expr : Expression
          A Symbolica expression representing a Laurent series in the dimensional regularisation parameter epsilon specified in the vakint engine.
        """
    def numerical_evaluation(self, evaluated_integral: typing.Any, params: typing.Mapping[builtins.str, builtins.float], externals: typing.Optional[typing.Mapping[builtins.int, tuple[builtins.float, builtins.float, builtins.float, builtins.float]]] = None) -> tuple[VakintNumericalResult, typing.Optional[VakintNumericalResult]]:
        r"""
        Substitute numerical parameters into an integral already evaluated parametrically by Vakint.

        ## Examples
        ```python
        >>> from symbolica import E
        >>> from symbolica.community.vakint import Vakint
        >>> vakint = Vakint(evaluation_order=[])
        >>> evaluated = E(
        ...     "muvsq*vakint::ε^-1 + mursq",
        ...     default_namespace="vakint",
        ... )
        >>> result, error = vakint.numerical_evaluation(
        ...     evaluated,
        ...     {"muvsq": 2.0, "mursq": 3.0},
        ... )
        >>> sorted(exponent for exponent, _ in result.to_list())
        [-1, 0]
        >>> error is None
        True
        ```

        Parameters
        ----------

        evaluated_integral : Expression
          A Symbolica expression representing an integral that has been evaluated parametrically by Vakint.
        params : Dict[str, float]
          A dictionary mapping parameter names to their numerical values.
        externals : Optional[Dict[int, Tuple[float, float, float, float]]]
          An optional dictionary mapping external momentum indices to their numerical 4-vector values.
        """
    def numerical_result_to_expression(self, result: VakintNumericalResult) -> Expression:
        r"""
        Convert a Vakint numerical result to a Symbolica Laurent-series expression.

        ## Examples
        ```python
        >>> from symbolica.community.vakint import Vakint, VakintNumericalResult
        >>> vakint = Vakint(evaluation_order=[])
        >>> result = VakintNumericalResult([
        ...     (-1, (2.0, 0.0)),
        ...     (0, (3.0, 0.0)),
        ... ])
        >>> expression = vakint.numerical_result_to_expression(result)
        >>> "ε" in str(expression)
        True
        ```
        """
    def to_canonical(self, integral_expression: Expression, short_form: typing.Optional[builtins.bool] = None) -> Expression:
        r"""
        Convert a Vakint expression to canonical momentum routing and topology numbering.

        ## Examples
        ```python
        >>> from symbolica import E
        >>> from symbolica.community.vakint import Vakint
        >>> vakint = Vakint(evaluation_order=[])
        >>> integral = E(
        ...     "topo(prop(18,edge(7,7),k(99),muvsq,1))",
        ...     default_namespace="vakint",
        ... )
        >>> canonical = vakint.to_canonical(integral, short_form=True)
        >>> "I1L" in str(canonical)
        True
        ```

        Parameters
        ----------

        integral_expression : Expression
          A Symbolica expression representing a vakint integral.
        short_form : Optional[bool]
          Whether to use the short form for the topology representation. Default is False.
        """
    def tensor_reduce(self, integral_expression: Expression) -> Expression:
        r"""
        Reduce the tensor integrals in a Vakint expression to scalar integrals.

        ## Examples
        ```python
        >>> from symbolica import E
        >>> from symbolica.community.vakint import Vakint
        >>> vakint = Vakint(evaluation_order=[])
        >>> integral = E(
        ...     "k(1,101)*k(1,102)*topo(prop(1,edge(1,1),k(1),muvsq,1))",
        ...     default_namespace="vakint",
        ... )
        >>> reduced = vakint.tensor_reduce(integral)
        >>> "g(101,102)" in str(reduced)
        True
        ```

        Parameters
        ----------
        integral_expression : Expression
           A Symbolica expression representing a vakint integral.
        """
    def evaluate_integral(self, integral_expression: Expression) -> Expression:
        r"""
        Perform the parametric evaluation of *only the integral* appearing in the Symbolica expression given in input representing a vakint integral.
        The numerator is left unchanged.

        ## Examples
        ```python
        >>> from symbolica import E
        >>> from symbolica.community.vakint import Vakint, VakintEvaluationMethod
        >>> vakint = Vakint(
        ...     evaluation_order=[VakintEvaluationMethod.new_alphaloop_method()]
        ... )
        >>> integral = E(
        ...     "topo(prop(1,edge(1,1),k(1),muvsq,1))",
        ...     default_namespace="vakint",
        ... )
        >>> evaluated = vakint.evaluate_integral(integral)
        >>> "ε" in str(evaluated)
        True
        ```

        The AlphaLoop evaluation method used here invokes FORM. Configure `form_exe_path` if
        FORM is not available as `form` on `PATH`.

        Parameters
        ----------

        integral_expression : Expression
          A Symbolica expression representing a vakint integral.
        """
    def evaluate(self, integral_expression: Expression) -> Expression:
        r"""
        Perform the complete parametric evaluation of the Vakint integral represented by the Symbolica expression given in input.
        Note that the tensor reduction will be automatically performed on the input given.

        ## Examples
        ```python
        >>> from symbolica import E
        >>> from symbolica.community.vakint import Vakint, VakintEvaluationMethod
        >>> vakint = Vakint(
        ...     evaluation_order=[VakintEvaluationMethod.new_alphaloop_method()]
        ... )
        >>> integral = E(
        ...     "k(1,101)*k(1,102)*topo(prop(1,edge(1,1),k(1),muvsq,1))",
        ...     default_namespace="vakint",
        ... )
        >>> evaluated = vakint.evaluate(integral)
        >>> "g(101,102)" in str(evaluated)
        True
        ```

        This complete path performs tensor reduction before integral evaluation and therefore
        has the same FORM requirement as `evaluate_integral` for the AlphaLoop method.

        Parameters
        ----------

        integral_expression : Expression
          A Symbolica expression representing a vakint integral.
        """

@typing.final
class VakintEvaluationMethod:
    r"""
    One configured backend in a `Vakint` instance's evaluation order.
    """
    def __str__(self) -> builtins.str:
        r"""
        String representation of the evaluation method.
        """
    @classmethod
    def new_alphaloop_method(cls) -> VakintEvaluationMethod:
        r"""
        Create a new VakintEvaluationMethod instance representing the AlphaLoop method.
        This method does not take any parameters.

        ## Examples
        ```python
        >>> from symbolica.community.vakint import VakintEvaluationMethod
        >>> alphaloop_method = VakintEvaluationMethod.new_alphaloop_method()
        >>> "AlphaLoop" in str(alphaloop_method)
        True
        ```
        """
    @classmethod
    def new_matad_method(cls, expand_masters: typing.Optional[builtins.bool] = None, susbstitute_masters: typing.Optional[builtins.bool] = None, substitute_hpls: typing.Optional[builtins.bool] = None, direct_numerical_substition: typing.Optional[builtins.bool] = None) -> VakintEvaluationMethod:
        r"""
        Create a new VakintEvaluationMethod instance representing the MATAD method.

        ## Examples
        ```python
        >>> from symbolica.community.vakint import VakintEvaluationMethod
        >>> matad_method = VakintEvaluationMethod.new_matad_method(
        ...     expand_masters=True,
        ...     susbstitute_masters=True,
        ...     substitute_hpls=True,
        ...     direct_numerical_substition=True,
        ... )
        >>> "MATAD" in str(matad_method)
        True
        ```

        Parameters
        ----------

        expand_masters : Optional[bool]
           Whether to expand master integrals. Default is True.
        susbstitute_masters : Optional[bool]
           Whether to substitute master integrals. Default is True.
        substitute_hpls : Optional[bool]
           Whether to substitute harmonic polylogarithms. Default is True.
        direct_numerical_substition : Optional[bool]
           Whether to perform direct numerical substitution. Default is True.

        Notes
        -----
        `susbstitute_masters` and `direct_numerical_substition` retain their historical
        misspellings for API compatibility. They mean `substitute_masters` and
        `direct_numerical_substitution`, respectively.
        """
    @classmethod
    def new_fmft_method(cls, expand_masters: typing.Optional[builtins.bool] = None, susbstitute_masters: typing.Optional[builtins.bool] = None) -> VakintEvaluationMethod:
        r"""
        Create a new VakintEvaluationMethod instance representing the FMFT method.

        ## Examples
        ```python
        >>> from symbolica.community.vakint import VakintEvaluationMethod
        >>> fmft_method = VakintEvaluationMethod.new_fmft_method(
        ...     expand_masters=True,
        ...     susbstitute_masters=True,
        ... )
        >>> "FMFT" in str(fmft_method)
        True
        ```

        Parameters
        ----------

        expand_masters : Optional[bool]
          Whether to expand master integrals. Default is True.
        susbstitute_masters : Optional[bool]
          Whether to substitute master integrals. Default is True.

        Notes
        -----
        `susbstitute_masters` retains its historical misspelling for API compatibility;
        it means `substitute_masters`.
        """
    @classmethod
    def new_pysecdec_method(cls, quiet: typing.Optional[builtins.bool] = None, relative_precision: typing.Optional[builtins.float] = None, min_n_evals: typing.Optional[builtins.int] = None, max_n_evals: typing.Optional[builtins.int] = None, reuse_existing_output: typing.Optional[builtins.str] = None, numerical_masses: typing.Optional[typing.Mapping[builtins.str, builtins.float]] = None, numerical_external_momenta: typing.Optional[typing.Mapping[builtins.int, tuple[builtins.float, builtins.float, builtins.float, builtins.float]]] = None) -> VakintEvaluationMethod:
        r"""
        Create a new VakintEvaluationMethod instance representing the numerical pySecDec method.

        ## Examples
        ```python
        >>> from symbolica.community.vakint import VakintEvaluationMethod
        >>> pysecdec_method = VakintEvaluationMethod.new_pysecdec_method(
        ...     quiet=True,
        ...     relative_precision=1e-7,
        ...     min_n_evals=10_000,
        ...     max_n_evals=1_000_000_000_000,
        ...     reuse_existing_output=None,
        ...     numerical_masses={"muvsq": 1.0},
        ...     numerical_external_momenta={
        ...         1: (1.0, 0.0, 0.0, 0.0),
        ...         2: (0.0, 1.0, 0.0, 0.0),
        ...     },
        ... )
        >>> "PySecDec" in str(pysecdec_method)
        True
        ```

        pySecDec performs numerical evaluation, so every required mass and external momentum
        must have a numerical value. Constructing this method does not run pySecDec; evaluation
        requires a working Python/pySecDec installation.

        Parameters
        ----------

        quiet : Optional[bool]
           Whether to suppress output from pySecDec. Default is True.
        relative_precision : Optional[float]
           The relative precision to be achieved in the numerical integration. Default is 1e-7.
        min_n_evals : Optional[int]
           The minimum number of evaluations to be performed in the numerical integration. Default is 10,000.
        max_n_evals : Optional[int]
           The maximum number of evaluations to be performed in the numerical integration. Default is 1,000,000,000,000.
        reuse_existing_output : Optional[str]
           Path to existing pySecDec output to reuse. Default is None.
        numerical_masses : Optional[Dict[str, float]]
           A dictionary mapping mass parameter names to their numerical values. Default is an empty dictionary.
        numerical_external_momenta : Optional[Dict[int, Tuple[float, float, float, float]]]
           A dictionary mapping external momentum indices to their numerical 4-vector values. Default is an empty dictionary.
        """

@typing.final
class VakintExpression:
    r"""
    A Vakint integral split into its numerator and normalized topology structure.

    Construct this wrapper from a Symbolica expression before applying Vakint operations.
    """
    def __str__(self) -> builtins.str:
        r"""
        String representation of the VakintExpression.
        """
    def to_expression(self) -> Expression:
        r"""
        Convert the VakintExpression back to a Symbolica Expression.

        ## Examples
        ```python
        >>> from symbolica import E
        >>> from symbolica.community.vakint import VakintExpression
        >>> integral = VakintExpression(E('''
        ...     k(1,11)*k(1,11)
        ...     *topo(prop(1,edge(1,1),k(1),muvsq,1))
        ... ''', default_namespace="vakint"))
        >>> "topo(" in str(integral.to_expression())
        True
        ```
        """
    def __new__(cls, atom: typing.Any) -> VakintExpression:
        r"""
        Split a Symbolica expression into Vakint numerator and topology components.

        ## Examples
        ```python
        >>> from symbolica import E
        >>> from symbolica.community.vakint import VakintExpression
        >>> integral = E('''
        ...     (
        ...         k(1,11)*k(2,11)*k(1,22)*k(2,22)
        ...       + p(1,11)*k(3,11)*k(3,22)*p(2,22)
        ...       + p(1,11)*p(2,11)*(k(2,22)+k(1,22))*k(2,22)
        ...     )*topo(
        ...          prop(1,edge(1,2),k(1),muvsq,1)
        ...         * prop(2,edge(2,3),k(2),muvsq,1)
        ...         * prop(3,edge(3,1),k(3),muvsq,1)
        ...         * prop(4,edge(1,4),k(3)-k(1),muvsq,1)
        ...         * prop(5,edge(2,4),k(1)-k(2),muvsq,1)
        ...         * prop(6,edge(3,4),k(2)-k(3),muvsq,1)
        ...     )
        ... ''', default_namespace="vakint")
        >>> wrapped = VakintExpression(integral)
        >>> "topo(" in str(wrapped)
        True
        ```

        Parameters
        ----------

        atom : Expression
          A Symbolica Expression containing a vakint integral, i.e. a sum of terms, each a product of a numerator and a `vakint::topo(...)` structure.
        """

@typing.final
class VakintNumericalResult:
    r"""
    Numerical Laurent series in the dimensional-regularization parameter epsilon.
    """
    def __str__(self) -> builtins.str:
        r"""
        String representation of the numerical result.

        ## Examples
        ```python
        >>> from symbolica.community.vakint import VakintNumericalResult
        >>> result = VakintNumericalResult([
        ...     (-3, (0.0, -11440.53140354612)),
        ...     (-2, (0.0, 57169.95521898031)),
        ...     (-1, (0.0, -178748.9838377694)),
        ...     (0, (0.0, 321554.1122184795)),
        ... ])
        >>> str(result)
        ε^-3 : (0+-11440.5314035461i)
        ε^-2 : (0+57169.9552189803i)
        ε^-1 : (0+-178748.983837769i)
        ε^ 0 : (0+321554.112218480i)
        ```
        """
    def to_list(self) -> builtins.list[tuple[builtins.int, tuple[builtins.float, builtins.float]]]:
        r"""
        Convert the numerical result to a native Python list of (epsilon exponent, (real, imag)) tuples.

        ## Examples
        ```python
        >>> from symbolica.community.vakint import VakintNumericalResult
        >>> result = VakintNumericalResult([
        ...     (-3, (0.0, -11440.53140354612)),
        ...     (-2, (0.0, 57169.95521898031)),
        ...     (-1, (0.0, -178748.9838377694)),
        ...     (0, (0.0, 321554.1122184795)),
        ... ])

        >>> values = result.to_list()
        >>> values[0]
        (-3, (0.0, -11440.53140354612))
        ```
        """
    def __new__(cls, values: typing.Sequence[tuple[builtins.int, tuple[builtins.float, builtins.float]]]) -> VakintNumericalResult:
        r"""
        Create a numerical Laurent series from `(epsilon exponent, (real, imaginary))` tuples.

        ## Examples
        ```python
        >>> from symbolica.community.vakint import VakintNumericalResult
        >>> result = VakintNumericalResult([
        ...     (-3, (0.0, -11440.53140354612)),
        ...     (-2, (0.0, 57169.95521898031)),
        ...     (-1, (0.0, -178748.9838377694)),
        ...     (0, (0.0, 321554.1122184795)),
        ... ])
        >>> len(result.to_list())
        4
        ```

        Parameters
        ----------

        values : List[Tuple[int, Tuple[float, float]]]
           A list of tuples, each containing an integer exponent of epsilon and a tuple of two floats
           representing the real and imaginary parts of the coefficient.
        """
    def compare_to(self, other: VakintNumericalResult, relative_threshold: builtins.float, error: typing.Optional[VakintNumericalResult] = None, max_pull: typing.Optional[builtins.float] = None) -> tuple[builtins.bool, builtins.str]:
        r"""
        Compare this numerical result to another, returning a tuple of (bool, str) where the bool indicates whether the results match within the specified thresholds,
        and the str provides details of the comparison.

        ## Examples
        ```python
        >>> from symbolica.community.vakint import VakintNumericalResult
        >>> result1 = VakintNumericalResult([
        ...     (-3, (0.0, -11440.53140354612)),
        ... ])
        >>> result2 = VakintNumericalResult([
        ...     (-3, (0.0, -11440.53140354612)),
        ...     (-2, (0.0, 2.0)),
        ... ])
        >>> matches, details = result1.compare_to(result2, relative_threshold=1e-5)
        >>> matches
        False
        >>> "ε^-2" in details
        True
        ```

        Parameters
        ----------

        other : VakintNumericalResult
           The other numerical result to compare to.
        relative_threshold : float
           The relative threshold for comparison.
        error : Optional[VakintNumericalResult]
           An optional numerical result representing the error in the evaluation.
        max_pull : Optional[float]
           The maximum pull for comparison. Default is 3.0.
        """