Heat

Heat transfer: diffusion of heat on lattices and meshes, and cooling towards the surroundings.

CoffeeCupElement(label, visual=None, *, T=90.0, room=20.0, k=0.1)

Bases: Element

Cup of coffee at the temperature T in a room at the temperature room, exchanging heat at the rate k.

Parameters:

Name	Type	Description	Default
label	str	The label of the cup.	required
visual	VisualSpec | None	How the cup is drawn, or None for none.	None
T	Annotated[float, StateSpec()]	The initial temperature of the coffee.	90.0
room	Annotated[float, ParameterSpec()]	The temperature of the room.	20.0
k	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The rate of heat exchange.	0.1

Examples:

>>> from skcomplex.models.physics.heat import CoffeeCupElement
>>> CoffeeCupElement('coffee', k=0.2).k
0.2

Source code in src/skcomplex/models/physics/heat/_cooling.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    T: Annotated[float, StateSpec()] = 90.0,
    room: Annotated[float, ParameterSpec()] = 20.0,
    k: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.1,
) -> None:
    super().__init__(label, visual=visual)
    self.T = T
    self.room = room
    self.k = k

HeatElement(label, visual=None, *, u=0.0, D=1.0)

Bases: Element

Site of a plate, with the temperature u and the diffusion coefficient D of heat.

Parameters:

Name	Type	Description	Default
label	str	The label of the site.	required
visual	VisualSpec | None	How the site is drawn, or None for none.	None
u	Annotated[float, StateSpec()]	The initial temperature.	0.0
D	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The diffusion coefficient.	1.0

Examples:

>>> from skcomplex.models.physics.heat import HeatElement
>>> HeatElement('site', D=0.5).D
0.5

Source code in src/skcomplex/models/physics/heat/_heat.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    u: Annotated[float, StateSpec()] = 0.0,
    D: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
) -> None:
    super().__init__(label, visual=visual)
    self.u = u
    self.D = D

cooling_coffee(T=90.0, *, room=20.0, k=0.1)

Return a cup of coffee whose temperature relaxes to that of the room, T' = -k (T - T_room).

The heat flow is proportional to the discrepancy between the coffee and the room, a balancing feedback loop, so hot coffee cools and iced coffee warms, both exponentially with the time constant 1 / k.

Parameters:

Name	Type	Description	Default
T	float	The initial temperature of the coffee.	90.0
room	float	The temperature of the room.	20.0
k	float	The rate of heat exchange.	0.1

Returns:

Name	Type	Description
system	System	The model, with the temperature coffee.T.

Examples:

>>> from skcomplex.models.physics.heat import cooling_coffee
>>> cooling_coffee(T=5.0).elements[0].T
5.0

Source code in src/skcomplex/models/physics/heat/_cooling.py

@register_model(
    field='physics/heat',
    tags=('heat', 'ode', 'balancing feedback', 'stocks and flows'),
    references=('Newton 1701', 'Meadows 2008'),
    defaults={'until': 60.0, 'dt': 0.5},
)
def cooling_coffee(T: float = 90.0, *, room: float = 20.0, k: float = 0.1) -> System:
    """Return a cup of coffee whose temperature relaxes to that of the room, `T' = -k (T - T_room)`.

    The heat flow is proportional to the discrepancy between the coffee and the room, a balancing feedback loop, so
    hot coffee cools and iced coffee warms, both exponentially with the time constant `1 / k`.

    Args:
        T:
            The initial temperature of the coffee.

        room:
            The temperature of the room.

        k:
            The rate of heat exchange.

    Returns:
        system:
            The model, with the temperature `coffee.T`.

    Examples:
        >>> from skcomplex.models.physics.heat import cooling_coffee
        >>> cooling_coffee(T=5.0).elements[0].T
        5.0
    """
    cooling = RelaxationInteraction(
        'cooling',
        target='coffee',
        state='T',
        goal=lambda s: s.target.room,
        time=lambda s: 1 / s.target.k,
    )
    return System(elements=[CoffeeCupElement('coffee', T=T, room=room, k=k)], interactions=[cooling])

harmonic(x, y)

Return the harmonic function exp(x) sin(y), a steady temperature known in closed form.

Parameters:

Name	Type	Description	Default
x	Array	The first coordinates.	required
y	Array	The second coordinates.	required

Returns:

Name	Type	Description
values	Array	The temperatures.

Examples:

>>> from skcomplex.models.physics.heat import harmonic
>>> float(harmonic(0.0, 0.0))
0.0

Source code in src/skcomplex/models/physics/heat/_heat.py

def harmonic(x: Array, y: Array) -> Array:
    """Return the harmonic function `exp(x) sin(y)`, a steady temperature known in closed form.

    Args:
        x:
            The first coordinates.

        y:
            The second coordinates.

    Returns:
        values:
            The temperatures.

    Examples:
        >>> from skcomplex.models.physics.heat import harmonic
        >>> float(harmonic(0.0, 0.0))
        0.0
    """
    return np.exp(x) * np.sin(y)

heat_diffusion(shape=(64, 64), *, D=1.0, spacing=1.0, boundary='zero-flux')

