variable

This module implements classes and methods to manage the variables in fitting.

class Bound(a=None, b=None, func=None)

Bases: object

This class provides methods to implement the boundary constraint for a variable. It has dependence on SymPy . The boundary-transforming function can transform a variable x defined in the real domain to a variable y defined in a limited range (a,b). y should be the physical parameter but x is the one used while fitting.

Parameters:

• a – Real number. The lower boundary

• b – Real number. The upper boundary

• func – String. The boundary-transforming function. By default, if neither a or b is None, func is “(b-a)*(sin(x)+1)/2+a”; else if only a is None, func is “b+1-sqrt(x**2+1)”; else if only b is None, func is “a-1+sqrt(x**2+1)”; else func is “x”.

a, b, func can be refered by self.lower, self.upper, self.func.

get_d2ydx2(val)

To calculate the derivative \(\frac{dy}{dx}\).

Parameters:

val – Real number x

Returns:

Real number \(\frac{dy}{dx}\)

get_dydx(val)

To calculate the derivative \(\frac{dy}{dx}\).

Parameters:

val – Real number x

Returns:

Real number \(\frac{dy}{dx}\)

get_func()

Initialize the function string into sympy objects.

Returns:

sympy objects f, df, inv, which are the function, its derivative and its inverse function.

get_x2y(val)

To derive y from x

Parameters:

val – Real number x

Returns:

Real number y

get_y2x(val)

To derive x from y. y will be set to a if y<a, and y will be set to b if y>b.

Parameters:

val – Real number y

Returns:

Real number x

class SumVar(value, grad, var, hess=None)

Bases: object

from_call(var, *args, **kwargs)

from_call_with_hess(var, *args, **kwargs)

class Variable(name, shape=None, cplx=False, vm=None, overwrite=True, is_cp=False, **kwargs)

Bases: object

This class has interface to VarsManager. It is convenient for users to define a group of real variables, since it may be more perceptually intuitive to define them together.

By calling the instance of this class, it returns the value of this variable. The type is tf.Tensor.

Parameters:

• name – The name of the variable group

• shape – The shape of the group. E.g. for a 4*3*2 matrix, shape is [4,3,2]. By default, shape is [] for a real variable.

• cplx – Boolean. Whether the variable (or the variables) are complex or not.

• vm – VarsManager. It is by default the one automatically defined in the global scope by the program.

• overwrite – Boolean. If it’s True, the program will not throw a warning when overwrite a variable with the same name.

• kwargs – Other arguments that may be used when calling self.real_var() or self.cplx_var()

cplx_cpvar(polar=True, fix=False, fix_vals=(1.0, 0.0, 0.0, 0.0), value=0.0)

It implements interface to VarsManager.add_complex_var(), but supports variables that are not of non-shape.

Parameters:

• polar – Boolean. Whether the variable is defined in polar coordinate or in Cartesian coordinate.

• fix – Boolean. Whether the variable is fixed. It’s enabled only if self.shape is None.

• fix_vals – Length-4 tuple. The value of the fixed complex variable is fix_vals[0]+fix_vals[1]j.

cplx_var(polar=None, fix=False, fix_vals=(1.0, 0.0))

It implements interface to VarsManager.add_complex_var(), but supports variables that are not of non-shape.

Parameters:

• polar – Boolean. Whether the variable is defined in polar coordinate or in Cartesian coordinate.

• fix – Boolean. Whether the variable is fixed. It’s enabled only if self.shape is None.

• fix_vals – Length-2 tuple. The value of the fixed complex variable is fix_vals[0]+fix_vals[1]j.

factor_names()

fixed(value=None)

Fix this Variable. Note only non-shape real Variable supports this method.

Parameters:

value – Real number. The fixed value

freed()

Set free this Variable. Note only non-shape Variable supports this method.

init_name_list()

is_fixed()

r_shareto(Var)

Share the radium component to another Variable of the same shape. Only complex Variable supports this method.

Parameters:

Var – Variable.

real_var(value=None, range_=None, fix=False)

It implements interface to VarsManager.add_real_var(), but supports variables that are not of non-shape.

Parameters:

• value – Real number. The value of all real components.

• range – Length-2 array. The length of all real components.

• fix – Boolean. Whether the variable is fixed.

rename(new_name)

Rename this Variable.

sameas(Var)

Set the Variable to be the same with another Variable of the same shape.

Parameters:

Var – Variable.

set_bound(bound, func=None, overwrite=False)

