API

DiskWindModel(r̄::Float64, rFac::Float64, α::Float64, i::Float64; rot::Float64=0.0, 
        nr::Int=128, nϕ::Int=256, scale::Symbol=:log, kwargs...)

Uses the model constructor to create a DiskWind model of the BLR as detailed in Long+2023 and Long+2025.

Parameters

• r̄::Float64: Mean radius of model (in terms of $r_s$)
• rFac::Float64: Radius factor
• α::Float64: Power-law source function scaling
• i::Float64: Inclination angle in radians
• rot::Float64=0.0: Rotation of system plane about z-axis in radians
• nr::Int=128: Number of radial bins
• nϕ::Int=256: Number of azimuthal bins
• scale::Symbol=:log: Radial binning scale (:log or :linear)
• kwargs...: Extra keyword arguments for model constructor (see examples)

Returns

• model object

Note

Similar to another DiskWind model constructor but here we pass r̄, rFac, and α.

DiskWindModel(rMin::Float64, rMax::Float64, i::Float64; nr::Int=128, nϕ::Int=256, 
        I::Function=DiskWindIntensity, v::Function=vCircularDisk, scale::Symbol=:log, kwargs...)

Uses the model constructor to create a DiskWind model of the BLR as detailed in Long+2023 and Long+2025.

Parameters

• rMin::Float64: Minimum radius of model (in terms of $r_s$)
• rMax::Float64: Maximum radius of model (in terms of $r_s$)
• i::Float64: Inclination angle in radians (all rings have the same inclination)
• nr::Int=128: Number of radial bins
• nϕ::Int=256: Number of azimuthal bins
• I::Function=DiskWindIntensity: Intensity function
• v::Function=vCircularDisk: Velocity function
• scale::Symbol=:log: Radial binning scale (:log or :linear)
• kwargs...: Extra keyword arguments for I and v functions (see examples)

Returns

• model object

Note

Similar to other DiskWind model constructor but must explicitly pass rMin and rMax.

cloudModel(nClouds::Int64; μ::Float64=500., β::Float64=1.0, F::Float64=0.5, rₛ::Float64=1.0, θₒ::Float64=π/2, γ::Float64=1.0, ξ::Float64=1.0, i::Float64=0.0, I::Union{Function,Float64}=IsotropicIntensity, v::Union{Function,Float64}=vCircularCloud, rng::AbstractRNG=Random.GLOBAL_RNG, kwargs...)

Uses the model constructor to create a cloud model of the BLR similar to Pancoast+ 2011 and 2014.

Parameters

• nClouds::Int64: Number of clouds
• μ::Float64=500.: Mean radius of model (in terms of $r_s$)
• β::Float64=1.0: Shape parameter for radial distribution
• F::Float64=0.5: Minimum fraction of maximum radius where clouds can be placed
• rₛ::Float64=1.0: Scale radius (in terms of $r_s$)
• θₒ::Float64=π/2: Maximum opening angle of cloud distribution (rad)
• γ::Float64=1.0: Disk concentration parameter
• ξ::Float64=1.0: Fraction of clouds in back side that have not been moved to the front (when ξ = 1.0 clouds equally distributed front - back and when ξ = 0.0 all clouds are on the front side)
• i::Float64=0.0: Inclination angle of system (rad)
• I::Union{Function,Float64}=IsotropicIntensity: Intensity function
• v::Union{Function,Float64}=vCircularCloud: Velocity function
• rng::AbstractRNG=Random.GLOBAL_RNG: Random number generator
• kwargs...: Extra keyword arguments for I and v functions (see examples)

Returns

• model object

Note

Similar to other cloudModel method but here random values are generated for ϕ₀, rot, and θₒ ,i,rot,θ,θₒ,ξ, rₛ=rₛ,μ=μ,β=β,F=F,I=I,v=v,rng=rng;kwargs...) while keeping i constant for the system.

cloudModel(ϕ₀::Vector{Float64}, i::Vector{Float64}, rot::Vector{Float64}, θₒ::Vector{Float64}, 
        θₒSystem::Float64, ξ::Float64; rₛ::Float64=1.0, μ::Float64=500., β::Float64=1.0, F::Float64=0.5, 
        I::Union{Function,Float64}=IsotropicIntensity, v::Union{Function,Float64}=vCircularCloud, kwargs...)

Uses the model constructor to create a cloud model of the BLR similar to Pancoast+ 2011 and 2014.

Parameters

• ϕ₀::Vector{Float64}: Initial azimuthal angle of cloud (rad)
• i::Vector{Float64}: Inclination angle (rad)
• rot::Vector{Float64}: Random rotation of cloud about z axis (rad)
• θₒ::Vector{Float64}: Opening angle of cloud (rad)
• θₒSystem::Float64: Maximum opening angle of the system (rad)
• ξ::Float64: Fraction of clouds in back side that have not been moved to the front (when ξ = 1.0 clouds equally distributed front - back and when ξ = 0.0 all clouds are on the front side)
• rₛ::Float64=1.0: Scale radius (in terms of $r_s$)
• μ::Float64=500.: Mean radius of model (in terms of $r_s$)
• β::Float64=1.0: Shape parameter for radial distribution
• F::Float64=0.5: Beginning radius in units of μ where clouds can be placed.
• I::Union{Function,Float64}=IsotropicIntensity: Intensity function
• v::Union{Function,Float64}=vCircularCloud: Velocity function
• kwargs...: Extra keyword arguments for I and v functions (see examples)

Returns

• model object

Note

Similar to other cloudModel method but here you must explicitly pass ϕ₀, i, rot, and θₒ.

camera

Camera coordinates struct.

Fields

• α::Union{Vector{Float64}, Matrix{Float64}}: x values in the camera plane
• β::Union{Vector{Float64}, Matrix{Float64}}: y values in the camera plane
• raytraced::Bool: whether the camera has been used to raytrace the model

model

A mutable structure to hold many rings and their parameters that model the BLR.

Fields

