Skip to content

Util

thmd.util

Modules:

check_installation

Functions:

check_install_ovito()

check_install_googlesearch()

compute_angle

Functions:

angle_vector2vectors(fixVector, arrayVectors, unit='rad')

copmute angles between a vector with set of vectors

compute_distance

Functions:

dist2_point2points(point, points)

Compute bond_len and postion_vetors from 1 point to a list of points

Parameters:

  • point (list array) –

    coordinate of 1 point.

  • points (list array) –

    2d-list of coordinates of points/point.

Returns:

  • df ( DataFrame ) –

    pd.DataFrame constains distance and component of connecting vectors.

dist2_points2line(points, line=[(0, 0, 0), (0, 0, 0)])

Compute bond_len and postion_vetors from 1 point to a list of points Ref: https://stackoverflow.com/questions/39840030/distance-between-point-and-a-line-from-two-points

Parameters:

  • points (list array DataFrame) –

    list of coordinates of points/point.

  • line (list array, default: [(0, 0, 0), (0, 0, 0)] ) –

    2d-array contains coordinates to define a line.

Returns:

  • d ( float list ) –

    distances between points and a line.

closest_points2line(points, line=[(0, 0, 0), (0, 0, 0)], distance=0, Xbound=None, Ybound=None, Zbound=None)

Find all points locate inside a checkin-distance "dist" from a line.

Parameters:

  • points (list array) –

    list of coordinates of points/point.

  • line (list array, default: [(0, 0, 0), (0, 0, 0)] ) –

    [[x1,y1,z1], [x1,y2,z2]]: 2d-list contains coordinates to define a line.

  • distance (float, default: 0 ) –

    the checkin-distance.

  • Xbound (tuple, default: None ) –

    define the boundaries for checking. Xbound='line': use the lengths of lines as bounds. Xbound=None: extend to INF. Xbound = (xlo, xhi)

  • Ybound (tuple, default: None ) –

    define the boundaries for checking.

  • Zbound (tuple, default: None ) –

    define the boundaries for checking.

Returns:

  • ds_idx ( Series ) –

    Series of indices of points within the checkin-distance

closest_points2multilines(points, multilines=[], distance=0, Xbound=None, Ybound=None, Zbound=None)

Find all points locate inside a checkin-distance "dist" from multilines. The Bound is set as the line-lengths.

Parameters:

  • points (list array) –

    list of coordinates of points/point.

  • multilines (list, default: [] ) –

    list of pair-points, each pair-point contains coordinates of 2 points to define a line used in 'closest_points2line'.

  • distance (float, default: 0 ) –

    the checkin-distance.

Returns:

  • ds_idx ( Series ) –

    Series of indices of points within the checkin-distance

compute_tensor

Functions:

ke_tensor(vel, mass, kb)

Compute Kinetic Energy tensors, and Temp Args: vel (array): Nx3 array of per-atom velocity mass (array): Nx3 array of atomic mass inUNIT (str): ['angstrom','ps','amu','eV'], outUNIT=['eV','K'] Returns: Kinetic energy tensor, Kinetic scalar, Temperature scalar

stress_tensor(per_atom_stress_tensor, atomic_volume, unitFac=1)

Compute local pressure/stress Args: per_atom_stress_tensor : Nx6 array of the per-atom stress tensor atomVol : Nx1 vector of atomVol inUNIT=['bar','angstrom'], outUNIT=['bar'] → unitFac=1e-4 for ['GPa'] Returns: pressure scalar Stress tensor

detect_sign_change

Functions:

detect_sign_change(y, x=[])

determine points where line y=y(x) change its sign

Parameters:

  • y –

    Nx1 arrays, contains dependent variable y

  • x –

    (Optinal) Nx1 arrays, contains independent variable x of line y(x)

Returns:

  • idx –

    1d array of indices where sign changes

fit

Modules:

Functions:

  • curve_intersect_shapely –

    find the intersection points between 2 lines

  • polyfit –

    Polynomial fitting for y = f(x) relation, which returns uncertainties of coefficients.

  • find_slope –

    Compute slope of a linear relation y = A + B*x.

  • find_roots –

    find roots for y = f(x) relation in polynomial form.

  • find_extrema –

    find extrema points (der=0) for y = f(x) relation in polynomial form.

  • find_convergence –

    y is a function of x, then find value of x that y converge with a tolerance < tol.

  • extrapolate –

curve_intersect_shapely(line1, line2)

find the intersection points between 2 lines Args: line1 (array like): Nx2 arrays, contains data points of curve 1 line2 (array like): Nx2 arrays, contains data points of curve 2

