Reference¶

Simulation¶

The Simulation class treats field indices as follows

class rcfdtdpy.sim.Simulation(i0, i1, di, n0, n1, dn, epsilon0, mu0, boundary, currents=[], materials=[], nstore=[], istore=[])[source]¶

Represents a single simulation. Field is initialized to all zeros.

Parameters:

i0 – The spatial value at which the field starts
i1 – The spatial value at which the field ends
di – The spatial step size
n0 – The temporal value at which the field starts
n1 – The temporal value at which the field ends
dn – The temporal step size
epsilon0 – \(\epsilon_0\), the vacuum permittivity
mu0 – \(\mu_0\), the vacuum permeability
boundary – The boundary type of the field, either ‘zero’, for fields bounded by zeros or ‘absorbing’ for absorbing boundary conditions
currents – A Current object or a list of Current objects that represent the currents present in the simulation, defaults to none
materials – A Material object or a list of Material objects that represent the materials present in the simulation, defaults to none
nstore – A list of time indices to save field values at in all points in space
istore – A list of spatial indices to save field values at in all points in time

static calc_arrays(i0, i1, di, n0, n1, dn)[source]¶

Calculates spatial and time arrays of the same dimensions of the simulation. Array values are populated by their the spatial and temporal values at their respective simulation spatial and temporal indices.

Parameters:	i0 – The spatial value at which the field starts i1 – The spatial value at which the field ends di – The spatial step size n0 – The temporal value at which the field starts n1 – The temporal value at which the field ends dn – The temporal step size
Returns:	A tuple (z, t) of the spatial and temporal arrays

static calc_dims(i0, i1, di, n0, n1, dn)[source]¶

Calculates the dimensions of the simulation in cells.

Parameters:	i0 – The spatial value at which the field starts i1 – The spatial value at which the field ends di – The spatial step size n0 – The temporal value at which the field starts n1 – The temporal value at which the field ends dn – The temporal step size
Returns:	A tuple (ilen, nlen) of the spatial and temporal dimensions

export_ifields()[source]¶

Exports the field values at spatial indices specified by istore at the Simulation object’s initialization, where an index along axis=1 corresponds to the corresponding spatial index in istore. Values along axis=0 correspond to the temporal index.

Returns:	(hfield, efield, hfieldr, efieldr) where the suffix r corresponds to a reference field. If istore is unspecified returns None

export_nfields()[source]¶

Exports the field values at temporal indices specified by nstore at the Simulation object’s initialization, where an index along axis=0 corresponds to the corresponding temporal index in nstore. Values along axis=1 correspond to the spatial index.

Returns:	(hfield, efield, hfieldr, efieldr) where the suffix r corresponds to a reference field. If nstore is unspecified returns None

get_dims()[source]¶

Returns the dimensions of the simulation.

Returns:	A tuple `(ilen, nlen)` containing the spatial and temporal dimensions in cells

get_materials()[source]¶

Returns the list of Material objects present in the simulation.

Returns:	A list of Material objects

simulate(tqdmarg={})[source]¶

Executes the simulation.

Parameters:	tqdmarg – The arguments to pass the tdqm iterator (lookup arguments on the tqdm documentation)

Current¶

The Current class is used to represent currents in the simulation. The current argument passed to the Current object at initialization is represented using the following two dimensional array

where \(n\) represents the time index of the current and \(i\) represents the spatial index of the current.

class rcfdtdpy.sim.Current(i0, n0, ilen, nlen, current)[source]¶

The Current class is used to represent a current in the simulation.

Parameters:	i0 – The starting spatial index of the current n0 – The starting temporal index of the current ilen – The number of spatial indices in the simulation nlen – The number of temporal indices in the simulation current – A matrix representing the current, where axis=0 represents locations in time \(n\) and axis=1 represents locations in space \(i\)

get_current(n)[source]¶: Returns the current at time index \(n\) as an array the length of the simulation

Materials¶

There are a number of material types that have been implemented for use with the RC-FDTD simulation.

Material¶