• rings::Vector{ring}: List of ring objects, see ring struct
• profiles::Union{Nothing,Dict{Symbol,profile}}: Dictionary of profiles (see profile struct) with keys as symbols; optional, usually initialized to empty dictionary and filled in with setProfile!
• camera::Union{Nothing,camera}: Camera coordinates (α,β) corresponding to each ring used to generate images and in raytracing, see camera struct
• subModelStartInds::Vector{Int}: Indices of start of each submodel in list of rings; used to separate out submodels for raytracing or for the recovery of individual models after being combined

Constructors

model(rings::Vector{ring}, profiles::Union{Nothing,Dict{Symbol,profile}}, camera::Union{Nothing,camera}, subModelStartInds::Vector{Int}) 

• the most flexible constructor, takes in user supplied vector of ring objects, optional dictionary of profiles, optional camera coordinates, and vector of indices for submodels

model(rings::Vector{ring{Vector{Float64},Float64}})

• cloud model constructor, takes in a vector of ring objects that are each points in space and returns a model object with camera coordinates calculated from the physical parameters of each ring

model(rMin::Float64, rMax::Float64, i::Float64, nr::Int, nϕ::Int, I::Function, v::Function, scale::Symbol; kwargs...)

• disk-wind model constructor, takes in minimum and maximum radius, inclination angle, number of radial and azimuthal bins, intensity and velocity functions, and scale for radial binning; returns a model object with rings generated from these parameters

model(r̄::Float64, rFac::Float64, Sα::Float64, i::Float64, nr::Int, nϕ::Int, scale::Symbol; kwargs...)

• disk-wind model constructor, takes in average radius, radius scaling factor, power law for source function, inclination angle, number of radial and azimuthal bins, and scale for radial binning; returns a model object with rings generated from these parameters

profile

A struct to hold binned data, usually bound to model struct with profiles.jl#setProfile!.

Fields

• name::Symbol: Name of profile
• binCenters::Vector{Float64}: Bin centers
• binEdges::Vector{Float64}: Bin edges
• binSums::Vector{Float64}: Sum of values in each bin (crude integral over bin)

ring{V,F} <: AbstractRing{V,F}

A mutable structure to hold parameters of each model ring, where the "ring" is a circle in the camera plane observing the BLR.

Fields

• r: Distance from central mass (in terms of $r_s$)

  • Union{Vector{Float64}, Float64, Function}
  • Can be a single value for constant radius, or vector corresponding to azimuthal angles
  • Can be a function returning Vector{Float64} or Float64

• i: Inclination angle in radians

  • Union{Vector{Float64}, Float64}
  • Must be between 0 and $\pi/2$, with 0 being face-on and $\pi/2$ being edge-on

• rot: Rotation of system plane about z-axis in radians

  • Union{Vector{Float64}, Float64}

• θₒ: Opening angle of ring in radians

  • Union{Vector{Float64}, Float64}
  • Should be between 0 and $\pi/2$

• v: Line of sight velocity

  • Union{Vector{Float64}, Float64, Function}
  • Can be a function that calculates velocity from other parameters

• I: Intensity

  • Union{Vector{Float64}, Float64, Matrix{Float64}, Function}
  • Can be a function that calculates intensity from other parameters

• ϕ: Azimuthal angle in radians

  • Union{Vector{Float64}, Float64}

• ϕ₀: Initial azimuthal angle before rotation in radians

  • Union{Vector{Float64}, Float64}
  • Defaults to 0.0 if not provided or if rot is 0.0

• ΔA: Projected area of each ring element in image

  • Union{Vector{Float64}, Float64}
  • Used in calculating profiles

• reflect: Whether cloud is reflected across disk mid-plane

  • Union{Bool, Array{Bool,}}

• τ: Optical depth

  • Union{Vector{Float64}, Float64, Function}

• η: Response parameter for reverberation

  • Union{Vector{Float64}, Float64, Function}

• Δr: Distance between camera pixels in r

  • Float64

• Δϕ: Distance between camera pixels in ϕ

  • Float64

• scale: Encoding for camera ring scaling

  • Union{Nothing, Symbol}
  • :log or :linear scale

Constructor

ring(; r, i, v, I, ϕ, rot=0.0, θₒ=0.0, ϕ₀=0.0, ΔA=1.0, reflect=false, 
    τ=0.0, η=1.0, Δr=1.0, Δϕ=1.0, scale=nothing, kwargs...)

Required parameters:

• r, i, v, I, ϕ

Optional parameters with defaults:

• rot=0.0, θₒ=0.0, ϕ₀=0.0, ΔA=1.0, reflect=false, τ=0.0, η=1.0, Δr=1.0, Δϕ=1.0, scale=nothing

Additional keyword arguments are passed to the r, v, I, and τ functions if they are provided as functions.

drawCloud(;μ::Float64=500.,β::Float64=1.0,F::Float64=0.5,
        ϕ₀::Float64=0.0,i::Float64=π/4,rot::Float64=0.0,rₛ::Float64=1.0,
        θₒ::Float64=0.0,θₒSystem::Float64=0.0,I::Union{Function,Float64}=IsotropicIntensity,
        v::Union{Function,Float64}=vCircularCloud,ξ::Float64=1.0,
        rng::AbstractRNG=Random.GLOBAL_RNG,kwargs...)

Generates a model ring struct for a single cloud drawn from a thick disk-like structure with parameters defined by the input arguments similar to Pancoast+ 2011 and 2014.

Arguments:

• μ::Float64=500.: Mean radius of model (in terms of $r_s$)
• β::Float64=1.0: Shape parameter for radial distribution
• F::Float64=0.5: Beginning radius in units of μ where clouds can be placed.
• ϕ₀::Float64=0.0: Initial azimuthal angle of cloud (rad)
• i::Float64=π/4: Inclination angle (rad)
• rot::Float64=0.0: Random rotation of cloud about z axis (rad)
• rₛ::Float64=1.0: Scale radius (in terms of $r_s$)
• θₒ::Float64=0.0: Opening angle of cloud (rad)
• θₒSystem::Float64=0.0: Maximum opening angle of the system (rad)
• ξ::Float64=1.0: Fraction of clouds in back side that have not been moved to the front (when ξ = 1.0 clouds equally distributed front - back and when ξ = 0.0 all clouds are on the front side)
• I::Union{Function,Float64}=IsotropicIntensity: Intensity function/value
• v::Union{Function,Float64}=vCircularCloud: Velocity function/value
• kwargs...: Extra keyword arguments for I and v functions (see examples)

