Public Functions

The public functions exported by GRASS are documented on this page. The high-level convenience functions should meet the needs of most users. Some other potentially useful, lower-level methods are exposed by GRASS and documented below. A full index of all methods defined by GRASS is available in the Full Index.

High-level Convenience Functions

GRASS provides a few high-level convenience wrappers for generating spectra.

GRASS.synthesize_spectra — Function

synthesize_spectra(
    spec,
    disk;
    seed_rng=false,
    verbose=true,
    use_gpu=false,
    precision=Float64,
    skip_times=falses(disk.Nt),
    contiguous_only=false,
    show_progress=true,
)

Synthesize spectra given parameters in spec and disk instances.

Arguments

spec::SpecParams: spectral synthesis parameters (line list, templates, wavelength grid).
disk::DiskParams: disk simulation parameters (grid size, time samples, geometry).

Keyword Arguments

seed_rng::Bool=false: re-seed RNG with a fixed seed per template.
verbose::Bool=true: print progress messages for template loading and simulation.
use_gpu::Bool=false: run the GPU implementation when available.
precision::DataType=Float64: GPU precision (Float32 or Float64); see Caveats
skip_times::BitVector=falses(disk.Nt): time indices to skip in the simulation loop.
contiguous_only::Bool=false: restrict to contiguous line groups when loading templates.
show_progress::Bool=true: enable progress reporting inside the simulation.

GRASS.SpecParams — Type

SpecParams(lines, depths, geffs, conv_blueshifts, variability, resolution, lambdas, templates)

GRASS.DiskParams — Type

DiskParams(; N=132, Nt=50, inclination=90.0)

Construct a DiskParams composite type instance. In the coordinate system, the x- and z- axes are sky-plane, and the y-axis is along the observer-to-star- center vector.

Arguments

N=197: number of stellar latitude grid elements; 197 recommended for physical validity.
Nt: number of 15-second time steps (required; must be provided).
Nsubgrid=40: number of subgrid points per surface element for integration.
radius=1.0: stellar radius in solar units.
inclination=90.0: sky-plane inclination of the stellar disk (90 degrees is equator-on).
u1=0.4: quadratic limb-darkening coefficient.
u2=0.26: quadratic limb-darkening coefficient.
vsini=2067.033467: equatorial rotational velocity magnitude in meters per second.
A=14.713: differential rotation coefficient (deg/day).
B=-2.396: differential rotation coefficient (deg/day).
C=-1.787: differential rotation coefficient (deg/day).
offset=false: randomize longitude grid edges by a half-step offset.

Velocity Measurement

GRASS wraps EchelleCCFs.jl to measure velocities from spectra using the CCF method.

GRASS.calc_ccf — Function

calc_ccf(λs, flux, var, lines, depths, resolution; mask_width=c_ms/resolution,
         Δv_max=15e3, Δv_step=100.0, mask_type=TopHatMask)

Compute the cross-correlation function (CCF) and its variance from a spectrum (λs, flux) and a per-pixel flux variance, using a line-list mask.

The CCF and its variance are returned unnormalized and on a common absolute scale. calc_rvs_from_ccf(v_grid, ccf, ccf_var) requires that; rescaling one without the other changes the reported σ_rv.

Arguments

λs::AbstractArray{Float64,1}: wavelength grid for the spectrum.
flux::AbstractArray{Float64,1}: flux values on the wavelength grid.
var::AbstractArray{<:Real,1}: per-pixel variance of flux.
lines::AbstractArray{Float64,1}: line centers for the CCF mask.
depths::AbstractArray{Float64,1}: line depths used as mask weights.
resolution::Float64: spectral resolution of the spectrum.

Keyword Arguments

mask_width::Float64=c_ms/resolution: mask width in velocity units.
Δv_max::Float64=15e3: maximum velocity shift (m/s) for the CCF grid.
Δv_step::Float64=100.0: velocity step size (m/s) for the CCF grid.
mask_type::Type=TopHatMask: mask shape type from EchelleCCFs.

calc_ccf(λs, flux, lines, depths, resolution; normalize=true, mask_width=c_ms/resolution,
         Δv_max=15e3, Δv_step=100.0, mask_type=TopHatMask)

Compute the cross-correlation function (CCF) from a spectrum (λs, flux) using a line-list mask.

Arguments

λs::AbstractArray{Float64,1}: wavelength grid for the spectrum.
flux::AbstractArray{Float64,1}: flux values on the wavelength grid.
lines::AbstractArray{Float64,1}: line centers for the CCF mask.
depths::AbstractArray{Float64,1}: line depths used as mask weights.
resolution::Float64: spectral resolution of the spectrum.

Keyword Arguments

normalize::Bool=true: normalize the CCF to its maximum value.
mask_width::Float64=c_ms/resolution: mask width in velocity units.
Δv_max::Float64=15e3: maximum velocity shift (m/s) for the CCF grid.
Δv_step::Float64=100.0: velocity step size (m/s) for the CCF grid.
mask_type::Type=TopHatMask: mask shape type from EchelleCCFs.

GRASS.calc_rvs_from_ccf — Function

