Metadata-Version: 2.4
Name: asymptotic
Version: 0.2.0
Summary: Symbolic asymptotics, transseries, dominant balance, and certified remainders on SymPy
Author-email: Bhuvanesh Bhatt <bhuvaneshbhatt@gmail.com>
License-Expression: GPL-3.0-only
Project-URL: Repository, https://github.com/BhuvaneshBhatt/asymptotic
Project-URL: Documentation, https://github.com/BhuvaneshBhatt/asymptotic/tree/main/docs
Project-URL: Issues, https://github.com/BhuvaneshBhatt/asymptotic/issues
Project-URL: Changelog, https://github.com/BhuvaneshBhatt/asymptotic/blob/main/CHANGELOG.md
Keywords: asymptotics,symbolic mathematics,computer algebra,sympy,limits,multivariate limits,series expansions,asymptotic expansions,asymptotic analysis,special functions,differential equations,recurrence relations,singularity analysis,formal series,symbolic computation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sympy>=1.14
Requires-Dist: exprtest>=0.1.0
Requires-Dist: funcprops>=0.3.0
Requires-Dist: semialg>=1.3.1
Provides-Extra: flint
Requires-Dist: python-flint>=0.9.0; extra == "flint"
Provides-Extra: optimization
Requires-Dist: symbopt>=0.1.0; extra == "optimization"
Provides-Extra: ode
Requires-Dist: odeanalysis>=0.1.0; extra == "ode"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: hypothesis>=6; extra == "test"
Provides-Extra: release
Requires-Dist: build>=1; extra == "release"
Requires-Dist: twine>=5; extra == "release"
Provides-Extra: benchmark
Requires-Dist: pytest>=8; extra == "benchmark"
Requires-Dist: pytest-benchmark>=4; extra == "benchmark"
Provides-Extra: lint
Requires-Dist: ruff>=0.16; extra == "lint"
Dynamic: license-file

# asymptotic

`asymptotic` is a symbolic asymptotic-analysis package built on SymPy. It spans directed real and multivariate asymptotics together with complex/sector-aware branch geometry, formal ODE/transseries interchange, asymptotic expansions, limits, sums, recurrences, implicit asymptotics, perturbation methods, and probability/Laplace asymptotics, and it includes certification and evidence for the conditions that make results valid. It handles simultaneous multivariate approaches, competing power/logarithmic/exponential scales, parameter conditions, and selected special-function and perturbation problems.

## Installation

```bash
python -m pip install asymptotic
```

The package requires Python 3.11 or later and SymPy 1.14 or later. The required `semialg` dependency installs python-flint 0.9.0 or later. The `flint` extra also declares this backend explicitly. The `ode` extra supplies the differential-equation integration.

## Start with a limit

```python
import sympy as sp
from asymptotic import limit, one_sided_limit
from asymptotic.limit_models import LimitStatus

x, y = sp.symbols("x y", real=True)
assert limit(x * y / sp.sqrt(x**2 + y**2), (x, y), (0, 0)) == 0
assert one_sided_limit(1 / x, x, 0, direction="+") == sp.oo
```
Note that the `direction` argument uses the SymPy convention for the sign: `+` means the approach is from the right and `-` means the approach is from the left. This differs from Mathematica's convention, in which `Direction -> +1` means you approach from more negative values and `Direction -> -1` means you approach from more positive values.

When you give a tuple of variables you're asking for a simultaneous limit, not one coordinate limit followed by another. For limit(...) and other API functions, the package gives the mathematical answer (without wrappers containing metadata) by default when that is feasible, i.e. it can be represented without losing unresolved branches or hypotheses. Use the option `return_result=True` when you need status, conditions or evidence.

```python
expr = x * y / (x**2 + y**2)
result = limit(expr, (x, y), (0, 0), return_result=True)
assert result.status is LimitStatus.DOES_NOT_EXIST
assert len({item.value for item in result.evidence}) >= 2
```

The result carries evidence for incompatible approaches. Inspect `result.evidence` when you need the proof route.

## An asymptotic sum

```python
from asymptotic import sum

n, k = sp.symbols("n k", positive=True, integer=True)
assert sum(
    k**-2, k, n, sp.oo, parameter=n, terms=3, method="euler-maclaurin"
) == 1/n + 1/(2 * n**2) + 1/(6 * n**3)
```

