# BigDog

## Introduction & Design Philosophy

**BigDog** is a robust Python package designed for high-precision scientific computing involving numerical values with **asymmetric uncertainties** and **physical units**. 

In traditional analytical error propagation (using partial derivatives), mathematical frameworks often collapse when dealing with highly non-linear equations or asymmetric errors. BigDog circumvents this limitation entirely by employing a **sampling-based approach (Monte Carlo distribution modeling)**. 

Instead of treating a value as a single scalar, BigDog represents every value as a vast probability distribution array (defaulting to $N=10,000$ samples). 
* **Perfect Propagation:** Element-wise array operations ensure that uncertainties propagate flawlessly through any complex mathematical function.
* **Inherent Covariance:** If the same variable is used multiple times in an equation, its identical index alignment ensures that statistical correlation (covariance) is automatically and accurately preserved.
* **Astropy Integration:** Fundamentally built upon `astropy.uncertainty` and `astropy.units`, it seamlessly upgrades unit management into a probabilistic framework.

Whether you are crawling and processing massive amounts of ArXiv papers in an automated pipeline or calculating the luminosity of stellar objects, BigDog guarantees mathematical integrity.

## Key Features

* **`ValueU`**: A core class for handling pure numerical values with symmetric or asymmetric uncertainties using sample distributions.
* **`QuantityU`**: An upper-compatible extension of `ValueU` that tightly integrates `astropy.units` for dimensionally safe probabilistic computing.
* **Geometric Asymmetric Splicing**: Accurately models asymmetric errors by splicing two distinct half-normal distributions based on the provided lower and upper standard deviations.
* **Physical Domain Enforcement**: Features like `.enforced_positive()` elegantly handle the "negative tail" problem in statistics by replacing physically impossible values (e.g., negative Kelvin temperatures) with `NaN` without distorting the underlying Probability Density Function (PDF).
* **Advanced Stratified Resampling**: Ultra-fast, memory-optimized resampling capabilities with exact proportion preservation and NaN-fixing algorithms.
* **Probabilistic Comparison**: Evaluate inequalities based on statistical significance (`central`, 1σ `permissive`, or 3σ `conservative` modes).

---

## Installation

BigDog is currently in the alpha stage. You can install it via `pip`:

```sh
pip install bigdog
```

### Dependencies
* **Python**: 3.8+ (Recommended)
* **Libraries**: `numpy>=1.23.2`, `scipy>=1.9.2`, `astropy>=6.1.3`

---

## Quick Start (User Journey)

### 1. Basic Declaration
Instantiate objects by providing the central value and standard deviation. The engine automatically generates the underlying sample sequence.

```pycon
from bigdog import ValueU, QuantityU
import astropy.units as u

# 1. Value with symmetric uncertainty
v1 = ValueU(center=15, std=3)

# 2. Value with asymmetric uncertainty (-3, +12)
v2 = ValueU(center=50, std=(-3, +12))

# 3. Quantity with physical units
q1 = QuantityU(center=72 * u.m, std=5)
```

### 2. Mathematical Operations & Unit Promotion
Interact with `ValueU` and `QuantityU` just like standard Python floats. Multiplying a `ValueU` by an Astropy unit automatically promotes it to a `QuantityU`.

```pycon
q2 = QuantityU(800 * u.cm, (-40, +50))

# Automatically handles unit conversion (m + cm) and element-wise uncertainty propagation
result = q1 + q2
print(result) 

# ValueU seamlessly upgrades to QuantityU when interacting with units
q_mass = v1 * u.kg
```

### 3. Physical Domain Enforcement
When calculating physical properties that cannot be negative (e.g., mass, absolute temperature), statistical tails might introduce invalid negative values. Use domain enforcement before applying non-linear operations like square roots or logarithms.

```pycon
# Replaces negative samples with NaN, preserving the valid distribution shape
q_safe = result.enforced_positive

# Prevents 'RuntimeWarning: invalid value encountered in power'
q_sqrt = q_safe ** 0.5
``` 

### 4. Probabilistic Comparisons
Because distributions aren't single points, inequalities require a significance threshold.

```pycon
# Set to conservative mode: Evaluates to True ONLY if 99.73% (3-sigma) of samples satisfy the condition
if q1.set_comparison_mode(conservative=True) > q2.set_comparison_mode(conservative=True):
    print("q1 is strictly greater than q2 with 3-sigma confidence.")
```

### 5. Advanced Resampling
Resize distributions while perfectly preserving the ratio of positive/negative deviations and managing `NaN` values. Highly optimized for memory-constrained environments.

```pycon
# Downscale or upscale the sample size
v_resampled = v1.resample(n_samples=1000)

# Resample while completely excluding NaN values from the distribution
v_clean = v1.resample(n_samples=10000, exclude_nan=True)
```

---

## Technical Notes & Warnings ⚠️

* **Memory Management**: BigDog uses high-resolution sampling (default: N=10,000). Processing massive arrays (e.g., large FITS images) element-by-element with `QuantityU` may lead to significant RAM consumption. Profile your memory usage for large-scale operations.
* **The Integer Casting Trap**: **NEVER** cast a distribution to integers (e.g., `.astype(int)`) if it contains `NaN` values (often introduced by `.enforced_positive()`). Since integer types cannot represent IEEE 754 `NaN`, NumPy will silently overflow it to an extreme negative number (e.g., `-9223372036854775808`), severely distorting your data.
* **Independence Assumption**: While the sampling engine captures existing correlations during operations, initial instances are generated assuming strict independence (zero initial covariance).

## Documentation

For comprehensive details on object creation, unit decomposition, and formatting, use the highly detailed built-in interactive help function:

```pycon
ValueU().help()     # Detailed guide for ValueU
QuantityU().help()  # Detailed guide for QuantityU
```

---

## Credits
* **Main Developer**: DH.Koh (donghyeok.koh.code@gmail.com)
* **Collaborating Developers**: JH.Kim, KM.Heo

## Changelog
### v1.2612.01 (2026-03-20)
* **Engine Upgrade**: Full transition to property-based lightweight value objects and approximate sampling for enhanced performance.
* **Domain Constraints**: Implemented auxiliary methods for sampled distribution computation and robust sign enforcement (`enforced_positive`, `enforced_negative`).
* **General Validation**: Completed general validation and synchronized `help()` explanations.
* **Memory Optimization**: Overhauled `.resample()` method with C-level in-place array operations and precise stratification.
