@apply table begin
    @where condition_1
    @where condition_2
    ...
end

Apply several @where conditions to a raw table, one after the other.

Each line in the block must be an @where comparison; anything else raises an error. Like @where, it works on the table (gas.data) in code units.

Returns the rows that satisfy every condition, as a table.

disc = @apply gas.data begin
    @where :rho >= density
    @where abs((:cz - 0.5) * boxlen / 2^:level - cv) <= height
end

@filter(obj, :column op value)

Filter by a single comparison. If obj is a Mera data object (hydro/gravity/RT/particles/ clumps) it routes through filterdata: the column may be any getvar quantity (derived physics, code units) and the result is a new object of the same type. If obj is a raw IndexedTable, the classic per-row column filter is used. For units, compound conditions (&/|/!) and percentile/finite selectors, use filterdata with Above etc.

hot = @filter gas :rho >= 1e2     # Mera object → HydroDataType of the matching cells
sub = @filter gas.data :rho >= 1e2  # raw table → filtered table (classic behaviour)

Returns a new object of the same type for a Mera object, or the filtered table for a raw table.

@loadall path output component...

Bind several components of one snapshot to variables of those names, in one line.

@loadall path 300 hydro gravity particles
# hydro, gravity and particles are now bound, and so is info

This is a thin wrapper over loadall; it expands to a destructuring assignment and adds nothing of its own.

(; hydro, gravity, particles) = loadall(path, 300)

Keyword arguments are passed through:

@loadall path 300 hydro particles lmax=10 range_unit=:kpc

Returns the same named tuple as loadall, so nt = @loadall path 300 hydro also works.

@project data quantity... [keyword=value...]

Project several quantities and bind each map to a variable of that name.

projection returns one object whose maps is a dictionary, so pulling several quantities out of it is a line of lookups:

pj = projection(gas, [:sd, :T], myargs=args)
sd = pj.maps[:sd]; T = pj.maps[:T]

This does the same in one line, and asks for the quantities together, which is also the form that lets the projection use its threads (see Performance):

@project gas sd T myargs=args
# sd and T are now the maps, and proj is the full projection object

Keywords pass straight through, so off-axis works the same way:

@project gas sd inclination=60 azimuth=30 binning=:exact

The full object is bound as proj, so the extent, units and everything else stay reachable:

heatmap(proj.extent[1:2], proj.extent[3:4], sd)

Like @loadall, this binds names in your scope. Inside a function or a package, prefer the explicit form above.

See also: projection, @loadall.

@region [unit=…] [center=…] begin … end

Build a (composite) region with shared constructor defaults and named parts. Inside the block, every Sphere/Cuboid/Cylinder/SphericalShell/CylindricalShell call that does not set range_unit/center itself receives the block's unit/center; explicit keywords always win. Assignments name intermediate parts; the block's last expression is the returned region — an ordinary AbstractRegion value, identical to writing the constructors out by hand.

capstone = @region unit=:kpc center=[:bc] begin
    disc    = cylinder(12, 2)
    blister = sphere(2.5; center=[30, :bc, 26])   # explicit center wins
    chimney = cylinder(1.2, 5; center=[19, :bc, :bc])
    (disc ∪ blister) \ chimney
end
subregion(gas, capstone)

@where table :column op value
@where table expression_of_columns op value

Keep the rows of a table whose columns satisfy one comparison.

Column names are written as symbols and can be combined in an expression, e.g. @where tbl abs((:cz - 0.5) * boxlen / 2^:level - cv) <= height; other names are taken from the surrounding code. It works on the raw table (gas.data), in code units, and is mostly used inside @apply to chain several conditions. For a Mera object and derived quantities, use @filter or filterdata.

Returns the filtered table.

dense = @where gas.data :rho >= 100.0

Mutable Struct: Contains the maps/units returned by an AMR cell-based projection (hydro, gravity-with-hydro, and radiative-transfer all return this type; the provenance is preserved in the .info field). smallr/smallc are hydro-only and set to 0 for RT.

Fields

• maps::SortedDict{Symbol,Array{Float64,2}} — one 2D map per requested quantity, keyed by variable symbol (e.g. :sd, :rho, :vx, :T). For an intensive variable the map is the weighted average per pixel; for an extensive variable (:sd, and :mass/:ekin/:etherm/ :volume under mode=:sum) it is the per-pixel column/sum. Access as proj.maps[:sd].
• maps_unit::SortedDict{Symbol,Symbol} — the physical unit of each map (e.g. :Msol_pc2, :g_cm3, :km_s, :standard for code units), keyed by the same symbols as maps.
• maps_lmax::SortedDict — always empty. A leftover field: both projection engines create it and neither ever writes to it. Do not read a level from it.
• maps_weight::SortedDict{Symbol,Symbol} — the weighting used per map: :mass, :volume, or :nothing for the extensive :sum/:sd accumulations that carry no weighting.
• maps_mode::SortedDict{Symbol,Symbol} — how each map was reduced: :mass_weighted, :volume_weighted, :standard, or :sum.
• lmax_projected::Real — the maximum AMR level actually used in the projection.
• lmin::Int, lmax::Int — the simulation's level range carried over for provenance.
• ranges::Array{Float64,1} — the 6-element projected sub-box [xmin,xmax,ymin,ymax,zmin,zmax] in box-fraction units [0,1]. (proj.xrange/yrange/zrange are accessor slices of this.)
• extent::Array{Float64,1} — [xmin,xmax,ymin,ymax] of the map in code length units (multiply by proj.scale.kpc etc. for physical axes); the data-plane extent for plotting.
• cextent::Array{Float64,1} — the same extent but centred on the chosen projection centre (so the centre sits at 0); use for axes labelled relative to the centre.
• ratio::Float64 — pixel aspect ratio of the map (xspan/yspan).
• effres::Int — the effective square resolution (pixels per side); proj.res aliases this.
• pixsize::Float64 — physical size of one pixel in code length units (× scale for kpc/pc).
• boxlen::Float64 — the simulation box length in code units.
• smallr::Float64, smallc::Float64 — hydro density/sound-speed floors (0 for RT projections).
• scale::ScalesType003 — unit-conversion factors (code↔physical) inherited from the dataset.
• info::InfoType — the full simulation descriptor (provenance: output, paths, cosmology, …).
• los, up, cam_right, center::Vector{Float64} — off-axis camera basis and centre; empty Float64[] for axis-aligned projections. proj.direction returns :offaxis when populated.

Above(quantity, value; unit=:standard)

Keep rows where getvar(obj, quantity, unit) > value.

AbovePercentile(quantity, p; unit=:standard)
BelowPercentile(quantity, p; unit=:standard)

Keep rows above (below) the p-th percentile of quantity over obj (p ∈ [0,100]) — an adaptive threshold, e.g. the densest 10 % of cells: AbovePercentile(:rho, 90).

AbstractFinder

Supertype of the seven 3D structure-finding algorithms passed to clumpfind: ThresholdFoF, DensityWatershed, Dendrogram, GraphSegFinder, HDBSCANFinder, PhaseSpaceFoF and PersistenceFinder. A finder is a typed parameter bundle (field, threshold, linking length, neighbour backend) that implements _label(finder, points); extend it by adding a new subtype and _label method.

Abstract supertype of the spatial indices used to find neighbours during clump finding.

Concrete subtypes are HashGrid and CellLinkedList; clumpfind picks one automatically from the particle count and density. Both index an arbitrary ids subset of the coordinate arrays, so the same code serves the FoF pass and the per-group watershed.

AbstractRegion

Supertype of the composable region value types passed to subregion: Cuboid, Sphere, Cylinder, SphericalShell, CylindricalShell. A region is a geometry-relative-to-center value type; subregion(obj, region) selects the cells it covers and, with split=true, attaches the exact per-cell inside-fraction. Regions compose with the boolean operators ∩ (intersection), ∪ (union), \ (difference) and ! (complement) — e.g. sphere(20) \ cylinder(5, 30) drills a cylindrical hole through a ball.

Abstract supertype of the criteria a candidate clump must satisfy to be kept.

Validators passed to clumpfind combine as an AND: a clump survives only if it passes every one. Concrete subtypes include MinMembers, and membership tests such as unbinding are applied during the analysis while predicates are applied after — that order is enforced regardless of the order you list them in.

Mutable Struct: Contains fields to use as arguments in functions

Below(quantity, value; unit=:standard)

Keep rows where getvar(obj, quantity, unit) < value.

BelowPercentile(quantity, p; unit=:standard)

Keep rows below the p-th percentile of quantity over obj (p ∈ [0,100]); the lower counterpart of AbovePercentile.

BenchmarkReport

What benchmark_report returns. Fields: info, nfiles_total, bytes, storage_split (bytes per component), filesystem, storage, reading, conversion, sweep, work_threads, reportfile. Stages that were not run are nothing.

Bound(egrav=:tree; iterative=true, softening=0.0, direct_max=2000)

Self-boundedness validator: builds the per-clump energy budget with potential egrav (:tree Barnes–Hut / :direct exact / :approx 3·GM²/5R), optionally strips unbound members (iterative, SUBFIND), and keeps only self-bound clumps (e_kin+e_therm[+e_mag] < |e_grav|).

Neighbour index storing cell occupancy in flat arrays covering the whole bounding box, which avoids hashing at the cost of memory proportional to that box.

The choice for dense, compact point sets. See HashGrid for the sparse counterpart and AbstractNeighborIndex for how one is selected.

CellLinkedList <: AbstractNeighborIndex

Mutable Struct: Contains the existing simulation snapshots in a folder and a list of the empty output-folders

ClumpCard(kind, field=:rho; threshold, linking_length, threshold_unit=:standard, pos_unit=:kpc, mass_unit=:Msol, min_members=1, label="")

