Fields

fields

Field creation utilities for scalar, gauge, and coupled lattices.

This module consolidates all field initialization functions for creating various lattice configurations.

create_vacuum_coupled_lattice(size, length, m=1.0, lambda_=1.0, g=1.0)

Create a coupled lattice in vacuum state.

Vacuum: \(\phi = 0, \pi = 0, U = 1, E = 0\)

Parameters:

Name	Type	Description	Default
size	tuple[int, int, int]	Lattice dimensions (Nx, Ny, Nz).	required
length	float | tuple[float, float, float]	Physical box size.	required
m	float	Scalar mass.	1.0
lambda_	float	Scalar self-coupling.	1.0
g	float	Gauge coupling.	1.0

Returns:

Type	Description
CoupledLattice	CoupledLattice in vacuum state.

Source code in jaxlatt/core/fields.py

def create_vacuum_coupled_lattice(
    size: tuple[int, int, int],
    length: float | tuple[float, float, float],
    m: float = 1.0,
    lambda_: float = 1.0,
    g: float = 1.0,
) -> CoupledLattice:
    """
    Create a coupled lattice in vacuum state.

    Vacuum: $\\phi = 0, \\pi = 0, U = 1, E = 0$

    Args:
        size: Lattice dimensions `(Nx, Ny, Nz)`.
        length: Physical box size.
        m: Scalar mass.
        lambda_: Scalar self-coupling.
        g: Gauge coupling.

    Returns:
        `CoupledLattice` in vacuum state.
    """
    if isinstance(length, (int, float)):
        length = (length, length, length)

    dx = length[0] / size[0]

    phi = jnp.zeros(size, dtype=jnp.complex64)
    pi = jnp.zeros(size, dtype=jnp.complex64)
    links = jnp.ones((3,) + size, dtype=jnp.complex64)
    E = jnp.zeros((3,) + size, dtype=jnp.float32)

    return CoupledLattice(
        phi=phi,
        pi=pi,
        links=links,
        E=E,
        m=m,
        lambda_=lambda_,
        g=g,
        dx=dx,
        size=size,
        length=length,
    )

create_random_coupled_lattice(key, size, length, m=1.0, lambda_=1.0, g=1.0, amplitude=0.1)

Create a coupled lattice with random initial conditions.

Parameters:

Name	Type	Description	Default
key	PRNGKey	Random number generator key.	required
size	tuple[int, int, int]	Lattice dimensions (Nx, Ny, Nz).	required
length	float | tuple[float, float, float]	Physical box size.	required
m	float	Scalar mass.	1.0
lambda_	float	Scalar self-coupling.	1.0
g	float	Gauge coupling.	1.0
amplitude	float	Amplitude of random perturbations.	0.1

Returns:

Type	Description
CoupledLattice	CoupledLattice with random initial fields.

Source code in jaxlatt/core/fields.py

def create_random_coupled_lattice(
    key: random.PRNGKey,
    size: tuple[int, int, int],
    length: float | tuple[float, float, float],
    m: float = 1.0,
    lambda_: float = 1.0,
    g: float = 1.0,
    amplitude: float = 0.1,
) -> CoupledLattice:
    """
    Create a coupled lattice with random initial conditions.

    Args:
        key: Random number generator key.
        size: Lattice dimensions `(Nx, Ny, Nz)`.
        length: Physical box size.
        m: Scalar mass.
        lambda_: Scalar self-coupling.
        g: Gauge coupling.
        amplitude: Amplitude of random perturbations.

    Returns:
        `CoupledLattice` with random initial fields.
    """
    if isinstance(length, (int, float)):
        length = (length, length, length)

    dx = length[0] / size[0]

    # Split random key
    k1, k2, k3, k4, k5, k6 = random.split(key, 6)

    # Random scalar field (complex)
    phi_re = amplitude * random.normal(k1, size, dtype=jnp.float32)
    phi_im = amplitude * random.normal(k2, size, dtype=jnp.float32)
    phi = phi_re + 1j * phi_im

    # Random conjugate momentum (complex)
    pi_re = amplitude * random.normal(k3, size, dtype=jnp.float32)
    pi_im = amplitude * random.normal(k4, size, dtype=jnp.float32)
    pi = pi_re + 1j * pi_im

    # Random gauge links (phases on unit circle)
    theta = amplitude * random.normal(k5, (3,) + size, dtype=jnp.float32)
    links = jnp.exp(1j * theta)

    # Random electric field
    E = amplitude * random.normal(k6, (3,) + size, dtype=jnp.float32)

    return CoupledLattice(
        phi=phi,
        pi=pi,
        links=links,
        E=E,
        m=m,
        lambda_=lambda_,
        g=g,
        dx=dx,
        size=size,
        length=length,
    )

