tutorial-reconstruction-algorithms/_episodes/06-working-with-podio.md

0001 ---
0002 title: "Working with PODIO"
0003 teaching: 5
0004 exercises: 1
0005 objectives:
0006 - "Gain familiarity working with PODIO collections"
0007 - "Understand PODIO subset collections"
0008 ---
0009
0010 ## Introduction to PODIO
0011
0012 Our data model is in a library/namespace/repository called `edm4eic`, and it is built on top of `edm4hep`, a data model designed to capture commonalities across HEP experiments. `edm4eic` is implemented using PODIO, which is a toolkit for generating the data model classes from a specification written in YAML. Here is a very simple example of a PODIO specification:
0013
0014 ```yaml
0015 options :
0016   # should getters / setters be prefixed with get / set?
0017   getSyntax: False
0018   # should POD members be exposed with getters/setters in classes that have them as members?
0019   exposePODMembers: True
0020   includeSubfolder: True
0021
0022 datatypes :
0023   ExampleHit :
0024     Description : "Hit"
0025     Author : "B. Hegner"
0026     Members:
0027       - unsigned long long cellID      // cellID
0028       - double x      // x-coordinate
0029       - double y      // y-coordinate
0030       - double z      // z-coordinate
0031       - double energy // measured energy deposit
0032
0033   ExampleCluster :
0034     Description : "Cluster"
0035     Author : "N. Brei"
0036     Members:
0037       - double energy // cluster energy
0038     OneToManyRelations:
0039       - ExampleHit Hits // hits contained in the cluster
0040       - ExampleCluster Clusters // sub clusters used to create this cluster
0041 ```
0042
0043 PODIO will then generate for us the following classes:
0044 ```
0045 DatamodelDefinition.h ExampleCluster.h ExampleClusterCollection.h ExampleClusterCollectionData.h ExampleClusterData.h ExampleClusterObj.h ExampleHit.h ExampleHitCollection.h ExampleHitCollectionData.h ExampleHitData.h ExampleHitObj.h MutableExampleHit.h MutableExampleCluster.h
0046 ```
0047
0048 As you can see, PODIO has a lot of moving pieces. Why?
0049
0050 1. PODIO adds a separate layer for managing memory in a way which is more consistent with Python and other garbage-collected languages. The user only has to work with values, no explicit allocations or deletions.
0051 2. PODIO separates the data's memory layout from its accessors
0052 3. PODIO enforces immutability directly in the object model
0053 4. PODIO has sophisticated (though fragile!) mechanisms for tracking object references
0054
0055 These design principles in principle should eliminate entire classes of bugs. However, there are still subtleties when using PODIO that can lead to leaks, crashes, or corrupted references. Luckily, the correct usage pattern is quite simple, as we will discuss next.
0056
0057
0058 ## Working with PODIO objects, collections, and subset collections:
0059
0060
0061 ```c++
0062 auto hits = std::make_unique<ExampleHitCollection>();
0063
0064 hits->push_back(ExampleHit(22, 0.0, 0.0, 0.0, 0.001));
0065
0066 MutableExampleHit hit;
0067 hit.x(0.0);
0068 hit.energy(0.001);
0069 // ...
0070 hits->push_back(hit);
0071
0072 MutableExampleCluster cluster;
0073 cluster.addHits(hit);
0074
0075 // Safety tip: Add object to a collection BEFORE creating an association to it
0076
0077 auto clusters = std::make_unique<ExampleClusterCollection>();
0078 clusters->push_back(cluster);
0079
0080 auto subset_clusters = std::make_unique<ExampleClusterCollection>();
0081 subset_clusters->setSubsetCollection(true);
0082 subset_clusters->push_back(cluster);
0083
0084 // Safety tip: Every PODIO object is owned by exactly one collection.
0085 // If you want to put the object in other collections, those collections need to
0086 // be designated as "subset collections", which means that they don't own their contents.
0087 ```
0088
0089
0090 Note that when you write a factory, its inputs will be `const ExampleHitCollection*`, which are *immmutable*.
0091 Its output will be `std::unique_ptr<ExampleHitCollection>`, which is still mutable but will transfer its ownership to JANA2. JANA2 will add the collection to a podio `Frame`. From that point on, the collection is immutable and owned by the `Frame`.
0092
0093 JANA2 will create and destroy `Frame`s internally.
0094
0095
0096 > Exercise:
0097 > - Have your algorithm produce some (fake) output data!
0098 {: .challenge}