### Install decaylanguage from PyPI

Source: https://decaylanguage.readthedocs.io/en/latest/getting_started/installation.html

Use this command to install the decaylanguage package from the Python Package Index.

```bash
pip install decaylanguage

```

--------------------------------

### Install DecayLanguage with Modeling Submodule

Source: https://decaylanguage.readthedocs.io/en/latest/index.html

Install DecayLanguage along with extra dependencies for the modeling submodule, including NumPy, pandas, and plumbum.

```bash
pip install "decaylanguage[modeling]"

```

--------------------------------

### Example .dec Decay File

Source: https://decaylanguage.readthedocs.io/en/latest/examples/notebooks/ExampleDecFileParsingWithLark.html

This is an example of a .dec file format used to define particle decays and their properties. It includes definitions for various particles and their decay modes.

```plaintext
Decay D*+
  0.677             D0 pi+       VSS;
  0.307             D+ pi0       VSS;
  0.016             D+ gamma     VSP_PWAVE;
Enddecay

Decay D*-
0.6770    anti-D0  pi-                VSS;
0.3070    D-       pi0                VSS;
0.0160    D-       gamma              VSP_PWAVE;
Enddecay

Decay D0
1.0   K-      pi+                  PHSP;
Enddecay

Decay D+
1.0   K-   pi+   pi+   pi0    PHSP;
Enddecay

Decay pi0
0.988228297   gamma   gamma                   PHSP;
0.011738247   e+      e-      gamma           PI0_DALITZ;
0.000033392   e+      e+      e-      e-      PHSP;
0.000000065   e+      e-                      PHSP;
Enddecay

```

--------------------------------

### DecayChain Class Initialization

Source: https://decaylanguage.readthedocs.io/en/latest/_modules/decaylanguage/decay/decay.html

Example of constructing a DecayChain object with a mother particle and its associated decay modes.

```python
dm1 = DecayMode(0.0124, 'K_S0 pi0', model='PHSP')
dm2 = DecayMode(0.692, 'pi+ pi-')
dm3 = DecayMode(0.98823, 'gamma gamma')
dc = DecayChain('D0', {'D0':dm1, 'K_S0':dm2, 'pi0':dm3})
```

--------------------------------

### Get Definitions

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Retrieves all general definitions from a parsed file. Use for accessing NAME=VALUE definitions.

```python
decaylanguage.dec.dec.get_definitions(_parsed_file_)
```

--------------------------------

### Get Dictionary of Definitions

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Return a dictionary of all 'Define' statements from the parsed file, mapping names to their float values.

```python
>>> dfp.dict_definitions()
```

--------------------------------

### Get Pythia Definitions

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Retrieves all Pythia 8 commands defined in the input file, categorized by their application (generic, alias, or both).

```python
dict_pythia_definitions()
```

--------------------------------

### Charge Conjugate Replacement Example

Source: https://decaylanguage.readthedocs.io/en/latest/_modules/decaylanguage/dec/dec.html

Demonstrates how to use the ChargeConjugateReplacement visitor to transform a decay tree by replacing particles with their charge conjugates. This is useful for ensuring symmetry in decay definitions.

```python
>>> from lark import Tree, Token
>>> t = Tree('decay', [Tree('particle', [Token('LABEL', 'D0')]), Tree('decayline', [Tree('value', [Token('SIGNED_NUMBER', '1.0')]), Tree('particle', [Token('LABEL', 'K-')]), Tree('particle', [Token('LABEL', 'pi+')]), Tree('model', [Token('MODEL_NAME', 'PHSP')])])])
>>> ChargeConjugateReplacement().visit(t)    # doctest: +NORMALIZE_WHITESPACE
Tree('decay', [Tree('particle', [Token('LABEL', 'anti-D0')]),
Tree('decayline', [Tree('value', [Token('SIGNED_NUMBER', '1.0')]),
Tree('particle', [Token('LABEL', 'K+')]),
Tree('particle', [Token('LABEL', 'pi-')]),
Tree('model', [Token('MODEL_NAME', 'PHSP')])])])
```

--------------------------------

### Simple Decay Chain Example

Source: https://decaylanguage.readthedocs.io/en/latest/_modules/decaylanguage/decay/decay.html

Illustrates a basic decay chain with no sub-decays. The output shows how a decay mode dictionary is transformed into a list of simple decay descriptor strings.

```json
{
    "anti-D0": [
        "anti-D0 -> K+ pi-"
    ]
}
```

--------------------------------

### Example .dec Decay File Content

Source: https://decaylanguage.readthedocs.io/en/latest/examples/notebooks/ExampleDecFileParsingWithLark.html

This snippet shows the typical format of a .dec file, defining particle decays and their branching ratios.

