API documentation#

GCOG#

class lotus_nlte.gcogs.gcog.SingleGCOG(wavelength, ep, element, stellar_type, cal, interpolated=False, ewlibpath=None, keys=None, atmos_pars=None)[source]#

Base class for General Curve of Growth (GCOG)

This intends for assemble discrete relationship between theoretical EW with other atsmopheric stellar parameters.

Parameters

  • wavelength (float) – Target line wavelength

  • ep (float) – Target line excitation potential , in unit of ev

  • element (str) – “FeI” or “FeII”

  • stellar_type (str) –

    The stellar type of your star, like:

    {spectral type, e.g. F, G, K}/{giant or subgiant or dwarf}/{metal_rich or metal_poor or very_metal_poor} or

    the estimation of your atmospheric parameters in such form:

    {T_low}_{T_high}/{logg_low}_{logg_high}/{[Fe/H]_low}_{[Fe/H]_high}

  • cal (str) – Types of EW, e.g. “lte” or “nlte”

  • interpolated (bool, optional) – True: use interpolated GCOG False: get GCOG from EW library

  • ewlibpath (None or str) – if interpolted==False, this must be assigned for assemble GCOG as the path for the libary of EW, it must be a h5 file if interpolated==True, this can be None

  • keys (None or list of str) – if interpolted==False, this should be the target keys of ewlib if interpolated=True, this can be None

  • atmos_pars (None or list) – if interpolted==False, this should be the target keys of ewlib, the shape of the list is (N_selected_gridpoints, 4) if interpolated==True, this can be None

assemble_hyper_surface()[source]#

Collect EW and other stellar parameters from library and assemble them into an array

Returns

An array with a shape of (N, 5), N is the number of grid points in your targerted region of library, this depends on the parameter of stellar_type

Return type

ndarray

load_model()[source]#

Load interpolated model for a single line

Raises

ValueError – interpolated==False, there is no interpolated model to import

Returns

m – interpolated model

Return type

sklearn.pipeline.Pipeline

plot_interpolated_cog(teff, logg, vt, ews=None)[source]#

Plot interpolated Curve of Growth

Parameters

  • teff (int or float) – which Teff the COG is at

  • logg (int or float) – which logg the COG is at

  • vt (int or float) – which microturbulen velocity the COG is at

  • ews (list or ndarray, optional) – . The default is None, then EWs are using from 1 $moverset{circ}A$ to 100$moverset{circ}A$.

Raises

ValueError – interpolated==False, there is no interpolated model to import

Returns

fig – plot for COG

Return type

matplotlib.figure.Figure

class lotus_nlte.gcogs.MultiGCOG(star, stellar_type, obs_path, cal='nlte', exp_cutoff=0, ewlibpath=None, interpolation=False, use_tarfile=True)[source]#

Base class for General Curve of Growth (GCOG) of multiple lines

This intends for assemble GCOG of multiple lines.

Parameters

  • star (str) – The name of target star

  • stellar_type (str:) –

    The stellar type of your star, like:

    {spectral type, e.g. F, G, K}/{giant or subgiant or dwarf}/{metal_rich or metal_poor or very_metal_poor} or

    the estimation of your atmospheric parameters in such form:

    {{T_low}_{T_high}/{logg_low}_{logg_high}/{feh_low}_{feh_high}}

  • obs_path (str) – Path of the observation ew list of the target star

  • cal (str) – Types of derivation, e.g. “lte” or “nlte”

  • exp_cutoff (int or float) – Cutoff of excitation potential during the derivation, in the unit of ev

  • ewlibpath (str) – The path for the libary of EW, it must be a h5 file

  • interpolation (bool, default: False) – True: use interpolated GCOG False: get GCOG from EW library

  • use_tarfle (bool, default: True) –

    True: use compressed version of GCOG models False: not use the compressed tarfile and this might specify the path for GCOG models or

    generate a new directory for storing generated GCOG models from EW library if interpolation==False

pipelines()[source]#

