MicEMD package¶

Subpackages¶

Submodules¶

MicEMD.utils module¶

Created on Fri Aug 21 15:20:36 2020

@author: Wang Zhen Methods: - mkvc: Creates a vector with the number of dimension specified - RotationMatrix: create the Euler rotation matrix

MicEMD.utils.RotationMatrix(theta, phi, psi)¶

Convert v in the observation frame to v prime in the object frame or rotate the vector about the origin.

theta: float: pitch angle
phi: float: roll angle
psi: float: yaw angle

res: ndarry: the Euler rotation matrix

This program rotates order (Z ->y->x), inside rotation. The outer spin of each particular order is equivalent to the inner spin of its opposite order and vice versa. The rotation matrix of the coordinate system about the origin and the rotation matrix of the vector (coordinate) about the origin are each other’s transpose. The rotation matrix of the world coordinate system to the target coordinate system and the rotation matrix of the target coordinate system to the world coordinate system are each other’s transpose.

[1] Y Wan, Wang Z , Wang P , et al. A Comparative Study of Inversion Optimization Algorithms for Underground Metal Target Detection[J]. IEEE Access, 2020, PP(99):1-1.

MicEMD.utils.mkvc(x, numDims=1)¶

Creates a vector with the number of dimension specified

e.g.:

a = np.array([1, 2, 3])

mkvc(a, 1).shape
    > (3, )

mkvc(a, 2).shape
    > (3, 1)

mkvc(a, 3).shape
    > (3, 1, 1)

Module contents¶

class MicEMD.Classification(data, method, cls_para, *args, **kwargs)¶

Bases: MicEMD.tdem.classification.BaseTDEMClassification

the class of the classification algorithm

data: tuple: conclude the train set and the test set
method: str: the method of classification
cls_para: dict: the Parameters for the classification algorithm

run: run the the classification algorithm and return the result
error: return the res of the classification

property error¶

run()¶

class MicEMD.Collection(t_split, snr, **kwargs)¶

Bases: object

the class conclude the parameters about collecting

t_split: int: the sampled times of the response every second
SNR: int: the Signal to Noise Ratio

class MicEMD.Detector(radius, current, pitch, roll)¶

Bases: object

the detector in TDEM

radius: float: the radius of the detector
current: float: the current of the detector
pitch: float: the pitch angle of the target
roll: float: the roll angle of the target

mag_moment: Returns the magnetic moment value of transmitter coil

property mag_moment¶

Calculate magnetic moment value of transmitter coil according to detector parameters.

TYPEfloat: The value of magnetic moment of z axis.

class MicEMD.FDEMHandler(**kwargs)¶

Bases: MicEMD.handler.handler.FDEMBaseHandler

The class is used to handle the results of the simulation and inversion

kwargs: optional: if there is para, the para is used to create the default dir of saving files

get_save_fdem_dir:: to create the file path by parameters about this target scene
save_fwd_data:: save the observed data that simulating by forward simulation
save_inv_res:: save the inversion result by custom path
save_fwd_data_default:: according to the default path to save the forward data
save_inv_res_default:: according to the default path to save the forward data
show_detection_scenario:: show the detection scenario
show_mag_map:: show the secondary field strength of some axis
show_inv_res:: show the inversion results in line chart and bar chart
show_detection_scenario_default:: according to the default path to save the scenerio
show_mag_map_default:: according to the default path to save the mag map
show_inv_res_default:: according to the default path to save the result display chart

get_save_fdem_dir()¶

to get the parameters about this target scene to make file save the data about fdem_forward_simulation

file_namestr: the file name to save the data about fdem_forward_simulation and fdem_inversion

save_forward()¶

save_fwd_data(data, file_name=None)¶

save the data of the forward_res the function to save the forward res

data: ndarray: conclude the receiver location and magnetic data
file_name: str: the name of the file that you want to save, the Default relative path is ‘../results/fdemResults/forward_res’,if you just input the file name, it will be saved in the path