```plaintext
D*+
       0.677 : D0  pi+
       0.307 : D+  pi0
       0.016 : D+  gamma                                          VSP_PWAVE
D*-
       0.677 : anti-D0  pi-
       0.307 : D-  pi0
       0.016 : D-  gamma                                          VSP_PWAVE
D0
           1 : K-  pi+
           1 : K-  pi+
D+
           1 : K-  pi+  pi+  pi0                                  PHSP
pi0
    0.988228 : gamma  gamma
   0.0117382 : e+  e-  gamma                                      PI0_DALITZ
  3.3392e-05 : e+  e+  e-  e-
     6.5e-08 : e+  e-

```

--------------------------------

### Get Lineshape Settings

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Retrieves all lineshape settings for particles, including shape names and parameters like Blatt-Weisskopf, mass range, and inclusion factors.

```python
dict_lineshape_settings()
```

--------------------------------

### Get Final State Particles

Source: https://decaylanguage.readthedocs.io/en/latest/_modules/decaylanguage/dec/dec.html

Retrieves a list of Lark Tree objects representing the final-state particles from a 'decayline' Tree. Includes an example illustrating its usage with a sample decay definition.

```python
def get_final_state_particles(decay_mode: Tree) -> list[Tree]:
    """
    Return a list of Lark Tree instances describing the final-state particles
    for the decay mode defined in the input Tree of name 'decayline'.

    Parameters
    ----------
    decay_mode: Lark Tree instance
        Input Tree satisfying Tree.data=='decayline'.

    Examples
    --------
    For a decay:: 

        Decay MyB_s0
            1.000     K+     K-     SSD_CP 20.e12 0.1 1.0 0.04 9.6 -0.8 8.4 -0.6;
        Enddecay

    the list
    ``[Tree(particle, [Token(LABEL, 'K+')]), Tree(particle, [Token(LABEL, 'K-')])]``
    will be returned.
    """
    if decay_mode.data != "decayline":
        raise RuntimeError("Input not an instance of a 'decayline' Tree!")

    # list of Trees of final-state particles
    return list(decay_mode.find_data("particle"))
```

--------------------------------

### Initialize DaughtersDict from various inputs

Source: https://decaylanguage.readthedocs.io/en/latest/_modules/decaylanguage/decay/decay.html

Demonstrates how to create a DaughtersDict object using different input formats: an empty dictionary, a dictionary with counts, a list of particle names, a string representation, or a mixed constructor.

```python
>>> # An empty final state
>>> dd = DaughtersDict()

>>> # Constructor from a dictionary
>>> dd = DaughtersDict({'K+': 1, 'K-': 2, 'pi+': 1, 'pi0': 3})

>>> # Constructor from a list of particle names
>>> dd = DaughtersDict(['K+', 'K-', 'K-', 'pi+', 'pi0'])

>>> # Constructor from a string representing the final state
>>> dd = DaughtersDict('K+ K- pi0')

>>> # "Mixed" constructor
>>> dd = DaughtersDict('K+ K-', pi0=1, gamma=2)
```

--------------------------------

### Define Spin Factors for D0 Decay (Line 4)

Source: https://decaylanguage.readthedocs.io/en/latest/examples/notebooks/DecayLanguageDemo.html

Defines spin factors for a D0 decay channel, using a 'P' type spin factor and different particle assignments than previous examples. Used in amplitude analysis setup.

```cpp
    spin_factor_list.push_back(std::vector<SpinFactor*>({
        new SpinFactor("SF", SF_4Body::DtoV1V2_V1toP1P2_V2toP3P4_P          , 2, 3, 0, 1),
        new SpinFactor("SF", SF_4Body::FF_12_34_L1                          , 2, 3, 0, 1),
        new SpinFactor("SF", SF_4Body::DtoV1V2_V1toP1P2_V2toP3P4_P          , 0, 1, 2, 3),
        new SpinFactor("SF", SF_4Body::FF_12_34_L1                          , 0, 1, 2, 3)
    }));
```

--------------------------------

### Load and Initialize DecFileParser

Source: https://decaylanguage.readthedocs.io/en/latest/examples/notebooks/DecayLanguageDemo.html

Initializes the DecFileParser with a large DecFile. This step prepares the parser for reading decay data.

```python
from decaylanguage import data

parser = DecFileParser(data.basepath / "DECAY_LHCB.DEC")
parser
```

--------------------------------

### Initialize and Parse DecFileParser

Source: https://decaylanguage.readthedocs.io/en/latest/examples/decfile_parsing.html

Instantiate DecFileParser with a decay file path and parse it. Imports required: DecFileParser, basepath.

```python
from decaylanguage import DecFileParser
from decaylanguage.data import basepath

# Parse the bundled LHCb decay file
parser = DecFileParser(basepath / "DECAY_LHCB.DEC")
parser.parse()
```

--------------------------------

### Parse and Build Decay Chains

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Demonstrates parsing a decay file and building decay chains for a specified particle. It also shows how to specify stable particles to simplify the output.

