antaress.ANTARESS_general.utils module

npint(array)

Integer conversion

Converts an array to integer type.

Parameters:

TBD

Returns:

TBD

default_func(*x)

Unity function.

Returns 1 for any set of input arguments (used as default function).

Parameters:

x (various) – input variables

Returns:

gen_output (array) – unity array

nantest(varname, var)

Nan/Inf test.

Checks whether input variable is nan or inf.

Parameters:

TBD

Returns:

TBD

stop(message=None)

Stop routine

Stops process with optional message.

Parameters:

message (str) – stop message

Returns:

None

find_between(s, start, end)

In-between string search

Finds the substring between two substrings of a string. The two substrings must be unique.

Parameters:

TBD

Returns:

TBD

dicval(dic, key, def_val)

Missing dictionary key

Returns the value associated with an existing key in a dictionary, or a user-defined value for missing keys.

Parameters:

• dic (dict) – input dictionary

• key (float) – input key

• def_val (any) – default value for missing keys

Returns:

out_val (any) – value associated with key or default value

get_time()

Current time.

Returns current time.

Parameters:

None

Returns:

start_time (float) – current time

end(start_time, id_time='')

Time stop.

Returns elapsed time.

Parameters:

start_time (float) – start time

Returns:

delta_time (float) – elapsed time

get_pw10(x)

Find power of ten.

For a given x, finds n so that \(x = y 10^n\), with \(1 < |y| < 10\).

Parameters:

x (float) – input value

Returns:

:math:`10^n` (n integer) – power of ten associated with x

dup_edges(x, xblue=None, xred=None)

Duplicate edges.

Attribute edge values to each side of an undefined table.

Parameters:

x (arr, float) – input array with possibly undefined values

Returns:

x (arr, float) – input array with fully defined values

np_where1D(cond)

1D where.

Simplified numpy where function in 1D.

Parameters:

cond (conditional statement) – condition on 1D array

Returns:

idx_cond (array) – array of indexes validating condition

step_range(start, stop, step)

Range with step.

Return all points x between \(x_\mathrm{start}\) and \(x_\mathrm{stop}\) separated by \(dx\)

\[x = x_\mathrm{start} + i x_\mathrm{step} <= x_\mathrm{stop}\]

Parameters:

TBD

Returns:

TBD

closest(x_tab, x_val)

Closest value : 1D.

Returns index of closest value in a 1D array.

Parameters:

• x_tab (array, float) – searched 1D array

• x_val (float) – input value

Returns:

idx (int) – index of value closest to x_val in x_tab

closest_Ndim(x_tab, x_val)

Closest value : ND.

Returns index of closest values along the first dimension of an array.

Parameters:

• x_tab (array, float) – searched multi-dimensional array

• x_val (float) – input value

Returns:

idx (list, int) – indexes of values closest to x_val along the first dimension of x_tab

closest_arr(x_tab, x_val)

Closest array.

Returns index of closest values from an array in another array.

Parameters:

• x_tab (array, float) – searched multi-dimensional array

• x_val (array, float) – input array values (must be sorted)

Returns:

idx (array, int) – indexes of values closest to x_val within x_tab

findgen(n, int=False)

IDL findgen.

Returns array of requested type with values increasing from 0 to n by step of 1.

Parameters:

TBD

Returns:

TBD

upsample(x, sample=2)

Upsampling.

Upsamples array by integer factor. Array values do not have to be equidistant.

Parameters:

TBD

Returns:

TBD

def_edge_tab(cen_bins, dim=2)

Bins edge definition

Defines edges of input, centered, bins.

Parameters:

TBD

Returns:

TBD

check_data(file_paths, vis=None, silent=False)

Data check

Checks that ANTARESS data is saved on disk.

Parameters:

TBD

Returns:

TBD

dataload_npz(path)

Npz retrieval.

Simplified call to function uploading npz file with data field.

Parameters:

TBD

Returns:

None

datasave_npz(path, data)

Npz saving.

Simplified call to function saving npz file with data field.

Parameters:

TBD

Returns:

None

path_nonpz(path)

npz path.

Ensures that the path used by dataload_npz() or datasave_npz() has no .npz extension

Parameters:

path (str) – path to a .npz

Returns:

path (str) – path to a .npz

path(path)

Slash path.

Ensures that a string that points to a folder (as a filepath) has a slash at the end.

Parameters:

path (str) – path to a folder

Returns:

path (str) – path to a folder

path_singslash(path)

Single slash path.

Ensures that a string that points to a folder (as a filepath) has only single slashes.

Parameters:

path (str) – path to a folder

Returns:

