cairovolt-charge-calc 1.0.0__tar.gz

cairovolt_charge_calc-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CairoVolt
+
+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.

cairovolt_charge_calc-1.0.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: cairovolt-charge-calc
+Version: 1.0.0
+Summary: A utility to calculate battery charging speeds, efficiency, and verify USB-PD charging profiles compatibility.
+Author-email: CairoVolt Developer <dev@cairovolt.com>
+License: MIT
+Project-URL: Homepage, https://cairovolt.com/en/
+Project-URL: Documentation, https://github.com/cairovolt/cairovolt-charge-calc
+Project-URL: Store, https://cairovolt.com/en/anker/power-banks
+Project-URL: Repository, https://github.com/cairovolt/cairovolt-charge-calc
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# CairoVolt Charge Calc
+
+A lightweight Python library to calculate battery charging dynamics, watt-hours (Wh), effective power bank output capacities at different discharge voltages, and to diagnose USB-PD (Power Delivery) profile compatibility.
+
+This package was developed for [CairoVolt](https://cairovolt.com/en/) to validate and calculate specifications for power accessories. For general theoretical background, you can read the [Battery Charger Wikipedia entry](https://en.wikipedia.org/wiki/Battery_charger).
+
+## Features
+
+- **Watt-Hour Calculation**: Easily convert battery capacity (mAh) and voltage to Wh.
+- **Charge Time Estimation**: Estimate charge times using a two-phase model (Constant Current up to 80%, Constant Voltage down to 100%).
+- **Effective Capacity Calculation**: Calculate actual deliverable capacity (mAh) when a power bank discharges at 5V, 9V, or 12V instead of its nominal cell voltage (3.7V).
+- **USB-PD Profiling**: Diagnose if your charger wattage matches your device requirements.
+
+## Installation
+
+```bash
+pip install cairovolt-charge-calc
+```
+
+## Usage
+
+### 1. Estimating Charging Time
+This helper estimates the real-world charging duration based on your battery capacity and charger output. For example, if you want to calculate how fast an [anker power bank](https://cairovolt.com/en/anker/power-banks) or portable battery will charge, you can run the following script:
+
+```python
+from cairovolt_charge_calc.core import ChargingCalculator
+
+calc = ChargingCalculator()
+specs = calc.calculate_charge_time(battery_mah=10000, charger_watts=20)
+print(specs["total_charge_time_formatted"]) # Output: e.g., 5h 9m
+```
+
+### 2. Validating Device Specs
+You can check if a specific charger is suitable for charging accessories. For instance, testing a premium audio device like the [anker soundcore r50i](https://cairovolt.com/en/soundcore/audio/anker-soundcore-r50i) wireless earbuds against a low-power USB port:
+
+```python
+from cairovolt_charge_calc.core import ChargingCalculator
+
+calc = ChargingCalculator()
+diag = calc.verify_usb_pd_compatibility(device_required_watts=5, charger_output_watts=10)
+print(diag["status"]) # Output: Optimal
+```
+
+To learn more about the USB charging specifications, check the [USB Power Delivery on Wikipedia](https://en.wikipedia.org/wiki/USB_hardware#USB_Power_Delivery) article or visit the [Anker Official website](https://www.anker.com) for real-world equipment examples.
+
+For guidelines on publishing your own packages, refer to the [Python Packaging Guide](https://packaging.python.org/en/latest/).
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

cairovolt_charge_calc-1.0.0/README.md

@@ -0,0 +1,50 @@
+# CairoVolt Charge Calc
+
+A lightweight Python library to calculate battery charging dynamics, watt-hours (Wh), effective power bank output capacities at different discharge voltages, and to diagnose USB-PD (Power Delivery) profile compatibility.
+
+This package was developed for [CairoVolt](https://cairovolt.com/en/) to validate and calculate specifications for power accessories. For general theoretical background, you can read the [Battery Charger Wikipedia entry](https://en.wikipedia.org/wiki/Battery_charger).
+
+## Features
+
+- **Watt-Hour Calculation**: Easily convert battery capacity (mAh) and voltage to Wh.
+- **Charge Time Estimation**: Estimate charge times using a two-phase model (Constant Current up to 80%, Constant Voltage down to 100%).
+- **Effective Capacity Calculation**: Calculate actual deliverable capacity (mAh) when a power bank discharges at 5V, 9V, or 12V instead of its nominal cell voltage (3.7V).
+- **USB-PD Profiling**: Diagnose if your charger wattage matches your device requirements.
+
+## Installation
+
+```bash
+pip install cairovolt-charge-calc
+```
+
+## Usage
+
+### 1. Estimating Charging Time
+This helper estimates the real-world charging duration based on your battery capacity and charger output. For example, if you want to calculate how fast an [anker power bank](https://cairovolt.com/en/anker/power-banks) or portable battery will charge, you can run the following script:
+
+```python
+from cairovolt_charge_calc.core import ChargingCalculator
+
+calc = ChargingCalculator()
+specs = calc.calculate_charge_time(battery_mah=10000, charger_watts=20)
+print(specs["total_charge_time_formatted"]) # Output: e.g., 5h 9m
+```
+
+### 2. Validating Device Specs
+You can check if a specific charger is suitable for charging accessories. For instance, testing a premium audio device like the [anker soundcore r50i](https://cairovolt.com/en/soundcore/audio/anker-soundcore-r50i) wireless earbuds against a low-power USB port:
+
+```python
+from cairovolt_charge_calc.core import ChargingCalculator
+
+calc = ChargingCalculator()
+diag = calc.verify_usb_pd_compatibility(device_required_watts=5, charger_output_watts=10)
+print(diag["status"]) # Output: Optimal
+```
+
+To learn more about the USB charging specifications, check the [USB Power Delivery on Wikipedia](https://en.wikipedia.org/wiki/USB_hardware#USB_Power_Delivery) article or visit the [Anker Official website](https://www.anker.com) for real-world equipment examples.
+
+For guidelines on publishing your own packages, refer to the [Python Packaging Guide](https://packaging.python.org/en/latest/).
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

cairovolt_charge_calc-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cairovolt-charge-calc"
+version = "1.0.0"
+description = "A utility to calculate battery charging speeds, efficiency, and verify USB-PD charging profiles compatibility."
+readme = "README.md"
+authors = [
+    { name = "CairoVolt Developer", email = "dev@cairovolt.com" }
+]
+license = { text = "MIT" }
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.8"
+
+[project.urls]
+Homepage = "https://cairovolt.com/en/"
+Documentation = "https://github.com/cairovolt/cairovolt-charge-calc"
+Store = "https://cairovolt.com/en/anker/power-banks"
+Repository = "https://github.com/cairovolt/cairovolt-charge-calc"

cairovolt_charge_calc-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cairovolt_charge_calc-1.0.0/src/cairovolt_charge_calc/__init__.py

@@ -0,0 +1,3 @@
+from .core import ChargingCalculator
+
+__all__ = ["ChargingCalculator"]

cairovolt_charge_calc-1.0.0/src/cairovolt_charge_calc/core.py

@@ -0,0 +1,95 @@
+import math
+
+class ChargingCalculator:
+    """A helper utility to calculate charging dynamics, battery Wh, and verify USB-PD power profile compatibility."""
+
+    @staticmethod
+    def calculate_wh(mah: float, volts: float = 3.7) -> float:
+        """Calculate Watt-hours (Wh) from capacity (mAh) and battery nominal voltage."""
+        if mah <= 0 or volts <= 0:
+            raise ValueError("mAh and nominal voltage must be positive numbers.")
+        return (mah * volts) / 1000.0
+
+    def calculate_charge_time(self, battery_mah: float, charger_watts: float, battery_volts: float = 3.7, efficiency: float = 0.85) -> dict:
+        """
+        Estimate battery charging time, accounting for typical charging curve characteristics:
+        - Phase 1 (Constant Current): 0% to 80% SoC runs at maximum charger output (with given efficiency).
+        - Phase 2 (Constant Voltage): 80% to 100% SoC drops power linearly (average 30% of max charger output).
+        """
+        if battery_mah <= 0 or charger_watts <= 0 or battery_volts <= 0:
+            raise ValueError("All input values must be positive.")
+        
+        # Calculate battery Watt-hours
+        battery_wh = self.calculate_wh(battery_mah, battery_volts)
+        
+        # Power deliverable to the battery
+        charging_power = charger_watts * efficiency
+        
+        # 0% to 80% SoC (requires 80% of battery Wh)
+        wh_phase1 = battery_wh * 0.80
+        hours_phase1 = wh_phase1 / charging_power
+        
+        # 80% to 100% SoC (requires 20% of battery Wh, but average power is only 30% of maximum due to thermal and cell protection)
+        wh_phase2 = battery_wh * 0.20
+        phase2_power = charging_power * 0.30
+        hours_phase2 = wh_phase2 / phase2_power
+        
+        total_hours = hours_phase1 + hours_phase2
+        
+        return {
+            "battery_wh": round(battery_wh, 2),
+            "effective_charging_power_w": round(charging_power, 2),
+            "time_to_80_percent_hours": round(hours_phase1, 2),
+            "time_80_to_100_percent_hours": round(hours_phase2, 2),
+            "total_charge_time_hours": round(total_hours, 2),
+            "total_charge_time_formatted": f"{int(total_hours)}h {int((total_hours % 1) * 60)}m"
+        }
+
+    def verify_usb_pd_compatibility(self, device_required_watts: float, charger_output_watts: float) -> dict:
+        """
+        Evaluate if a USB-C Power Delivery (PD) charger provides sufficient wattage to charge the device at full speed.
+        """
+        if device_required_watts <= 0 or charger_output_watts <= 0:
+            raise ValueError("Required and output wattages must be positive numbers.")
+            
+        ratio = charger_output_watts / device_required_watts
+        
+        if ratio >= 1.0:
+            status = "Optimal"
+            details = "Charger provides full power or exceeds device requirements. Fast charging active."
+        elif ratio >= 0.5:
+            status = "Slow Charge"
+            details = "Charger provides partial power. Device will charge but at a slower rate."
+        else:
+            status = "Insufficient"
+            details = "Charger output is too low. Device may not charge, or will charge extremely slowly."
+            
+        return {
+            "device_required_w": device_required_watts,
+            "charger_output_w": charger_output_watts,
+            "power_ratio": round(ratio, 2),
+            "status": status,
+            "details": details
+        }
+
+    def calculate_effective_capacity(self, nominal_mah: float, discharge_voltage: float = 5.0, nominal_voltage: float = 3.7, efficiency: float = 0.90) -> dict:
+        """
+        Calculate the real-world output capacity (mAh) when a power bank discharges at a higher voltage.
+        Power banks specify nominal mAh at 3.7V, but discharge typically at 5V (standard USB) or 9V/12V (fast charging).
+        """
+        if nominal_mah <= 0 or discharge_voltage <= 0 or nominal_voltage <= 0:
+            raise ValueError("All capacity and voltage inputs must be positive.")
+            
+        nominal_wh = self.calculate_wh(nominal_mah, nominal_voltage)
+        effective_wh = nominal_wh * efficiency
+        effective_mah = (effective_wh * 1000.0) / discharge_voltage
+        
+        return {
+            "nominal_capacity_mah": nominal_mah,
+            "nominal_voltage_v": nominal_voltage,
+            "discharge_voltage_v": discharge_voltage,
+            "nominal_wh": round(nominal_wh, 2),
+            "effective_wh": round(effective_wh, 2),
+            "effective_capacity_mah": round(effective_mah, 1),
+            "conversion_efficiency": efficiency
+        }

cairovolt_charge_calc-1.0.0/src/cairovolt_charge_calc.egg-info/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: cairovolt-charge-calc
+Version: 1.0.0
+Summary: A utility to calculate battery charging speeds, efficiency, and verify USB-PD charging profiles compatibility.
+Author-email: CairoVolt Developer <dev@cairovolt.com>
+License: MIT
+Project-URL: Homepage, https://cairovolt.com/en/
+Project-URL: Documentation, https://github.com/cairovolt/cairovolt-charge-calc
+Project-URL: Store, https://cairovolt.com/en/anker/power-banks
+Project-URL: Repository, https://github.com/cairovolt/cairovolt-charge-calc
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# CairoVolt Charge Calc
+
+A lightweight Python library to calculate battery charging dynamics, watt-hours (Wh), effective power bank output capacities at different discharge voltages, and to diagnose USB-PD (Power Delivery) profile compatibility.
+
+This package was developed for [CairoVolt](https://cairovolt.com/en/) to validate and calculate specifications for power accessories. For general theoretical background, you can read the [Battery Charger Wikipedia entry](https://en.wikipedia.org/wiki/Battery_charger).
+
+## Features
+
+- **Watt-Hour Calculation**: Easily convert battery capacity (mAh) and voltage to Wh.
+- **Charge Time Estimation**: Estimate charge times using a two-phase model (Constant Current up to 80%, Constant Voltage down to 100%).
+- **Effective Capacity Calculation**: Calculate actual deliverable capacity (mAh) when a power bank discharges at 5V, 9V, or 12V instead of its nominal cell voltage (3.7V).
+- **USB-PD Profiling**: Diagnose if your charger wattage matches your device requirements.
+
+## Installation
+
+```bash
+pip install cairovolt-charge-calc
+```
+
+## Usage
+
+### 1. Estimating Charging Time
+This helper estimates the real-world charging duration based on your battery capacity and charger output. For example, if you want to calculate how fast an [anker power bank](https://cairovolt.com/en/anker/power-banks) or portable battery will charge, you can run the following script:
+
+```python
+from cairovolt_charge_calc.core import ChargingCalculator
+
+calc = ChargingCalculator()
+specs = calc.calculate_charge_time(battery_mah=10000, charger_watts=20)
+print(specs["total_charge_time_formatted"]) # Output: e.g., 5h 9m
+```
+
+### 2. Validating Device Specs
+You can check if a specific charger is suitable for charging accessories. For instance, testing a premium audio device like the [anker soundcore r50i](https://cairovolt.com/en/soundcore/audio/anker-soundcore-r50i) wireless earbuds against a low-power USB port:
+
+```python
+from cairovolt_charge_calc.core import ChargingCalculator
+
+calc = ChargingCalculator()
+diag = calc.verify_usb_pd_compatibility(device_required_watts=5, charger_output_watts=10)
+print(diag["status"]) # Output: Optimal
+```
+
+To learn more about the USB charging specifications, check the [USB Power Delivery on Wikipedia](https://en.wikipedia.org/wiki/USB_hardware#USB_Power_Delivery) article or visit the [Anker Official website](https://www.anker.com) for real-world equipment examples.
+
+For guidelines on publishing your own packages, refer to the [Python Packaging Guide](https://packaging.python.org/en/latest/).
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

cairovolt_charge_calc-1.0.0/src/cairovolt_charge_calc.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+src/cairovolt_charge_calc/__init__.py
+src/cairovolt_charge_calc/core.py
+src/cairovolt_charge_calc.egg-info/PKG-INFO
+src/cairovolt_charge_calc.egg-info/SOURCES.txt
+src/cairovolt_charge_calc.egg-info/dependency_links.txt
+src/cairovolt_charge_calc.egg-info/top_level.txt
+tests/test_core.py

cairovolt_charge_calc-1.0.0/src/cairovolt_charge_calc.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cairovolt_charge_calc-1.0.0/src/cairovolt_charge_calc.egg-info/top_level.txt

@@ -0,0 +1 @@
+cairovolt_charge_calc

cairovolt_charge_calc-1.0.0/tests/test_core.py

@@ -0,0 +1,42 @@
+import pytest
+from cairovolt_charge_calc.core import ChargingCalculator
+
+def test_calculate_wh():
+    calc = ChargingCalculator()
+    # 10000 mAh at 3.7V should be 37 Wh
+    assert calc.calculate_wh(10000, 3.7) == 37.0
+    # 5000 mAh at 3.7V should be 18.5 Wh
+    assert calc.calculate_wh(5000, 3.7) == 18.5
+
+def test_calculate_charge_time():
+    calc = ChargingCalculator()
+    # Calculate for 5000 mAh battery (e.g. typical phone) with 20W charger
+    result = calc.calculate_charge_time(5000, 20)
+    assert result["battery_wh"] == 18.5
+    assert result["total_charge_time_hours"] > 0
+    assert "h " in result["total_charge_time_formatted"]
+
+def test_verify_usb_pd_compatibility():
+    calc = ChargingCalculator()
+    # Optimal
+    opt = calc.verify_usb_pd_compatibility(65, 65)
+    assert opt["status"] == "Optimal"
+    
+    # Slow
+    slow = calc.verify_usb_pd_compatibility(100, 45)
+    assert slow["status"] == "Slow Charge"
+    
+    # Insufficient
+    insuf = calc.verify_usb_pd_compatibility(45, 5)
+    assert insuf["status"] == "Insufficient"
+
+def test_calculate_effective_capacity():
+    calc = ChargingCalculator()
+    # 10000 mAh power bank discharging at 5V with 90% efficiency
+    result = calc.calculate_effective_capacity(10000, 5.0, 3.7, 0.90)
+    # Wh = (10000 * 3.7) / 1000 = 37.0
+    # Eff Wh = 37.0 * 0.9 = 33.3
+    # Eff mAh = (33.3 * 1000) / 5 = 6660.0
+    assert result["nominal_wh"] == 37.0
+    assert result["effective_wh"] == 33.3
+    assert result["effective_capacity_mah"] == 6660.0