save_fwd_data_default(loc_mag)¶

the mag_data(contained the detection position and secondary field data) saved by ‘.xls’ file.

file_namestr: the specific path of the fdem_results. the path named by the parameters of the detection scene

None.

save_inv()¶

save_inv_res(inv_res, file_name)¶

save the inversion result

inv_res: dict: the res of the inversion, conclude the error, the true value and the pred value
file_name: str: the name of the file that you want to save, the Default relative path is ‘../results/fdemResults/inverse_res’,if you just input the file name, it will be saved in the path

save_inv_res_default(inv_res, method)¶

the inv_result(contained the true properties,estimate properties and errors between them) saved by ‘.xls’ file named by the optimization algorithm name + ‘_invResult’

file_namestr: the specific path of the fdem_results. the path named by the parameters of the detection scene

None.

show_detection_scenario(Target, Collection, show=False, save=False, file_name=None, fig=None)¶

in 3D ax show the detection scene,the main part is to show the metal cylinder with different posture,the posture of the metal cylinder can be showed by the rotation matrix

targetclass Target: Contains the parameters of the target.
collectionclass Collection: Contains the parameters of the collection process.
show: bool: whether to show the fig
save: bool: whether to save the fig
file_name: str: if save is true, the file path to save, it is ‘../results/fdemResults/forward_res’ defaultly
figmatplotlib.figure.Figure: it is None defaultly

show_detection_scenario_default(fig=None, show=True, save=True)¶

in 3D ax show the detection scene,the main part is to show the metal cylinder with different posture,the posture of the metal cylinder can be showed by the rotation matrix

figmatplotlib.figure.Figure: Empty figure.
targetclass Target: Contains the parameters of the target.
collectionclass Collection: Contains the parameters of the collection process.

None.

show_discretize(mesh, mapped_model, Collection, Target, show=False, save=False, file_name=None, fig=None)¶

show_discretize_default(mesh, mapped_mode, fig=None, show=True, save=True)¶

show_inv_res(inv_res, show=False, save=False, file_name=None, fig=None)¶

show_inv_res_default(inv_res, fig=None, show=True, save=True)¶

show_mag_map(loc_mag, Collection, show=False, save=False, file_name=None, fig=None)¶

show the magnetic field map

figmatplotlib.figure.Figure: Empty figure.
receiver_locationsnumpy.ndarray, shape(N*3): See fdem_forward_simulation.fdem_forward_simulation receiver_locations.
mag_datanumpy.ndarray, shape(N*1): See fdem_forward_simulation.fdem_forward_simulation mag_data.

None.

show_mag_map_default(loc_res, fig=None, show=True, save=True)¶

figmatplotlib.figure.Figure: Empty figure.
receiver_locationsnumpy.ndarray, shape(N*3): See fdem_forward_simulation.fdem_forward_simulation receiver_locations.
mag_datanumpy.ndarray, shape(N*1): See fdem_forward_simulation.fdem_forward_simulation mag_data.

None.

class MicEMD.Inversion(data, method, inv_para)¶

Bases: MicEMD.fdem.inversion.BaseFDEMInversion

inverse the properties of the target

based on the optimization algorithms to solve the inversion problem

data: tuple: the data conclude the observed data, target class and detector class
method: str: the name of the optimization
inv_para: dict: the parameters setting of the optimization

true_properties:: Returns the true properties of the target
inv_objective_function:: Returns the calculated objective_function value in x position
inv_objectfun_gradient:: Returns the calculated gradient value in x position
inv_residual_vector:: Returns the residual vector.
inv_get_preicted_data:: Returns Predicted secondary fields calculated by the dipole model at all receiver_loc.
inv_forward_calculation:: Returns predicted secondary fields according the linear magnetic dipole model at receiver_loc.
inv_residual_vector_grad:: Returns the gradient of all the residual vectors.
inv_forward_grad:: Returns the gradient of inv_forward_calculation()
polar_tensor_to_properties:: ransform the polar tensor to properties transform M11, M22, M33, M12, M13, M23 to polarizability and pitch and roll angle and return
find_xyz_polarizability_index:: make the order of eigenvalue correspond to the polarizability order
run:: run the process of the inversion and return the estimate values
error:: Returns the error between true value and estimate value

