Balansis

Balansis is a scientific and engineering Python library for workloads where plain floating-point arithmetic hides instability instead of making it explicit.

It is built around Absolute Compensation Theory (ACT): a numerical model that introduces structured runtime objects such as AbsoluteValue, ABSOLUTE, and EternalRatio, and exposes compensation directly in the API instead of silently discarding it.

Documentation | Quick Start | API Reference | Formal Verification | Examples | Benchmarks

---

What Problem Does Balansis Solve?

IEEE 754 floating-point arithmetic is fast and ubiquitous, but several failure patterns still matter in real systems:

• large reductions lose small but meaningful residuals
• catastrophic cancellation turns uncertain differences into misleading zeros
• divide-by-zero handling is deferred to edge-case logic instead of the data model
• financial and simulation pipelines often hide correction logic outside the core arithmetic API

Balansis is for cases where you want those edge conditions to be visible, structured, and auditable.

Why Was It Created?

Balansis was created to explore a stronger arithmetic interface for:

• scientific computations with unstable reductions
• long-running simulations with drift-sensitive accumulation
• financial workflows that benefit from structural cancellation semantics
• research pipelines that want a bridge from runtime code to formal proofs

---

Real-World Value First

1. Large-Scale Aggregation

sum([1e16, 1.0, -1e16])  # IEEE 754 / Python float
# 0.0

from balansis import AbsoluteValue as Bv, Operations

values = [
    Bv.from_float(1e16),
    Bv.from_float(1.0),
    Bv.from_float(-1e16),
]
result, compensation = Operations.sequence_sum(values)
# result == AbsoluteValue.from_float(1.0)
# compensation > 0.0

Why it matters: the small residual survives, and the API exposes that a meaningful correction was applied.

2. Catastrophic Cancellation

(1e16 + 1.0) - 1e16  # IEEE 754 / Python float
# 0.0

from balansis import AbsoluteValue as Bv, Operations

a = Bv.from_float(1e16)
b = Bv.from_float(-1e16)
result, compensation = Operations.compensated_add(a, b)

Why it matters: when precision loss is suspected at very large magnitudes, Balansis preserves an informative residual instead of always collapsing to a spurious exact zero.

3. Financial Cancellation

from decimal import Decimal
from balansis.finance.ledger import Ledger

ledger = Ledger()
ledger.post_entry("cash", Decimal("250.00"))
ledger.post_entry("cash", Decimal("-250.00"))

balance = ledger.balance()
# balance == ABSOLUTE

Why it matters: offsetting entries cancel structurally to the ACT identity, which is easier to reason about than burying bookkeeping semantics in plain float totals.

4. Division Edge Handling

1.0 / 0.0  # standard runtime edge case
# ZeroDivisionError

from balansis import AbsoluteValue, Operations

num = AbsoluteValue.from_float(6.0)
den = AbsoluteValue.from_float(2.0)
ratio, compensation = Operations.compensated_divide(num, den)

Why it matters: Balansis makes ratio structure explicit through EternalRatio for valid denominators and rejects an ABSOLUTE denominator directly instead of pretending that infinity-like behavior is a normal value.

---

Why Adopt Balansis?

• Explicit compensation: low-level operations return both a result and a compensation factor
• Structured edge handling: ratio and additive-identity behavior are part of the model, not scattered ad hoc checks
• Research continuity: the repository includes a Lean4 formal layer for the public ACT theorem surface
• Practical scope: core arithmetic, algebraic structures, linear algebra, finance helpers, and experimental subprojects

---

Install In 60 Seconds

pip install balansis

CLI / pipx install:

pipx install balansis
balansis --version
balansis doctor

Optional extras:

pip install balansis[plot]
pip install balansis[notebook]
pip install balansis[torch]
pip install balansis[all]

Supported Python versions: 3.10, 3.11, 3.12.

More install options: Installation Guide

---

Quick Start

from balansis import AbsoluteValue, Operations, ABSOLUTE

a = AbsoluteValue(magnitude=5.0, direction=1)
b = AbsoluteValue(magnitude=3.0, direction=-1)

result, compensation = Operations.compensated_add(a, b)

print(result)
print(compensation)
print(ABSOLUTE)

Continue with:

• Quick Start
• Glossary
• Examples

---

Documentation By Audience

Audience	Start here	Why
Decision makers	Why Balansis	Understand the problem, the value proposition, and where Balansis fits
Developers	Quick Start	Install the package and start using the runtime surface
Researchers	Mathematics	Explore ACT concepts, notation, and theorem-oriented material
Verification-oriented readers	Formal Verification	Review the Lean architecture and current proof status
Contributors	Contributing	Set up the repo, quality gates, and documentation workflow

Documentation Map

• Documentation Home
• Getting Started
• Core Concepts
• Architecture
• API Reference
• Mathematics
• Formal Verification
• Examples
• Benchmarks
• TNSIM Overview
• Research Materials

---

Formal Verification Status

Version 1.1.0 ships a compiled Lean4 formalization on Mathlib v4.28.0.

• BalansisFormal is the constructive core
• ACT is the public theorem facade
• formal/ contains 0 axiom, 0 sorry, 0 admit
• public theorem groups A1-A5, E1-E4, and S1-S3 are compiled as Lean theorems

Verification entrypoints:

• Formal Overview
• Lean README

---

Package Surface

Core areas currently present in the repository:

• balansis.core
• balansis.algebra
• balansis.linalg
• balansis.finance
• balansis.numpy_integration
• balansis.ml
• balansis.sets

Reader-oriented API navigation starts here: API Reference

---

TNSIM

tnsim/ is a repository subproject for zero-sum infinite sets experimentation. It is maintained in the same repository, but it is not the main balansis package entrypoint.

• TNSIM Overview
• TNSIM README

---

Contributing

Contributions are welcome, but Balansis is maintained under a dual-license model. Before opening a substantial pull request, read:

• CONTRIBUTING.md
• CLA.md
• LICENSING.md
• NOTICE
• SECURITY.md
• Documentation Standards

---

License

Balansis is dual-licensed:

• LICENSE: AGPL-3.0
• COMMERCIAL_LICENSE.md: commercial proprietary terms
• LICENSING.md: routing and selection guide

Commercial execution material:

• ORDER_FORM_TEMPLATE.md
• SECURITY.md

Copyright (c) 2024-2026 Andrey Tikhonov (XTeam-Pro). All rights reserved.

---

Balansis is part of the StudyNinja-Eco ecosystem.