BroadLineRegions.jl

A fast and flexible toolkit for modeling the broad-line region (BLR) in Julia.

Installation

Julia

using Pkg
Pkg.add("BroadLineRegions")

Or install from the GitHub repo directly:

using Pkg
Pkg.add("https://github.com/kirklong/BroadLineRegions.jl")

Python

To access BroadLineRegions from within your Python installation, first you must install JuliaCall. After successfully installing JuliaCall you can add BroadLineRegions to your new Julia installation in Python with:

from juliacall import Main as jl
from juliacall import Pkg as jlPkg
jlPkg.add("BroadLineRegions") #or use the github link

Quickstart

While this code is designed to be very flexible and modular such that you can implement your own bespoke models of the BLR easier, two popular models of the BLR are included as default models which one can play with.

To generate a "cloud" model similar to that of Pancoast+ 2011 and 2014, use syntax like:

using BroadLineRegions #exports itself as both BroadLineRegions and the shorter acronym BLR
mClouds = BLR.cloudModel(100_000,μ=500.,β=1.,F=0.5,θₒ=30/180*π,γ=1.,ξ=1.,i=0.,
        I=BLR.IsotropicIntensity,v=BLR.vCircularCloud,rescale=1e-5,τ=0.0)

To generate a "disk-wind" model similar to that of Chiang and Murray 1996 and 1997 following the prescription laid out in Long+ 2023 and 2025 use syntax like:

mDisk = BLR.DiskWindModel(500.,5.,1.,30/180*π,nr=24,nϕ=48,scale=:log,
        f1=1.0,f2=1.0,f3=1.0,f4=1.0,reflect=false,τ=5.)

You can of course define fully custom models by passing your own "rings" (on a camera) and optionally any default profiles, a camera struct, and submodel start indices:

mCustom = BLR.model(myCustomRings,nothing,myCustomCamera,[1]) #a custom model with no profiles, a user-defined camera for raytracing/visualization, and with no submodels

Models can be combined simply by writing mCombined = m1 + m2.

Generate profiles (i.e. line, phase, delay, or whatever else your heart desires) for models with syntax like:

p = BLR.getProfile(m,:line) #generate line profile with default parameters
BLR.setProfile!(m,p) #optinally store the profile in model data structure 

A few default visualization recipes exist as well:

profiles = BLR.profile(m) #plot all of the model's stored profiles 
img = BLR.image(m,:I) #make an image of the model intensity, can pass any other parameter as well to "image" them
geometry = BLR.plot3d(m) #visualize the geometry of the system in a 3d plot, can also color points according to any parameter

Note that no functions are exported by default into the global namespace to prevent overlap with other modules, and you must prepend the module name to all methods to access them. BroadLineRegions.jl exports itself as both BroadLineRegions and BLR, so both of these prefixes are equivalent, i.e. BroadLineRegions.model == BLR.model. If adding this prefix annoys you, you can avoid this by specifying the functions you want added to the global namespace in your import/Using statement. For example:

using BLR: DiskWindModel, cloudModel
mDisk = DiskWindModel(parms...) #instead of BLR.DiskWindModel

For more detailed examples, see the Usage and Examples page.

Full documentation is available in the API section.

Also note that if you are using BroadLineRegions from within Python you will need to modify all the code examples with the corresponding name that you imported julia with, i.e. the simple cloud example in the quickstart above in Python would become:

from juliacall import Main as jl
import numpy as np
jl.seval("Using BroadLineRegions") #load BLR into Main

mClouds = jl.BLR.cloudModel(100_000,μ=500.,β=1.,F=0.5,θₒ=30/180*np.pi,γ=1.,ξ=1.,i=0.,
             I=jl.BLR.IsotropicIntensity,v=jl.BLR.vCircularCloud,rescale=1e-5,τ=0.0)

You may also consider starting Julia with a sysimage to improve performance (see pure Julia example here, and instructions for enabling the functionality in juliacall here).

Referencing

If you find this code useful in your work, please cite it as:

lorem ipsum

Contributing

If you would like to contribute to the package, please open a pull request. For bug reports and feature requests, please open an issue.