property error¶

calculate the error of the true value and estimate value

error: ndarray: return the error

find_xyz_polarizability_index(polarizability)¶

make the order of eigenvalue correspond to the polarizability order

polarizabilityTYPE: DESCRIPTION.

None.

inv_forward_calculation(detector, receiver_loc, x)¶

Forward calculation in inversion process. It generates predicted secondary fields according the linear magnetic dipole model at receiver_loc.

detector : class Detector receiver_loc : numpy.array, size=3

A receiver location.

xnumpy.array, size=9: See inv_objective_function x.

Bnumpy.mat, shape=(3*1): Predicted secondary field.

Wan Y, Wang Z, Wang P, et al. A Comparative Study of Inversion Optimization Algorithms for Underground Metal Target Detection[J]. IEEE Access, 2020, 8: 126401-126413.

inv_forward_grad(detector, receiver_loc, x)¶

Use the difference method to calculate the gradient of inv_forward_calculation().

detector : class Detector receiver_loc : numpy.array, size=3

A receiver location.

xnumpy.array, size=9: See inv_objective_function x.

grad : numpy.mat, shape=(3*9)

inv_get_preicted_data(detector, receiver_locations, x)¶

It generates predicted secondary fields at all receiver locations.

detector : class Detector receiver_locations : numpy.ndarray, shape=(N*3)

See inv_objective_function receiver_locations.

xnumpy.array, size=9: See inv_objective_function x.

predicted_mag_datanumpy.ndarray, shape=(N*3): Predicted secondary fields.

inv_objectfun_gradient(detector, receiver_locations, true_mag_data, x)¶

The gradient of the objective function with respect to x.

detector : class Detector receiver_locations : numpy.ndarray, shape=(N*3)

See inv_objective_function receiver_locations.

true_mag_datanumpy.ndarray, shape=(N*3): See inv_objective_function true_mag_data.
xnumpy.array, size=9: See inv_objective_function x.

gradnumpy.array, size=9: The partial derivative of the objective function with respect to nine parameters.

inv_objective_function(detector, receiver_locations, true_mag_data, x)¶

Objective function.

detector : class Detector receiver_locations : numpy.ndarray, shape=(N*3), N=len(receiver_locations)

All acquisition locations of the detector. Each row represents an acquisition location and the three columns represent x, y and z axis locations of an acquisition location.

true_mag_datanumpy.ndarray, shape=(N*3): All secondary fields of acquisition locations (x, y and z directions).
xnumpy.array, size=9: target’s parameters in inversion process, including position x, y, z, polarizability M11, M22, M33, M12, M13, M23.

objective_fun_value : float

inv_residual_vector(detector, receiver_locations, true_mag_data, x)¶

Construct the residual vector.

detector : class Detector receiver_locations : numpy.ndarray, shape=(N*3)

See inv_objective_function receiver_locations.

true_mag_datanumpy.ndarray, shape=(N*3): See inv_objective_function true_mag_data.
xnumpy.array, size=9: See inv_objective_function x.

residualnumpy.mat, shape=(N*3,1): Residual vector.

inv_residual_vector_grad(detector, receiver_locations, x)¶

Calculate the gradient of all the residual vectors.

detector : class Detector receiver_locations : numpy.ndarray, shape=(N * 3)

See inv_objective_function receiver_locations.

xnumpy.array, size=9: See inv_objective_function x.

gradnumpy.mat, shape=(N*3,9): Jacobian matrix of the residual vector.