The Material class is an abstract class containing the properties and functions that any material implementation should have. Any subclass of material should call to super at initialization and implement each function defined here.

class rcfdtdpy.sim.Material(di, dn, ilen, nlen, material_i0, material_i1, material_n0, material_n1)[source]¶

The Material class is an abstract class that defines the minimum requirements for a Material object to have in the simulation. All Materials in the simulation must inherit Material.

Parameters:

di – The spatial time step of the simulation
dn – The temporal step size of the simulation
ilen – The number of spatial indices in the simulation
nlen – The number of temporal indices in the simulation
material_i0 – The starting spatial index of the material
material_i1 – The ending spatial index of the material
material_n0 – The starting temporal index of the material
material_n1 – The ending temporal index of the material

get_chi0()[source]¶

Returns the value of \(\chi_0\) at the current time step in the simulation at each spatial location in the simulation.

Returns:	The current value of \(\chi_0\) at each spatial location in the simulation

get_epsiloninf()[source]¶

Returns the value of \(\epsilon_\infty\) at the current time step in the simulation at each spatial location in the simulation.

Returns:	The current value of \(\epsilon_\infty\) at each spatial location in the simulation

get_psi()[source]¶

Returns the value of \(\psi\) at the current time step in the simulation at each spatial location in the simulation.

Returns:	The current value of \(\psi\) at each spatial location in the simulation

reset_material()[source]¶: This function is called before each simulation. It should reset any material values that are calculated during the simulation to their initial values.

update_material(n, efield)[source]¶

This function is called at the start of each simulation time step. It should update the \(\chi\) and \(\psi\) values of the material to their values at n.

Parameters:	n – The current temporal index of the simulation. efield – The previous electric field of the simulation.

EmptyMaterial¶

The EmptyMaterial class represents vacuum

class rcfdtdpy.sim.EmptyMaterial(di, dn, ilen, nlen)[source]¶

Represents an empty Material, i.e. vacuum

get_chi0()[source]¶

Returns the value of \(\chi_0\) at the current time step in the simulation at each spatial location in the simulation.

Returns:	The current value of \(\chi_0\) at each spatial location in the simulation

get_epsiloninf()[source]¶

Returns the value of \(\epsilon_\infty\) at the current time step in the simulation at each spatial location in the simulation.

Returns:	The current value of \(\epsilon_\infty\) at each spatial location in the simulation

get_psi()[source]¶

Returns the value of \(\psi\) at the current time step in the simulation at each spatial location in the simulation.

Returns:	The current value of \(\psi\) at each spatial location in the simulation

reset_material()[source]¶: This function is called before each simulation. It should reset any material values that are calculated during the simulation to their initial values.

update_material(n, efield)[source]¶

This function is called at the start of each simulation time step. It should update the \(\chi\) and \(\psi\) values of the material to their values at n.

Parameters:	n – The current temporal index of the simulation. efield – The previous electric field of the simulation.

StaticMaterial¶

The StaticMaterial class is an implementation of the Material class. The variables \(A_1\), \(A_2\), \(\gamma\), and \(\beta\) are represented using the following two dimensional array

where \(m_0\) is the starting index of the material. Increments along the vertical axis represent increments in the oscillator index \(j\), and increments along the horizontal axis represent increments in space.

The StaticMaterial class uses the update equations for \(\psi^n\) derived in Beard et al..

class rcfdtdpy.sim.StaticMaterial(di, dn, ilen, nlen, material_i0, epsiloninf, a1, a2, g, b, opacity=None, istore=[])[source]¶

The StaticMaterial class allows for the simulation of a static material, that is a material that has a constant definition of electric susceptibility in time. The electric susceptibility is modeled using a harmonic oscillator. This material is more computationally efficient than NumericMaterial, and uses the update equations specified in Beard et al..

Parameters:

di – The spatial time step of the simulation
dn – The temporal step size of the simulation
ilen – The number of spatial indices in the simulation
nlen – The number of temporal indices in the simulation
material_i0 – The starting spatial index of the material
epsiloninf – The \(\epsilon_\infty\) of the material, which is constant over space and time.
a1 – A matrix representing \(A_1\) where axis=0 represents the \(j\) th oscillator and axis=1 represents the \(i\) th spatial index
a2 – A matrix representing \(A_2\) where axis=0 represents the \(j\) th oscillator and axis=1 represents the \(i\) th spatial index
g – A matrix representing \(\gamma\) where axis=0 represents the \(j\) th oscillator and axis=1 represents the \(i\) th spatial index
b – A matrix representing \(eta\) where axis=0 represents the \(j\) th oscillator and axis=1 represents the \(i\) th spatial index
opacity – A vector representing the opacity of the material in time. Each index corresponds to the \(n\) th time index of the material where 1 corresponds to the material being opaque and 0 corresponds to the material being transparent. Values can be real numbers. Defaults to an opaque material for all time.
istore – A list of spatial indices to save \(\chi\) values at in all points in time

export_ifields()[source]¶

Exports the \(\chi\) values at spatial indices specified by istore at the Material object’s initialization, where an index along axis=1 corresponds to the corresponding spatial index in istore. Values along axis=0 correspond to the temporal index.

Returns:	chi or None if istore is unspecified.

get_chi0()[source]¶

Returns the value of \(\chi^0\) at all spatial indices resulting from the material.

Returns:	\(\chi^0\) at all values of the simulation resulting from the material.

get_epsiloninf()[source]¶

Returns the value of \(\epsilon_\infty\) at all spatial indices resulting from the material.

Returns:	\(\epsilon_\infty\) at all values of the simulation resulting from the material.

get_psi()[source]¶

Calculates psi at all points in the simulation using the current value of psi_1 and psi_2. Scaled by the opacity array passed in at initialization.

Returns:	\(\psi^n\) at all values of the simulation resulting from the material where \(n\) is given by the number of times update_material has been called by the Material’s corresponding Simulation object, which is once per simulation step.

reset_material()[source]¶: This function is called before each simulation. It should reset any material values that are calculated during the simulation to their initial values.

update_material(n, efield)[source]¶

Updates the values of \(\psi\) and \(\chi\) Saves the values of \(chi\) requested via the istore parameter.

Parameters:	n – The iteration index \(n\) efield – The efield to use in update calculations

NumericMaterial¶

The NumericMaterial class is an implementation of the Material class designed to simulate a material with any arbitrary definition of electric susceptibility \(\chi(t)\). The value of \(\chi^m\) at each simulation step is calculated at the initialization of the NumericMaterial.

class rcfdtdpy.sim.NumericMaterial(di, dn, ilen, nlen, material_i0, material_i1, chi_func, epsiloninf_func, tqdmarg={})[source]¶

The NumericMaterial class represents a material that has a non-constant definition of electric susceptibility in time. Currently this Material can only represent materials that have a constant definition of electric susceptibility in space.

Parameters:

di – The spatial time step of the simulation
dn – The temporal step size of the simulation
ilen – The number of spatial indices in the simulation
nlen – The number of temporal indices in the simulation
material_i0 – The starting spatial index of the material
material_i1 – The ending spatial index of the material
chi_func – A function representing the electric susceptibility \(\chi\) as a function of time. The function should accept a single argument n corresponding to the time index.
epsiloninf – A function representing the \(\epsilon_\infty\) of the material as a function of time. The function should accept a single argument n corresponding to the time index.
tqdmarg – The arguments to pass the tdqm iterator (lookup arguments on the tqdm documentation).

export_chi()[source]¶

Exports the electric susceptibility \(\chi\) at each time index.

Returns:	The electric susceptibility \(\chi\)

get_chi0()[source]¶

Returns the value of \(\chi_0\) at the current time step in the simulation at each spatial location in the simulation.

Returns:	The current value of \(\chi_0\) at each spatial location in the simulation

get_epsiloninf()[source]¶

Returns the value of \(\epsilon_\infty\) at the current time step in the simulation at each spatial location in the simulation.

Returns:	The current value of \(\epsilon_\infty\) at each spatial location in the simulation

get_psi()[source]¶

