Frequently Asked Questions

Since v2.0.0, pre-compiled binaries are provided for macOS (Apple Silicon and Intel) and Linux (x86-64). There is no standalone Windows binary in v2.x — Windows users should run the Linux binary inside WSL (Windows Subsystem for Linux). All downloads are available from the Downloads page and from the Bitbucket downloads page. Source code can be compiled on Linux or macOS using gfortran, gcc, and cmake — see the Developer section of the manual for full build instructions.

Because the binary is not signed with an Apple Developer ID, macOS will quarantine it on first run. To allow it:

1. Right-click (or Control-click) the MERRILL executable and choose Open.
2. In the dialog that appears, click Open again.

Alternatively, in a terminal: xattr -d com.apple.quarantine /path/to/merrill

Since v2.0.0, MERRILL does not ship a native Windows executable. The recommended approach is to use Windows Subsystem for Linux (WSL):

1. Enable WSL and install a Linux distribution (e.g. Ubuntu) from the Microsoft Store.
2. Download the Linux binary from the Downloads page and place it inside your WSL file system.
3. Run MERRILL from the WSL terminal exactly as you would on Linux:

   ./merrill my_script.txt

Alternatively, you can compile MERRILL from source on any system with gfortran, gcc, and cmake.

MERRILL reads PATRAN-format tetrahedral meshes (and TecPlot-format meshes). Several routes exist:

• GMSH — free, feature-rich, exports to many formats including PATRAN.
• Iso2Mesh — MATLAB/Octave library that converts STL files or image slices (e.g. from FIB-nt) to tetrahedral meshes using tetgen and CGal. A companion script merrillsave.m exports results in a MERRILL-readable format. Works with the free GNU Octave if you do not have MATLAB.
• CAD tools — OpenSCAD, FreeCAD, or Blender can generate complex 3-D shapes and export to STL; the STL surface mesh can then be converted to a volume mesh with tetgen or CGAL.
• CGAL / tetgen — command-line tools for direct volumetric meshing from STL surfaces.

Alternatively, use the pre-built mesh library on the Resources page to skip meshing entirely. A guide to using Iso2Mesh for MERRILL can be found at nanopaleomag.esc.cam.ac.uk.

The mesh must resolve the exchange length (l_ex) of your material. For magnetite, l_ex ≈ 5–7 nm, so a node spacing of 3–5 nm is standard for detailed simulations. The pre-built mesh library uses 3 nm (spheres, cuboids) and 9 nm (cuboctahedra) node spacings. Coarser meshes run faster but may miss narrow domain walls.

A MERRILL script is a plain ASCII text file containing a sequence of commands. Any file extension is accepted (the manual conventionally uses .txt); the .mscr extension is also commonly used. From the command line (Linux / macOS):

./merrill my_script.txt

On Windows, run the Linux binary inside WSL:

./merrill my_script.txt

Comments start with !; keywords are case-insensitive. See Tutorial 1 for a full walkthrough of your first simulation.

It depends heavily on mesh size and the number of field steps. A hysteresis loop on a 5,000-node mesh runs in a few minutes on a modern laptop. FORC simulations require many reversal curves (typically 50–200) and can take hours for large meshes. NEB path searches are the most computationally intensive and may run overnight for large systems.

Since v2.0.0, MERRILL uses the H2Lib boundary-element compression library, reducing memory usage from O(K²) to O(K·log K) during initialisation. This makes previously impractical grain sizes substantially more accessible.

• Increase Set: MaxEnergyEvaluations=<n> (e.g. 10000 or more) — this is the primary limit on minimisation iterations.
• Increase Set: MaxRestarts=<n> to allow the minimiser to restart from the current best state.
• Use a finer mesh — poor convergence often indicates unresolved domain walls. The mesh must resolve the exchange length (≈ 5–7 nm for magnetite).
• Start from a better initial state: use the Vortex command for PSD-sized grains, or Uniform magnetization for SD-sized grains.
• Try RandomizeMagnetization with a small angle (e.g. 5°) to perturb a stuck configuration.
• Switch between minimisation axes using Set: SwitchCount=<n> — the default multi-axis minimiser alternates between X, Y, Z polar coordinates and Cartesian, which helps escape local traps.

MERRILL writes two types of output files:

• <filename>_mult.tec — a TecPlot-format file containing the full mesh and magnetisation vectors. Open it in ParaView (free, cross-platform) or TecPlot and use the Glyph or Vector representation to display the magnetisation structure.
• <filename>.dat — a lightweight plain-text file with node coordinates and magnetisation vectors only (no mesh), useful for post-processing.

The demagnetisation field can be exported separately with the WriteDemag command, also in TecPlot format.

MERRILL does not currently manage job parallelism natively. You can run independent simulations in parallel manually by launching separate processes in different terminal sessions or using a shell script with background processes (&). Native multi-grain batch parallelism is planned for MERRILL 3 — see the Roadmap.

FORCINN accepts CSV and Excel (.xlsx) files containing raw FORC measurement data. The file should contain field and magnetisation columns as exported from common VSM/MPMS software (MPMS, EV9, VFTB). See the preprocessing documentation on the Resources page for column format details.

Typically 1–3 minutes on the server, depending on dataset size and current load. The progress bar on the FORCINN page tracks preprocessing, model loading, inversion, and post-processing stages.

The inversion returns:

• Size mean — the geometric mean grain diameter of the modelled assemblage (nm).
• AR mean — the mean aspect ratio (elongation) of the grain population.
• R² (loc) — coefficient of determination for the predicted vs measured FORC; higher is better.
• RMS (loc) — root-mean-square residual between predicted and measured FORC.

The output PNG shows the predicted FORC overlaid on the preprocessed input data.

Cite the primary software paper:

Ó Conbhuí, P., Williams, W., Fabian, K., Ridley, P., Nagy, L., & Muxworthy, A. R. (2018). MERRILL: Micromagnetic Earth Related Robust Interpreted Language Laboratory. Geochemistry, Geophysics, Geosystems, 19(4), 1080–1106. https://doi.org/10.1002/2017GC007279

A ready-to-paste BibTeX entry is in the citations.bib file.

The primary citation DOI is 10.1002/2017GC007279 (the G3 software paper). A Zenodo archive with a citable DOI for the software package itself is planned. In the meantime, cite the paper and include the Bitbucket URL and version number in your methods section.

Single domain (SD): grains small enough that uniform magnetisation across the whole grain is the lowest energy state. For magnetite, typically < 70–100 nm depending on shape.

Multi-domain (MD): large grains that reduce magnetostatic energy by subdividing into multiple domains separated by domain walls. Typically > 1–10 µm for magnetite.

Pseudo-single domain (PSD): the broad intermediate range, characterised by vortex or flower states. This is where most natural magnetic grains sit and where MERRILL provides the most insight.

See the Glossary for definitions.

MERRILL includes built-in material parameter presets for:

• Magnetite (Fe₃O₄) — including a temperature-dependent cubic/monoclinic anisotropy model valid from −200 °C to 580 °C (Verwey transition at −153 °C handled automatically)
• Titanomagnetite (Fe_3-xTi_xO₄, configurable Ti content x; compositions above x = 65 are less reliable)
• Pyrrhotite (Fe₇S₈) — monoclinic and hexagonal basal-plane anisotropy models available
• Greigite (Fe₃S₄)
• Haematite (α-Fe₂O₃)
• Iron (Fe) — valid up to the Curie temperature at 770 °C

Custom material parameters (M_s, A_ex, K₁, K₂, and others) can be specified directly in any MERRILL script for materials not listed above.