Metadata-Version: 2.4
Name: aurea-bignum-library-python
Version: 0.1.0
Summary: A python module for handling big numbers with arbitrary precision.
Author: Aurea Caelum
Author-email: pichue202@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# bignum

A Python module for representing and computing with extremely large or extremely small numbers using a structured scientific-notation system instead of native numeric types.

Unlike standard floats or integers, **bignum** stores numbers as dictionaries containing sign, mantissa, exponent, exponent sign, magnitude layer, and imaginary flag. This allows it to represent values far beyond Python’s built-in numeric limits while still supporting arithmetic and mathematical functions.

---

## Features

- Arbitrary-scale number representation
- Supports exponent layers (`e`, `ee`, `eee`, …)
- Arithmetic operations
- Logarithms and exponentials
- Roots and powers
- Factorials
- Imaginary number support
- Configurable precision
- Safe mode for preventing expensive operations

---

## Number Format

Each number is stored internally as:

```
{
  'sign': '+' | '-',
  'mantissa': float,
  'exponent': int,
  'exponentsign': '+' | '-',
  'magnitude': int,
  'imaginary': bool
}
```

Example:

```
1e10 → +1.0e10
1ee10 → +1.0ee10
```

Magnitude represents repeated exponent layers.

---

## Installation

```bash
pip install bignum
```

---

## Quick Example

```python
from bignum import *

a = fromInteger(4000)
b = fromInteger(200)

print(toScientific(addBignum(a, b)))
```

Output:

```
+4.2e3
```

---

## Supported Operations

### Arithmetic

- `addBignum`
- `subBignum`
- `multBignum`
- `divBignum`

### Math Functions

- `lnBignum`
- `Log10`
- `Logx`
- `expBignum`
- `sqrtBignum`
- `cubrtBignum`
- `nthrtBignum`
- `factBignum`

### Utilities

- `compareBignum`
- `roundBignum`
- `floorBignum`
- `absBignum`
- `recipBignum`
- `isZero`

---

## Configuration

The module includes configurable globals:

| Variable | Description |
|--------|-------------|
`SF` | Significant figures (default 5) |
`SafeMode` | Prevents very expensive calculations |

---

## Limitations

- `toInteger()` only converts values between `1e-10` and `1e10`.
- Precision depends on floating-point mantissa accuracy.
- Some operations are restricted when `SafeMode` is enabled.

---

## Use Cases

bignum is useful for:

- Scientific experimentation
- Simulating extreme growth systems
- Studying large exponent structures
- Mathematical modeling beyond float limits

---

## License

See `LICENSE.txt` for details.
