Periodic boundary conditions

Periodic boundary conditions replace the walls by a repeating cell, which removes the edge effects that a container inevitably introduces. This matters whenever the quantity of interest is a bulk property rather than the response of a finite sample, and it is what makes concurrent double-scale simulations possible.

Important

These keywords are only understood when Rockable has been compiled with

cmake .. -DROCKABLE_ENABLE_PERIODIC=ON

Without that option the keywords are still accepted, but each of them only prints PERIODIC_NOT_ENABLED when Rockable was compiled and does nothing. rockable -b tells you which options a binary was built with.

Warning

Periodic boundary conditions and the special boundaries (ROCKABLE_ENABLE_BOUNDARY) cannot be used together.

The cell

The cell is described by a \(3 \times 3\) matrix \(\mathbf{h}\) whose columns are the three vectors spanning the cell. A cubic cell of side \(L\) is simply \(\mathbf{h} = L\,\mathbf{I}\), and a sheared cell has off-diagonal terms.

Keyword	Description
usePeriodicCell (int)	1 activates the periodic cell, 0 disables it.
h (mat9r)	The cell matrix, nine reals given row by row.
vh (mat9r)	Velocity of the cell matrix, \(\dot{\mathbf{h}}\).
ah (mat9r)	Acceleration of the cell matrix, \(\ddot{\mathbf{h}}\).
mh (double)	Mass ratio used to build the inertia of the cell degrees of freedom.
dh (double)	Numerical damping applied to the cell degrees of freedom.

The cell has its own dynamics: it is not a kinematic constraint but a set of nine degrees of freedom integrated along with the particles, which is what allows a stress to be imposed on it. mh sets how heavy those degrees of freedom are, and therefore how fast the cell responds; dh damps their oscillations.

Tip

A cell that oscillates instead of converging under a constant pressure is the sign of an mh too small or a dh too small. Both are numerical parameters, to be calibrated like numericalDampingCoeff.

Corrections and stress measurement

Keyword	Description
cellVelocityCorrection (int)	Removes the mean velocity drift of the sample.
cellMomentumCorrection (int)	Removes the total momentum drift of the sample.
useKineticStress (int)	Includes the kinetic (velocity fluctuation) term in the stress used to drive the cell.

A fully periodic system has no boundary to anchor it, so nothing prevents the whole sample from drifting: any residual momentum is conserved for ever. The two correction flags remove that drift, and are normally left on.

useKineticStress matters as soon as the sample is not quasi-static. The stress of a granular assembly is the sum of a contact term and a kinetic term; for a slow compression the second is negligible, for a rapid flow it is not.

Note

Kinematics are stored in the conf-files in real coordinates, and converted to the reduced coordinates of the cell internally when the file is read. A conf-file of a periodic simulation therefore remains readable, and see displays it correctly.

Driving the cell

The loading is set in drivingSystem.txt (see Driving the boundaries), with the PeriodicLoading keyword instead of the Control and Servo entries used for walls.

PeriodicLoading IsotropicCompression (double) pressure

The three diagonal components of the cell are stress-driven at \(-p\), and every shear component is held at zero velocity. This is the periodic equivalent of tritriIsostaticCompression, and the usual way of preparing a dense periodic sample.

PeriodicLoading TriaxialCompression (string) X|Y|Z (double) pressure (double) strainRate

The named direction is strain-driven at a constant rate, the two others being kept at pressure. The imposed velocity is recomputed at every step as \(\dot{\varepsilon}\, h_{ii}\), so the strain rate stays constant as the cell shrinks, rather than the velocity.

PeriodicLoading SimpleShearDeformable (string) XY|XZ|YX|YZ|ZX|ZY (double) pressure (double) shearRate

Shear at a constant rate on the named component, the three normal components being stress-driven at pressure. The two letters name the component of \(\mathbf{h}\) that is sheared; the normal direction used to convert the rate into a velocity follows from it.

drivingSystem.txt

PeriodicLoading IsotropicCompression 100

Note

PeriodicLoading replaces the walls entirely: nDriven should be 0, and there is no wall body in the Particles list.

Visualising a periodic sample

see draws the cell as a box, toggled with the key P. The particles are drawn at their real positions, so a particle straddling a face of the cell is shown on one side only; this is expected, and not a sign that the periodicity is broken.

Current status

Warning

Periodic boundary conditions are implemented and usable, but they are still described as being in a testing phase. The work is carried out with Lhassan Amarsid and Duc-Cuong Pham. Check your results against a known case before relying on them, in particular for the deformable-cell shear.