Return heat diffusing on a plate from a hot square in its middle, du/dt = D laplacian(u).

Parameters:

Name	Type	Description	Default
shape	Sequence[int]	The number of sites along every dimension.	(64, 64)
D	float	The diffusion coefficient.	1.0
spacing	float	The distance between sites.	1.0
boundary	str	'periodic', 'zero-flux' for an insulated plate, or 'fixed' for edges held at zero.	'zero-flux'

Returns:

Name	Type	Description
system	System	The model, with the temperature plate.u.

Examples:

>>> from skcomplex.models.physics.heat import heat_diffusion
>>> heat_diffusion((10, 10)).elements[0].check().prepare().size_
100

Source code in src/skcomplex/models/physics/heat/_heat.py

@register_model(
    field='physics/heat',
    tags=('field', 'diffusion', 'pde'),
    references=('Fourier 1822', 'Datseris and Parlitz 2022'),
    defaults={'until': 50.0, 'dt': 1.0},
)
def heat_diffusion(
    shape: Sequence[int] = (64, 64),
    *,
    D: float = 1.0,
    spacing: float = 1.0,
    boundary: str = 'zero-flux',
) -> System:
    """Return heat diffusing on a plate from a hot square in its middle, `du/dt = D laplacian(u)`.

    Args:
        shape:
            The number of sites along every dimension.

        D:
            The diffusion coefficient.

        spacing:
            The distance between sites.

        boundary:
            `'periodic'`, `'zero-flux'` for an insulated plate, or `'fixed'` for edges held at zero.

    Returns:
        system:
            The model, with the temperature `plate.u`.

    Examples:
        >>> from skcomplex.models.physics.heat import heat_diffusion
        >>> heat_diffusion((10, 10)).elements[0].check().prepare().size_
        100
    """
    shape = tuple(shape)
    u = np.zeros(shape)
    middle = tuple(slice(size // 2 - max(size // 8, 1), size // 2 + max(size // 8, 1)) for size in shape)
    u[middle] = 1.0
    condition = ('fixed', 0.0) if boundary == 'fixed' else boundary
    space = LatticeSpace(shape, spacing=spacing)
    return System(
        elements=[
            FieldElement('plate', element=HeatElement, space=space, boundary={'u': condition}, values={'u': u, 'D': D}),
        ],
        interactions=[DiffusionInteraction('conduction', target='plate', state='u', coefficient=lambda s: s.target.D)],
    )

heat_l_shape(refine=3, *, D=1.0, temperature=harmonic)

Return heat on the L-shaped domain with fixed boundary temperatures, discretised by linear finite elements.

The plate starts cold inside, and its temperature relaxes to the solution of Laplace's equation with the boundary temperatures. The default boundary temperature is harmonic, so the steady state is known.

Parameters:

Name	Type	Description	Default
refine	int	The number of uniform refinements of the mesh.	3
D	float	The diffusion coefficient.	1.0
temperature	Callable[[Array, Array], Array] | float	The boundary temperature, a number or a function of the coordinates.	harmonic

Returns:

Name	Type	Description
system	System	The model, with the temperature plate.u at the nodes of the mesh.

Examples:

>>> from skcomplex.models.physics.heat import heat_l_shape
>>> heat_l_shape(1).elements[0].check().prepare().size_
21

Source code in src/skcomplex/models/physics/heat/_heat.py

@register_model(
    field='physics/heat',
    tags=('field', 'diffusion', 'finite element', 'mesh', 'pde'),
    references=('Strang and Fix 1973', 'Gustafsson and McBain 2020'),
    defaults={'until': 2.0, 'dt': 0.1, 'solver': IMEXEulerSolver(dt=0.05)},
)
def heat_l_shape(
    refine: int = 3,
    *,
    D: float = 1.0,
    temperature: Callable[[Array, Array], Array] | float = harmonic,
) -> System:
    """Return heat on the L-shaped domain with fixed boundary temperatures, discretised by linear finite elements.

    The plate starts cold inside, and its temperature relaxes to the solution of Laplace's equation with the
    boundary temperatures. The default boundary temperature is harmonic, so the steady state is known.

    Args:
        refine:
            The number of uniform refinements of the mesh.

        D:
            The diffusion coefficient.

        temperature:
            The boundary temperature, a number or a function of the coordinates.

    Returns:
        system:
            The model, with the temperature `plate.u` at the nodes of the mesh.

    Examples:
        >>> from skcomplex.models.physics.heat import heat_l_shape
        >>> heat_l_shape(1).elements[0].check().prepare().size_
        21
    """
    grid = skfem.MeshTri.init_lshaped().refined(refine)
    mesh = MeshSpace(grid.p, grid.t)
    return System(
        elements=[
            FieldElement(
                'plate',
                element=HeatElement,
                space=mesh,
                boundary={'u': ('fixed', temperature)},
                values={'D': D},
                discretization='finite-element',
            ),
        ],
        interactions=[DiffusionInteraction('conduction', target='plate', state='u', coefficient=lambda s: s.target.D)],
    )