External fields

External fields are fields which are applied to the particles at each timestep and are specified by the user, instead of being self-consistently evolved by the simulation.

class fbpic.lpa_utils.external_fields.ExternalField(field_func, fieldtype, amplitude, length_scale, species=None, gamma_boost=None)[source]

Initialize an ExternalField object, so that the function field_func is called at each time step on the field fieldtype

This object should be added to the list external_fields, which is an attribute of the Simulation object, so that the fields are applied at each timestep. (See the example below)

The function field_func is automatically converted to a GPU function if needed, by using numba’s ufunc feature.

Parameters:

  • field_func (callable) –

    Function of the form field_func( F, x, y, z, t, amplitude, length_scale ) and which returns the modified field F’ (in the lab frame)

    This function will be called at each timestep, with:

    • F: 1d array of shape (N_ptcl,), containing the field designated by fieldtype, gathered on the particles

    • x, y, z: 1d arrays of shape (N_ptcl), containing the positions of the particles (in the lab frame)

    • t: float, the time in the simulation (in the lab frame)

    • amplitude and length_scale: floats that can be used within the function expression

    Warning

    In the PIC loop, this function is called after the field gathering. Thus this function can potentially overwrite the fields that were gathered on the grid. To avoid this, use “return(F + external_field) ” inside the definition of field_func instead of “return(external_field)”

    Warning

    Inside the definition of field_func please use the math module for mathematical functions, instead of numpy. This will allow the function to be compiled for GPU.

  • fieldtype (string) – Specifies on which field field_func will be applied. Either ‘Ex’, ‘Ey’, ‘Ez’, ‘Bx’, ‘By’, ‘Bz’

  • species (a Particles object, optionals) – The species on which the external field has to be applied. If no species is specified, the external field is applied to all particles.

  • gamma_boost (float, optional) – When running the simulation in a boosted frame, set the value of gamma_boost to the corresponding Lorentz factor. The external fields will be automatically converted to the boosted frame.

Example

In order to define a magnetic undulator, polarized along y, with a field of 1 Tesla and a period of 1 cm :

def field_func( F, x, y, z, t , amplitude, length_scale ):
    return( F + amplitude * math.cos( 2*np.pi*z/length_scale ) )

sim.external_fields = [ ExternalField( field_func, 'By', 1., 1.e-2 ) ]

Warning

Note that, in principle, field_func does not necessarily need to use the arguments amplitude and length_scale. For instance, in the above example, we could have used

def field_func( F, x, y, z, t , amplitude, length_scale ):
    return( F + 1. * math.cos( 2*np.pi*z/1.e-2 ) )

However, when running the simulation in a boosted frame (i.e. when setting the above argument gamma_boost), the expression of the external fields needs to be proportional to amplitude. This is because, internally, the automatic conversion of the external fields to the boosted frame relies on this variable. (There is no similar constraint for length_scale, however.)