Returns:

A model ring struct representing the properties of the cloud.

getG(β::Float64)

Returns a Gamma distribution with parameters derived from the input parameter β as in Pancoast+ 2014 equation 12.

getGamma(;μ::Float64,β::Float64,F::Float64)

Returns a Gamma distribution with parameters derived from the input parameters as in Pancoast+ 2014 equations 7-10.

getR(rₛ::Float64,μ::Float64,β::Float64,F::Float64,
    g::Gamma{Float64},rng::AbstractRNG=Random.GLOBAL_RNG)

Returns the radius r calculated using Pancoast+ 2014 equation 12, where g is a Gamma distribution and a random number is drawn from it.

getR(rₛ::Float64,γ::Gamma{Float64},rng::AbstractRNG=Random.GLOBAL_RNG)

Returns a random number drawn from the Gamma distribution γ and shifted by rₛ.

getR(rₛ::Float64,μ::Float64,β::Float64,F::Float64,g::Float64)

Returns the radius r calculated using Pancoast+ 2014 equation 12, where g is already set.

Base.:+(m1::model, m2::model) combines two models by concatenating their rings and camera parameters.

Create a new model with the combined rings and camera parameters, and updates the subModelStartInds accordingly.

Base.getindex(m::model, i::Int)

Retrieves the i-th submodel from the model m.

DiskWindIntensity(;r::Union{Vector{Float64},Float64}, i::Float64, ϕ::Union{Vector{Float64},Float64}, 
        f1::Float64, f2::Float64, f3::Float64, f4::Float64, α::Float64, rMin::Float64 = 0.0, rMax::Float64 = Inf, _...)

Calculates the intensity from a disk-wind model of the BLR following the prescription given in Long+ 2023 and 2025, similar to Chiang and Murray 1996 and 1997, assumes optically thick line emission limit (Sobolev).

Arguments:

• r::Union{Vector{Float64},Float64} - radius from central mass (in terms of rₛ)
• i::Float64 - inclination angle (rad)
• ϕ::Union{Vector{Float64},Float64} - list of azimuthal angles (rad)
• f1::Float64 - strength of radial velocity gradient $\mathrm{d}v_{r}/\mathrm{d}r$
• f2::Float64 - strength of Keplerian shear velocity gradient $\mathrm{d}v_{\phi}/\mathrm{d}r$
• f3::Float64 - strength of radial lifting velocity gradient $\mathrm{d}v_{\theta}/\mathrm{d}r$
• f4::Float64 - strength of vertical lifting velocity gradient $\mathrm{d}v_{\theta}/\mathrm{d}\theta$ (equivalent to isotropic emission)
• α::Float64 - power-law index of the source function $S(r) \propto r^{-\alpha}$
• rMin::Float64 - minimum radius to consider (default: 0.0)
• rMax::Float64 - maximum radius to consider (default: Inf)

Returns:

• intensity (arbitrary units) as a Vector{Float64}

DiskWind_I_(r::Float64, ϕ::Float64, i::Float64, f1::Float64, f2::Float64, f3::Float64, f4::Float64, α::Float64)

Same as DiskWind_I_(r::Vector{Float64}, ϕ::Vector{Float64}, i::Float64, f1::Float64, f2::Float64, f3::Float64, f4::Float64, α::Float64) but for a single radius r and a single azimuthal angle ϕ.

DiskWind_I_(r::Float64, ϕ::Vector{Float64}, i::Float64, f1::Float64, f2::Float64, f3::Float64, f4::Float64, α::Float64)

Same as DiskWind_I_(r::Vector{Float64}, ϕ::Vector{Float64}, i::Float64, f1::Float64, f2::Float64, f3::Float64, f4::Float64, α::Float64) but for a single radius r and a vector of azimuthal angles ϕ.

DiskWind_I_(r::Vector{Float64}, ϕ::Float64, i::Float64, f1::Float64, f2::Float64, f3::Float64, f4::Float64, α::Float64)

Same as DiskWind_I_(r::Vector{Float64}, ϕ::Vector{Float64}, i::Float64, f1::Float64, f2::Float64, f3::Float64, f4::Float64, α::Float64) but for a vector of radii r and a single azimuthal angle ϕ.

DiskWind_I_(r::Vector{Float64}, ϕ::Vector{Float64}, i::Float64, f1::Float64, f2::Float64, f3::Float64, f4::Float64, α::Float64)

Calculates the intensity of the disk wind at radius r from the central mass and inclined at angle i (rad) over grid of azimuthal angles ϕ (rad) Follows the prescription given in Long+ 2023 and 2025, similar to Chiang and Murray 1996 and 1997, assumes optically thick line emission limit

Arguments:

• r::Vector{Float64} - radius from central mass (in terms of rₛ)
• ϕ::Vector{Float64} - list of azimuthal angles (rad)
• i::Float64 - inclination angle (rad)
• f1::Float64 - strength of radial velocity gradient dvᵣ/dr
• f2::Float64 - strength of Keplerian shear dvϕ/dr
• f3::Float64 - strength of velocity gradient dvθ/dr
• f4::Float64 - strength of velocity gradient dvθ/dθ (or isotropic emission)
• α::Float64 - power-law index of the source function S(r) ∝ r^(-α)

Returns:

• intensity (arbitrary units) as a Vector{Float64}

IsotropicIntensity(;r::Union{Vector{Float64},Float64}, ϕ::Union{Vector{Float64},Float64}, 
        rescale::Float64=1.0, rMin::Float64 = 0.0, rMax::Float64 = Inf, _...)

Returns a constant intensity value at all radii and azimuthal angles, rescaled by rescale factor.

IϕCloudMask(;r::Float64, ϕ::Float64, θₒ::Float64, ϕ₀::Float64, rot::Float64, i::Float64, κ::Float64=0.0, 
        ϕMin::Float64, ϕMax::Float64, overdense::Bool=false, _...)