calc_rvs_from_ccf(v_grid, ccf; frac_of_width_to_fit=0.75, fit_type=GaussianFit)

Calculate apparent radial velocity from a CCF and velocity grid.

Arguments

v_grid::AbstractArray{Float64,1}: velocity grid returned by calc_ccf.
ccf::AbstractArray{Float64,1}: CCF values returned by calc_ccf.

Keyword Arguments

frac_of_width_to_fit::Float64=0.75: fraction of the CCF width used in the fit.
fit_type::Type=GaussianFit: fit model from EchelleCCFs.

calc_rvs_from_ccf(v_grid, ccf, ccf_var; frac_of_width_to_fit=0.75, fit_type=GaussianFit)

Calculate apparent radial velocity and its uncertainty from a CCF, the CCF variance, and a velocity grid.

ccf and ccf_var must be on a common absolute scale, as returned together by calc_ccf(λs, flux, var, ...).

σ_rv is not a calibrated uncertainty

calc_ccf returns only the diagonal of the CCF covariance, and the fit weights by 1 ./ ccf_var, so neighbouring velocity lags are treated as independent when they are not: the tophat mask spans c_ms/resolution in velocity, several times the default Δv_step. The returned σ_rv therefore shrinks as sqrt(Δv_step) without bound and understates the true scatter of recovered velocities. Use it as a relative weight between epochs sharing one Δv_step, not as an absolute error bar. Handling this properly needs the off-diagonal covariance (EchelleCCFs.RVFromCCF provides ccf_sample_covar.jl for that).

Arguments

v_grid::AbstractArray{Float64,1}: velocity grid returned by calc_ccf.
ccf::AbstractArray{Float64,1}: CCF values returned by calc_ccf.
ccf_var::AbstractArray{Float64,1}: CCF variance returned by calc_ccf.

Keyword Arguments

frac_of_width_to_fit::Float64=0.75: fraction of the CCF width used in the fit.
fit_type::Type=GaussianFit: supplies the fit hyperparameters. Must be GaussianFit; any other FitType raises AssertionError.

Input Data

GRASS uses solar observations as input to simulate granulation in spectra. There are a few functions and composite types used to manipulate these data. See also the Manipulating Input Data tutorial.

GRASS.LineProperties — Type

LineProperties

Container for metadata about available line templates on disk.

GRASS.SolarData — Type

SolarData

Container for line profile data and metadata loaded from a template HDF5 file.

Bisector Measurement

GRASS.calc_bisector — Function

calc_bisector(wavs, flux; kwargs...)

Compute the line bisector from a wavelength grid and flux profile.

Arguments

wavs::AbstractArray{<:Real,1}: wavelength grid.
flux::AbstractArray{<:Real,1}: flux values on the grid.

Keyword Arguments

Keyword arguments are forwarded to calc_line_quantity, including:

continuum::Real=1.0: continuum level for normalization.
top::Real=0.99: maximum fraction of the continuum to sample.
nflux::Int=length(flux): number of bisector points to compute.

GRASS.calc_bisector_inverse_slope — Function

calc_bisector_inverse_slope(bis, int; b1=0.10, b2=0.4, b3=0.55, b4=0.90)

Compute the bisector inverse slope (BIS) from a line bisector and intensity profile. Following Queloz et al. 2001.

Arguments

bis::AbstractArray{<:Real,1}: bisector values as a function of intensity.
int::AbstractArray{<:Real,1}: normalized intensities corresponding to bis.

Keyword Arguments

b1::Real=0.10: upper depth fraction for the top region.
b2::Real=0.4: lower depth fraction for the top region.
b3::Real=0.55: upper depth fraction for the bottom region.
b4::Real=0.90: lower depth fraction for the bottom region.

GRASS.calc_bisector_span — Function

calc_bisector_span(bis, int)

Compute the bisector span using the line core and blue wing.

Arguments

bis::AbstractArray{<:Real,1}: bisector values as a function of intensity.
int::AbstractArray{<:Real,1}: normalized intensities corresponding to bis.

GRASS.calc_bisector_bottom — Function

calc_bisector_curvature(bis, int; c1=0.20, c2=0.30, c3=0.40,
                        c4=0.55, c5=0.75, c6=0.95)

Compute the bisector curvature from three depth regions. Following Dall et al. 2006.

Arguments

bis::AbstractArray{<:Real,1}: bisector values as a function of intensity.
int::AbstractArray{<:Real,1}: normalized intensities corresponding to bis.

Keyword Arguments

c1::Real=0.20: upper depth fraction for the top region.
c2::Real=0.30: lower depth fraction for the top region.
c3::Real=0.40: upper depth fraction for the middle region.
c4::Real=0.55: lower depth fraction for the middle region.
c5::Real=0.75: upper depth fraction for the bottom region.
c6::Real=0.95: lower depth fraction for the bottom region.

GRASS.calc_bisector_curvature — Function

From Dall et al. 2006

Utilities

GRASS.calc_rms — Function

calc_rms(A)

Calculate the RMS of given data about the observed mean.

Arguments

A::AbstractArray{Float64,1}: 1D array containing data for RMS calculation