Returns:

  • Points ( array like ) –

    Nx2 arrays, contains data points of intersection points

polyfit(x, y, deg=1, sigma_y=None, uncert=False, **kwargs)

Polynomial fitting for y = f(x) relation, which returns uncertainties of coefficients. The fitted polynomial(s) are in the form

p(x) = a0 + a1*x + a2*x^2 + ... + an*x^n

Parameters:

  • x,y (array) –

    1D array of x and y data

  • deg (int, default: 1 ) –

    degree of polynomial

  • sigma_y (array, default: None ) –

    1D array of standard deviation of y data. Use in weighted least square fitting.

  • uncert (bool, default: False ) –

    return uncertainties of coefficients. Defaults to False.

  • **kwargs –

    additional arguments, adapt all args from np.polyfit

Returns:

  • pars ( array ) –

    1D array of coefficients

  • uncert ( array ) –

    1D array of standard deviation of coefficients

find_slope(x, y)

Compute slope of a linear relation y = A + B*x.

Parameters:

  • x (list) –

    a list/array of x value

  • y (list) –

    a list/array of y value

Return

slope (float): the slope to linear relation

find_roots(x, y, order=1)

find roots for y = f(x) relation in polynomial form.

Parameters:

  • x (list) –

    a list/array of x value

  • y (list) –

    a list/array of y value

  • order (int, default: 1 ) –

    order of polynomial. Defaults to 1.

Returns:

  • roots ( list ) –

    list of roots

find_extrema(x, y, order=2, retun_fit=False)

find extrema points (der=0) for y = f(x) relation in polynomial form.

Parameters:

  • x (list) –

    a list/array of x value

  • y (list) –

    a list/array of y value

  • order (int, default: 2 ) –

    order of polynomial. Defaults to 2.

  • retun_fit (bool, default: False ) –

    return fitted params. Defaults to False.

Returns:

  • p ( list ) –

    list of flex points.

find_convergence(x, y, tol=1e-06, grid_size=None, convergence_side='right')

y is a function of x, then find value of x that y converge with a tolerance < tol.

Parameters:

  • x (list) –

    a list/array of x values

  • y (list) –

    a list/array of y values

  • tol (float, default: 1e-06 ) –

    tolerance of the slope (dy/dx). Defaults to 1e-6.

  • grid_size (float, default: None ) –

    set grid size of x if need to interpolate finer data. Defaults to None.

  • convergence_side (str, default: 'right' ) –

    find the first x on the left or right side. Defaults to "right".

Returns:

  • –

    best_x, best_y (float): found x and y value that y converge with a tolerance < tol.

Notes

Value df['dy'] = df['y'].diff() depends on grid size. Should use df['dy'] = df['y'].diff()/ df['x'].diff().

References
  1. https://docs.scipy.org/doc/scipy/tutorial/interpolate.html

extrapolate(x, y, left_side: list = None, right_side: list = None, grid_size=0.1) -> tuple[list, list]

curve_intersect

Functions:

curve_intersect_shapely(line1, line2)

find the intersection points between 2 lines Args: line1 (array like): Nx2 arrays, contains data points of curve 1 line2 (array like): Nx2 arrays, contains data points of curve 2

Returns:

  • Points ( array like ) –

    Nx2 arrays, contains data points of intersection points

___curve_intersect_numpy(curve1, curve2, degree=3, bounds=None)

find the intersection points between 2 curves

Parameters:

  • curve1 (array like) –

    Nx2 arrays in form (x,y), contains data points of curve 1

  • curve2 (array like) –

    Nx2 arrays in form (x,y), contains data points of curve 2

  • degree (int, default: 3 ) –

    degree of polynomial function to fit the curve

  • bounds (tuple, default: None ) –

    (min, max) of x, to select points in bounds

Returns:

  • Points ( array like ) –

    Nx2 arrays, contains data points of intersection points

Refs

[1] http://t.ly/2_a-K

fit_root

Functions:

  • polyfit –

    Polynomial fitting for y = f(x) relation, which returns uncertainties of coefficients.

  • find_slope –

    Compute slope of a linear relation y = A + B*x.

  • find_roots –

    find roots for y = f(x) relation in polynomial form.

  • find_extrema –

    find extrema points (der=0) for y = f(x) relation in polynomial form.

  • find_convergence –

    y is a function of x, then find value of x that y converge with a tolerance < tol.

  • extrapolate –
polyfit(x, y, deg=1, sigma_y=None, uncert=False, **kwargs)