Set boundary for this Variable. Note only non-shape real Variable supports this method.

Parameters:

• bound – Length-2 tuple.

• func – String. Refer to class tf_pwa.variable.Bound.

• overwrite – Boolean. If it’s True, the program will not throw a warning when overwrite a variable with the same name.

set_fix_idx(fix_idx=None, fix_vals=None, free_idx=None)

Parameters:

• fix_idx – Interger or list of integers. Which complex component in the innermost layer of the variable is fixed. E.g. If self.shape==[2,3,4] and fix_idx==[1,2], then Variable()[i][j][1] and Variable()[i][j][2] will be the fixed value.

• fix_vals – Float or length-2 float list for complex variable. The fixed value.

• free_idx – Interger or list of integers. Which complex component in the innermost layer of the variable is set free. E.g. If self.shape==[2,3,4] and fix_idx==[0], then Variable()[i][j][0] will be set free.

set_phi(phi, index=None)

set_rho(rho, index=None)

set_same_ratio()

set_value(value, index=None)

property value

Ndarray of self.shape.

Type:

return

property variables

Names of the real variables contained in this Variable instance.

Returns:

List of string.

class VarsManager(name='', dtype=tf.float64, multi_gpu=None)

Bases: object

This class provides methods to operate the variables in fitting. Every variable is a 1-d tf.Variable of dtype (tf.float64 by default).

All variables are stored in a dictionary self.variables. The indices of the dictionary are the variables’ names, so name property in tf.Variable does not matter. All methods intended to change the variables are operating self.variables directly.

Besides, all trainable variables’ names will be stored in a list self.trainable_vars.

add_cartesiancp_var(name, polar=None, trainable=True, fix_vals=(1.0, 0.0, 0.0, 0.0))

Add a complex variable. Two real variables named name+’r’ and name+’i’ will be added into self.variables. The initial values will be given automatically according to its form of coordinate.

Parameters:

• name – The name of the complex variable.

• polar – Boolean. If it’s True, name+’r’ and name+’i’ are defined in polar coordinate; otherwise they are defined in Cartesian coordinate.

• trainable – Boolean. If it’s True, real variables name+’r’ and name+’i’ will be trainable.

• fix_vals – Length-4 array. If trainable=False, the fixed values for name+’r’ and name+’i’ are fix_vals[0], fix_vals[1] respectively.

add_complex_var(name, polar=None, trainable=True, fix_vals=(1.0, 0.0))

Add a complex variable. Two real variables named name+’r’ and name+’i’ will be added into self.variables. The initial values will be given automatically according to its form of coordinate.

Parameters:

• name – The name of the complex variable.

• polar – Boolean. If it’s True, name+’r’ and name+’i’ are defined in polar coordinate; otherwise they are defined in Cartesian coordinate.

• trainable – Boolean. If it’s True, real variables name+’r’ and name+’i’ will be trainable.

• fix_vals – Length-2 array. If trainable=False, the fixed values for name+’r’ and name+’i’ are fix_vals[0], fix_vals[1] respectively.

add_real_var(name, value=None, range_=None, trainable=True)

Add a real variable named name into self.variables. If value and range_ are not provided, the initial value is set to be a uniform random number between 0 and 1.

Parameters:

• name – The name of the variable, the index of this variable in self.variables

• value – The initial value.

• range – Length-2 array. It’s useless if value is given. Otherwise the initial value is set to be a uniform random number between range_[0] and range_[0].

• trainable – Boolean. If it’s True, the variable is trainable while fitting.

batch_sum_var(fun, data, batch=65000)

error_trans(err_matrix)

get(name, val_in_fit=True)

Get a real variable. If val_in_fit is True, this is the variable used in fitting, not considering its boundary transformation.

Parameters:

name – String

Returns:

tf.Variable

get_all_dic(trainable_only=False)

Get a dictionary of all variables.

Parameters:

trainable_only – Boolean. If it’s True, the dictionary only contains the trainable variables.

Returns:

Dictionary

get_all_val(val_in_fit=False)

Get the values of all trainable variables.

Parameters:

val_in_fit – Boolean. If it’s True, the values will be the ones that are actually used in fitting (thus may not be the physical values because of the boundary transformation).

Returns:

List of real numbers.

mask_params(params)

minimize(fcn, jac=True, method='BFGS', mini_kwargs={})

minimize a give function

minimize_error(fcn, fit_result)

read(name)

refresh_vars(init_val=None, bound_dic=None)

Refresh all trainable variables

remove_bound()

