Metadata-Version: 2.4
Name: bigdog
Version: 1.2609.1a0
Summary: Test field for pre-release package evaluation
Project-URL: Homepage, https://kohdh.com/
Author-email: Donghyeok Koh <donghyeok.koh.code@gmail.com>
License: Other/Proprietary License
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.6
Requires-Dist: astropy
Requires-Dist: numpy>=1.23.2
Requires-Dist: scipy>=1.9.2
Description-Content-Type: text/markdown

# BigDog

## Introduction

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

Unlike traditional error propagation, BigDog employs a **sampling-based approach** (Monte Carlo distribution modeling). By representing uncertainties as large sequences of sample values, it inherently captures correlations during mathematical operations and supports non-normal distributions. It is fundamentally built upon `astropy.uncertainty` and `astropy.units`, extending them with intuitive interfaces and advanced convenience features.

## Key Features

* **ValueU**: A core class for handling values with symmetric or asymmetric uncertainties using sample distributions.
* **QuantityU**: An upper-compatible extension of `ValueU` that integrates `Astropy` unit control.
* **Advanced Sampling Engine**: Transitioned from theoretical models to approximate sampling (Aug 2025) for more realistic error modeling.
* **Intuitive Comparisons**: Supports multiple comparison modes: `central`, `conservative` (3σ), and `permissive` (1σ).
* **Domain Enforcement**: Methods like `.enforced_positive()` and `.enforced_negative()` for physical consistency.
* **Built-in Help System**: Access detailed, formatted documentation directly via `.help()` on any instance.

## 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`

## Quick Start

### 1. Basic Declaration

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

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

# Value with asymmetric uncertainty and units
q1 = QuantityU(center=72 * u.m, std=(-3, +12))

```

### 2. Mathematical Operations

Operations are performed element-wise across the sampled distribution:

```python
q2 = QuantityU(800 * u.cm, (-400, +500))
result = q1 + q2
print(result) # Automatically handles unit conversion and uncertainty propagation

```

### 3. Comparison Modes

Since distributions aren't simple scalars, you can define how to compare them:

```python
# Set to conservative mode (True if 99.73% 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")

```

## Documentation

For comprehensive details on object creation, mathematical operations, unit decomposition, and formatting, use the built-in help function:

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

```

## Technical Notes & Disclaimer

* **Memory Management**: High `n_samples` (default: 10,000) can lead to significant memory consumption.
* **Independence Assumption**: While the sampling captures existing correlations, initial instances are generated assuming independent variables (zero covariance).
* **Type Casting**: Use caution when casting to integers (`.astype(int)`) if the distribution contains `NaN` values, as this may lead to silent data distortion.

## Credits

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

## Changelog

### v1.2609.01-alpha (2026-02-24)

* **General Validation**: Completed general validation and synchronized `help()` explanations.
* **Engine Upgrade**: Full transition to property-based lightweight value objects and approximate sampling.
* **Domain Constraints**: Implemented auxiliary methods for sampled distribution computation and sign enforcement.
