{"id":22760832,"url":"https://github.com/mohamedelashri/lvec","last_synced_at":"2026-02-25T23:04:45.602Z","repository":{"id":267461073,"uuid":"901359903","full_name":"MohamedElashri/lvec","owner":"MohamedElashri","description":"Python package for seamless handling of Lorentz vectors","archived":false,"fork":false,"pushed_at":"2025-04-12T03:43:27.000Z","size":497,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-08T21:55:02.409Z","etag":null,"topics":["awkward","hep","hep-ex","numpy","physics","root","root-cern","uproot"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/lvec/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MohamedElashri.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-10T14:12:16.000Z","updated_at":"2025-04-12T02:03:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"b58848cd-cd64-4f05-b617-fb8bcba44137","html_url":"https://github.com/MohamedElashri/lvec","commit_stats":null,"previous_names":["mohamedelashri/lvec"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/MohamedElashri/lvec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MohamedElashri%2Flvec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MohamedElashri%2Flvec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MohamedElashri%2Flvec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MohamedElashri%2Flvec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MohamedElashri","download_url":"https://codeload.github.com/MohamedElashri/lvec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MohamedElashri%2Flvec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29844845,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-25T22:37:40.667Z","status":"ssl_error","status_checked_at":"2026-02-25T22:37:25.960Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["awkward","hep","hep-ex","numpy","physics","root","root-cern","uproot"],"created_at":"2024-12-11T09:08:40.104Z","updated_at":"2026-02-25T23:04:45.586Z","avatar_url":"https://github.com/MohamedElashri.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![lvec CI](https://github.com/MohamedElashri/lvec/actions/workflows/Build_Package.yml/badge.svg)](https://github.com/MohamedElashri/lvec/actions/workflows/Build_Package.yml)\n\n# LVec\n\n[![PyPI version](https://badge.fury.io/py/lvec.svg)](https://badge.fury.io/py/lvec)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n\n\u003e ⚠️ This project is a work in progress\n\nA Python package for seamless handling of Lorentz vectors, 2D vectors, and 3D vectors in HEP analysis, bridging the gap between Scikit-HEP and ROOT ecosystems.\n\n## Motivation\n\nLVec aims to simplify HEP analysis by providing a unified interface for working with various vector types across different frameworks. It seamlessly integrates with both the Scikit-HEP ecosystem (uproot, vector, awkward) and ROOT/PyROOT, enabling physicists to write more maintainable and efficient analysis code.\n\n## Installation\n\n```bash\npip install lvec\n```\n\nFor development installation:\n```bash\ngit clone https://github.com/MohamedElashri/lvec\ncd lvec\npip install -e \".[dev]\"\n```\n\n## Quick Start\n\n### Lorentz Vectors\n```python\nfrom lvec import LVec\nimport numpy as np\n\n# Create a single Lorentz vector\nv = LVec(px=1.0, py=2.0, pz=3.0, E=4.0)\n\n# Access properties\nprint(f\"Mass: {v.mass}\")\nprint(f\"pt: {v.pt}\")\n\n# Create from pt, eta, phi, mass\nv2 = LVec.from_ptepm(pt=5.0, eta=0.0, phi=0.0, m=1.0)\n\n# Vector operations\nv3 = v1 + v2\nv4 = v1 * 2.0\n```\n\n### Memory Optimization\n```python\n# Create vector with cache size limit (LRU eviction)\nv = LVec(px=1.0, py=2.0, pz=3.0, E=4.0, max_cache_size=100)\n\n# Create vector with TTL for all properties\nv_ttl = LVec(px=1.0, py=2.0, pz=3.0, E=4.0, default_ttl=60)  # 60 second TTL\n\n# Set TTL for specific property\nv.set_ttl('pt', 10)  # 10 second TTL for transverse momentum\n\n# Get cache statistics\nstats = v.cache_stats\nprint(f\"Cache hit ratio: {v.cache_hit_ratio}\")\n```\n\n### Reference Frames\n```python\nfrom lvec import LVec, Frame\n\n# Create particles in the lab frame\np1_lab = LVec(px=0.0, py=0.0, pz=20.0, E=25.0)\np2_lab = LVec(px=0.0, py=0.0, pz=-15.0, E=20.0)\ntotal_lab = p1_lab + p2_lab\n\n# Create reference frames\nlab_frame = Frame.rest(name=\"lab\")  # Stationary frame\ncm_frame = Frame.from_lvec(total_lab, name=\"cm\")  # Center-of-mass frame\n\n# Transform particles to center-of-mass frame\np1_cm = p1_lab.transform_frame(lab_frame, cm_frame)\np2_cm = p2_lab.transform_frame(lab_frame, cm_frame)\n\n# Verify momentum conservation in CM frame\ntotal_cm = p1_cm + p2_cm\nprint(f\"Total momentum in CM: ({total_cm.px:.3f}, {total_cm.py:.3f}, {total_cm.pz:.3f})\")\n# Should output values close to (0, 0, 0)\n\n# Alternative: directly transform to a frame\np1_cm_alt = p1_lab.to_frame(cm_frame)\n```\n\n### 2D Vectors\n```python\nfrom lvec import Vector2D\n\n# Create a 2D vector\nvec2d = Vector2D(x=3.0, y=4.0)\n\n# Access properties\nprint(f\"Magnitude: {vec2d.r}\")\nprint(f\"Angle (phi): {vec2d.phi}\")\n\n# Rotate vector\nrotated = vec2d.rotate(angle=np.pi/4)  # 45 degrees rotation\n```\n\n### 3D Vectors\n```python\nfrom lvec import Vector3D\n\n# Create a 3D vector\nvec3d = Vector3D(x=1.0, y=2.0, z=3.0)\n\n# Access properties\nprint(f\"Magnitude: {vec3d.r}\")\nprint(f\"Theta: {vec3d.theta}\")\nprint(f\"Phi: {vec3d.phi}\")\n\n# Rotate around axis\nrotated = vec3d.rotate(theta=np.pi/2, axis=[0, 1, 0])  # 90 degrees around y-axis\n```\n\n### Array Operations\n```python\n# Works with numpy arrays\npx = np.array([1.0, 2.0, 3.0])\npy = np.array([2.0, 3.0, 4.0])\npz = np.array([3.0, 4.0, 5.0])\nE = np.array([4.0, 5.0, 6.0])\nvectors = LVec(px, py, pz, E)\n\n# Works with awkward arrays\nimport awkward as ak\nvectors_ak = LVec(ak.Array(px), ak.Array(py), ak.Array(pz), ak.Array(E))\n```\n\n## Available Methods\n\n### Lorentz Vector (LVec) Methods\n\n| Method | Description | Parameters | Returns |\n|--------|-------------|------------|----------|\n| `__init__` | Create a Lorentz vector | `px, py, pz, E, max_cache_size=None, default_ttl=None` | `LVec` |\n| `from_ptepm` | Create from pt, eta, phi, mass | `pt, eta, phi, m` | `LVec` |\n| `from_p4` | Create from px, py, pz, E | `px, py, pz, E` | `LVec` |\n| `from_ary` | Create from dictionary | `ary_dict` with px, py, pz, E keys | `LVec` |\n| `from_vec` | Create from vector-like object | `vobj` with px, py, pz, E attributes | `LVec` |\n| `boost` | Boost vector to new frame | `bx, by, bz` | `LVec` |\n| `to_frame` | Transform to specified frame | `frame` | `LVec` |\n| `transform_frame` | Transform between frames | `current_frame, target_frame` | `LVec` |\n| `set_ttl` | Set TTL for property | `property_name, ttl_seconds` | None |\n| `clear_expired` | Remove expired cache values | - | `int` (count) |\n| `cache_stats` | Get cache statistics | - | `dict` |\n| `cache_hit_ratio` | Get cache hit ratio | - | `float` |\n| `reset_cache_stats` | Reset cache statistics | - | None |\n| `cache_size` | Get current cache size | - | `int` |\n| `mass` | Get invariant mass | - | `float` |\n| `pt` | Get transverse momentum | - | `float` |\n| `eta` | Get pseudorapidity | - | `float` |\n| `phi` | Get azimuthal angle | - | `float` |\n| `E` | Get energy | - | `float` |\n| `p` | Get total momentum | - | `float` |\n\n### Frame Methods\n\n| Method | Description | Parameters | Returns |\n|--------|-------------|------------|----------|\n| `__init__` | Create a reference frame | `bx, by, bz, name` | `Frame` |\n| `rest` | Create a stationary frame | `name` | `Frame` |\n| `from_lvec` | Create frame in which a vector is at rest | `total_lvec, name` | `Frame` |\n| `center_of_mass` | Create center-of-mass frame from vectors | `lvec_list, name` | `Frame` |\n\n### 2D Vector (Vector2D) Methods\n\n| Method | Description | Parameters | Returns |\n|--------|-------------|------------|----------|\n| `__init__` | Create a 2D vector | `x, y` | `Vector2D` |\n| `x` | Get x component | - | `float` |\n| `y` | Get y component | - | `float` |\n| `r` | Get vector magnitude | - | `float` |\n| `phi` | Get azimuthal angle | - | `float` |\n| `dot` | Compute dot product | `other` | `float` |\n\n### 3D Vector (Vector3D) Methods\n\n| Method | Description | Parameters | Returns |\n|--------|-------------|------------|----------|\n| `__init__` | Create a 3D vector | `x, y, z` | `Vector3D` |\n| `x` | Get x component | - | `float` |\n| `y` | Get y component | - | `float` |\n| `z` | Get z component | - | `float` |\n| `r` | Get vector magnitude | - | `float` |\n| `rho` | Get cylindrical radius | - | `float` |\n| `phi` | Get azimuthal angle | - | `float` |\n| `theta` | Get polar angle | - | `float` |\n| `dot` | Compute dot product | `other` | `float` |\n| `cross` | Compute cross product | `other` | `Vector3D` |\n\n## Requirements\n\n- Python \u003e= 3.10\n- NumPy \u003e= 1.20.0\n- Awkward \u003e= 2.0.0\n\nFor development:\n- pytest \u003e= 7.0.0\n- uproot \u003e= 5.0.0\n\n## Citation\n\nIf you use LVec in your research, please cite:\n\n```bibtex\n@software{lvec2024,\n  author       = {Mohamed Elashri},\n  title        = {LVec: A Python package for handling Lorentz vectors},\n  year         = {2024},\n  publisher    = {GitHub},\n  url          = {https://github.com/MohamedElashri/lvec}\n}\n```\n\n## Documentation\n\nFor detailed documentation and examples, visit our [documentation page](https://github.com/MohamedElashri/lvec/tree/main/docs).\n\n## Examples\n\nCheck out our [examples directory](https://github.com/MohamedElashri/lvec/tree/main/examples) for comprehensive examples including:\n- Basic vector operations\n- Reference frame transformations\n- Decay reconstructions\n- Center-of-mass calculations\n- 2D vector manipulations\n- 3D spatial analysis\n- Advanced selections\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmohamedelashri%2Flvec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmohamedelashri%2Flvec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmohamedelashri%2Flvec/lists"}