path (str) – path to a folder

import_module(mod_path)

Import python module.

Reads file at mod_path and loads it as a python module.

Parameters:

mod_path (str) – absolute path or name of the python file (if within current directory) to import, ending with .py

Returns:

module () – loaded module

is_odd(x)

Odd check.

Cheks whether a variable is odd.

Parameters:

x (array, float) – input variable

Returns:

cond_odd (array, bool) – True if x is odd

factrial(x)

Factorial.

Simplified call to numpy factorial of input variable.

Parameters:

x (int) – input variable.

Returns:

fact_x (int) – factorial of x

closest_mod(x, p, y)

Closest modulo.

Given x, p, y, returns the value of \(x +- n \times p\) closest to y. This is equivalent to finding the largest n so that \([ (x - y)/p ] +- n\) is closest to 0.

Parameters:

• x (float or array) – dividend.

• p (float or array) – divisor.

• y (float or array) – target.

Returns:

r (float or array) – remainder

conv_log(var_tab, log_mod)

Log conversion

Returns either the log10 or the original of the input value, upon request.

Parameters:

TBD

Returns:

TBD

np_hyp2f2(z)

Voigt integration

Returns the integral of a Voigt profile, with broadcasting (original function cannot be used with arrays), based on Hypergeometric mpmath function.

Parameters:

TBD

Returns:

TBD

dichotomy(low, high, f, x)

Dichotomy

Returns the value v between low and high such that \(f(v)=x\) using a dichotomic search.

If v is not in [low, high], returns -1.

Assumes that f is an increasing function (i.e. \(f(a)>f(b)\) for \(a>b\)). If f is a decreasing function, use -f.

Parameters:

TBD

Returns:

TBD

convol_contin(x_grid, dx_grid, y_tab, kern, hw_kern)

Convolution with tabulated kernel.

Convolves a tabulated profile F with a tabulated (continuously-defined) kernel k.

The convolved profile is expressed as

\[\begin{split}F_\mathrm{conv}(x) &= \int_{t}( F(x-t) k_\mathrm{norm}(t) dt) \\ \mathrm{where \,} &k_\mathrm{norm}(t) = \frac{k(t)}{\int_{u}(k(u) du)}\end{split}\]

With \(F_\mathrm{conv}\) and F in the same units (thus \(k_\mathrm{norm}\) in units of \([dt^{-1}]\)), and \(k_\mathrm{norm}\) normalized to an integral unity.