Method that can select lines with accurate and precise abundance prediction

Return type

None.

remove_outliers(abunds, **kwargs)[source]#

Remove outliers according to the derived abundance

Parameters

abunds (ndarray) – Derived abdunaces from GCOG

class lotus_nlte.gcogs.PolyMultiGCOG(star, stellar_type, obs_path, exp_cutoff=0, ew_error=5, ewlibpath=None, ewdiffpath=None, interpolation=False, use_tarfile=True, cal='nlte')[source]

Sub class for General Curve of Growth (GCOG) of multiple lines based on multivariate polynomial regresssion

Parameters

ew_error (float or int) – Max of the deviation of EW allowed for the predicted EW from multivariate polynomial model if mean(pred)+std(pred) > ew_error or mean(prea)-std(pred) < -ew_error, the line doesn’t pass the precision test

pipelines()

Method that can select lines with accurate and precise abundance prediction

Return type

None.

remove_outliers(abunds, **kwargs)

Remove outliers according to the derived abundance

Parameters

abunds (ndarray) – Derived abdunaces from GCOG

lotus_nlte.gcogs.utils.get_keys_and_atmos_pars(ewlibpath, stellar_type)[source]#

Get keys of the EW library for corresponding combinations of atmospheric stellar parameters, given the type of star.

Parameters

  • ewlibpath (str) – The path for the libary of EW, it must be a h5 file

  • stellar_type (str) –

    The stellar type of your star, like:

    {spectral type, e.g. F, G, K}/{giant or subgiant or dwarf}/{metal_rich or metal_poor or very_metal_poor} or

    the estimation of your atmospheric parameters in such form:

    {{T_low}_{T_high}/{logg_low}_{logg_high}/{feh_low}_{feh_high}}

Returns

  • keys (list of strs) – Keys of corresponding combinations of atmospheric stellar parameters

  • ini_cents (list) – the list of stellar parameters given the range defined by the stellar type the shape of the list is (N_selected_gridpoints, 4)

lotus_nlte.gcogs.utils.find_closest_model(wl, ep, ele, search_path, interp_method, interpolation, tarfile=None)[source]#

Find closest interpolated model under designated direcctory

Parameters

  • wl (float) – wavelength of line

  • ep (float) – excitation potential of line

  • ele (str) – “FeI” or “FeII”

  • search_path (str) – designated directory

  • interp_method (str) – “[2-5]” for multivariate polynomial interpolation

  • interpolation (bool) – True: use interpolated GCOG False: get GCOG from EW library

  • tarfile (tarfile.Tarfile or None) – if None, search closest model in a directory else search in a tarfile

Returns

length > 0 : closest model found; length = 0 : can’t find closest model

Return type

list

Interpolation#

class lotus_nlte.interpolation.MultivariatePolynomialInterpolation(X, Y, degree)[source]#

Multivariate polynomial interpolator

Parameters

  • X (list or ndarray, (N,4)) – [Teff, logg, vt, EW]

  • Y (list or ndarray, (N,1)) – [Fe/H]

  • degree (int) – degree of polynomial

fit(**kargs)[source]#

Compute interpolation.

Parameters

**kargs (dict) – args into sklearn PolynomicalFeatures and LinearRegression

Returns

model – interpolated model

Return type

sklearn.pipeline.Pipeline

Optimization#

class lotus_nlte.optimize.StellarOptimization(mgcog, physicaltol=1e-05)[source]#

Base class for stellar parameter opimization

Parameters

  • mgcog – lotus_nlte.gcog.MultiGCOG

  • physicaltol – torelence for stopping the iteration of optimization

checkintols(xk)[source]#

Check if proposal match with the convergence condition

Parameters

xk (list) – proposal, [Teff, logg, vt]

Returns

Whether to stop the optimization

Return type

bool

fun_der(stellar_parameters)[source]#

Calculate first derivatives

Parameters

stellar_parameters (list) – stellar parameter at the minimization of function

Returns