create_higgs_vev_lattice(size, length, m=1.0, lambda_=1.0, g=1.0, vev_amplitude=None)

Create a coupled lattice with Higgs field at vacuum expectation value.

For the symmetry breaking potential \(V = -\frac{m^2}{2}|\phi|^2 + \frac{\lambda}{4}|\phi|^4\), the VEV is \(|\phi| = \sqrt{m^2/\lambda}\).

Parameters:

Name	Type	Description	Default
size	tuple[int, int, int]	Lattice dimensions (Nx, Ny, Nz).	required
length	float | tuple[float, float, float]	Physical box size.	required
m	float	Scalar mass parameter.	1.0
lambda_	float	Scalar self-coupling.	1.0
g	float	Gauge coupling.	1.0
vev_amplitude	float	Optional VEV amplitude. If None, uses \(\sqrt{m^2/\lambda}\).	None

Returns:

Type	Description
CoupledLattice	CoupledLattice with Higgs field initialized near the VEV.

Source code in jaxlatt/core/fields.py

def create_higgs_vev_lattice(
    size: tuple[int, int, int],
    length: float | tuple[float, float, float],
    m: float = 1.0,
    lambda_: float = 1.0,
    g: float = 1.0,
    vev_amplitude: float = None,
) -> CoupledLattice:
    """
    Create a coupled lattice with Higgs field at vacuum expectation value.

    For the symmetry breaking potential $V = -\\frac{m^2}{2}|\\phi|^2 + \\frac{\\lambda}{4}|\\phi|^4$,
    the VEV is $|\\phi| = \\sqrt{m^2/\\lambda}$.

    Args:
        size: Lattice dimensions `(Nx, Ny, Nz)`.
        length: Physical box size.
        m: Scalar mass parameter.
        lambda_: Scalar self-coupling.
        g: Gauge coupling.
        vev_amplitude: Optional VEV amplitude. If `None`, uses $\\sqrt{m^2/\\lambda}$.

    Returns:
        `CoupledLattice` with Higgs field initialized near the VEV.
    """
    if isinstance(length, (int, float)):
        length = (length, length, length)

    dx = length[0] / size[0]

    # Vacuum expectation value
    if vev_amplitude is None:
        if lambda_ > 0 and m > 0:
            vev_amplitude = jnp.sqrt(m**2 / lambda_)
        else:
            vev_amplitude = 0.0

    # Constant field at VEV (real for simplicity)
    phi = jnp.full(size, vev_amplitude, dtype=jnp.complex64)
    pi = jnp.zeros(size, dtype=jnp.complex64)
    links = jnp.ones((3,) + size, dtype=jnp.complex64)
    E = jnp.zeros((3,) + size, dtype=jnp.float32)

    return CoupledLattice(
        phi=phi,
        pi=pi,
        links=links,
        E=E,
        m=m,
        lambda_=lambda_,
        g=g,
        dx=dx,
        size=size,
        length=length,
    )

create_vacuum_gauge_lattice(size, length, g=1.0)

Create a gauge lattice in vacuum state (links=1, E=0).

Parameters:

Name	Type	Description	Default
size	tuple[int, int, int]	Grid dimensions	required
length	float	Physical box size	required
g	float	Gauge coupling	1.0

Returns:

Type	Description
GaugeLattice	GaugeLattice in vacuum configuration

Source code in jaxlatt/core/fields.py

def create_vacuum_gauge_lattice(
    size: tuple[int, int, int],
    length: float,
    g: float = 1.0,
) -> GaugeLattice:
    """
    Create a gauge lattice in vacuum state (links=1, E=0).

    Args:
        size: Grid dimensions
        length: Physical box size
        g: Gauge coupling

    Returns:
        GaugeLattice in vacuum configuration
    """
    return GaugeLattice(size=size, length=length, g=g)