Polynomial fitting for y = f(x) relation, which returns uncertainties of coefficients. The fitted polynomial(s) are in the form

p(x) = a0 + a1*x + a2*x^2 + ... + an*x^n

Parameters:

  • x,y (array) –

    1D array of x and y data

  • deg (int, default: 1 ) –

    degree of polynomial

  • sigma_y (array, default: None ) –

    1D array of standard deviation of y data. Use in weighted least square fitting.

  • uncert (bool, default: False ) –

    return uncertainties of coefficients. Defaults to False.

  • **kwargs –

    additional arguments, adapt all args from np.polyfit

Returns:

  • pars ( array ) –

    1D array of coefficients

  • uncert ( array ) –

    1D array of standard deviation of coefficients

find_slope(x, y)

Compute slope of a linear relation y = A + B*x.

Parameters:

  • x (list) –

    a list/array of x value

  • y (list) –

    a list/array of y value

Return

slope (float): the slope to linear relation

find_roots(x, y, order=1)

find roots for y = f(x) relation in polynomial form.

Parameters:

  • x (list) –

    a list/array of x value

  • y (list) –

    a list/array of y value

  • order (int, default: 1 ) –

    order of polynomial. Defaults to 1.

Returns:

  • roots ( list ) –

    list of roots

find_extrema(x, y, order=2, retun_fit=False)

find extrema points (der=0) for y = f(x) relation in polynomial form.

Parameters:

  • x (list) –

    a list/array of x value

  • y (list) –

    a list/array of y value

  • order (int, default: 2 ) –

    order of polynomial. Defaults to 2.

  • retun_fit (bool, default: False ) –

    return fitted params. Defaults to False.

Returns:

  • p ( list ) –

    list of flex points.

find_convergence(x, y, tol=1e-06, grid_size=None, convergence_side='right')

y is a function of x, then find value of x that y converge with a tolerance < tol.

Parameters:

  • x (list) –

    a list/array of x values

  • y (list) –

    a list/array of y values

  • tol (float, default: 1e-06 ) –

    tolerance of the slope (dy/dx). Defaults to 1e-6.

  • grid_size (float, default: None ) –

    set grid size of x if need to interpolate finer data. Defaults to None.

  • convergence_side (str, default: 'right' ) –

    find the first x on the left or right side. Defaults to "right".

Returns:

  • –

    best_x, best_y (float): found x and y value that y converge with a tolerance < tol.

Notes

Value df['dy'] = df['y'].diff() depends on grid size. Should use df['dy'] = df['y'].diff()/ df['x'].diff().

References
  1. https://docs.scipy.org/doc/scipy/tutorial/interpolate.html
extrapolate(x, y, left_side: list = None, right_side: list = None, grid_size=0.1) -> tuple[list, list]
___uncertainty_weighted_fit_linear(x, y, sigma_y=None)

Compute uncertainties in coefficients A and B of y = A + B*x from the weighted least square fitting.

Apply when the measured data y_i has different uncertainties sigma_y_i, the weights w_i = 1/(sigma_y_i^2).

Parameters:

  • x,y (array) –

    1D array of x and y data

  • sigma_y (array, default: None ) –

    1D array of standard deviation of y data. Use in weighted least square fitting.

Returns:

  • pars ( array ) –

    1D array of coefficients A and B

  • uncertainties ( tuple ) –

    1D array (sigma_intercept, sigma_slope) of standard deviation of A and B

References
  1. Taylor_1997_An introduction to error analysis: the study of uncertainties in physical measurements, page 198.
  2. https://numpy.org/doc/stable/reference/generated/numpy.polynomial.polynomial.polyfit.html

user_lmfit

Classes:

  • UserLmfit –

    The class contains set of objective function of fitting use by LMFIT package

UserLmfit

The class contains set of objective function of fitting use by LMFIT package NOTEs: - defined function followed the convection of LMFIT: the first argument of the function is taken as the independent variable, held in independent_vars, and the rest of the functions positional arguments (and, in certain cases, keyword arguments – see below) are used for Parameter names. https://lmfit.github.io/lmfit-py/model.html - This Class defines curve-forms that are not vailable in LMFIT's built-in models

  • Attributes: swType : (default='RATIONAL') Type of witching function, r0, d0 : The r_0 parameter of the switching function

  • Methods: fFunc : compute & return value and derivation of sw function fDmax : estimate value of Dmax

Ex: func = thmd.CurveLib.Linear(x)

Methods:

Linear(x, a0, a1)