polar_tensor_to_properties(polar_tensor_vector)¶

transform the polar tensor to properties transform M11, M22, M33, M12, M13, M23 to polarizability and pitch and roll angle

polar_tensor_vectornumpy.array, size=6: M11, M22, M33, M12, M13, M23.

None.

run()¶

run the process of the inversion

res: ndarray: return the estimate properties[x, y, z, bx, by, bz, pitch, roll]

property true_properties¶

return the true properties

res: ndarry: return the true properties, conclude position, polarizability, pitch and roll angle of the target, amount to 8 inverse parameters

MicEMD.MLP(train_set, test_set, solver='lbfgs', hidden_layer_sizes=(50), activation='tanh')¶

the ANN classification algorithm

train_set: ndarry: the train set
test_set: ndarry: the test set
solver: str: the optimization of the ANN
hidden_layer_sizes: tuple: the ANN hidden layer sizes
activation: str: the activation of the ANN

res: tuple: (accuracy, y_pred, y_true),the accuracy of classification, the predict value and the true value

class MicEMD.Model(Survey)¶

Bases: MicEMD.tdem.model.BaseTDEMModel

dpred()¶

product the forward data

feature_lablendarry: shape(n,402), n represent the number of simulation feature_lable include material_flag, shape_flag and the response
sample: dict: represent a sample,it’s to show the data one of the collection key = [‘data’, ‘M1’, ‘M2’, ‘M1_without_noise’, ‘M2_without_noise’, ‘t’, ‘SNR’, ‘material’, ‘ta’, ‘tb’]

ellipsoid_k_plus(ta, tb, c)¶

ellipsoid_parameter(c, c0, d, ta, tb)¶

func(t, k, a, b, R)¶: calculate the response of the sphere and return it

parameter_sphere(c, c0, d, r)¶

use less para to fit the sphere response To reduce the computational complexity of the charac- teristic response, a simple empirical function defined by a minimum number of parameters is utilized to replicate the features of the characteristic response

c: float: the relative permeability of the target
c0: float: the permeability of vacuum
d: float: the conductivity of the target
r: float: the radius of the target

k, a, b, R: the tuple of the fitting parameters

1: J. T. Smith, H. F. Morrison, and A. Becker, “Parametric forms and the inductive response of a permeable conducting sphere,” Journal of Envi- ronmental & Engineering Geophysics, vol. 9, no. 4, pp. 213–216, 2004.

wgn_one_npower(x, snr)¶: add the noise to the date

MicEMD.RotationMatrix(theta, phi, psi)¶

Convert v in the observation frame to v prime in the object frame or rotate the vector about the origin.

theta: float: pitch angle
phi: float: roll angle
psi: float: yaw angle

res: ndarry: the Euler rotation matrix

This program rotates order (Z ->y->x), inside rotation. The outer spin of each particular order is equivalent to the inner spin of its opposite order and vice versa. The rotation matrix of the coordinate system about the origin and the rotation matrix of the vector (coordinate) about the origin are each other’s transpose. The rotation matrix of the world coordinate system to the target coordinate system and the rotation matrix of the target coordinate system to the world coordinate system are each other’s transpose.

[1] Y Wan, Wang Z , Wang P , et al. A Comparative Study of Inversion Optimization Algorithms for Underground Metal Target Detection[J]. IEEE Access, 2020, PP(99):1-1.

class MicEMD.Simulation(model)¶

Bases: MicEMD.tdem.simulation.BaseTDEMSimulation

pred()¶

class MicEMD.Source(Target, Detector, Collection, *args)¶

Bases: MicEMD.tdem.source.BaseTDEMSource

property source_list¶

class MicEMD.Survey(Source)¶

Bases: MicEMD.tdem.survey.BaseTDEMSurvey

property survey¶

class MicEMD.TDEMHandler(**kwargs)¶

Bases: MicEMD.handler.handler.TDEMBaseHandler