Expressed in the discrete domain, the convolution writes as (see http://www.exelisvis.com/docs/CONVOL.html)

\[\begin{split}F_\mathrm{conv}(x) &= \sum_{i=0}^{m-1}( F( x+i-hm ) k(i) ) \mathrm{\, if \,} hm <= x <= n-hm-1 \\ &= F(0) \sum_{i=0}^{hm-x-1} ( k(i) ) + \sum_{i=hm-x:m-1} ( F( x+i-hm ) k(i) ) \mathrm{\, if \,} x < hm \\ &= \sum_{i=0}^{n-1+hm-x} ( F( x+i-hm ) k(i) ) + F(n-1) \sum_{i=n+hm-x,m-1} ( k(i) ) \mathrm{\, if \,} x > n-hm-1\end{split}\]

With F the function to be convolved (dimension n), and m the kernel (dimension k). This can also be written with \((j=x+i-hm -> i=j-x+hm)\) and \((m - hm = hm)\) as:

\[\begin{split}F_\mathrm{conv}(x) &= \sum_{j=x-hm}^{x+hm} ( F( j ) k(j-x+hm) ) \mathrm{\, if \,} hm <= x <= n-hm-1 \\ &= F(0) \sum_{j=x-hm}^{-1} ( k(j-x+hm) ) + \sum_{j=0}^{x+hm} ( F( j ) k(j-x+hm) ) \mathrm{\, if \,} x < hm \\ &= \sum_{j=x-hm}^{n-1} ( F( j ) k(j-x+hm) ) + F(n-1) \sum_{j=n}^{x+hm-1} ( k(j-x+hm) ) \mathrm{\, if \,} x > n-hm-1\end{split}\]

Here we use extended edges, ie we repeat the values of F at the edge to compute their convolved values.

We take into account the (possibly variable) spectral sampling of F, and use a function for the kernel to be able to calculate its value at any position. We define

• \(k[\lambda_\mathrm{cen}](\lambda)\) as the value of the kernel centered on \(\lambda_\mathrm{cen}\), at wavelength \(\lambda\).

• \(\mathrm{hw}_\mathrm{kern}\) (ie hm) the interval between the kernel center and the wavelength point where the kernel falls below 1% of its max, ie where its contribution to the convolution becomes negligible (\(\sim\) 0.1% difference with the full kernel range)

• dw(j) the width of the pixel at index j in the table of F

We separate again three different cases

• regular values (\(\lambda(0)+\mathrm{hw}_\mathrm{kern} <= \lambda(x) <= \lambda(n-1)-\mathrm{hw}_\mathrm{kern}\))

  \[\begin{split}F_\mathrm{conv}(x) &= \sum_{ j=j_s}^{j_e }( F( j ) k[\lambda(j)]( \lambda(x) ) dw(j) ) \\ & j_s \mathrm{lowest \, index \,that\, gives} \lambda(j_s) >= \lambda(x) - \mathrm{hw}_\mathrm{kern} \\ & j_e \mathrm{highest \, index \,that \,gives} \lambda(j_e) <= \lambda(x) + \mathrm{hw}_\mathrm{kern}\end{split}\]

  We cannot define \((j_s,j_e)\) in terms of indexes because the resolution of F can be variable

• lower edge (\(\lambda(x) < \lambda(0)+\mathrm{hw}_\mathrm{kern}\))

  \[\begin{split}F_\mathrm{conv}(x) &= F(0) dw(0) \sum_{j= -1 - int(\mathrm{hw}_\mathrm{kern}/dw(0))}^{-1} ( k[\lambda(0)+dw(0) j]( \lambda(x) ) ) + \sum_{ j=0}^{j_e} ( F( j ) k[\lambda(j)]( \lambda(x) ) dw(j) )\\ & j_e \mathrm{highest \, index \,that \,gives} \lambda(j_e) <= \lambda(x) + \mathrm{hw}_\mathrm{kern}\end{split}\]

  In that case, because \(\mathrm{hw}_\mathrm{kern}/dw(0) -1 < int(\mathrm{hw}_\mathrm{kern}/dw(0)) <= \mathrm{hw}_\mathrm{kern}/dw(0)\) the first pixel on which the kernel is centered on at \(\lambda_{j_\mathrm{min}} = \lambda(0) - dw(0) - dw(0) int( \mathrm{hw}_\mathrm{kern}/dw(0) )\) verifies \(\mathrm{hw}_\mathrm{kern}<\lambda(0)-\lambda_{j_\mathrm{min}}<=\mathrm{hw}_\mathrm{kern}+dw\) thus this is the farthest phantom pixel, when extending the table with pixels at the resolution of the first pixel, for which the kernel contributes significantly to the convolution (since the next extended pixel would be at more than \(\mathrm{hw}_\mathrm{kern}\) from the first pixel at :math`lambda(0)`).

• upper edge (\(\lambda(x) > \lambda(n-1)-\mathrm{hw}_\mathrm{kern}\))

  \[F_\mathrm{conv}(x) = \sum_{j=j_s}^{n-1}( F( j ) k[\lambda(j)]( \lambda(x) ) dw(j) ) + F(n-1) dw(n-1) \sum_{j=1}^{1+int(\mathrm{hw}_\mathrm{kern}/dw(n-1))}( k[\lambda(n-1)+dw(n-1) j]( \lambda(x) ) )\]

  With \(j_s\) lowest index that gives \(\lambda(j_s) >= \lambda(x) - \mathrm{hw}_\mathrm{kern}\). In that case, because \(\mathrm{hw}_\mathrm{kern}/dw(n-1) -1 < int(\mathrm{hw}_\mathrm{kern}/dw(n-1)) <= \mathrm{hw}_\mathrm{kern}/dw(n-1)\) the last pixel on which the kernel is centered on at \(\lambda_{j_\mathrm{max}} = \lambda(n-1) + dw(n-1) + dw(n-1) int( \mathrm{hw}_\mathrm{kern}/dw(n-1) )\) verifies \(\mathrm{hw}_\mathrm{kern} < \lambda_{j_\mathrm{max}} - \lambda(n-1) <= \mathrm{hw}_\mathrm{kern} +dw(n-1)\).

Parameters:

TBD

Returns:

TBD

planck(wav_tab, Teff)

Black body spectrum

Calculates black body at a given temperature, over an input wavelength table. To get the black body flux at distance d from the star, do:

>>> planck(wav_tab,Teff) x (Rstar/d)^2

Parameters:

• wav_tab (array, float) – wavelength table in A

• Teff (float) – temperature in K

Returns:

bbflux (array, float) – black body flux in erg/cm2/s/A at the radius of the star

air_index(l, t=15.0, p=760.0)

Air refraction index.

Computes the refraction index n of the air (author: C. Lovis)

\[\begin{split}& \lambda_\mathrm{air} = \lambda_\mathrm{vacuum}/n \\ & n_\mathrm{vacuum}=1.\end{split}\]

Parameters:

• l (float, array) – Wavelength in Angström

• t (float, array) – Air temperature in Celsius

• p (float, array) – Air pressure in millimeter of mercury

Returns:

n (float, array) – Refraction index.

gen_specdopshift(rv_s2r, v_s=0.0)

General Doppler effect.

Calculates the Doppler shift for the case where the inertial motions of the source and receiver are at any specified angle.

The Doppler shift for a source moving at speed \(v_s\) at an angle \(\theta_r\) measured in the frame of a stationary receiver is expressed in frequency and wavelength as

\[\begin{split}\nu_\mathrm{r} &= \frac{ \nu_\mathrm{s} }{ \gamma ( 1 + \beta \cos{\theta_r} ) } \\ \lambda_\mathrm{r} &= \lambda_\mathrm{s} \gamma (1+\beta \cos{\theta_r}) \\ \mathrm{where \,} &\beta = \frac{v}{c}\end{split}\]

The radial component of the source’s motion along the line of sight is equal to \(rv = v \cos{\theta_r}\), negative if the source is moving away from the receiver, so that

\[\begin{split}\lambda_\mathrm{r} &= \lambda_\mathrm{s} f_\mathrm{Dopp} \\ \mathrm{where \,} &f_\mathrm{Dopp} = \gamma (1+ \beta_\mathrm{rv}) \\ &\beta_\mathrm{rv} = \frac{rv[s/r]}{c} \\ &\gamma = \frac{1}{\sqrt{1 - \beta^2}}\end{split}\]

The Lorentz factor \(\gamma = 1/\sqrt{1 - (v/c)^2} \sim 1\) in most cases but is accounted in the Doppler shift of the orbital velocity, as it can yields variations on the order of 1-10 m/s for close-in planets on eccentric orbits.

Typically we convert wavelengths from the receiver to the source frame (to align measurements in their frame of emission), so one needs to divide \(\lambda_\mathrm{r}\) by \(f_\mathrm{Dopp}\).

Parameters:

• rv_s2r (array, float) – radial velocity of source with respect to receiver (km/s)

• v_s (array, float) – absolute velocity of source (km/s)

Returns:

f_dopp (array, float) – spectral Doppler shift

rel_lon_specdopshift(rv_s2r)

Longitudinal Doppler effect.

Calculates the Doppler shift for the case where the inertial motions of the source and receiver are along the axis from one to the other.

Parameters:

rv_s2r (array, float) – radial velocity of source with respect to receiver (km/s)

Returns:

f_dopp (array, float) – spectral Doppler shift

conv_flux2ph(w_grid)

Flux to photons conversion.

Returns the conversion factor from flux density in erg/cm2/s/A to ph/cm2/s/A at a given wavelength. The energy of a photon is E[erg] = E[cm2 g s−2] = h[g cm2 s-1] c[m] / lambda[m] = 1e3*1e4*h[kg m2 s-1] c[m] / (1e-10 lambda[A]) = 1e3*1e4*6.62606957e-34*299792458./ (1e-10 lambda[A]) = 1.986445683269303e-08/lambda[A] Thus one erg yields (1/1.986445683269303e-08)*lambda[A] photons

Parameters:

w_grid (array, float) – input wavelength grid (A)

Returns:

conv_fact (array, float) – conversion factor ( flux_ph = conv_fact*flux_erg)

MAIN_multithread(func_input, nthreads, n_elem, y_inputs, common_args, output=False)

Multithreading wrap-up.

This routine is applicable to functions that takes chunkable inputs defined as arrays with dimension of same length. Specific routines must be defined for other types of inputs.

Parameters:

• func_input (function) – multi-threaded function

• nthreads (int) – number of threads

• n_elem (int) – number of elements to thread between the different workers

• y_inputs (list) – threadable function inputs (each element of the list is an array with first dimension of length n_elem)

• common_args (tuple) – common function inputs to be passed to all workers (chunkable inputs should be put in y_inputs)

• output (bool) – set to True to return function outputs

Returns:

y_output (None or specific to func_input) – function outputs

init_parallel_func(nthreads, n_elem)

Multithreading initialization.

Prepares multi-threading to execute routine on different cores with several arguments.

Parameters:

• nthreads (int) – number of threads

• n_elem (int) – number of elements to thread

Returns:

ind_chunk_list (list) – function arguments separated in chunks to be passed to each thread.