9. API¶

9.1. Model¶

class hazel.model.Model(config=None, working_mode='synthesis', verbose=0, debug=False, rank=0, randomization=None, root='')¶

Bases: object

Methods

`add_chromosphere`(atmosphere)	Programmatically add a chromosphere
`add_parametric`(atmosphere)	Programmatically add a parametric atmosphere
`add_photosphere`(atmosphere)	Programmatically add a photosphere
`add_spectral`(spectral)	Programmatically add a spectral region
`add_straylight`(atmosphere)	Programmatically add a straylight atmosphere
`add_topology`(atmosphere_order)	Add a new topology
`backtracking_parabolic`(dchi2, ddchi2[, ...])	Do the backtracking to get an optimal value of lambda in the LM algorithm
`compute_chi2`([only_chi2, weights])	Compute chi2 for all spectral regions
`compute_uncertainty`()	Compute the uncertainty in the parameters at the minimum with the current Hessian
`find_active_parameters`(cycle)	Find all active parameters in all active atmospheres in the current cycle
`flatten_parameters_to_reference`(cycle)	Flatten all current parameters to the reference atmosphere
`init_sir`()	Initialize SIR for this synthesis.
`init_sir_external`()	Initialize SIR for this synthesis
`invert`([randomize, randomization_ind])	Invert all atmospheres
`invert_external`(algorithm[, use_jacobian])	Invert all atmospheres
`modified_svd_inverse`(H[, tol])	Compute the inverse of the Hessian matrix using a modified SVD, by thresholding each subpsace separately
`normalize_ff`(nodes)	Normalize all filling factors so that they add to one to avoid later problems.
`randomize`()	Randomize all free parameters to lie uniformly in the interval [-2,2] in the transformed domain
`remove_atmosphere`(atm)	Remove unused atmospheres
`remove_unused_atmosphere`()	Remove unused atmospheres
`set_new_model`(nodes)	Set the nodes of the current model to the values passed on the arguments
`set_nlte`(option)	Set calculation of Ca II 8542 A to NLTE
`set_topologies`(topologies)	Set the topologies to be used in the inversion
`setup`()	Setup the model for synthesis/inversion.
`synthesize`([perturbation])	Synthesize all atmospheres
`synthesize_and_compute_rf`([compute_rf, ...])	Compute response functions for all free parameters according to all active_parameters
`synthesize_spectral_region`(spectral_region)	Synthesize all atmospheres for a single spectral region and normalize to the continuum of the quiet Sun at disk center
`use_configuration`(config_dict)	Use a configuration file

backtracking_brent
close_output
exit_hazel
open_output
read_observation
write_output

add_chromosphere(atmosphere)¶

Programmatically add a chromosphere

Parameters:: atmosphere (dict) – Dictionary containing the following data ‘Name’, ‘Spectral region’, ‘Height’, ‘Line’, ‘Wavelength’, ‘Reference atmospheric model’, ‘Ranges’, ‘Nodes’
Return type:: None

add_parametric(atmosphere)¶

Programmatically add a parametric atmosphere

Parameters:: atmosphere (dict) – Dictionary containing the following data ‘Name’, ‘Spectral region’, ‘Wavelength’, ‘Reference atmospheric model’, ‘Type’, ‘Ranges’, ‘Nodes’
Return type:: None

add_photosphere(atmosphere)¶

Programmatically add a photosphere

Parameters:: atmosphere (dict) – Dictionary containing the following data ‘Name’, ‘Spectral region’, ‘Height’, ‘Line’, ‘Wavelength’, ‘Reference atmospheric model’, ‘Ranges’, ‘Nodes’
Return type:: None

add_spectral(spectral)¶

Programmatically add a spectral region

Parameters:: spectral (dict) – Dictionary containing the following data ‘Name’, ‘Wavelength’, ‘Topology’, ‘Weights Stokes’, ‘Wavelength file’, ‘Wavelength weight file’, ‘Observations file’, ‘Mask file’
Return type:: None

add_straylight(atmosphere)¶

Programmatically add a straylight atmosphere

Parameters:: atmosphere (dict) – Dictionary containing the following data ‘Name’, ‘Spectral region’, ‘Reference atmospheric model’, ‘Ranges’, ‘Nodes’
Return type:: None