Calculates the intensity using cloudIntensity but with an extra layer of masking based on azimuthal angle ϕ and the specified range [ϕMin, ϕMax]. If ϕ is outside this range, the intensity is set to 0.0. If overdense is true, the intensity is multiplied by 2.0 to account for the "lost" cloud and thus preserve total intensity in the model.

IϕDiskWindMask(;r::Union{Vector{Float64},Float64}, ϕ::Union{Vector{Float64},Float64}, i::Float64, 
        f1::Float64, f2::Float64, f3::Float64, f4::Float64, α::Float64, ϕMin::Float64, ϕMax::Float64, _...)

Calculates the intensity using DiskWindIntensity but with an extra layer of masking based on azimuthal angle ϕ and the specified range [ϕMin, ϕMax]. If ϕ is outside this range, the intensity is set to 0.0.

cloudIntensity(;r::Float64, ϕ::Float64, θₒ::Float64, ϕ₀::Float64, rot::Float64, i::Float64, κ::Float64=0.0, _...)

Calculate the intensity of the cloud at radius r from the central mass and inclined at angle i (rad) over grid of azimuthal angles ϕ (rad) following Pancoast+ 2011 and 2014.

Arguments

• r::Float64: radius from central mass (in terms of r₍ₛ₎)
• ϕ::Float64: azimuthal angle (rad)
• θₒ::Float64: opening angle of cloud
• ϕ₀::Float64: initial azimuthal angle
• rot::Float64: rotation angle
• i::Float64: inclination angle
• κ::Float64: anisotropy parameter

Returns

• Intensity (arbitrary units) as a Float64

vCirc(r::Float64, rₛ::Float64=1.0)

Calculate circular velocity at radius r from central mass, with Schwarzschild radius rₛ.

Defaults to rₛ=1.0 for unitless calculations.

vCircularCloud(;r::Float64, ϕ₀::Float64, i::Float64, rot::Float64, θₒ::Float64, rₛ::Float64=1.0, reflect::Bool=false, _...)

Calculate line of sight velocity for cloud in 3D space.

Arguments

• r::Float64: radius from central mass (in terms of rₛ)
• ϕ₀::Float64: starting azimuthal angle in ring plane (rad)
• i::Float64: inclination angle of ring plane (rad)
• rot::Float64: rotation of system plane about z axis (rad)
• θₒ::Float64: opening angle of point
• rₛ::Float64=1.0: Schwarzschild radius (optional, to convert to physical units)
• reflect::Bool=false: whether the point is reflected across the midplane of the disk
• _...: extra kwargs, ignored

Returns

• Line of sight velocity (Float64)

vCircularDisk(;r::Union{Float64,Vector{Float64}}, i::Float64, ϕ::Union{Vector{Float64},Float64}, rₛ=1.0, _...)

Calculate line of sight velocity for circular orbit at radius r from central mass and inclined at angle i (rad) over grid of azimuthal angles ϕ (rad).

vCircularRadialDisk(;r::Union{Float64,Vector{Float64}}, i::Float64, ϕ::Union{Vector{Float64},Float64}, 
        vᵣFrac::Union{Vector{Float64},Float64}=0.0, inflow::Union{Vector{Bool},Bool}=true, rₛ=1.0, _...)

Calculate line of sight velocity for circular orbit at radius r from central mass and inclined at angle i (rad) over grid of azimuthal angles ϕ (rad) with radial inflow/outflow.

vCloudTurbulentEllipticalFlow(;σρᵣ::Float64, σρc::Float64, σΘᵣ::Float64, σΘc::Float64, 
        θₑ::Float64, fEllipse::Float64, fFlow::Float64, σₜ::Float64, r::Float64, 
        i::Float64, rot::Float64, θₒ::Float64, rₛ::Float64=1.0, ϕ₀::Float64=0.0, 
        reflect::Bool=false, rng::AbstractRNG=Random.GLOBAL_RNG, _...)

Calculate line of sight velocity for cloud in 3D space with potential for elliptical orbital velocities, in/outflow, and turbulence as in Pancoast+14.

Arguments

• σρᵣ::Float64: Radial standard deviation around radial orbits
• σρc::Float64: Radial standard deviation around circular orbits
• σΘᵣ::Float64: Angular standard deviation around radial orbits
• σΘc::Float64: Angular standard deviation around circular orbits
• θₑ::Float64: Angle in vϕ-vr plane
• fEllipse::Float64: Fraction of elliptical orbits
• fFlow::Float64: If < 0.5, inflow, otherwise, outflow
• σₜ::Float64: Standard deviation of turbulent velocity
• r::Float64: Radius from central mass (in terms of rₛ)
• i::Float64: Inclination angle of ring plane (rad)
• rot::Float64: Rotation of system plane about z axis (rad)
• θₒ::Float64: Opening angle of point
• rₛ::Float64=1.0: Schwarzschild radius (optional, to convert to physical units)
• ϕ₀::Float64=0.0: Starting azimuthal angle in ring plane (rad)
• reflect::Bool=false: Whether the point is reflected across the midplane of the disk
• rng::AbstractRNG=Random.GLOBAL_RNG: Random number generator
• _...: Extra kwargs, ignored

Returns

• Line of sight velocity (Float64)

binModel(bins::Union{Int,Vector{Float64}}=100; m::model, yVariable::Union{String,Symbol,Function}, 
        xVariable::Union{String,Symbol,Function}=:v, kwargs...)
binModel(bins::Vector{Float64}, dx::Array{Float64,}; m::model, yVariable::Union{String,Symbol,Function}, 
        xVariable::Union{String,Symbol,Function}=:v, kwargs...)

Bin the model into a histogram, where each bin is the integrated value of the yVariable as a function of the xVariable.

Arguments

• m::model: Model object to bin
• yVariable::Union{String,Symbol,Function}: Variable to bin
  • Must be valid attribute of model.rings (e.g. :I, :v, :r, :e, :i, :ϕ) or a function that can be applied to model.rings
  • Example: Keplerian disk time delays could be calculated like t(ring) = ring.r*(1 .+ sin.(ring.ϕ).*ring.i))
