bigdog 1.2609.1a0

Test field for pre-release package evaluation

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:

pip install bigdog

Dependencies

• Python: 3.8+ (Recommended)
• Libraries: numpy>=1.23.2, scipy>=1.9.2, astropy

Quick Start

1. Basic Declaration

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:

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:

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

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 ([e-mail])
• 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.