add_topology(atmosphere_order)¶

Add a new topology

Parameters:: topology (str) – Topology
Return type:: None

backtracking_brent(dchi2, ddchi2, maxiter=10, bounds=[-3.0, 3.0], tol=0.01)¶

backtracking_parabolic(dchi2, ddchi2, direction='down', maxiter=5, lambda_init=0.001, current_chi2=10000000000.0)¶

Do the backtracking to get an optimal value of lambda in the LM algorithm

Parameters:

dchi2 (float) – Gradient of the chi2
ddchi2 (float) – Second order derivatives with which the Hessian is computed
direction (str, optional) – Direction on which do the backtracking (‘down’/’up’ for decreasing/increasing lambda)
maxiter (int) – Maximum number of iterations
lambda_init (float) – Initial value of lambda
current_chi2 (float) – Current best chi2 to compare with those of the backtracking

Returns:

lambda_opt (float) – Optimal value of lambda found. Bracketed value if bracketing has been possible or just the best value otherwise
bracketed (bool) – True if the best value has been bracketed
best_chi2 (float) – Best value of chi2 found

close_output()¶

compute_chi2(only_chi2=False, weights=None)¶

Compute chi2 for all spectral regions

Parameters:

obs (float) – Vector of observations
only_chi2 (bool) – Control whether the gradient and Hessian is returned

Return type:

None

compute_uncertainty()¶

Compute the uncertainty in the parameters at the minimum with the current Hessian

Parameters:: None
Return type:: None

exit_hazel()¶

find_active_parameters(cycle)¶

Find all active parameters in all active atmospheres in the current cycle

Parameters:: cycle (int) – Cycle to consider
Return type:: None

flatten_parameters_to_reference(cycle)¶

Flatten all current parameters to the reference atmosphere

Parameters:: cycle (int) – Current cycle
Return type:: None

init_sir()¶

Initialize SIR for this synthesis. This version does not make use of any external file, which might be not safe when running in MPI mode.

Parameters:: None
Return type:: None

init_sir_external()¶

Initialize SIR for this synthesis

Parameters:: None
Return type:: None

invert(randomize=False, randomization_ind=None)¶

Invert all atmospheres

Parameters:: None
Return type:: None

invert_external(algorithm, use_jacobian=False, **kwargs)¶

Invert all atmospheres

Parameters:: None
Return type:: None

modified_svd_inverse(H, tol=1e-08)¶

Compute the inverse of the Hessian matrix using a modified SVD, by thresholding each subpsace separately

Parameters:

H (float) – Hessian matrix
tol (float) – Tolerance for the singular value of each subspace

Return type:

None

normalize_ff(nodes)¶

Normalize all filling factors so that they add to one to avoid later problems. We use a softmax function to make sure they all add to one and can be unconstrained

ff_i = exp(x_i) / sum(exp(x_i))

Parameters:: None
Return type:: None

open_output()¶

randomize()¶: Randomize all free parameters to lie uniformly in the interval [-2,2] in the transformed domain

read_observation()¶

remove_atmosphere(atm)¶

Remove unused atmospheres

Parameters:: None
Return type:: None

remove_unused_atmosphere()¶

Remove unused atmospheres

Parameters:: None
Return type:: None

set_new_model(nodes)¶

Set the nodes of the current model to the values passed on the arguments

Parameters:: nodes (float) – Array with the new set of nodes
Return type:: None

set_nlte(option)¶

Set calculation of Ca II 8542 A to NLTE

Parameters:: option (bool) – Set to True to use NLTE, False to use LTE

set_topologies(topologies)¶

Set the topologies to be used in the inversion

Parameters:: topologies (list) – List of strings with the names of the topologies
Return type:: None

setup()¶

Setup the model for synthesis/inversion. This setup includes adding the topologies, removing unused atmospheres, reading the number of cycles for the inversion and some sanity checks

Parameters:: None
Return type:: None

synthesize(perturbation=False)¶

Synthesize all atmospheres

Parameters:: perturbation (bool) – Set to True if you are synthesizing with a perturbation. In this case, the synthesis is saved in spectrum.stokes_perturbed instead of spectrum.stokes
Return type:: None

