Warning about Decfiles and how to avoid common pitfalls

second-analysis-steps/simulation-advanced-dkfiles.md

@@ -79,6 +79,60 @@ CDecay MyD_s-
 ```
 Note that the fractions will always be renormalised to sum to 1 - you can directly use PDG branching fractions without having to rescale by hand.
 
+## A Warning about intermediate state cocktails with forced final states 
+
+*Be careful!* - if you are simulating a cocktail of intermediate states and forcing a decay to one or more final states, you may need to correct the branching fractions of all the intermediate decays as well. For example, if studying inclusive decays for some ``Xc0 -> D0X`` or ``Xc0 -> D+X`` with intermediate ``D*+`` and ``D*0`` states:
+
+If ``Xc0`` decays to ``D*0 pi0`` and ``D*+ pi-`` with equal probability and you are interested in the ``D0`` final state, to have a decfile such as:
+
+```
+Decay MyXc0
+ 0.5000 MyD*0 pi0  PHOTOS  <MODEL>;
+ 0.5000 MyD*+ pi-  PHOTOS  <MODEL>;
+Enddecay
+CDecay MyAntiXc0
+#
+Decay MyD*+
+ 0.677 D0 pi+  PHOTOS  VSS;
+Enddecay
+CDecay MyD*-
+#
+Decay MyD*0
+ 0.647   D0 pi0    PHOTOS  VSS;
+ 0.353   D0 gamma  PHOTOS  VSP_PWAVE;
+ 0.00391 D0 e+ e-  PHOTOS  PHSP;
+Enddecay
+CDecay MyAntiD*0
+```
+
+would result in a sample where an equal number of ``D0`` are coming from intermediate ``D*+`` as ``D*0``, even though the branching fraction for the former is only 67.7% - thus the ``D0 pi+ pi-`` final state would be overrepresented in the sample. 
+
+This is to say that the fact that EvtGen normalizes all branching fractions for a decay to 1 matters for cocktails with multiple intermediate final states decaying to a forced final state! The proper handling would instead be:
+
+```
+Decay MyXc0
+ 0.5000 MyD*0 pi0  PHOTOS  <MODEL>;
+ 0.3385 MyD*+ pi-  PHOTOS  <MODEL>;
+Enddecay
+CDecay MyAntiXc0
+#
+Decay MyD*+
+ 0.677 D0 pi+  PHOTOS  VSS;
+Enddecay
+CDecay MyD*-
+#
+Decay MyD*0
+ 0.647   D0 pi0    PHOTOS  VSS;
+ 0.353   D0 gamma  PHOTOS  VSP_PWAVE;
+ 0.00391 D0 e+ e-  PHOTOS  PHSP;
+Enddecay
+CDecay MyAntiD*0
+```
+
+If you have multiple generations of intermediate cocktail states, the forced final state decay needs to be back-propagated through each generation in this manner.
+
+It is important to be careful about this even when using **pre-existing** decfiles and always check them for consistency, as even many decfiles within the database do not take this important factor into account.
+
 ## Final state radiation
 After generating the decay, final state radiation is added using PHOTOS. Note that PHOTOS is enabled by default, even though many decfiles explicitly specify it. It needs to be explicitly removed via "noPhotos"
 

second-analysis-steps/simulation-dkfiles.md

@@ -60,3 +60,9 @@ The "Cuts" field specifies which one of a predetermined set of cut tools are use
 The bottom part of the decay file specifies the decay itself:
 This DecFile defines a signal `D*+` which decays 100% to `D0` `pi+`, and the D0 in turn decays 100% into `K+`, `K-`, `mu+` and `mu-`. Important is the definition of "MyD0". If the decay was to "D0" rather than "MyD0", the D0 would decay via all of the decay modes implemented in DECAY.DEC.
 The final part of each decay is the actual physics model used - in this case "VSS", the generic matrix element for vector to scaler-scaler transitions, and "PHSP", which is phase space only (matrix element = constant). Note that with PHSP, the decay products are completely unpolarized - for anything other than (spin0) to (spin0 spin0) this will get the angular momentum wrong!
+
+{% callout "Double Check Pre-Existing Decay Files!" %}
+
+When using pre-existing decay files, it is important to check them closely for consistency first. Many Decay files are created for a specific physics use case, and some may even get physics wrong when it comes to e.g. the relative branching fractions of intermediate states in a cocktail with a forced final state.
+
+{% endcallout %}