Jacobian function

Return type

ndarray

fun_hess(stellar_parameters, **kargs)[source]#

Calculate second derivatives

Parameters

  • stellar_parameters (list) – stellar parameter at the minimization of function

  • **kargs (dict) – args feed to Hessian matrix functon

Returns

Hessian matrix

Return type

ndarray

generate_met(model, teff, logg, vt, ew)[source]#

Generate metalicity for single line given the interpolated model and proposed stellar paramters and its observed EW.

Parameters

  • model (sklearn.pipeline.Pipeline) – interpolated model

  • teff (int or float) – Teff

  • logg (int or float) – logg

  • vt (int or float) – micro-turbulence velocity

  • ew (int or float) – observed EW

Returns

predict_y – Predicted metalicity given by Teff, logg, vt and EW

Return type

number

log_likelihood(theta)[source]#

Calculate loglikehood function at the proposed stellar parameters

Parameters

theta (list or ndarray) – [Teff, logg, vt]

Returns

loglikehood function

Return type

Number

minimisation_function(stellar_parameters)[source]#

Calculate objective function given proposed stellar parameters

Parameters

stellar_parameters (list) – [Teff, logg, vt]

Returns

objective function

Return type

Number

obs_calculation(gen_met, obs_ele, obs_ew, obs_wavelength, obs_ep, gen_met_err=None)[source]#

Calculate observed slope between excitation potentials and abundances, the slope between reduced equivalent widths and abundances and the difference between abundances of FeI and FeII

Parameters

  • gen_met (list) – Predicted metalicity for every lines

  • obs_ele (ndarray) – Species for the observed lines

  • obs_ew (ndarray) – EWs for the observed lines

  • obs_wavelength (ndarray) – Wavelength for the observed lines

  • obs_ep (ndarray) – Excitation potential for the observed lines

  • gen_met_err (ndarray, optional) – Not implemented yet. The default is None.

Returns

[the slope between excitation potentials and abundances, the slope between reduced equivalent widths and abundances, the difference between abundances of FeI and FeII]

Return type

List

optimize(method_func, callback=None, **kargs)[source]#

Optimization wrapper

Parameters

  • method_func (func) – scipy.optimize.differential_evolution or scipy.optimization.shgo

  • callback (func, None) – Callback function. The default is None.

  • **kargs (dict) – args feed into method_func

Returns

optimization progress

Return type

func

uncertainty(result)[source]#

Uncertainty estimation according given the Hessian Matrix

Parameters

result (dict) – result containing optimization result

class lotus_nlte.optimize.DiffEvoStellarOptimization(mgcog, bounds=None, physicaltol=1e-05)[source]#

Optimizer using Differential Evolution Algorithm, wrapped from scipy.optimize.differential_evolution

Parameters

  • bounds – list of tuples, None

  • None (if) –

  • grid (use the boundary of our) –

checkintols(xk)#

Check if proposal match with the convergence condition

Parameters

xk (list) – proposal, [Teff, logg, vt]

Returns

Whether to stop the optimization

Return type

bool

fun_der(stellar_parameters)#

Calculate first derivatives

Parameters

stellar_parameters (list) – stellar parameter at the minimization of function

Returns

Jacobian function

Return type

ndarray

fun_hess(stellar_parameters, **kargs)#

Calculate second derivatives

Parameters

  • stellar_parameters (list) – stellar parameter at the minimization of function

  • **kargs (dict) – args feed to Hessian matrix functon

Returns

Hessian matrix

Return type

ndarray

generate_met(model, teff, logg, vt, ew)#

Generate metalicity for single line given the interpolated model and proposed stellar paramters and its observed EW.

Parameters

  • model (sklearn.pipeline.Pipeline) – interpolated model

  • teff (int or float) – Teff

  • logg (int or float) – logg

  • vt (int or float) – micro-turbulence velocity

  • ew (int or float) – observed EW

Returns

predict_y – Predicted metalicity given by Teff, logg, vt and EW