synthesize_and_compute_rf(compute_rf=False, include_jacobian=False)¶

Compute response functions for all free parameters according to all active_parameters

Parameters:: compute_rf (bool (optional, default False)) – If True, then compute the response functions. If not, just compute the synthesis.
Return type:: None

synthesize_spectral_region(spectral_region, perturbation=False)¶

Synthesize all atmospheres for a single spectral region and normalize to the continuum of the quiet Sun at disk center

Parameters:

spectral_region (str) – Spectral region to synthesize
perturbation (bool) – Set to True if you are synthesizing with a perturbation. In this case, the synthesis is saved in spectrum.stokes_perturbed instead of spectrum.stokes

Return type:

None

use_configuration(config_dict)¶

Use a configuration file

Parameters:: config_dict (dict) – Dictionary containing all the options from the configuration file previously read
Return type:: None

write_output(randomization=0)¶

9.2. Photosphere¶

class hazel.photosphere.SIR_atmosphere(working_mode, name='', root='', verbose=0)¶

Bases: General_atmosphere

Methods

`add_active_line`(lines, spectrum, wvl_range, ...)	Add an active lines in this atmosphere
`allocate_info_cycles`(n_cycles)	Set the appropriate variables to store per-cycle models
`get_parameters`()	Get the curent parameters as a model
`init_reference`([check_borders])	Initialize the reference atmosphere to the values of the parameters, doing the inverse transformation if in inversion mode
`interpolate_nodes`(log_tau, reference, nodes, ...)	Generate a model atmosphere by interpolating the defined nodes.
`interpolate_nodes_rf`(log_tau, reference, ...)	Generate a model atmosphere by interpolating the defined nodes.
`list_lines`()	List the lines available in SIR for synthesis
`load_reference_model`(model_file, verbose)	Load a reference model or a model for every pixel for synthesis/inversion
`model_to_nodes`()	Transform from model to nodes
`nodes_to_model`()	Transform from nodes to model
`reset_reference`()	Reset reference model to the original reference loaded from file
`set_parameters`(model, ff, vmac)	Set the parameters of the current model to those passed as argument
`set_reference`([cycle])	Set reference model to that of the current parameters
`synthesize`(stokes_in[, returnRF, nlte])	Carry out the synthesis and returns the Stokes parameters and the response functions to all physical variables at all depths
`to_physical`()	Transform the atmospheric parameters from transformed domain to physical domain given the ranges.
`to_transformed`()	Transform the atmospheric parameters from transformed domain to physical domain given the ranges.

load_nlte_model
print_parameters

add_active_line(lines, spectrum, wvl_range, verbose)¶

Add an active lines in this atmosphere

Parameters:

lines (str) – Line to activate
spectrum (Spectrum) – Spectrum object
wvl_range (float) – Vector containing wavelength range over which to synthesize this line

Return type:

None

get_parameters()¶

Get the curent parameters as a model

Parameters:: None
Returns:: model
Return type:: a 6xN photspheric model

interpolate_nodes(log_tau, reference, nodes, nodes_location)¶

Generate a model atmosphere by interpolating the defined nodes. The interpolation order depends on the number of nodes.

Parameters:

log_tau (float) – Vector of log optical depth at 500 nm
reference (float) – Vector with the reference atmosphere to which the nodes are added
nodes (float) – List with the position of the nodes

Returns:

Vector with the interpolated atmosphere

Return type:

real

interpolate_nodes_rf(log_tau, reference, nodes, lower, upper)¶

Generate a model atmosphere by interpolating the defined nodes. The interpolation order depends on the number of nodes.

Parameters:

log_tau (float) – Vector of log optical depth at 500 nm
reference (float) – Vector with the reference atmosphere to which the nodes are added
nodes (float) – List with the position of the nodes

Returns:

Vector with the interpolated atmosphere

Return type:

real

list_lines()¶: List the lines available in SIR for synthesis

load_nlte_model(verbose)¶

load_reference_model(model_file, verbose)¶

Load a reference model or a model for every pixel for synthesis/inversion

Parameters:

model_file (str) – String with the name of the file. Extensions can currently be “1d” or “h5”
verbose (bool) – Verbosity

Return type:

None

model_to_nodes()¶

Transform from model to nodes

Parameters:: None
Return type:: None

nodes_to_model()¶

Transform from nodes to model

Parameters:: None
Return type:: None

print_parameters(first=False, error=False)¶

set_parameters(model, ff, vmac)¶

Set the parameters of the current model to those passed as argument

Parameters:

model_in (float) – Array with the model
ff (float) – Value of the filling factor
vmac (float) – Value of the macroturbulent velocity

Return type:

None

synthesize(stokes_in, returnRF=False, nlte=False)¶

Carry out the synthesis and returns the Stokes parameters and the response functions to all physical variables at all depths

Parameters:

stokes_in (float) – An array of size [4 x nLambda] with the input Stokes parameter. It is irrelevant in this case because we assume that all SIR atmospheres have the Planck function as boundary.
returnRF (bool, optional) – Return response functions

Returns:

stokes (float) –

Stokes parameters, with the first index containing the wavelength displacement and the remaining
containing I, Q, U and V. Size (5,nLambda)
rf (float (optional)) –

Response functions to T, Pe, vmic, B, v, theta, phi, all of size (4,nLambda,nDepth), plus the RF to macroturbulence of size (4,nLambda)
It is not returned if returnRF=False

9.3. Chromosphere¶

class hazel.chromosphere.Hazel_atmosphere(working_mode, name='')¶

Bases: General_atmosphere

Methods

`add_active_line`(line, spectrum, wvl_range)	Add an active lines in this atmosphere
`allocate_info_cycles`(n_cycles)	Set the appropriate variables to store per-cycle models
`init_reference`([check_borders])	Initialize the reference atmosphere to the values of the parameters, doing the inverse transformation if in inversion mode
`load_reference_model`(model_file, verbose)	Load a reference model or a model for every pixel for synthesis/inversion
`nodes_to_model`()	Transform from nodes to model
`reset_reference`()	Reset reference model to the original reference loaded from file
`set_parameters`(pars, ff)	Set the parameters of this model chromosphere
`set_reference`([cycle])	Set reference model to that of the current parameters
`synthesize`([stokes, returnRF, nlte])	Carry out the synthesis and returns the Stokes parameters
`to_physical`()	Transform the atmospheric parameters from transformed domain to physical domain given the ranges.
`to_transformed`()	Transform the atmospheric parameters from transformed domain to physical domain given the ranges.

print_parameters
select_coordinate_system

add_active_line(line, spectrum, wvl_range)¶

Add an active lines in this atmosphere

Parameters:

lines (str) – Line to activate: [‘10830’,’5876’]
spectrum (Spectrum) – Spectrum object
wvl_range (float) – Vector containing wavelength range over which to synthesize this line

Return type:

None

load_reference_model(model_file, verbose)¶

Load a reference model or a model for every pixel for synthesis/inversion

Parameters:

model_file (str) – String with the name of the file. Extensions can currently be “1d” or “h5”
verbose (bool) – verbosity flag

Return type:

None

nodes_to_model()¶

Transform from nodes to model

Parameters:: None
Return type:: None

print_parameters(first=False, error=False)¶

select_coordinate_system()¶

set_parameters(pars, ff)¶

Set the parameters of this model chromosphere

Parameters:

pars (list of float) – This list contains the following parameters in order: Bx, By, Bz, tau, v, delta, beta, a
ff (float) – Filling factor

Return type:

None

synthesize(stokes=None, returnRF=False, nlte=None)¶

Carry out the synthesis and returns the Stokes parameters

Parameters:

stokes (float) – An array of size [4 x nLambda] with the input Stokes parameter.

Returns:

stokes –

Stokes parameters, with the first index containing the wavelength displacement and the remaining: containing I, Q, U and V. Size (4,nLambda)

Return type:

float

9.4. Parametric¶

class hazel.parametric.Parametric_atmosphere(working_mode, name='')¶

Bases: General_atmosphere

Methods

