Analyzing the results

get_spectrum(
    hamiltonian_parts::HamiltonianParts,
    external_fields::ExternalFields,
)

Compute the energies and eigenstates under the external fields.

To avoid reconstructing the Hamiltonian each time, hamiltonian_parts can be reused over calls to get_spectrum. The output is a DataFrame, with the following fields:

See also get_spectra, make_hamiltonian_parts, make_krb_hamiltonian_parts, ExternalFields.

find_closest_eigenstate(spectrum, basis_state::State; tol=0.5)

Find the row in spectrum whose :eigenstate has the highest overlap with basis_state.

Example!!!

get_energy(spectrum, basis_state::State; tol = 0.5)

Find the row in spectrum whose :eigenstate has the highest overlap with basis_state.

Example!!!

get_energy_difference(spectrum, basis_g::State, basis_e::State; tol = 0.5)

Find the row in spectrum whose :eigenstate has the highest overlap with basis_state.

Example!!!

get_spectra(hamiltonian_parts, fields_scan, df_transform)

Compute the energies and eigenstates at each point in fields_scan, applying df_transform to each intermediate spectrum.

The fields_scan can be conveniently generated with generate_fields_scan. The closure df_transform, which must have the signature DataFrame -> DataFrame, can be used to filter away unneeded rows (typically large N states), or to do further analysis.

Internally, this method calls get_spectrum for each point in fields_scan, calls df_transform on each point (if provided), and vertically concatenates the results. The output is a DataFrame, see get_spectrum for details on the dataframe columns.

See also make_hamiltonian_parts, make_krb_hamiltonian_parts, generate_fields_scan, get_spectrum.

transform_spectra(spectra, f; groupby=:fields)

A generic function for transforming the output of get_spectra.

Returns the result of grouping spectra by groupby and applying f to each group, then combining the results into a new DataFrame. The signature of f must be DataFrame -> DataFrame.

Example??

expand_fields!(df; magnitude_only=true)
expand_fields!(df, col_names::Vector{Symbol}, expander::Function)

Expands the :fields column of df to new columns with the individual field parameters.

In the first variant, the optical fields are ignored. If magnitude_only=true (default), then the :fields column is expanded to new columns :B and :E contaning fields.B.magnitude and fields.E.magnitude, respectively. This is convenient for plotting, so the values of E can be accessed as df.E (and similarly for df.B). If magnitude_only=false, then new columns for the field angles :θ_B, :ϕ_B, :θ_E, and :ϕ_E are added, in addition to the field magnitudes.

The second variant allows full control of the behavior. col_names is the list of the columns to add to df. expander must be a function fields -> Vector, which defines how a value in the :fields column is transformed to the quantities named in col_names. This variant should be used for extracting the optical field parameters.

Add examples!

filter_basis_state!(df, basis_state::State)

Retains the rows of df whose :eigenstate is most overlapping with basis_state. This mutates df.

filter_basis_state(df, basis_state::State)

Returns a new DataFrame containing the rows of df whose :eigenstate is most overlapping with basis_state.

filter_hyperfine!(df, m_i1, m_i2)

Retains the rows of df where (row.m_i1 in m_i1) && (row.m_i2 in m_i2), removing the rest. This mutates df.

filter_hyperfine(df, m_i1, m_i2)

Returns a new DataFrame containing the rows of df where (row.m_i1 in m_i1) && (row.m_i2 in m_i2).

filter_rotational!(df, N)    
filter_rotational!(df, N, m_n)

Retains the rows of df where (row.N in N) && (row.m_n in m_n), removing the rest. This mutates df.

filter_rotational(df, N)    
filter_rotational(df, N, m_n)

Returns a new DataFrame containing the rows of df where (row.N in N) && (row.m_n in m_n).

wide_format(spectra, valuecol, renamecols::Function; groupby=:fields)

renamecols is a function row -> String, where row is a row of a DataFrame.

adiabatic(
    spectra;
    groupby=:fields,
    radius::Union{Int,Nothing}=nothing
)

closest_basis_state(parts::HamiltonianParts, state)

induced_dipole_moments(
    spectra,
    hamiltonian_parts::HamiltonianParts;
    groupby=:fields
)

Returns a new DataFrame containing spectra with an additional column :d_ind, the induced dipole moment parallel to the applied electric field.

transitions(
    spectra,
    hamiltonian_parts::HamiltonianParts,
    ground_basis_state::State,
    frequency_range::Union{Vector,Nothing} = nothing;
    groupby=:fields,
    tol=0.5,
    restrict_N=true,
    keep_negatives=true,
    cutoff::Union{Float64,Nothing}=1e-3
)

plot_induced_dipole(
    spectra,
    hamiltonian_parts::HamiltonianParts;
    groupby=:E,
    use_adiabatic=true
)

plot_induced_dipole(spectra; groupby=:E, use_adiabatic=true)

plot_states_adiabatic(
    spectra;
    groupby=:E,
    radius::Union{Int,Nothing}=nothing
)

plot_states_adiabatic_weighted(
    spectra,
    states::Vector{State};
    groupby=:E,
    radius::Union{Int,Nothing}=nothing
)

plot_transition_dipole(
    spectra,
    hamiltonian_parts::HamiltonianParts,
    initial_state::State,
    p::Int;
    groupby=:E,
    use_adiabatic=true,
)

plot_transition_dipole(
    spectra,
    initial_state::State,
    p::Int;
    groupby=:E,
    use_adiabatic=true
)

plot_transition_strengths(
    spectrum,
    hamiltonian_parts::HamiltonianParts,
    ground_basis_state::State,
    frequency_range::Union{Vector,Nothing} = nothing;
    groupby=:E,
    tol=0.5,
    restrict_N=true,
    keep_negatives=true,
    cutoff::Union{Float64,Nothing}=1e-3,
    normalization=1/sqrt(3)
)

plot_transition_strengths(
    spectra;
    groupby=:E,
)

plot_transitions_adiabatic(
    spectra,
    hamiltonian_parts::HamiltonianParts,
    ground_basis_state::State,
    frequency_range::Union{Vector,Nothing} = nothing;
    groupby=:E,
    tol=0.5,
    restrict_N=true,
    radius::Union{Int,Nothing}=nothing 
)