Return type

number

log_likelihood(theta)#

Calculate loglikehood function at the proposed stellar parameters

Parameters

theta (list or ndarray) – [Teff, logg, vt]

Returns

loglikehood function

Return type

Number

minimisation_function(stellar_parameters)#

Calculate objective function given proposed stellar parameters

Parameters

stellar_parameters (list) – [Teff, logg, vt]

Returns

objective function

Return type

Number

obs_calculation(gen_met, obs_ele, obs_ew, obs_wavelength, obs_ep, gen_met_err=None)#

Calculate observed slope between excitation potentials and abundances, the slope between reduced equivalent widths and abundances and the difference between abundances of FeI and FeII

Parameters

  • gen_met (list) – Predicted metalicity for every lines

  • obs_ele (ndarray) – Species for the observed lines

  • obs_ew (ndarray) – EWs for the observed lines

  • obs_wavelength (ndarray) – Wavelength for the observed lines

  • obs_ep (ndarray) – Excitation potential for the observed lines

  • gen_met_err (ndarray, optional) – Not implemented yet. The default is None.

Returns

[the slope between excitation potentials and abundances, the slope between reduced equivalent widths and abundances, the difference between abundances of FeI and FeII]

Return type

List

optimize(method_func=<function differential_evolution>, **kargs)[source]#

Optimization wrapper

Parameters

  • method_func (func) – scipy.optimize.differential_evolution or scipy.optimization.shgo

  • callback (func, None) – Callback function. The default is None.

  • **kargs (dict) – args feed into method_func

Returns

optimization progress

Return type

func

uncertainty(result)#

Uncertainty estimation according given the Hessian Matrix

Parameters

result (dict) – result containing optimization result

class lotus_nlte.optimize.ShgoStellarOptimization(mgcog, bounds=None, physicaltol=1e-05)[source]#

Optimizer using SHG optimization, wrapped from scipy.optimize.shgo

Parameters

  • bounds – list of tuples, None

  • None (if) –

  • grid (use the boundary of our) –

checkintols(xk)#

Check if proposal match with the convergence condition

Parameters

xk (list) – proposal, [Teff, logg, vt]

Returns

Whether to stop the optimization

Return type

bool

fun_der(stellar_parameters)#

Calculate first derivatives

Parameters

stellar_parameters (list) – stellar parameter at the minimization of function

Returns

Jacobian function

Return type

ndarray

fun_hess(stellar_parameters, **kargs)#

Calculate second derivatives

Parameters

  • stellar_parameters (list) – stellar parameter at the minimization of function

  • **kargs (dict) – args feed to Hessian matrix functon

Returns

Hessian matrix

Return type

ndarray

generate_met(model, teff, logg, vt, ew)#

Generate metalicity for single line given the interpolated model and proposed stellar paramters and its observed EW.

Parameters

  • model (sklearn.pipeline.Pipeline) – interpolated model

  • teff (int or float) – Teff

  • logg (int or float) – logg

  • vt (int or float) – micro-turbulence velocity

  • ew (int or float) – observed EW

Returns

predict_y – Predicted metalicity given by Teff, logg, vt and EW

Return type

number

log_likelihood(theta)#

Calculate loglikehood function at the proposed stellar parameters

Parameters

theta (list or ndarray) – [Teff, logg, vt]

Returns

loglikehood function

Return type

Number

minimisation_function(stellar_parameters)#

Calculate objective function given proposed stellar parameters

Parameters

stellar_parameters (list) – [Teff, logg, vt]

Returns

objective function

Return type

Number

obs_calculation(gen_met, obs_ele, obs_ew, obs_wavelength, obs_ep, gen_met_err=None)#

Calculate observed slope between excitation potentials and abundances, the slope between reduced equivalent widths and abundances and the difference between abundances of FeI and FeII