```python
>>> parser = DecFileParser('a-Dplus-decay-file.dec')
>>> parser.parse()
>>> parser.build_decay_chains('D+')
{'D+': [{'bf': 1.0,
   'fs': ['K-',
    'pi+',
    'pi+',
    {'pi0': [{'bf': 0.988228297,
       'fs': ['gamma', 'gamma'],
       'model': 'PHSP',
       'model_params': ''},
      {'bf': 0.011738247,
       'fs': ['e+', 'e-', 'gamma'],
       'model': 'PI0_DALITZ',
       'model_params': ''},
      {'bf': 3.3392e-05,
      'fs': ['e+', 'e+', 'e-', 'e-'],
      'model': 'PHSP',
      'model_params': ''},
      {'bf': 6.5e-08, 'fs': ['e+', 'e-'], 'model': 'PHSP', 'model_params': ''}]}],
   'model': 'PHSP',
   'model_params': ''}]}
>>> p.build_decay_chains('D+', stable_particles=['pi0'])
{'D+': [{'bf': 1.0, 'fs': ['K-', 'pi+', 'pi+', 'pi0'], 'model': 'PHSP', 'model_params': ''}]}
```

--------------------------------

### Get Pythia Definitions

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Extracts Pythia 8 parameter definitions. Use to get Pythia settings for generic, alias, or both types of decays.

```python
decaylanguage.dec.dec.get_pythia_definitions(_parsed_file_)
```

--------------------------------

### Get Decays to Copy Statements

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Extracts statements defining decays to be copied. Use to get a mapping of decay names to the decays they should copy.

```python
decaylanguage.dec.dec.get_decays2copy_statements(_parsed_file_)
```

--------------------------------

### Instantiate and Parse DecFileParser

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Instantiate the DecFileParser with a decay file path and then call the parse method. Ensure the .dec file exists at the specified path.

```python
>>> dfp = DecFileParser('my-decay-file.dec')
>>> dfp.parse()
```

--------------------------------

### DecayChain.bf

Source: https://decaylanguage.readthedocs.io/en/latest/api/decay.html

Gets the branching fraction of the top-level decay.

```APIDOC
## DecayChain.bf

### Description
Branching fraction of the top-level decay.

### Method
Property

### Parameters
None

### Response
#### Success Response (200)
- **float** - The branching fraction.

### Response Example
```json
{
  "example": 0.6770
}
```
```

--------------------------------

### Create Amplitude with FOCUS (I32) and kMatrix (prod.0)

Source: https://decaylanguage.readthedocs.io/en/latest/examples/notebooks/AmpGen2GooFit_D2K3p.html

Constructs an Amplitude object for D0 decay, utilizing FOCUS lineshape with I32 mode and kMatrix with prod.0 parameterization for KPi00 and PiPi00 resonances.

```cpp
amplitudes_list.push_back(new Amplitude{
        "D0{KPi00[FOCUS.I32]{K-,pi+},PiPi0[kMatrix.prod.0]{pi+,pi-}}",
        mkvar("D0{KPi00[FOCUS.I32]{K-,pi+},PiPi0[kMatrix.prod.0]{pi+,pi-}}_r", true, 1.0, 0.0),
        mkvar("D0{KPi00[FOCUS.I32]{K-,pi+},PiPi0[kMatrix.prod.0]{pi+,pi-}}_i", true, 0.0, 0.0),
        line_factor_list.back(),
        spin_factor_list.back(),
        2});

    DK3P_DI.amplitudes_B.push_back(amplitudes_list.back());
```

--------------------------------

### Get Aliases

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Retrieves all alias definitions from a parsed file. Use for simple NAME=ALIAS mappings.

```python
decaylanguage.dec.dec.get_aliases(_parsed_file_)
```

--------------------------------

### Initialize DecayMode

Source: https://decaylanguage.readthedocs.io/en/latest/_modules/decaylanguage/decay/decay.html

Demonstrates various ways to initialize a DecayMode object, from empty to specifying branching fraction, daughters, and metadata.

```python
>>> # A 'default' and hence empty, decay mode
>>> dm = DecayMode()

>>> # Decay mode with minimal input information
>>> dd = DaughtersDict('K+ K-')
>>> dm = DecayMode(0.5, dd)

>>> # Decay mode with minimal input information, simpler version
>>> dm = DecayMode(0.5, 'K+ K-')

>>> # Decay mode with decay model information
>>> dd = DaughtersDict('pi- pi0 nu_tau')
>>> dm = DecayMode(0.2551, dd,
...                model='TAUHADNU',
...                model_params=[-0.108, 0.775, 0.149, 1.364, 0.400])

>>> # Decay mode with user metadata
>>> dd = DaughtersDict('K+ K-')
>>> dm = DecayMode(0.5, dd, model='PHSP', study='toy', year=2019)
```

--------------------------------