The class is used to handle the results of the simulation and classification

kwargs: optional
if there is para, the para is used to create the default dir of saving files

get_save_tdem_dir:
to create the file path by parameters about this target scene

save_fwd_data:
save the observed data that simulating by forward simulation

save_sample_data:

save the sample data of the fwd_data

save_fwd_data_default:: according to the default path to save the forward data
save_sample_data_default:: according to the default path to save the sample data
save_preparation_default:: save the pre-processed data
save_dim_reduction_default:: save the data after dimension reduction according to the default path
plot_confusion_matrix:: plot the result of classification
plot_confusion_matrix_default:: plot the result of classification according to the default path
plot_data:: plot the sample data

get_save_tdem_dir()¶

to get the parameters about this target scene to make file save the data about fdem_forward_simulation

file_namestr: the file name to save the data about fdem_forward_simulation and fdem_inversion

save_cls_res(cls_res, file_name)¶

save the classification result

cls_res: dict: the res of the classification, conclude the accuracy, the true value and the pred value
file_name: str: the name of the file that you want to save, the Default relative path is ‘../results/tdemResults/classify_res’,if you just input the file name, it will be saved in the path

save_cls_res_default(cls_res)¶

save the classification result defaultly

cls_res: dict: the res of the classification, conclude the accuracy, the true value and the pred value
file_name: str: the name of the file that you want to save, the Default relative path is ‘../results/tdemResults/classify_res’,if you just input the file name, it will be saved in the path

save_dim_reduction_default(train_set, test_set, task, dim_method)¶

save_fwd_data(response, file_name=None)¶

save the data of the forward_res the function as the general save function of the forward res

response: ndarry: the dataset to save
file_name: str: the name of the file that you want to save, the Default relative path is ‘../results/tdemResults/forward_res’,if you just input the file name, it will be saved in the path

save_fwd_data_default(response)¶

save the data of the forward_res the function as the general save function of the forward res

response: ndarry: the dataset to save
file_name: str: the name of the file that you want to save, the Default relative path is ‘../results/tdemResults/forward_res’,if you just input the file name, it will be saved in the path

save_preparation_default(train_set, test_set, task)¶

save_sample_data(sample, file_name, show=False)¶

save the sample data of the forward_res

sample: ndarry: the dataset to save
file_name: str: the name of the file that you want to save, the Default relative path is ‘../results/tdemResults/forward_res’,if you just input the file name, it will be saved in the path
show: bool: show the picture of the sample data

save_sample_data_default(sample, fig=None, show=True, save=True)¶

save the sample data of the forward_res

sample: ndarry: the dataset to save
file_name: str: the name of the file that you want to save, the Default relative path is ‘../results/tdemResults/forward_res’,if you just input the file name, it will be saved in the path
show: bool: show the picture of the sample data

show_cls_res(cls_res, type, fig=None, show=False, save=False, file_name=None)¶

This function prints and plots the confusion matrix. Normalization can be applied by setting normalize=True. Parameters: ———– type: list

the list of classification types

show: bool: whether to show
save: bool: whether to save
file_name: str: the name of the file that you want to save, the Default relative path is ‘../results/tdemResults/classify_res’,if you just input the file name, it will be saved in the path, if you don’t input the file name, it will be saved by the name ‘cls_res.pdf’

show_cls_res_default(cls_result, task, fig=None, show=False, save=True)¶: This function prints and plots the confusion matrix. Normalization can be applied by setting normalize=True.

show_sample_data(M1, M2, M1_without_noise, M2_without_noise, t, SNR, material, ta, tb, file_name=None, show=False, fig=None)¶

show the sample data

