Boundary Conditions β€” Configuration Guide

This guide explains how to describe boundary conditions for a lattice structure using a JSON file, based on the example used in example/simulation_lattice.py.

Minimal JSON example

{
  "geometry": {
    "cell_size": { "x": 1, "y": 1, "z": 1 },
    "number_of_cells": { "x": 6, "y": 3, "z": 3 },
    "radii": [0.1],
    "geom_types": ["BCC"]
  },
  "simulation_parameters": {
    "enable": true,
    "material": "VeroClear",
    "periodicity": false
  },
  "boundary_conditions": {
    "Displacement": {
      "Fixed": {
        "Surface": ["Xmin"],
        "DOF": ["X", "Y", "Z", "RX", "RY", "RZ"],
        "Value": [0, 0, 0, 0, 0, 0]
      },
      "Displacement": {
        "Surface": ["Xmax", "Zmax"],
        "DOF": ["Z"],
        "Value": [-0.01]
      }
    },
    "Force": {
      "Force": {
        "Surface": ["Xmax", "Zmin"],
        "DOF": ["Y"],
        "Value": [0.025]
      }
    }
  }
}

Structure of the boundary_conditions block

  • Displacement: prescribed displacements (Dirichlet BCs).

  • Force: applied loads (Neumann BCs)

Each entry (e.g., "Fixed", "Displacement", "Force") follows the same schema:

  • Surface (list[str], required) Combination of index extrema: Xmin, Xmax, Ymin, Ymax, Zmin, Zmax, Xmid, Ymid, Zmid. The order matters: filtering is iterative (see below).

  • DOF (list[str], required) Degrees of freedom: X, Y, Z, RX, RY, RZ.

  • Value (list[float], required) Same length and order as DOF. Units: translations β†’ length β†’ mm; rotations β†’ radians.

  • SurfaceCells (list[str], optional β€” not used in the example) Select the nodes on the surface of the cell, if not indicated the same surface in Surface is used.

Surface selection

Selection of cells based on their indices is done iteratively:

  • ["Xmin"]: all cells at the minimum X index.

  • ["Xmax","Zmax"]: from Xmax, keep only those with maximum Z.

  • ["Xmax","Zmin"]: from Xmax, keep only those with minimum Z.

Important: The order of items in Surface defines the sequence of successive filters.

DOF mapping

DOF

Meaning

Index

X

Translation in X

0

Y

Translation in Y

1

Z

Translation in Z

2

RX

Rotation about X

3

RY

Rotation about Y

4

RZ

Rotation about Z

5

Reading the example, step by step

1) Clamp the Xmin side

"Fixed": {
  "Surface": ["Xmin"],
  "DOF": ["X", "Y", "Z", "RX", "RY", "RZ"],
  "Value": [0, 0, 0, 0, 0, 0]
}

  • Selection: cells with minimum X index.

  • Effect: all DOFs fixed to 0 β†’ built-in clamp on the Xmin face.

2) Downward displacement on the top front edge

"Displacement": {
  "Surface": ["Xmax", "Zmax"],
  "DOF": ["Z"],
  "Value": [-0.01]
}

  • Selection: first Xmax, then among those Zmax β†’ top-most region at Xmax.

  • Effect: imposed Z displacement of βˆ’0.01.

3) Lateral force on the bottom rear edge

"Force": {
  "Force": {
    "Surface": ["Xmax", "Zmin"],
    "DOF": ["Y"],
    "Value": [0.025]
  }
}

  • Selection: first Xmax, then Zmin β†’ bottom-most region at Xmax.

  • Effect: Y-direction force (or equivalent load) of +0.025.

Best practices

  • Match DOF and Value: identical lengths and same ordering.

  • Surface order: think about surface order (e.g., Xmax then Zmin may differ from Zmin then Xmax if lattice design is complex).

  • BC conflicts: avoid imposing different conditions on the same node/DOF.

  • Units & sign: be consistent with the global coordinate system and solver conventions.

Quick troubleshooting

  • Plotting simulation results: use plotting at your adavantage to visualize the lattice and boundary conditions.

vizualizer = LatticePlotting()
vizualizer.visualize_lattice(
    enable_system_coordinates=True,
    deformedForm=True,
    enable_boundary_conditions=True
)

  • Instability: ensure at least one region is properly fixed (avoid free rigid-body modes).

  • Loads vs. displacements: don’t impose a displacement and a force on the same node/DOF without a clear strategy (can over-constrain).