### Get LineshapePW Definitions

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Retrieves definitions for SetLineshapePW, which specify a value for a mother-daughter particle combination.

```python
list_lineshapePW_definitions()
```

--------------------------------

### Get Jetset Definitions

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Retrieves all JETSET parameters defined in the input file, organized by module.

```python
dict_jetset_definitions()
```

--------------------------------

### Construct DecayMode with Metadata

Source: https://decaylanguage.readthedocs.io/en/latest/_modules/decaylanguage/decay/decay.html

Demonstrates creating a DecayMode instance with custom metadata, such as generator-specific information like zfit configurations.

```python
>>> # Decay mode with metadata for generators such as zfit's phasespace
>>> dm = DecayMode(0.5, "K+ K-", zfit={"B0": "gauss"})
>>> dm.metadata['zfit'] == {'B0': 'gauss'}
True
```

--------------------------------

### Get Value from Parser - DecayLanguage

Source: https://decaylanguage.readthedocs.io/en/latest/api/modeling.html

Retrieves a specific key's value from a parser object.

```python
decaylanguage.modeling.ampgentransform.get_from_parser(_parser_ , _key_)[source]#
     
```

--------------------------------

### Get Charge Conjugate Definitions

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Returns a dictionary of all charge conjugate definitions, mapping particles to their conjugates.

```python
dict_charge_conjugates()
```

--------------------------------

### Create Amplitude with FOCUS (I32) and kMatrix (pole.1)

Source: https://decaylanguage.readthedocs.io/en/latest/examples/notebooks/AmpGen2GooFit_D2K3p.html

Constructs an Amplitude object for D0 decay, utilizing FOCUS lineshape with I32 mode and kMatrix with pole.1 parameterization for KPi00 and PiPi00 resonances.

```cpp
amplitudes_list.push_back(new Amplitude{
        "D0{KPi00[FOCUS.I32]{K-,pi+},PiPi0[kMatrix.pole.1]{pi+,pi-}}",
        mkvar("D0{KPi00[FOCUS.I32]{K-,pi+},PiPi0[kMatrix.pole.1]{pi+,pi-}}_r", true, 1.0, 0.0),
        mkvar("D0{KPi00[FOCUS.I32]{K-,pi+},PiPi0[kMatrix.pole.1]{pi+,pi-}}_i", true, 0.0, 0.0),
        line_factor_list.back(),
        spin_factor_list.back(),
        2});

    DK3P_DI.amplitudes_B.push_back(amplitudes_list.back());
```

--------------------------------

### Get Amplitude Chain Properties - DecayLanguage

Source: https://decaylanguage.readthedocs.io/en/latest/api/modeling.html

Properties to access the full amplitude and the range of angular momentum.

```python
property ls_enum#
     

property full_amp#
     

L_range(_conserveParity =False_)[source]#
     

property L#
     
```

--------------------------------

### Print GooFit Parameters

Source: https://decaylanguage.readthedocs.io/en/latest/examples/notebooks/AmpGen2GooFit_D2K3p.html

Prints the parameters used in the GooFit analysis, including initial values for various interference terms and masses. This is essential for understanding the model's parameter space.

```cpp
colors.green.print("    // Parameters")
print(GooFitChain.make_pars())
```

```cpp
// Parameters
    Variable D0_radius {"D0_radius", 0.0037559 };
    Variable IS_p1_4pi {"IS_p1_4pi", 0.0 };
    Variable IS_p1_EtaEta {"IS_p1_EtaEta", -0.39899 };
    Variable IS_p1_EtapEta {"IS_p1_EtapEta", -0.34639 };
    Variable IS_p1_KK {"IS_p1_KK", -0.55377 };
    Variable IS_p1_mass {"IS_p1_mass", 0.651 };
    Variable IS_p1_pipi {"IS_p1_pipi", 0.22889 };
    Variable IS_p2_4pi {"IS_p2_4pi", 0.0 };
    Variable IS_p2_EtaEta {"IS_p2_EtaEta", 0.39065 };
    Variable IS_p2_EtapEta {"IS_p2_EtapEta", 0.31503 };
    Variable IS_p2_KK {"IS_p2_KK", 0.55095 };
    Variable IS_p2_mass {"IS_p2_mass", 1.2036 };
    Variable IS_p2_pipi {"IS_p2_pipi", 0.94128 };
    Variable IS_p3_4pi {"IS_p3_4pi", 0.55639 };
    Variable IS_p3_EtaEta {"IS_p3_EtaEta", 0.1834 };
    Variable IS_p3_EtapEta {"IS_p3_EtapEta", 0.18681 };
    Variable IS_p3_KK {"IS_p3_KK", 0.23888 };
    Variable IS_p3_mass {"IS_p3_mass", 1.55817 };
    Variable IS_p3_pipi {"IS_p3_pipi", 0.36856 };
    Variable IS_p4_4pi {"IS_p4_4pi", 0.85679 };
    Variable IS_p4_EtaEta {"IS_p4_EtaEta", 0.19906 };
```

