flexfloat 0.1.2__py3-none-any.whl → 0.1.5__py3-none-any.whl

flexfloat/types.py

@@ -1,4 +1,10 @@
-"""Type definitions for the flexfloat package."""
+"""Type definitions for the flexfloat package.
+
+This module provides type aliases used throughout the flexfloat package.
+
+Type Aliases:
+    Number: Alias for int | float, used for numeric arguments.
+"""
 
 from typing import TypeAlias
 

flexfloat-0.1.5.dist-info/METADATA

@@ -0,0 +1,340 @@
+Metadata-Version: 2.4
+Name: flexfloat
+Version: 0.1.5
+Summary: A library for arbitrary precision floating point arithmetic
+Author: Ferran Sanchez Llado
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: isort>=5.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: pylint>=3.0; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Requires-Dist: bump2version>=1.0; extra == "dev"
+Requires-Dist: build>=0.10; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Requires-Dist: check-manifest>=0.49; extra == "dev"
+Requires-Dist: PyYAML>=6.0; extra == "dev"
+Dynamic: license-file
+
+# FlexFloat
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI version](https://badge.fury.io/py/flexfloat.svg)](https://badge.fury.io/py/flexfloat)
+
+A high-precision Python library for arbitrary precision floating-point arithmetic with **growable exponents** and **fixed-size fractions**. FlexFloat extends IEEE 754 double-precision format to handle numbers beyond the standard range while maintaining computational efficiency and precision consistency.
+
+## ✨ Key Features
+
+- **🔢 Growable Exponents**: Dynamically expand exponent size to handle extremely large (>10^308) or small (<10^-308) numbers
+- **🎯 Fixed-Size Fractions**: Maintain IEEE 754-compatible 52-bit fraction precision for consistent accuracy
+- **⚡ Full Arithmetic Support**: Addition, subtraction, multiplication, division, and power operations
+- **🔧 Multiple BitArray Backends**: Choose between list-based and int64-based implementations for optimal performance
+- **🌟 Special Value Handling**: Complete support for NaN, ±infinity, and zero values
+- **🛡️ Overflow Protection**: Automatic exponent growth prevents overflow/underflow errors
+- **📊 IEEE 754 Baseline**: Fully compatible with standard double-precision format as the starting point
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install flexfloat
+```
+
+### Basic Usage
+
+```python
+from flexfloat import FlexFloat
+
+# Create FlexFloat instances
+a = FlexFloat.from_float(1.5)
+b = FlexFloat.from_float(2.5)
+
+# Perform arithmetic operations
+result = a + b
+print(result.to_float())  # 4.0
+
+# Handle very large numbers that would overflow standard floats
+large_a = FlexFloat.from_float(1e308)
+large_b = FlexFloat.from_float(1e308)
+large_result = large_a + large_b
+
+# Result automatically grows exponent to handle the overflow
+print(f"Exponent bits: {len(large_result.exponent)}")  # > 11 (grown beyond IEEE 754)
+print(f"Can represent: {large_result}")  # No overflow!
+```
+
+### Advanced Examples
+
+```python
+from flexfloat import FlexFloat
+
+# Mathematical operations
+x = FlexFloat.from_float(2.0)
+y = FlexFloat.from_float(3.0)
+
+# Power operations
+power_result = x ** y  # 2^3 = 8
+print(power_result.to_float())  # 8.0
+
+# Exponential using Euler's number
+e_result = FlexFloat.e ** x  # e^2
+print(f"e^2 ≈ {e_result.to_float()}")
+
+# Working with extreme values
+tiny = FlexFloat.from_float(1e-300)
+huge = FlexFloat.from_float(1e300)
+extreme_product = tiny * huge
+print(f"Product: {extreme_product.to_float()}")  # Still computable!
+
+# Precision demonstration
+precise_calc = FlexFloat.from_float(1.0) / FlexFloat.from_float(3.0)
+print(f"1/3 with 52-bit precision: {precise_calc}")
+```
+
+## 🔧 BitArray Backends
+
+FlexFloat supports multiple BitArray implementations for different performance characteristics:
+
+```python
+from flexfloat import (
+    FlexFloat, 
+    set_default_implementation, 
+    get_available_implementations
+)
+
+# View available implementations
+print(get_available_implementations())  # ['list', 'int64']
+
+# Use list-based implementation (default, more flexible)
+set_default_implementation('list')
+flex_list = FlexFloat.from_float(42.0)
+
+# Use int64-based implementation (faster for small bit arrays)
+set_default_implementation('int64')
+flex_int64 = FlexFloat.from_float(42.0)
+
+# Both produce the same results with different performance characteristics
+```
+
+### Implementation Comparison
+
+| Implementation | Best For | Pros | Cons |
+|---------------|----------|------|------|
+| `list[bool]` | Smaller exponents and testing | Flexible, easy to understand | Slower for large numbers |
+| `list[int64]` | Standard operations | Fast for bigger numbers, efficient memory | Overhead for small numbers |
+
+## 📚 API Reference
+
+### Core Operations
+
+```python
+# Construction
+FlexFloat.from_float(value: float) -> FlexFloat
+FlexFloat(sign: bool, exponent: BitArray, fraction: BitArray)
+
+# Conversion
+flexfloat.to_float() -> float
+
+# Arithmetic
+a + b, a - b, a * b, a / b, a ** b
+abs(a), -a
+
+# Mathematical functions
+FlexFloat.e ** x  # Exponential function
+```
+
+### Special Values
+
+```python
+from flexfloat import FlexFloat
+
+# Create special values
+nan_val = FlexFloat.nan()
+inf_val = FlexFloat.infinity()
+neg_inf = FlexFloat.negative_infinity()
+zero_val = FlexFloat.zero()
+
+# Check for special values
+if result.is_nan():
+    print("Result is Not a Number")
+if result.is_infinite():
+    print("Result is infinite")
+```
+
+## 🧪 Development & Testing
+
+### Development Installation
+
+```bash
+git clone https://github.com/ferranSanchezLlado/flexfloat-py.git
+cd flexfloat-py
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+python -m pytest tests/
+
+# Run with coverage
+python -m pytest tests/ --cov=flexfloat --cov-report=html
+
+# Run specific test categories
+python -m pytest tests/test_arithmetic.py  # Arithmetic operations
+python -m pytest tests/test_conversions.py  # Number conversions
+python -m pytest tests/test_bitarray.py  # BitArray implementations
+```
+
+### Code Quality
+
+```bash
+# Format code
+black flexfloat/ tests/
+
+# Sort imports
+isort flexfloat/ tests/
+
+# Type checking
+mypy flexfloat/
+
+# Linting
+pylint flexfloat/
+flake8 flexfloat/
+```
+
+## 🎯 Use Cases
+
+### Scientific Computing
+```python
+# Handle calculations that would overflow standard floats
+from flexfloat import FlexFloat
+
+# Factorial of large numbers
+def flex_factorial(n):
+    result = FlexFloat.from_float(1.0)
+    for i in range(1, n + 1):
+        result = result * FlexFloat.from_float(i)
+    return result
+
+large_factorial = flex_factorial(1000)  # No overflow!
+```
+
+### Financial Calculations
+```python
+# High-precision compound interest calculations
+principal = FlexFloat.from_float(1000000.0)
+rate = FlexFloat.from_float(1.05)  # 5% annual return
+years = FlexFloat.from_float(100)
+
+# Calculate compound interest over very long periods
+final_amount = principal * (rate ** years)
+```
+
+### Physics Simulations
+```python
+# Handle extreme values in physics calculations
+c = FlexFloat.from_float(299792458)  # Speed of light
+mass = FlexFloat.from_float(1e-30)   # Atomic mass
+
+# E = mc² with extreme precision
+energy = mass * c * c
+```
+
+## 🏗️ Architecture
+
+FlexFloat is built with a modular architecture:
+
+```
+flexfloat/
+├── core.py              # Main FlexFloat class
+├── types.py             # Type definitions
+├── bitarray/            # BitArray implementations
+│   ├── bitarray.py          # Abstract base class
+│   ├── bitarray_list.py     # List-based implementation
+│   ├── bitarray_int64.py    # Int64-based implementation
+│   └── bitarray_mixins.py   # Common functionality
+└── __init__.py          # Public API exports
+```
+
+### Design Principles
+
+1. **IEEE 754 Compatibility**: Start with standard double-precision format
+2. **Graceful Scaling**: Automatically expand exponent when needed
+3. **Precision Preservation**: Keep fraction size fixed for consistent accuracy
+4. **Performance Options**: Multiple backends for different use cases
+5. **Pythonic Interface**: Natural syntax for mathematical operations
+
+## 📊 Performance Considerations
+
+### When to Use FlexFloat
+
+✅ **Good for:**
+- Calculations requiring numbers > 10^308 or < 10^-308
+- Scientific computing with extreme values
+- Financial calculations requiring high precision
+- Preventing overflow/underflow in long calculations
+
+❌ **Consider alternatives for:**
+- Simple arithmetic with standard-range numbers
+- Performance-critical tight loops
+- Applications where standard `float` precision is sufficient
+
+### Optimization Tips
+
+```python
+# Prefer int64 implementation for standard operations
+set_default_implementation('int64')
+
+# Batch operations when possible
+values = [FlexFloat.from_float(x) for x in range(1000)]
+sum_result = sum(values, FlexFloat.zero())
+
+# Use appropriate precision for your use case
+if value_in_standard_range:
+    result = float(flexfloat_result.to_float())  # Convert back if needed
+```
+
+## 📋 Roadmap
+
+- [ ] Additional mathematical functions (sin, cos, tan, log, sqrt)
+- [ ] Serialization support (JSON, pickle)
+- [ ] Performance optimizations for large arrays
+- [ ] Complex number support
+- [ ] Decimal mode for exact decimal representation
+
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- IEEE 754 standard for floating-point arithmetic foundation
+- Python community for inspiration and best practices
+- Contributors and users who help improve the library
+
+## 📞 Support
+
+- 📚 **Documentation**: Full API documentation available in docstrings
+- 🐛 **Issues**: Report bugs on [GitHub Issues](https://github.com/ferranSanchezLlado/flexfloat-py/issues)
+- 💬 **Discussions**: Join conversations on [GitHub Discussions](https://github.com/ferranSanchezLlado/flexfloat-py/discussions)
+- 📧 **Contact**: Reach out to the maintainer for questions

flexfloat-0.1.5.dist-info/RECORD

@@ -0,0 +1,15 @@
+flexfloat/__init__.py,sha256=u-B9oE-zA_3wuKYhRMLiXldCKN7Xeclf5gK0vAT2OBI,933
+flexfloat/core.py,sha256=EQiBMmUtDreWFLjVeuaEiEj-PyNNcOV9BmRtOCs4neU,42821
+flexfloat/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexfloat/types.py,sha256=Enm4-oyGnvxGI-7MOK6eEIH2IzWafk0wQBsPaTqFYrE,266
+flexfloat/bitarray/__init__.py,sha256=aFnw7HSlFwWnFwmLhmjvRwt6qOakbUochHwT8di0v14,979
+flexfloat/bitarray/bitarray.py,sha256=L8CYFSxyMgfV-CpvtrKJ_kO3nexsHK2E2pNN9BfnNyI,8428
+flexfloat/bitarray/bitarray_bigint.py,sha256=yLfAreZ9hhP2f2dIS7ptYSuAFlUTXJiv-LtHhRWN5dc,9986
+flexfloat/bitarray/bitarray_bool.py,sha256=naTUcTycvP9BfU1_CJRgajgvsJoQz9jvi5aI224pphE,6429
+flexfloat/bitarray/bitarray_int64.py,sha256=FLfbg2gk_Ia-9_4UjoiWYZNK3CbD4teAYU5SGSV3WF0,10856
+flexfloat/bitarray/bitarray_mixins.py,sha256=HJkyseP_yat0tE3_XElFEqBgKk8oWEiHEKjzqIRwUnw,5026
+flexfloat-0.1.5.dist-info/licenses/LICENSE,sha256=uwwkK--SUYUV3lbrv9kXJ_vDiYfHVb-t732g6c4qg7Q,1077
+flexfloat-0.1.5.dist-info/METADATA,sha256=wAYgXkZWRv9YERXb5-XygV8y506I8GW2Dg-C1uiaIu4,10375
+flexfloat-0.1.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+flexfloat-0.1.5.dist-info/top_level.txt,sha256=82S8dY2UoNZh-9pwg7tUvbwB3uw2s3mfEoyUW6vCMdU,10
+flexfloat-0.1.5.dist-info/RECORD,,

flexfloat/bitarray.py

@@ -1,257 +0,0 @@
-"""BitArray implementation for the flexfloat package."""
-
-from __future__ import annotations
-
-import struct
-from typing import Iterator, overload
-
-
-class BitArray:
-    """A bit array class that encapsulates a list of booleans with utility methods.
-
-    This class provides all the functionality previously available through utility
-    functions, now encapsulated as methods for better object-oriented design.
-    """
-
-    def __init__(self, bits: list[bool] | None = None):
-        """Initialize a BitArray.
-
-        Args:
-            bits: Initial list of boolean values. Defaults to empty list.
-        """
-        self._bits = bits if bits is not None else []
-
-    @classmethod
-    def from_float(cls, value: float) -> BitArray:
-        """Convert a floating-point number to a bit array.
-
-        Args:
-            value (float): The floating-point number to convert.
-        Returns:
-            BitArray: A BitArray representing the bits of the floating-point number.
-        """
-        # Pack as double precision (64 bits)
-        packed = struct.pack("!d", value)
-        # Convert to boolean list
-        bits = [bool((byte >> bit) & 1) for byte in packed for bit in range(7, -1, -1)]
-        return cls(bits)
-
-    @classmethod
-    def from_signed_int(cls, value: int, length: int) -> BitArray:
-        """Convert a signed integer to a bit array using off-set binary representation.
-
-        Args:
-            value (int): The signed integer to convert.
-            length (int): The length of the resulting bit array.
-        Returns:
-            BitArray: A BitArray representing the bits of the signed integer.
-        Raises:
-            AssertionError: If the value is out of range for the specified length.
-        """
-        half = 1 << (length - 1)
-        max_value = half - 1
-        min_value = -half
-
-        assert (
-            min_value <= value <= max_value
-        ), "Value out of range for specified length."
-
-        # Convert to unsigned integer representation
-        unsigned_value = value - half
-
-        bits = [(unsigned_value >> i) & 1 == 1 for i in range(length - 1, -1, -1)]
-        return cls(bits)
-
-    @classmethod
-    def zeros(cls, length: int) -> BitArray:
-        """Create a BitArray filled with zeros.
-
-        Args:
-            length: The length of the bit array.
-        Returns:
-            BitArray: A BitArray filled with False values.
-        """
-        return cls([False] * length)
-
-    @classmethod
-    def ones(cls, length: int) -> BitArray:
-        """Create a BitArray filled with ones.
-
-        Args:
-            length: The length of the bit array.
-        Returns:
-            BitArray: A BitArray filled with True values.
-        """
-        return cls([True] * length)
-
-    @staticmethod
-    def parse_bitarray(bitstring: str) -> BitArray:
-        """Parse a string of bits (with optional spaces) into a BitArray instance."""
-        bits = [c == "1" for c in bitstring if c in "01"]
-        return BitArray(bits)
-
-    def to_float(self) -> float:
-        """Convert a 64-bit array to a floating-point number.
-
-        Returns:
-            float: The floating-point number represented by the bit array.
-        Raises:
-            AssertionError: If the bit array is not 64 bits long.
-        """
-        assert len(self._bits) == 64, "Bit array must be 64 bits long."
-
-        byte_values = bytearray()
-        for i in range(0, 64, 8):
-            byte = 0
-            for j in range(8):
-                if self._bits[i + j]:
-                    byte |= 1 << (7 - j)
-            byte_values.append(byte)
-        # Unpack as double precision (64 bits)
-        return struct.unpack("!d", bytes(byte_values))[0]  # type: ignore
-
-    def to_int(self) -> int:
-        """Convert the bit array to an unsigned integer.
-
-        Returns:
-            int: The integer represented by the bit array.
-        """
-        return sum((1 << i) for i, bit in enumerate(reversed(self._bits)) if bit)
-
-    def to_signed_int(self) -> int:
-        """Convert a bit array into a signed integer using off-set binary
-        representation.
-
-        Returns:
-            int: The signed integer represented by the bit array.
-        Raises:
-            AssertionError: If the bit array is empty.
-        """
-        assert len(self._bits) > 0, "Bit array must not be empty."
-
-        int_value = self.to_int()
-        # Half of the maximum value
-        bias = 1 << (len(self._bits) - 1)
-        # If the sign bit is set, subtract the bias
-        return int_value - bias
-
-    def shift(self, shift_amount: int, fill: bool = False) -> BitArray:
-        """Shift the bit array left or right by a specified number of bits.
-
-        This function shifts the bits in the array, filling in new bits with the
-        specified fill value.
-        If the value is positive, it shifts left; if negative, it shifts right.
-        Fills the new bits with the specified fill value (default is False).
-
-        Args:
-            shift_amount (int): The number of bits to shift. Positive for left shift,
-                negative for right shift.
-            fill (bool): The value to fill in the new bits created by the shift.
-                Defaults to False.
-        Returns:
-            BitArray: A new BitArray with the bits shifted and filled.
-        """
-        if shift_amount == 0:
-            return self.copy()
-        if abs(shift_amount) > len(self._bits):
-            new_bits = [fill] * len(self._bits)
-        elif shift_amount > 0:
-            new_bits = [fill] * shift_amount + self._bits[:-shift_amount]
-        else:
-            new_bits = self._bits[-shift_amount:] + [fill] * (-shift_amount)
-        return BitArray(new_bits)
-
-    def copy(self) -> BitArray:
-        """Create a copy of the bit array.
-
-        Returns:
-            BitArray: A new BitArray with the same bits.
-        """
-        return BitArray(self._bits.copy())
-
-    def __len__(self) -> int:
-        """Return the length of the bit array."""
-        return len(self._bits)
-
-    @overload
-    def __getitem__(self, index: int) -> bool: ...
-    @overload
-    def __getitem__(self, index: slice) -> BitArray: ...
-
-    def __getitem__(self, index: int | slice) -> bool | BitArray:
-        """Get an item or slice from the bit array."""
-        if isinstance(index, slice):
-            return BitArray(self._bits[index])
-        return self._bits[index]
-
-    @overload
-    def __setitem__(self, index: int, value: bool) -> None: ...
-    @overload
-    def __setitem__(self, index: slice, value: BitArray | list[bool]) -> None: ...
-
-    def __setitem__(
-        self, index: int | slice, value: bool | list[bool] | BitArray
-    ) -> None:
-        """Set an item or slice in the bit array."""
-        if isinstance(index, slice):
-            if isinstance(value, BitArray):
-                self._bits[index] = value._bits
-            elif isinstance(value, list):
-                self._bits[index] = value
-            else:
-                raise TypeError("Cannot assign a single bool to a slice")
-            return
-        if isinstance(value, bool):
-            self._bits[index] = value
-        else:
-            raise TypeError("Cannot assign a list or BitArray to a single index")
-
-    def __iter__(self) -> Iterator[bool]:
-        """Iterate over the bits in the array."""
-        return iter(self._bits)
-
-    def __add__(self, other: BitArray | list[bool]) -> BitArray:
-        """Concatenate two bit arrays."""
-        if isinstance(other, BitArray):
-            return BitArray(self._bits + other._bits)
-        return BitArray(self._bits + other)
-
-    def __radd__(self, other: list[bool]) -> BitArray:
-        """Reverse concatenation with a list."""
-        return BitArray(other + self._bits)
-
-    def __eq__(self, other: object) -> bool:
-        """Check equality with another BitArray or list."""
-        if isinstance(other, BitArray):
-            return self._bits == other._bits
-        if isinstance(other, list):
-            return self._bits == other
-        return False
-
-    def __bool__(self) -> bool:
-        """Return True if any bit is set."""
-        return any(self._bits)
-
-    def __repr__(self) -> str:
-        """Return a string representation of the BitArray."""
-        return f"BitArray({self._bits})"
-
-    def __str__(self) -> str:
-        """Return a string representation of the bits."""
-        return "".join("1" if bit else "0" for bit in self._bits)
-
-    def any(self) -> bool:
-        """Return True if any bit is set to True."""
-        return any(self._bits)
-
-    def all(self) -> bool:
-        """Return True if all bits are set to True."""
-        return all(self._bits)
-
-    def count(self, value: bool = True) -> int:
-        """Count the number of bits set to the specified value."""
-        return self._bits.count(value)
-
-    def reverse(self) -> BitArray:
-        """Return a new BitArray with the bits in reverse order."""
-        return BitArray(self._bits[::-1])