A report card that runs clumpfind and reports the clump count + total clump mass (the full ClumpCatalog is kept in the result card's data.catalog).

ClumpCatalog

Result of clumpfind. clumps is a vector of per-clump NamedTuples (sorted most-massive first); meta records the search parameters; tree is the StructureTree hierarchy (only when built via hierarchy=true, else nothing). Index/iterate it like a vector (cat[1], length(cat), for c in cat).

Mutable Struct: Contains clump data and information about the selected simulation

ClumpDataType <: ContainMassDataSetType

CombinedCard(datatypes, compute; unit=:fraction, label="combined")
CombinedCard(datatypes; unit=:fraction, label="combined") do datas … end

A cross-datatype scalar card. compute(datas) receives a Dict{Symbol,Any} of the read data objects for datatypes and returns a number. Computed only if all datatypes are present. See the built-ins baryon_fraction and clump_mass_fraction.

Mutable Struct: Contains the collected information about the compilation of RAMSES

Abstract Supertype of all datasets that contain mass variables

HydroPartType <: ContainMassDataSetType <: DataSetType

Mutable Struct: The runtime cost model behind report's dry-run and budget modes

Holds the per-unit coefficients of the work a report does — per read, per cell, per projection pixel, per deposited cell, per histogram bin, per particle — together with multiplicative corrections learned per cost class, so estimates track this machine rather than a generic one. Corrections are updated passively from every real report run, or actively via calibrate!.

preview prints the resulting dry-run; downsample shrinks a plan to a wall-time target, which is the mechanism behind report(...; budget_s=…).

CoveringGridResult

Result of covering_grid / slice. grid maps each variable to its uniform array (3-D for a covering grid, 2-D for a slice); level is the uniform refinement level, dims the array size, extent the physical bounds [x0,x1,y0,y1,z0,z1] and cellsize the physical cell size (both in pos_unit). Index grid[:rho] for the array.

cuboid(; xrange, yrange, zrange, center=[:bc], range_unit=:kpc)

An axis-aligned box; xrange/yrange/zrange are [lo, hi] offsets from center (in range_unit), as in subregion(:cuboid).

Custom(f)

Keep clumps for which f(clump)::Bool is true (clump is the per-clump NamedTuple, with fields n_members, mass, com, peak, radius and — when bound — e_kin, e_grav, alpha_vir, bound).

cylinder(radius, height; axis=[0,0,1], center=[:bc], range_unit=:kpc)

A cylinder of cylindrical radius spanning ±height along axis (so height is the half-height, matching the existing subregion(:cylinder) convention). axis is the symmetry direction (any non-zero 3-vector, normalised internally) — e.g. a galaxy's spin vector for a tilted disk; the default [0,0,1] is the classic z-aligned cylinder.

cylindricalshell(r_in, r_out, height; axis=[0,0,1], center=[:bc], range_unit=:kpc)

A cylindrical shell r_in ≤ r_cyl ≤ r_out of half-height height along axis (the value-type analogue of shellregion(:cylinder); axis allows a tilted shell).

Abstract Supertype of all the different dataset type maps AMRMapsType <: DataMapsType PartMapsType <: DataMapsType

Abstract Supertype of all the different dataset types

HydroPartType <: ContainMassDataSetType <: DataSetType

Dendrogram(field=:rho; threshold, linking_length, threshold_unit=:standard, min_delta=0.0, backend=CellLinkedList)

Multi-scale hierarchy finder (Rosolowsky & Leroy 2008): the finest density peaks (local maxima with prominence ≥ min_delta) are the catalog's leaf clumps, and clumpfind(obj, …; hierarchy=true) attaches the full merge StructureTree recording the level at which they join. min_delta (in field units) is the minimum peak-to-saddle contrast for a separate leaf.

DensityWatershed(field=:rho; threshold, linking_length, threshold_unit=:standard, peak_min_distance=2·linking_length, persistence=0.0, backend=CellLinkedList)

Watershed finder: friends-of-friends for connectivity, then each connected group is split into density-descending basins (peaks separated by peak_min_distance), so touching cores are resolved along their saddles (DENMAX/SUBFIND-style). persistence (in field units) prunes shallow basins: a basin whose prominence — peak value minus the saddle at which it joins a deeper basin — is below persistence is merged into that deeper basin (topological contrast control, Rosolowsky & Leroy 2008 min_delta). persistence=0 keeps every local maximum (bare watershed).

Mutable Struct: Contains the collected information about the descriptors

Equals(quantity, value; unit=:standard, atol=0.0)

Keep rows where getvar(obj, quantity, unit) == value (within atol). Best for discrete fields such as :level, particle ids or :family.

Mutable Struct: Contains the full paths of the files belonging to one simulation output

Reachable as info.fnames. Each field is the resolved path Mera reads for that component, e.g. info.fnames.hydro, which is useful when checking what a reader actually opened.

FilterCondition

Supertype of the composable value-space selectors passed to getmask / filterdata: Above, Below, InRange. Combine them with & (and), | (or) and ! (not) — e.g. Above(:T, 1e4; unit=:K) & Below(:rho, 100; unit=:nH).

GalaxyFrame

Orientation + centre returned by face_on / edge_on. Splat the fields straight into projection:

fr = face_on(gas)
projection(gas, :sd; los=fr.los, up=fr.up, center=fr.center, range_unit=fr.center_unit)

Fields: center (in center_unit), los (unit vector the camera looks along), up (unit vector for the camera's up direction), angmom (the net angular-momentum vector the frame was derived from), and info (the source snapshot — so provenance(frame) works).

GraphSegFinder(field=:rho; threshold, linking_length, threshold_unit=:standard, scale=1.0, backend=CellLinkedList)

Graph-segmentation finder (Felzenszwalb & Huttenlocher 2004): segments the neighbour graph so that the density variation within a region stays below the contrast between regions. scale k sets the granularity (larger ⇒ fewer, larger segments). Near-linear; good as a fast multi-scale deblender, e.g. deblend=GraphSegFinder(...).

Mutable Struct: Contains gravity data and information about the selected simulation

Returned by getgravity. Holds the selected leaf cells in data, the originating InfoType in info, and the unit scales in scale.

GravDataType <: DataSetType

Mutable Struct: Contains the collected information about grid

HDBSCANFinder(field=:rho; threshold, linking_length, threshold_unit=:standard, min_cluster_size=5, min_samples=min_cluster_size, backend=CellLinkedList)

Density-adaptive finder — a self-contained HDBSCAN* (Campello+2013; McInnes+2017): core distances from the min_samples-nearest neighbours define a mutual-reachability metric whose minimum spanning tree is condensed into a cluster hierarchy, and the most stable clusters (each with ≥ min_cluster_size members) are extracted. Finds clumps across a wide density range with almost no tuning; points not in any stable cluster are labelled noise (dropped). linking_length only bounds the neighbour search (set it generously).

Neighbour index storing occupied cells in a Dict, so memory scales with the number of occupied cells rather than the bounding box.

The choice for sparse or widely spread point sets. See CellLinkedList for the dense counterpart and AbstractNeighborIndex for how one is selected.

HashGrid <: AbstractNeighborIndex

Mutable Struct: Contains the 2D histogram returned by the function: histogram2 and information about the selected simulation

Mutable Struct: Contains hydro data and information about the selected simulation

HydroDataType <: HydroPartType

const HydroMapsType = AMRMapsType

Deprecated alias for AMRMapsType (renamed because gravity and RT projections return the same AMR-map type, not only hydro). Kept for backward compatibility: existing code using HydroMapsType (construction, isa, dispatch) keeps working unchanged. Prefer AMRMapsType in new code.

Abstract Supertype of data-sets that contain hydro and particle data

HydroPartType <: ContainMassDataSetType <: DataSetType

IOBenchmark

Result of run_benchmark: the iops, throughput and openclose sub-results (each with .samples/.stats), the number of runs, the threads levels tested, and total_elapsed seconds. Pass it to plot_results for a figure.

InRange(quantity, lo, hi; unit=:standard)

Keep rows where lo ≤ getvar(obj, quantity, unit) ≤ hi.

Mutable Struct: Collected information about the selected simulation output

IsFinite(quantity; unit=:standard)

Keep rows where getvar(obj, quantity, unit) is finite (drops NaN/Inf) — data hygiene, e.g. before a statistic. Combine with ! to select the non-finite rows instead.

MassAbove(m)

Keep clumps with mass > m (in the catalog's mass_unit).

MeraMovie

A stack of projected frames over a simulation's outputs, returned by getmovie: frames (a vector of 2D maps), the per-frame outputs and times, the map extent, and the quantity/unit/time_unit. Write it to an animated GIF with savemovie.

MinMembers(n)

Keep only clumps with at least n members.

MortonGrid <: AbstractNeighborIndex

Neighbour-search backend (pass as backend=MortonGrid to any finder). Like CellLinkedList, but the indexed points are visited in Morton (Z-order) order so spatially-near points are also near in the traversal — neighbour lookups then touch cache-resident coordinates and the access pattern is near-sequential (the locality an out-of-core path also needs). Produces exactly the same neighbour pairs as the CellLinkedList/HashGrid backends; only the traversal order, and hence speed on large selections, differs.

Mutable Struct: Contains particle data and information about the selected simulation

PartDataType <: HydroPartType

Mutable Struct: Contains the collected information about particles

Mutable Struct: Contains the maps/units returned by a particle projection (projection(::PartDataType, …)). Particle maps are histogram deposits of the selected quantity onto the sky grid; provenance is preserved in the .info field.

Fields

• maps::SortedDict{Symbol,Array{Float64,2}} — one 2D map per requested quantity, keyed by variable symbol (e.g. :sd surface density, :vx, :age). :sd is the column mass per pixel area; intensive variables are mass- or volume-weighted averages per pixel.
• maps_unit::SortedDict{Symbol,Symbol} — the physical unit of each map (e.g. :Msol_pc2, :km_s, :standard for code units), keyed by the same symbols as maps.
• maps_lmax::SortedDict — always empty. A leftover field that is created and never written, on this path as on the grid one.
• maps_mode::SortedDict{Symbol,Symbol} — how each map was reduced: :mass_weighted, :volume_weighted, :sph, :voronoi, or :sum when mode=:sum was given. weighting picks the weight, mode picks a weighted mean against a per-pixel total.
• lmax_projected::Real — the maximum grid level used.
• lmin::Int, lmax::Int — the simulation's level range carried over for provenance.
• ref_time::Real — the reference time (code units) used to convert birth times to ages for age-dependent quantities (e.g. :age); taken from info.time unless overridden.
• ranges::Array{Float64,1} — the 6-element projected sub-box [xmin,…,zmax] in box-fraction units [0,1]. (proj.xrange/yrange/zrange are accessor slices.)
• extent::Array{Float64,1} — [xmin,xmax,ymin,ymax] of the map in code length units (× proj.scale.kpc etc. for physical axes).
• cextent::Array{Float64,1} — the same extent centred on the projection centre.
• ratio::Float64 — pixel aspect ratio of the map (xspan/yspan).
• effres::Int — effective square resolution (pixels per side); proj.res aliases this.
• pixsize::Float64 — physical size of one pixel in code length units (× scale for kpc/pc).
• boxlen::Float64 — the simulation box length in code units.
• scale::ScalesType003 — unit-conversion factors (code↔physical) inherited from the dataset.
• info::InfoType — the full simulation descriptor (provenance).
• los, up, cam_right, center::Vector{Float64} — off-axis camera basis and centre; empty Float64[] for axis-aligned projections. proj.direction returns :offaxis when populated.

PersistenceFinder(field=:rho; threshold, linking_length, persistence, threshold_unit=:standard, backend=CellLinkedList)

Topological persistence clustering (0-dim persistent homology / ToMATo; Chazal+2013): a superlevel-set filtration of the density field where a peak is kept as a separate cluster only if its prominence (peak − merge saddle) reaches persistence. Principled, parameter-light deblending that is robust in crowded fields.

PhaseCard(kind, xvar, yvar; weight=:mass, nbins=(80,80), xscale=:log, yscale=:log, xunit=:standard, yunit=:standard, label="")

A phase (2-D histogram) card for a ReportPlan.

PhaseSpaceFoF(field=:rho; threshold, linking_length_pos, linking_length_vel, threshold_unit=:standard, backend=CellLinkedList)

6-D phase-space friends-of-friends (Rockstar-style; Behroozi+2013): points link only when within linking_length_pos in space and linking_length_vel (km/s) in velocity, so kinematically distinct populations that overlap spatially — streams, subhaloes, tidal debris — separate. Needs velocities (the finder loads them automatically).

Mutable Struct: Legacy physical-constants layout, retained so older mera/JLD2 files still load

Superseded by PhysicalUnitsType002, which is what info.constants carries today. This type exists only so files written by earlier Mera versions can be reconstructed and upgraded on load. Values are in cgs units.

Mutable Struct: Contains the physical constants in cgs units

ProfileCard(kind, xvar, yvar=nothing; weight=:mass, nbins=40, geometry=:none, unit=:standard, xunit=:standard, range_unit=:standard, center=[:bc], yscale=:auto, label="")

A profile (1-D radial/other profile) card for a ReportPlan. For a disk galaxy use xvar=:r_cylinder, geometry=:cylindrical (radius in the disk plane); :r_sphere, geometry=:spherical suits a halo/spheroid. yscale sets the y-axis when plotted: :log/:log10 (log₁₀), :identity (linear), or :auto (log when the profile is positive and spans ≳ 1.5 decades, e.g. density).

ProjectionCard(kind, var; unit=:standard, weight=:mass, res=256, pxsize=nothing, direction=:z, center=[:bc], range_unit=:standard, label="")

A projection card (surface-density / mass-weighted map) for a ReportPlan.

Resolution is set either by res (pixels per side) or by pxsize=[value, unit] (physical size of a pixel, e.g. [100., :pc]). pxsize wins when both are given. Because a card is built before the simulation is read, a pxsize cannot be converted to a pixel count until report runs — estimate/preview therefore resolve it against the box at that point.

Provenance

Reproducibility record returned by provenance: mera_version, mera_build (the version, plus the branch and commit when Mera is a git checkout, so a result made on a development version does not claim a release), simulation path, output, simcode, cosmological, the snapshot time_myr (physical time in Myr; the age of the universe for a cosmological run), redshift and aexp, boxlen, ndim, levelmin/levelmax, the serialized scale_type (e.g. :ScalesType003), and the output's file_ctime. Render a one-liner with provenance_string.

QuickLookResult

Result of quicklook. Fields: info, levelmin, levelmax, lmax_used (level actually read, nothing for a header-only call), ncells (cells read), sampled (true ⇒ coarse/partial ⇒ estimates are approximate), maps (a NamedTuple of surface-density projections: gas x, y, z, face-on stars/dm when particles are present, plus a face-on magnetic-field map bmag (μG) on an MHD run, or nothing), phase (the ρ–T histogram, or nothing), budget (a NamedTuple global snapshot budget — gas/stellar/DM mass and current SFR — or nothing), and summary (a NamedTuple of facts + estimates).

QuickReport

The result of report: cards (a vector of [ReportResultCard]), summary (header facts), provenance, cost (timings), and info. Render with render(report, :ascii|:jld2|:file) or reload with loadreport.

Abstract supertype of the recipe cards you compose into a report.

A card describes one panel — what to compute and how to draw it — and its concrete type selects which Mera function runs. ProjectionCard is the most common; others cover phase diagrams, profiles and scalars. Build a list of cards and hand it to report.

ReportPlan(output; path=".", cards=[], lmax=-1, budget=2_000_000)

A declarative, inspectable plan of report cards. Build it, preview its cost, then run it with report. cards is a vector of ReportCard. lmax=-1 picks a budgeted level (coarse if the full output exceeds budget cells), mirroring quicklook.

ReportResultCard

A computed card inside a [QuickReport]: label, kind (:map/:phase/:profile/:scalar), datatype, func, the plain-data data payload, and a meta NamedTuple (units, ranges, cost_s, sampled, …).

Mutable Struct: Contains radiative-transfer (RT) data and information about the selected simulation

Returned by getrt. Same AMR leaf-cell structure as hydro, carrying the nvarrt RT variables: per photon group g, the photon number density Np plus the flux components Fx/Fy/Fz. Mirrors GravDataType.

RtDataType <: DataSetType

SFRCard(kind=:particles; tbinsize=10.0, trange=[0.0,missing], unit=:Msol_yr, mode=:none, mass=:auto, mask=nothing, label="")

A star-formation-history card (sfr). mode=:probability gives the normalised SFH (a fraction); mass=:auto prefers a stored initial-mass field; mask=obj->BitVector subselects.

Satisfies(quantity, f; unit=:standard)

Keep rows where f(value)::Bool for each getvar(obj, quantity, unit) value — a composable arbitrary predicate (the value-type form of the filterdata(obj, :q, pred) shorthand).

ScalarCard(kind, var; reduce=:sum, unit=:standard, fraction=false, relative_to=nothing, mask=nothing, label="")

A scalar reduction card (reduce ∈ :sum,:mean,:extrema,:count). fraction=true divides by the total of relative_to (or var); mask=obj->BitVector restricts the rows.

Mutable Struct: Legacy unit-scale layout, retained so older mera/JLD2 files still load

Superseded by ScalesType003, which is what new data carries. This type exists only so files written by earlier Mera versions can be reconstructed and upgraded on load; it is not what you get from a current getinfo.

Mutable Struct: Contains the created scale factors from code to physical units

Mutable Struct: Contains the unit scales of the loaded simulation

The current scale type, reachable as info.scale and as the scale field of every data object. Each field converts a code-unit value into that physical unit, e.g. scale.kpc.

Identical to ScalesType002 plus the :nG (nanogauss) magnetic unit. Versioned rather than extended in place so pre-existing mera/JLD2 files — which store the 133-field ScalesType002 layout — still reconstruct; the JLD2 typemap upgrades them on load.

SidecarRecord

What readsidecar and sidecaroverview return for one sidecar: file (the data file), sidecar (the .meta.json), data (the parsed JSON, index it like a dictionary, e.g. r.data["source"]["output"]) and status: :unchanged or :changed when the file's SHA-256 was checked, :missing when the data file is gone, :unchecked otherwise.

SimulationRecord

What simulationrecord returns: data, the record as an ordered dictionary (index it directly, e.g. rec["resolution"]["levelmax"]), and path, the simulation folder. It prints a short summary in the REPL. Write it as JSON with writesimulationrecord, or turn it into DataCite metadata with datacite.

Mutable Struct: Contains the RAMSES sink-particle catalogue and the simulation metadata

mutable struct SinkDataType <: ContainMassDataSetType
    data
    info::InfoType
    boxlen::Float64
    ranges::Array{Float64,1}
    selected_sinkvars::Array{Symbol,1}
    used_descriptors::Dict{Any,Any}
    scale::ScalesType003
end

Sinks are written by RAMSES as a single CSV per output (sink_NNNNN.csv), not as one file per CPU like the AMR data — the catalogue is small and global. The file carries TWO header lines: the column names, and the dimensional formula of each column in terms of m, l and t (e.g. l t**-1 for a velocity). Mera keeps those formulas in used_descriptors[:units] so the physical meaning of every column survives the read.

Load with getsinks.

sphere(radius; center=[:bc], range_unit=:kpc)

A ball of radius (in range_unit) about center.

sphericalshell(r_in, r_out; center=[:bc], range_unit=:kpc)

The shell r_in ≤ |r| ≤ r_out (in range_unit) about center.

StructureNode

One node of a StructureTree: id, parent (0 at a root), children (ids), an is_leaf flag, the peak field value in its subtree, the base level at which it forms (the saddle where it merges into its parent, or the threshold at a root), and member counts n_self (points it owns directly — nonzero only for leaves) and n_subtree (points in the whole subtree).

StructureTree

The multi-scale hierarchy produced by a Dendrogram finder (clumpfind(obj, …; hierarchy=true)): nodes (a vector of StructureNode, indexable by node id) and roots (top-level node ids, one per disconnected region). Leaves are the finest structures (density peaks pruned by min_delta); branches are the levels at which they merge. Accessors: roots, leaves, children, parent.

ThreadSafeProgress

Mutable struct for managing progress bar updates across multiple threads. Prevents race conditions when multiple threads try to update progress simultaneously.

Fields

• progress: ProgressMeter.Progress object for display
• current_file: Name of file currently being processed
• completed: Number of files completed so far
• total: Total number of files to process
• lock: ReentrantLock for thread synchronization

ThreadSafeProgress(total::Int) -> ThreadSafeProgress

Constructor for thread-safe progress tracker. Initializes progress bar with appropriate settings for file conversion display.

Progress Bar Configuration

• Shows completion ratio [completed/total]
• Updates every 0.5 seconds to avoid excessive output
• 40-character progress bar for good visual feedback
• Shows processing speed (files/second)

ThresholdFoF(field=:rho; threshold, linking_length, threshold_unit=:standard, backend=CellLinkedList)

Friends-of-friends finder: members with field ≥ threshold are linked into a clump when within linking_length of one another. The classic, fast connectivity finder (Davis et al. 1985).

VirialBelow(alpha)

Keep clumps with virial parameter alpha_vir < alpha. Requires a Bound in the chain (or boundedness=true) so alpha_vir is computed; a non-finite alpha_vir fails the test.

VolumeLook

How a quantity is turned into colour and opacity, resolved to numbers by volumelook: quantity, unit, scale, colorrange, colormap, the opacity ramp and its opacity_gamma, the sigma (per cm) that full opacity means, and the background colour.

Reuse one look for every frame of a movie, so the colours and the opacity do not change from frame to frame.

VolumeRenderType

The result of volumerender.

• image: the picture, Matrix{RGB{Float64}} indexed [ix, iy] like a projection map. Save it with save("frame.png", rotl90(m.image)).
• alpha: how much of each pixel is filled, 1 − transmission, between 0 and 1
• value: the value of the quantity you actually see, averaged along the ray and weighted by what reaches you (NaN where nothing is visible)
• look: the VolumeLook used, so the next frame can share it
• extent, pixsize: code length, measured from the centre of the view (getextent)
• los, up, cam_right, center: the camera; los points toward the observer
• supersample, boxlen, scale, info

Mutable Struct: Contains the output statistics returned by wstat

Union Type: Mask-array that is of type Bool or BitArray MaskType = Union{Array{Bool,1},BitArray{1}}

JLD2flag(first_flag::Bool) -> (Bool, Symbol)

Determines the appropriate file mode for JLD2 operations.

• First write operation: creates new file (:write mode)
• Subsequent operations: append to existing file (:append mode)

Returns updated first_flag and corresponding file mode symbol.

__init__()

Announce Mera on load. In an interactive session (REPL / Jupyter) print the ASCII banner with the version; otherwise emit a single greppable @info "Mera vX.Y.Z" line (stderr, silenceable, doesn't pollute stdout) so scripts / tests / CI get a clean one-line marker instead of the art. The version comes from pkgversion, so it always tracks Project.toml. (Top-level printlns would only run during precompilation, so this lives in __init__ instead.)

_attach_gravity_parents!(grav; verbose=true)

Reads the stored gravity values of every refined cell from the original output and keeps them in grav.used_descriptors[:parents] (Mera cell coordinates, like the leaves), so they travel into a mera file. writeramses then writes them instead of averages of the children.

_boundary_group(info) -> Dict

&BOUNDARY_PARAMS of the run. When Mera's copy of the namelist lacks it (older RAMSES versions leave namelist.txt empty) but the output has walls and still exists, the walls are taken from its amr files and checked there (as repartition does), and returned in namelist form.

_can_select_columns(info) -> Bool

Whether gethydro(info; vars=…) will actually be honoured for this snapshot's code.

True for native RAMSES, which reads a column subset itself, and for a frontend that declared select_vars=true. False otherwise, where asking for a subset raises rather than quietly returning everything. Callers that request a subset as an OPTIMISATION (quicklook) must check this first and fall back to a full read, or they break on every reader that cannot narrow.

_check_unit_factor(factor, unit)

Reject a conversion factor that cannot be real.

A unit is resolved with getfield(scale, unit), so an unknown name raises FieldError immediately — but a field that exists and was never assigned returns whatever memory held, typically a subnormal near 1e-314, and does so SILENTLY. That is the dangerous case: results come out as plausible-looking numbers rather than an error, and they differ between processes. This turns that back into a loud failure.

Fill the card and cut off the overflow, keeping the part anchor names.

Scale the whole picture into the card and pad what is left over. Nothing is lost.

_fov_premask(dataobject, mask) -> (object, mask)

Internal. Apply a boolean mask to the object BEFORE the fov sphere is cut out of it.

A mask is one boolean per row of the object the caller holds, and the fov path projects a subregion of that object, so passing the mask on unchanged hands the inner call the wrong length. Cutting the mask to the selection instead is not reliable either: subregion keeps a cell whose volume overlaps the sphere at all, not merely one whose centre is inside, so no open-coded test reproduces its row set. Masking first sidesteps the question, because the sphere is then cut from data that is already filtered.

The stored gravity parents of a Mera object as leaf cells for the writer, or nothing.

&REFINE_PARAMS interpol_var of the run (RAMSES's default 0 when it is not set).

_lz4_typemap()

Create a JLD2 typemap entry for handling old LZ4FrameCompressor objects.

Old files have LZ4FrameCompressor with header::TranscodingStreams.Memory field, new code expects header::Vector{UInt8}. We map the old type directly to the current type — JLD2 constructs a fresh default compressor, which works because the compressor is just metadata (the actual compressed data is separate).

_mask_rows(t, pred) -> Vector{Bool}

Evaluate a row predicate over a table WITHOUT materialising a NamedTuple per row.

pred(c, i) receives the table's column NamedTuple c and a row index, so it reads c.cx[i] where the row-wise form read p.cx. The arithmetic is written out identically — this is a loop over columns, not a broadcast rewrite — so results are bit-for-bit what filter(p -> …, t) produced, while skipping the per-row NamedTuple that made the row-wise form cost ~80 allocations per row on a wide table (see _subset_table).

Pair with _subset_table to replace a filter:

sub = _subset_table(t, _mask_rows(t, (c,i) -> c.level[i] > 5))

_minimum_image(d, L)

Nearest separation d under periodic boundaries of period L, i.e. wrapped into [-L/2, +L/2].

RAMSES boxes are periodic, so the true distance between two points is the shortest of the direct separation and the ones going around the box. For a point near a face the direct separation is the LONG way round: with L = 0.5, a cell at d = 0.45 is really 0.05 away. Getting this wrong is silent — every distance stays finite and plausible — and it changes answers qualitatively: measuring a Sedov blast at the box origin with direct distances gives a fitted expansion exponent of 1.41 instead of the correct 0.4.

Branchless, and exact for any d (not just |d| < L).

_namelist_float(v) -> Union{Float64,Nothing}

Internal. Parse one RAMSES namelist value. A value routinely carries a trailing Fortran comment (eta_sn=.0 ! Efficiency of the feedback) which parse rejects, and may use a Fortran d exponent (1d2). Returns nothing when the value is not a number, so a malformed entry is skipped rather than making the whole output unreadable.

Namelist group from Mera's namelist_content as key => [values…].

True if key is set to .true. in namelist group group.

Number of records in a Fortran file (a particle file: 8 header records, then one per field).

_ordering(info) -> Symbol

RAMSES's domain ordering of the run: from the namelist (&RUN_PARAMS ordering), else from the original output, else RAMSES's default :hilbert. A restart needs the files in the ordering its namelist names.

The original RAMSES output directory of a Mera object, if it still exists.

The colour the padding takes: whichever colour the picture's own corners agree on.

_particle_layout(info, pc) -> (names, types, legacy)

The particle fields of the files, in order, with their descriptor names and types. Legacy files (RAMSES before 2018, no partfiledescriptor.txt) hold x, y, z, vx, vy, vz, mass, id (Int32) and level (Int32), then with stars the birth time and the fields after it (metallicity), all Float64.

_quietly(f)

Internal. Run f with Mera's messages off, without touching the user's verbose setting. Used for internal steps, such as the camera set-up, that would otherwise print hints meant for someone computing physics. Safe to call from several threads at once.

_ramses_physics(info) -> OrderedDict

The physics of a RAMSES run from its namelist and makefile: a summary with the cross-code keys (_PHYSICS_KEYS), the makefile variables when makefile.txt holds them, and the full cleaned namelist. Registered as the physics capability of the RAMSES reader.

_resolve_unit(scale, unit) -> Float64

Look up unit's conversion factor, raising a USEFUL error when it is not a unit at all.

This was a bare getfield(scale, unit), so a typo surfaced as FieldError: type ScalesType003 has no field :pc_e3 — the symbol and nothing else. getvar's FIELD namespace has said "did you mean…" since the ASCII-alias work; the UNIT namespace should behave the same way, and did not.

_same_cells(a, b, cmin) -> Bool

Do two Mera objects hold the same cells? Mera keeps its tables sorted by level and position, so equal position columns answer it without building sets of hundreds of millions of cells; tables in another order are compared as sorted lists.

Do two Mera objects list the same cells in the same order (equal level and position columns)?

_slab_fractions(z_cam, csize, cam_w, lo, hi) -> Vector{Float64}

Internal. What fraction of each cell's VOLUME lies inside the camera-space slab [lo, hi].

The depth cut is a plane pair in camera coordinates, and a cell is an axis-aligned cube in world coordinates, so the cut crosses cubes at an angle. A bare centre test keeps a cell that is 10 percent inside exactly as fully as one that is entirely inside, which puts a half-cell step at each slab face. This returns the real fraction instead.

Cells that lie wholly inside or wholly outside are settled by arithmetic: the cube's half-extent along the line of sight is h·(|w₁|+|w₂|+|w₃|), so a centre further than that from both faces needs no sampling. Only the cells the faces actually cross are sub-sampled, on an nsub³ grid of offsets, the same way subregion(...; split=true) samples a sphere.

_subset_table(t, keep::AbstractVector{Bool})

Select the rows of t where keep is true, working on whole columns.

filter(p -> …, t) walks the table row by row, and StructArrays materialises a full NamedTuple for every row it visits — on a 12-column AREPO gas table that is ~80 allocations per particle, which dominated the axis-aligned particle projection (~90 alloc/particle, 4.2 GiB for 800k cells). Selecting each column by index instead is the same result for a constant number of allocations.

The row order, column types and table type are identical to filter's, so this is a drop-in replacement wherever the predicate can be written as a columnwise boolean.

_subset_table_keyed(t, keep::AbstractVector{Bool})

As _subset_table, but carrying the primary key over, and lazily: the columns are views into t, not copies.

t[findall(keep)] preserves the pkey, so the getvar masking paths — which used it — must too, or a masked call would hand back a differently-keyed table than an unmasked one. findall returns ascending indices and the table was already sorted by its key, so the subset is still sorted and this costs no re-sort.

Why views: a mask selects rows, but copying materialises EVERY column, while a getvar call reads two or three of them. That copy is essentially the whole cost of a masked getvar — measured at 83–120 % of it — and it grows with table width, which the caller cannot control. Views make the subset O(kept rows) in the columns actually read. Element access through a SubArray is slower than through a dense Vector, so the downstream arithmetic does pay a little, but the saving dominates: 1.5–4.5x faster end to end on 2M rows, and 206 MB → 8 MB at 20 columns / 50 % kept.

A uniform grid: the run never refines beyond levelmin, so Mera stores no :level column.

_unknown_var_error(dataobject, v)

Raised when getvar is asked for a name nothing can compute. Replaces a bare KeyError thrown from inside get_data, which named the symbol and nothing else — no indication of what was valid, and no hint that the intended name differs only by a Greek letter.

_write_sidecar(file, result, source; anonymize=false, note="", include_script=false, verbose=false,
               explain=true)

Write <file>.meta.json and return its path, or nothing if it could not be written (a warning says why). result is a dictionary describing the file's content.

add_field(name::Symbol, compute::Function; depends_on=Symbol[], datatypes=:hydro,
          unit::Symbol=:standard, description::String="")

Register a user-defined derived field that then behaves like any built-in getvar quantity — it works in getvar, and therefore in projection, profile, phase, etc.

• compute(dataobject, deps) — your kernel. deps is a Dict{Symbol,Vector} holding the arrays of depends_on (already centered / masked consistently). Return the field in code units; the requested unit (or this field's default unit) is applied for you.
• depends_on — the variables your kernel needs (built-in or other user fields). These are also recorded in the dependency graph so getvar_requirements (and the read-only-what-you-need logic in project/quicklook) cover your field.
• datatypes — a kind symbol or collection of them: :hydro, :gravity, :rt, :particle, :clump.
• unit — default unit symbol (must be a field of info.scale, or :standard).

add_field(:vmag2, (o, d) -> d[:vx].^2 .+ d[:vy].^2 .+ d[:vz].^2; depends_on=[:vx,:vy,:vz])
getvar(gas, :vmag2)
projection(gas, :vmag2)

See also delete_field, list_fields.

optional lists columns that change the result when they are loaded but are not needed, as described for getvar_optional; variants is a short text, shown in the field listings, that says how the result differs with and without them.

add_unit(name::Symbol, factor::Real)

Register a custom unit: a value in code units is multiplied by factor to convert to this unit. The name then works anywhere a unit symbol is accepted — in add_field (as the field's default unit), and in getvar(obj, var, name).

add_unit(:Msun_per_yr, 1.0)                      # e.g. for an SFR-like custom field
add_field(:mdot, (o,d)->d[:rho]; depends_on=[:rho], unit=:Msun_per_yr)

See also delete_unit, list_units.

age_from_aform(info::InfoType, aform; unit::Symbol=:Gyr)

Stellar age(s) for data whose formation time is stored as the scale factor a_form (AREPO / IllustrisTNG GFM_StellarFormationTime, exposed by Mera as :aform), rather than as the RAMSES super-conformal :birth used by stellar_age.

Wind particles — which TNG marks with a_form < 0 — return NaN, as does any non-finite entry.

unit accepts :Gyr (default), :Myr, :yr, :s.

stars = getparticles(info; families=[4])
ages  = age_from_aform(info, getvar(stars, :aform))          # [Gyr]

age_of_universe(info::InfoType; unit=:Gyr)

The age of the universe today (a = 1) for this run's cosmology — cosmic_time(info, 1).

A natural sanity check on a run's cosmological parameters, and one people otherwise compute by hand: a Planck-like ΛCDM gives ≈ 13.8 Gyr, so a value far from it means the parameters read from the header are not what you assumed.

Returns a Float64 in unit.

allocated_cpus() -> Int

How many CPUs this process is actually entitled to, rather than how many the machine has. Reads the batch scheduler's own variables first (SLURM_CPUS_PER_TASK, SLURM_JOB_CPUS_PER_NODE, PBS_NP, NSLOTS, OMP_NUM_THREADS), then falls back to Sys.CPU_THREADS.

On a shared node Sys.CPU_THREADS reports the whole machine, so using it to size a benchmark takes cores that belong to other jobs and produces numbers shaped by the contention you caused.

amr_header_of(info) -> (Dict, source::Symbol)

The amr-header fields needed for a restart: from the Mera object (:mera), else from the original simulation if it still exists (:simulation), else reconstructed from the info (:approximate: time steps unknown).

amroverview(dataobject::GravDataType; verbose::Bool=true)

Get the number of cells and CPUs per AMR level for gravity data. Returns an IndexedTable with columns level, cells, cellsize, and optionally cpus.

amroverview(dataobject::HydroDataType; verbose::Bool=true)
amroverview(dataobject::GravDataType; verbose::Bool=true) 
amroverview(dataobject::PartDataType; verbose::Bool=true)

Generate an overview table showing the distribution of cells/particles across AMR levels.

Arguments

• dataobject: AMR data object (HydroDataType, GravDataType, or PartDataType)
• verbose::Bool=true: Display progress information during calculation

Returns

• IndexedTable: Table with columns:
  • :level: AMR refinement level
  • :cells/:particles: Number of cells or particles at each level
  • :cellsize: Physical size of cells at each level (Hydro/Grav only)
  • :cpus: Number of CPU domains at each level (if CPU info available)

Examples

```julia

Basic AMR overview for hydro data

gas = gethydro(info, verbose=false) table = amroverview(gas)

Silent processing

table = amroverview(gas, verbose=false)

amroverview(dataobject::PartDataType; verbose::Bool=true)

Get the number of particles and CPUs per AMR level for particle data. Returns an IndexedTable with columns level, particles, and optionally cpus.

analyze_amr_structure(gas_data) → Dict

Perform comprehensive analysis of AMR data structure and refinement hierarchy.

Analyzes the adaptive mesh refinement structure to understand data complexity, refinement level distribution, and spatial extent. This information provides essential context for interpreting benchmark performance results.

Returns

Dictionary containing:

• total_cells: Total number of AMR cells
• data_size_gb: Memory footprint in gigabytes
• level_range: (minlevel, maxlevel) refinement range
• level_count: Number of distinct refinement levels
• level_stats: Per-level cell counts and percentages
• complexity_factor: Normalized complexity metric for performance scaling

Analysis Components

1. Cell Count Statistics: Total cells and memory usage
2. Refinement Level Distribution: Cell counts per refinement level
3. Spatial Extent Analysis: Coordinate ranges and effective resolution
4. Performance Metrics: Complexity weighting for benchmark interpretation

Example

gas_data = loaddata(300, "/path/to/ramses/", :hydro)
amr_stats = analyze_amr_structure(gas_data)
println("AMR complexity factor: $(amr_stats["complexity_factor"])")

angmom(data; center=[:bc], range_unit=:standard, radius=nothing, mask=nothing, unit=:standard,
       vcenter=nothing)
angmom([gas, stars, dm]; ...) -> Vector{Float64}

Net angular momentum L = Σ mᵢ rᵢ × vᵢ about center, as a 3-vector.

This is the vector behind direction=:faceon, direction=:edgeon and axis=:angmom. Those presets compute it from one object; calling angmom yourself lets you decide what defines the orientation, then hand the answer to any view:

L = angmom(gas; center=[:bc], radius=[10, :kpc])
projection(gas, :sd; axis=L, inclination=60, center=[:bc])   # same camera for every dataset

Several components at once

A galaxy's plane is set by gas, stars and dark matter together, and each of the three has its own axis. Pass them as a vector and the momenta are added:

L = angmom([gas, stars, dm]; center=[:bc], radius=[20, :kpc])

The objects must share a snapshot; they need not share a resolution or a particle count. The sum is over mass, so a component contributes in proportion to how much of it there is: in most discs the dark matter dominates the total even though the gas defines the visible plane. Decide which tracer you mean, rather than combining out of habit.

Arguments

• center, range_unit: the point L is measured about. Change this and the vector changes, because r is measured from it.

• radius: restrict the sum to a sphere about center, as [10, :kpc] or a bare number in range_unit (or in radius_unit, when the centre is expressed in a different unit). Without it the sum runs over everything the object holds, where the outer material has the longest lever arm and can tilt a "face-on galaxy" by the halo.

• mask: a boolean per row, so the sum can be restricted to, say, cold gas or one particle family (see getparticlemask). It combines with radius: cold gas inside 10 kpc.

• unit: unit for the returned components. The direction does not depend on it, and only the direction is used for orientation.

• vcenter: the velocity frame, as in getvar: :auto for the object's own bulk velocity, or a vector [vx, vy, vz] in the velocity unit you pass (e.g. vunit=:km_s).

Velocity frame

By default velocities are taken as they are stored, in the box frame, and no hint is printed about it. For an object streaming through the box this changes |L|, and tilts it, because r × v picks up r × v_bulk. Measuring about the object's own centre of mass largely cancels it (Σ mᵢ rᵢ = 0 there), which is what face_on does with center=:com. To remove the bulk motion outright, pass vcenter. With several components, give one explicit vector rather than :auto, so that all of them are measured in the same frame.

See also face_on, edge_on, center_of, projection.

average_mweighted(dataobject, var::Symbol; mask=[false]) -> Float64

Mass-weighted mean of var over the cells or particles in dataobject: $\langle q \rangle_m = \sum m_i q_i / \sum m_i$.

The mass weight is the natural one for intensive quantities — it follows the dense gas, whereas a volume weight follows the diffuse. Use wstat when you also want the median, spread or higher moments, or to weight by something other than mass.

average_mweighted(gas, :T)              # mass-weighted mean temperature, code units
average_mweighted(gas, :T, mask=hot)    # over a subset only

See also wstat, center_of_mass, bulk_velocity.

Metaprogramming-optimized mass-weighted average with template generation. Fuses mass and variable data access for optimal performance.

average_velocity(data, unit::Symbol=:standard; weighting=:mass, mask=[false]) -> (vx, vy, vz)

Another name for bulk_velocity, with the same arguments and keywords (weighting, mask).

baryon_fraction(; label="baryon_fraction")

Cross-datatype card: (gas + stars) / (gas + stars + dark matter), reading hydro + particles.

Returns a CombinedCard, to pass to report.

batch_convert_mera(input_dir::String, output_dir::String, 
                           start_output::Int, end_output::Int;
                           requested_threads::Int=Threads.nthreads(),
                           safety_margin::Float64=DEFAULT_SAFETY_MARGIN,
                           min_threads::Int=DEFAULT_MIN_THREADS,
                           max_threads::Int=DEFAULT_MAX_THREADS,
                           skip_existing::Bool=true,
                           show_confirmation::Bool=true,
                           compress=nothing) -> Dict

Main function for safe multithreaded batch conversion with active safety margin monitoring.

This function coordinates the entire conversion process including:

1. System resource validation and safety checks
2. File discovery and filtering by output number range
3. Thread count optimization based on system constraints
4. User confirmation and information display
5. Multithreaded conversion with real-time monitoring
6. Comprehensive results reporting and recommendations

Parameter Details

Required Parameters

• input_dir: Source directory containing old JLD2 files with version issues
• output_dir: Destination directory for converted files (created if doesn't exist)
• start_output: Starting output number for conversion range (inclusive)
• end_output: Ending output number for conversion range (inclusive)

Performance Tuning Parameters

• requested_threads: Desired number of conversion threads (default: all available)
• safety_margin: Memory usage threshold as decimal 0.0-1.0 (default: 0.8 = 80%)
• min_threads: Minimum thread count even under resource constraints (default: 1)
• max_threads: Maximum thread count regardless of system capacity (default: 64)

Behavior Control Parameters

• skip_existing: Skip files that already exist in output directory (default: true)
• show_confirmation: Display user confirmation prompt before starting (default: true)
• compress: Compression codec for the output files, matching savedata's API (default: nothing → LZ4FrameCompressor()). Pass false to write uncompressed files, or a specific codec instance (LZ4FrameCompressor(), ZlibCompressor(), Bzip2Compressor()) for finer control.
• sidecar: also write <file>.meta.json next to each converted file, as savedata does: the data types it holds, the provenance of the snapshot, the environment, and the file it was converted from (default: true). The global switch sidecar overrides it.

Safety Margin System

The safety_margin parameter is now actively used throughout the process:

Pre-Conversion Phase

• Validates current system memory usage
• Adjusts thread recommendations based on available memory within safety limits
• Warns user if current usage already exceeds margin

During Conversion Phase

• Monitors memory usage before each file load operation
• Checks memory after data loading (peak usage point)
• Triggers automatic garbage collection on violations
• Counts total violations for reporting

Post-Conversion Phase

• Reports final memory state and violation statistics
• Provides recommendations for future conversions based on violation patterns

Return Value

Returns comprehensive dictionary with conversion statistics:

• success: Number of files successfully converted
• failed: Number of files that failed conversion
• skipped: Number of files skipped (already existed)
• safety_violations: Number of times memory exceeded safety margin
• conversion_time: Total time spent in conversion (seconds)
• threads_used: Actual number of threads used
• final_memory_usage_percent: Memory usage percentage at completion

Error Handling Strategy

The function handles errors gracefully:

• Individual file failures don't stop the batch
• Out-of-memory errors receive specific guidance
• System resource violations trigger automatic recovery
• All errors are logged with specific context

Example Usage

Basic conversion with default safety settings: results = batchconvertmera("/data/old", "/data/new", 100, 200)

Conservative conversion for large files: results = batchconvertmera("/data/old", "/data/new", 100, 200; requestedthreads=4, safetymargin=0.9)

High-performance conversion with monitoring: results = batchconvertmera("/data/old", "/data/new", 100, 200; requestedthreads=16, safetymargin=0.7, skip_existing=false)

Split 1:nfiles into chunks of size ≤ chunk.

bell(sound = nothing)

Play a short notification sound — e.g. when a long calculation finishes.

Pick the sound in any of these ways (first match wins):

1. by name — bell(:chime) (a Symbol or String);
2. by number — bell(2) (the position shown by bell(:list), also a numeric string like bell("2"));
3. a configured default — [bell] sound = "gong" in ~/.mera.toml, the MERA_BELL_SOUND environment variable, or the legacy ~/bell.txt (see mera_config);
4. the built-in fallback — :strum (the original Mera sound).

19 sounds ship with Mera. List them with their numbers using bell(:list): arpeggio, bell, bird, bloop, bongo, chime, coin, coindrop, cosmic, ding, done, door, frog, gong, knock, oscillations, owl, strum, whistle.

You can also drop your own *.wav into the package's src/sounds/ folder and select it by its file name or number.

bell()            # the configured default, else :strum
bell(:gong)       # a deep blooming gong
bell("chime")     # a glassy three-note chime
bell(4)           # the 4th sound in bell(:list)
bell(:list)       # print the numbered catalogue of available sounds

Returns nothing.

benchmark_buffer_sizes(simulation_path::String, output_num::Int; 
                      test_sizes=[32768, 65536, 131072, 262144], verbose=true)

Benchmark different buffer sizes to find the optimal setting for this specific simulation.

Returns a Dict with "optimal_buffer", "optimal_time" and "all_results", or nothing when no buffer size could be timed.

benchmark_conversion(path, output; merapath, components, runs=3, verbose=true)

Measure what converting a snapshot to a MERA file costs, and how quickly that cost is repaid by faster re-reads.

Reads output from the RAMSES simulation in path, writes it out with savedata, then reads it back runs times. Reports the one-off conversion cost, the warm re-read time, and the break-even: the number of re-reads after which converting was worth it.

The break-even is the number to act on. Below it, read the RAMSES output directly. Above it, convert.

Keywords

• merapath: where to write the MERA file. Defaults to a temporary directory, which is left in place so you can inspect or delete it.
• components: which of :hydro, :gravity, :particles to include. Defaults to every component the snapshot actually has, so a run without gravity is fine.
• lmax, and any selection keyword (xrange, center, range_unit), forwarded to the readers. Without them the conversion reads the whole box, which on a large snapshot is slow and not comparable with a sweep that was capped.
• runs: how many times to read the MERA file back. The first is reported separately because it carries compilation; the warm figure is the minimum of the rest.
• verbose: print the report. The values are returned either way.

Returns

A NamedTuple with read_time, write_time, convert_total, first_read, warm_read, size_ramses, size_mera, size_ratio, breakeven and components.

# on your own simulation
benchmark_conversion("/path/to/simulation", 300)

# or on a public test simulation, to see what it reports
path = download_testdata("sedov3d_amr")
benchmark_conversion(path, 7)

See also: run_reading_benchmark, run_merafile_benchmark.

max_threads limits the threads used; 0 (the default) uses all available threads, at most the allocated CPUs.

benchmark_levels(path, output; levels, runs=3, components=nothing,
                 max_threads=0, merapath, outdir, stages)

Run benchmark_report once per refinement level and collect the results.

Reading cost, memory and the MERA-file advantage all depend strongly on how much of the AMR hierarchy you read, so a single level is one point on a curve. This measures the whole curve under identical conditions.

Every level runs in its own Julia process, so peak memory is measured cleanly rather than inherited from the previous level. A level that fails does not stop the sweep.

Keywords

• levels: which levels to measure. Defaults to 6:levelmax.
• runs: repeats per measurement inside each level.
• components: passed through; defaults to every component the snapshot has.
• max_threads: thread ceiling; defaults to the job's allocation.
• merapath, outdir: written per level into lmaxNN subdirectories.
• stages: passed through to benchmark_report.

Returns

A NamedTuple with levels, outdir, reports (the per-level report file paths that were produced) and failed.

using Mera
benchmark_levels("/path/to/simulation", 250;
                 merapath="/scratch/merafiles", outdir="/scratch/levels")

# a subset, and fewer repeats
benchmark_levels("/path/to/simulation", 250; levels=[6, 10, 13], runs=1)

See also: benchmark_report, collect_levels.

benchmark_mera_io(simulation_path::String, output_num::Int; 
                 test_sizes=["32KB", "64KB", "128KB", "256KB"])

Benchmark different I/O configurations to find optimal settings for your specific simulation.

This function tests various buffer sizes with your actual data to determine which configuration gives the best performance on your system.

Arguments

• simulation_path: Path to your RAMSES simulation directory
• output_num: Output number to test with
• test_sizes: Array of buffer sizes to test (as strings)

Returns

• Dictionary with benchmark results and recommended optimal settings

Example

# Standard benchmark
results = benchmark_mera_io("/path/to/simulation", 300)

# Custom buffer sizes to test
results = benchmark_mera_io("/path/to/simulation", 300, 
                           test_sizes=["64KB", "128KB", "256KB", "512KB"])

# Access results
optimal_buffer = results["optimal_buffer_size"]
performance_gain = results["performance_improvement"]

What it does

1. Tests each buffer size with your actual simulation data
2. Measures getinfo() and gethydro() performance
3. Identifies the optimal buffer size for your system
4. Automatically applies the best settings
5. Returns detailed performance comparison

benchmark_multi_variable_projection(gas_data, n_threads::Int, n_runs::Int=10) → Dict

Execute multi-variable projection benchmark testing simultaneous computation of 10 hydro variables.

Performs comprehensive timing analysis of multi-variable projections computing 10 simultaneous hydro variables including velocity components, velocity dispersion, and cylindrical coordinates. This benchmark tests the threading efficiency for complex projection scenarios typical in astrophysical analysis workflows.

Variable Set (10 Variables)

• Velocity: :v (3D velocity field analysis)
• Velocity Dispersion: σ:, σx, :σy, :σz (turbulence and kinematic structure)
• Cylindrical Coordinates: :vrcylinder, :vϕcylinder, σrcylinder, σϕcylinder (disk dynamics)
• Thermal Soundspeed: :cs

Methodology

• Projection Type: Simultaneous multi-variable calculation (realistic workflow)
• Threading: Shared memory parallelization across variables and spatial bins
• Statistics: several repetitions with comprehensive error analysis

Performance Characteristics

Multi-variable projections exhibit different scaling behavior than single-variable:

• Memory Scaling: higher memory usage due to multiple output arrays
• Threading Efficiency: May differ due to increased memory bandwidth requirements
• Computational Complexity: Higher arithmetic intensity but better cache reuse

Arguments

• gas_data: HydroDataType object containing AMR hydro simulation data
• n_threads::Int: Number of threads for parallel computation
• n_runs::Int=10: Statistical repetitions for robust measurement

Returns

Dictionary with detailed performance analysis:

• mean_time, std_time: Multi-variable projection timing statistics
• mean_memory: Peak memory usage
• success_rate: Reliability metric (target: >95% for complex operations)
• coefficient_variation: Precision indicator for multi-variable timing

Performance Comparison

Compare with single-variable results to understand:

• Threading efficiency differences between simple/complex projections
• Memory bandwidth limitations in multi-variable scenarios
• Optimal thread counts for different projection complexities

Example

# Multi-variable benchmark for threading analysis
result = benchmark_multi_variable_projection(gas_data, 8, 10)

# Compare with single-variable efficiency
single_result = benchmark_single_variable_projection(gas_data, 8, 10)
efficiency_ratio = single_result["mean_time"] / result["mean_time"] * 10
println("Multi-variable efficiency: $(efficiency_ratio) variables per single-variable time")

benchmark_projection_hydro(gas_data, thread_counts::Vector{Int}, n_runs::Int=10, output_file::String="") → Dict

Execute comprehensive AMR hydro projection benchmark with robust statistical analysis.

This function serves as the main coordinator for hydro projection performance testing. It performs AMR structure analysis, data quality validation, executes both single-variable and multi-variable projection benchmarks across specified thread counts, and exports results in multiple formats with comprehensive statistical analysis.

Benchmark Methodology

• Single-Variable Test: Surface density projection (:sd → Msun/pc²)
• Multi-Variable Test: 10 simultaneous variable projections: vars = [:v, :σ, :σx, :σy, :σz, :vrcylinder, :vϕcylinder, :σrcylinder, :σϕcylinder, :cs]
• Statistical Robustness: several repetitions per configuration with coefficient of variation
• Quality Control: Success rate monitoring (>80% threshold for reliable data)
• Memory Profiling: Peak memory usage and garbage collection analysis

Threading Analysis

Evaluates performance across thread counts with derived metrics:

• Speedup: Performance improvement vs single-threaded execution
• Efficiency: Speedup per thread (percentage of ideal scaling)
• Memory Scaling: Memory usage patterns across thread configurations

Output Files Generated

• {output_file}.csv: Structured data for spreadsheet analysis and plotting
• {output_file}.json: Machine-readable structured data for programmatic access
• {output_file}_summary.txt: Human-readable performance report with insights

Arguments

• gas_data: HydroDataType object from loaddata() or gethydrodata()
• thread_counts::Vector{Int}: Thread counts to benchmark [1, 2, 4, 8, 16, ...]
• n_runs::Int=10: Statistical repetitions per configuration (10 for robust analysis)
• output_file::String="": Output filename base (auto-generated timestamp if empty)

Returns

Dictionary containing complete benchmark results with keys:

• n_threads, test_type, mean_time, std_time, speedup, efficiency
• mean_memory, success_rate, min_time, max_time, n_runs

Example Usage

# Load RAMSES hydro data
gas_data = loaddata(300, "/path/to/ramses/output/", :hydro)

# Run comprehensive benchmark (single + multi-variable)
results = benchmark_projection_hydro(gas_data, [1, 2, 4, 8, 16], 10, "performance_test")

# Results saved as:
# - performance_test.csv (for plotting with plot_results.jl)
# - performance_test.json (for programmatic analysis)  
# - performance_test_summary.txt (human-readable report)

Performance Insights

The benchmark automatically analyzes threading efficiency and provides guidance:

• Identifies optimal thread counts for your system and data size
• Detects threading bottlenecks and memory constraints
• Quantifies single vs multi-variable projection performance differences
• Provides statistical confidence intervals for all measurements

Integration Workflow

1. Data Loading: Use Mera's loaddata() for your RAMSES simulation
2. Benchmarking: Execute this function with desired thread counts
3. Visualization: Use plot_results.jl to create performance dashboards
4. Analysis: Review summary.txt for optimization recommendations

benchmark_report(path, output; merapath, components=[:hydro], lmax=missing,
                 runs=3, nfiles=64, outdir=homedir(), force=false, stages=:all)

Run Mera's performance benchmarks on one snapshot and print a report that can be pasted straight into an issue, a paper, or the documentation.

Measures, in order:

1. the snapshot itself, machine, filesystem, ncpu, file count, size on disk
2. storage, IOPS and open/close cost across thread counts (run_benchmark)
3. reading the RAMSES output, per component with GC share (run_reading_benchmark)
4. conversion, what savedata costs and after how many re-reads it pays back (benchmark_conversion)

A high ncpu is the interesting case: the per-file parsing that a MERA file avoids is exactly what a snapshot with thousands of files makes expensive, so that is where the format advantage is largest.

Keywords

• merapath: where to write the MERA file in step 4. Give it a real filesystem, not a small /tmp.
• components: which components to convert. Defaults to every component the snapshot has, so the comparison covers the whole dataset. Pass [:hydro] on a snapshot too large to hold all components in memory at once.
• lmax: cap the refinement level when reading. The honest way to benchmark a box too large to read whole.
• runs: repetitions per timed measurement.
• nfiles: how many files the throughput sweep samples. It reads file contents once per thread level per run, so this is deliberately bounded.
• outdir: where the report and the raw JSON/CSV go.
• max_threads: thread budget for every stage. When the :sweep stage runs and this is left at its default, the reading and conversion stages use the sweet spot the sweep found rather than the full budget, since that is the configuration the report goes on to recommend. Setting it explicitly pins every stage to your number instead. Defaults to min(Threads.nthreads(), allocated_cpus()), so on a batch node it follows the scheduler's allocation rather than the machine's core count. Set it lower to leave headroom on a shared node.
• force: run a full read even when it looks too large for the machine's memory.
• stages: :all, or any of :storage, :reading, :conversion, :sweep to run a subset. :sweep is never part of :all: it runs one full read per thread count per repetition, so it must be asked for by name, stages=[:storage, :sweep].

Returns

A NamedTuple with info, nfiles_total, bytes, filesystem, storage, reading, conversion and reportfile. Stages not run are nothing.

using Mera
benchmark_report("/data/sim/MilkyWay", 250; merapath="/data/merafiles")

# a box too large to read whole
benchmark_report("/data/sim/MilkyWay", 250; lmax=11, merapath="/data/merafiles")

benchmark_single_variable_projection(gas_data, n_threads::Int, n_runs::Int=10) → Dict

Execute single-variable surface density projection benchmark with robust statistical analysis.

Performs high-precision timing measurements of surface density (:sd → Msun/pc²) projections using the specified thread count. Implements comprehensive statistical analysis including warm-up runs, outlier detection, and memory profiling for reliable performance data.

Methodology

• Variable: Surface density (:sd) - most common astronomical observable
• Unit: Msun/pc² (solar masses per square parsec) - standard surface density unit
• Resolution: 128×128 projection grid (balanced performance/accuracy)
• Statistics: several repetitions with coefficient of variation analysis
• Quality Control: Success rate monitoring and outlier detection

Performance Monitoring

• Timing: Microsecond-precision measurement with warm-up runs
• Memory: Peak memory usage tracking during projection execution
• GC Analysis: Garbage collection overhead monitoring
• Progress: Real-time statistics with running averages and CV calculation

Arguments

• gas_data: HydroDataType object containing AMR simulation data
• n_threads::Int: Number of threads for projection calculation
• n_runs::Int=10: Statistical repetitions (10 for robust analysis)

Returns

Dictionary with comprehensive performance metrics:

• mean_time, std_time, min_time, max_time: Timing statistics (seconds)
• coefficient_variation: Measurement precision indicator (target: <5%)
• mean_memory: Average peak memory usage (GiB)
• mean_gc_time: Average garbage collection overhead (seconds)
• success_rate: Fraction of successful runs (1.0 = 100% success)
• n_runs: Number of statistical repetitions performed

Example

# Single-threaded surface density benchmark
result = benchmark_single_variable_projection(gas_data, 1, 10)
println("Mean execution time: $(result["mean_time"]) seconds")
println("Measurement precision: $(result["coefficient_variation"]*100)%")

benchmarkplot(r; size=(1000, 760)) -> Makie.Figure

Turn a benchmark_report result into one figure: the reading thread sweep, the read-time comparison, the memory each path churns through, and storage IOPS against thread count. Panels for stages that were not run are omitted.

Needs a Makie backend, so using CairoMakie first. The Figure is returned; save it with Makie.save("bench.png", fig). benchmark_report saves one automatically when a backend is already loaded.

using Mera, CairoMakie
r = benchmark_report("/data/sim", 250; stages=[:storage, :sweep, :conversion])
Makie.save("bench.png", benchmarkplot(r))

build_camera_basis(los, up=nothing; roll=0.0) -> (right, up, w)

Construct a right-handed orthonormal camera basis from a line-of-sight vector los (the viewing direction) and an optional up hint.

Returns three unit 3-vectors (right, up, w) where w = los/‖los‖ is the viewing direction, and right, up span the image plane (image x = right, image y = up). The basis is right-handed with right × up = w.

If up is nothing, or (anti)parallel to los, the camera uses world +z as its up hint (falling back to +y when los is itself the z axis). That is deterministic, and it makes a view down a box axis reproduce the matching direction= preset: los=[0,0,1] gives the same image orientation as direction=:z.

roll (radians) rotates the image plane about the line of sight — i.e. it sets the orientation of the image on the "sky" (the astronomical position angle / camera roll). It leaves w unchanged and rotates (right, up) together, so it composes with any way of choosing los.

Convention check: los=[0,0,1] ⇒ right=[1,0,0], up=[0,1,0], matching the axis-aligned direction=:z mapping (image x→sim x, image y→sim y), with or without an explicit up=[0,1,0].

bulk_velocity(data, unit::Symbol=:standard; weighting=:mass, mask=[false]) -> (vx, vy, vz)

Return the mean velocity of the cells, particles or clumps in data, weighted by mass by default.

This is the velocity of the frame that getvar(...; vcenter=:auto) subtracts. average_velocity is another name for it.

Arguments

• data: any Mera object with masses and velocities, or a selection.
• unit::Symbol = :standard: the unit of the result, e.g. :km_s; :standard means code units. It can also be given as the keyword unit.

Keywords

• weighting::Symbol = :mass: :mass, :volume (hydro only) or :no for a plain mean. Any other value raises an error.
• mask: a Bool vector with one entry per row; only rows marked true count.

Examples

julia> bulk_velocity(gas, :km_s)

julia> v0 = bulk_velocity(stars, :km_s; mask=getvar(stars, :r_sphere, :kpc; center=[:bc]) .< 10);

julia> getvar(stars, :vϕ_cylinder, :km_s; center=[:bc], vcenter=v0, vunit=:km_s)

See also center_of_mass, getvar.

Metaprogramming-optimized bulk velocity with compile-time weighting dispatch. Generates specialized code for each weighting scheme at compile time.

bundle(dir="."; title=nothing, description=nothing, creators=nothing, license=nothing,
       keywords=String[], simulation=nothing, recursive=true, verify=true, verbose=true) -> String

Describe a finished analysis folder in one record, ready to publish, for example on Zenodo. bundle reads the sidecars in the folder and writes three files into it:

• ro-crate-metadata.json: an RO-Crate that lists every file with its size, type and SHA-256, and for each file written by Mera what made it: the Mera version, the script and the snapshot, from its sidecar;
• software.bib: the BibTeX from citation;
• simulation.json: the simulationrecord, when simulation is given.

Nothing is copied, so the folder needs no extra disk space. Running it again replaces the three files.

Arguments

• dir::String = ".": the analysis folder.

Keywords

• title, description, creators, license, keywords: who made the analysis and under which license, as for datacite: creators as "Family, Given" or (name=…, orcid=…, affiliation=…), license as an SPDX identifier such as "CC-BY-4.0". Missing ones are read from an analysis.toml in the folder (the same fields as simulation.toml, see meraproject); the title falls back to the folder name.
• simulation = nothing: the simulation the analysis used: a folder, an InfoType or a SimulationRecord. Its record is written to simulation.json.
• recursive::Bool = true: include subfolders. Hidden files and folders are left out.
• verify::Bool = true: check each file against the SHA-256 in its sidecar, and warn about files that changed after they were written.
• verbose::Bool = true: print a summary.

Returns

The path of ro-crate-metadata.json.

Examples

bundle("galaxy_paper"; simulation="/data/mw_L10",
       creators=["Behrendt, Manuel"], license="CC-BY-4.0")

See also meraproject, sidecaroverview, citation, datacite.

calculate_safe_thread_count(requested_threads::Int; 
                           safety_margin::Float64=DEFAULT_SAFETY_MARGIN,
                           min_threads::Int=DEFAULT_MIN_THREADS,
                           max_threads::Int=DEFAULT_MAX_THREADS) -> Int

Calculate the maximum safe number of threads based on system constraints and current state. This function now actively uses the safety_margin to provide intelligent recommendations.

Algorithm

1. Check current memory usage against safety margin
2. Calculate available memory within safety limits
3. Apply memory-based adjustment factor if resources are constrained
4. Respect system core count and user-defined limits
5. Ensure result stays within min/max bounds

Parameters

• requested_threads: User's desired thread count
• safety_margin: Maximum memory usage threshold (0.0-1.0)
• min_threads: Minimum allowable threads (safety floor)
• max_threads: Maximum allowable threads (performance ceiling)

Returns

Integer thread count that balances performance with system safety

calibrate!(output; path=".", budget=200_000) -> CostModel

Actively calibrate the cost model for this machine/output by running a tiny report (one coarse level + small projection/phase/profile/scalar) and learning the timing coefficients. ~0.5–3 s, once. (The model also self-calibrates passively after every real report.)

verbose=true prints the report runs and the calibrated correction.

capabilities(info::InfoType) -> Vector{Symbol}

The entry points the reader that produced info provides, e.g. [:info, :hydro, :particles] for PLUTO data. See supports.

cell_shift(level::Int, value::Real, cell::Bool)

Legacy compatibility function for shell region functions.

This function provides backward compatibility with older shell region code that used cellshift calls. The newer geometry helper functions (getradius*, getheight_*) handle cell vs point-based selection internally, so this function simply returns the input value unchanged.

Arguments

• level::Int: AMR level (unused in current implementation)
• value::Real: The input value to be returned
• cell::Bool: Cell vs point selection flag (unused in current implementation)

Returns

• Real: The input value unchanged

Note

This function exists for compatibility with legacy shell region functions. New code should use the geometry helper functions directly.

center_of(data; method=:com, unit=:standard, mask=[false])

Find the centre of an object and return [x, y, z] in unit.

• method=:com — mass-weighted centre of mass (delegates to center_of_mass).
• method=:densest (:peak) — position of the densest hydro cell (needs hydro data).

mask (a Bool/BitArray over the cells/particles) restricts the calculation.

center_of_mass(data, unit::Symbol=:standard; mask=[false], periodic=false) -> (x, y, z)
center_of_mass([gas, part], unit::Symbol=:standard; mask=[[false], [false]]) -> (x, y, z)

Return the mass-weighted mean position of the cells, particles or clumps in data, measured from the box corner. com is a short name for it.

Given a vector of objects, e.g. gas and stars, it returns their joint centre of mass.

Arguments

• data: any Mera object with masses, or a vector of hydro and particle objects.
• unit::Symbol = :standard: the unit of the result, e.g. :kpc; :standard means code length. It can also be given as the keyword unit.

Keywords

• mask: a Bool vector with one entry per row; only rows marked true count. For a vector of objects, one mask per object.
• periodic = false: average on a periodic box, with the circular mean (Bai & Breen 2008), so a structure that crosses a face of the box is not averaged to the middle of the box. true for all three axes, or per axis as (x=true, y=true, z=false) or a 3-tuple. getinfo reports whether a run is periodic (info.boundaries). Single objects only.

Examples

julia> center_of_mass(gas, :kpc)

julia> center_of_mass([gas, part], :kpc)              # gas and particles together

julia> center_of_mass(clump, :kpc; periodic=true)     # an object on the box boundary

See also bulk_velocity, msum.

Metaprogramming-optimized joint center of mass for multiple datasets. Uses template-based loop generation with compile-time optimization.

Metaprogramming-optimized center of mass with fused mass-weighted operations. Uses compile-time template generation for maximum performance.

check_available_files(input_dir::String) -> Dict

Analyze directory contents and provide comprehensive file information. Used for validation and user feedback about available data.

Returns Dictionary with keys:

• "files": Vector of valid JLD2 filenames
• "range": Tuple of (minoutput, maxoutput) or nothing if no files
• "gaps": Vector of missing output numbers within the range
• "total": Total count of valid files

Gap Detection Algorithm

Identifies missing files in the sequence, which can indicate:

• Incomplete simulation runs
• File transfer errors
• Storage problems

This helps users identify data integrity issues before conversion

check_safety_margin_violation(safety_margin::Float64) -> Bool

Determine if current system memory usage exceeds the configured safety margin. This is the core safety check function that prevents system overload.

Arguments

• safety_margin: Decimal value (0.0-1.0) representing maximum allowed memory usage

Returns

• true if memory usage exceeds safety margin (dangerous situation)
• false if memory usage is within safe limits

Example

• safety_margin = 0.8 means allow up to 80% memory usage
• If current usage is 85%, this returns true (violation)

Get the existing simulation snapshots in a given folder

• returns field outputs with Array{Int,1} containing the output-numbers of the existing simulations
• returns field miss with Array{Int,1} containing the output-numbers of empty simulation folders
• returns field path as String

checkoutputs(path::String="./"; verbose::Bool=true)
return CheckOutputNumberType

Examples

# Example 1:
# look in current folder
julia> N = checkoutputs();
julia> N.outputs
julia> N.miss
julia> N.path

# Example 2:
# look in given path
# without any keyword
julia>N = checkoutputs("simulation001");

checksimulations(path="."; verbose=true, filternames=String[]) -> Dict

Scan path for simulation folders and report which outputs each one holds.

Where checkoutputs inspects a single simulation, this walks a directory of them — the view you want when a project directory holds many runs and you need to know what is on disk before loading anything. filternames restricts the scan to named subfolders.

checksimulations("/data/simulations")               # every run under the folder
checksimulations("/data", filternames=["mw_L10"])   # just one

See also checkoutputs, storageoverview.

citation(source=nothing; file=nothing) -> Text

The BibTeX to cite for a result: Mera at its exact version, and the papers of the simulation code and of the physics modules the run used (for RAMSES: the code paper, and the MHD and RT papers when the run has them).

Arguments

• source: nothing for Mera alone; a data object, projection, profile or InfoType; a SimulationRecord; or a saved file with a sidecar ("fig3.png"), which gives the Mera version that wrote it.

Keywords

• file::String = nothing: also write the BibTeX to this file, e.g. "mera.bib".

Returns

The BibTeX as Text, which prints as plain text; string(citation()) gives the String.

Examples

citation()                         # Mera, at the version that runs
citation(gas)                      # also RAMSES, and RAMSES-RT for an RT run
citation("fig3.png")               # the Mera version recorded in fig3.png.meta.json
citation(gas; file="software.bib")

The DOI is Mera's Zenodo concept DOI, which covers all versions; the version field names the one you used, and the Zenodo page lists the DOI of each version.

See also provenance, readsidecar, datacite.

clear_mera_cache!()

Empty the cache of simulation metadata that Mera keeps between getinfo calls, and report how many entries were dropped.

Useful when a simulation folder changed on disk during a session and you want the next getinfo to re-read it rather than reuse what it saw earlier. See show_mera_cache_stats to inspect the cache first.

Returns nothing.

clump_mass_fraction(; label="clump_mass_fraction")

Cross-datatype card: total clump mass / total gas mass, reading clumps + hydro.

Returns a CombinedCard, to pass to report.

clump_massfunction(cat::ClumpCatalog; nbins=20, scale=:log, cumulative=false)
    -> (mass, N)

The clump mass function. Differential (default): histogram of clump masses into nbins (scale=:log ⇒ log-spaced bins) — returns (bin_centres, counts). Cumulative (cumulative=true): returns (sorted_mass, N(≥M)).

clump_recovery(found_labels, true_labels; background=0) -> NamedTuple

Compare a found clump segmentation against a known ground truth, label-for-label over the same points. Returns (; ari, completeness, purity, merit, n_found, n_true, n_points):

• ari — Adjusted Rand Index (Hubert & Arabie 1985): 1 = perfect agreement, 0 = chance-level, can be slightly negative. The standard clustering-quality metric.
• completeness — mass/count-weighted fraction of each true clump captured by its best-matching found clump, averaged over true clumps (1 = every true clump is fully contained in one found clump).
• purity — the same from the found side (1 = no found clump mixes two true clumps).
• merit — mean bijective merit Σ max_i n_ij²/(|found_i|·|true_j|) (Srisawat+2013 "SUSSING"), rewarding one-to-one matches.

background (default 0) is the label for unassigned points; those points are excluded from completeness/purity/merit (but kept in ari, which scores the full partition). Both label vectors must be the same length and indexed by the same points.

m = clump_recovery(found_labels, true_labels)
m.ari            # ≈ 1 when the finder recovers the input clumps

clumpfind(obj::HydroPartType, field=:rho; threshold, linking_length,
          threshold_unit=:standard, pos_unit=:kpc, mass_unit=:Msol,
          min_members=1, mask=[false], boundedness=false, bound_only=false,
          egrav=:approx, direct_max=2000, deblend=false, peak_min_distance=2·linking_length,
          substructure=false, sub_min_members=min_members) -> ClumpCatalog

Convenience form of the AbstractFinder method: builds a ThresholdFoF from field/threshold/linking_length and forwards every other keyword. Existing scripts keep working unchanged; see the finder method above for the full keyword reference.

gas = gethydro(getinfo(output, path))
cat = clumpfind(gas, :rho; threshold=1e2, threshold_unit=:nH, linking_length=0.2)   # 0.2 kpc
bound = clumpfind(gas, :rho; threshold=1e2, threshold_unit=:nH, linking_length=0.2,
                  boundedness=true, bound_only=true, deblend=true)

clumpfind(components::AbstractVector; linking_length, pos_unit=:kpc, mass_unit=:Msol,
          min_members=1, boundedness=false, bound_only=false, egrav=:approx,
          direct_max=2000, softening=0.0, iterative_unbinding=false) -> ClumpCatalog

Multi-field structure finder: pre-select points from several components and link them with a single friends-of-friends pass, so over-densities in gas + stars + dark matter are found together. Each component is a NamedTuple (obj, field, threshold, name [, threshold_unit, mask]); its points with field ≥ threshold (and optional mask(obj)) join the common cloud tagged by name. Per clump the catalog reports total mass, com, radius, member count, and a components breakdown (name=(mass=…, n=…), …) per source.

boundedness=true adds the combined-cloud energetics (e_kin, e_therm, e_mag, e_grav, alpha_vir, bound) computed over all species together (each contributing its own mass and velocity; gas also its thermal/magnetic support), so the bound test uses the full self-gravity of gas + stars + DM while the components breakdown remains the per-species mass budget. egrav, direct_max, softening, iterative_unbinding and bound_only behave as in the single-object form.

cat = clumpfind([
    (obj=gas,   field=:rho,  threshold=1e2, threshold_unit=:nH, name=:gas),
    (obj=parts, field=:mass, threshold=0.0, name=:stars, mask = o->getvar(o,:birth).>0),
    (obj=parts, field=:mass, threshold=0.0, name=:dm,    mask = o->getvar(o,:birth).<=0),
]; linking_length=0.5, boundedness=true)
cat[1].components.gas.mass        # gas mass in the most massive structure
cat[1].bound                      # self-bound across all three species?

clumpfind(map::DataMapsType, field; threshold, connectivity=8, min_pixels=1) -> ClumpCatalog

2D connected-component finder on a projection map. Pixels with map[field] ≥ threshold are grouped by connectivity (4 or 8). Per region it returns pixel count n_members, mass (area-integral Σ value · pixel_area, exact for a surface-density map), com (value-weighted centroid), peak & peak_pos, and radius — positions in the map's extent units.

clumpfind(obj::HydroPartType, finder::AbstractFinder; pos_unit=:kpc, mass_unit=:Msol,
          min_members=1, mask=[false], boundedness=false, bound_only=false,
          egrav=:approx, direct_max=2000, softening=0.0, iterative_unbinding=false,
          deblend=false, peak_min_distance=…, substructure=false, sub_min_members=min_members,
          tidal=false, gravity=nothing, tidal_sample=3.0, hierarchy=false,
          max_threads=Threads.nthreads()) -> ClumpCatalog

3D structure finder driven by any AbstractFinder finder value (one of the seven: ThresholdFoF, DensityWatershed, Dendrogram, GraphSegFinder, HDBSCANFinder, PhaseSpaceFoF, PersistenceFinder; it carries the field/threshold/linking-length and selects the algorithm). Per clump it returns member count, mass, centre of mass com, peak field value and peak_pos, and radius (max member distance from the COM) — positions in pos_unit, mass in mass_unit.

• boundedness=true adds per-clump energetics (cgs): e_kin (COM-frame kinetic), e_therm (thermal, gas), e_grav (binding energy), alpha_vir = 2·e_kin/|e_grav|, and a bound flag (e_kin + e_therm < |e_grav|). bound_only=true keeps only self-bound clumps. The potential is set by egrav: :approx ⇒ 3/5·GM²/R (biased, fast); :direct ⇒ exact pairwise sum up to direct_max members; :tree ⇒ Barnes–Hut octree, O(N log N), accurate at any N (Barnes & Hut 1986). softening (in pos_unit) softens the kernel 1/√(r²+ε²).
• iterative_unbinding=true runs SUBFIND-style unbinding (Springel+2001): members with positive total energy in the bulk-velocity frame are stripped iteratively until convergence, so each clump's reported membership/mass is its self-bound subset. Implies the boundedness analysis.
• deblend=true/:peak splits merged clumps at their density peaks (members assigned to the nearest peak); deblend=:watershed instead assigns by density-descending basins. Peaks are separated by peak_min_distance (in pos_unit). (Equivalent to using a DensityWatershed finder.)
• substructure=true builds a bound-substructure tree: each top-level clump is split into density basins (watershed) and the gravitationally self-bound ones (≥ sub_min_members) are attached as nested subclumps (with n_subclumps). Implies the boundedness analysis.
• tidal (needs substructure=true) truncates each sub-clump at its tidal/Hill radius in the host: tidal=true uses the analytic Jacobi radius, tidal=:tensor the least-squares tidal-tensor radius from a gravity object (getgravity); tidal_sample scales the host sampling region.
• hierarchy=true (for a Dendrogram finder) also returns the multi-scale merger tree in cat.tree (a StructureTree).
• max_threads caps the threads used for the per-clump analysis (deterministic regardless of count).
• validators — a composable chain of value-typed acceptance criteria (MinMembers, Bound, VirialBelow, MassAbove, Custom) that a clump must all satisfy (an AND). It is a clearer alternative to the boundedness kwargs: a Bound in the chain configures the boundedness pass (potential, iterative unbinding) and keeps only self-bound clumps; the predicate validators filter the catalog. A non-empty validators overrides boundedness/bound_only/min_members/egrav/iterative_unbinding. Membership-mutating validators run during the analysis, predicates after — independent of the order listed.

gas = gethydro(getinfo(output, path))
cat = clumpfind(gas, ThresholdFoF(:rho; threshold=1e2, threshold_unit=:nH, linking_length=0.2))
# contrast-controlled watershed + tree-gravity boundedness with iterative unbinding:
cores = clumpfind(gas, DensityWatershed(:rho; threshold=1e2, threshold_unit=:nH,
                                        linking_length=0.4, persistence=0.3);
                  boundedness=true, egrav=:tree, iterative_unbinding=true)
# the same, written as a validator chain, plus virial + size cuts:
cores = clumpfind(gas, DensityWatershed(:rho; threshold=1e2, threshold_unit=:nH, linking_length=0.4);
                  validators=[MinMembers(20), Bound(:tree; iterative=true), VirialBelow(2.0)])

backend chooses the neighbour search, e.g. backend=MortonGrid; the default is CellLinkedList. All backends find the same pairs and differ only in speed.

clumpfind_benchmarks(gas; threshold, threshold_unit=:nH, linking_length=0.5, reps=5)

Benchmark the structure finders on a loaded hydro object gas: each finder's wall time + clump count, the boundedness potentials (:approx/:direct/:tree), and a thread-scaling table for the per-clump stats path. Prints a report; returns a NamedTuple of the timings.

clumping(dataobject; weight=:volume, grid=nothing, grid_unit=:standard,
         mask=[false], verbose=true) -> NamedTuple

The clumping factor $C = \langle n^2 \rangle / \langle n \rangle^2$ of the gas density.

C = 1 is a uniform medium; larger means the mass is concentrated into a smaller fraction of the volume. It is the usual way to quantify how much unresolved structure a simulation has, and the usual way to get burned:

Cell-by-cell (the default) weights each cell by weight:

• :volume — the volume-weighted mean density, the convention C is normally defined with.
• :mass — mass-weighted. This answers a different question — how clumpy is the gas the mass is actually in — and it does not simply give a larger number. For a two-phase medium whose mass sits overwhelmingly in the dense phase the weighted distribution is narrow, so C → 1: equal volumes at n = 1 and 99 give C = 1.96 volume-weighted but 1.01 mass-weighted. Neither is the other's approximation.
• :none — a plain average over cells, which weights a tiny cell the same as a huge one and is almost never what you want on an unstructured mesh.

On a fixed grid (grid = L) the cells are first deposited onto a cube of side L, and C is computed over those equal-volume bins — the form that compares to published values:

clumping(gas)                                    # cell-by-cell, volume-weighted
clumping(gas; grid=13.7, grid_unit=:kpc)         # fixed-grid, comparable to papers
clumping(gas; mask=getvar(gas,:cellsize,:pc) .< 500)   # resolution-restricted

Returns (C, mean_n, mean_n2, n_cells, weight, grid, grid_cells, empty_fraction) with mean_n in cm⁻³.

See also getvar for :cellsize, and the Zoom Simulations page.

max_bins = 5e7 is a guard against a grid that would not fit in memory: a request for more bins raises an error that names the likely cause (often a grid_unit mix-up).

clumpplot(cat::ClumpCatalog; background=nothing, sizeby=:mass, colormap=:viridis,
          max_markersize=28, kwargs...) -> Makie.Figure

Plot a ClumpCatalog: each clump's centre of mass as a marker, sized by sizeby (:mass, :radius, or :n_members) and coloured by log₁₀ mass. Pass background = a projection result (e.g. the gas surface density) to overlay the clumps on it. Needs a Makie backend loaded (using CairoMakie).

cat = clumpfind(gas, :rho; threshold=1e2, threshold_unit=:nH, linking_length=0.5)
using CairoMakie
bg  = projection(gas, :sd, :Msol_pc2; center=[:bc])
fig = clumpplot(cat; background=bg)

clumptable(cat::ClumpCatalog) -> NamedTuple

A columnar view of the catalog: a NamedTuple of equal-length vectors — id, n_members, mass, com_x, com_y(, com_z), radius, and (when present) peak, the boundedness columns (e_kin, e_therm, e_grav, alpha_vir, bound), and per-component masses/counts (mass_gas, n_gas, …). Drop straight into DataFrame(clumptable(cat)) or CSV.write.

collect_levels(dir) -> Vector

Read every MERA_BENCHMARK.txt under dir, print one row per refinement level, and write levels_summary.csv beside them.

Directories named superseded are skipped. They hold runs kept for the record but known to be unsound, and folding those into a summary is how a bad number gets published.

using Mera
benchmark_levels("/path/to/sim", 250; outdir="/scratch/levels")
collect_levels("/scratch/levels")

See also: benchmark_levels, benchmark_report.

com(data, unit::Symbol=:standard; kwargs...) -> (x, y, z)

A short name for center_of_mass, with the same arguments and keywords (mask, periodic).

comoving_to_proper_density(info, density_comoving) -> Float64

Convert a comoving mass density to proper density (proper = comoving / aexp^3). Identity for non-cosmological runs.

comoving_to_proper_length(info, length_comoving) -> Float64

Convert a comoving length to the proper length at the snapshot's aexp (proper = comoving * aexp). Identity for non-cosmological runs.

compareramses(output, path_a, path_b; leaves_only=false)

Compare two RAMSES outputs with the same output number, written with any numbers of CPUs: whether they hold the same octree, the largest difference of every hydro, gravity and RT variable (relative to that variable's largest value), and the particles (matched by identity) and sinks.

Use it to check a repartition (the values must be identical), a round trip A → B → A, or two restarts of the same run on different numbers of ranks. With leaves_only=true only leaf cells are compared, which is the right test for an output written by writeramses, whose refined cells are rebuilt from their children.

Returns a CompareResult with the fields same_tree, ngrids, maxdiff, nparticles, particle_ids_match, particle_maxdiff, families_a, families_b, nmatched, nsinks and sink_maxdiff.

Send final completion notification for progress tracker

Parameters:

• tracker: Progress tracker to complete
• final_message: Optional final message
• include_summary: Include full execution summary (default: true)

Examples:

tracker = create_progress_tracker(1000, task_name="Simulation")
# ... do work with update_progress! calls ...
complete_progress!(tracker, "All galaxies processed successfully!")

Returns nothing.

configure_adaptive_io(simulation_path::String, output_num::Int; verbose=true)

Automatically configure I/O settings based on simulation characteristics.

Returns true when the settings were applied, false when the simulation could not be analysed and the defaults are kept.

configure_mera_io(; buffer_size="auto", cache=true, large_buffers=true, show_config=true)

Manually configure Mera I/O settings with user-friendly parameters.

Arguments

• buffer_size: Buffer size as string ("32KB", "64KB", "128KB", "256KB", "512KB") or "auto"
• cache=true: Enable file metadata caching for faster repeat operations
• large_buffers=true: Enable large buffer optimizations
• show_config=true: Display the applied configuration

Examples

# Use 128KB buffer with caching
configure_mera_io(buffer_size="128KB")

# Disable caching
configure_mera_io(buffer_size="64KB", cache=false)

# Maximum performance for very large simulations
configure_mera_io(buffer_size="512KB", cache=true, large_buffers=true)

# Minimal settings for small simulations
configure_mera_io(buffer_size="32KB", large_buffers=false)

Buffer size recommendations

• "32KB": Small simulations (< 50 CPU files)
• "64KB": Medium simulations (50-200 CPU files) - Default
• "128KB": Large simulations (200-500 CPU files)
• "256KB": Very large simulations (500-1000 CPU files)
• "512KB": Huge simulations (> 1000 CPU files)

Returns true.

Create a New DataSetType from a Filtered Data Table

function construct_datatype(data::IndexedTables.AbstractIndexedTable, dataobject::HydroDataType)
return HydroDataType

function construct_datatype(data::IndexedTables.AbstractIndexedTable, dataobject::PartDataType)
return PartDataType

function construct_datatype(data::IndexedTables.AbstractIndexedTable, dataobject::ClumpDataType)
return ClumpDataType

function construct_datatype(data::IndexedTables.AbstractIndexedTable, dataobject::GravDataType)
return GravDataType

Example

# read simulation information
julia> info = getinfo(420)
julia> gas = gethydro(info)

# filter and create a new` data table
julia> density = 3. /gas.scale.Msol_pc3
julia> filtered_db = @filter gas.data :rho >= density

# construct a new HydroDataType
# (comparable to the object "gas" but only with filtered data)
julia> gas_new = construct_datatype(filtered_db, gas)

convert_single_file_safe(old_path::String, new_path::String, file_index::Int, 
                        total_files::Int, safety_margin::Float64) -> Bool

Convert a single JLD2 file with comprehensive safety monitoring and error handling. This is the core conversion function called by each thread.

Safety Features

1. Pre-conversion memory check
2. Post-loading memory monitoring
3. Automatic garbage collection on violations
4. Specific error handling for different failure modes
5. Immediate memory cleanup after conversion

Parameters

• old_path: Full path to source file
• new_path: Full path to destination file
• file_index: Current file number (for progress reporting)
• total_files: Total files being processed
• safety_margin: Memory usage threshold for violation detection

Returns

• true: Successful conversion
• false: Conversion failed (error logged)

Memory Management Strategy

• Check safety margin before loading (most memory-intensive operation)
• Monitor again after loading to catch memory spikes
• Force garbage collection and nullify data references
• Brief pause after GC to allow memory recovery

Converts full simulation data into a compressed/uncompressed JLD2 format:

This function provides a comprehensive data conversion workflow for RAMSES simulation data, converting multiple data types into compressed JLD2 format with full benchmarking and threading control capabilities.

Features:

• Multi-datatype support: Handles :hydro, :particles, :gravity, :clumps, :rt, :sinks data types
• Threading control: Configurable threading for performance optimization (excluding clumps)
• Compression options: Multiple compression algorithms with automatic selection
• Spatial filtering: Select specific data ranges with flexible unit support
• Benchmarking: Comprehensive timing and performance statistics storage
• Progress tracking: Optional progress bars and verbose output modes
• Memory management: Automatic memory cleanup and usage tracking

Data Processing Workflow:

1. Configuration: Parse arguments and setup threading/compression parameters
2. Data Loading: Sequential loading of requested datatypes with optional threading
3. Data Writing: Compressed storage to JLD2 format with timing measurements
4. Statistics: Comprehensive benchmark and threading information storage

function convertdata(output::Int; datatypes::Array{<:Any,1}=[missing], path::String="./", fpath::String="./", fname = "output", compress::Any=nothing, comments::Any=nothing, lmax::Union{Int, Missing}=missing, xrange::Array{<:Any,1}=[missing, missing], yrange::Array{<:Any,1}=[missing, missing], zrange::Array{<:Any,1}=[missing, missing], center::CenterType=[0., 0., 0.], rangeunit::Symbol=:standard, smallr::Real=0., smallc::Real=0., verbose::Bool=true, showprogress::Bool=true, maxthreads::Int=Threads.nthreads(), myargs::ArgumentsType=ArgumentsType() )

return statistics_dictionary

Arguments

Required:

• output: RAMSES output number to convert

Optional Keywords:

• datatypes: Array of datatypes to convert.
  • Default: [missing] → converts all available data (:hydro, :gravity, :particles, :clumps, :rt, :sinks)
  • Examples: [:hydro, :particles], [:hydro], :particles
• path: Path to RAMSES simulation folders (default: "./").
• fpath: Output path for JLD2 files (default: "./")
• fname: Base filename for output files (default: "output_")
  • Final filename: fname + output_number + ".jld2"
• compress: Compression settings
  • Default: nothing → automatic LZ4 compression
  • Options: false (no compression), LZ4FrameCompressor(), Bzip2Compressor(), ZlibCompressor()
  • Requires: CodecZlib, CodecBzip2, or CodecLz4 packages for specific compressors
• comments: String description of the simulation (stored in file metadata)
• lmax: Maximum AMR level to process
  • Default: missing → uses all available levels
  • Limits data processing to specified refinement level
• xrange, yrange, zrange: Spatial selection ranges [min, max]
  • Default: [missing, missing] → full simulation box
  • Units specified by range_unit, relative to center
  • Zero-length ranges (min=max=0) converted to maximum extent
• center: Coordinate center for spatial ranges
  • Default: [0., 0., 0.] → simulation origin
  • Special values: [:bc], [:boxcenter] → box center
  • Mixed: [value, :bc, :bc] → custom center per axis
• range_unit: Units for spatial ranges and center
  • Options: :standard (code units), :Mpc, :kpc, :pc, :mpc, :ly, :au, :km, :cm
  • See viewfields(info.scale) for available unit conversions
• smallr: Lower density threshold (0 = inactive)
• smallc: Lower thermal pressure threshold (0 = inactive)
• max_threads: Threading control for data loading operations
  • Default: Threads.nthreads() → uses all available Julia threads
  • Applied to: :hydro, :gravity, :particles data loading
  • NOT applied to: :clumps and :sinks data (single-threaded)
  • Examples: max_threads=4 (limit to 4 threads), max_threads=1 (single-threaded)
• verbose: Enable detailed console output (default: true)
• show_progress: Enable progress bars during data loading (default: true)
• myargs: Pre-configured ArgumentsType struct to override multiple parameters

Return Value:

Returns a comprehensive statistics dictionary containing:

• TimerOutputs: Detailed timing for reading/writing operations
• threading: Threading configuration and system information
• benchmark: Performance metrics, compression ratios, processing times
• viewdata: Metadata about the converted dataset
• size: Memory usage and file size information

Method Overloads:

• convertdata(output::Int64; ...) → Full parameter interface
• convertdata(output::Int64, datatypes::Vector{Symbol}; ...) → Direct datatype specification
• convertdata(output::Int64, datatypes::Symbol; ...) → Single datatype conversion

Threading Behavior:

• Threaded operations: File-level parallelism for :hydro, :gravity, :particles
• Single-threaded: :clumps and :sinks data processing (threading not beneficial)
• Thread safety: All operations use thread-safe file I/O and memory management
• Performance: Optimal threading automatically balances CPU files across threads

Usage Examples:

Convert all datatypes with default settings and available threads

stats = convertdata(42, path, fpath)

Convert specific datatypes with threading control

stats = convertdata(42, [:hydro, :particles], path="source/folder", fpath="export/folder", max_threads=4)

Spatial selection with different compression

stats = convertdata(42, xrange=[-10, 10], yrange=[-10, 10], rangeunit=:Mpc, compress=Bzip2Compressor(), maxthreads=8)

Access performance statistics println("Total time: ", stats["benchmark"]["totalprocessingtimeseconds"]) println("Compression ratio: ", stats["benchmark"]["compressionratio"]) println("Threads used: ", stats["threading"]["effective_threads"])

cosmic_time(info::InfoType, a; unit=:Gyr)

The age of the universe at scale factor a, for this run's own cosmology. Accepts a scalar or any array, and is vectorised over it.

gettime answers for the snapshot; this answers for any epoch, which is what tracking across a set of outputs needs — an output tells you its scale factor, and a alone is not a time.

cosmic_time(info, 0.2276)                     # Gyr at the snapshot's scale factor
cosmic_time(info, [gc.aexp for gc in cats])   # …across every catalogue

See also lookback_time, age_of_universe.

Returns a Float64 in unit for a single a, or a vector for a vector of scale factors.

cosmology(info::InfoType) -> NamedTuple

Return the cosmological state of the snapshot as a NamedTuple. All quantities are derived from the stored info fields, so this works on freshly read simulations and on Mera files of any age.

Fields:

For a non-cosmological run iscosmological is false, redshift is 0, and the cosmology-derived times/densities are returned as NaN (the sentinel info values are not physical).

c = cosmology(getinfo(80, "…/yt_cosmo"))
c.redshift        # ≈ 0.143
c.age_Gyr         # ≈ 11.9

covering_grid(obj, var, [unit]; lmax=obj.lmax, center=[0.,0.,0.],
              xrange=[missing,missing], yrange=[missing,missing], zrange=[missing,missing],
              range_unit=:standard, max_bytes=4e9, pos_unit=:standard, verbose=true) -> CoveringGridResult

Resample AMR cell data (HydroDataType, GravDataType, or RtDataType) — or moving-mesh gas carried as particles (PartDataType with a :volume column, i.e. AREPO/GADGET PartType0) — onto a uniform Nx×Ny×Nz grid at refinement level lmax over the (optional) sub-box, every output cell sampled (not integrated). var may be a Symbol or a vector; unit likewise (defaults to code units).

For AMR cells, coarse leaves are replicated and fine leaves volume-averaged. For moving-mesh gas each output cell centre takes the value of the nearest generator that reaches it (KD-tree, capped at (√3/2)·V^(1/3) — the same ownership rule projection's weighting=:voronoi uses, so the two agree about which cell owns a point). Output cells that no cell reaches are NaN in both cases.

Point particles without a :volume column (stars, dark matter) have no extent to resample and raise an ArgumentError; use projection for those. Clumps raise a MethodError.

A uniform grid is dense and can be far larger than the AMR data — call covering_grid_memory first; this errors rather than allocate past max_bytes.

Pass periodic=true to let the window continue around a box face instead of being cut at it, which is what you want for a structure sitting on a boundary. A run that wraps in some directions only takes (x=true, y=true, z=false); getinfo reports which (info.boundaries). Without it the requested range is clamped to the box, so the grid comes back narrower than asked for.

gas = gethydro(getinfo(output, path))
covering_grid_memory(gas, [:rho, :T]; lmax=8)          # check size first
cg  = covering_grid(gas, [:rho, :T], [:nH, :K]; lmax=8) # then build
cg[:rho]                                                # the 3-D array

covering_grid_memory(obj, [vars]; lmax=obj.lmax, center=[0.,0.,0.], xrange=[missing,missing],
                     yrange=[missing,missing], zrange=[missing,missing], range_unit=:standard,
                     verbose=true) -> NamedTuple

Predict the size of the covering_grid before allocating it — a uniform grid is dense and can dwarf the sparse AMR data, so size it first. Returns (; level, dims, ncells, nvars, bytes_per_array, result_bytes, peak_bytes, amr_ncells, blowup): result_bytes is the returned arrays, peak_bytes the transient high-water mark during construction ((nvars+1) arrays — one shared geometric weight), and blowup = output cells ÷ AMR cells. vars only sets nvars (default 1). Pass an InfoType to size without loading data (then amr_ncells/blowup are missing).

Progress tracking with automatic time-based notifications

Creates a progress tracker that automatically sends notifications at specified time intervals or progress milestones.

Parameters:

• total_items: Total number of items to process
• time_interval: Send notification every N seconds (default: 300 = 5 minutes)
• progress_interval: Send notification every N% progress (default: 10%)
• task_name: Name of the task for notifications
• zulip_channel: Zulip channel (default: "progress")
• zulip_topic: Zulip topic (default: "Task Progress")

Returns: ProgressTracker object with update!() method

Examples:

# Create progress tracker for 1000 items, notify every 5 minutes or 10% progress
tracker = create_progress_tracker(1000, task_name="Galaxy analysis")

for i in 1:1000
    # Do some work
    process_galaxy(i)
    
    # Update progress (automatically sends notifications at intervals)
    update_progress!(tracker, i)
end

# Final completion notification
complete_progress!(tracker)

create_ultrafast_table(vars_1D, pos_1D, cpus_1D, names_constr, nvarh_corr, nvarh_i_list, read_cpu, isamr, verbose=false, max_threads=Threads.nthreads())

Creates IndexedTable with controlled threading for optimal performance.

Threading Control:

• Uses min(maxthreads, availablethreads, total_columns) for optimal load balancing
• Prevents thread over-subscription for small datasets
• Provides thread usage feedback when verbose=true

createconstants!(info::InfoType) -> InfoType

Fill info.constants with Mera's CGS constant table and return info. The in-place companion of createconstants; getinfo calls it for you, so you need this only when building an InfoType by hand.

createconstants() -> PhysicalUnitsType

Return Mera's table of physical constants in CGS units — G, c, kB, mH, Msol, pc, yr and the rest. This is what info.constants holds, and what every derived quantity is built from.

Use it to get the constants without an InfoType in hand; createconstants! fills the field on an existing info instead.

c = createconstants()
c.G       # 6.6743e-8  cm³ g⁻¹ s⁻²
c.Msol    # 1.9891e33  g

Mixing these CGS constants with code-unit quantities is the classic source of silently wrong answers — convert first, e.g. getvar(gas, :rho, :g_cm3).

See also createconstants!, createscales, getunit.

```julia createpath(output::Real, path::String; namelist::String="")

return FileNamesType ```

Create an object with predefined scale factors from code to pysical units

function createscales!(dataobject::InfoType)

return ScalesType003

createscales(info::InfoType) -> ScalesType
createscales(unit_l, unit_d, unit_t, unit_m, constants) -> ScalesType

Build the unit-conversion table — the object behind info.scale. Every entry is the factor that takes a code-unit quantity into that unit, so getvar(gas, :rho) .* info.scale.g_cm3 and getvar(gas, :rho, :g_cm3) agree.

The four-number form builds scales without an InfoType, which is how the unit tests check the conversions against CODATA without reading a snapshot.

Note a scale of exactly 1.0 cannot detect an inverted conversion (x*1 == x/1) — a fixture whose scale.kpc is 1 will not catch a reciprocal bug.

See also createscales!, createconstants, getunit.

X_frac (0.76) is the hydrogen mass fraction behind :nH, and mu (1/X_frac) the mean molecular weight behind temperatures in :K; see setcomposition! to change them on an InfoType.

critical_density(info::InfoType; unit=:g_cm3, z=redshift(info)) -> Float64

Critical density at redshift z, ρ_crit(z) = 3H(z)²/8πG, with H(z) = H0·E(a) and the full Friedmann E(a) = √(Ωm a⁻³ + Ωk a⁻² + ΩΛ) — the same value cosmology(info).rho_crit_cgs reports at the snapshot redshift.

Note this is not ρ̄_m/Ωm. The mean matter density scales exactly as (1+z)³ whatever ΩΛ does, so mean_matter_density uses Ωm·ρ_crit,0·(1+z)³; the critical density follows E(a), which adds the ΩΛ term. At z ≈ 3.4 with Planck-like parameters the two differ by a couple of percent, so they are not interchangeable.

Code-agnostic: it needs only H0, the density parameters and the constants, so it works for RAMSES, GADGET and AREPO alike. Pass z for another redshift, or unit for something other than g/cm³ (any density unit getunit accepts, e.g. :Msol_pc3).

cuboid(; xrange, yrange, zrange, center=[:bc], range_unit=:kpc)

An axis-aligned box; xrange/yrange/zrange are [lo, hi] offsets from center.

Returns a region value, for subregion and the region operators ∩, ∪, \ and !.

cylinder(radius, height; axis=[0,0,1], center=[:bc], range_unit=:kpc)

A cylinder of cylindrical radius spanning ±height along axis (height is the half-height).

Returns a region value, for subregion and the region operators ∩, ∪, \ and !.

cylindricalshell(r_in, r_out, height; axis=[0,0,1], center=[:bc], range_unit=:kpc)

A cylindrical shell r_in ≤ r_cyl ≤ r_out of half-height height along axis.

Returns a region value, for subregion and the region operators ∩, ∪, \ and !.

datacite(rec::SimulationRecord; creators=nothing, title=nothing, description=nothing,
         license=nothing, keywords=String[], publisher=nothing, year=nothing,
         related=[], toml=:auto, file=nothing) -> OrderedDict

The simulation as DataCite metadata (schema 4.5), the record that data repositories and DOI registration use. Mera fills what it knows: the resource type, the technical description, the size and formats, the creation date, and the paper of the simulation code. You supply what only you know: who made it, its title, its license.

Arguments

• rec::SimulationRecord: from simulationrecord, best the folder form, so the record knows every output.

Keywords

• creators: the people, as "Family, Given" strings or as (name=…, orcid=…, affiliation=…). Required.
• title::String: the title of the dataset. Required.
• description::String: a short abstract.
• license::String: an SPDX identifier, e.g. "CC-BY-4.0".
• keywords: subject keywords.
• publisher::String: the repository that will hold it, e.g. "Zenodo". Required by DataCite; defaults to "Zenodo".
• year: the publication year; defaults to this year.
• related: further related works, each (identifier=…, relation=…, type="DOI"), e.g. the paper the data supplements: (identifier="10.1093/mnras/…", relation="IsSupplementTo").
• toml = :auto: read the same fields from a simulation.toml file. :auto looks for one in the simulation folder; a path reads that file; nothing reads none. Keywords given here win over the file.
• file = nothing: also write the metadata to this JSON file.

A simulation.toml holds the same fields:

title = "Isolated Milky-Way-like disc, 10 levels"
description = "Hydrodynamics with star formation and supernova feedback."
license = "CC-BY-4.0"
keywords = ["galaxy", "interstellar medium"]

[[creators]]
name = "Behrendt, Manuel"
orcid = "0000-0000-0000-0000"
affiliation = "My institute"

Returns

The metadata as an ordered dictionary, ready for JSON3.write.

Examples

rec = simulationrecord("/data/sim")
datacite(rec; creators=["Behrendt, Manuel"], title="Isolated disc galaxy",
         license="CC-BY-4.0", file="datacite.json")

See also simulationrecord, exportdata.

dataoverview(dataobject::ClumpDataType)

Get the extrema (min/max) of each variable in the clump database. Returns an IndexedTable with extrema per variable.

dataoverview(dataobject::GravDataType; verbose::Bool=true)

Get total epot and min/max values of each gravity variable per level. Returns an IndexedTable summarizing epot and other variables.

dataoverview(dataobject::HydroDataType; verbose::Bool=true)

Provide a comprehensive overview of hydro simulation data including variable statistics.

Arguments

• dataobject::HydroDataType: Hydro simulation data object
• verbose::Bool=true: Control level of output detail

Returns

• IndexedTable: Mass and min/max values for each variable per refinement level

Description

Analyzes hydro data and provides statistics across AMR levels.

dataoverview(dataobject::PartDataType; verbose::Bool=true)

Get the min/max value of each particle variable per AMR level. Returns an IndexedTable summarizing min/max per level.

delete_field(name::Symbol; datatypes=:all)

Remove a previously add_field-registered field. datatypes=:all (default) removes it from every kind; otherwise pass a kind symbol or collection.

Returns nothing.

delete_unit(name::Symbol)

Remove a custom unit registered with add_unit.

Returns nothing.

depletion_time(dataobject, sfr_Msol_yr; mass=:mass, mask=[false]) -> NamedTuple

Gas depletion time and star-formation efficiency per free-fall time. Given a gas region and its star-formation rate sfr_Msol_yr [M⊙/yr], returns

• t_depl_Gyr = M_gas / SFR — how long the present SFR would take to consume the gas;
• t_ff_mw_Myr — the mass-weighted mean free-fall time ⟨√(3π/32Gρ)⟩ (per-cell :freefall_time);
• eps_ff = SFR · ⟨t_ff⟩ / M_gas — the dimensionless star-formation efficiency per free-fall time (Krumholz–McKee), typically ~0.01–0.1;
• M_gas_Msol, sfr.

Use a mask (e.g. dense star-forming gas getvar(gas,:rho,:nH) .> 27) to measure the efficiency of the gas actually forming stars. Works on any grid data with :mass and :freefall_time.

_, s = sfr_snapshot(stars).sfr[2], 0   # or any SFR estimate in M⊙/yr
d = depletion_time(gas, 1.5; mask = getvar(gas,:rho,:nH) .> 27)
d.t_depl_Gyr, d.eps_ff

deposit_rotated_cells_exact!(grid, weight_grid, x_cam, y_cam, cellsize, values, weights, cam_right, cam_up, cam_w, extent, res; max_threads=...)

Analytic deposit kernel for off-axis projections (binning=:exact): for every pixel a cell covers, the line-of-sight chord length through the rotated cube is integrated over the pixel area (polygon clipping against the six cube faces), i.e. the true column integral — the fidelity reference the other kernels are compared against. Sub-pixel cells fall back to a CIC 4-pixel stencil. Weight-conserving; threaded like :overlap. Internal; see the "Off-axis Projection: How It Works Internally" docs page.

deposit_rotated_cells_overlap!(grid, weight_grid, x_cam, y_cam, cellsize, values, weights, cam_right, cam_up, extent, res; nmax=64, max_threads=...)

Footprint deposit kernel for off-axis projections (binning=:overlap, the default): each cube is split into ns³ sub-points (ns = ⌈cellsize/pixel⌉, capped at nmax), every sub-point rotated into the camera frame and CIC-deposited with weight 1/ns³; cells coarser than the cap deposit each sub-cube as a footprint-sized top-hat, so the camera plane tiles without holes at any viewing angle. Converges to the :exact kernel. Per-cell contributions sum to exactly 1 — the kernel is weight-conserving by construction. Threaded over contiguous cell chunks into per-thread grids (summed at the end). Internal; see the "Off-axis Projection: How It Works Internally" docs page.

deposit_rotated_cells_to_grid!(grid, weight_grid, x_cam, y_cam, values, weights, extent, res; kwargs...)

Centre-only deposit kernel for off-axis projections (binning=:cic/:ngp): each rotated cell centre lands on its nearest pixel (:ngp) or is spread bilinearly over the 4 surrounding pixels (:cic). Fast preview quality — cells wider than a pixel leave speckle/moiré; the footprint-aware kernels below fix that. Exactly weight-conserving. Internal; see the "Off-axis Projection: How It Works Internally" docs page.

download_testdata([names]; dir, force=false, verbose=true)

Download Mera's public RAMSES test simulations. They are small (a few MB each, except Bondi) and every one has a known answer, so they can be used to check that an installation behaves correctly without a large download.

Called with a single name, returns the path to that simulation, which can be handed straight to getinfo:

path = download_testdata("sedov3d_amr")
info = getinfo(path, output=7)     # this run has 7 snapshots; 1 is before the blast
gas  = gethydro(info)

Called with several names or none at all, downloads them and returns the directory holding them. Anything already present is skipped unless force=true.

By default they land in joinpath(DEPOT_PATH[1], "mera_testdata"), alongside Julia's own package depot, so they survive between sessions. Pass dir to put them somewhere else.

The layout matches what Mera's test suite looks for, so the returned directory can be handed straight to it. Set MERA_SMOKE_ONLY too: without it the suite also looks for the maintainer's unpublished runs and fails on missing data.

ENV["MERA_TEST_DATA"] = download_testdata()   # or a subset by name
ENV["MERA_SMOKE_ONLY"] = "1"                  # every test the public data can back
using Pkg; Pkg.test("Mera")

Available simulations, with download sizes:

The Test Simulations page shows each of them with quicklook.

See also: getinfo, synthetic_clumps for a data-free alternative.

downsample(plan::ReportPlan, target_s) -> ReportPlan

Return a new plan trimmed to an estimated wall-time of target_s seconds: first drop the read level (fewest cells — helps every card), then shrink projection resolution and histogram bins. Used by report(...; budget_s=target_s). Never goes below levelmin / minimum sane resolution.

edge_on(data; center=:com, aperture=nothing, range_unit=:standard)

Return a GalaxyFrame oriented edge-on: the line of sight lies in the disk plane (perpendicular to the spin axis) and the spin axis points up in the image. Same arguments as face_on.

enhanced_fortran_read(file_path, read_function; use_cache=true)

Read a Fortran record file through Mera's buffered, optionally cached IO path, applying read_function to the opened stream.

An internal helper behind the RAMSES readers rather than something to call directly; caching is additionally gated by configure_mera_io(cache=…) and ENV["MERA_CACHE_ENABLED"].

ensure_optimal_io!(info::InfoType; force_reoptimize=false, verbose=false)

Automatically ensures optimal I/O settings based on simulation characteristics. This function is called transparently by gethydro(), getparticles(), and getgravity().

Arguments

• info: InfoType object from getinfo()
• force_reoptimize=false: Force re-optimization even if already optimized
• verbose=false: Enable detailed output (usually disabled for transparent operation)

Returns

• true if optimization was applied/verified, false if failed

estimate(plan::ReportPlan) -> NamedTuple

Zero-I/O runtime estimate for a [ReportPlan]: returns (per_card, read_s, compute_s, total_s, level, cells, sampled, calibrated) where per_card is a vector of (label, kind, datatype, cells, seconds). Absolute times are advisory until the cost model is calibrate!d (calibrated=false ⇒ treat as ±2×).

export_vtk(gas::HydroDataType, outprefix::String; scalars=[:rho], scalars_unit=[:nH], kwargs...)
export_vtk(part::PartDataType, outprefix::String; scalars=[:mass], scalars_unit=[:Msol], kwargs...)

Write cells or particles to VTK files, for 3-D viewers such as ParaView.

Cells are written as points at their centres, one file per level (<outprefix>_L<level>.vtu, and <outprefix>_vec_L<level>.vtu for a vector), with multiblock files that collect them (<outprefix>_scalar.vtm, <outprefix>_vector.vtm). Particles are written as points to one file, <outprefix>.vtu.

Arguments

• gas, part: the data to export, or a selection.
• outprefix::String: the start of the file names, with its folder, e.g. "vtk/galaxy".

Keywords

Data:

• scalars, scalars_unit: the quantities to write and one unit each; anything getvar computes. Defaults: [:rho] in [:nH] for cells, [:mass] in [:Msol] for particles.
• scalars_log10::Bool = false: write log10 of the scalars. Zero becomes -30, and negative values are written as log10 of their absolute value, with a count of them.
• vector = [missing, missing, missing]: three components of a vector, e.g. [:vx, :vy, :vz].
• vector_unit::Symbol = :km_s, vector_name = "velocity", vector_log10::Bool = false: its unit, its name in the file, and log10.
• positions_unit::Symbol = :standard: the unit of the positions; :standard means code length.

Levels (cells only):

• lmin = gas.lmin, lmax = gas.lmax: the levels to write.
• interpolate_higher_levels::Bool = true: average cells finer than lmax onto level lmax; with false they are left out.
• max_cells::Int = 100_000_000: the most points per level; above it, the points with the most finer cells under them are kept.

Limits and output:

• max_particles::Int = 100_000_000: particles only; the first max_particles rows are written.
• compress::Bool: compress the files; on by default for cells, off for particles.
• chunk_size::Int = 50000: not used at present.
• verbose::Bool = true: print progress.
• myargs::ArgumentsType: set verbose in one object.

Examples

julia> export_vtk(gas, "vtk/galaxy"; scalars=[:rho, :T], scalars_unit=[:nH, :K],
                  scalars_log10=true, vector=[:vx, :vy, :vz], positions_unit=:kpc)

julia> export_vtk(stars, "vtk/stars"; scalars=[:mass, :age], scalars_unit=[:Msol, :Myr])

See also savedata.

Returns, for cells, the written paths (scalar_files, vector_files, scalar_vtm, vector_vtm), with vector_vtm empty without a vector; for particles, nothing.

exportdata(result, file; format=:auto, vars=nothing, source=nothing,
           length_unit=:standard, sidecar=true, anonymize=false, note="",
           include_script=false, verbose=true) -> String

Write a Mera result to a file that other tools read, and a sidecar <file>.meta.json that records what it holds and where it came from.

Use it to publish the data behind a figure, or to continue in Python, IDL or a spreadsheet. The file holds plain arrays; the sidecar holds the provenance, the units and the environment that ran (the Reproducibility page explains it). To keep a result for Mera itself, use savemap or savedata instead: they round-trip the full object.

Arguments

• result: what to write.
  • a projection from projection: every map, plus the pixel centres x and y;
  • a profile, phase or pdf result;
  • a timeseries table;
  • a movie from getmovie: the frames as a cube, plus outputs and times;
  • an array, a number, or a NamedTuple of arrays, e.g. getvar columns. Pass source so the sidecar knows which snapshot they came from.
• file::String: the file to write. Its extension selects the format.

Keywords

• format::Symbol = :auto: the format, :jld2, :hdf5, :csv, :npy, :npz, :json or :fits; :auto takes it from the extension.
• vars = nothing: write only these arrays, e.g. vars=:sd or vars=[:mean, :median]. The coordinates (pixel centres, bin edges) are always kept.
• source = nothing: the data object or InfoType the result was computed from. Needed for arrays, numbers and timeseries tables, which do not carry it; a map, profile, phase or pdf carries it already.
• length_unit::Symbol = :standard: the unit of a map's pixel centres, extent and pixel size, e.g. :kpc. :standard keeps code units. Maps only.
• sidecar::Bool = true: write <file>.meta.json. The global switch sidecar overrides it.
• anonymize::Bool = false: in the sidecar, keep only the last two parts of the simulation path. The host name is never recorded.
• note::String = "": a free text stored in the sidecar, e.g. which figure this is.
• include_script::Bool = false: also store the full text of the running script (or the code cells of the notebook) in the sidecar. Its name and SHA-256 are always recorded, when Julia knows the script.
• verbose::Bool = true: print what was written.

Python and other C-order readers see the axes of an HDF5 or JLD2 array reversed (a Julia nx × ny map has shape (ny, nx) in h5py). NumPy files are written in Fortran order, so there a[i, j] is A[i+1, j+1]. The sidecar states the layout of each file.

Returns

The path of the data file, as a String.

Examples

p = projection(gas, [:sd, :T], [:Msol_pc2, :K])
exportdata(p, "fig3.h5"; length_unit=:kpc)          # + fig3.h5.meta.json
exportdata(p, "fig3_sd.npy"; vars=:sd)              # one map for numpy
exportdata(p, "fig3.csv"; length_unit=:kpc)         # x, y, sd, T per pixel

prof = profile(gas, :r_cylinder, :rho; xunit=:kpc, unit=:nH)
exportdata(prof, "fig4.csv"; note="Figure 4, radial density")

exportdata((rho=getvar(gas, :rho, :nH), T=getvar(gas, :T, :K)), "cells.npz"; source=gas)

using FITSIO
exportdata(p, "fig3.fits"; length_unit=:kpc)

See also savemap, savedata, provenance, export_vtk.

extract_column_data(vars_1D, pos_1D, cpus_1D, nvarh_corr, nvarh_i_list, col_idx, read_cpu, isamr)

Helper function to extract data for a specific column index. Centralizes the column extraction logic for better maintainability.

face_on(data; center=:com, aperture=nothing, range_unit=:standard)

Return a GalaxyFrame oriented face-on: the line of sight is the object's angular-momentum (spin) axis, so a projection with los=fr.los sees the disk from above.

• center — :com (default), :densest, or an explicit [x,y,z] in range_unit.
• aperture — optional sphere radius (in range_unit) around the centre; measure the spin only from gas inside it, to isolate the disk from the halo/outskirts.

fr = face_on(gas)                         # whole object, centred on the CoM
fr = face_on(gas; aperture=10, range_unit=:kpc)   # spin from the inner 10 kpc
projection(gas, :sd; los=fr.los, up=fr.up, center=fr.center, range_unit=fr.center_unit)

fr = face_on(gas; center=:densest, aperture=30, range_unit=:kpc)   # the densest galaxy
fr = face_on(gas; center=[x,y,z],  aperture=30, range_unit=:kpc)   # a catalogued halo

field_dependencies(kind::Symbol, var::Symbol) -> (; direct, raw)

Inspect a derived field's dependencies for data-type kind: direct are its immediate dependencies (raw or derived, as declared), raw is the transitive set of physical stored variables it ultimately needs (same as getvar_requirements). Works for built-in and add_field-registered quantities.

field_info(name::Symbol; kind::Symbol=:hydro)

The registration record (; compute, depends_on, unit, description) for a user field, or nothing if it isn't registered for that kind.

Returns that record as a named tuple, or nothing for an unknown name.

field_tree(kind::Symbol, var::Symbol; io=stdout)

Pretty-print the dependency tree of a derived field down to its raw leaves (cycle-safe).

Prints to io and returns nothing.

filesystem_info(path) -> NamedTuple

What kind of storage path sits on: type (lustre, gpfs, nfs, ext4, xfs, apfs, ...), mount point, and stripe for Lustre. Empty strings where it cannot be determined.

A read benchmark without this is not reproducible. A number from a Lustre scratch filesystem and the same number from a local NVMe describe different machines.

filter_by_range(files::Vector{String}, start_num::Int, end_num::Int) -> Vector{String}

Filter and sort files by output number range. Only files matching the RAMSES pattern and within the specified range are included.

Algorithm

1. Parse output number from each filename
2. Keep only files with valid numbers within [startnum, endnum]
3. Sort numerically (not lexicographically) for consistent processing order

Why Sorting Matters

• Ensures predictable processing order
• Makes progress tracking more intuitive
• Helps with debugging and result verification
• Important for time-series data analysis workflows

filterdata(obj, condition...; verbose=true) -> same-type Mera object
filterdata(obj, quantity, predicate; unit=:standard, verbose=true) -> same-type Mera object

Select the rows of obj (hydro / gravity / RT / particles / clumps) matching a value-space condition and return a new object of the same type — chainable with projection, getvar, subregion, … . Conditions select by any getvar quantity in any unit and compose with &/|/!; several positional conditions are AND-combined. The quantity/ predicate form is a shorthand for a single condition.

hot   = filterdata(gas, Above(:T, 1e4; unit=:K))
cold_dense = filterdata(gas, Below(:T, 1e3; unit=:K) & Above(:rho, 100; unit=:nH))
disc  = filterdata(gas, InRange(:r_cylinder, 0, 15; unit=:kpc), center=[:bc])

center, center_unit and vcenter are passed straight to getvar and default to its defaults, which means a radius is measured from the box corner and a velocity-derived quantity is in the box frame. Give them whenever the condition names a quantity that depends on where the object is, or on how fast it moves:

```julia filterdata(gas, InRange(:r_cylinder, 0, 10; unit=:kpc), center=[:bc]) # about the box centre filterdata(gas, Above(:mach, 1), vcenter=:auto) # in the gas rest frame

Pretty-print duration in seconds as h/m/s.

formation_redshift(info::InfoType, birth)

Redshift z_form = 1/a_birth − 1 at which each star particle formed, for a cosmological RAMSES run, from its super-conformal :birth time(s) (scalar or array). Non-star sentinels (birth = 0) and birth times after the snapshot return NaN, so filter with birth .< 0 (or isfinite). See also formation_time.

(Note: via getvar(particles, :zform) these NaNs become 0 — getvar maps all NaNs to 0 — so there too, select stars with birth .< 0.)

zf = formation_redshift(info, getvar(part, :birth))

formation_time(info::InfoType, birth; unit::Symbol=:Gyr)

Cosmic time (age of the universe) at which each star particle formed, for a cosmological RAMSES run, from its super-conformal :birth time(s). unit: :Gyr (default), :Myr, :yr, :s. Non-star sentinels return NaN. Equivalently formation_time = age_of_universe(snapshot) − stellar_age.

get_available_memory_gb() -> Float64

Get currently available (free) system memory in GB. Uses Sys.free_memory() which returns bytes, converts to GB for readability.

Get cross-platform disk information command string

Returns the appropriate command string for getting disk usage information based on the current operating system.

Usage Example (use carefully - exposes disk info):

julia> cmd = get_disk_info_command()  # Get command string
julia> notifyme(msg="Disk status:", capture_output=cmd)  # Use only when necessary

get_far_radius_cylinder(cx, cy, level, cx_shift, cy_shift, cell, periodic)

Distance from the cylinder axis to the FARTHEST point of a cell (cell=true), or to the cell centre (cell=false). A classic cylindrical shell with cell=true keeps every cell it touches: the nearest point of the cell lies inside r_out and its farthest point outside r_in.

get_far_radius_sphere(cx, cy, cz, level, cx_shift, cy_shift, cz_shift, cell, periodic)

Distance from the sphere centre to the FARTHEST point of a cell (cell=true), or to the cell centre (cell=false). A classic spherical shell with cell=true keeps every cell it touches: the nearest point of the cell lies inside r_out and its farthest point outside r_in.

get_filtered_ranges(gravitydata::GravDataType)

Extract spatial ranges from a GravDataType for use with projection functions.

Returns the ranges in the format expected by projection functions: (xrange, yrange, zrange) as arrays of [min, max] values.

Arguments

• gravitydata::GravDataType: Data object containing filtered spatial ranges

Returns

• Tuple{Array,Array,Array}: (xrange, yrange, zrange) for projection functions

Example

gravity_subregion = subregioncuboid(gravity, xrange=[0.4, 0.6], yrange=[0.4, 0.6])
xr, yr, zr = get_filtered_ranges(gravity_subregion)
projection(gravity_subregion, vars; xrange=xr, yrange=yr, zrange=zr, ...)