`add_active_line`(spectrum, wvl_range)	Add an active lines in this atmosphere
`allocate_info_cycles`(n_cycles)	Set the appropriate variables to store per-cycle models
`init_reference`([check_borders])	Initialize the reference atmosphere to the values of the parameters, doing the inverse transformation if in inversion mode
`load_reference_model`(model_file, verbose)	Load a reference model or a model for every pixel for synthesis/inversion
`nodes_to_model`()	Transform from nodes to model
`reset_reference`()	Reset reference model to the original reference loaded from file
`set_parameters`(pars, ff)	Set parameters of the model
`set_reference`([cycle])	Set reference model to that of the current parameters
`synthesize`([stokes, nlte])	Carry out the synthesis and returns the Stokes parameters
`to_physical`()	Transform the atmospheric parameters from transformed domain to physical domain given the ranges.
`to_transformed`()	Transform the atmospheric parameters from transformed domain to physical domain given the ranges.

print_parameters

add_active_line(spectrum, wvl_range)¶

Add an active lines in this atmosphere

Parameters:: None
Return type:: None

load_reference_model(model_file, verbose)¶

Load a reference model or a model for every pixel for synthesis/inversion

Parameters:

model_file (str) – String with the name of the file. Extensions can currently be “1d” or “h5”
verbose (bool) – verbosity flag

Return type:

None

nodes_to_model()¶

Transform from nodes to model

Parameters:: None
Return type:: None

print_parameters(first=False, error=False)¶

set_parameters(pars, ff)¶

Set parameters of the model

Parameters:

pars (list of floats) – Values of the parameters: lambda0, sigma, depth, a
ff (float) – Filling factor

Return type:

None

synthesize(stokes=None, nlte=None)¶

Carry out the synthesis and returns the Stokes parameters

Parameters:

stokes (float) – An array of size [4 x nLambda] with the input Stokes parameter.

Returns:

stokes –

Stokes parameters, with the first index containing the wavelength displacement and the remaining: containing I, Q, U and V. Size (4,nLambda)

Return type:

float

9.5. Multiprocess¶

class hazel.multiprocess.Iterator(use_mpi=False)¶

Bases: object

Methods

`mpi_parent_work`([start, end])	MPI parent work
`mpi_workers_work`()	MPI workers work
`nonmpi_work`([start, end])	Do the synthesis/inversion for all pixels in the models
`run_all_pixels`([start, end])	Run synthesis/inversion for all pixels

cleanup
get_rank
use_model

cleanup(*args)¶

get_rank(n_workers=0)¶

mpi_parent_work(start=0, end=None)¶

MPI parent work

Parameters:

start (int) – Initial pixel, by default 0
end (int) – Final pixel, by default the number of pixels in the observations

Return type:

None

mpi_workers_work()¶

MPI workers work

Parameters:: None
Return type:: None

nonmpi_work(start=0, end=None)¶

Do the synthesis/inversion for all pixels in the models

Parameters:: model (model) – Model to be synthesized
Return type:: None

run_all_pixels(start=0, end=None)¶

Run synthesis/inversion for all pixels

Parameters:

start (int, optional) – Initial pixel, by default 0
end (int) – Final pixel, by default the number of pixels in the observations

use_model(model=None)¶

class hazel.multiprocess.tags(value)¶

Bases: IntEnum

An enumeration.

DONE = 1¶

DONOTHING = 4¶

EXIT = 2¶

READY = 0¶

START = 3¶

9.6. Stray-light¶

class hazel.stray.Straylight_atmosphere(working_mode, name='')¶

Bases: General_atmosphere

Methods

`add_active_line`(spectrum, wvl_range)	Add an active lines in this atmosphere
`allocate_info_cycles`(n_cycles)	Set the appropriate variables to store per-cycle models
`init_reference`([check_borders])	Initialize the reference atmosphere to the values of the parameters, doing the inverse transformation if in inversion mode
`load_reference_model`(model_file, verbose)	Load a reference model or a model for every pixel for synthesis/inversion
`nodes_to_model`()	Transform from nodes to model
`reset_reference`()	Reset reference model to the original reference loaded from file
`set_reference`([cycle])	Set reference model to that of the current parameters
`set_straylight`(stokes)	Load a reference model or a model for every pixel for synthesis/inversion
`synthesize`([nlte])	Carry out the synthesis and returns the Stokes parameters
`to_physical`()	Transform the atmospheric parameters from transformed domain to physical domain given the ranges.
`to_transformed`()	Transform the atmospheric parameters from transformed domain to physical domain given the ranges.

