ReactionRates

abstract type AbstractReactionRate end

Reaction rates should be defined as a subtype of AbstractReactionRate. Any custom reaction rate needs to contain a set of fixed fields:

struct MyReactionRate{TT<:Real} <: ReactionRates.AbstractReactionRate
    name::Symbol
    # num_iso_in of isotopes iso_in are converted into num_iso_out of isotopes iso_out
    iso_in::Vector{Symbol}
    num_iso_in::Vector{Int}
    iso_out::Vector{Symbol}
    num_iso_out::Vector{Int}
    Qvalue::TT  # energy released per reaction of this type (i.e. the mass defect), in erg
end

arbitrary fields can be added here. For instance if you have a tabulated reaction rate you can add the table values or even include the data defining a specific interpolator for it.

For any custom rate the following function needs to be defined

function get_reaction_rate(reaction::MyReactionRate, T::T1, ρ::T2, xa::AbstractVector{TT}
    #insert your code here
end

the function computes the specific reaction rate based on the name field of the reaction or done generically based on the other fields of the struct. Units are in $\mathrm{s^{-1}\;g^{-1}}$

reaction_list::Dict{Symbol, Dict{Symbol,AbstractReactionRate}} = Dict()

The reaction_list dictionary contains reaction rates that are available for construction of nuclear reaction networks. It is a dictionary of dictionaries, for instance accessing reaction_list[:jina_rates] will provide all available rates from JINA.

You can add a new dictionary of rates to reaction_list by doing

reaction_list[:kipp_rates] = Dict(
    :kipp_pp => MyReactionRate(:my_pp, [:H1], [2], [:H2], [1],
                                 ((2 * Chem.isotope_list[:H1].mass - Chem.isotope_list[:He2].mass) * AMU * CLIGHT^2)),
                                 # add whatever more rates
                                 )

this assumes a specific form for the constructor of MyReactionRate which only includes the mandatory fields, you can use any custom constructor for rate definitions which have more fields than the standard ones.

struct KippReactionRate{TT<:Real}<:ReactionRates.AbstractReactionRate

Struct for a Kippenhahn reaction rate, as defined in the Kippenhahn textbook. Results are evaluated by using the specific formula needed based on the name of the reaction.

• name: Symbol giving the name of the reaction.
• iso_in: vector that contains all reactants given as symbols (e.g. [:H1, :H2])
• num_iso_in: number of each of the elements in iso_in that are used in the reaction, given as a vector of integers. For example if iso_in is [:He4] and num_iso_in is [3] it means the reaction uses three ":He4".
• iso_out: Same as iso_in but for the products of the reaction.
• num_iso_out: Same as num_iso_in but for the products of the reaction.
• Qvalue: Q-value of the reaction (in erg), simply given by the mass difference.

function get_reaction_rate(reaction::KippReactionRate, T::T1, ρ::T2, xa::AbstractVector{TT},
                            xa_index::Dict{Symbol,Int})::TT where {TT,T1,T2}

Input: reaction: the reaction to evaluate for

• T`: the temperature in K
• ρ`: the density g cm^-3
• xa`: element mass fractions
• xa_index: Dictionary containing the index of each element within xa

Output:

• ϵ_nuc / Qvalue, has units s^-1 g^-1

JinaReactionRate{TT<:Real}<:ReactionRates.AbstractReactionRate

Struct that holds the following information for a given reaction rate:

TODO: explain all the different details that are read from the JINA data

• name: Symbol giving the name of the reaction.
• iso_in: vector that contains all reactants given as symbols (e.g. [:H1, :H2])
• num_iso_in: number of each of the elements in iso_in that are used in the reaction, given as a vector of integers. For example if iso_in is [:He4] and num_iso_in is [3] it means the reaction uses three ":He4".
• iso_out: Same as iso_in but for the products of the reaction.
• num_iso_out: Same as num_iso_in but for the products of the reaction.
• Qvalue: Q-value of the reaction (in erg), read from th JINA tables but its simply given by the mass difference.
• coeff: different $a\_i$ values of the fit to the reaction. Contains a vector of 7 values.
• set_label: Symbol containing set label of the reaction
• res_rate: A 1 character flag symbol:
  • when blank or n it is a non-resonant rate
  • when r it is a resonant rate
  • when w it is a weak rate.
• rev_rate: a 1 character flag symbol which is set to 'v' when it is a reverse rate.
• chapter: chapter this reaction is in. Different chapters

get_reaction_rate(reaction::JinaReactionRate, T::T1, ρ::T2, xa::AbstractVector{TT}, 
                  xa_index::Dict{Symbol,Int})

Evaluates the reaction rate, in s^{-1}g^{-1}, by computing Eqs. 1 and 2 from Cyburt+2010.

function read_dataset(dataset, dictionary, reference_dictionary)

Parses a large string object dataset, containing JINA reaction rate data, into a main dictionary and a reference dictionary. The main dictionary has entries with unique keys for every reaction rate in the database (double entries are distinguised with _0, _1 at the end of their key Symbol), while the reference dictionary has one entry per reaction equation, but has as value a list of all JINA rates for that reaction equation.

Example: if H1 + H1 -> D2 has two rates in the JINA database, main dictionary will contain:

dictionary[:H1_H1_to_D2_0] = _rate_info_(...)
dictionary[:H1_H1_to_D2_1] = _rate_info_(...)

while the reference dict will contain:

reference_dictionary[:H1_H1_to_D2] = [:H1_H1_to_D2_0, :H1_H1_to_D2_1]

For rates with only one entry in the JINA database, only an "_0" entry is made in the main dictionary, and the reference dictionary contains the list with only that one key.

add_to_references(main_dict, ref_dict, reaction, new_info::JinaReactionRate)

Function to identify rates with the same reaction equation Evaluates if a reaction rate is already in the reference dictionary ref_dict

If the reaction rate does not exist already in the reference dictionary: added as a new key to the reference dictionary the value of the key is a list containing all variations of the specific reaction the reaction will be added to the main dictionary

If the reaction rate already exists in the reference dictionary: keys in the main dictionary update so they have unique keys value of the key of the reaction in ref_dict is updated so all the unique versions of the rate are in

correct_names(JINA_name)

Returns the name that corresponds with the JEMS isotope database, given JINA_name, the name of the element as it is given in the JINA library (without the extra spaces).

function sort_reaction(elements)

Extracts the unique elements and the amount of times they appear in the list elements.

struct ToyReactionRate{TT<:Real}<:ReactionRates.AbstractReactionRate

• name: Symbol giving the name of the reaction.
• iso_in: vector that contains all reactants given as symbols (e.g. [:H1, :H2])
• num_iso_in: number of each of the elements in iso_in that are used in the reaction, given as a vector of integers. For example if iso_in is [:He4] and num_iso_in is [3] it means the reaction uses three ":He4".
• iso_out: Same as iso_in but for the products of the reaction.
• num_iso_out: Same as num_iso_in but for the products of the reaction.
• Qvalue: Q-value of the reaction (in erg), simply given by the mass difference.

function get_reaction_rate(reaction::ToyReactionRate, T::T1, ρ::T2, xa::AbstractVector{TT},
                            xa_index::Dict{Symbol,Int})::TT where {TT,T1,T2}

Input: reaction: the reaction to evaluate for

• T`: the temperature in K
• ρ`: the density g cm^-3
• xa`: element mass fractions
• xa_index: Dictionary containing the index of each element within xa

Output:

• ϵ_nuc / Qvalue, has units s^-1 g^-1