--------------------------------

### Get Aliases

Source: https://decaylanguage.readthedocs.io/en/latest/_modules/decaylanguage/dec/dec.html

Extracts 'Alias' statements from a parsed file, returning a dictionary of names and their corresponding alias strings.

```python
def get_aliases(parsed_file: Tree) -> dict[str, str]:
    """
    Return a dictionary of all aliases in the input parsed file, of the form
    "Alias <NAME> <ALIAS>", as {'NAME1': ALIAS1, 'NAME2': ALIAS2, ...}.

    Parameters
    ----------
    parsed_file: Lark Tree instance
        Input parsed file.
    """
    return _extract_two_token_dict(parsed_file, "alias")

```

--------------------------------

### Import necessary libraries for AmpGen to GooFit conversion

Source: https://decaylanguage.readthedocs.io/en/latest/examples/notebooks/AmpGen2GooFit_D2K3p.html

Imports `SpinType` from the `particle` library and `GooFitChain`, `SF_4Body` from `decaylanguage.modeling.goofit`. These are essential for defining and manipulating decay chains and amplitude models.

```python
from __future__ import annotations

from particle import SpinType

from decaylanguage.modeling.goofit import GooFitChain, SF_4Body
```

--------------------------------

### Get JETSET Definitions

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Retrieves JETSET parameter definitions. Use to access JETSET module and parameter settings.

```python
decaylanguage.dec.dec.get_jetset_definitions(_parsed_file_)
```

--------------------------------

### Instantiating a Graphviz Digraph with Defaults

Source: https://decaylanguage.readthedocs.io/en/latest/_modules/decaylanguage/decay/viewer.html

Create a new graphviz.Digraph instance, applying default attributes for the graph, nodes, and edges. User-provided attributes can override these defaults.

```python
graph_attr = self._get_graph_defaults()
node_attr = self._get_node_defaults()
edge_attr = self._get_edge_defaults()
for key, attr in (
    ("graph_attr", graph_attr),
    ("node_attr", node_attr),
    ("edge_attr", edge_attr),
):
    if key in attrs:
        attr.update(**attrs.pop(key))

arguments = self._get_default_arguments()
arguments.update(**attrs)  # type: ignore[call-overload]

return graphviz.Digraph(
    graph_attr=graph_attr, node_attr=node_attr, edge_attr=edge_attr, **arguments
)
```

--------------------------------

### Get Decay Mother Names

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Returns a list of all mother particle names present in the parsed decay file.

```python
list_decay_mother_names()
```

--------------------------------

### Instantiate DecayChainViewer

Source: https://decaylanguage.readthedocs.io/en/latest/_modules/decaylanguage/decay/viewer.html

Instantiate the DecayChainViewer with a decay chain. The decay chain can be provided as a dictionary or a DecayChain object. Optionally, display effective branching fractions by setting show_effective_bf to True.

```python
dfp = DecFileParser('my-Dst-decay-file.dec')    # doctest: +SKIP
dfp.parse()    # doctest: +SKIP
chain = dfp.build_decay_chains('D*+')    # doctest: +SKIP
dcv = DecayChainViewer(chain)    # doctest: +SKIP
# display the SVG figure in a notebook
dcv    # doctest: +SKIP
```

--------------------------------

### Charge Conjugate Replacement Initialization

Source: https://decaylanguage.readthedocs.io/en/latest/_modules/decaylanguage/dec/dec.html

Shows the initialization of the ChargeConjugateReplacement class, highlighting how user-provided charge conjugate definitions are handled.

```python
def __init__(self, charge_conj_defs: dict[str, str] | None = None) -> None:
    # Copy the user-provided dict, since it is used internally as a cache.
    # Mutating the caller's dict would silently pollute it.
    self.charge_conj_defs = dict(charge_conj_defs) if charge_conj_defs else {}
```

--------------------------------

### Get Number of Decays

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Returns the total count of particle decays defined within the parsed .dec file.

```python
number_of_decays
```

--------------------------------

### Construct DecayMode from Dictionary

Source: https://decaylanguage.readthedocs.io/en/latest/_modules/decaylanguage/decay/decay.html

Shows how to initialize a DecayMode object from a dictionary, including mandatory 'bf' and 'fs' keys, and optional model/metadata.

```python
>>> # Simplest construction
>>> DecayMode.from_dict({'bf': 0.98823, 'fs': ['gamma', 'gamma']})
<DecayMode: daughters=gamma gamma, BF=0.98823>
```

```python
>>> # Decay mode with decay model details
>>> DecayMode.from_dict({'bf': 0.98823,
...                      'fs': ['gamma', 'gamma'],
...                      'model': 'PHSP',
...                      'model_params': ''})
<DecayMode: daughters=gamma gamma, BF=0.98823>
```