create_random_gauge_lattice(key, size, length, g=1.0, amplitude=0.1)

Create a gauge lattice with small random perturbations.

Initializes links with small random phases and electric field with small random values, suitable for testing dynamics.

Parameters:

Name	Type	Description	Default
key	PRNGKey	JAX random key	required
size	tuple[int, int, int]	Grid dimensions	required
length	float	Physical box size	required
g	float	Gauge coupling	1.0
amplitude	float	Amplitude of random fluctuations	0.1

Returns:

Type	Description
GaugeLattice	GaugeLattice with random initial conditions

Source code in jaxlatt/core/fields.py

def create_random_gauge_lattice(
    key: random.PRNGKey,
    size: tuple[int, int, int],
    length: float,
    g: float = 1.0,
    amplitude: float = 0.1,
) -> GaugeLattice:
    """
    Create a gauge lattice with small random perturbations.

    Initializes links with small random phases and electric field with
    small random values, suitable for testing dynamics.

    Args:
        key: JAX random key
        size: Grid dimensions
        length: Physical box size
        g: Gauge coupling
        amplitude: Amplitude of random fluctuations

    Returns:
        GaugeLattice with random initial conditions
    """
    key1, key2 = random.split(key)

    # Random phases for links (small perturbation around identity)
    phases = amplitude * random.normal(key1, shape=(3, *size))
    links = jnp.exp(1j * phases).astype(jnp.result_type(complex))

    # Random electric field
    E = amplitude * random.normal(key2, shape=(3, *size)).astype(jnp.result_type(float))

    return GaugeLattice(size=size, length=length, g=g, links=links, E=E)

create_vacuum_real_scalar_lattice(size, length)

Initialise chi = 0, chi' = 0 (vacuum) on a periodic lattice.

Parameters:

Name	Type	Description	Default
size	tuple[int, ...]	Grid dimensions, e.g. (32, 32, 32) for a cubic 3-D box.	required
length	float	Physical side length (same for all dimensions).	required

Returns:

Type	Description
RealScalarLattice	Zero-initialised :class:RealScalarLattice.

Source code in jaxlatt/core/fields.py

def create_vacuum_real_scalar_lattice(
    size: tuple[int, ...],
    length: float,
) -> RealScalarLattice:
    """Initialise chi = 0, chi' = 0 (vacuum) on a periodic lattice.

    Args:
        size: Grid dimensions, e.g. ``(32, 32, 32)`` for a cubic 3-D box.
        length: Physical side length (same for all dimensions).

    Returns:
        Zero-initialised :class:`RealScalarLattice`.
    """
    return RealScalarLattice(size=size, length=length)

create_random_real_scalar_lattice(key, size, length, amplitude=0.001)

Initialise chi with small random perturbations, chi' = 0.

Parameters:

Name	Type	Description	Default
key	Array	JAX PRNG key.	required
size	tuple[int, ...]	Grid dimensions.	required
length	float	Physical side length.	required
amplitude	float	Standard deviation of the Gaussian perturbation.	0.001

Returns:

Type	Description
RealScalarLattice	class:RealScalarLattice with random field and zero field_dot.

Source code in jaxlatt/core/fields.py

def create_random_real_scalar_lattice(
    key: Array,
    size: tuple[int, ...],
    length: float,
    amplitude: float = 1e-3,
) -> RealScalarLattice:
    """Initialise chi with small random perturbations, chi' = 0.

    Args:
        key: JAX PRNG key.
        size: Grid dimensions.
        length: Physical side length.
        amplitude: Standard deviation of the Gaussian perturbation.

    Returns:
        :class:`RealScalarLattice` with random ``field`` and zero ``field_dot``.
    """
    # astype matches the gauge factories above: random.normal's default dtype
    # ignores jax_enable_x64, so without this the field is float32 even in a
    # run that has explicitly asked for double precision.
    field = amplitude * random.normal(key, shape=size).astype(jnp.result_type(float))
    return RealScalarLattice(size=size, length=length, field=field)