ExternalTabulated

The ExternalTabulated potential allows for the application of an arbitrary external potential defined on a 3D grid. This is particularly useful for complex external fields that cannot be easily described analytically.

The potential is defined on a 3D grid with dimensions nx, ny, and nz. The simulation box (provided by the ensemble) is divided into nx x ny x nz grid points, and the potential is defined at each grid point. The size of each grid cell the simulation box is divided into is given by:

\[\Delta x = \frac{L_x}{nx}, \quad \Delta y = \frac{L_y}{ny}, \quad \Delta z = \frac{L_z}{nz}\]

where L_x, L_y, and L_z are the lengths of the simulation box in the x, y, and z directions.

Warning

The current version of the ExternalTabulated potential requires all the \(\Delta x\), \(\Delta y\), and \(\Delta z\) to be equal. Otherwise, an error will be thrown.

An scaling factor scale can be provided. If so, the energy and force values are multiplied by this factor.

Warning

The force values are interpolated from the given values for the force, not calculated from the energy values. (The derivative of the energy values is not used to calculate the force values.) Ensure that the force values are consistent with the energy values.

  • type: External, ExternalTabulated

  • parameters:

    • nx, ny, nz: int: Number of grid points in x, y, and z directions

    • scale: real: Scaling factor for energy and force (optional, default: 1.0)

  • data:

    • i, j, k: int: Grid point indices

    • energy: real: Energy value at the grid point

    • force: real3: Force vector at the grid point

Example:

"externalTabulated":{
  "type":["External","ExternalTabulated"],
  "parameters":{
    "nx":64, "ny":64, "nz":64,
    "scale":1.0
  },
  "labels":["i", "j", "k", "energy", "force"],
  "data":[
    [0, 0, 0, 1.0, [0.1, 0.0, 0.0]],
    [0, 0, 1, 0.9, [0.09, 0.0, 0.01]],
    ...
  ]
}

The potential and forces are interpolated from the provided grid values to particle positions using a 3-point interpolation scheme.

Note

This potential is highly flexible and can represent complex external fields, but requires pre-computation of the energy and force values on a grid.

Note

ExternalTabulated uses the interpolation provided by the Immerse Boundary Method (IBM) of UAMMD (Developed by Raul. P. Pelaez). Documentation for the IBM can be found at https://uammd.readthedocs.io/en/latest/ImmersedBoundary.html

Warning

The tabulated data should cover the entire simulation box with sufficient resolution for accurate interpolation. Ensure that the grid spacing is fine enough to capture the relevant features of your external potential.

Tip

The scale parameter can be used to easily adjust the strength of the external potential without recalculating the entire grid.