```python
>>> # Decay mode with metadata for generators such as zfit's phasespace
>>> dm = DecayMode.from_dict({'bf': 0.5, 'fs': ["K+, K-"], "zfit": {"B0": "gauss"}})
>>> dm.metadata
{'model': '', 'model_params': '', 'zfit': {'B0': 'gauss'}}
```

--------------------------------

### Get Dictionary of Aliases

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Return a dictionary of all 'Alias' definitions from the parsed file, mapping names to their aliased values.

```python
>>> dfp.dict_aliases()
```

--------------------------------

### Convert AmpGen to GooFit (Command Line)

Source: https://decaylanguage.readthedocs.io/en/latest/examples/amplitude_models.html

Use this command-line tool to convert an AmpGen model file to GooFit format. The output can be directly piped to a file.

```bash
python -m decaylanguage.goofit models/DtoKpipipi_v2.txt
```

```bash
python -m decaylanguage.goofit models/DtoKpipipi_v2.txt > output.cu
```

--------------------------------

### Get Branching Fraction

Source: https://decaylanguage.readthedocs.io/en/latest/_modules/decaylanguage/dec/dec.html

Extracts the branching fraction as a float from a 'decayline' Tree object. It handles potential errors during conversion.

```python
def get_branching_fraction(decay_mode: Tree) -> float:
    """
    Return the branching fraction (float) for the decay mode defined
    in the input Tree of name 'decayline'.

    Parameters
    ----------
    decay_mode: Lark Tree instance
        Input Tree satisfying Tree.data=='decayline'.
    """
    if decay_mode.data != "decayline":
        raise RuntimeError("Check your input, not an instance of a 'decayline' Tree!")

    # For a 'decayline' Tree, Tree.children[0] is the branching fraction Tree
    # and tree.children[0].children[0].value is the BF stored as a str
    try:  # the branching fraction value as a float
        return float(decay_mode.children[0].children[0].value)
    except (AttributeError, IndexError, ValueError) as e:
        raise RuntimeError(
            "'decayline' Tree does not seem to have the usual structure. Check it."
        ) from e
```

--------------------------------

### Enable pretty colors for terminal output

Source: https://decaylanguage.readthedocs.io/en/latest/examples/notebooks/AmpGen2GooFit_D2K3p.html

Initializes color support from the `plumbum` library to enhance terminal output readability. This is useful for highlighting different parts of the output.

```python
from plumbum import colors

colors.use_color = 2
```

--------------------------------

### Get Global Photos Flag

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Checks the global flag status for enabling PHOTOS in decays. Returns PhotosEnum.yes or PhotosEnum.no.

```python
global_photos_flag()
```

--------------------------------

### Generate GooFit Intro Code

Source: https://decaylanguage.readthedocs.io/en/latest/examples/notebooks/AmpGen2GooFit_D2K3p.html

Generates the introductory C++ code for a GooFit amplitude analysis, including event type, particle masses, and variable definitions. This is a foundational step for setting up a new analysis.

```cpp
print(GooFitChain.make_intro(all_states))
```

```cpp
// Event type: D0 ->  K- (0)   pi+ (1)   pi+ (2)   pi- (3)

    std::vector<std::vector<Lineshape*>> line_factor_list;
    std::vector<std::vector<SpinFactor*>> spin_factor_list;
    std::vector<Amplitude*> amplitudes_list;

    constexpr fptype PI_PLUS  { 139.57039      };
    constexpr fptype PI_MINUS { 139.57039      };
    constexpr fptype D_0      { 1864.84        };
    constexpr fptype K_MINUS  { 493.677        };

    Variable PiPi1_M         { "PiPi1_M"            , 9990       };
    Variable PiPi1_W         { "PiPi1_W"            , 9.9e+09    };
    Variable Kst_892_0_bar_M { "Kst_892_0_bar_M"    , 895.55     };
    Variable Kst_892_0_bar_W { "Kst_892_0_bar_W"    , 47.3       };
    Variable KPi1_0_M        { "KPi1_0_M"           , 9990       };
    Variable KPi1_0_W        { "KPi1_0_W"           , 9.9e+09    };
    Variable rho_1450_0_M    { "rho_1450_0_M"       , 1465       };
    Variable rho_1450_0_W    { "rho_1450_0_W"       , 400        };
    Variable PiPi_0_M        { "PiPi_0_M"           , 9990       };
    Variable PiPi_0_W        { "PiPi_0_W"           , 9.9e+09    };
    Variable K_1_1400_minus_M { "K_1_1400_minus_M"   , 1403       };
    Variable K_1_1400_minus_W { "K_1_1400_minus_W"   , 174        };
    Variable omega_782_M     { "omega_782_M"        , 782.66     };
    Variable omega_782_W     { "omega_782_W"        , 8.68       };
    Variable KPi0_0_M        { "KPi0_0_M"           , 9990       };
    Variable KPi0_0_W        { "KPi0_0_W"           , 9.9e+09    };
    Variable K_1460_minus_M  { "K_1460_minus_M"     , 1482.4     };
    Variable K_1460_minus_W  { "K_1460_minus_W"     , 335.6      };
    Variable PiPi3_M         { "PiPi3_M"            , 9990       };
    Variable PiPi3_W         { "PiPi3_W"            , 9.9e+09    };
    Variable K_1_1270_minus_M { "K_1_1270_minus_M"   , 1253       };
    Variable K_1_1270_minus_W { "K_1_1270_minus_W"   , 90         };
    Variable rho_770_0_M     { "rho_770_0_M"        , 775.26     };
    Variable rho_770_0_W     { "rho_770_0_W"        , 147.4      };
    Variable a_1_1260_plus_M { "a_1_1260_plus_M"    , 1230       };
    Variable a_1_1260_plus_W { "a_1_1260_plus_W"    , 420        };
    Variable PiPi2_M         { "PiPi2_M"            , 9990       };
    Variable PiPi2_W         { "PiPi2_W"            , 9.9e+09    };
    Variable K_2st_1430_minus_M { "K_2st_1430_minus_M" , 1427.3     };
    Variable K_2st_1430_minus_W { "K_2st_1430_minus_W" , 100        };
    Variable KPi2_0_M        { "KPi2_0_M"           , 9990       };
    Variable KPi2_0_W        { "KPi2_0_W"           , 9.9e+09    };

    DK3P_DI.meson_radius = 5;
    DK3P_DI.particle_masses = {D_0, K_MINUS, PI_PLUS, PI_PLUS, PI_MINUS};
```

