docs: LHE file writing examples (#256)

* File LHEFile members * Add LHEFile fieldnames * Add write and filter example * Fix tests * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * pre-commit fixes * Add lhe_file read tests * docs: Add writing example to README.md * Spelling in README.md * Update README.md Co-authored-by: Eduardo Rodrigues <[email protected]> * Deprecate write_lhe_file and write_lhe_string * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * chore: ruff adjustments * Cleanup write function --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Eduardo Rodrigues <[email protected]>
scikit-hep · Oct 18, 2024 · d4231f5 · d4231f5
1 parent 6f85efd
commit d4231f5
Show file tree

Hide file tree

Showing 6 changed files with 3,041 additions and 19 deletions.
diff --git a/README.md b/README.md
@@ -32,6 +32,8 @@ The visualization capabilities require the external dependency of [Graphviz](htt
 The example below provides a simple overview.
 Full functionality can be inspected from the functions provided in the `pylhe` module.
 
+### Reading
+
 ```python
 import itertools
 
@@ -59,6 +61,78 @@ event.graph.render(filename="test", format="png", cleanup=True)
 event.graph.render(filename="test", format="pdf", cleanup=True)
 ```
 
+### Writing
+
+For a full example see [write](examples/write_monte_carlo_example.ipynb) or [filter](examples/filter_events_example.ipynb).
+The values in the sketch below are intentionally left empty since they depend on the use-case.
+The data structure of `pylhe` is:
+
+```python
+import pylhe
+
+file=pylhe.LHEFile(
+    init=pylhe.LHEInit(
+        initInfo=pylhe.LHEInitInfo(
+            beamA=,
+            beamB=,
+            energyA=,
+            energyB=,
+            PDFgroupA=,
+            PDFgroupB=,
+            PDFsetA=,
+            PDFsetB=,
+            weightinStrategy=,
+            numProcesses=,
+        ),
+        procInfo=pylhe.LHEProcInfo(
+            xSection=,
+            error=,
+            unitWeight=,
+            procId=,
+        ),
+    ),
+    events=[
+        pylhe.LHEEvent(
+            eventinfo=pylhe.LHEEventInfo(
+                nparticles=,
+                pid=,
+                weight=,
+                scale=,
+                aqed=,
+                aqcd=,
+            ),
+            particles=[
+                pylhe.LHEParticle(
+                    id=,
+                    status=,
+                    mother1=,
+                    mother2=,
+                    color1=,
+                    color2=,
+                    px=,
+                    py=,
+                    pz=,
+                    e=,
+                    m=,
+                    lifetime=,
+                    spin=,
+                ),
+                ...
+            ],
+            weights=None,
+            attributes=None,
+            optional=None,
+        ),
+        ...
+    ]
+)
+
+# write to file, compressed if gz/gzip suffix
+write_lhe_file(file.init, file.events, "myevents.lhe.gz", rwgt=True, weights=False)
+
+```
+
+
 ## Citation
 
 The preferred BibTeX entry for citation of `pylhe` is