Histories

Histories provide data from each time step of a simulation. They can provide useful diagnostics to make sure your simulation is proceeding as intended. Some histories are only available with certain simulation setups (e.g. only available in electromagnetic simulation, or only available in simulations with particles).

To add a history, right-click the “Histories” element of the setup tree then navigate to the history to be added to the simulation. Note that a new history can be added when the simulation is restarted. In this case, the new history data will be appended to history data that were collected at the beginning of the simulation. If the user adds a history from a restart, then the new history data will not be synced with other history data, and the new data will be plotted starting at t=0 (even though the new data actually were collected starting at t > 0).

Field History

Field Histories record on a per time-step basis. Field histories are used to measure quantities such as the value or energy of the field at a location. The output will be a 1D array of the value vs time.

Accelerating Voltage

This history creates a test electron and measures the accelerating voltage received by an electron traveling at a fixed velocity across a gap in a cavity structure. See acceleratingVoltage for a reference defining ‘acclerating voltage’.

kind (not editable)

Accelerating Voltage

description

A comment to describe the history.

start coordinate 0

The starting position of the test electron in the x-direction in Cartesian simulations (or z-direction in cylindrical simulations).

start coordinate 1

The starting position of the test electron in the y-direction in Cartesian simulations (or r-direction in cylindrical simulations).

start coordinate 2

The starting position of the test electron in the z-direction in Cartesian simulations (or phi-direction in cylindrical simulations).

end coordinate 0

The starting position of the test electron in the x-direction in Cartesian simulations (or z-direction in cylindrical simulations).

end coordinate 1

The starting position of the test electron in the y-direction in Cartesian simulations (or r-direction in cylindrical simulations).

end coordinate 2

The starting position of the test electron in the z-direction in Cartesian simulations (or phi-direction in cylindrical simulations).

velocity

The velocity of the test electron. By default this is the speed of light.

EM Field Energy

Calculate the total energy of the electromagnetic field in the specified volume (Joules). Only available in electromagnetic simulations.

kind (not editable)

EM Field Energy

volume

The region over which to calculate the field energy.

  • simulation region

    Use the entire simulation domain.

  • index 3d slab

    A user-defined volume based on cell indices.

    lower indices

    The lower indices of the volume.

    upper indices

    The upper indices of the volume.

    shape

    A volume based on a previously defined geometry.

  • object name

    Select from a previously defined geometry.

EM Field On Plane

ONLY AVAILABLE IN ELECTROMAGNETIC SIMULATIONS

Records E and B Field data in the plane of cells specified, typically used for computation of S Parameters using computeSParams Analyzers. The Two histories created will be historyName*_E and *historyName_B.

kind (not editable)

S Parameter

surface

The plane to use.

  • yz

    offset

    The x offset from zero, in meters.

    yMin

    The location of the y minimum, in meters.

    yMax

    The location of the y maximum, in meters.

    zMin

    The location of the z minimum, in meters.

    zMax

    The location of the z maximum, in meters.

  • xz

    offset

    The y offset from zero, in meters.

    xMin

    The location of the x minimum, in meters.

    xMax

    The location of the x maximum, in meters.

    zMin

    The location of the z minimum, in meters.

    zMax

    The location of the z maximum, in meters.

  • xy

    offset

    The z offset from zero, in meters.

    xMin

    The location of the x minimum, in meters.

    xMax

    The location of the x maximum, in meters.

    yMin

    The location of the y minimum, in meters.

    yMax

    The location of the y maximum, in meters.

Electric Field Energy

Calculate the total energy of the electric field in the specified volume (Joules).

kind (not editable)

Electric Field Energy

volume

The region over which to calculate the field energy.

  • simulation region

    Use the entire simulation domain.

  • index 3d slab

    A user-defined volume based on cell indices.

    lower indices

    The lower indices of the volume.

    upper indices

    The upper indices of the volume.

Field at Position

Record the specified field at the specified coordinates. All components of the field are recorded into an array.

kind (not editable)

Field at Position

field

Select the desired field.

coordinate 0

The position coordinate in the 0th dimension, x in cartesian coordinates, z in cylindrical.

