Macroscopic pml with mur in H PML

[jackieyao0114]

This PR is to add the macroscopic material property mu_r into evolving H field in the PML, especially when Ms=0 such that mu_r is essential for phase matching at the interface between the real box and PML box.

One sample case of a plane wave traveling in a medium with mu_r=4 and Ms=0 is shown below:

The input file used to generate the animation is copied here:

# This is a E+H (use USE_LLG=TRUE) simulation of a
# plane wave in a periodic domain
################################
####### GENERAL PARAMETERS ######
#################################
max_step = 1000
amr.n_cell = 16 16 128
amr.max_grid_size = 32
amr.blocking_factor = 16
geometry.coord_sys   = 0
geometry.is_periodic = 1  1  0
geometry.prob_lo     =  -16.e-6 -16.e-6 -128.e-6
geometry.prob_hi     =   16.e-6  16.e-6  128.e-6
amr.max_level = 0

#################################
############ NUMERICS ###########
#################################
warpx.verbose = 0
warpx.use_filter = 0
warpx.cfl = 0.9
warpx.do_pml = 1
algo.em_solver_medium = macroscopic # vacuum/macroscopic
algo.macroscopic_sigma_method = laxwendroff # laxwendroff or backwardeuler
macroscopic.sigma_init_style = "parse_sigma_function" # parse or "constant"
macroscopic.sigma_function(x,y,z) = "0.0"
macroscopic.epsilon_init_style = "parse_epsilon_function" # parse or "constant"
macroscopic.epsilon_function(x,y,z) = "8.8541878128e-12"
macroscopic.epsilon_function(x,y,z) = "epsilon_r*8.8541878128e-12"
macroscopic.mu_init_style = "parse_mu_function" # parse or "constant"
macroscopic.mu_function(x,y,z) = "1.25663706212e-06"
macroscopic.mu_function(x,y,z) = "mu_r*1.25663706212e-06"
particles.nspecies = 0

#################################
############ FIELDS #############
#################################
my_constants.mu_r = 4
my_constants.epsilon_r = 1
my_constants.pi = 3.14159265359
my_constants.L = 141.4213562373095e-6
my_constants.c = 299792458.
my_constants.wavelength = 64.e-6

warpx.E_ext_grid_init_style = parse_E_ext_grid_function
warpx.Ez_external_grid_function(x,y,z) = 0.
warpx.Ex_external_grid_function(x,y,z) = 0.
#warpx.Ey_external_grid_function(x,y,z) = "1.e5*exp(-z**2/L**2)*cos(2*pi*z/wavelength)"
warpx.Ey_external_grid_function(x,y,z) = "1.e5*exp(-z**2/L**2)*cos(2*pi*z/wavelength * sqrt(epsilon_r*mu_r))"
warpx.H_ext_grid_init_style = parse_H_ext_grid_function
warpx.Hx_external_grid_function(x,y,z)= "-1.e5*exp(-z**2/L**2)*cos(2*pi*z/wavelength * sqrt(epsilon_r*mu_r)) / sqrt( mu_r*1.25663706212e-06 / (epsilon_r*8.8541878128e-12) )"
warpx.Hy_external_grid_function(x,y,z)= 0.
warpx.Hz_external_grid_function(x,y,z) = 0.

# If you want to use a USE_LLG build with Ms=0 everywhere, uncomment these settings
warpx.mag_M_normalization = 1
macroscopic.mag_Ms_init_style = constant
macroscopic.mag_Ms = 0.
macroscopic.mag_alpha_init_style = constant
macroscopic.mag_alpha = 0.
macroscopic.mag_gamma_init_style = constant
macroscopic.mag_gamma = 0.

# Diagnostics
diagnostics.diags_names = plt
plt.period = 10
plt.fields_to_plot = Ex Ey Ez Hx Hy Hz Bx By Bz
plt.diag_type = Full

[RevathiJambunathan]

Thank you @jackieyao0114 for this PR.

In the implementation it looks like we expect the user to ensure mu_r and Ms are consistently initialized in the input file.
If this is the case, can you please add a couple of lines in the documentation explaining this?

[RevathiJambunathan]

was there a reason for this to be changed to periodic?

[jackieyao0114]

oh no, this is just the residual in the test. I'll change it back

[jackieyao0114]

Thank you @jackieyao0114 for this PR.

In the implementation it looks like we expect the user to ensure mu_r and Ms are consistently initialized in the input file.
If this is the case, can you please add a couple of lines in the documentation explaining this?

The explanation has been added in parameters.rst.

[RevathiJambunathan]

coud you remove this unused function

[RevathiJambunathan]

delete this function too

[ajnonaka]

Are we actually enforcing this in the code with an Abort(), or warning with a Warn(), or neither? Is it more accurate to say that the value of mu_r in regions where Ms != 0 simply doesn't matter?

[jackieyao0114]

Operationally, it is true that the value of mu_r in regions where Ms != 0 simply doesn't matter. But I'm concerned this might be misleading. Maybe a warning should be added in the next PR (together with this document)?

[ajnonaka]

Approve pending two minor comments.