--------------------------------

### dict_pythia_definitions

Source: https://decaylanguage.readthedocs.io/en/latest/_modules/decaylanguage/dec/dec.html

Returns a dictionary of all Pythia 8 commands categorized by their type (generic, alias, or both).

```APIDOC
## dict_pythia_definitions

### Description
Returns a dictionary of all Pythia 8 commands specified as "PythiaGenericParam", "PythiaAliasParam", or "PythiaBothParam" in the input parsed file. The commands are organized by their type.

### Method
`dict_pythia_definitions()`

### Parameters
None

### Response
- **dict[str, dict[str, str | float]]**: A dictionary with keys "PythiaAliasParam", "PythiaBothParam", and "PythiaGenericParam". Each value is another dictionary mapping module-parameter strings to their corresponding label or value.
```

--------------------------------

### Get Dictionary of Model Aliases

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Retrieve a dictionary of all 'ModelAlias' definitions, mapping alias names to a list of the model and its options.

```python
>>> dfp.dict_model_aliases()
```

--------------------------------

### Get Dictionary of CopyDecay Statements

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Retrieve a dictionary of all 'CopyDecay' statements from the parsed file, mapping names to the decays they copy.

```python
>>> dfp.dict_decays2copy()
```

--------------------------------

### Generate GooFit Script Introduction

Source: https://decaylanguage.readthedocs.io/en/latest/_modules/decaylanguage/modeling/goofit.html

Generates the header for a GooFit Python script, including constant definitions and particle masses. This method is crucial for setting up the script environment.

```python
    @classmethod
    def make_intro(cls, all_states):
        """
        Write out definitions of constant variables and lists to hold intermediate values.
        """
        header = f"#Event type: {all_states[0]} ->  "
        header += "   ".join(f"{b} ({a})" for a, b in enumerate(all_states[1:]))
        header += "\nfrom goofit import *\n"
        header += "\nDK3P_DI = DecayInfo4()\n"

        header += (
            "\nline_factor_list = []\nspin_factor_list = []\namplitudes_list = []\n"
        )

        final_particles = set(all_states)

        for particle in final_particles:
            name = particle.programmatic_name.upper()
            header += f"{name:8} = {particle.mass:<14.8g}\n"

        header += "\n"

        for particle in cls.all_particles - final_particles:
            name = particle.programmatic_name
            header += (
                "{name:15} = Variable({nameQ:21}, {particle.mass:<10.8g})\n".format(
                    name=name + "_M", nameQ='"' + name + '_M"', particle=particle
                )
            )
            header += (
                "{name:15} = Variable({nameQ:21}, {particle.width:<10.8g})\n".format(
                    name=name + "_W", nameQ='"' + name + '_W"', particle=particle
                )
            )

        header += "\n"
        header += "DK3P_DI.meson_radius = 5\n"
        header += "DK3P_DI.particle_masses = ({})
".format(
            ", ".join(x.programmatic_name.upper() for x in all_states)
        )

        return header
```

--------------------------------

### Create DecayMode with Metadata

Source: https://decaylanguage.readthedocs.io/en/latest/api/decay.html

Instantiate a `DecayMode` with additional metadata such as the decay model. This allows for richer descriptions of decay processes.

