{"id":18009504,"url":"https://github.com/glouppe/recnn","last_synced_at":"2025-09-22T15:30:44.165Z","repository":{"id":68828936,"uuid":"68205285","full_name":"glouppe/recnn","owner":"glouppe","description":"Repository for the code of \"QCD-Aware Recursive Neural Networks for Jet Physics\"","archived":false,"fork":false,"pushed_at":"2019-09-17T14:02:08.000Z","size":7257,"stargazers_count":46,"open_issues_count":1,"forks_count":17,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-07T16:21:09.854Z","etag":null,"topics":["deep-learning","jet-clustering","machine-learning","particle-physics"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/glouppe.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}},"created_at":"2016-09-14T12:41:12.000Z","updated_at":"2025-01-20T16:54:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"8382d167-45d9-43d3-807c-5e226c3269cb","html_url":"https://github.com/glouppe/recnn","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/glouppe/recnn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glouppe%2Frecnn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glouppe%2Frecnn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glouppe%2Frecnn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glouppe%2Frecnn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/glouppe","download_url":"https://codeload.github.com/glouppe/recnn/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glouppe%2Frecnn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276430825,"owners_count":25641121,"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-09-22T02:00:08.972Z","response_time":79,"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":["deep-learning","jet-clustering","machine-learning","particle-physics"],"created_at":"2024-10-30T02:09:37.666Z","updated_at":"2025-09-22T15:30:43.756Z","avatar_url":"https://github.com/glouppe.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# QCD-Aware Recursive Neural Networks for Jet Physics\nhttps://arxiv.org/abs/1702.00748\n\n* Gilles Louppe\n* Kyunghyun Cho\n* Cyril Becot\n* Kyle Cranmer\n\nRecent progress in applying machine learning for jet physics has been built upon an analogy between calorimeters and images. In this work, we present a novel class of recursive neural networks built instead upon an analogy between QCD and natural languages. In the analogy, four-momenta are like words and the clustering history of sequential recombination jet algorithms is like the parsing of a sentence. Our approach works directly with the four-momenta of a variable-length set of particles, and the jet-based tree structure varies on an event-by-event basis. Our experiments highlight the flexibility of our method for building task-specific jet embeddings and show that recursive architectures are significantly more accurate and data efficient than previous image-based networks. We extend the analogy from individual jets (sentences) to full events (paragraphs), and show for the first time an event-level classifier operating on all the stable particles produced in an LHC event.\n\n---\n\nPlease cite using the following BibTex entry:\n\n```\n@article{louppe2017qcdrecnn,\n           author = {{Louppe}, G. and {Cho}, K. and {Becot}, C and {Cranmer}, K.},\n            title = \"{QCD-Aware Recursive Neural Networks for Jet Physics}\",\n          journal = {ArXiv e-prints},\n    archivePrefix = \"arXiv\",\n           eprint = {1702.00748},\n     primaryClass = \"hep-th\",\n             year = 2017,\n            month = feb,\n}\n```\n\n---\n\n## Instructions\n\n### Requirements\n\n- python 2.7\n- [autograd](https://github.com/HIPS/autograd/tree/master/autograd)\n- scikit-learn\n- click\n\n### Data\n\n(mirror to be released)\n\n### Usage\n\nClassification of W vs QCD jets:\n\n```\n# Training\npython train.py data/w-vs-qcd/final/antikt-kt-train.pickle model.pickle\n\n# Test\n# see notebooks/04-jet-study.ipynb\n```\n\nClassification of full events:\n\n```\n# Training\npython train_event.py data/events/antikt-kt-train.pickle model.pickle\n\n# Test\npython test_event.py data/events/antikt-kt-train.pickle data/events/antikt-kt-test.pickle model.pickle 100000 100000 predictions.pickle\n# see also notebooks/04-event-study.ipynb\n```\n\n### Rebuilding the data\n\nAdditional requirements:\n\n- [fastjet](http://fastjet.fr/)\n- cython\n- rootpy\n- h5py\n\nBuilding W vs QCD jet data:\n1. Load data from h5 files. Execute cells 1-3 from `notebooks/01-load-w-vs-qcd.ipynb`. Adapt cell 3 as necessary.\n2. Split the data into train and test. Execute cells 1-3 from `notebooks/02-split-train-test.ipynb`. Adapt cell 3 as necessary.\n3. Preprocess the data. Execute cells 1-6 from `notebooks/03-preprocessing.ipynb`.\nAdapt cell 6 as necessary. Run one of the following cells depending on the desired topology.\n4. (Optional) Repack the train and test using the last cell of `notebooks/03-preprocessing.ipynb`. This is necessary for historical reasons to exactly reproduce the paper data.\n\nBuilding full event data:\n1. Load data from pickle files. Execute cells 1-2, 4-7. Adapt cell 7 as necessary.\n2. Split the data into train and test. Execute cells 1-2 and the last of `notebooks/02-split-train-test.ipynb`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglouppe%2Frecnn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglouppe%2Frecnn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglouppe%2Frecnn/lists"}