Alouette API

Decay function

The decay function simulates a $\tau$ decay with TAUOLA. An optionnal polarisation 3-vector can be provided. If the latter is NULL (None), then spin effects are not simulated. The format of decay products is described below.

C synopsis

enum alouette_return alouette_decay(int mode, int pid, const double momentum[3],
    const double * polarisation, struct alouette_products * products);

Python synopsis

alouette.decay(mode=None, pid=None, momentum=None, polarisation=None)

Undecay function

The undecay function simulates a $\tau$ decay from a given decay product using the Backward Monte Carlo technique (BMC). The spin polarisation of the primary $\tau$ can be provided a posteriori as a callback function. Setting polarisation to NULL (None) results in spin effects to be ignored. The format of decay products is described below.

Configuration parameters

The undecay function has three additional configuration parameters, for advanced usage, detailed below.

• The alouette_undecay_mother (undecay.mother) parameter allows to specify the mother PID in a backward decay. Setting it to 0 results in both $\tau^-$ and $\tau^+$ being considered, which is the default setting.

• The alouette_undecay_bias (undecay.bias) parameter allows to control the spin biasing procedure, in backward decays. It must be within $[-1, 1]$. Default is 1, which assumes left (right) handed $\tau^-$ ($\tau^+$).

• The alouette_undecay_scheme (undecay.scheme) parameter allows to specify the Monte~Carlo integration scheme when computing the BMC weight. Default is cartesian, which is consistent with Alouette and TAUOLA APIs, using a Cartesian 3-momentum. Other possibilities are spherical and energy. The former assumes spherical coordinates for the 3-momentum, e.g. a flux per unit momentum and solid angle. The latter assumes an energy-direction representation of particles, e.g. like in PUMAS.

C synopsis

enum alouette_return alouette_undecay(int mode, int pid,
    const double momentum[3], alouette_polarisation_cb * polarisation,
    struct alouette_products * products);

typedef void alouette_polarisation_cb(
    int pid, const double momentum[3], double * polarisation);

Python synopsis

alouette.undecay(mode=None, pid=None, momentum=None, polarisation=None)

Decay products

Decay products are stored in a dedicated data structure. The daughters PIDs and 4-momenta, P, are accessed as arrays. The decay polarimeter vector is also provided for advanced usage, e.g. in order to simulate spin-spin corellations in $\tau^-\tau^+$ pairs, following Jadach et al. (1991).

C synopsis

struct alouette_products {
        /** Number of decay products. */
        int size;
        /** PDG IDs of decay products. */
        int pid[ALOUETTE_MAX_SIZE];
        /** Four momenta (px, py, pz, E) of decay products, in GeV/c. */
        double P[ALOUETTE_MAX_SIZE][4];
        /** Polarimeter vector of the decay. */
        double polarimeter[3];
        /** Monte Carlo weight of the decay. */
        double weight;

Python synopsis

class alouette.Products:
    size: int
    pid: int
    P: numpy.ndarray
    polarimeter: numpy.ndarray
    weight: float

Errors handling

The C library functions return a status code indicating success or failure, as described below. When an error occurs, the alouette_message function can be used in order to fetch the last error message, as a C string.

In the Python package, errors are managed automatically. Internal C library errors result in raising a ValueError or a RuntimeError exception, with the corresponding error message.

C return codes

enum alouette_return {
        /** Execution was successful. */
        ALOUETTE_RETURN_SUCCESS = 0,
        /** A parameter is out of its validity range. */
        ALOUETTE_RETURN_VALUE_ERROR,
        /** A TAUOLA error occured. */
        ALOUETTE_RETURN_TAUOLA_ERROR
};

/* Get the last (error) message(s). */
const char * alouette_message(void);

Initialisation

Initialisation is done automatically by Alouette using default settings. However, for advanced usage, the library can also be initialised explicitly using the alouette_initialise (alouette.initialise) function. Then, one can specify an optionnal random seed for TAUOLA's "warm up", i.e. the determination of $W_\text{max}$ weights, as detailed in Jadach et al. (1991). In addition, one can override the cutoff, $k_0^\text{decay}$, for radiative corrections in leptonic decays, see e.g. Jezabek et al. (1992).

C synopsis

enum alouette_return alouette_initialise(unsigned long * seed, double * xk0dec);

Python synopsis

alouette.initialise(seed=None, xk0dec=None)

Random stream

Alouette embeds a Mersenne Twister Pseudo Random Numbers Generator (PRNG). The next number in the sequence is returned by the alouette_random (alouette.random) function. The PRNG can be reset using alouette_random_set (random.set), and providing an optionnal seed. The alouette_random_seed function (random.seed attribute) returns the current seed value.

C synopsis

/* The library PRNG, uniform over (0,1). */
extern float (*alouette_random)(void);

/* Get the random seed of the built-in PRNG. */
unsigned long alouette_random_seed(void);

/* (Re)set the built-in PRNG. */
void alouette_random_set(unsigned long * seed);

Python synopsis

# The library PRNG, uniform over (0,1).
alouette.random()

# Get the random seed of the built-in PRNG.
alouette.random.seed

# (Re)set the built-in PRNG.
alouette.random.set(seed=None)

Tauola data

For more advanced usage, one might need to access TAUOLA's internal data. Those are exposed to C users with the tauola_ prefix. E.g., the /PARMAS/ common block can be accessed as tauola_parmas C structure. For Python users, some of these data are also wrapped in alouette.tauola submodule. They can be accessed as attributes, using the usual syntax. E.g. tauola.parmas.amtau returns the (read-only) $\tau$-lepton mass, according to TAUOLA.