flexfloat 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

flexfloat/types.py

@@ -1,5 +1,5 @@
-"""Type definitions for the flexfloat package."""
-
-from typing import TypeAlias
-
-Number: TypeAlias = int | float
+"""Type definitions for the flexfloat package."""
+
+from typing import TypeAlias
+
+Number: TypeAlias = int | float

flexfloat-0.1.3.dist-info/METADATA

@@ -0,0 +1,340 @@
+Metadata-Version: 2.4
+Name: flexfloat
+Version: 0.1.3
+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.3.dist-info/RECORD

@@ -0,0 +1,14 @@
+flexfloat/__init__.py,sha256=QynzrIicNr9asICyJbity5QdrFop7xEDlKkrS7rZfKk,725
+flexfloat/core.py,sha256=u5TVNxGxsb0_H4vc9p6PvjeBYRJrYBABhZxOTcS5sAg,39658
+flexfloat/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexfloat/types.py,sha256=_vRC7gQl5ua76QfKco4L3jQ4uPtEPUxPNGy4zWBFbns,113
+flexfloat/bitarray/__init__.py,sha256=nyHA70JnEuDVOYWfHjhNNu0zm4xVLWADkuMo0kqsJ7c,2512
+flexfloat/bitarray/bitarray.py,sha256=ASq8L1Ky84H41AzhLlZjY1u1k6zOtyf2czuD-ixGsJA,5912
+flexfloat/bitarray/bitarray_int64.py,sha256=kq-vULiA0lk8GaSDUf9U41q12qCREdn83ywKxiNjv_M,10585
+flexfloat/bitarray/bitarray_list.py,sha256=OTH6MjA1kBHPZP2Mi2mIViN2aOdxHVVrCybV-9ko99c,6586
+flexfloat/bitarray/bitarray_mixins.py,sha256=Cfm0dt1gRIG5kNb9wPPH62Tzd5B0Ck6YZupHia1jKmo,3302
+flexfloat-0.1.3.dist-info/licenses/LICENSE,sha256=uwwkK--SUYUV3lbrv9kXJ_vDiYfHVb-t732g6c4qg7Q,1077
+flexfloat-0.1.3.dist-info/METADATA,sha256=Iea-nvdjZCsfvrhfNQTEHnCozLgPLRotRG8RqskwjXs,10375
+flexfloat-0.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+flexfloat-0.1.3.dist-info/top_level.txt,sha256=82S8dY2UoNZh-9pwg7tUvbwB3uw2s3mfEoyUW6vCMdU,10
+flexfloat-0.1.3.dist-info/RECORD,,

flexfloat-0.1.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ferran Sanchez Llado
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flexfloat-0.1.1.dist-info/METADATA

@@ -1,82 +0,0 @@
-Metadata-Version: 2.4
-Name: flexfloat
-Version: 0.1.1
-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
-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"
-
-# FlexFloat
-
-A Python library for arbitrary precision floating point arithmetic with a flexible exponent and fixed-size fraction.
-
-## Features
-
-- **Growable Exponents**: Handle very large or very small numbers by dynamically adjusting the exponent size
-- **Fixed-Size Fractions**: Maintain precision consistency with IEEE 754-compatible 52-bit fractions  
-- **IEEE 754 Compatibility**: Follows IEEE 754 double-precision format as the baseline
-- **Special Value Support**: Handles NaN, positive/negative infinity, and zero values
-- **Arithmetic Operations**: Addition and subtraction with proper overflow/underflow handling
-
-## Installation
-
-```bash
-pip install flexfloat
-```
-
-## Development Installation
-
-```bash
-pip install -e ".[dev]"
-```
-
-## 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
-large_a = FlexFloat.from_float(1e308)
-large_b = FlexFloat.from_float(1e308)
-large_result = large_a + large_b
-# Result has grown exponent to handle overflow
-print(len(large_result.exponent))  # > 11 (grows beyond IEEE 754 standard)
-```
-
-## Running Tests
-
-```bash
-python -m pytest tests
-```
-
-
-## License
-
-MIT License

flexfloat-0.1.1.dist-info/RECORD

@@ -1,9 +0,0 @@
-flexfloat/__init__.py,sha256=SFtec_6Rr65_Sr83rhoh9VT7Egj8N-e2F0fyMQbBqKg,378
-flexfloat/bitarray.py,sha256=hlJtoe50Lx6KdNTyMNFkJCBON4t_gtCDc3hWfX_bza4,9196
-flexfloat/core.py,sha256=7bnw7aJvnFOD1RTtZvH9nc4QCKcSowqsSGhcncAMlJI,28771
-flexfloat/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-flexfloat/types.py,sha256=SFTYmG3BHLiCJc0LvNwOnByRLRcRXH2erINeqLyHLKs,118
-flexfloat-0.1.1.dist-info/METADATA,sha256=SMM9FyWRr08gI32_gssW0bkCLxPF-MTm9lim3J_-Wdk,2459
-flexfloat-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-flexfloat-0.1.1.dist-info/top_level.txt,sha256=82S8dY2UoNZh-9pwg7tUvbwB3uw2s3mfEoyUW6vCMdU,10
-flexfloat-0.1.1.dist-info/RECORD,,