Use `return_result=True` for a sum's remainder, method and certificates. This option also exposes the internal records for expansion, solving, statistics and optimization workflows. Unresolved or unproved formal calculations retain their records. Lazy nested expansions and scale-regime stratifications keep the structures needed to express their mathematics; see the [return conventions](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/api.md#mathematical-values-and-evidence).

## An asymptotic expansion: keep the error term

With a series expansion, keep its omitted-term scale alongside the prefix. For a positive variable tending to infinity:

```python
from asymptotic import multiseries

t = sp.symbols("t", positive=True)
expansion = multiseries(sp.exp(1/t), t, scale=[1 / t], terms=5, return_result=True)
truncation = expansion.as_element().truncation(3)
assert truncation.prefix == 1 + 1/t + 1/(2 * t**2)
assert truncation.remainder.check() is True
```

Here the omitted scale is `1/(6*t**3)`. A remainder certificate concerns the declared regime; a formal series alone does not establish a uniform error bound. Follow the [expansion guide](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/expansions.md) for the difference between a prefix, its remainder and a certified operation.

## Choose the right workflow

| Question | Entry point | What to inspect |
|---|---|---|
| Does a limit exist on the full approach domain? | `limit` | Status, value and domain |
| What happens on every complex approach? | `complex_limit` | Finite-point chart and spherical poles |
| Which finite values can oscillation accumulate at? | `cluster_set` | Exact set, attained sequences and pole avoidance |
| What happens on one real side or a fixed complex ray? | `one_sided_limit`, `complex_ray_limit` | Direction and branch conditions |
| What are the leading terms on competing small scales? | `series`, `multiseries`, `local_series` | Scale, truncation and remainder |
| How does an implicit solution or root behave? | `implicit`, `root`, `inverse` | Branch and nonzero-derivative conditions |
| How does a sum, product or recurrence grow? | `sum`, `product`, `rsolve` | Exact identities and certificates |
| Which perturbation method fits my equation? | `regular_perturbation`, `lindstedt_poincare` | Regime, residual order and solvability |
| What is a probability or integral's asymptotic behavior? | `probability`, `expectation`, `mellin` | Domain, saddle geometry and error |

The root namespace has 66 primary entry points, including result types. The [API guide](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/api.md) distinguishes between common and specialized/expert-level theorem/ geometry functions.

## Understand the answer

| Limit status | Meaning |
|---|---|
| `PROVED` | The value follows under the checked hypotheses. |
| `DOES_NOT_EXIST` | Admissible approaches attain incompatible limiting values or another nonexistence certificate applies. |
| `UNKNOWN` | Available methods cannot establish the result. |

Formal expansions and certified asymptotic expansions are distinct. Read the attached remainder and certification information before using an expansion as an error bound. Numerical checks support a symbolic argument but do not replace its domain and branch hypotheses.

## Capabilities and limitations

| Area | Representative support | Important boundary |
|---|---|---|
| Univariate asymptotics | powers, logs, exponentials, finite log-exp scales, generalized series | not a complete decision procedure for every nested or oscillatory germ |
| Simultaneous multivariate limits | exact composition, cylindrical reduction, radial order, weighted bounds, Newton/projective geometry, semialgebraic angular images, oscillatory clusters | difficult high-dimensional images or unresolved symbolic parameters can remain `UNKNOWN` |
| Expansions | multiseries, nested forms, Puiseux branches, transseries | branch-sensitive complex continuation is partial |
| Implicit problems | simple roots, Newton-Puiseux/scaling handoff, parameter strata | general resolution of higher-dimensional singularities is outside scope |
| Sums and recurrences | exact routes, Euler-Maclaurin, Mellin/Poisson routes, recurrence asymptotics | difficult resonance and deeper ramification remain partial |
| ODE/perturbation | structured `PerturbationProblem`, explainable method recommendation, regular/Lindstedt/multiple-scale/matched methods, symbolic residual validation, numerical convergence diagnostics | automatic method selection declines ambiguous oscillator cases; general nonlinear/global connection problems are not solved |
| Probability/Laplace | exact reductions, selected lattice methods, multivariate Laplace geometry | curved constraints and general degenerate saddles are partial |
| Certification | explicit status, evidence, replayable remainder certificates | a formal construction is not automatically a certified asymptotic statement |

