pacejka 0.1.0__py3-none-any.whl

pacejka/__init__.py

@@ -0,0 +1,7 @@
+"""pacejka: tire force calculations using the pacejka magic formula."""
+
+from .tire import AxisShape, MagicFormulaCoefficients, Tire
+
+__version__ = "0.1.0"
+
+__all__ = ["AxisShape", "MagicFormulaCoefficients", "Tire", "__version__"]

pacejka/tire.py

@@ -0,0 +1,455 @@
+"""Tire force model based on the pacejka "magic formula"."""
+
+from dataclasses import dataclass
+from typing import Optional, Tuple, Union
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+# Conversion factor used to turn a stiffness per degree into a stiffness per radian
+DEG_PER_RAD = 180.0 / np.pi
+
+# Inputs can be single numbers or anything array-like; results take the shape of the inputs
+FloatOrArray = Union[float, np.ndarray]
+
+# Plain Python/numpy floats take the fast scalar path; anything else takes the array path
+_SCALAR = (int, float)
+
+# Accepted values for the ``alpha_unit`` argument. Left as None, the unit is detected.
+ALPHA_UNITS = ("rad", "deg")
+
+# When ``alpha_unit`` is not given, slip angles are assumed to be radians unless any value
+# has a magnitude beyond this limit (pi/2 rad = 90 deg, where a tire is no longer rolling
+# forward). The whole input is then treated as degrees.
+ALPHA_RADIAN_LIMIT = np.pi / 2
+
+# Default magic formula shape (C) and curvature (E) factors
+DEFAULT_C = 1.4
+DEFAULT_E_LONGITUDINAL = 0.1
+DEFAULT_E_LATERAL = -0.1
+
+# Defaults used when building a tire from macro properties
+DEFAULT_LOAD_SENSITIVITY = 0.9
+DEFAULT_REFERENCE_LOAD = 150
+
+
+@dataclass(frozen=True)
+class AxisShape:
+    """
+    Fixed magic formula settings for one axis (longitudinal or lateral).
+
+    These describe the tire itself. They are set once at construction and
+    cannot be modified afterwards.
+
+    Attributes:
+        c: Shape factor.
+        e: Curvature factor.
+        b: Stiffness factor. Only set for ``constant_b`` tires; otherwise B
+            depends on the load and is computed per request.
+    """
+
+    c: float
+    e: float
+    b: Optional[float] = None
+
+
+@dataclass(frozen=True)
+class MagicFormulaCoefficients:
+    """
+    The complete set of magic formula coefficients for one axis at one load.
+
+    Created fresh for every request by ``Tire.coefficients_at`` and never
+    stored on the tire, so concurrent calls cannot interfere with each other.
+    """
+
+    b: FloatOrArray
+    c: float
+    d: FloatOrArray
+    e: float
+
+
+class Tire:
+    """
+    Holds tire parameters and computes tire forces for the applied conditions.
+
+    The fixed magic formula settings for each axis live in ``longitudinal`` and
+    ``lateral`` (both ``AxisShape``). The load-dependent coefficients (D, and B
+    unless ``constant_b`` is set) are computed on demand by ``coefficients_at``
+    and are never stored on the tire.
+
+    The force methods accept single numbers or numpy arrays. Array inputs are
+    broadcast together by numpy, so for example a column of loads and a row of
+    slip angles produce a grid of forces.
+
+    Attributes:
+        name (str): Tire name (intended to be the compound name).
+        mu_peak (float): Peak coefficient of friction.
+        cornering_stiffness_per_rad (float): Force per radian of slip angle (alpha)
+            at small angles, i.e. the slope of the force vs. angle curve. The
+            constructor only accepts radians; use ``from_macro_properties`` to
+            supply a per-degree value.
+        longitudinal_stiffness (float): Force per unit of longitudinal slip (kappa).
+        load_sensitivity_n (float): Non-linearity of peak friction as load increases.
+        f_z0 (float): Typical (reference) load, used in the load sensitivity calculations.
+        constant_b (bool): If True, B is supplied by the user and never recomputed.
+        longitudinal (AxisShape): Fixed C, E (and B if constant) for the longitudinal axis.
+        lateral (AxisShape): Fixed C, E (and B if constant) for the lateral axis.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        mu_peak: float,
+        cornering_stiffness_per_rad: Optional[float] = None,
+        longitudinal_stiffness: Optional[float] = None,
+        load_sensitivity_n: Optional[float] = None,
+        f_z0: Optional[float] = None,
+        b_x: Optional[float] = None,
+        c_x: float = DEFAULT_C,
+        e_x: float = DEFAULT_E_LONGITUDINAL,
+        b_y: Optional[float] = None,
+        c_y: float = DEFAULT_C,
+        e_y: float = DEFAULT_E_LATERAL,
+        constant_b: bool = False,
+    ):
+        self.name = name
+        self.mu_peak = mu_peak
+        self.cornering_stiffness_per_rad = cornering_stiffness_per_rad
+        self.longitudinal_stiffness = longitudinal_stiffness
+        self.load_sensitivity_n = load_sensitivity_n
+        self.f_z0 = f_z0
+        self.constant_b = constant_b
+
+        # Only the fixed settings are stored. D (and B unless constant_b is set)
+        # depend on the load, so they are computed per request instead.
+        self.longitudinal = AxisShape(c=c_x, e=e_x, b=b_x)
+        self.lateral = AxisShape(c=c_y, e=e_y, b=b_y)
+
+    # ------------------------------------------------------------------
+    # Alternate constructors
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_constants(
+        cls,
+        compound_name: str,
+        mu_base: float,
+        b_x: float,
+        c_x: float,
+        e_x: float,
+        b_y: Optional[float] = None,
+        c_y: Optional[float] = None,
+        e_y: Optional[float] = None,
+    ) -> "Tire":
+        """Build a tire from fixed B, C, E constants. Lateral values default to the longitudinal ones."""
+        return cls(
+            compound_name,
+            mu_base,
+            b_x=b_x,
+            c_x=c_x,
+            e_x=e_x,
+            b_y=b_x if b_y is None else b_y,
+            c_y=c_x if c_y is None else c_y,
+            e_y=e_x if e_y is None else e_y,
+            constant_b=True,
+        )
+
+    @classmethod
+    def from_macro_properties(
+        cls,
+        compound_name: str,
+        mu_base: float,
+        cornering_stiffness_per_deg: Optional[float] = None,
+        longitudinal_stiffness: Optional[float] = None,
+        load_sensitivity_n: float = DEFAULT_LOAD_SENSITIVITY,
+        f_z0: float = DEFAULT_REFERENCE_LOAD,
+        cornering_stiffness_per_rad: Optional[float] = None,
+    ) -> "Tire":
+        """
+        Build a tire from measurable stiffnesses; B is derived from them at each load.
+
+        Cornering stiffness can be given per degree or per radian (exactly one of
+        the two). Longitudinal stiffness is required.
+        """
+        if cornering_stiffness_per_deg is None and cornering_stiffness_per_rad is None:
+            raise ValueError(
+                "Provide cornering stiffness per degree or per radian."
+            )
+        if longitudinal_stiffness is None:
+            raise ValueError("longitudinal_stiffness is required.")
+
+        if cornering_stiffness_per_deg is not None and cornering_stiffness_per_rad is not None:
+            raise ValueError(
+                "Provide cornering stiffness per degree or per radian, not both."
+            )
+
+        # The constructor works in radians only, so convert degrees here
+        if cornering_stiffness_per_rad is None:
+            cornering_stiffness_per_rad = cornering_stiffness_per_deg * DEG_PER_RAD
+
+        return cls(
+            compound_name,
+            mu_base,
+            cornering_stiffness_per_rad=cornering_stiffness_per_rad,
+            longitudinal_stiffness=longitudinal_stiffness,
+            load_sensitivity_n=load_sensitivity_n,
+            f_z0=f_z0,
+        )
+
+    # ------------------------------------------------------------------
+    # Public force calculations
+    # ------------------------------------------------------------------
+
+    def calculate_forces(
+        self,
+        f_z: ArrayLike,
+        alpha: ArrayLike,
+        kappa: ArrayLike,
+        friction_circle: bool = True,
+        alpha_unit: Optional[str] = None,
+    ) -> Tuple[FloatOrArray, FloatOrArray]:
+        """
+        Calculate tire forces for a vertical load, slip angle and slip ratio.
+
+        Each of ``f_z``, ``alpha`` and ``kappa`` can be a single number or an
+        array, and arrays are broadcast together. With ``friction_circle=True`` both
+        forces have the broadcast shape of all three inputs. With
+        ``friction_circle=False`` each force only has the shape of its own inputs
+        (lateral: ``f_z`` and ``alpha``; longitudinal: ``f_z`` and ``kappa``).
+
+        Args:
+            f_z: Vertical load on the tire.
+            alpha: Slip angle. See ``alpha_unit`` for the unit.
+            kappa: Longitudinal slip ratio.
+            friction_circle: If True, limit the combined force to the friction circle.
+            alpha_unit: ``"rad"`` or ``"deg"`` to state the unit of ``alpha`` explicitly.
+                If None, ``alpha`` is assumed to be radians unless any value has a
+                magnitude above ALPHA_RADIAN_LIMIT (pi/2), in which case all of
+                ``alpha`` is treated as degrees.
+
+        Returns:
+            (lateral_force, longitudinal_force)
+        """
+        longitudinal, lateral = self.coefficients_at(f_z)
+
+        lateral_force = self._magic_formula_core(
+            self._slip_angle_to_radians(alpha, alpha_unit), lateral
+        )
+        longitudinal_force = self._magic_formula_core(kappa, longitudinal)
+
+        if friction_circle:
+            longitudinal_force, lateral_force = self.friction_circle(
+                longitudinal_force, lateral_force, f_z
+            )
+
+        return lateral_force, longitudinal_force
+
+    def calculate_lateral_force(
+        self, f_z: ArrayLike, alpha: ArrayLike, alpha_unit: Optional[str] = None
+    ) -> FloatOrArray:
+        """
+        Calculate the pure lateral force (no friction circle) for a load and slip angle.
+
+        ``f_z`` and ``alpha`` can be single numbers or arrays (broadcast together).
+        ``alpha_unit`` is ``"rad"``, ``"deg"`` or None to detect the unit, exactly
+        as described in ``calculate_forces``.
+        """
+        _, lateral = self.coefficients_at(f_z)
+        return self._magic_formula_core(self._slip_angle_to_radians(alpha, alpha_unit), lateral)
+
+    # ------------------------------------------------------------------
+    # Coefficient calculations
+    # ------------------------------------------------------------------
+
+    def coefficients_at(
+        self, f_z: ArrayLike
+    ) -> Tuple[MagicFormulaCoefficients, MagicFormulaCoefficients]:
+        """
+        Build the full B, C, D, E coefficients for each axis at a vertical load.
+
+        Nothing is stored on the tire, so this has no side effects and is safe to
+        call from several threads at once.
+
+        Returns:
+            (longitudinal, lateral)
+        """
+        d = self.calculate_d(f_z)
+
+        if self.constant_b:
+            b_longitudinal, b_lateral = self.longitudinal.b, self.lateral.b
+        else:
+            b_longitudinal, b_lateral = self.calculate_b(f_z, d)
+
+        longitudinal = MagicFormulaCoefficients(
+            b=b_longitudinal, c=self.longitudinal.c, d=d, e=self.longitudinal.e
+        )
+        lateral = MagicFormulaCoefficients(
+            b=b_lateral, c=self.lateral.c, d=d, e=self.lateral.e
+        )
+        return longitudinal, lateral
+
+    def calculate_d(self, f_z: ArrayLike) -> FloatOrArray:
+        """
+        Return the peak factor D (peak force) at a vertical load.
+
+        Assumes the same coefficient of friction in both directions, so the
+        value applies to both axes.
+
+        A tire carrying no load (or lifted off the ground, f_z <= 0) can produce
+        no force. This is returned directly, because the load sensitivity term
+        raises zero to a negative power and cannot be evaluated there. For an
+        array of loads this is applied to each element separately.
+
+        If ``load_sensitivity_n`` is None, load sensitivity is skipped and the
+        friction coefficient is treated as constant (D = mu_peak * f_z).
+        """
+        if isinstance(f_z, _SCALAR):  # fast path for a single load
+            if f_z <= 0:
+                return 0.0
+            if self.load_sensitivity_n is None:
+                return self.mu_peak * f_z
+            return self.mu_peak * pow(self._load_ratio(f_z), self.load_sensitivity_n - 1) * f_z
+
+        f_z = np.asarray(f_z, dtype=float)
+        loaded = f_z > 0
+        # Swap unloaded points for 1.0 so the power below never sees 0 or a negative
+        safe_f_z = np.where(loaded, f_z, 1.0)
+
+        if self.load_sensitivity_n is None:
+            mu_effective = self.mu_peak
+        else:
+            # Peak friction falls off as load rises above the reference load
+            mu_effective = self.mu_peak * pow(
+                self._load_ratio(safe_f_z), self.load_sensitivity_n - 1
+            )
+        return np.where(loaded, mu_effective * safe_f_z, 0.0)[()]
+
+    def calculate_b(
+        self, f_z: ArrayLike, d: FloatOrArray
+    ) -> Tuple[FloatOrArray, FloatOrArray]:
+        """
+        Return the stiffness factor B for each axis, from the cornering and
+        longitudinal stiffness at a vertical load.
+
+        Args:
+            f_z: Vertical load.
+            d: Peak factor D at this load.
+
+        Returns:
+            (b_longitudinal, b_lateral)
+        """
+        # Unloaded points have d == 0, which already forces B to 0 below
+        if isinstance(f_z, _SCALAR):
+            safe_f_z = f_z if f_z > 0 else 1.0
+        else:
+            f_z = np.asarray(f_z, dtype=float)
+            safe_f_z = np.where(f_z > 0, f_z, 1.0)
+        load_scaling = self._load_ratio(safe_f_z) ** self.load_sensitivity_n
+
+        # Lateral: B needs the cornering stiffness per radian
+        cornering_stiffness_rad = self.cornering_stiffness_per_rad * load_scaling
+        b_lateral = self._stiffness_to_b(cornering_stiffness_rad, self.lateral.c, d)
+
+        # Longitudinal
+        longitudinal_stiffness = self.longitudinal_stiffness * load_scaling
+        b_longitudinal = self._stiffness_to_b(longitudinal_stiffness, self.longitudinal.c, d)
+
+        return b_longitudinal, b_lateral
+
+    def friction_circle(
+        self, fx_raw: ArrayLike, fy_raw: ArrayLike, f_z: ArrayLike
+    ) -> Tuple[FloatOrArray, FloatOrArray]:
+        """
+        Limit the combined force to the friction circle. The radius is the peak
+        force at this load, so it includes load sensitivity (same as D).
+
+        Args:
+            fx_raw: Unconstrained longitudinal force.
+            fy_raw: Unconstrained lateral force.
+            f_z: Vertical load.
+
+        Returns:
+            (fx_final, fy_final)
+        """
+        if isinstance(fx_raw, _SCALAR) and isinstance(fy_raw, _SCALAR) and isinstance(f_z, _SCALAR):
+            f_max = self.calculate_d(f_z)  # fast path for single values
+            magnitude = np.sqrt(fx_raw ** 2 + fy_raw ** 2)
+            if magnitude > f_max and magnitude > 0:
+                scale = f_max / magnitude
+                return fx_raw * scale, fy_raw * scale
+            return fx_raw, fy_raw
+
+        fx_raw = np.asarray(fx_raw, dtype=float)
+        fy_raw = np.asarray(fy_raw, dtype=float)
+        f_max = self.calculate_d(f_z)
+        magnitude = np.sqrt(fx_raw ** 2 + fy_raw ** 2)
+
+        # Where total demand exceeds physical grip, scale back to the circle boundary
+        over = (magnitude > f_max) & (magnitude > 0)
+        scale = np.where(over, f_max / np.where(over, magnitude, 1.0), 1.0)
+        return (fx_raw * scale)[()], (fy_raw * scale)[()]
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _load_ratio(self, f_z: FloatOrArray) -> FloatOrArray:
+        """Vertical load relative to the reference load."""
+        return f_z / self.f_z0
+
+    @staticmethod
+    def _slip_angle_to_radians(
+        alpha: ArrayLike, alpha_unit: Optional[str] = None
+    ) -> FloatOrArray:
+        """
+        Return the slip angle in radians.
+
+        Args:
+            alpha: Slip angle, a single value or an array.
+            alpha_unit: ``"rad"`` (no conversion), ``"deg"`` (always convert), or
+                None to detect the unit. Detection makes one decision for the
+                whole input: if any value is beyond ALPHA_RADIAN_LIMIT, all of it
+                is treated as degrees, so a sweep is never half degrees, half radians.
+        """
+        if alpha_unit is not None and alpha_unit not in ALPHA_UNITS:
+            raise ValueError(f"alpha_unit must be one of {ALPHA_UNITS} or None, got {alpha_unit!r}")
+
+        is_scalar = isinstance(alpha, _SCALAR)
+        if not is_scalar:
+            alpha = np.asarray(alpha, dtype=float)
+
+        if alpha_unit == "rad":
+            return alpha
+        if alpha_unit == "deg":
+            return np.radians(alpha)
+
+        exceeds_limit = abs(alpha) > ALPHA_RADIAN_LIMIT if is_scalar else np.any(
+            np.abs(alpha) > ALPHA_RADIAN_LIMIT
+        )
+        return np.radians(alpha) if exceeds_limit else alpha
+
+    @staticmethod
+    def _stiffness_to_b(stiffness: FloatOrArray, c: float, d: FloatOrArray) -> FloatOrArray:
+        """Convert a stiffness into the magic formula B factor (B = stiffness / (C * D))."""
+        if isinstance(d, _SCALAR):  # fast path for a single load
+            return stiffness / (c * d) if d > 0 else 0
+        d = np.asarray(d, dtype=float)
+        positive = d > 0
+        safe_d = np.where(positive, d, 1.0)
+        return np.where(positive, stiffness / (c * safe_d), 0.0)[()]
+
+    @staticmethod
+    def _magic_formula_core(x_input: ArrayLike, coeffs: MagicFormulaCoefficients) -> FloatOrArray:
+        """
+        Evaluate the magic formula: D * sin(C * arctan(Bx - E * (Bx - arctan(Bx)))).
+
+        Args:
+            x_input: Slip input (slip angle or slip ratio).
+            coeffs: The B, C, D and E coefficients for this axis and load.
+        """
+        if not isinstance(x_input, _SCALAR):
+            x_input = np.asarray(x_input, dtype=float)
+
+        bx = coeffs.b * x_input
+        argument = coeffs.c * np.arctan(bx - coeffs.e * (bx - np.arctan(bx)))
+        return coeffs.d * np.sin(argument)

pacejka-0.1.0.dist-info/METADATA

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: pacejka
+Version: 0.1.0
+Summary: Calculate tire forces with the Pacejka magic formula
+Author: 2023popn
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/2023popn/Pacejka
+Project-URL: Issues, https://github.com/2023popn/Pacejka/issues
+Keywords: tire,pacejka,magic formula,vehicle dynamics,motorsport
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Provides-Extra: plots
+Requires-Dist: matplotlib>=3.5; extra == "plots"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: matplotlib>=3.5; extra == "test"
+Dynamic: license-file
+
+# Pacejka
+
+Calculate the forces a tire generates with the Pacejka "magic formula".
+
+Describe a tire by its peak friction, cornering and longitudinal stiffness, and how its grip changes with load. Then ask for the lateral and longitudinal force at any vertical load, slip angle and slip ratio. Everything works on single numbers or on whole numpy arrays, so a full slip-angle sweep or a load-versus-slip grid is one call.
+
+## Installation
+
+```bash
+pip install pacejka
+```
+
+The only dependency is numpy. To run the plotting tests too, install the `test` extra (see [Development](#development)).
+
+The package is installed as `pacejka` and imported as `Pacejka`:
+
+```python
+from pacejka import Tire
+```
+
+## Quick start
+
+```python
+from pacejka import Tire
+
+tire = Tire.from_macro_properties(
+    "Hoosier R55A",
+    mu_base=1.6,  # peak friction coefficient at the reference load
+    cornering_stiffness_per_deg=25.0,  # lateral force per degree of slip angle (small angles)
+    longitudinal_stiffness=2000.0,  # longitudinal force per unit slip ratio (small slip)
+    load_sensitivity_n=0.9,  # how much grip per unit load falls as load rises
+    f_z0=150.0,  # reference load the stiffnesses are quoted at
+)
+
+fy, fx = tire.calculate_forces(f_z=150.0, alpha=4.0, kappa=0.05, alpha_unit="deg")
+print(f"lateral = {fy:.1f}, longitudinal = {fx:.1f}")
+```
+
+```
+lateral = 94.8, longitudinal = 94.3
+```
+
+`calculate_forces` returns `(lateral_force, longitudinal_force)`. Forces come out in whatever unit you use for load, so pounds in gives pounds-force out and newtons in gives newtons out.
+
+If you only need the lateral force:
+
+```python
+fy = tire.calculate_lateral_force(150.0, 4.0, alpha_unit="deg")
+```
+
+## Units
+
+| Input | Unit |
+|---|---|
+| `f_z` (vertical load) | any force unit; forces come back in the same unit |
+| `alpha` (slip angle) | radians or degrees, see below |
+| `kappa` (slip ratio) | dimensionless, `1.0` is 100 % slip |
+| `cornering_stiffness_per_deg` / `_per_rad` | force per degree / radian of slip angle |
+| `longitudinal_stiffness` | force per unit slip ratio |
+
+### Slip angle: radians or degrees
+
+State the unit of `alpha` explicitly with `alpha_unit="rad"` or `alpha_unit="deg"`. This is the safest option.
+
+If you leave `alpha_unit` out, the unit is detected: the angle is taken to be radians unless any value has a magnitude above π/2 (about 1.57), in which case the **whole** input is treated as degrees. A sweep from −15 to 15 is therefore read correctly as degrees, but small angles in degrees are not (an angle of `0.5` looks like radians). When in doubt, pass `alpha_unit`.
+
+```python
+tire.calculate_lateral_force(150.0, 4.0)                       # detected: 4.0 is degrees
+tire.calculate_lateral_force(150.0, 0.5)                       # detected: 0.5 is radians -> 239.8
+tire.calculate_lateral_force(150.0, 0.5, alpha_unit="deg")     # explicitly degrees       -> 12.5
+```
+
+### Cornering stiffness: per degree or per radian
+
+`from_macro_properties` takes either `cornering_stiffness_per_deg` or `cornering_stiffness_per_rad` (exactly one). The `Tire` constructor itself works in radians only.
+
+## Sweeps and grids with arrays
+
+Pass arrays for any of `f_z`, `alpha` and `kappa`. numpy broadcasting combines them.
+
+A slip-angle sweep at one load:
+
+```python
+import numpy as np
+
+alpha = np.linspace(-15, 15, 7)
+fy = tire.calculate_lateral_force(150.0, alpha, alpha_unit="deg")
+print(np.round(fy, 1))
+```
+
+```
+[-223.1 -188.7 -115.2    0.   115.2  188.7  223.1]
+```
+
+A grid with one row per load and one column per slip angle:
+
+```python
+loads = np.array([[100.0], [150.0], [200.0]])   # a column
+alpha = np.array([2.0, 5.0, 10.0])               # a row
+grid = tire.calculate_lateral_force(loads, alpha, alpha_unit="deg")
+print(grid.shape)
+print(np.round(grid, 1))
+```
+
+```
+(3, 3)
+[[ 34.2  80.  131. ]
+ [ 49.3 115.2 188.7]
+ [ 63.9 149.2 244.5]]
+```
+
+Plotting a sweep with matplotlib:
+
+```python
+import matplotlib.pyplot as plt
+
+alpha = np.linspace(-30, 30, 400)
+for f_z in (50, 100, 150, 200, 250):
+    plt.plot(alpha, tire.calculate_lateral_force(f_z, alpha, alpha_unit="deg"), label=f"{f_z}")
+plt.xlabel("Slip angle (deg)")
+plt.ylabel("Lateral force")
+plt.legend()
+plt.show()
+```
+
+A scalar in gives a scalar out. Lists work as well as arrays.
+
+> When `friction_circle=False`, each force has the shape of its own inputs (lateral from `f_z` and `alpha`, longitudinal from `f_z` and `kappa`). With the friction circle on (the default), both forces have the full broadcast shape.
+
+## The friction circle
+
+By default, `calculate_forces` limits the combined force so it cannot exceed the tire's peak force at that load. If the lateral and longitudinal forces together are too large, both are scaled down by the same factor, which keeps their direction.
+
+```python
+for circle in (False, True):
+    fy, fx = tire.calculate_forces(150.0, 8.0, 0.3, friction_circle=circle, alpha_unit="deg")
+    print(f"friction_circle={circle}: fy={fy:.1f} fx={fx:.1f} total={np.hypot(fx, fy):.1f}")
+```
+
+```
+friction_circle=False: fy=164.9 fx=238.5 total=290.0
+friction_circle=True: fy=136.5 fx=197.4 total=240.0
+```
+
+The limit here is 240, which is the peak force at this load (`tire.calculate_d(150.0)`). Pass `friction_circle=False` for the pure, independent lateral and longitudinal forces.
+
+## Building a tire
+
+**From measurable properties** (most common). B is derived from your stiffnesses at each load, and grip changes with load:
+
+```python
+Tire.from_macro_properties("name", mu_base=1.6, cornering_stiffness_per_deg=25.0,
+                           longitudinal_stiffness=2000.0, load_sensitivity_n=0.9, f_z0=150.0)
+```
+
+`load_sensitivity_n` of `1.0` means grip per unit load is constant. Lower values mean it falls as load increases (`0.9` is roughly a 10 % drop per doubling of load). `f_z0` is the load at which the stiffnesses and `mu_base` apply.
+
+**From fixed magic formula constants.** You supply B, C and E directly, and there is no load sensitivity (peak force is `mu_base * f_z`). Lateral values default to the longitudinal ones if you leave them out:
+
+```python
+fixed_tire = Tire.from_constants("Fixed", mu_base=1.5, b_x=8.0, c_x=1.4, e_x=0.1)
+fy, fx = fixed_tire.calculate_forces(200.0, 0.1, 0.05, alpha_unit="rad")
+```
+
+**Directly** with `Tire(...)`, which takes cornering stiffness per radian and the other values by keyword.
+
+## Looking at the coefficients
+
+`coefficients_at(f_z)` returns the full set of magic formula coefficients for each axis at a given load, as `(longitudinal, lateral)`:
+
+```python
+longitudinal, lateral = tire.coefficients_at(150.0)
+print(lateral)
+```
+
+```
+MagicFormulaCoefficients(b=4.263078832818626, c=1.4, d=240.0, e=-0.1)
+```
+
+These are immutable and freshly built on every call. A `Tire` never changes when you ask it for forces, so one tire can safely be shared between threads. The fixed settings that belong to the tire are on `tire.longitudinal` and `tire.lateral`, for example `AxisShape(c=1.4, e=-0.1, b=None)`.
+
+## How it works
+
+For each axis, with `x` the slip angle in radians (lateral) or the slip ratio (longitudinal):
+
+```
+F = D * sin( C * arctan( B*x - E * (B*x - arctan(B*x)) ) )
+
+D = mu_peak * (Fz / Fz0) ** (n - 1) * Fz          peak force at load Fz
+B = stiffness * (Fz / Fz0) ** n / (C * D)         from the small-slip stiffness
+```
+
+`C` (shape) and `E` (curvature) default to 1.4 and 0.1 (longitudinal) or -0.1 (lateral). D is the same for both axes. A load of zero or less produces no force.
+
+## Limitations
+
+- These are the pure-slip magic formulas combined with a friction circle, not the full combined-slip Pacejka formulation. Lateral force does not depend on slip ratio except through the friction circle limit.
+- No camber, inflation pressure, speed, temperature or aligning moment.
+- The effective friction coefficient follows a power law in load, so it grows without bound as load approaches zero. Peak force still goes to zero.
+- Tire properties are your inputs. The package does not ship measured tire data, so check your coefficients against your own data.
+
+## Development
+
+```bash
+git clone https://github.com/2023popn/Pacejka
+cd pacejka
+pip install -e ".[test]"
+pytest
+```
+
+The tests include **sweeps**: plots of lateral force against slip angle, longitudinal force against slip ratio, load sensitivity, the friction circle, and a load-versus-slip grid. They are saved as PNG files in `sweep_output/` (or the folder given by `--sweep-dir`) so you can look at the curves, and each also checks the shape of what it plots.
+
+```bash
+pytest --sweep-dir=plots      # save the sweep plots somewhere else
+pytest -m "not sweep"         # skip the plotting tests
+```
+
+The sweep tests need matplotlib and are skipped if it is not installed.
+
+## License
+
+MIT. See `LICENSE`.

pacejka-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pacejka/__init__.py,sha256=5D0gvGtndphDnDbPp0UgroMv8q6p5w3goOAPh8xGP_A,232
+pacejka/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pacejka/tire.py,sha256=g9SBcTzkEzqWYDVg-qv-A_9PfB900HsI3shY9FHsyxQ,17912
+pacejka-0.1.0.dist-info/licenses/LICENSE,sha256=K3ZkJrIMYW43Wn366xIcofxxTAFfatD6Y7jLbd0VU1c,1065
+pacejka-0.1.0.dist-info/METADATA,sha256=zQNp8EK_WLbB3G6m_lsF-d56XOVho_alDOfD3H75dA0,9934
+pacejka-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pacejka-0.1.0.dist-info/top_level.txt,sha256=3Moz-Ykr26su8rdF_cpTMB7XLxUQ8c2vP4DM0CStqRg,8
+pacejka-0.1.0.dist-info/RECORD,,

pacejka-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pacejka-0.1.0.dist-info/licenses/LICENSE

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

pacejka-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pacejka