coordinate 1

The position coordinate in the 1st dimension, y in cartesian coordinates, r in cylindrical.

coordinate 2

The position coordinate in the 2nd dimension, z in cartesian coordinates.

representationRadius

The size of the sphere used to show the field at position history in the setup window. Does not impact the recorded history.

Magnetic Field Energy

Calculate the total energy of the magnetic field in the specified volume (Joules).

kind (not editable)

Magnetic Field Energy

volume

The region over which to calculate the field energy.

  • simulation region

    Use the entire simulation domain.

  • index 3d slab

    A user-defined volume based on cell indices.

    lower indices

    The lower indices of the volume.

    upper indices

    The upper indices of the volume.

Poynting Flux

ONLY AVAILABLE IN ELECTROMAGNETIC SIMULATIONS

Calculates the integrated Poynting vector (energy flux) through the area defined by the min and max values.

kind (not editable)

Poynting Vector

surface

The plane to use.

  • yz

    offset

    The x offset from zero, in meters.

    yMin

    The location of the y minimum, in meters.

    yMax

    The location of the y maximum, in meters.

    zMin

    The location of the z minimum, in meters.

    zMax

    The location of the z maximum, in meters.

  • xz

    offset

    The y offset from zero, in meters.

    xMin

    The location of the x minimum, in meters.

    xMax

    The location of the x maximum, in meters.

    zMin

    The location of the z minimum, in meters.

    zMax

    The location of the z maximum, in meters.

  • xy

    offset

    The z offset from zero, in meters.

    xMin

    The location of the x minimum, in meters.

    xMax

    The location of the x maximum, in meters.

    yMin

    The location of the y minimum, in meters.

    yMax

    The location of the y maximum, in meters.

Pseudo-potential

This option is deprecated. Use ‘Pseudo-potential at Coordinates’ or ‘pseudo-potential at Indices’ instead.

kind (not editable)

Pseudo-potential

start indices

The indices of the cells for the starting location.

end indices

The indices of the cells for the ending location.

Pseudo-potential at Coordinates

Calculates the pseudo-potential difference, in Volts, between two points. The start point would correspond to the measure point, while the end point would correspond to the reference.

kind (not editable)

Pseudo-potential

start coordinate 0

The coordinate of the start point in the 0th dimension.

start coordinate 1

The coordinate of the start point in the 1st dimension.

start coordinate 2

The coordinate of the start point in the 2nd dimension.

end coordinate 0

The coordinate of the end point in the 0th dimension.

end coordinate 1

The coordinate of the end point in the 1st dimension.

end coordinate 2

The coordinate of the end point in the 2nd dimension.

Pseudo-potential at Indices

Calculates the pseudo-potential difference, in Volts, between two points, specified by grid index.

kind (not editable)

Pseudo-potential

description

A description of the potential difference.

start indices

The indices of the cells for the starting location.

end indices

The indices of the cells for the ending location.

Particle History

Particle Histories record on a per time-step basis. Particle histories are used to measure quantities such as the total number of particles in a simulation at each step, or the current absorbed at chosen absorbing surface at each step. The output will be a 1D array of the value vs time.

Absorbed Particle Current

Calculates the absorbed current on a specified particle absorber, in Amps.

kind (not editable)

Absorbed Particle Current

particle absorber

Select the previously defined particle absorbing boundary condition. This must be a ParticleBoundaryCondition that can Save.

Absorbed Particle Power

Calculates the power absorbed on a specified particle absorber, in Joules/second.

kind (not editable)

Absorbed Particle Power

particle absorber

Select the previously defined particle absorbing boundary condition. This must be a ParticleBoundaryCondition that can Save particle data.

Emitted Current

Records the emitted current from the specified particle emitter, in Amps. If trying to track the current from a secondary emitter it is necessary to use the Log History Emitted Particle Log

kind (not editable)

Emitted Current

particle emitter

Select the previously defined particle emitting boundary condition.

Number of Macroparticles

Calculates the total number of macroparticles in the simulation domain for the specified KineticParticle.

kind (not editable)

Number of Macroparticles

particles

