physkit 0.1.17__py3-none-any.whl

physkit/conversions.py

@@ -0,0 +1,124 @@
+# Physkit - A Python toolkit for constants, unit conversions, and equations.
+# Copyright (C) 2024 sapphimars
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""
+conversions.py
+
+Convenience functions for unit conversions, using the shared Pint
+UnitRegistry from config.py.
+
+The user-facing API only takes/returns floats and strings:
+    - convert_unit(value, from_unit, to_unit)
+    - convert_to_base_units(value, from_unit)
+    - convert_unit_system(value, from_unit, system_name="cgs")
+
+Under the hood, we use Pint's UnitRegistry (from config.py) to do
+all conversions. The user never interacts with Pint objects.
+"""
+
+import pint
+from .config import get_ureg  # , set_default
+
+
+def convert_unit(value: float, from_unit: str, to_unit: str) -> float:
+    """
+    Convert a numeric value from `from_unit` to `to_unit`.
+
+    Args:
+        value (float): The numeric value to convert.
+        from_unit (str): The current unit of `value`.
+        to_unit (str): The target unit.
+
+    Returns:
+        float: The numeric value converted to the `to_unit`.
+
+    Example:
+        convert_unit(5, "erg", "J") -> 5e-7
+        convert_unit(1, "meter", "foot") -> ~3.28084
+    """
+    ureg = get_ureg()
+    quantity = value * ureg(from_unit)
+    converted = quantity.to(to_unit)
+    return converted.magnitude
+
+
+def convert_to_base_units(value: float, from_unit: str) -> tuple[float, str]:
+    """
+    Convert a numeric value from `from_unit` to the *default base units*
+    of the shared UnitRegistry. Typically this is SI base units unless
+    you've called set_default_system(...) to change it.
+
+    Args:
+        value (float): input value
+        from_unit (str): input unit
+
+    Returns:
+        tuple[float, str]: output value and its unit
+
+    Example:
+        # If default system is SI:
+        convert_to_base_units(39.37, "inch") -> ~1.0 (meter)
+    """
+    ureg = get_ureg()
+    quantity = value * ureg(from_unit)
+    base_converted = quantity.to_base_units()
+    return base_converted.magnitude, f"{base_converted.units:~}"
+
+
+def convert_unit_system(
+    value: float, from_unit: str, system_name: str = "cgs"
+) -> tuple[float, str]:
+    """
+    Convert a numeric value from `from_unit` in the shared default registry
+    to the base units of a different unit system (e.g., 'cgs', 'imperial', etc.)
+    without changing the global default system.
+
+    Creates a temporary pint.UnitRegistry with the specified system,
+    converts `value` to base SI, then interprets that SI quantity in
+    the temporary system's base units.
+
+    Args:
+        value (float): input value
+        from_unit (str): input unit
+        system_name (str, optional): output unit system. Defaults to "cgs".
+
+    Returns:
+        tuple[float, str]: output value and its unit
+
+    Example:
+        # Suppose global default is SI
+        # We convert 1 meter (in SI) to the base units of cgs -> centimeter
+        convert_unit_system(1, "meter", system_name="cgs") -> 100.0 (centimeter)
+    """
+
+    # Convert the input to base SI using the shared registry
+    shared_ureg = get_ureg()
+    si_quantity = (value * shared_ureg(from_unit)).to_base_units()
+
+    # Create a temporary registry in the chosen system
+    temp_ureg = pint.UnitRegistry(system=system_name)
+
+    # Build the quantity in the temporary registry
+
+    magnitude_si = si_quantity.magnitude
+    unit_si_str = str(si_quantity.u)
+
+    new_qty_in_temp = magnitude_si * temp_ureg(unit_si_str)
+
+    # Convert to the base units of the new system
+    base_in_temp_system = new_qty_in_temp.to_base_units()
+
+    return base_in_temp_system.magnitude, f"{base_in_temp_system.units:~}"

physkit/custom_units.py

@@ -0,0 +1,33 @@
+# Physkit - A Python toolkit for constants, unit conversions, and equations.
+# Copyright (C) 2024 sapphimars
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+
+def define_custom_units(ureg):
+    """
+    Define custom units that Pint doesn't include by default.
+    Call this AFTER creating the UnitRegistry in config.py.
+
+    Args:
+        ureg (pint.UnitRegistry): global ureg object from config.py
+    """
+    # Jansky (Jy)
+    ureg.define("jansky = 1e-26 watt / meter^2 / hertz = Jy")
+
+    # Solar luminosity: 1 L_sun = 3.828e26 W
+    ureg.define("solar_luminosity = 3.828e26 watt = L_sun")
+
+    # Solar mass: 1 M_sun = 1.98847e30 kg
+    ureg.define("solar_mass = 1.98847e30 kg = M_sun")

physkit/equations.py

@@ -0,0 +1,117 @@
+# Physkit - A Python toolkit for constants, unit conversions, and equations.
+# Copyright (C) 2024 sapphimars
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+
+from .config import get_ureg
+from .constants import constants
+
+
+class Equations:
+
+    @staticmethod
+    def gravitational_radius(
+        mass_value: float, mass_unit: str = "kg", out_unit: str = "m"
+    ) -> tuple[float, str]:
+        """
+        Compute the gravitational radius for a given mass.
+        r_g = G * M / c^2
+
+        Args:
+            mass_value (float): input mass
+            mass_unit (str, optional): unit for input mass. Defaults to "kg".
+            out_unit (str, optional): unit for output radius. Defaults to "m".
+
+        Returns:
+            (float, str): output radius and its unit
+        """
+
+        # Get the shared registry
+        ureg = get_ureg()
+
+        # Get pint Quantity for mass
+        mass_qty = mass_value * ureg(mass_unit)
+
+        # Retrieve constants from the constants module
+        G_val, G_unit = constants.G
+        c_val, c_unit = constants.c
+
+        # Get Pint Quantities for constants
+        G_qty = G_val * ureg(G_unit)
+        c_qty = c_val * ureg(c_unit)
+
+        r_g_qty = G_qty * mass_qty / (c_qty**2)
+
+        # Convert to output unit
+        r_g_converted = r_g_qty.to(out_unit)
+
+        return r_g_converted.magnitude, f"{r_g_converted.units:~}"
+
+    @staticmethod
+    def schwartzschild_radius(
+        mass_value: float, mass_unit: str = "kg", out_unit: str = "m"
+    ) -> tuple[float, str]:
+        """
+        Compute the Schwartzschild radius for a given mass.
+
+        Args:
+            mass_value (float): input mass
+            mass_unit (str, optional): unit for input mass. Defaults to "kg".
+            out_unit (str, optional): unit for output radius. Defaults to "m".
+
+        Returns:
+            tuple[float, str]: output radius and its unit
+        """
+        mag, unit_str = Equations.gravitational_radius(mass_value, mass_unit, out_unit)
+        mag *= 2
+        return mag, unit_str
+
+    @staticmethod
+    def eddington_luminosity(
+        mass_value: float, mass_unit: str = "kg", out_unit: str = "W"
+    ) -> tuple[float, str]:
+        """
+        Compute the Eddington luminosity for a given mass.
+
+        Args:
+            mass_value (float): input mass
+            mass_unit (str, optional): unit for input mass. Defaults to "kg".
+            out_unit (str, optional): unit for output luminosity. Defaults to "W".
+
+        Returns:
+            tuple[float, str]: output luminosity and its unit
+        """
+        ureg = get_ureg()
+        mass_qty = mass_value * ureg(mass_unit)
+
+        pi, _ = constants.pi
+        G_val, G_unit = constants.G  # e.g. (6.6743e-11, "m^3 / kg / s^2")
+        c_val, c_unit = constants.c  # e.g. (3.0e8, "m / s")
+        m_p_val, m_p_unit = constants.m_p
+        sigma_T_val, sigma_T_unit = constants.sigma_T
+
+        G_qty = G_val * ureg(G_unit)
+        c_qty = c_val * ureg(c_unit)
+        m_p_qty = m_p_val * ureg(m_p_unit)
+        sigma_T_qty = sigma_T_val * ureg(sigma_T_unit)
+
+        L_edd_qty = 4 * pi * G_qty * m_p_qty * c_qty * mass_qty / sigma_T_qty
+
+        L_edd_converted = L_edd_qty.to(out_unit)
+
+        return L_edd_converted.magnitude, f"{L_edd_converted.units:~}"
+
+
+equations = Equations()

physkit/plot_styler.py

@@ -0,0 +1,115 @@
+# Physkit - A Python toolkit for constants, unit conversions, and equations.
+# Copyright (C) 2024 sapphimars
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+
+import matplotlib.pyplot as plt
+
+
+def plot_styler(
+    xdata,
+    ydata,
+    title: str = None,
+    xlabel: str = None,
+    ylabel: str = None,
+    xlims: list = None,
+    ylims: list = None,
+    color: str = None,
+    label: str = None,
+    marker: str = None,
+    line: str = None,
+    markersize: int = 4,
+    linewidth: float = None,
+    yerr: list = None,
+    minorgrid: bool = False,
+    loglog: bool = False,
+    ax=None,
+    scatter: bool = False,
+) -> None:
+    """
+    Helper function which adds styling to each plot in the way we want.
+
+    Args:
+        xdata (list or np.ndarray),
+        ydata (list or np.ndarray),
+        title (str optional),
+        xlabel (str optional),
+        ylabel (str optional),
+        xlims (list optional),
+        ylims (list optional),
+        color (str optional),
+        label (str optional),
+        marker (str optional),
+        line (str optional)
+        markersize (int default = 4),
+        linewidth (float optional),
+        yerr (np.ndarray optional),
+        minorgrid (bool default = False),
+        loglog (bool default = False),
+        ax (matplotlib.axes.Axes optional),
+        scatter (bool default = False),
+    """
+
+    if ax is None:
+        ax = plt  # Default to using the global plt object if no axis
+
+    if loglog:
+        ax.set_xscale("log")
+        ax.set_yscale("log")
+
+    if yerr is not None:
+        ax.errorbar(
+            xdata,
+            ydata,
+            fmt=marker,
+            yerr=yerr,
+            color=color,
+            markersize=markersize,
+            label=label,
+            linewidth=linewidth,
+        )
+    elif scatter:
+        ax.scatter(xdata, ydata, marker=marker, color=color, label=label)
+    else:
+        ax.plot(
+            xdata,
+            ydata,
+            marker=marker,
+            color=color,
+            markersize=markersize,
+            label=label,
+            linewidth=linewidth,
+        )
+
+    if title:
+        ax.set_title(title, fontsize=15)
+    if xlabel:
+        ax.set_xlabel(xlabel, fontsize=12)
+    if ylabel:
+        ax.set_ylabel(ylabel, fontsize=12)
+    if xlims:
+        ax.set_xlim(xlims)
+    if ylims:
+        ax.set_ylim(ylims)
+
+    ax.grid(which="major", color="#CCCCCC")
+    if minorgrid:
+        ax.minorticks_on()
+        ax.grid(which="minor", color="#EEEEEE", linestyle=":")
+
+    ax.set_axisbelow(True)
+
+    if label:
+        ax.legend()

physkit-0.1.17.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.1
+Name: physkit
+Version: 0.1.17
+Summary: A Python toolkit providing physical constants, unit conversions, and plotting styles
+Keywords: physics,units,pint,plotting
+Author: sapphimars
+License: GPL-3.0-or-later
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: OS Independent
+Project-URL: Homepage, https://github.com/sapphimars/physkit
+Project-URL: Repository, https://github.com/sapphimars/physkit
+Project-URL: Bug Tracker, https://github.com/sapphimars/physkit/issues
+Requires-Python: >=3.12
+Requires-Dist: pint>=0.24.4
+Requires-Dist: matplotlib>=3.10.0
+Requires-Dist: pdm-backend>=2.4.3
+Description-Content-Type: text/markdown
+
+# Physkit - A Python toolkit for constants, unit conversions, and equations
+
+[![Build Status](https://github.com/sapphimars/physkit/actions/workflows/test.yml/badge.svg)](https://github.com/sapphimars/physkit/actions/workflows/test.yml)
+[![PyPI Version](https://img.shields.io/pypi/v/physkit)](https://pypi.org/project/physkit/)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+
+**Physkit** is a Python library for performing scientific computations, unit conversions, and working with physical constants and equations.  
+It provides tools for astrophysical and physical calculations, supporting multiple unit systems and CLI functionalities.
+
+<figure> 
+  <img src="https://github.com/sapphimars/physkit/blob/main/assets/physkit_icon_wide.png?raw=true" alt="drawing" />
+</figure>
+
+###### Icon created by [astroastra](https://github.com/astroastrastudio)
+
+---
+
+## **License**
+
+This project is licensed under the terms of the **GNU General Public License v3.0**.  
+See the [LICENSE](https://github.com/sapphimars/physkit/blob/main/LICENSE) file for details.  
+
+Copyright (C) 2024 [sapphimars](https://github.com/sapphimars)  
+
+---
+
+### **Third-Party Licenses**
+
+This project makes use of the following third-party libraries:
+
+- **[Matplotlib](https://matplotlib.org/)** - Licensed under the Matplotlib License Agreement. See [licenses/LICENSE-MATPLOTLIB.txt](https://github.com/sapphimars/physkit/blob/main/licenses/LICENSE-MATPLOTLIB.txt) or [directly on their repository](https://github.com/matplotlib/matplotlib/tree/main/LICENSE).
+- **[Pint](https://github.com/hgrecco/pint)** - Licensed under the BSD 3-Clause License. See [licenses/LICENSE-PINT.txt](https://github.com/sapphimars/physkit/blob/main/licenses/LICENSE-PINT.txt) or [directly on their repository](https://github.com/hgrecco/pint/blob/master/LICENSE).
+
+Note: Third-party libraries included in this project are licensed under their respective terms. See the `licenses/` directory for full details.
+
+---
+
+## **Installation**
+
+### **Requirements**
+
+- Python **3.12** or higher  
+- Dependencies:
+  - **Matplotlib** >= 3.5  
+  - **Pint** >= 0.20  
+
+---
+
+### **Install via pip**
+```bash
+pip install physkit
+```
+
+---
+
+### **For Development**
+```bash
+pdm install
+```
+
+To install test dependencies:
+```bash
+pdm install -G test
+```
+
+---
+
+## **Usage Examples**
+
+### **Access Constants**
+```python
+import physkit as pk
+from physkit.constants import constants as csts
+
+print(csts.G)  # Gravitational constant in SI
+pk.set_default("cgs")
+print(csts.G)  # Gravitational constant in CGS
+```
+
+---
+
+### **Unit Conversion**
+```python
+from physkit.conversions import convert_unit
+
+result = convert_unit(1, 'm', 'cm')
+print(result)  # Outputs: 100.0
+```
+
+---
+
+### **Equations**
+```python
+from physkit.equations import equations
+
+# Default units are SI. Specify other units explicitly, like so:
+mass = 1.0  # Solar mass
+radius = equations.gravitational_radius(mass, 'M_sun', 'km') # input mass in solar masses
+print(radius)  # Gravitational radius in km
+```
+
+---
+### **Plot Styling**
+This is just a quick way to make good looking plots simply.
+```python
+import physkit as pk
+import matplotlib.pyplot as plt
+
+x_data = [...]  # Example data for x and y
+y_data = [...]
+
+fig, ax = plt.subplots()
+pk.plot_styler(x_data, y_data, ax=ax, title="test", 
+               ylabel="y label", xlabel="x label", loglog=True)
+plt.show()
+
+```
+---
+### **Command Line Interface (CLI)**
+```bash
+physkit constant G --system cgs
+```
+```bash
+physkit convert 1 m cm
+```
+
+---
+
+## **Contributing**
+
+Contributions are welcome!  
+
+1. Fork the repository.  
+2. Create a new branch (`git checkout -b feature-name`).  
+3. Commit changes (`git commit -m "Add new feature"`).  
+4. Push to your branch (`git push origin feature-name`).  
+5. Open a Pull Request.
+
+---
+
+## **Issues**
+
+If you encounter any issues or have suggestions, feel free to open an issue on [GitHub](https://github.com/sapphimars/physkit/issues).
+
+---
+
+## **Contact**
+
+For inquiries, contact me via GitHub: [sapphimars](https://github.com/sapphimars)
+

physkit-0.1.17.dist-info/RECORD

@@ -0,0 +1,13 @@
+physkit-0.1.17.dist-info/METADATA,sha256=iE5KzzzjHS7CGRQmQRdna_jSPl8uR4QYNERyRD7UgVQ,4851
+physkit-0.1.17.dist-info/WHEEL,sha256=thaaA2w1JzcGC48WYufAs8nrYZjJm8LqNfnXFOFyCC4,90
+physkit-0.1.17.dist-info/entry_points.txt,sha256=GOPyeWV9vsHwYs8FvWvR1kLPnIC6_o1kuRxjM_2dZ9M,61
+physkit-0.1.17.dist-info/licenses/LICENSE,sha256=5X8cMguM-HmKfS_4Om-eBqM6A1hfbgZf6pfx2G24QFI,35150
+physkit/__init__.py,sha256=Kjhw8VH2KZ8Rpz2leY2oR1MiJ7zY98hIma0OvxV7DSE,1324
+physkit/cli.py,sha256=sUGnTyHKhuqhzfqyxmosA7crPmeLW9ofp2psY0lICwE,3130
+physkit/config.py,sha256=wQaZGIFsjEVWER0Oi5K-vmbirBrsqrlaIeXU_Z6q-eo,1282
+physkit/constants.py,sha256=YpsRAjOMcEynREJGYLI0Gefbus6hrCA2N0Mv7XZ5r8w,14868
+physkit/conversions.py,sha256=Q2Vp5UhLEuiHUFU-UviY-APuzzn2JJUkKCad8L0qb14,4203
+physkit/custom_units.py,sha256=769knoVgg5FOlChwoFp7BzSVB75DW0AS-lZ4w58Whkk,1277
+physkit/equations.py,sha256=hMFuV4SYXXcsN_f3xjNs4ZvYFKialv11myMkkGC-An0,3881
+physkit/plot_styler.py,sha256=ZAgmW7k3DjTsIHnIzk2tKawWBOSAp6IglKx5YUAa-Bc,3138
+physkit-0.1.17.dist-info/RECORD,,

physkit-0.1.17.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: pdm-backend (2.4.3)
+Root-Is-Purelib: true
+Tag: py3-none-any

physkit-0.1.17.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+physkit = physkit.cli:main
+
+[gui_scripts]
+