Returns the value of \(\psi\) at the current time step in the simulation at each spatial location in the simulation.

Returns:	The current value of \(\psi\) at each spatial location in the simulation

reset_material()[source]¶: This function is called before each simulation. It should reset any material values that are calculated during the simulation to their initial values.

update_material(n, efield)[source]¶

This function is called at the start of each simulation time step. It should update the \(\chi\) and \(\psi\) values of the material to their values at n.

Parameters:	n – The current temporal index of the simulation. efield – The previous electric field of the simulation.

TwoStateMaterial¶

The TwoStateMaterial class is possibly unstable. Its use is not recommended.

class rcfdtdpy.sim.TwoStateMaterial(di, dn, ilen, nlen, n_ref_ind, material_i0, e_a1, e_a2, e_b, e_g, g_a1, g_a2, g_b, g_g, v_a1, v_a2, v_b, v_g, alpha, Gamma, t_diff, tau, b, epsiloninf, tqdmarg_f={}, tqdmarg_c={})[source]¶

The TwoStateMaterial class represents a material that has a non-constant definition of electric susceptibility in time. This material is represents the same material proposed in Beard and Schmuttenmaer 2001 (www.doi.org/10.1063/1.1338526). The ground state electric susceptibility oscillator is defined by

\(\chi_{g,j}(t)=e^{-\gamma_{g,j}t}\left[A_{g,1,j}e^{\beta_{g,j}t}+A_{g,2,j}e^{-\beta_{g,j}t}\right]\)

and the excited state electric susceptibility oscillator is defined by

\(\chi_{e,j}(t)=e^{-\gamma_{e,j}t}\left[A_{e,1,j}e^{\beta_{e,j}t}+A_{e,2,j}e^{-\beta_{e,j}t}\right]\)

There is also an visual electric susceptibility oscillator that represents any susceptibility change resulting directly from the incident visual pulse. This is defined by

\(\chi_{\text{vis},j}(t)=e^{-\gamma_{\text{vis},j}t}\left[A_{\text{vis},1,j}e^{\beta_{\text{vis},j}t}+A_{\text{vis},2,j}e^{-\beta_{\text{vis},j}t}\right]\)

The total susceptibility is defined as

\(\chi(t,t'',z)=\sum_j\left[f_e(t,t'',z)\chi_{e,j}(t)+(1-f_e(t,t'',z))\chi_{g,j}(t)+g(t,t'',z)\chi_{\text{vis},j}(t)\right]\)

where \(f_e(t,t'',z)\) the the fraction of excited oscillators and \(g(t,t'',z)\) is the incident visual pulse. We define \(f_e(t,t'',z)\) as a decay as a function of distance into the material times the convolution of the visual pulse and the excited state decay