Select the name of the previously defined KineticParticles.

Number of Physical Particles

Calculates the total number of real particles in the simulation domain for the specified KineticParticle.

kind (not editable)

Number of Physical Particles

particles

Select the name of the previously defined KineticParticles.

Particle Energy

Calculates the total energy in the simulation domain for the specified KineticParticle, in Joules.

kind (not editable)

Particle Energy

particles

Select the name of the previously defined KineticParticles.

Particle Energy Change from Boundary

Calculates the energy change in a particle species due to a diffuse reflector boundary condition.

kind (not editable)

Particle Energy Change from Boundary

particle absorber

Select the name of the boundary diffuse reflector particle boundary condition.

Combo History

Combo Histories are used to create new histories by combining other histories. The operation is done at every time step and the resulting output will be a 1D array of the value vs time. Any number of histories may be combined.

Note

Due to the nature of the combination process, a combo history will always use data from the previous timestep as compared to the other histories, and will be initialized with a value of 1. The Combined history will not have data from the last timestep of the simulation.

kind (not editable)

Combination History

Constituent History

As many constituent histories as desired may be added. The name of the constituent history itself is not of particular importance.

  • history name

    Select one previously defined Field or Particle History.

  • coefficient

    This is a multiplying factor on the selected history.

  • combination

    This operation will be applied to combine the history with all preceding constituent histories. The order of operations is demonstrated in an example with three histories of each below

    add

    (coefficient1*history name 1) + (coefficient2*history name 2) + (coefficient3*history name 3)

    subtract

    (coefficient1*his:command:Accelerating Voltage

This history creates a test electron and measures the accelerating voltage received by an electron traveling at a fixed velocity across a gap in a cavity structure. See acceleratingVoltage for a reference defining ‘acclerating voltage’.

kind (not editable)

Accelerating Voltage

description

A comment to describe the history.

start coordinate 0

The starting position of the test electron in the x-direction in Cartesian simulations (or z-direction in cylindrical simulations).

start coordinate 1

The starting position of the test electron in the y-direction in Cartesian simulations (or r-direction in cylindrical simulations).

start coordinate 2

The starting position of the test electron in the z-direction in Cartesian simulations (or phi-direction in cylindrical simulations).

end coordinate 0

The starting position of the test electron in the x-direction in Cartesian simulations (or z-direction in cylindrical simulations).

end coordinate 1

The starting position of the test electron in the y-direction in Cartesian simulations (or r-direction in cylindrical simulations).

end coordinate 2

The starting position of the test electron in the z-direction in Cartesian simulations (or phi-direction in cylindrical simulations).

velocity

The velocity of the test electron. By default this is the speed of light.

multiply

(( (coefficient1*history name 1)) * (coefficient2*history name 2)) * (coefficient3*history name 3)

divide

(( (coefficient1*history name 1)) / (coefficient2*history name 2)) / (coefficient3*history name 3)

As the above examples show, using a multiply or divide operation on the third or greater constituent history, will multiply or divide by the combination of all preceding histories.

Time Average

This history can reference other particle and field histories, averaging them in the selected time window.

kind (not editable)

Time Average

history name

The history to be averaged.

time window

The time window to be doing the averaging in.

Array History

An Array History will output an array of data for each time-step.

Far-Field Box Data

ONLY AVAILABLE IN ELECTROMAGNETIC SIMULATIONS

kind (not editable)

Far-Field Box Data

measurement time

The way to define measurement time.

  • seconds defined Gives specification of time in seconds.

    • start time

      The time to start recording data for far field calculations (seconds).

    • end time

      The time to stop recording data for far field calculations (seconds).

  • timesteps defined Gives specification of time in timestep number.

    • start time

      The time to start recording data for far field calculations (timesteps).

    • end time

      The time to stop recording data for far field calculations (timesteps).

volume

The volume to use for the box.

  • cartesian 3d slab

    • xMin

      The minimum x position of the box.

    • xMax

      The maximum x position of the box.

    • yMin

      The minimum y position of the box.

    • yMax

      The maximum y position of the box.

    • zMin

      The minimum z position of the box.

    • zMax

      The maximum z position of the box.

  • index 3d slab Index 3d slab is used in cases where absolute symmetry is necessary so grid alignment must be guranteed.

    • lower index 0

      The lower grid cell of the box in the 0th direction.

    • lower index 1

      The lower grid cell of the box in the 1st direction.

    • lower index 2

      The lower grid cell of the box in the 2nd direction.

    • upper index 0

      The upper grid cell of the box in the 0th direction.

    • upper index 1

      The upper grid cell of the box in the 1st direction.

    • upper index 2

      The upper grid cell of the box in the 2nd direction.

Field Slab Data

Store the value of a field at every timestep within a specified 3D volume.

kind (not editable)

Field Slab Data

description

A comment to describe the history.

field

Choose the field to record. Options for electromagnetic simulations are:

  • Electric Field

  • Magnetic Field

Options for electromagnetic simulations are:

  • Phi

  • Charge Density

  • Electric Field

volume

The volume inside of which to collect the field data.

  • cartesian 3d slab

    • xMin

      The minimum x position of the box.

    • xMax

      The maximum x position of the box.

    • yMin

      The minimum y position of the box.

    • yMax

      The maximum y position of the box.

    • zMin

      The minimum z position of the box.

    • zMax

      The maximum z position of the box.

Particle Momentum

Calculate the total momentum for a particular set of particles in the whole simulation domain. All three components of the momentum are recorded. Thus, for some simulations in 1D or 2D, some components of the momentum may always be zero.

kind (not editable)

Particle Momentum

particles

Select any of the previously defined KineticParticles in your simulation.

Log History

A Log History will record data based on user specified logging method. A single log history may contain multiple particle quantities.

Absorbed Particle Log

Record information about each and every particle that strikes a chosen absorbing surface. The output will be a 1D array of the value.

kind (not editable)

Absorbed Particle Log

particle absorber

Select the previously defined particle absorbing boundary condition. This must be a ParticleBoundaryCondition that can Save.

particle quantity

What information about the particle is to be recorded. For vector-like quantities (position, velocity, and weight), you must select which component of the vector you wish to record in the component option (0 –> x, 1 –> y, 2 –> z) in Cartesian, (0 –> r, 1 –> z, 2 –> phi) in Cylindrical.

particle time

The time the particle strikes the absorber.

particle position

The position of the particle when it is absorbed.

particle velocity

The velocity of the particle when it is absorbed (Non-relativistic m/s).

particle weight

The weight of the particle when it is absorbed.

particle energy

The total relativistic energy of all the particles that are absorbed (Joules).

particle current

The total current of all the particles that are absorbed (Amps, the charge divided by timestep).

particle gamma velocity

The gamma velocity of the particle when it is absorbed (relativistic m/s).

particle charge

The charge of the particle when it is absorbed (Coulombs).

particles in macro particle

The number of particles in that macro particle when it is absorbed.

particle mass

The total mass of the macro particle (kilograms).

Emitted Particle Log

Record information about each and every particle that is emitted from a particle emitter. The output will be a 1D array of the value.

kind (not editable)

Emitted Particle Log

particle emitter

Select the previously defined particle emitter. Any emitter type is applicable.

particle quantity

What information about the particle is to be recorded. For vector-like quantities (position, velocity, and weight), you must select which component of the vector you wish to record in the component option (0 –> x, 1 –> y, 2 –> z) in Cartesian, (0 –> r, 1 –> z, 2 –> phi) in Cylindrical.

particle time

The time the particle is emitted

particle position

The position of the particle when it is emitted.

particle velocity

The velocity of the particle when it is emitted (Non-relativistic m/s).

particle weight

The weight of the particle when it is emitted.

particle energy

The total relativistic energy of all the particles that are emitted (Joules).

particle current

The total current of all the particles that are emitted (Amps, the charge divided by timestep).

particle gamma velocity

The gamma velocity of the particle when it is emitted (relativistic m/s).

particle charge

The charge of the particle when it is emitted (Coulombs).

particles in macro particle

The number of particles in that macro particle when it is emitted.

particle mass

The total mass of the macro particle (kilograms).