{"id":32635521,"url":"https://github.com/uob-positron-imaging-centre/up4","last_synced_at":"2025-10-31T00:54:51.630Z","repository":{"id":65781680,"uuid":"293095306","full_name":"uob-positron-imaging-centre/up4","owner":"uob-positron-imaging-centre","description":"Post-processor for particle data.","archived":false,"fork":false,"pushed_at":"2025-10-03T23:24:50.000Z","size":228849,"stargazers_count":10,"open_issues_count":16,"forks_count":2,"subscribers_count":6,"default_branch":"uPPPP","last_synced_at":"2025-10-04T00:26:22.188Z","etag":null,"topics":["granular","postprocessing"],"latest_commit_sha":null,"homepage":"https://uob-positron-imaging-centre.github.io/up4/","language":"Rust","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/uob-positron-imaging-centre.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-09-05T14:46:47.000Z","updated_at":"2025-10-03T23:24:50.000Z","dependencies_parsed_at":"2024-05-02T10:51:55.736Z","dependency_job_id":"a2844074-01b8-4d34-9e39-606b12812b4c","html_url":"https://github.com/uob-positron-imaging-centre/up4","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/uob-positron-imaging-centre/up4","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uob-positron-imaging-centre%2Fup4","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uob-positron-imaging-centre%2Fup4/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uob-positron-imaging-centre%2Fup4/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uob-positron-imaging-centre%2Fup4/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uob-positron-imaging-centre","download_url":"https://codeload.github.com/uob-positron-imaging-centre/up4/tar.gz/refs/heads/uPPPP","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uob-positron-imaging-centre%2Fup4/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281908615,"owners_count":26582147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-30T02:00:06.501Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["granular","postprocessing"],"created_at":"2025-10-31T00:54:49.021Z","updated_at":"2025-10-31T00:54:51.624Z","avatar_url":"https://github.com/uob-positron-imaging-centre.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1\u003e\u003cimg src=\"docs/source/_static/logo.jpeg\" width = \"70px\", style = \"float: right\"\u003eup4: Universal Post-Processor for Particulate Processes\u003c/h1\u003e\n\n[![Test Rust](https://github.com/uob-positron-imaging-centre/up4/actions/workflows/test-rust.yml/badge.svg)](https://github.com/uob-positron-imaging-centre/up4/actions/workflows/test-rust.yml)\n[![Test Python](https://github.com/uob-positron-imaging-centre/up4/actions/workflows/test-python.yml/badge.svg)](https://github.com/uob-positron-imaging-centre/up4/actions/workflows/test-python.yml)\n[![docs](https://img.shields.io/badge/docs-dev-blue)](https://uob-positron-imaging-centre.github.io/up4/)\n\n## A fast _and_ flexible analysis toolset for particle data of all kinds\n\nUse it to compare inter-platform particle results - either experimental\nor synthetic data generated by different platforms like\n[LIGGGHTS][1], [MercuryDPM][2], [Barracuda][3] and more.\n\n`up4` has a python API, which enables it to be easy to use for a wide range of\nscientists, but the core of it is implemented in [Rust](https://www.rust-lang.org/).\n\n## Installation\n\n### **1. HDF5**\n\nOne of the main requirements is the HDF5 library.\nTo install the library we recommend using conda\n\n```bash\nconda install -c conda-forge hdf5==1.10.4\n```\n\nadditionally, we recommend installing to export the following environment variables:\n\n```bash\nexport HDF5_DIR=\"$CONDA_PREFIX\"\n```\n\nfor more information see the [hdf5-rust](https://github.com/aldanor/hdf5-rust) instructions\n\n### **2. Rust**\n\nyou will need a rust compiler, see:\n\n\u003chttps://www.rust-lang.org/tools/install\u003e\n\nRust dependencies will be installed automatically DURING compilation\n\n### **3. Python**\n\nDownload or clone this repository and run:\n\n```bash\npython3 -m pip install -r requirements.txt\n```\n\nafter the requirements are installed, you can install the package with:\n\n```bash\npython3 -m pip install .\n```\n\nthis could take some time as it compiles the rust code on your machine.\n\nTo ensure that the installation was successful, you can run tests with [pytest](https://docs.pytest.org/en/7.1.x/getting-started.html):\n\n```bash\npython3 -m pytest tests/test_all.py\n```\n\n### VSCode users\n\nCurrently, type hinting/ autocomplete is only possible\nif the [Python language server is set to Jedi][4].\n\n## To DO / Dev notes\n\n### Tests\n\n- test failures. make exceptions work\n- make paths work also when pytested from different folder\n- new, better and smaller test datasets\n- test converter::convertertools:{interpolate, velocity}\n\n## Ideas\n\n- save_constraints --\u003e save the current particle selector constraints in the hdf5\n  file if file contains constraints, load them in Selector, however warn the user\n  while loading, also make a reverse function to set selector to default state\n  ( data.selector_default or similar)\n- Align grids for comparison. Use some smart metric to align two grids and make\n  diffs/or Hanquiao plots\n- Statistics, is my data good enough? (how many traj do i need per cell to get\n  good data)\n- Data manipulation --\u003e Rotate, translate system(with backup)\n-\n\n## Bugs\n\n- bug in interpolator for csv files? there are zeros in 3u_HD1_glass\n\n## Documentation\n\nExtensive effort has gone into documenting _every_ trait, function, struct, class\nand method in this library, so regardless of using this library in Rust _or_\nPython, there are no magic undocumented blocks of code. The Rust API reference\ncan be found here\n\n## TODO add link\n\nand the Python API reference [here](https://uob-positron-imaging-centre.github.io/up4/index.html).\n\n## Help and Support\n\nWe recommend you check out our [tutorials][5]. If your issue is not suitably\nresolved there, please check the [issues][6] page on our GitHub. Finally, if no\nsolution is available there, feel free to [open an issue][7]; the authors will\nattempt to respond as soon as possible.\n\n## Performance\n\nThe core of this library is implemented in [Rust](https://www.rust-lang.org/),\na modern systems language that natively boasts high performance and strong memory\n\u0026 thread safety. The [pyo3](https://github.com/PyO3/pyo3) Rust library is used to\nexport the Rust backend as a Python library, so Rust knowledge _is not_ a\nprerequisite for using `up4`. We deliberately chose a Rust-Python mix to ensure\nthat the computationally intensive parts are _fast but readable_ (rather than\nusing an arcane mix of Cython and Numba) whilst maintaining an easy to use\ninterface, which is where Python excels.\n\n## Contributing\n\nThe `up4` library is _not_ a one-man project; it is continually being worked on\ndirectly _and_ indirectly by a dedicated group of granular materials researchers\nwho are both tired of writing the _same_ Python boilerplate to analyse experiments\n_and_ waiting for said code to execute. If you are reading this, then it is likely\nthat you feel at least one of these frustrations too!\n\nIf you want to contribute to this project, there are many ways to help:\n\n- [Open an issue](https://github.com/uob-positron-imaging-centre/up4/issues/new)\n- Write a tutorial that fills in any gaps in the [`up4` documentation][8]\n  to help future users.\n- Share relevant algorithms/ functions that improve the post-processing process,\n  so that others can benefit. If these come from published work, then please add a\n  reference to this work in the code documentation.\n- Add your code directly to the repo and [open a pull request](https://github.com/uob-positron-imaging-centre/up4/compare).\n\n## Citing\n\nIf you use this library in your research, you are kindly asked to cite:\n\n\u003e [Paper after publication]\n\n## Licensing\n\nThe `up4` package is [GPL v3.0](https://choosealicense.com/licenses/gpl-3.0/)\nlicensed. In non-lawyer terms, the key points of this license are:\n\n- You can view, use, copy and modify this code _**freely**_.\n- Your modifications must _also_ be licensed with GPL v3.0 or later.\n- If you share your modifications with someone, you have to include the source\n  code as well.\n\nEssentially, do whatever you want with the code, but don't try selling it saying\nit's yours :). GPL v3.0 is indeed a very strong _copyleft_ license; it was\ndeliberately chosen to maintain the openness and transparency of great software\nand progress. This also ties into the very reason for `up4`'s conception - to\ntransparently process and compare Lagrangian data, regardless of source.\nFurther, open collaboration is frankly way more efficient than closed,\nfor-profit competition.\n\nPoincarePlotter\n\n### Project to-do list\n\n- [ ] HDF5 converter\n  - [x] VTK -\u003e HDF5\n  - [x] CSV -\u003e HDF5\n  - [ ] TXT -\u003e HDF5\n  - [ ] XLSX -\u003e HDF5\n- [ ] Plotting utilities\n  - [ ] Vector plots\n    - [x] 2D\n    - [ ] 3D\n  - [x] Heatmaps\n  - [x] Contour plots\n  - [ ] Slice plots\n  - [ ] Distributions\n  - [x] Parity plots\n  - [ ] Recipes for above plots\n- [ ] Vectorfield functions\n  - [x] Grid\n    - [ ] Euler grid\n    - [ ] Lagrange grid\n- [ ] Equipment specific functions (or recipes?)\n  - [ ] Rotating drum\n  - [ ] Mills\n  - [ ] Fluidised beds\n- [ ] Generic particle functions (see old upppp)\n  - [ ] Granular temperature distribution\n  - [x] Velocity distribution\n- [x] Documentation\n  - [x] Agree standards\n  - [x] Python\n    - [x] Configure Sphinx\n    - [x] Link rust docs (if possible)\n  - [x] Rust\n- [ ] DEM contact list functions\n  - [ ] Energy dissipated\n  - [ ] Collision modes\n\n## State of `up4`\n\n### Plotting\n\n- Rust\n  - Limited ability to easily customise plots compared to the Python API. This\n    is actively being worked on.\n- Python\n  - Export of created JSON strings to `Plotly.py` means that all tools\n    are available to edit plot layout.\n\n[1]: https://www.cfdem.com/liggghtsr-open-source-discrete-element-method-particle-simulation-code\n[2]: https://www.mercurydpm.org/\n[3]: https://cpfd-software.com/\n[4]: https://github.com/microsoft/pylance-release/issues/1942\n[5]: https://uob-positron-imaging-centre.github.io/up4/tutorials/index.html\n[6]: https://github.com/uob-positron-imaging-centre/up4/issues\n[7]: https://github.com/uob-positron-imaging-centre/up4/issues/new\n[8]: https://uob-positron-imaging-centre.github.io/up4/tutorials/index.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuob-positron-imaging-centre%2Fup4","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuob-positron-imaging-centre%2Fup4","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuob-positron-imaging-centre%2Fup4/lists"}