```python
>>> # Decay mode with metadata
>>> dm = DecayMode.from_pdgids(0.5, (310, 310), model="PHSP")
>>> dm.metadata
{'model': 'PHSP', 'model_params': ''}
```

--------------------------------

### Get All Decay Definitions

Source: https://decaylanguage.readthedocs.io/en/latest/_modules/decaylanguage/dec/dec.html

Retrieves a list of all decay definitions from a parsed file. Each definition is returned as a Lark Tree instance with Tree.data=='decay'.

```python
from lark import Tree

def get_decays(parsed_file: Tree) -> list[Tree]:
    """
    Return a list of all decay definitions in the input parsed file,
    of the form "Decay <MOTHER>",
    as a tuple of Lark Tree instances with Tree.data=='decay', i.e.::

        [Tree(decay, [Tree(particle, [Token(LABEL, <MOTHER1>)]), ...),
         Tree(decay, [Tree(particle, [Token(LABEL, <MOTHER2>)]), ...)].

    Parameters
    ----------
    parsed_file: Lark Tree instance
        Input parsed file.
    """
    try:
        return list(parsed_file.find_data("decay"))
    except Exception as err:
        raise RuntimeError(
            "Input parsed file does not seem to have the expected structure."
        ) from err
```

--------------------------------

### Instantiate DecayChainViewer with Graphviz Options

Source: https://decaylanguage.readthedocs.io/en/latest/index.html

Instantiates DecayChainViewer with custom graphviz.Digraph attributes like name and format. Use this for tailored graph output.

```python
dcv = DecayChainViewer(chain, name='TEST', format='pdf')
```

--------------------------------

### Get Charge Conjugate Definitions

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Extracts charge conjugate definitions. Use to find particle to its charge conjugate particle mappings.

```python
decaylanguage.dec.dec.get_charge_conjugate_defs(_parsed_file_)
```

--------------------------------

### Get Model Aliases

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Extracts model alias definitions. Use to find mappings from alias names to model names and options.

```python
decaylanguage.dec.dec.get_model_aliases(_parsed_file_)
```

--------------------------------

### Get Decay Mother Name

Source: https://decaylanguage.readthedocs.io/en/latest/_modules/decaylanguage/dec/dec.html

Provides a function to extract the name of the mother particle from a 'decay' Tree object generated by the Lark parser.

```python
def get_decay_mother_name(decay_tree: Tree) -> str | Any:
    """
    Return the mother particle name for the decay mode defined
    in the input Tree of name 'decay'.

    Parameters
    ----------
    decay_tree: Lark Tree instance
        Input Tree satisfying Tree.data=='decay'.
    """
    if decay_tree.data != "decay":
        raise RuntimeError("Input not an instance of a 'decay' Tree!")

    # For a 'decay' Tree, tree.children[0] is the mother particle Tree
    # and tree.children[0].children[0].value is the mother particle name
    return decay_tree.children[0].children[0].value
```

--------------------------------

### Get Number of Particle Decays

Source: https://decaylanguage.readthedocs.io/en/latest/_modules/decaylanguage/dec/dec.html

Returns the total count of particle decays defined in the parsed .dec file. Requires that the file has been parsed.

```python
@property
def number_of_decays(self) -> int:
    """Return the number of particle decays defined in the parsed .dec file."""
    self._check_parsing()
    assert self._parsed_decays is not None

    return len(self._parsed_decays)
```

--------------------------------

### Get Charge Conjugate Decays

Source: https://decaylanguage.readthedocs.io/en/latest/api/dec.html

Retrieves all charge conjugate decay definitions from a parsed file. Use when needing to identify CDecay statements.

```python
decaylanguage.dec.dec.get_charge_conjugate_decays(_parsed_file_)
```

--------------------------------

### Initialize DecayChainViewer with DecayChain Object

Source: https://decaylanguage.readthedocs.io/en/latest/_modules/decaylanguage/decay/viewer.html

The constructor accepts DecayChain objects directly, converting them to a dictionary format internally for processing.

```python
chain = DecayChain()
# ... populate chain ...
dcv = DecayChainViewer(chain, show_effective_bf=True)
```

--------------------------------

### Visualize Decay Chain with Graphviz

Source: https://decaylanguage.readthedocs.io/en/latest/api/decay.html

Initializes a `DecayChainViewer` to visualize a decay chain. This is particularly useful within notebook environments for direct display, or for generating output files using Graphviz.

```python
>>> dfp = DecFileParser('my-Dst-decay-file.dec')
>>> dfp.parse()
>>> chain = dfp.build_decay_chains('D*+')
>>> dcv = DecayChainViewer(chain)
>>> # display the SVG figure in a notebook
>>> dcv

>>> dcv.graph.render(filename=”test”, format=”pdf”, view=True, cleanup=True) # doctest: +SKIP
```