• bins::Union{Int,Vector{Float64}}: Number of bins or bin edges for binning
  • If Int: Number of bins with edges equally spaced between min/max of xVariable
  • If Vector{Float64}: Specific bin edges, with number of bins = length(bins)-1
  • Left edge inclusive, right edge exclusive (except last bin which is inclusive)
• xVariable::Union{String,Symbol,Function}=:v: Variable to bin over
  • Must be a valid attribute of model.rings or a function that can be applied to model.rings
• dx::Array{Float64,}: Integration element for each bin
  • If provided, used as the associated integral element
  • Otherwise defaults to ΔA in each ring struct

Returns

• Tuple{Vector{Float64},Vector{Float64},Vector{Float64}}: A tuple containing:
  • binEdges: Bin edges for the xVariable of the histogram
  • binCenters: Bin centers for the xVariable
  • yBinned: Binned values of the yVariables

binnedSum(x::Array{Float64,}, y::Array{Float64, }; bins=100, 
        overflow=false, centered=false, minX=nothing, maxX=nothing)

Bin the x and y variables into a histogram, where each bin is the sum of the y values for the corresponding x values.

Arguments

• x::Array{Float64,}: x variable to bin over
• y::Array{Float64,}: y variable to bin
• bins::Union{Int,Vector{Float64}}=100: Number of bins or bin edges for binning
  • If Int: Number of bins with edges equally spaced between min/max of x
  • If Vector{Float64}: Specific bin edges, with number of bins = length(bins)-1
  • Left edge inclusive, right edge exclusive (except last bin which is inclusive)
• overflow::Bool=false: If true, include values outside bin range in the first/last bins
• centered::Bool=false: If true, shift bin edges to center around middle value
• minX::Union{Float64,Nothing}=nothing: Minimum value of x for binning (defaults to minimum(x))
• maxX::Union{Float64,Nothing}=nothing: Maximum value of x for binning (defaults to maximum(x))

Returns

• Tuple{Vector{Float64},Vector{Float64},Vector{Float64}}: A tuple containing:
  • binEdges: Bin edges for the x variable
  • binCenters: Bin centers for the x variable
  • result: Binned sums of the y variable

getProfile(m::model, name::Union{String,Symbol,Function}; 
           bins::Union{Int,Vector{Float64}}=100, 
           dx::Union{Array{Float64,},Nothing}=nothing, kwargs...)

Return a profile for the model based on the specified name.

Arguments

• m: Model object to get the profile from
• name: Name of the profile to get. Options include:
  • :line: Returns the line profile (integrated intensity as function of velocity)
  • :delay: Returns the delay profile (mean delays weighted by intensity/responsivity vs. velocity)
  • :r: Returns the mean radius (weighted by intensity) as function of velocity
  • :ϕ: Returns the mean azimuthal angle (weighted by intensity) as function of velocity
  • :phase: Returns the phase profile (integrated phase as function of velocity)
    • Requires U [Mλ], V [Mλ], PA [rad], and BLRAng [rad] as keyword arguments
  • Function: Returns the intensity weighted mean of this function vs. velocity
• bins: Number of bins or bin edges for binning
  • If Int: Number of bins with edges equally spaced between min/max velocity
  • If Vector{Float64}: Specific bin edges, with number of bins = length(bins)-1
  • Left edge inclusive, right edge exclusive (except last bin which is inclusive)
• dx: Integration element for each ring (defaults to ΔA in each ring struct if nothing)
• Additional kwargs passed to binModel include:
  • overflow=true: Include overflow bins
  • centered=true: Center bins around 0.0
  • minX, maxX: Set min/max bin boundaries

Returns

• profile: A profile object containing bin edges, bin centers, and binned sums. Assign to a model object using setProfile! to store the profile in the model.

phase(m::model; U, V, PA, BLRAng, returnAvg=false, offAxisInds=nothing, kwargs...)

Calculate differential phase signal for a model based on specified baselines, model orientation, and BLR angular size.

Arguments

• m::model: Model object to calculate phase for
• U::Vector{Float64}: U component of complex visibility in [Mλ]
• V::Vector{Float64}: V component of complex visibility in [Mλ]
• PA::Float64: On-sky position angle of the model in radians
• BLRAng::Float64: Characteristic size of the BLR model in radians (conversion from $r_s$ to radians)
• returnAvg::Bool=false: If true, returns the average phase across all baselines
• offAxisInds::Union{Nothing,Vector{Int}}=nothing: If provided, only calculates phase for baselines at specified indices

Returns

• If returnAvg=true: Tuple{Vector{Float64},Vector{Float64},Vector{Float64}} containing:
  • Bin edges for velocity
  • Bin centers for velocity
  • Average differential phase (in radians)
• If returnAvg=false: Vector{Tuple{Vector{Float64},Vector{Float64},Vector{Float64}}} containing:
  • For each baseline, a tuple of bin edges, bin centers, and differential phase

The differential phase is calculated by integrating the phase over the model at each velocity bin, weighted by the intensity and area of each ring element.

setProfile!(m::model, p::profile; overwrite::Bool=false)

Set a profile in the model's profiles dictionary. If the profile already exists and overwrite is false, a warning is issued.

t(ring::ring, subFxn::Function=tDisk)

Calculate time delays for a point in a disk or cloud using a custom function subFxn that takes a ring struct.

It is more peformant to pass the function directly rather than figure it out on the fly if known ahead of time.

t(ring::ring)

Calculate time delays for a point in a disk as `` t = \eta r \left(1 + \cos(\phi) \sin(i)\right)`` or a cloud with opening angle ``\theta_o``
as the x-coordinate of the point subtracted from the radial distance of the point ``t = r - x``.

tCloud(ring::ring)

Calculate time delays for a cloud with opening angle ``\theta_o`` as the x-coordinate of the point subtracted from the radial distance of the point ``t = r - x``.

tDisk(ring::ring)

Calculate time delays for a point in a disk as `` t = \eta r \left(1 - \cos(\phi) \sin(i)\right)``

getΨ(m::model,vEdges::Array{Float64},tEdges::Array{Float64})