print_parameters
set_parameters

add_active_line(spectrum, wvl_range)¶

Add an active lines in this atmosphere

Parameters:: None
Return type:: None

load_reference_model(model_file, verbose)¶

Load a reference model or a model for every pixel for synthesis/inversion

Parameters:

model_file (str) – String with the name of the file. Extensions can currently be “1d” or “h5”
verbose (bool) – verbosity flag

Return type:

None

nodes_to_model()¶

Transform from nodes to model

Parameters:: None
Return type:: None

print_parameters(first=False, error=False)¶

set_parameters(pars, ff)¶

set_straylight(stokes)¶

Load a reference model or a model for every pixel for synthesis/inversion

Parameters:

model_file (str) – String with the name of the file. Extensions can currently be “1d” or “h5”
verbose (bool) – verbosity flag

Return type:

None

synthesize(nlte=None)¶

Carry out the synthesis and returns the Stokes parameters

Parameters:

None

Returns:

stokes –

Stokes parameters, with the first index containing the wavelength displacement and the remaining: containing I, Q, U and V. Size (4,nLambda)

Return type:

float

9.7. Tools¶

class hazel.tools.File_chromosphere(file=None, mode='single')¶

Bases: object

Class that defines a model atmosphere and can be used to easily save observations

Methods

`save`(file[, default])	Save the curent observation
`set_default`([n_pixel, default])	Set the atmosphere to one of the default ones available in the code
`set_size`([n_pixel])	Set the number of pixels of the current atmosphere

save(file, default=None)¶

Save the curent observation

Parameters:: file (str) – Name of the output files. Extensions will be added to it
Return type:: None

set_default(n_pixel=1, default='disk')¶

Set the atmosphere to one of the default ones available in the code

Parameters:

n_pixel (int (optional, equal to 1 as default)) – Number of pixels of the output
default (str ('disk' -> on-disk observations, 'offlimb' -> off-limb observations))

Return type:

None

set_size(n_pixel=1)¶

Set the number of pixels of the current atmosphere

Parameters:: n_pixel (int (optional, equal to 1 as default)) – Number of pixels of the output
Return type:: None

class hazel.tools.File_observation(file=None, mode='single')¶

Bases: object

Class that defines an observation. This can be used to easily save observations in the appropriate format

Methods

`save`(file)	Save the curent observation
`set_size`(n_lambda[, n_pixel])	Set the number of wavelengths and number of pixels of the current observation

save(file)¶

Save the curent observation

Parameters:: file (str) – Name of the output files. Extensions will be added to it
Return type:: None

set_size(n_lambda, n_pixel=1)¶

Set the number of wavelengths and number of pixels of the current observation

Parameters:

n_lambda (int) – Number of wavelength points
n_pixel (int (optional, equal to 1 as default)) – Number of pixels of the output

Return type:

None

class hazel.tools.File_photosphere(file=None, mode='single')¶

Bases: object

Class that defines a model photosphere and can be used to easily save observations

Methods

`save`(file[, default])	Save the curent model
`set_default`([n_pixel, default])	Set the atmosphere to one of the default ones available in the code
`set_size`(nz[, n_pixel])	Set the number of depth points and number of pixels of the current atmosphere

list_models

list_models()¶

save(file, default=None)¶

Save the curent model

Parameters:: file (str) – Name of the output files. Extensions will be added to it
Return type:: None

set_default(n_pixel=1, default='hsra')¶

Set the atmosphere to one of the default ones available in the code

Parameters:

n_pixel (int (optional, equal to 1 as default)) – Number of pixels of the output
default (str ('hsra' -> Harvard-Smithsonian Reference Atmosphere))

Return type:

None

set_size(nz, n_pixel=1)¶

Set the number of depth points and number of pixels of the current atmosphere

Parameters:

nz (int) – Number of depth points of the atmosphere
n_pixel (int (optional, equal to 1 as default)) – Number of pixels of the output

Return type:

None