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:

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.

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.

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.

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

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

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

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.