Parameters

  • gen_met (list) – Predicted metalicity for every lines

  • obs_ele (ndarray) – Species for the observed lines

  • obs_ew (ndarray) – EWs for the observed lines

  • obs_wavelength (ndarray) – Wavelength for the observed lines

  • obs_ep (ndarray) – Excitation potential for the observed lines

  • gen_met_err (ndarray, optional) – Not implemented yet. The default is None.

Returns

[the slope between excitation potentials and abundances, the slope between reduced equivalent widths and abundances, the difference between abundances of FeI and FeII]

Return type

List

optimize(method_func=<function shgo>, **kargs)[source]#

Optimization wrapper

Parameters

  • method_func (func) – scipy.optimize.differential_evolution or scipy.optimization.shgo

  • callback (func, None) – Callback function. The default is None.

  • **kargs (dict) – args feed into method_func

Returns

optimization progress

Return type

func

uncertainty(result)#

Uncertainty estimation according given the Hessian Matrix

Parameters

result (dict) – result containing optimization result

Sampling#

lotus_nlte.sampling.slicesampling(log_likelihood, mgcog, priors, priors_stderr, bounds, ndraws=1000, ntunes=200, chains=4)[source]#

Slice sampling wrapper

Parameters

  • log_likelihood (lotus_nlte.optimize.StellarOptimization.log_likelihood) – calculate log likelihood function

  • mgcog (lotus_nlte.gcogs.MultiGCOG) – Instance of MultiGCOG

  • priors (list or ndarray) – Priors of Teff, logg, vt

  • priors_stderr (list or ndarray) – Estimated priors standard deviation

  • bounds (list of tuple) – boundary for parameters

  • ndraws (int, optional) – Number of draws. The default is 1000.

  • ntunes (int, optional) – Number of tunning(burning). The default is 200.

  • chains (int, optional) – Number of chains. The default is 4.

Returns

trace – Contains all samples up to the current iteration

Return type

MultiTrace

Plot#

lotus_nlte.plot.plot_optimized_equilibrium(star, opt_stellarpars, fit_pars, REWs1, REWs2, chis1, chis2, abunds1, abunds2, abunds1_err=None, abunds2_err=None)[source]#

Plot for abundances vs reduced EWs and abundances vs excitation potential given stellar parameters.

Parameters

  • star (str) – Name of star

  • opt_stellarpars (dict) – Contains Teff, logg, vt and their uncertainty

  • fit_pars (list) – [dict(linear fitting of A vs REW), dict(linear fitting of A vs chi)]

  • REWs1 (list or ndarray) – Reduced EWs for FeI

  • REWs2 (list or ndarray) – Reduced EWs for FeII

  • chis1 (list or ndarray) – Excitation potential for FeI

  • chis2 (list or ndarray) – Excitation potential for FeI

  • abunds1 (list of ndarry) – Abundances of FeI

  • abunds2 (list of ndarry) – Abundances of FeI

  • abunds1_err (list of ndarray, optional) – Error of derived abundances of FeI (not implemeted yet). The default is None.

  • abunds2_err (list of ndarray, optional) – Error of derived abundances of FeII (not implemeted yet). The default is None.

Returns

fig – plot for equiibira

Return type

matplotlib.figure.Figure

lotus_nlte.plot.plot_results_brute(result, grid, best_vals=True, varlabels=None, output=None)[source]#

Visualize the result of the optimization results.

The output file will display the chi-square value per parameter and contour plots for all combination of two parameters.

Inspired by the corner package (https://github.com/dfm/corner.py).

Parameters

  • result (MinimizerResult) – Contains the results from the brute() method.

  • best_vals (bool, dict) – Whether to show the best values from the grid search (default is True). if this is a bool, then the parameters in result will be used for ploting; if this a dictionary then values in this dictionary will be used for ploting.

  • varlabels (list, optional) – If None (default), use result.var_names as axis labels, otherwise use the names specified in varlabels.

  • output (str, optional) – Name of the output PDF file (default is ‘None’)

Returns

fig – plot for element-wise objective function values at proposed grid points

Return type

matplotlib.figure.Figure