Calculate the 2D transfer function Ψ for a model m over specified velocity and time bins, whose edges are given by vEdges and tEdges.

getΨ(m::model,vBins::Int64,tBins::Int64)

Calculate the 2D transfer function Ψ for a model m over specified number of velocity bins vBins and time bins tBins. The velocity and time edges are automatically calculated based on the minimum and maximum values for velocity and delays in the model.

getΨt(m::model,tBins::Int64,maxT::Float64=Inf,overflow::Bool=false)

Calculate the 1D transfer function Ψ(t) for a model m over specified number of time bins tBins. The maxT parameter specifies the maximum time delay to consider, and overflow determines whether to include contributions from delays outside the specified edges in the edge bins.

getΨt(m::model,tEdges::Array{Float64},overflow::Bool=false;)

Calculate the 1D transfer function Ψ(t) for a model m over specified time edges tEdges. The overflow parameter determines whether to include contributions from delays outside the specified edges in the edge bins.

response(r::Float64; ηₒ::Float64=0.5, η₁::Float64=0.5, αRM::Float64=0.0, rNorm::Float64=1.0, _...)

Calculate response function for use in reverberation mapping calculations.

photograph(r::Float64, ϕ₀::Float64, i::Float64, rot::Float64, θₒ::Float64, reflect::Bool=false)

Calculate the image coordinates from system coordinates r, ϕ + inclination angle i.

Arguments

• r::Float64: radius from central mass (in terms of rₛ)
• ϕ₀::Float64: unrotated azimuthal angle in ring plane (rad)
• i::Float64: inclination angle of ring plane (rad)
• rot::Float64: rotation of system plane about z axis (rad)
• θₒ::Float64: ring opening angle
• reflect::Bool=false: whether the point is reflected across the midplane of the disk

Returns

• α::Float64: image x coordinate (in terms of rₛ)
• β::Float64: image y coordinate (in terms of rₛ)

Note

