Granular LAB 2.1

From a question to a measurement.

A short guide to the workspace and its main workflows. For the complete reference, read the English user manual (PDF).

A first measured experiment

  1. Choose a question. Select an experiment in the sidebar. Silo discharge is a useful starting point for flow; Chiral motion connects self-propulsion with a particle trajectory.
  2. Read and prepare. Check the experiment information, parameters and numerical health. Use Prepare when the preset offers a preparation stage.
  3. Run and measure. Press Play. Open Inspect beside Performance, select a tool and choose a particle, region, section or wall. Pause when a selection is difficult.
  4. Keep the result. Choose the numerical export you need, or record an exploration and save it in a project.
Chiral motion with a selected particle and the Inspect measurement panel.
The simulation, local instrument and controls share one workspace.View full size

Local analysis

Inspect addresses a selected object or part of space. Its four instruments answer complementary questions.

Inspect instrument with Particle, Region, Section and Wall tabs, measured values and population history.
Choose the target in Inspect; its acquired measurements appear beside the simulation.View full size
InstrumentWhat to selectWhat to read
ParticleOne grainIdentity, position, speed, trajectory and available contacts.
RegionA fixed rectangleParticle count, number density and mean motion.
SectionAn oriented lineCrossings in both directions and net particle flow.
WallA physical boundaryAvailable contact reactions and load histories.

Particle, Region and Wall histories use acquired simulation frames. Section crossings are counted during DEM stepping. A history does not reconstruct values between acquired samples, and periodic edges are not physical walls.

See the four instruments

Global analysis

Analysis examines spatial organization across the active system. Availability depends on the experiment.

Granular LAB Analysis menu with Fields, Contacts and Photoelasticity, and synthetic fringe controls.
Analysis groups the supported global layers. Switching the control page does not disable an enabled layer.View full size

Fields

Map area fraction, mean velocity, speed or agitation. The averaging radius defines a physical measurement scale; grid resolution alone cannot recover detail removed by smoothing.

Contact

Explore contact geometry, spatial order, connectivity and available network descriptors. Contact arrangement and contact load are different quantities.

Force Links

Overlay force links and chains to identify the paths carrying load. Choose thresholds and force scales consistently when comparing states.

Photoelasticity

Visualize a synthetic fringe response to the simulated contact state. Gain and appearance controls change the image, not the mechanical forces. These images are not calibrated photographs of a photoelastic material.

Explore the global analysis tools

Choose a way to run

Run Comparison showing three independent chiral-motion runs, shared acquired curves and study settings.
Run Comparison keeps each run and its acquired curves together; sweep and background modes serve different workflows.View full size

Run Comparison

Vary one parameter across independently evolved runs, read acquired curves on shared axes and export the study. Available in 28 presets, with observables specific to the selected experiment.

Parametric sweep

Explore a parameter range as a batch and retain numerical outputs. Available in 42 presets. The execution settings let compatible cases share the available computing capacity.

Background run

Prepare a separate simulation and choose supported video and data outputs. The interactive workspace remains independent. Keep the complete result folder to revisit supported playback and synchronized observables.

Up to eight independent jobs can run concurrently, depending on CPU and memory. Four or fewer are recommended initially. This is parallel execution of separate simulations, not a claim that a single contact calculation uses every core.

See the three modes

Projects & recorded explorations

A .glab project brings together a captured configuration, instruments, studies, acquired recordings and notes.

  1. Choose File → New Project from Workspace to capture a supported setup, or use File → Record Exploration to acquire particle frames and selected measurements.
  2. Review the setup, sampling and notes. Save the project with File → Save.
  3. Reopen it from Finder or File → Open to consult the saved studies and acquired frames.
Granular LAB recorded exploration with a time history and a speed distribution from saved frames.
Recorded data can be analyzed without rerunning DEM.View full size

Recorded exploration supports a region → speed → histogram recipe. It does not reproduce every live Analysis layer or restore unsampled motion.

Recording is bounded at 1,200 frames or 200,000 particle states. Projects are limited to 256 MiB, including their index, and 64 studies. A project is not a general physical restart checkpoint. Keep a separate backup of important work.

Export & reproduce

Video Export dialog showing canvas-only or canvas plus observables, duration, frame interval, movie rate and output size.
Choose the exported content, acquisition interval and output dimensions before starting.View full size
OutputUse it for
Image / PNGThe supported current simulation view.
Particle snapshot CSVParticle properties at one instant.
Time series CSVAcquisition from the current state onward, rather than a retrospective dump of the screen history.
Field CSVAvailable spatial fields, with coordinates and averaging context.
VideoSupported simulation output; distinguish physical duration from movie playback duration.
Comparison exportStudy inputs, acquired data and diagnostics, with optional charts.
.glab projectNative review of a setup and its acquired work.

Keep the preset, seed, time step, preparation protocol, units and sampling definition with a quantitative result. Check numerical health and time-step sensitivity before drawing conclusions.

The model behind the motion

In Experiment → Physics of this experiment, read the equations of motion, parameter meanings, units and assumptions for each preset. The app distinguishes the integrated model from relations used to interpret the observations.

Actual Physics of this experiment panel explaining the chiral-motion model, its controls and units.
Equations and controls are explained together in the app.View full size

Most experiments use dry soft-particle DEM in two dimensions, with dissipative contacts, friction and rotation where applicable. Selected quasi-2D experiments use 3D spheres, and active-matter presets use idealized propulsion and interaction models.

Read each preset’s scope and maturity. “Implemented” does not mean calibrated in every regime; “Experimental” indicates specific outstanding physical checks. Granular LAB is not a CFD solver or a calibrated biological model.

The complete user manual

Cover of the Granular LAB 2.0 User Manual.
The complete reference is available as a PDF and offline in the app.View full size

The English PDF covers the workspace, instruments, global analysis, experiments, projects, exports and models, with real app screenshots and a reference for all 47 presets.

Open the Granular LAB 2.0 User Manual (PDF)

The same manual is available offline in the app through Help → User Manual (PDF).

Keep exploring.

Granular LAB 2.1 for Mac. Works offline. No account required.

Read the user manual (PDF)
Download on the Mac App Store
Created by Germán Varas · Instituto de Física, PUCVContact & supportPrivacy Policy
Cite Granular LAB

Varas, G. Granular LAB: a native macOS workspace for granular and active-matter simulations. Version 2.1.0, 2026.