Remove a boundary for a variable

remove_var(name)

Remove a variable from self.variables. More specifically, two variables (name+’r’ and name+’i’) will be removed if it’s complex.

Parameters:

name – The name of the variable

rename_var(name, new_name, cplx=False)

Rename a variable.

Parameters:

• name – Name of the variable

• new_name – New name

• cplx – Boolean. Users should indicate if this variable is complex or not.

rp2xy(name)

Transform a complex variable into Cartesian coordinate. :param name: String

rp2xy_all(name_list=None)

If name_list is not provided, this method will transform all complex variables into Cartesian coordinate.

Parameters:

name_list – List of names of complex variables

set(name, value, val_in_fit=True)

Set value for a real variable. If val_in_fit is True, this is the variable used in fitting, not considering its boundary transformation.

Parameters:

• name – String

• value – Real number

set_all(vals, val_in_fit=False)

Set values for some variables.

Parameters:

vals – It can be either a dictionary or a list of real numbers. If it’s a list, the values correspond to all trainable variables in order.

set_bound(bound_dic, func=None, overwrite=False)

Set boundary for the trainable variables. The variables will be constrained in their ranges while fitting.

Parameters:

• bound_dic – Dictionary. E.g. {“name1”:(-1.0,1.0), “name2”:(None,1.0)}. In this example, None means it has no lower limit.

• func – String. Users can provide a string to describe the transforming function. For details, refer to class tf_pwa.variable.Bound.

• overwrite – Boolean. If it’s True, the program will not throw a warning when overwrite a variable with the same name.

set_fix(name, value=None, unfix=False)

Fix or unfix a variable (change the trainability) :param name: The name of the variable :param value: The fixed value. It’s useless if unfix=True. :param unfix: Boolean. If it’s True, the variable will become trainable rather than be fixed.

set_same(name_list, cplx=False)

Set some variables to be the same.

Parameters:

• name_list – List of strings. Name of the variables.

• cplx – Boolean. Whether the variables are complex or real.

set_share_r(name_list)

If some complex variables want to share their radia variable while their phase variable are still different. Users can set this type of constrain using this method.

Parameters:

name_list – List of strings. Note the strings should be the name of the complex variables rather than of their radium parts.

set_trans_var(xvals)

\(y = y(x)\)

Parameters:

fcn_grad – The return of class tf_pwa.model???

Returns:

standard_complex()

std_polar(name)

Transform a complex variable into standard polar coordinate, which mean its radium part is positive, and its phase part is between \(-\pi\) to \(\pi\). :param name: String

std_polar_all()

Transform all complex variables into standard polar coordinate.

temp_params(params)

property trainable_variables

List of tf.Variable. It is similar to tf.keras.Model.trainable_variables.

trans_error_matrix(hess_inv, xvals)

Bound trans for error matrix \(F(x)=F(y(x))\), \(V_y = y' V_x y'\)

Returns:

trans_f_grad_hess(f)

\(F(x)=F(y(x))\), \(G(x)=\frac{dF}{dx}=\frac{dF}{dy}\frac{dy}{dx}\)

Parameters:

fcn_grad – The return of class tf_pwa.model???

Returns:

trans_fcn_grad(fcn_grad)

\(F(x)=F(y(x))\), \(G(x)=\frac{dF}{dx}=\frac{dF}{dy}\frac{dy}{dx}\)

Parameters:

fcn_grad – The return of class tf_pwa.model???

Returns:

trans_grad_hessp(f)

\(F(x)=F(y(x))\), \(G(x)=\frac{dF}{dx}=\frac{dF}{dy}\frac{dy}{dx}\)

Parameters:

fcn_grad – The return of class tf_pwa.model???

Returns:

trans_params(polar)

Transform all complex variables into either polar coordinate or Cartesian coordinate.

Parameters:

polar – Boolean

xy2rp(name)

Transform a complex variable into polar coordinate. :param name: String

xy2rp_all(name_list=None)

If name_list is not provided, this method will transform all complex variables into polar coordinate.

Parameters:

name_list – List of names of complex variables

combineVM(vm1, vm2, name='', same_list=None)

This function combines two VarsManager objects into one. (WIP)

Parameters:

• name – The name of this combined VarsManager

• same_list – To make some variables in the two VarsManager to be the same. E.g. if same_list = ["var",["var1","var2"]], then “var” in vm1 and vm2 will be the same, and “var1” in vm1 and “var2” in vm2 will be the same.

deep_stack(dic, deep=1)