\(f_e(t,t'',z)=\exp{\left(-\alpha z\right)}\int_0^t\exp{\left[-\left(\frac{t''-t'}{\Gamma}\right)^2\right]}\left(\exp{\left[-\frac{t'}{\tau}\right]}+b\right)\text{d}t'\)

where \(\alpha\) is the spatial decay of the visual pulse in the material, \(\Gamma\) is the width of the visual pulse, \(t''\) is the time delay between the visual and simulation pulses, \(\tau\) is the time decay of an excited oscillator, \(b\) is the offset that the excited oscillators have (used if not all excited oscillators ultimately de-excite), and \(t'=t-zv_\text{vis}\). We define \(g(t,t'',z)\) as the visual pulse multiplied by the spatial decay of the pulse in the material

\(g(t,t'',z)=\exp{\left(-\alpha z\right)}\exp{\left[-\left(\frac{t''-t'}{\Gamma}\right)^2\right]}\)

The user supplies \(\alpha\), \(\Gamma\), \(t''\), \(\tau\), and \(b\) at the simulation initialization to define \(f_e(t,t'',z)\) and \(g(t,t'',z)\). The user must also supply the constants that define the ground, excited, and visual oscillators. Initializing the material will trigger the computation of the fraction of excited oscillators followed by the computation of the discretized electric susceptibility.

Parameters:

di – The spatial time step of the simulation
dn – The temporal step size of the simulation
ilen – The number of spatial indices in the simulation
nlen – The number of temporal indices in the simulation
n_ref_ind – The time index to use as a reference for the the t_diff argument
material_i0 – The starting spatial index of the material
e_a1 – The excited state oscillator \(A_{e,1}\), where axis=0 represents the \(j\) th oscillator and axis=1 represents the \(i\) th spatial oscillator in the material.
e_a2 – The excited state oscillator \(A_{e,2}\), where axis=0 represents the \(j\) th oscillator and axis=1 represents the \(i\) th spatial oscillator in the material.
e_b – The excited state oscillator \(\beta_{e,1}\), where axis=0 represents the \(j\) th oscillator and axis=1 represents the \(i\) th spatial oscillator in the material.
e_g – The excited state oscillator \(\gamma_{e,1}\), where axis=0 represents the \(j\) th oscillator and axis=1 represents the \(i\) th spatial oscillator in the material.
g_a1 – The ground state oscillator \(A_{e,1}\), where axis=0 represents the \(j\) th oscillator and axis=1 represents the \(i\) th spatial oscillator in the material.
g_a2 – The ground state oscillator \(A_{e,2}\), where axis=0 represents the \(j\) th oscillator and axis=1 represents the \(i\) th spatial oscillator in the material.
g_b – The ground state oscillator \(\beta_{e,1}\), where axis=0 represents the \(j\) th oscillator and axis=1 represents the \(i\) th spatial oscillator in the material.
g_g – The ground state oscillator \(\gamma_{e,1}\), where axis=0 represents the \(j\) th oscillator and axis=1 represents the \(i\) th spatial oscillator in the material.
v_a1 – The visual oscillator \(A_{e,1}\), where axis=0 represents the \(j\) th oscillator and axis=1 represents the \(i\) th spatial oscillator in the material.
v_a2 – The visual oscillator \(A_{e,2}\), where axis=0 represents the \(j\) th oscillator and axis=1 represents the \(i\) th spatial oscillator in the material.
v_b – The visual oscillator \(\beta_{e,1}\), where axis=0 represents the \(j\) th oscillator and axis=1 represents the \(i\) th spatial oscillator in the material.
v_g – The visual oscillator \(\gamma_{e,1}\), where axis=0 represents the \(j\) th oscillator and axis=1 represents the \(i\) th spatial oscillator in the material.
alpha – The spatial decay constant \(\alpha\) in meters
Gamma – The visual pulse width \(\Gamma\) in seconds
t_diff – The time difference \(t''\) in seconds between the visual pulse and index n_ref_ind
tau – The oscillator time decay constant \(\tau\) in seconds
b – The excited oscillator decay offset \(\b\)
epsiloninf – The \(\epsilon_\infty\) of the material, which is constant over space and time.
tqdmarg_f – The arguments to pass the tdqm iterator during the fraction of excited oscillators calculation (lookup arguments on the tqdm documentation).
tqdmarg_c – The arguments to pass the tdqm iterator during the electric susceptibility calculation (lookup arguments on the tqdm documentation).

get_chi0()[source]¶

Returns the value of \(\chi_0\) at the current time step in the simulation at each spatial location in the simulation.

Returns:	The current value of \(\chi_0\) at each spatial location in the simulation

get_epsiloninf()[source]¶

Returns the value of \(\epsilon_\infty\) at the current time step in the simulation at each spatial location in the simulation.

Returns:	The current value of \(\epsilon_\infty\) at each spatial location in the simulation

get_psi()[source]¶

Returns the value of \(\psi\) at the current time step in the simulation at each spatial location in the simulation.

Returns:	The current value of \(\psi\) at each spatial location in the simulation

reset_material()[source]¶: This function is called before each simulation. It should reset any material values that are calculated during the simulation to their initial values.

update_material(n, efield)[source]¶

This function is called at the start of each simulation time step. It should update the \(\chi\) and \(\psi\) values of the material to their values at n.

Parameters:	n – The current temporal index of the simulation. efield – The previous electric field of the simulation.