This function is coordinate photography only. To visualize models, see Image.`

raytrace!(m::model; IRatios::Union{Float64,Array{Float64,}}=1.0, 
        τCutOff::Float64=1.0, raytraceFreeClouds::Bool=false)

Perform raytracing for a model, combining overlapping components along line of sight.

This function should be called after combining all relevant models (i.e. mCombined = m1 + m2 + m3...). It performs raytracing in discrete steps (no absorption, only adding intensity in chunks along the line of sight until maximum optical depth τ is reached) and generates a new model object with extraneous points removed. Note that this function will mutate the input model objects.

Arguments

• m::model: Model to raytrace
• IRatios::Union{Float64,Array{Float64,}}=1.0: Intensity ratios for each submodel
  • If Float64, applies to all submodels equally
  • If array, applies to each submodel individually (must match number of submodels)
  • Used when combining models with different intensity functions if they aren't properly normalized
• τCutOff::Float64=1.0: Maximum optical depth to raytrace to (stops when τ > τCutOff)
• raytraceFreeClouds::Bool=false: Whether to raytrace free clouds (cloud-cloud raytracing)
  • If false, clouds are only raytraced if they overlap with a continuous model
  • If true, clouds will be checked for overlap with other clouds and raytraced accordingly

Returns

• m::model: Model with raytraced points

raytrace(α::Float64, β::Float64, i::Float64, rot::Float64, θₒPoint::Float64)

Calculate where ray traced back from camera coordinates α and β intersects the system (assumes circular geometry).

Arguments

• α::Float64: image x coordinate (in terms of rₛ)
• β::Float64: image y coordinate (in terms of rₛ)
• i::Float64: inclination angle of system (rad)
• rot::Float64: how the point was rotated about z axis (rad)
• θₒPoint::Float64: opening angle of current point

Returns

• r::Float64: distance from central mass (in terms of rₛ)
• ϕ::Float64: azimuthal angle of system ring plane at intersection
• ϕ₀::Float64: original azimuthal angle in ring plane (no rotation)

Note

This function is coordinate raytracing only. To raytrace models and combine intensities, see raytrace!.

raytrace(α::Float64, β::Float64, i::Float64, rot::Float64, θₒPoint::Float64, 
        r3D::Matrix{Float64}, xyz::Vector{Float64}, matBuff::Matrix{Float64}, 
        colBuff::Vector{Float64})

Performant version of raytrace function – calculate where ray traced back from camera coordinates α, β intersects the system (assumes circular geometry).

Arguments

• α::Float64: image x coordinate (in terms of rₛ)
• β::Float64: image y coordinate (in terms of rₛ)
• i::Float64: inclination angle of system (rad)
• rot::Float64: rotation of current point about z axis (rad)
• θₒPoint::Float64: opening angle of current point
• r3D::Matrix{Float64}: matrix that rotates system plane into XY plane
• xyz::Vector{Float64}: preallocated xyz vector (but not precalculated)
• matBuff::Matrix{Float64}: preallocated buffer matrix for storing result of 3x3 matrix multiplication
• colBuff::Vector{Float64}: preallocated buffer vector for storing final matrix multiplication result

Returns

• r::Float64: distance from central mass (in terms of rₛ)
• ϕ::Float64: azimuthal angle of system ring plane at intersection
• ϕ₀::Float64: original azimuthal angle in ring plane

Note

This function is coordinate raytracing only. To raytrace models and combine intensities, see raytrace!.

removeDiskObscuredClouds!(m::model, rotate3D::Function=rotate3D)

Remove clouds that are obscured by the disk.

Performs simple raytracing for an optically thick obscuring disk. The function modifies the input model by removing cloud points that are obscured by the disk. Note that this is a mutating operation and the input model will be modified in place.

Arguments

• m::model: Model to remove disk obscured clouds. Should be a combined model consisting of a disk component and a cloud component.
• rotate3D::Function=rotate3D: Function to rotate coordinates in 3D space

Returns

• m::model: Model with disk obscured clouds removed

See also

• zeroDiskObscuredClouds!: Function to zero out disk obscured clouds instead of removing them

zeroDiskObscuredClouds!(m::model; diskCloudIntensityRatio::Float64=1.0, rotate3D::Function=rotate3D)

Zero out the intensities of clouds that are obscured by the disk.

Performs simple raytracing for an optically thick obscuring disk. The function modifies the input model by setting the intensity of obscured cloud points to zero and adjusting the disk intensity according to the specified ratio.

Arguments

• m::model: Model to zero out disk obscured clouds. Should be a combined model consisting of a disk component and a cloud component.
• diskCloudIntensityRatio::Float64=1.0: Ratio of disk to cloud intensity, used to scale the disk intensities after zeroing out clouds
• rotate3D::Function=rotate3D: Function to rotate coordinates in 3D space

Returns

• m::model: Model with disk obscured clouds zeroed out

See also

• removeDiskObscuredClouds!: Function to remove disk obscured clouds instead of zeroing them out

addGrid!(m::model, colors=nothing, nϕ::Int=64)

Add a grid to the model image plot - mostly a debugging tool to visualize grid cells of overlapping models.

Arguments

• m::model: Model object to add grid to
• colors=nothing: Vector of colors for each submodel (if nothing, uses default colors)
• nϕ::Int=64: Number of azimuthal angles to use for the grid

Returns

• ::Plots.plot: Plot with grid added

getFlattenedCameraIndices(m::model)

Get flattened camera indices corresponding to rings in model.

Arguments

• m::model: Model object to extract camera indices from

Returns

• camStartInds::Vector{Int}: Vector of camera starting indices with length equal to m.subModelStartInds

getRingFromFlattenedInd(m::model, flattenedInd::Int) -> Tuple{Int, Int}

Retrieve the model ring index and subindex (if applicable) from flattened array index.

Arguments

• m::model: Model object with rings
• flattenedInd::Int: The index in the flattened array we need to work back from

Returns

• row::Int: The ring index in model.rings that the flattened index corresponds to
• column::Int: The subindex that matches the flattened index passed to this function.

getVariable(m::model, variable::Function; flatten=false)

Retrieve model variable when specified as a Function. See main docstring for details.

getVariable(m::model, variable::Union{String,Symbol,Function}; flatten=false)

Retrieve elements from model object and stack them into matrices for easy manipulation.

Arguments

• m::model: Model object to extract variables from
• variable::Union{String,Symbol,Function}: Variable to extract from model
  • If String, will be converted to Symbol
  • Must be a valid attribute of model.rings (e.g. :I, :v, :r, :e, :i, :ϕ) or a function that can be applied to model.rings
  • Example: Keplerian disk time delays could be calculated like t(ring) = ring.r*(1 .+ sin.(ring.ϕ).*ring.i))
• flatten::Bool=false: If true, flatten the result to a vector

Returns

• Array{Float64,}: Matrix or vector of extracted variable from model.rings, created by stacking the output variable for each ring
  • For example, if variable given is :I, result will have shape (length(r), length(ϕ)) as at each r and ϕ there is a value of I
  • If flatten=true, result will be a flattened vector

getVariable(m::model, variable::Symbol; flatten=false)

Retrieve model variable when specified as a Symbol. See main docstring for details.

get_r3D(i::Float64, rot::Float64, θₒ::Float64) -> Matrix{Float64}

Calculate rotation matrix to transform from initial XY plane coordinates to 3D space.

Parameters

• i::Float64: Inclination angle of ring (rad)
• rot::Float64: Rotation of ring plane about z axis (rad)
• θₒ::Float64: Opening angle of point (rad)

Returns

• matrix::Matrix{Float64}: 3×3 rotation matrix

get_rMinMaxDiskWind(r̄::Float64, rFac::Float64, α::Float64)

Calculate the minimum and maximum radius of model given the (intensity weighted) mean radius r̄, the radius factor rFac, and the power-law index α following Long+ 2023.

Parameters

• r̄::Float64: mean radius of model (in terms of rₛ)
• rFac::Float64: radius scaling factor
• α::Float64: power-law index of the source function $S(r) \propto r^{-\alpha}$ (cannot be 1/2 or 3/2 as this divides by zero)

Returns

• rMin::Float64: minimum radius of model (in terms of rₛ)
• rMax::Float64: maximum radius of model (in terms of rₛ)

BLR.image(m::model, variable::Union{String,Symbol,Function}, kwargs...)

Generate an image of the model where the color of each point is determined by the variable provided.

Arguments

• m::model: Model object to extract variable from
• variable::Union{String,Symbol,Function}: Variable to extract from model
  • If String, will be converted to Symbol
  • Must be a valid attribute of model.rings (e.g. :I, :v, :r, :e, :i, :ϕ) or a function that can be applied to model.rings
  • Example: Keplerian disk time delays could be calculated like t(ring) = ring.r*(1 .+ sin.(ring.ϕ).*ring.i))

Keywords

• Additional keyword arguments are passed to Plots.plot

Returns

• p::Plots.plot: Plot object representing the generated image

BLR.image(m::model, variable::Union{String,Symbol,Function}, kwargs...)

Generate an image of the model where the color of each point is determined by the variable provided.

Arguments

• m::model: Model object to extract variable from
• variable::Union{String,Symbol,Function}: Variable to extract from model
  • If String, will be converted to Symbol
  • Must be a valid attribute of model.rings (e.g. :I, :v, :r, :e, :i, :ϕ) or a function that can be applied to model.rings
  • Example: Keplerian disk time delays could be calculated like t(ring) = ring.r*(1 .+ sin.(ring.ϕ).*ring.i))

Keywords

• Additional keyword arguments are passed to Plots.plot

Returns

• p::Plots.plot: Plot object representing the generated image

BLR.image(m::model, variable::Union{String,Symbol,Function}, kwargs...)

Generate an image of the model where the color of each point is determined by the variable provided.

Arguments

• m::model: Model object to extract variable from
• variable::Union{String,Symbol,Function}: Variable to extract from model
  • If String, will be converted to Symbol
  • Must be a valid attribute of model.rings (e.g. :I, :v, :r, :e, :i, :ϕ) or a function that can be applied to model.rings
  • Example: Keplerian disk time delays could be calculated like t(ring) = ring.r*(1 .+ sin.(ring.ϕ).*ring.i))

Keywords

• Additional keyword arguments are passed to Plots.plot

Returns

• p::Plots.plot: Plot object representing the generated image

midPlaneXZ(x::Float64, i::Float64) -> Float64

midPlaneXZ(x,i) = -x*cot(i)

plot3d(m::model, [variable], [annotate], [kwargs...])

Generate a 3D plot of the model geometry, optionally colored by a variable.

Parameters

• m::model: Model object to plot
• variable::Union{String,Symbol,Function}=nothing: Variable to color the points by
  • If String, will be converted to Symbol
  • Must be a valid attribute of model.rings (e.g., :I, :v, :r, :e, :i, :ϕ) or a function that can be applied to model.rings
  • Example: Keplerian disk time delays could be calculated like t(ring) = ring.r*(1 .+ sin.(ring.ϕ).*ring.i))
  • If not provided, defaults to nothing (no coloring)
• annotate::Bool=true: Whether to annotate the camera position and model orientation in the plot
• kwargs...: Additional keyword arguments passed to Plots.plot

Returns

• p::Plots.plot: 3D plot of the model geometry, optionally colored by the variable provided

plot3d(m::model, [variable], [annotate], [kwargs...])

Generate a 3D plot of the model geometry, optionally colored by a variable.

Parameters

• m::model: Model object to plot
• variable::Union{String,Symbol,Function}=nothing: Variable to color the points by
  • If String, will be converted to Symbol
  • Must be a valid attribute of model.rings (e.g., :I, :v, :r, :e, :i, :ϕ) or a function that can be applied to model.rings
  • Example: Keplerian disk time delays could be calculated like t(ring) = ring.r*(1 .+ sin.(ring.ϕ).*ring.i))
  • If not provided, defaults to nothing (no coloring)
• annotate::Bool=true: Whether to annotate the camera position and model orientation in the plot
• kwargs...: Additional keyword arguments passed to Plots.plot

Returns

• p::Plots.plot: 3D plot of the model geometry, optionally colored by the variable provided

plot3d(m::model, [variable], [annotate], [kwargs...])

Generate a 3D plot of the model geometry, optionally colored by a variable.

Parameters

• m::model: Model object to plot
• variable::Union{String,Symbol,Function}=nothing: Variable to color the points by
  • If String, will be converted to Symbol
  • Must be a valid attribute of model.rings (e.g., :I, :v, :r, :e, :i, :ϕ) or a function that can be applied to model.rings
  • Example: Keplerian disk time delays could be calculated like t(ring) = ring.r*(1 .+ sin.(ring.ϕ).*ring.i))
  • If not provided, defaults to nothing (no coloring)
• annotate::Bool=true: Whether to annotate the camera position and model orientation in the plot
• kwargs...: Additional keyword arguments passed to Plots.plot

Returns

• p::Plots.plot: 3D plot of the model geometry, optionally colored by the variable provided

profile(m::model, [variable], [kwargs...])

Plot all profiles set in the model, normalized to the maximum value of each profile.

Arguments

• model: A model object containing profile data.
• variable: Optional. A symbol or string (or list of symbols/strings) specifying which profile to plot. If not provided, all profiles set in model will be plotted.
• kwargs...: Additional keyword arguments passed to Plots.plot

profile(m::model, [variable], [kwargs...])

Plot all profiles set in the model, normalized to the maximum value of each profile.

Arguments

• model: A model object containing profile data.
• variable: Optional. A symbol or string (or list of symbols/strings) specifying which profile to plot. If not provided, all profiles set in model will be plotted.
• kwargs...: Additional keyword arguments passed to Plots.plot

reflect!(xyzSys::Vector{Float64}, i::Float64) -> Vector{Float64}

Reflect coordinates in 3D space across the ring plane.

Parameters

• xyzSys::Vector{Float64}: [x;y;z] coordinates in 3D space
• i::Float64}: Inclination angle of ring plane (rad)

Returns

• xyzSys::Vector{Float64}: [x';y';z'] coordinates in 3D space after reflection

removeNaN!(m::model)

Remove points with I = NaN from model.

Parameters

• m::model: Model to remove points from

Returns

• m::model: Model with NaN points removed

reset!(m::model; profiles=true, img=false)

Erase existing profiles/raytrace status.

Parameters

• m::model: Model object to reset
• profiles::Bool=true: If true, reset profiles
• img::Bool=false: If true, reset raytracing boolean (does not change existing model but allows model to be raytraced again after combining other new models)

rotate3D(r::Float64, ϕ₀::Float64, i::Float64, rot::Float64, θₒ::Float64, reflect::Bool=false)

Transform from ring coordinates to 3D coordinates where camera is at +x.

Parameters

• r::Float64: Radius from central mass (in terms of rₛ)
• ϕ₀::Float64: Starting azimuthal angle in ring plane (rad)
• i::Float64: Inclination angle of ring plane (rad)
• rot::Float64: Rotation of system plane about z axis (rad)
• θₒ::Float64: Opening angle of point (rad)
• reflect::Bool=false: Whether to reflect across the ring plane

Returns

• Tuple{Float64, Float64, Float64}: (x, y, z) coordinates in 3D space

rotate3D(r::Float64, ϕ₀::Float64, i::Float64, matrix::Matrix{Float64}, reflect::Bool=false)

Transform from ring coordinates to 3D coordinates where camera is at +x using a precomputed rotation matrix.

Parameters

• r::Float64: Radius from central mass (in terms of rₛ)
• ϕ₀::Float64: Starting azimuthal angle in ring plane (rad)
• i::Float64: Inclination angle of ring plane (rad)
• matrix::Matrix{Float64}: Precomputed rotation matrix for the ring
• reflect::Bool=false: Whether to reflect across the ring plane

Returns

• Vector{Float64}: [x; y; z] coordinates in 3D space

profile(m::model, [variable], [kwargs...])

Plot all profiles set in the model, normalized to the maximum value of each profile.

Arguments

• model: A model object containing profile data.
• variable: Optional. A symbol or string (or list of symbols/strings) specifying which profile to plot. If not provided, all profiles set in model will be plotted.
• kwargs...: Additional keyword arguments passed to Plots.plot