M1: ndarry: the M1 response of the target
M2: ndarry: the M2 response of the target
M1_without_noise: ndarry: the M1 response of the target without the noise
M2_without_noise: ndarry: the M2 response of the target without the noise
t: int: the times collected per second
SNR: int: SNR(Signal to Noise Ratio)
material: str: the material of the target of the sample
ta: int: the radial radius of the target of the sample
tb: int: the axial radius of the target of the sample
file_name: str: the name of the file that you want to save, the Default relative path is ‘../results/tdemResults/forward_res’,if you just input the file name, it will be saved in the path
show: bool: whether to show the picture

class MicEMD.Target(material, shape, attribute, ta_min, ta_max, tb_min, tb_max, a_r_step, b_r_step, **kwargs)¶

Bases: object

Refer in particular to spheroid targets.

material: list: the list of material of the target
shape: list: the list of shape of the target
attribute: 2D-ndarray: the relative permeability, permeability of vacuum and conductivity of the target
ta_minfloat: represent the min radial radius of the spheroid targets
ta_maxfloat: represent the max radial radius of the spheroid targets
tb_minfloat: represent the min axial radius of the spheroid targets
tb_maxfloat: represent the max axial radius of the spheroid targets
a_r_step: float: represent the changed step of radial radius
b_r_step: float: represent the changed step of axial radius

MicEMD.classify(data_set, cls_method, cls_para=None, *args, **kwargs)¶

the interface of the classification of the target

data_set: tuple: conclude the train set and the test set
cls_method: str: the method of classification
cls_para: dict: the Parameters for the classification algorithm

res: dict: keys: [‘accuracy’, ‘y_pred’, ‘y_true’], represent the accuracy , predict value and true value of the classification

MicEMD.classify_method(train_set, test_set, cls_method='ANN', cls_para=None)¶

solve the classification problem of the target

train_set: ndarry: the data of the train set
test_set: ndarry: the data of the test set
cls_method: str: the name of the classification method
cls_para: dict: the parameters of the classifier

res: tuple: (accuracy, y_pred, y_true),the accuracy of classification, the predict value and the true value

MicEMD.data_prepare(response, task)¶

preparation of the tdem data

response: ndarry: the data of response in TDEM
task: str: the specific task of classification

res: tuple: conclude the train set and the test set.

MicEMD.inverse(data, method, inv_para, *args, **kwargs)¶

the interface is used to handle the process of inversion

data: tuple: the data conclude the observed data, target class and detector class
method: str: the name of the optimization
inv_para: dict: the parameters setting of the optimization

res: dict: res conclude the predicted value, true value and the error value

MicEMD.mkvc(x, numDims=1)¶

Creates a vector with the number of dimension specified

e.g.:

a = np.array([1, 2, 3])

mkvc(a, 1).shape
    > (3, )

mkvc(a, 2).shape
    > (3, 1)

mkvc(a, 3).shape
    > (3, 1, 1)

MicEMD.numopt(fun, grad, jacobian, x0, iterations, method='BFGS', tol=1e-09)¶

Call optimization algorithms.

fun: func: the cite of objective function
grad: func: the cite of calculate grad of the fun(objective function)
jacobian: func: the cite of calculate jacobian
x0: list: the initial value of the estimate value
methodstr: The name of optimization algorithms.
iterationsint: Maximum iterations of optimization algorithms.
tolfloat: Tolerance of optimization algorithms.

res.x : numpy.array, size=9

MicEMD.preprocess(response, dim_red_method=None)¶

The data were dimensionalized

response: ndarry: the received response
dim_red_method: str: the method of the dimensionality reduction

res: tuple: the train set and test set of after dimensionality reduction for example: res[0] represent the train set after dimensionality reduction res[1] represent the test set after dimensionality reduction

MicEMD.simulate(target, detector, collection, model='dipole', *args, **kwargs)¶

the interface of the simulation

target: class: the target of the TDEM
detector: class: the detector of the TDEM
collection: class: the collection of the TDEM
model: str: the name of the model

res: tuple: the result of the method dpred in model class

MicEMD.statistic_feature(data)¶

data: tuple: conclude the train set and test set

return the train set and test set after dimensionality