Placing and moving a mesh

Every mesh is placed and moved by one block: the transforms of its model entry. It holds three settings. scale converts the units of the mesh file, transform puts the mesh where it belongs in the case, and motion describes how it moves, or the frame its flow is solved in, during the run. Each is optional.

The order of operations

The coordinates of every node pass through the three settings in a fixed order:

x_file ──scale──▶ x_m ──transform──▶ x_placed ──motion(t)──▶ x(t)

1. scale multiplies the coordinates read from the mesh file, so that they are in metres.
2. transform is applied once, when the mesh is read, to the scaled coordinates. A translation in a transform matrix is therefore in metres, whatever the units of the file.
3. motion acts on the placed mesh. Its axis, origin and velocity are given in placed coordinates: the position of the mesh in the case, after scale and transform.

A rotor whose mesh was built about the origin in inches, and placed 2 m along x, therefore turns about an origin of [2.0, 0.0, 0.0], not about the origin of its mesh file.

Keys

Which settings go together

Validation applies these rules and names the setting and its remedy when a deck breaks one.

• A mesh may carry one motion.
• "moving mesh": True requires an unsteady compressible run and an overset or sliding interface on that mesh. A steady rotor, or any motion in the incompressible solver, is written with "moving mesh": False.
• ramp time is allowed only with "moving mesh": True. A frame runs at its full rate from the first cycle.
• rotate nodes is allowed only on a rotating motion with "moving mesh": True. A frame never moves the nodes.
• transform is either a matrix or a function. A function is called once during validation with a representative location, and must return three numbers.

A motion, moving mesh or frame, always covers the whole mesh. A region that moves on its own, such as a fan inside a duct, is either a mesh of its own, joined to the rest by a sliding or overset interface and carrying its own motion, or, when it turns steadily, a set of cell zones solved in a rotating frame by a rotating fluid zone. A model with a rotating fluid zone carries no motion and no overset or sliding interface. A wall's velocity turns or slides that surface without moving the mesh.

A moving mesh and a frame differ in what the solver integrates. A moving mesh is advanced to its new position every real time step, and every overset mapping or sliding intersection that involves it is recomputed. A frame leaves the mesh where it is and adds the Coriolis and centrifugal sources of a rotating frame, or the velocity of a translating one, to every cell. The incompressible solver applies the frame velocity at every cell and face but adds no Coriolis or centrifugal source.

Examples

A rotor

An overset cylinder, placed at y = 1.2 m and z = 1.2 m, turning about its own axis at 104.72 rad/s. The origin is the placed centre of the cylinder:

parameters["model"]["cylinder_1"] = {
    "mesh": "cylinder_origin.h5",
    "transforms": {
        "transform": [
            [1.0, 0.0, 0.0, 0.0],
            [0.0, 1.0, 0.0, 1.2],
            [0.0, 0.0, 1.0, 1.2],
            [0.0, 0.0, 0.0, 1.0],
        ],
        "motion": {
            "type": "rotating",
            "axis": [1.0, 0.0, 0.0],
            "origin": [0.0, 1.2, 1.2],
            "omega": 104.72,
            "moving mesh": True,
        },
    },
    "boundary conditions": {"BC_1": {"type": "interface", "kind": "overset", "zones": [7]}},
}

Each model entry sits under a label of its own, so several entries may load the same mesh file, each with its own placement and motion. A rotor turning inside a stator across a sliding interface carries its motion in the same way; see Sliding.

A frame

A steady rotor in a mesh of its own is the same block with "moving mesh": False. The flow is solved in the rotating frame and the mesh does not move:

parameters["model"]["rotor"]["transforms"] = {
    "motion": {
        "type": "rotating",
        "axis": [0.0, 0.0, 1.0],
        "origin": [0.0, 0.0, 0.0],
        "omega": 100.0,
        "moving mesh": False,
    }
}

A frame over only part of a mesh, such as a wheel or an impeller meshed as cell zones of their own, is a rotating fluid zone instead of a motion.

A sliding interface whose rotating side is a frame is a frozen rotor. The two meshes keep their relative position, the rotor is solved in its own frame, and the interface takes its axis from the frame. The run may be steady.

A translating body that starts from rest

A train, placed 110 m along x, accelerated from rest to 69.4 m/s over the first 1.5 s:

parameters["model"]["train"] = {
    "mesh": "train.h5",
    "transforms": {
        "transform": [
            [1.0, 0.0, 0.0, 110.0],
            [0.0, 1.0, 0.0, 0.0],
            [0.0, 0.0, 1.0, 0.0],
            [0.0, 0.0, 0.0, 1.0],
        ],
        "motion": {
            "type": "translating",
            "velocity": [-69.4, 0.0, 0.0],
            "moving mesh": True,
            "ramp time": 1.5,
        },
    },
    "boundary conditions": {"BC_2": {"type": "interface", "kind": "overset", "zones": [9]}},
}

Without ramp time the mesh moves at its full rate from the start of the run. With it, the rate rises linearly from rest over ramp time seconds of physical time, which avoids the transient of an impulsive start. For a ramp time $T$ the angle turned by time $t$ is $\omega t^2 / (2T)$ during the ramp and $\omega (t - T/2)$ after it, and a translation follows the same law.

A scaled and placed mesh

A mesh built in inches, converted to metres and then turned 10 degrees about y and moved 1 m upstream. The matrix acts on the scaled coordinates, so its translation is in metres:

import zutil.transform

placement = zutil.transform.rotate([0.0, 1.0, 0.0], 10.0)
placement = zutil.transform.translate([0.0, 0.0, 0.0], [-1.0, 0.0, 0.0], placement)

parameters["model"]["wing"]["transforms"] = {
    "scale": [0.0254, 0.0254, 0.0254],
    "transform": placement,
}

The zutil.transform helpers and the conventions of an affine matrix are described in Initial placement.

A placement function

transform may instead be a function. It is called with each node's scaled position as the keyword argument location, and returns the placed position as three numbers. Here the mesh is wrapped about the z axis:

import math


def place(*, location):
    x, y, z = location
    radius = 5.0 + y
    angle = x / 5.0
    return (radius * math.sin(angle), radius * math.cos(angle), z)


parameters["model"]["duct"]["transforms"] = {"transform": place}

A function is evaluated node by node in Python, so it is slower than a matrix on a large mesh. It cannot place a mesh that carries non-conformal interface faces; give such a mesh a matrix.

Each time step of a moving mesh

At each real time step a moving mesh is placed where its motion puts it at the end of the step. Its velocity over the step is the distance moved divided by the time step, so the volumes swept by the moving faces are consistent with the motion. A restart is described in the next section.

Restarting a run with a moving mesh

A restart carries on from the mesh as the stored solution left it. The results file records where the mesh was, and the run resumes from that position, whatever has been changed in the deck. A restart therefore continues the run as an uninterrupted one would, or stops at start-up with an error that names the model, the file, both values and what to do.

Changing the motion

You may change omega or velocity, reverse the direction, or change or remove ramp time. The mesh moves on from its stored position at the new rate. With rotate nodes, you may also change axis or origin: the new rotation is applied to the mesh where it stands. A rotating motion may be replaced by a translating one, and the reverse, in the same way.

ramp time counts from the time the motion first appears. A motion present from the start of the run ramps from time zero. A motion added at a restart ramps from the restart time. A motion removed at a restart leaves the mesh where it was.

The rate of the first step after a restart is the mean over the step that produced the stored solution, so a mesh in the middle of a ramp resumes at the rate it had reached.

parameters["model"]["cylinder_1"]["transforms"]["motion"]["omega"] = 62.83

A steady run may be restarted as an unsteady run with a moving mesh. The clock starts at zero and the mesh keeps the position stored in the file. An unsteady run restarted as a steady one holds the mesh where it was.

Changing the time step

A restart may use a different time step. The first step at the new size is taken at first order, and the order of accuracy then rises as usual. The same applies when the step is edited during a run. A step that was stopped part way is finished at its own size before the new one takes over. Dual and global time stepping may be exchanged.

Restarting the clock

restart_ignore_history restarts the clock at zero and ignores the cycle history, but the mesh stays where the file left it. ramp time then counts from zero.

Changes that stop the run

The run stops at start-up, before the solution is read, when a restart would otherwise be inconsistent. Each error names the file and both values.

Results files written before these records were kept are accepted. The mesh is taken to have moved by the current motion from time zero, and a warning names the file.