For limits, strong coverage includes rational and algebraic real limits, uniform norm and logarithmic bounds, selected real discontinuities,selected parameter strata, finite local germs, fixed complex-ray branches, gamma and harmonic tails, proportional large-order Bessel J/Y tails, bounded recurrence reductions, and attained oscillatory subsequences. Complex directional infinity retains a direction and is distinct from spherical complex infinity. General complex sectors, arbitrary variable-order special functions, and coupled oscillations with accumulating poles need additional hypotheses or unsupported theorems. Some expressions exceed practical computation budgets. Unknown user functions have no assumed continuity; `analytic_limit` accepts an explicit, call-scoped analytic contract.

The [capability matrix](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/capabilities.md) gives supported inputs, proof boundaries and limitations by area. The [limit guide](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/limits.md) explains domains, parameters, branches and nonexistence witnesses for limits. The [limit contracts guide](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/limit-contracts.md) covers conditional outputs, whole-plane approaches, cluster sets and directional infinities.

## Learn by running examples

Start with [certified limits](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/examples/certified_limits.py), then try [complex branches](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/examples/branch_limits.py) and [special-function tails](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/examples/special_function_limits.py). Each example contains executable checks and explains its mathematical question.

For expansion, summation, probability and perturbation workflows, follow the [examples guide](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/examples/README.md). The [getting-started guide](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/getting-started.md) supplies the assumptions and terminology needed for these examples.

The `examples/` directory contains executable examples. The introductory sequence is:

1. `certified_limits.py` — existence, nonexistence, domains, and evidence.
2. `multivariate_limits.py` — radial, path-dependent, cylindrical, and correlated examples.
3. `ordinary_expansion.py` — ordinary expansion.
4. `asymptotic_summation.py` — discrete asymptotics.
5. `probability_asymptotics.py` — probability and Laplace asymptotics.
6. `perturbation_problem.py` — unified perturbation dispatch, validation, and evidence.

## Documentation

I suggest starting with these guides:

- [Introduction to asymptotics](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/introduction-to-asymptotics.md) — conceptual background, techniques, and applications.
- [Documentation index](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/index.md) — complete documentation map for users, specialists, reference, and contributors.
- [Getting started](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/getting-started.md) — installation, first computations, and result inspection.
- [Choosing an API](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/workflows.md) — problem-oriented guide to the appropriate public entry point.
- [Limits](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/limits.md) — limit semantics, domains, assumptions, and evidence.
- [Multivariate limits](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/multivariate-limits.md) — joint/simultanous limits, radial/angular geometry, cluster sets, and parameters.
- [Certification](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/certification.md) — what a proof status means and why `UNKNOWN` is useful.
- [Capabilities and limitations](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/capabilities.md) — supported routes and known capabilty boundaries.
- [User guide](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/user-guide.md) — broader workflows across expansions, sums, ODEs and probability.
- [Algorithm selection](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/algorithm-selection.md) — how high-level APIs choose exact, structural, saddle, implicit, ODE, recurrence, and optimization routes.
- [Primary API](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/api.md) — curated public entry points and contracts.
- [API reference](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/api-reference.md) — detailed signatures and public records.
- [API classification](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/api-classification.md) — primary, expert, and internal interfaces.
- [Function properties](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/function-properties.md) — reviewed branch-aware property, singularity, and domain reasoning.
- [Probability and expectation asymptotics](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/probability-asymptotics.md) — exact reduction, moving domains, degenerate/coalescing saddles, and global Laplace certificates.
- [Asymptotic sums](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/asymptotic-sums.md) — creative telescoping, Euler-Maclaurin, Mellin/Poisson methods, uniform termwise expansion, multidimensonal sums, and discrete saddles.
- [Discrete asymptotics](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/discrete-asymptotics.md) — factorial scales, discrete Newton polygons, and recurrence lifting.
- [Perturbation hierarchies](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/perturbation-hierarchies.md) — common order-by-order representation used by perturbation solvers.
- [Power simplification and branch semantics](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/power-simplification.md) — branch-sensitive transformations and their proof obligations.
- [Architecture](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/architecture.md) — solver organization for contributors.
- [Testing](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/testing.md) — public contracts, theorem tests, metamorphic tests, and performance gates.

## Development

Contributions – whether they are bug reports, suggestions, or code – are welcome!

Source check:
```bash
python -m pip install -e ".[test,lint,benchmark]"
ruff check src tests examples
ruff format --check src tests examples
pytest -m "not reference_corpus"
```

Correctness, proof boundaries and performance tested separately. See [testing guide](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/testing.md) and [documentation guide](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/documentation.md).

Maintainers can follow the [release guide](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/docs/releasing.md) for artifact checks and publishing gates.

## License

The package is distributed under the [GPL-3.0 license](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/LICENSE).