this func is available in LMFIT, just play as an example here

inverseTemperature(x, a, b)
ExpDecay(x, A, lambd)
sizeEffect(x, a, b)

system size-dependence on term N^(⅔

unNormalGaussian(x, amp, cen, sig)

The unNormalize Gaussian function

NormalGaussian(x, amp, cen, sig)

The Normalize Gaussian function

sum_2unNormalGaussian(x, amp1, amp2, cen1, cen2, sig1, sig2)

The sum of 2 Gaussian function

sum_3unNormalGaussian(x, amp1, amp2, amp3, cen1, cen2, cen3, sig1, sig2, sig3)

The sum of 3 Gaussian function

sum_4unNormalGaussian(x, amp1, amp2, amp3, amp4, cen1, cen2, cen3, cen4, sig1, sig2, sig3, sig4)

The sum of 4 Gaussian function

sum_5unNormalGaussian(x, amp1, amp2, amp3, amp4, amp5, cen1, cen2, cen3, cen4, cen5, sig1, sig2, sig3, sig4, sig5)

The sum of 5 Gaussian function

sum_2NormalGaussian(x, amp1, amp2, cen1, cen2, sig1, sig2)

The sum of 2 Gaussian function

sum_3NormalGaussian(x, amp1, amp2, amp3, cen1, cen2, cen3, sig1, sig2, sig3)

The sum of 3 Gaussian function

sum_4NormalGaussian(x, amp1, amp2, amp3, amp4, cen1, cen2, cen3, cen4, sig1, sig2, sig3, sig4)

The sum of 4 Gaussian function

sum_5NormalGaussian(x, amp1, amp2, amp3, amp4, amp5, cen1, cen2, cen3, cen4, cen5, sig1, sig2, sig3, sig4, sig5)

The sum of 5 Gaussian function

DoseResp(x, A1=-3.3, A2=-2.9, LOGx0=480000, p=1.2)

Dose-response curve with variable Hill slope given by parameter 'p'. Origin's Category: Pharmacology * Params: Names=A1,A2,LOGx0,p Meanings=bottom asymptote,top asymptote, center, hill slope Initiate params: pars = mod.make_params(A1=-3.3, A2=-2.9, LOGx0=480000, p=1.2)

BiDoseResp(x, A1=-3.3, A2=-2.9, LOGx01=175000, LOGx02=480000, h1=0.1, h2=0.2, p=0.5)

Biphasic Dose Response Function, Origin's Category: Pharmacology * Params: Names=A1, A2, LOGx01, LOGx02, h1, h2, p Meanings=Bottom, Top, 1st EC50, 2nd EC50, slope1, slope2, proportion Initiate params: pars = mod.make_params(A1=0, A2=100, LOGx01=-8, LOGx02=-4, h1=0.8, h2=1.2, p=0.5)

Carreau(x, A1=60, A2=3, t=3.0, a=2.2, n=0.3)

Carreau-Yasuda model to describe pseudoplastic flow with asymptotic viscosities at zero and infinite shear rates Origin's Category: Rheology * Params: Names = A1,A2,t,a,n >0 (lower bound) Meanings = zero shear viscosity,infinite shear viscosity,time constant,transition control factor,power index Initiate params: pars = mod.make_params(A1=-3.3, A2=-2.9, t=2.0, a=2.2, n=0.2)

Cross(x, A1=0.1, A2=3, t=1000, m=0.9)

Cross model to describe pseudoplastic flow with asymptotic viscosities at zero and infinite shear rates Origin's Category: Rheology * Params: Names = A1,A2,t,m >0 (lower bound) Meanings = zero shear viscosity,infinite shear viscosity,time constant,power index Initiate params: pars = mod.make_params(A1=0.1, A2=3, t=1000, m=0.9)

GammaCFD(x, y0, A1, a, b)

Gamma cumulative distribution function Origin's Category: Statistics * Params: Names = y0,A1,a,b (A1,a,b >0) Meanings = Offset,Amplitude,Shape,Scale Initiate params: pars = mod.make_params(A1=0.1, A2=3, t=1000, m=0.9)

grid_box

Functions:

  • grid_box_2d –

    devide box into 2d grid, return list of atom-IDs in each slab and list of slab-centers

  • grid_box_1d –

    devide box into 1d slabs, return list of atom-IDs in each slab and list of slab-centers

grid_box_2d(points, box, plane='XY', mode='bin_number', grid_size=[20, 20])

devide box into 2d grid, return list of atom-IDs in each slab and list of slab-centers Args: P : Nx3 array contain positions of atoms box : simulation box mode : "bin_number" or "bin_size" mode_value : corresponding 'Number-of-bins' or 'size-of-bin' plane : on which plane the box will be gridded Returns: atomIDinCell : 1xBinNumber array of 1xM-vector, contain indices of atoms of each Cell cellCenter : 1xBinNumber array of scalar, is center of each slab

grid_box_1d(points, box, axis='Z', mode='bin_number', grid_size=20)

devide box into 1d slabs, return list of atom-IDs in each slab and list of slab-centers Args: P : Nx3 array contain positions of atoms box : simulation box mode : "bin_number" or "bin_size" mode_value : corresponding 'Number-of-bins' or 'size-of-bin' axis : on which axis the box will be slabbed Returns: atomIDinCell : 1xBinNumber array of 1xM arrays, contain indices of atoms of each Slab, array of arrays geoCenter : 1xBinNumber array of scalar, is geometry center of each slab massCenter : 1xBinNumber array of scalar, is mass center of each slab

many_stuff

Functions:

memory_usage()

return the memory usage in MB

natSorted(mylist)

https://stackoverflow.com/questions/4836710/is-there-a-built-in-function-for-string-natural-sort

split_list(a, n)

Should use np.array_split instead Args: a (list): list to be splitted n (int): number of chunks Returns: generator: a generator of splitted list

find_nearest_value(array, value)

row_operation

Functions:

unique_row(X, tol_decimal=2)

find match_indices & mismatch_indices of arr(find_rows) in arr(X), return indices of X Args: X, find_rows : NxN numpy arrays tol_decimal : number of digits for round off input data

match_row(X, find_rows, tol_decimal=2)

find match_indices & mismatch_indices of arr(find_rows) in arr(X), return indices of X Args: X, find_rows : NxN numpy arrays tol_decimal : number of digits for round off input data

asvoid(arr)

Base on: https://stackoverflow.com/questions/38674027/find-the-row-indexes-of-several-values-in-a-numpy-array

string_index

Functions:

string_index(idx_list)

groupSURF index by consecutive-series

unit

This module to convert unit of some physical properties pressure

Consider to use this module: https://unyt.readthedocs.io/en/stable/usage.html

Functions:

  • pressure –

    convert unit of pressure

  • force –

    convert unit of force

  • energy –

    convert unit of energy

  • constant –

    list of constants

pressure(key_word='all_key')

convert unit of pressure Pa: Pascal atm: standard atmosphere at: technical atmosphere

kgf/cm2 = kg/cm2 1 Pa = 1 N/m^2 1 kgf/cm2 = 1

Parameters:

  • key_word (str, default: 'all_key' ) –

    a string to specify units to be converted.

Returns:

  • factor ( float ) –

    multiply factor of conversion

Examples:

key_word='Pa_atm': convert from Pa (Pascal) to atm (Standard atmosphere)

force(key_word='all_key')

convert unit of force N: Newton kgf = m.g: kilogram-force (weight: one kilogram of mass in a 9.80665 m/s2 gravitational field) lbf: pound-force p: pond

1 N = 1 J/m (Work = Force.distance) 1 kcal = 4184 J = 4184 N.m = 4184.10^10 N.Angstrom 69.4786 pN = 1 kcal/mol Angstrom. https://tinyurl.com/yb2gnlhc

Parameters:

  • key_word (str, default: 'all_key' ) –

    a string to specify units to be converted.

Returns:

  • factor ( float ) –

    multiply factor of conversion

energy(key_word='all_key')

convert unit of energy J: Joule W.h: watt-hour cal: calorie (th) hp.h: horsepower hour eV: electron-volt

1 J = 1 N.m (Work = Force.distance) 1J = 1 W.s

Parameters:

  • key_word (str, default: 'all_key' ) –

    a string to specify units to be converted.

Returns:

  • factor ( float ) –

    multiply factor of conversion

Notes 

## convert eV to kcal/mol
eV2J = 1/unit_convert.energy('J_eV')
J2Jmol = unit_convert.constant('1/mol')
kj2kcal = 1/unit_convert.energy('kcal/mol_kJ/mol')
eV2kcalmol = eV2J * J2Jmol * 1e-3 *kj2kcal

constant(key_word='all_key')

list of constants Na = 6.02214076e23 (=1/mol): Avogadro number

Parameters:

  • Ex –

    key_word='Pa_atm': convert from Pa (Pascal) to atm (Standard atmosphere)

Returns: factor: float, multiply factor of conversion