Find examples in the Mera Documentation for: filter data with pipeline macros

@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)

Find examples in the Mera Documentation for: filter data with pipeline macros

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 — per-map record of the AMR level a map was projected onto (relevant when a coarser lmax than the simulation maximum was requested).
• 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.

AbstractRegion

Supertype of the composable region value types passed to subregion: Cuboid, Sphere, Cylinder, SphericalShell. 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.

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.

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|).

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

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.

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).

FluxBudgetType

Result of fluxbudget. rates is a NamedTuple keyed by quantity (:mass, :momentum, :energy, :metals), each an (in, out, net, err_in, err_out, err_net, n_in, n_out, unit) NamedTuple (in ≤ 0 inflow, out ≥ 0 outflow, net = in + out; err_* is the sampling/shot-noise standard error of the cell-sum — large when a few cells dominate). components is nothing or a per-phase NamedTuple. surface/radius/shell_width/center record the definition; n_cells the shell cell count; shell_mass_Msol and residual the conservation check.

FluxMapType

Result of fluxmap. map is the 2-D surface map of quantity (:vr — mass-weighted mean normal velocity [km/s], inflow < 0 / outflow > 0; or :mdot — the per-bin mass-flux contribution [Msol/yr], whose sum is the net flux total). xedges/yedges are the surface-coordinate bin edges (xlabel/ylabel name them); mass is the Σ-mass map.

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 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).

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.

Mutable Struct: an off-axis line-of-sight cube returned by los_cube / velocity_cube.

cube[i,j,k] is the deposited weight (default mass) at sky pixel (i,j) in bin k of the binned line-of-sight quantity (e.g. :vlos, :T, :rho, or a vector (:bx,:by,:bz)). x/y/bins are bin EDGES. Convenience aliases: .velocity → bins, .v_unit → bin_unit, .direction → :offaxis. Store with savecube / load with loadcube.

Fields

• cube::Array{Float64,3} — the (nx, ny, nbins) data cube: deposited weight per sky pixel and line-of-sight bin. Summing over the 3rd axis recovers the column (moment-0) map.
• x::Vector{Float64}, y::Vector{Float64} — sky-pixel bin edges in code length units (length nx+1, ny+1); × scale.kpc etc. for physical axes.
• bins::Vector{Float64} — the line-of-sight quantity bin edges (length nbins+1) in bin_unit (e.g. velocity channels for :vlos).
• quantity::Any — the binned LOS quantity: a Symbol (:vlos, :T, :rho, …) or a 3-tuple/ vector of symbols for a vector LOS component (e.g. (:bx,:by,:bz)).
• bin_unit::Symbol — unit of the bins axis (e.g. :km_s, :standard). Alias: .v_unit.
• weight::Symbol — the deposit weight (:mass or :volume).
• los, up, cam_right::Vector{Float64} — the orthonormal off-axis camera basis (line of sight, up vector, right vector).
• center::Vector{Float64} — the projection centre in code units.
• pixsize::Float64 — physical size of one sky pixel in code length units.
• boxlen::Float64 — the simulation box length in code units.
• range_unit::Symbol — the unit the spatial ranges were specified in.
• scale::ScalesType003 — unit-conversion factors (code↔physical).
• info::InfoType — the full simulation descriptor (provenance).

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 — per-map record of the grid level the deposit used.
• maps_mode::SortedDict{Symbol,Symbol} — how each map was reduced: :mass_weighted or :volume_weighted (particle projection has no mode=:sum path; weighting selects between :mass and :volume).
• 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: 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, direction=:z, center=[:bc], range_unit=:standard, label="")

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

Provenance

Reproducibility record returned by provenance: mera_version, 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.

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, …).

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: Contains the created scale factors from code to physical units

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.

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.)

_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).

absorption_map(dataobject; kappa, sd_unit=:g_cm2, kappa_unit=:standard, verbose=true,
               <projection view kwargs>) -> NamedTuple

Continuum absorption map along the line of sight. Returns the optical depth τ = ∫κρ dl, the transmission e^{-τ}, the absorbed fraction 1 - e^{-τ}, the column density sd, and the column-effective opacity kappa_eff (= τ/Σ).

kappa sets the opacity and may be

• a Real — a constant (grey) opacity, τ = κ·Σ (e.g. kappa=dust_opacity(0.55));
• a Symbol — a per-cell opacity field: any getvar field, an add_field- registered field, or a raw data column (e.g. a stored metallicity). τ = ⟨κ⟩_mass·Σ, which is exactly ∫κρ dl;
• an AbstractVector — a per-cell opacity, one value per cell (full data length), in kappa_unit.

So the opacity can depend on metallicity, gas phase, temperature or ionization (build the per-cell κ from getvar), and on wavelength (via dust_opacity). Units: κ must be inverse to sd_unit (cm²/g for the default sd_unit=:g_cm2) so τ is dimensionless; for a Symbol/vector, kappa_unit is the unit those values are in (default :standard, i.e. already cm²/g).

All projection view/region keywords pass through (los/up, direction, inclination/azimuth, center, range_unit, xrange/…, res, lmax).

a = absorption_map(gas; kappa=210.0)                         # grey, dust-like
a = absorption_map(gas; kappa=dust_opacity(0.55))            # grey at V band

# metallicity-dependent dust opacity, per cell (κ ∝ Z, with a temperature dust-sublimation cutoff)
κcell = dust_opacity(0.55) .* getvar(gas,:metals) ./ 0.0134 .* (getvar(gas,:T,:K) .< 1500.0)
a = absorption_map(gas; kappa=κcell, los=fr.los, up=fr.up, center=fr.center)

# phase-specific (only molecular gas absorbs) via a registered field, or a raw column
a = absorption_map(gas; kappa=:my_kappa_field)

Returns (tau, transmission, absorbed, sd, kappa_eff, sd_unit, extent, los, up, center, pixsize, info). See also emission_map (the emission counterpart) and dust_opacity.

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.

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.

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"])")

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

Calculate the average velocity (w/o mass-weight) of any ContainMassDataSetType:

average_velocity(dataobject::ContainMassDataSetType; unit::Symbol=:standard, weighting::Symbol=:mass, mask::MaskType=[false])

return Tuple{Float64, Float64, Float64,}

Arguments

Required:

• dataobject: needs to be of type: "ContainMassDataSetType"

Optional Keywords:

• unit: the unit of the result (can be used w/o keyword): :standard (code units) :kms, :ms, :cm_s (of typye Symbol) ..etc. ; see for defined velocity-scales viewfields(info.scale)
• weighting: use different weightings: :mass (default), :volume (hydro), :no
• mask: needs to be of type MaskType which is a supertype of Array{Bool,1} or BitArray{1} with the length of the database (rows)

baryon_fraction(; label="baryon_fraction")

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

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.

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 = batchconvertera("/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 default file — put a sound name or number on the first line of ~/bell.txt (the same home-folder pattern notifyme uses with email.txt / zulip.txt);
4. the built-in fallback — :strum (the original Mera sound).

List the bundled sounds (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()            # default sound (from ~/bell.txt if present, 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

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.

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_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)%")

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 — a deterministic auto-up is chosen (the world axis least parallel to los), so the result is fully reproducible.

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], up=[0,1,0] ⇒ right=[1,0,0], up=[0,1,0], matching the axis-aligned direction=:z mapping (image x→sim x, image y→sim y).

Calculate the average velocity (w/o mass-weight) of any ContainMassDataSetType:

bulk_velocity(dataobject::ContainMassDataSetType; unit::Symbol=:standard, weighting::Symbol=:mass, mask::MaskType=[false])

return Tuple{Float64, Float64, Float64,}

Arguments

Required:

• dataobject: needs to be of type: "ContainMassDataSetType"

Optional Keywords:

• unit: the unit of the result (can be used w/o keyword): :standard (code units) :kms, :ms, :cm_s (of typye Symbol) ..etc. ; see for defined velocity-scales viewfields(info.scale)
• weighting: use different weightings: :mass (default), :volume (hydro), :no
• mask: needs to be of type MaskType which is a supertype of Array{Bool,1} or BitArray{1} with the length of the database (rows)

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

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.)

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.

Calculate the center-of-mass of any ContainMassDataSetType:

center_of_mass(dataobject::ContainMassDataSetType; unit::Symbol=:standard, mask::MaskType=[false])

return Tuple{Float64, Float64, Float64,}

Arguments

Required:

• dataobject: needs to be of type: "ContainMassDataSetType"

Optional Keywords:

• unit: the unit of the result (can be used w/o keyword): :standard (code units), :Mpc, :kpc, :pc, :mpc, :ly, :au , :km, :cm (of typye Symbol) ..etc. ; see for defined length-scales viewfields(info.scale)
• mask: needs to be of type MaskType which is a supertype of Array{Bool,1} or BitArray{1} with the length of the database (rows)

Calculate the joint center-of-mass of any HydroPartType:

center_of_mass(dataobject::Array{HydroPartType,1}, unit::Symbol; mask::MaskArrayAbstractType=[[false],[false]])

return Tuple{Float64, Float64, Float64,}

Arguments

Required:

• dataobject: needs to be of type: "Array{HydroPartType,1}""

Optional Keywords:

• unit: the unit of the result (can be used w/o keyword): :standard (code units), :Mpc, :kpc, :pc, :mpc, :ly, :au , :km, :cm (of typye Symbol) ..etc. ; see for defined length-scales viewfields(info.scale)
• mask: needs to be of type MaskArrayAbstractType which contains two entries with supertype of Array{Bool,1} or BitArray{1} and the length of the database (rows)

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");

clump_mass_fraction(; label="clump_mass_fraction")

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

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)])

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.

column_integral(dataobject, quantity[, unit]; binning=:exact, <view & range kwargs>)
    -> (map, quantity, unit, los, up, cam_right, center, pixsize, extent, boxlen, scale)

Line-of-sight column integral ∫ q dl of an arbitrary field q — the path-length-weighted sum along each sightline (not mass-weighted). This is the geometric primitive behind a true column density / optical-depth map: e.g. q=:rho gives the mass column (the same physical quantity as :sd, up to the code↔physical unit conversion of ρ and the path length), a constant opacity κ gives τ = κ·∫ρ dl, and q=:ne (with unit) the dispersion-measure-like ∫n dl.

It is exact when binning=:exact (the analytic chord length through each cube is integrated per pixel) and approximate for :overlap/:cic. Internally this is projection(dataobject, quantity; mode=:sum, weighting=:volume, binning=binning, …) divided by the pixel area, since the volume-weighted :sum deposits Σ q·(cube∩pixel-column volume).

.map holds ∫ q dl with the path length in code units (multiply by the appropriate dataobject.scale factor for a physical length, e.g. .map .* dataobject.scale.cm). The camera basis and extent travel with the result.

Calculate the center-of-mass of any ContainMassDataSetType:

com(dataobject::ContainMassDataSetType; unit::Symbol=:standard, mask::MaskType=[false])

return Tuple{Float64, Float64, Float64,}

Arguments

Required:

• dataobject: needs to be of type: "ContainMassDataSetType"

Optional Keywords:

• unit: the unit of the result (can be used w/o keyword): :standard (code units), :Mpc, :kpc, :pc, :mpc, :ly, :au , :km, :cm (of typye Symbol) ..etc. ; see for defined length-scales viewfields(info.scale)
• mask: needs to be of type MaskType which is a supertype of Array{Bool,1} or BitArray{1} with the length of the database (rows)

Calculate the joint center-of-mass of any HydroPartType:

com(dataobject::Array{HydroPartType,1}, unit::Symbol; mask::MaskArrayAbstractType=[[false],[false]])

return Tuple{Float64, Float64, Float64,}

Arguments

Required:

• dataobject: needs to be of type: "Array{HydroPartType,1}""

Optional Keywords:

• unit: the unit of the result (can be used w/o keyword): :standard (code units), :Mpc, :kpc, :pc, :mpc, :ly, :au , :km, :cm (of typye Symbol) ..etc. ; see for defined length-scales viewfields(info.scale)
• mask: needs to be of type MaskArrayAbstractType which contains two entries with supertype of Array{Bool,1} or BitArray{1} and the length of the database (rows)

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.

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!")

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

Automatically configure I/O settings based on simulation characteristics.

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)

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

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) 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). Coarse leaves are replicated, fine leaves volume-averaged; output cells outside the data are NaN. Particles and clumps are not AMR cells and raise a MethodError (use projection for particles).

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.

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

```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

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.

delete_unit(name::Symbol)

Remove a custom unit registered with add_unit.

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

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.

dust_opacity(wavelength_um; kappa_V=210.0, Z_over_Zsun=1.0, beta=1.8) -> Float64

Approximate dust opacity per gram of gas κ(λ) [cm²/g] for a Milky-Way (RV≈3.1) extinction curve, for use as the kappa of [`absorptionmap](@ref). ReturnsκV · (Aλ/AV) · ZoverZsun, whereAλ/A_Vis interpolated (log–log) from a representative MW curve for0.15 ≤ λ ≤ 2.2 μmand extended into the IR as aλ^{-beta}` power law beyond 2.2 μm.

• kappa_V — V-band opacity per gram of gas (default 210 cm²/g, i.e. A_V/N_H≈5.3e-22 mag cm² with μ≈1.4); this is why the old grey default κ≈200 was "dust-like".
• Z_over_Zsun — linear metallicity (dust-to-gas) scaling of the dust opacity.
• beta — IR emissivity index for the λ > 2.2 μm extrapolation.

κ = dust_opacity(0.55)              # V band ≈ 210 cm²/g
κ = dust_opacity(0.15; Z_over_Zsun=0.3)   # FUV, metal-poor
a = absorption_map(gas; kappa=κ)   # grey at that wavelength

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.

emission_map(dataobject; kappa, source, <view & range kwargs>, res=256, pxsize=nothing)
    -> (map, tau, x, y, extent, los, up, cam_right, center, pixsize, scale)

Off-axis emission + absorption map: the front-to-back formal solution of radiative transfer along each sightline, I = Σ_cells S·(1 − e^{−Δτ})·e^{−τ_front} with Δτ = κ·ℓ and the exact box-spline chord length ℓ per cell (the geometry the :exact deposit already computes). This turns the conservative projection into an approximate radiative-transfer mock observation (emission attenuated by intervening optical depth).

• kappa — absorption coefficient (per code length): a getvar field name (Symbol), a constant (Real), or a per-cell vector. The emissivity is κ·S, so a small but nonzero κ gives the optically-thin limit I ≈ S·κL, while kappa=0 yields zero emission. For a κ-independent optically-thin column use column_integral or mode=:sum.
• source — source function / emissivity S: a field name, constant, or per-cell vector.

Cells are accumulated nearest→farthest from the observer (the observer is on the −ŵ side; ŵ points away from the observer). Returns .map = observed intensity I and .tau = total optical depth, plus the camera metadata. Validation: a uniform slab of depth L with constant κ,S gives I = S(1 − e^{−κL}) (thin limit S·κL, thick limit S). View/centring keywords are the same as projection.

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 particle data to VTK format for visualization in tools like ParaView.

• export data that is present in your database and can be processed by getvar() (done internally)
• select scalar(s) and their unit(s)
• select a vector and its unit (like velocity)
• export data in log10
• creates binary files with optional compression
• supports multi-threading

-> generates VTU files; each particle is represented as a vertex point with associated scalar and vector data.

export_vtk(
    dataobject::PartDataType, outprefix::String;
    scalars::Vector{Symbol} = [:mass],
    scalars_unit::Vector{Symbol} = [:Msol],
    scalars_log10::Bool=false,
    vector::Array{<:Any,1}=[missing, missing, missing],
    vector_unit::Symbol = :km_s,
    vector_name::String = "velocity",
    vector_log10::Bool=false,
    positions_unit::Symbol = :standard,
    chunk_size::Int = 50000,
    compress::Bool = false,
    max_particles::Int = 100_000_000,
    verbose::Bool = true,
    myargs::ArgumentsType=ArgumentsType()
)

Arguments

Required:

• **dataobject::PartDataType:*** needs to be of type "PartDataType"
• outprefix: The base path and prefix for output file (e.g., "foldername/particles" will create "foldername/particles.vtu").

Predefined/Optional Keywords:

• scalars: List of scalar variables to export (default is particle mass); from the database or a predefined quantity (see field: info, function getvar(), dataobject.data)
• scalars_unit: Sets the unit for the list of scalars (default is :Msol).
• scalars_log10: Apply log10 to the scalars (default false).
• vector: List of vector component variables to export (default is missing).
• vector_unit: Sets the unit for the vector components (default is km/s).
• vector_name: The name of the vector field in the VTK file (default: "velocity").
• vector_log10: Apply log10 to the vector components (default: false).
• positions_unit: Sets the unit of the particle positions (default: code units); usefull in paraview to select regions
• chunk_size::Int = 50000: Size of data chunks for processing (reserved for future optimizations).
• compress: If false (default), disable compression.
• max_particles: Maximum number of particles to export (caps output if exceeded), (default: 100000000)
• verbose: If true (default), print detailed progress and diagnostic messages.

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.

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

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

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), Below(:vz, 50; unit=:km_s))
projection(hot, :sd, :Msol_pc2)        # the result is a normal Mera object

fluxbudget(obj::HydroDataType; surface=:sphere, radius, shell_width,
           quantities=[:mass], center=[:bc], range_unit=:kpc,
           phases=nothing, verbose=true) -> FluxBudgetType

Flux through a surface, split into inflow / outflow. surface is :sphere (radius radius) or :cylinder (curved wall at cylindrical radius radius); the thin shell has width shell_width (both in range_unit) centred at center. quantities ⊆ [:mass, :momentum, :energy, :metals].

Returns a FluxBudgetType: per quantity an (in, out, net, unit) rate — mass & metals in Msol/yr, momentum in Msol·km/s/yr, energy in erg/s. in sums the cells moving inward (v⊥ < 0) and out those moving outward (v⊥ ≥ 0); net = in + out. For mass/metals/energy in ≤ 0 and out ≥ 0; for momentum the carried quantity already contains v⊥ (radial momentum m·v⊥), so both in and out are ≥ 0 — the ram-pressure flux from in- and out-moving gas respectively. Pass phases = (cold = o->getvar(o,:T,:K).<1e4, hot = o->getvar(o,:T,:K).>=1e4) (a NamedTuple of shell→mask functions) for a per-phase breakdown in .components (the phases sum to the total).

gas = gethydro(getinfo(output, path))
fb  = fluxbudget(gas; surface=:sphere, radius=30.0, shell_width=2.0, range_unit=:kpc,
                 quantities=[:mass, :energy])
fb.rates.mass.out        # outflow rate, Msol/yr
fb.rates.mass.net        # net (in + out)

fluxmap(obj::HydroDataType; surface=:sphere, radius, shell_width, quantity=:vr,
        nbins=(72, 36), center=[:bc], range_unit=:kpc, verbose=true) -> FluxMapType

A surface map of the flux through the shell — where gas flows in vs out — binned by surface coordinates: (φ, cosθ) for a :sphere (equal-solid-angle sky map), (φ, z) for a :cylinder (the wall unrolled). This is not projection: projection integrates along a Cartesian axis and superposes the near and far side of the shell; fluxmap places each cell at its own surface location.

quantity=:vr (default) maps the mass-weighted mean normal velocity (km/s; inflow < 0, outflow > 0) — the clearest "where is the inflow/outflow" picture. quantity=:mdot maps the per-bin mass-flux contribution (Msol/yr), whose sum equals the net mass flux. nbins=(nφ, nθ_or_z).

fm = fluxmap(gas; surface=:sphere, radius=30.0, shell_width=2.0, range_unit=:kpc, quantity=:vr)
fm.map           # nφ × ncosθ map of mean v⊥ [km/s] — heatmap it (red out, blue in)
fm.xedges, fm.yedges

fluxmapplot(fm::FluxMapType; kwargs...) -> Makie.Figure

Render a fluxmap surface map as a heatmap — a perceptually-uniform diverging colormap (:vik) centred at zero for :vr (blue inflow / red-brown outflow), perceptually-uniform sequential (:viridis) for :mdot. Both are colorblind-safe. For :vr the symmetric range is clipped at the clip percentile of |v⊥| (default 0.95) so a few extreme cells don't wash out the contrast. Pass colormap= / clip= to override. Needs a Makie backend (using CairoMakie).

using CairoMakie
fm = fluxmap(gas; surface=:sphere, radius=30.0, shell_width=2.0, range_unit=:kpc)
fig = fluxmapplot(fm); Makie.save("flux_skymap.png", fig)

fluxprofile(obj::HydroDataType; surface=:sphere, radii, shell_width, quantity=:mass,
            center=[:bc], range_unit=:kpc, verbose=true) -> NamedTuple

Radial flux profile: run fluxbudget for quantity at each radius in radii (a vector or range, in range_unit) and assemble the inflow / outflow / net rate — with its sampling uncertainty — versus radius. Shows where the flux is launched or converges and lets you pick a converged radius and shell width. shell_width is the (constant) Δr of every shell.

Returns (; radius, in, out, net, err_net, n_cells, unit, surface, shell_width, quantity).

fp = fluxprofile(gas; surface=:sphere, radii=5:5:50, shell_width=2.0, range_unit=:kpc)
fp.radius, fp.net, fp.err_net      # net Ṁ(R) ± sampling error [Msol/yr]

fluxshell(obj::HydroDataType; surface=:sphere, radius, shell_width, center=[:bc], range_unit=:kpc)
    -> HydroDataType

Return the exact thin shell that fluxbudget measures — the AMR cells in [radius-shell_width/2, radius+shell_width/2] (spherical, or a cylindrical annulus) — as a normal HydroDataType. Use it to visualize what was measured: project it, profile it, or map the surface-normal velocity to see where gas flows in vs out.

sh = fluxshell(gas; surface=:sphere, radius=30.0, shell_width=2.0, range_unit=:kpc)
projection(sh, :sd, :Msol_pc2; center=[:bc])              # the shell as a ring/annulus
projection(sh, :vr_sphere, :km_s; center=[:bc])           # inflow (<0) / outflow (>0) over the shell

fluxtimeseries(loadfn, outputs, surface=:sphere; radius, shell_width, quantity=:mass,
               time_unit=:Myr, kwargs...) -> NamedTuple

Evolution of the flux through a fixed surface across a snapshot series. loadfn(output) returns a loaded HydroDataType (e.g. o -> gethydro(getinfo(o, path), verbose=false)); outputs is the list of output numbers. For each snapshot it runs fluxbudget for quantity and assembles the inflow / outflow / net rate versus time. Extra kwargs (shell_width, center, range_unit, …) pass through to fluxbudget.

fts = fluxtimeseries(o -> gethydro(getinfo(o, "/sim"), verbose=false), 100:10:300, :sphere;
                     radius=30.0, shell_width=2.0)
fts.t, fts.out          # time [Myr], outflow rate [Msol/yr]

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_cylinder_inclusion_weight(cx, cy, cz, level, cx_shift, cy_shift, cz_shift, 
                             radius_shift, height_shift, cell, smooth_boundary, boundary_width)

Calculate inclusion weight for a cell in cylindrical subregion with optional smooth boundaries.

Returns

• Float64: Weight between 0.0 (excluded) and 1.0 (fully included)

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_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, ...)

get_filtered_ranges(hydrodata::HydroDataType)

Extract spatial ranges from a HydroDataType 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

• hydrodata::HydroDataType: Data object containing filtered spatial ranges

Returns

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

Example

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

get_filtered_ranges(rtdata::RtDataType)

Extract spatial ranges from a RtDataType 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

• rtdata::RtDataType: Data object containing filtered spatial ranges

Returns

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

Example

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

get_height_cylinder(cz, level, cz_shift, cell)

Calculate distance from cell to cylinder center plane for cylindrical subregion selection.

This function handles both cell-based and point-based selection modes:

• Cell-based (cell=true): Returns minimum distance from cell boundary to center plane
• Point-based (cell=false): Returns distance from cell center to center plane

Arguments

• cz: Cell z-coordinate in grid units
• level: AMR level of the cell
• cz_shift: Cylinder center plane position in physical coordinates [0,1]
• cell::Bool: Selection mode (true=cell-based, false=point-based)

Returns

• Float64: Distance from cell to cylinder center plane in physical coordinates

Algorithm

For cell-based selection, returns 0 if the center plane intersects the cell, otherwise returns distance to closest cell boundary. For point-based selection, returns absolute distance from cell center to center plane.

Get cross-platform memory information command string

Returns the appropriate command string for getting detailed memory information based on the current operating system.

Usage Example (use carefully - exposes system info):

julia> cmd = get_memory_info_command()  # Get command string only
julia> notifyme(msg="Memory status:", capture_output=cmd)  # Use judiciously

Platform-specific commands:

• macOS: vmstat + memorypressure (native Darwin tools)
• Linux: free + /proc/meminfo (standard Linux memory tools)
• Windows: wmic memory queries (Windows Management Interface)

get_memory_usage_percentage() -> Float64

Calculate current memory usage as percentage of total system memory. Formula: (totalmemory - availablememory) / total_memory * 100 This gives the percentage of memory currently in use by all system processes.

Get cross-platform network information command string

Returns the appropriate command string for getting network configuration based on the current operating system.

Usage Example (use carefully - exposes network info):

julia> cmd = get_network_info_command()  # Get command string
julia> notifyme(msg="Network status:", capture_output=cmd)  # Consider privacy implications

Get cross-platform process information command string

Returns the appropriate command string for getting running process information based on the current operating system.

Usage Example (use carefully - exposes process info):

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

get_radius_cylinder(cx, cy, level, cx_shift, cy_shift, cell)

Calculate distance from cell to cylinder axis for cylindrical subregion selection.

This function handles both cell-based and point-based selection modes:

• Cell-based (cell=true): Returns minimum distance from cell boundary to cylinder axis
• Point-based (cell=false): Returns distance from cell center to cylinder axis

Arguments

• cx, cy: Cell coordinates in grid units
• level: AMR level of the cell
• cx_shift, cy_shift: Cylinder axis position in physical coordinates [0,1]
• cell::Bool: Selection mode (true=cell-based, false=point-based)

Returns

• Float64: Distance from cell to cylinder axis in physical coordinates

Algorithm

For cell-based selection, finds the closest point on the cell boundary to the axis using clamp operations. For point-based selection, uses cell center.

get_radius_sphere(cx, cy, cz, level, cx_shift, cy_shift, cz_shift, cell)

Calculate distance from cell to sphere center for spherical subregion selection.

This function handles both cell-based and point-based selection modes:

• Cell-based (cell=true): Returns minimum distance from cell boundary to sphere center
• Point-based (cell=false): Returns distance from cell center to sphere center

Arguments

• cx, cy, cz: Cell coordinates in grid units
• level: AMR level of the cell
• cx_shift, cy_shift, cz_shift: Sphere center position in physical coordinates [0,1]
• cell::Bool: Selection mode (true=cell-based, false=point-based)

Returns

• Float64: Distance from cell to sphere center in physical coordinates

Algorithm

For cell-based selection, finds the closest point on the cell boundary to the center using clamp operations on each dimension. For point-based selection, uses the Euclidean distance from cell center to sphere center.

Example

# Distance from cell at (10,20,30) on level 2 to sphere at (0.5,0.5,0.5)
distance = get_radius_sphere(10, 20, 30, 2, 0.5, 0.5, 0.5, true)

get_simulation_characteristics(simulation_path::String, output_num::Int)

Analyze simulation folder to determine optimal I/O settings. Returns a dictionary with simulation characteristics and recommended settings.

Get cross-platform system information command string

Returns the appropriate command string for getting system information (memory, disk, CPU) based on the current operating system.

Usage Examples (use carefully - exposes system info):

julia> cmd = get_system_info_command()  # Get command string
julia> notifyme(msg="System status:", capture_output=cmd)  # Consider privacy implications

julia> cmd = get_memory_info_command()  
julia> notifyme(msg="Memory status:", capture_output=cmd)

Cross-platform compatibility:

• macOS: Uses vmstat, memorypressure, df, sysctl
• Linux: Uses free, df, /proc/meminfo, /proc/cpuinfo
• Windows: Uses wmic, systeminfo commands

get_total_memory_gb() -> Float64

Get total installed system memory in GB. Uses Sys.total_memory() for accurate system capacity measurement.

Generate optimized unit conversion at compile time. Eliminates runtime unit lookup overhead.

Read the clump-data:

• selected variables
• limited to a spatial range
• print the name of each data-file before reading it
• toggle verbose mode
• pass a struct with arguments (myargs)

getclumps(  dataobject::InfoType;
            vars::Array{Symbol,1}=[:all],
            xrange::Array{<:Any,1}=[missing, missing],
            yrange::Array{<:Any,1}=[missing, missing],
            zrange::Array{<:Any,1}=[missing, missing],
            center::Array{<:Any,1}=[0., 0., 0.],
            range_unit::Symbol=:standard,
            print_filenames::Bool=false,
            verbose::Bool=true,
            myargs::ArgumentsType=ArgumentsType() )

Returns an object of type ClumpDataType, containing the clump-data table, the selected options and the simulation ScaleType and summary of the InfoType

return ClumpDataType()

# get an overview of the returned fields:
# e.g.:
julia> info = getinfo(100)
julia> clumps  = getclumps(info)
julia> viewfields(clumps)
#or:
julia> fieldnames(clumps)

Arguments

Required:

• dataobject: needs to be of type: "InfoType", created by the function getinfo

Predefined/Optional Keywords:

• vars: Currently, the length of the loaded variable list can be modified *(see examples below).
• vars: List of clump columns to read; default [:all] uses the file header. The order must match the columns in the clump files. You may specify fewer names (to read a subset) or more names if the data contains more columns than listed in the header.
• xrange: the range between [xmin, xmax] in units given by argument range_unit and relative to the given center; zero length for xmin=xmax=0. is converted to maximum possible length
• yrange: the range between [ymin, ymax] in units given by argument range_unit and relative to the given center; zero length for ymin=ymax=0. is converted to maximum possible length
• zrange: the range between [zmin, zmax] in units given by argument range_unit and relative to the given center; zero length for zmin=zmax=0. is converted to maximum possible length
• zrange: the range between [zmin, zmax] in units given by argument range_unit and relative to the given center; zero length for zmin=zmax=0. is converted to maximum possible length Note: spatial filtering uses the columns :peakx, :peaky, :peak_z. If you set any ranges, ensure these columns are included in vars (or use vars=[:all]).
• range_unit: the units of the given ranges: :standard (code units), :Mpc, :kpc, :pc, :mpc, :ly, :au , :km, :cm (of type Symbol) ..etc. ; see for defined length-scales viewfields(info.scale)
• center: in units given by argument range_unit; by default [0., 0., 0.]; the box-center can be selected by e.g. [:bc], [:boxcenter], [value, :bc, :bc], etc..
• print_filenames: print on screen the current processed clump file of each CPU
• verbose: print timestamp, selected vars and ranges on screen; default: true
• myargs: pass a struct of ArgumentsType to pass several arguments at once and to overwrite default values of xrange, yrange, zrange, center, range_unit, verbose

Important notes

• Spatial selection is applied to the clump peak position only (columns :peak_x, :peak_y, :peak_z). It does not test the full clump extent/volume.
• All clump columns are parsed as Float64 from the text files. Cast to other types as needed after loading.
• Column names with dashes in the header must be requested as symbols with quotes, e.g. Symbol("rho-") and Symbol("rho+").
• For faster I/O, pass a smaller vars list to read only the columns you need.
• When supplying a custom vars list, ensure the data files contain at least that many columns and that the order matches the file columns; otherwise parsing will fail.

Defined Methods - function defined for different arguments

• getclumps(dataobject::InfoType; ...) # no given variables -> all variables loaded
• getclumps(dataobject::InfoType, vars::Array{Symbol,1}; ...) # one or several given variables -> array needed

Examples

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

# Example 1:
# read clump data of all variables, full-box
julia> clumps = getclumps(info)

# Example 2:
# read clump data of all variables
# data range 20x20x4 kpc; ranges are given in kpc relative to the box (here: 48 kpc) center at 24 kpc
julia> clumps = getclumps(    info,
                              xrange=[-10.,10.],
                              yrange=[-10.,10.],
                              zrange=[-2.,2.],
                              center=[24., 24., 24.],
                              range_unit=:kpc )

# Example 3:
# give the center of the box by simply passing: center = [:bc] or center = [:boxcenter]
# this is equivalent to center=[24.,24.,24.] in Example 2
# the following combination is also possible: e.g. center=[:bc, 12., 34.], etc.
julia> clumps = getclumps(  info,
                            xrange=[-10.,10.],
                            yrange=[-10.,10.],
                            zrange=[-2.,2.],
                            center=[33., :bc, 10.],
                            range_unit=:kpc )

# Example 4:
# Load less than the found 12 columns from the header of the clump files;
# Pass an array with the variables to the keyword argument *vars*.
# The order of the variables has to be consistent with the header in the clump files:
julia> clumps = getclumps(info, [ :index, :lev, :parent, :ncell,
                                 :peak_x, :peak_y, :peak_z ])

# Example 5:
# Load more than the found 12 columns from the header of the clump files.
# E.g. the list can be extended with more names if there are more columns
# in the data than given by the header in the files.
# The order of the variables has to be consistent with the header in the clump files:
julia> clumps = getclumps(info, [   :index, :lev, :parent, :ncell,
                                    :peak_x, :peak_y, :peak_z,
                                    Symbol("rho-"), Symbol("rho+"),
                                    :rho_av, :mass_cl, :relevance,
                                    :vx, :vy, :vz ])
...

Get the extent of the dataset-domain:

function getextent( dataobject::DataSetType;
                     unit::Symbol=:standard,
                     center::Array{<:Any,1}=[0., 0., 0.],
                     center_unit::Symbol=:standard,
                     direction::Symbol=:z)

return (xmin, xmax), (ymin ,ymax ), (zmin ,zmax )

Arguments

Required:

• dataobject: needs to be of type: "DataSetType"

Predefined/Optional Keywords:

• center: in unit given by argument center_unit; by default [0., 0., 0.]; the box-center can be selected by e.g. [:bc], [:boxcenter], [value, :bc, :bc], etc..
• center_unit: :standard (code units), :Mpc, :kpc, :pc, :mpc, :ly, :au , :km, :cm (of typye Symbol) ..etc. ; see for defined length-scales viewfields(info.scale)
• direction: todo
• unit: return the variables in given unit

Defined Methods - function defined for different arguments

• getextent( dataobject::DataSetType; # one given variable
• getextent( dataobject::DataSetType, unit::Symbol; ...) # one given variable with its unit

Read gravity leaf-cells with optional spatial selection and multithreading.

• Select variables (e.g., :epot, :ax, :ay, :az; include :cpu to add CPU column)
• Limit to a maximum refinement level (lmax)
• Select by spatial range around a center in a chosen unit
• Parallel file processing (configurable max_threads) with progress bar
• Verbose output with timestamps and table memory overview
• Pass an ArgumentsType struct (myargs) to override multiple keywords at once

getgravity(dataobject::InfoType;
        lmax::Real=dataobject.levelmax,
        vars::Array{Symbol,1}=[:all],
        xrange::Array{<:Any,1}=[missing, missing],
        yrange::Array{<:Any,1}=[missing, missing],
        zrange::Array{<:Any,1}=[missing, missing],
        center::Array{<:Any,1}=[0., 0., 0.],
        range_unit::Symbol=:standard,
        print_filenames::Bool=false,
        verbose::Bool=true,
        show_progress::Bool=true,
        myargs::ArgumentsType=ArgumentsType(),
        max_threads::Int=Threads.nthreads())

Returns a GravDataType with:

• data: IndexedTable with position columns (:cx,:cy,:cz), optionally :level and/or :cpu, followed by selected variables
• info, lmin, lmax, boxlen, ranges, selectedgravvars, useddescriptors, scale

Arguments

• Required
  • dataobject: InfoType from getinfo
• Keywords
  • lmax: maximum refinement level to read (validated against the dataset)
  • vars: gravity variables to load; default [:all]. Known names include :epot, :ax, :ay, :az. Include :cpu to add CPU column.
  • xrange, yrange, zrange: [min,max] in units of range_unit relative to center; use missing to skip. Zero-length [0,0] is expanded to full box.
  • center: selection center; default [0.,0.,0.]; you can use symbols like [:bc] for box center (also combinations like [val, :bc, :bc]).
  • range_unit: units for ranges/center (e.g., :standard, :kpc, :pc, :Mpc, :km, :cm; Symbol)
  • print_filenames: print each processed file path
  • verbose: print timestamps and summaries
  • show_progress: show a progress bar during reading
  • myargs: ArgumentsType struct to override lmax, ranges, center, rangeunit, verbose, showprogress
  • max_threads: cap threads used for table creation and column extraction (≤ available threads)

Defined methods

• getgravity(dataobject::InfoType; ...) # no vars → all variables loaded
• getgravity(dataobject::InfoType, var::Symbol; ...) # single variable (Symbol)
• getgravity(dataobject::InfoType, vars::Array{Symbol,1}; ...) # multiple variables

Examples

# Read all gravity variables at all levels, whole box
g = getgravity(info)

# Read only potential and acceleration components within a kpc-scale box around the center
g = getgravity(info, vars=[:epot, :ax, :ay, :az],
                             xrange=[-5,5], yrange=[-5,5], zrange=[-2,2],
                             center=[:bc], range_unit=:kpc)

# Include CPU column
g = getgravity(info, vars=[:cpu, :epot])

# Override several keywords at once via myargs
g = getgravity(info, myargs=ArgumentsType(lmax=12, range_unit=:kpc, verbose=false))

Important notes

• Spatial selection is evaluated at cell centers (:cx,:cy,:cz).
• AMR vs uniform grid affects included columns and primary key: AMR adds :level.
• Variable names can also come from file descriptors; unknown indices are named :gravN.

gethydro(info::InfoType, var::Symbol; kwargs...)
gethydro(info::InfoType, vars::Vector{Symbol}; kwargs...)
gethydro(info::InfoType; vars=[:all], kwargs...)

Load leaf-cell hydro variables from a RAMSES output described by an InfoType. Supports spatial sub-selection (xrange/yrange/zrange, center, range_unit), level restriction (lmax), variable filtering (vars or single var), basic data sanitation (smallr, smallc, negative value checks), progress + verbosity control, and explicit thread limiting (max_threads). Returns a HydroDataType containing an IndexedTable plus metadata (selected variables, scales, ranges). See extended docstring below for full argument reference and examples.

Read the leaf-cells of the hydro-data:

• select variables
• limit to a maximum level
• limit to a spatial range
• multi-threading
• set a minimum density or sound speed
• check for negative values in density and thermal pressure
• print the name of each data-file before reading it
• toggle verbose mode
• toggle progress bar
• pass a struct with arguments (myargs)

gethydro(dataobject::InfoType;
            lmax::Real=dataobject.levelmax,
            vars::Array{Symbol,1}=[:all],
            xrange::Array{<:Any,1}=[missing, missing],
            yrange::Array{<:Any,1}=[missing, missing],
            zrange::Array{<:Any,1}=[missing, missing],
            center::Array{<:Any,1}=[0., 0., 0.],
            range_unit::Symbol=:standard,
            smallr::Real=0.,
            smallc::Real=0.,
            check_negvalues::Bool=false,
            print_filenames::Bool=false,
            verbose::Bool=true,
            show_progress::Bool=true,
            myargs::ArgumentsType=ArgumentsType(),
            max_threads::Int=Threads.nthreads())

Returns an object of type HydroDataType, containing the hydro-data table, the selected options and the simulation ScaleType and summary of the InfoType

return HydroDataType()

# get an overview of the returned fields:
# e.g.:
julia> info = getinfo(100)
julia> gas  = gethydro(info)
julia> viewfields(gas)
#or:
julia> fieldnames(gas)

Arguments

Required:

• dataobject: needs to be of type: "InfoType", created by the function getinfo

Predefined/Optional Keywords:

• lmax: the maximum level to be read from the data
• var(s): the selected hydro variables in arbitrary order: :all (default), :cpu, :rho, :vx, :vy, :vz, :p, and the passive scalars. When the output has a hydro_file_descriptor.txt, the scalars carry their descriptor names (e.g. :metallicity, :scalar00, :scalar01...); without a descriptor they are positional (:var6, :var7...). Positional :varN selectors keep working in either case.
• xrange: the range between [xmin, xmax] in units given by argument range_unit and relative to the given center; zero length for xmin=xmax=0. is converted to maximum possible length
• yrange: the range between [ymin, ymax] in units given by argument range_unit and relative to the given center; zero length for ymin=ymax=0. is converted to maximum possible length
• zrange: the range between [zmin, zmax] in units given by argument range_unit and relative to the given center; zero length for zmin=zmax=0. is converted to maximum possible length
• range_unit: the units of the given ranges: :standard (code units), :Mpc, :kpc, :pc, :mpc, :ly, :au , :km, :cm (of typye Symbol) ..etc. ; see for defined length-scales viewfields(info.scale)
• center: in units given by argument range_unit; by default [0., 0., 0.]; the box-center can be selected by e.g. [:bc], [:boxcenter], [value, :bc, :bc], etc..
• smallr: set lower limit for density; zero means inactive
• smallc: set lower limit for thermal pressure; zero means inactive
• check_negvalues: check loaded data of "rho" and "p" on negative values; false by default
• print_filenames: print on screen the current processed hydro file of each CPU
• verbose: print timestamp, selected vars and ranges on screen; default: true
• show_progress: print progress bar on screen
• myargs: pass a struct of ArgumentsType to pass several arguments at once and to overwrite default values of lmax, xrange, yrange, zrange, center, rangeunit, verbose, showprogress
• **max_threads: give a maximum number of threads that is smaller or equal to the number of assigned threads in the running environment

Defined Methods - function defined for different arguments

• gethydro( dataobject::InfoType; ...) # no given variables -> all variables loaded
• gethydro( dataobject::InfoType, var::Symbol; ...) # one given variable -> no array needed
• gethydro( dataobject::InfoType, vars::Array{Symbol,1}; ...) # several given variables -> array needed

Examples

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

# Example 1:
# read hydro data of all variables, full-box, all levels
julia> gas = gethydro(info)

# Example 2:
# read hydro data of all variables up to level 8
# data range 20x20x4 kpc; ranges are given in kpc relative to the box (here: 48 kpc) center at 24 kpc
julia> gas = gethydro(    info,
                          lmax=8,
                          xrange=[-10.,10.],
                          yrange=[-10.,10.],
                          zrange=[-2.,2.],
                          center=[24., 24., 24.],
                          range_unit=:kpc )

# Example 3:
# give the center of the box by simply passing: center = [:bc] or center = [:boxcenter]
# this is equivalent to center=[24.,24.,24.] in Example 2
# the following combination is also possible: e.g. center=[:bc, 12., 34.], etc.
julia> gas = gethydro(    info,
                          lmax=8,
                          xrange=[-10.,10.],
                          yrange=[-10.,10.],
                          zrange=[-2.,2.],
                          center=[33., bc:, 10.],
                          range_unit=:kpc )

# Example 4:
# read hydro data of the variables density and the thermal pressure, full-box, all levels
julia> gas = gethydro( info, [:rho, :p] ) # use array for the variables

# Example 5:
# read hydro data of the single variable density, full-box, all levels
julia> gas = gethydro( info, :rho ) # no array for a single variable needed
...

gethydro_athena(info::InfoType; xrange, yrange, zrange, center, range_unit, verbose=true) -> HydroDataType

Read an Athena++ HDF5 snapshot described by info (from getinfo_athena) into a HydroDataType with columns (:level, :cx, :cy, :cz, <vars…>) in Mera's AMR convention, so the analysis layer works on it unchanged. Each MeshBlock's cells are placed on the level lattice via its LogicalLocation and level.

xrange/yrange/zrange (+ center, range_unit) select a spatial window at load time (the leaf-cell analogue of Athena++'s own athdf(x1_min=…, x1_max=…)), exactly as for the RAMSES gethydro; the returned object's ranges records it.

gethydro_flash(info::InfoType; xrange, yrange, zrange, center, range_unit, verbose=true) -> HydroDataType

Read a FLASH HDF5 snapshot described by info (from getinfo_flash) into a HydroDataType with columns (:level, :cx, :cy, :cz, <vars…>) in Mera's AMR convention. Only leaf blocks (node type == 1) are loaded. xrange/yrange/zrange (+ center, range_unit) select a spatial window at load time, reading only the intersecting leaf blocks (per-block HDF5 hyperslabs), exactly as for the RAMSES gethydro.

gethydro_pluto(info::InfoType; xrange, yrange, zrange, center, range_unit, verbose=true) -> HydroDataType

Read a PLUTO static-grid snapshot (data.NNNN.dbl, single-file double precision) described by info (from getinfo_pluto) into a uniform-grid HydroDataType — columns (:cx,:cy,:cz, :rho,:vx,:vy,:vz,:p), the same schema the RAMSES uniform-grid reader produces, so the whole analysis layer works on it unchanged.

xrange/yrange/zrange (+ center, range_unit) select a spatial window at load time, exactly as for the RAMSES gethydro; the returned object's ranges records it.

getinfo([output::Real]; path::String="", namelist::String="", verbose::Bool=true)

Return simulation overview metadata (an InfoType) for a RAMSES output. It inspects info, descriptor and header files (hydro / gravity / particles / RT / clumps), parses the namelist when available, gathers compile + build information, and collects basic cosmological units & scaling factors.

Call patterns: info = getinfo(42) # current directory, output 42 info = getinfo(output=42, path="/sim") # explicit keywords info = getinfo("/sim"; output=42) # path first

Set verbose=false to suppress the textual summary. The returned object exposes fields like descriptor, grid_info, part_info, scale, and helper accessors (namelist(info), makefile(info), timerfile(info), etc.).

getinfo_athena(output::Int, path::String; unit_length=1.0, unit_density=1.0,
               unit_velocity=1.0, verbose=true) -> InfoType

Read Athena++ HDF5 (.athdf) snapshot metadata for output in path (a directory holding the …NNNNN.athdf file, or the file itself) into a Mera InfoType (simcode = "Athena++"). The AMR level range maps to levelmin/levelmax (levelmin == levelmax ⇒ uniform grid). Feed the result to gethydro.

Units. Athena++ data is in code units; supply the run's CGS unit_length/unit_density/ unit_velocity for physical :kpc/:Msol/… conversions (defaults treat the run as dimensionless, see getinfo_pluto for the same convention).

getinfo_flash(output::Int, path::String; unit_length=1.0, unit_density=1.0,
              unit_velocity=1.0, verbose=true) -> InfoType

Read FLASH HDF5 snapshot metadata for output in path (a directory holding the …_hdf5_plt_cnt_NNNN / …_hdf5_chk_NNNN file, or the file itself) into a Mera InfoType (simcode = "FLASH"). The PARAMESH refinement range maps to levelmin/levelmax. Feed the result to gethydro.

Units. FLASH usually writes CGS, so the defaults (unit_* = 1) treat code units as CGS and :kpc/:Msol/… conversions are already physical. Override unit_length/unit_density/ unit_velocity for a run in scaled units (same convention as getinfo_athena).

getinfo_gadget(output::Int, path::String; unit_length=1.0, unit_density=1.0,
               unit_velocity=1.0, verbose=true) -> InfoType

Read GADGET HDF5 snapshot metadata for output in path (a directory holding the snap…_NNN.hdf5 file, or the file itself) into a Mera InfoType (simcode = "GADGET"). GADGET is particle-based; feed the result to getparticles.

Units. GADGET data is in code units (commonly length kpc/h, mass 10¹⁰ M⊙/h, velocity km/s); the defaults treat the run as dimensionless. Supply the run's CGS unit_length/unit_density/ unit_velocity (and note the h factors) for physical conversions.

getinfo_pluto(output::Int, path::String; unit_length=1.0, unit_density=1.0,
              unit_velocity=1.0, verbose=true) -> InfoType

Read PLUTO static-grid metadata (grid.out + dbl.out) for snapshot output in path into a Mera InfoType (simcode = "PLUTO"). Uniform 3-D Cartesian grid → levelmin == levelmax. Feed the result to gethydro.

Units. PLUTO writes data in code units and does not store its UNIT_* constants in the output, so by default the run is treated as dimensionless (unit_* = 1) — Mera's scale system still works, but physical conversions like :kpc/:Msol are only meaningful if you supply the run's CGS units. Pass PLUTO's UNIT_LENGTH, UNIT_DENSITY, UNIT_VELOCITY (the unit_length/unit_density/unit_velocity keywords, in CGS) for a dimensional run and every getvar/projection unit conversion becomes physical:

# a galactic PLUTO run, say UNIT_LENGTH = 1 kpc, UNIT_DENSITY = m_p, UNIT_VELOCITY = 1 km/s
info = getinfo_pluto(5, path; unit_length=3.086e21, unit_density=1.67e-24, unit_velocity=1e5)
getvar(gethydro(info), :x, :kpc)        # now physically correct

getmask(obj, condition) -> BitVector
getmask(obj, quantity, predicate; unit=:standard) -> BitVector

Build a boolean selection mask over obj's rows from a value-space condition (FilterCondition, composable with &/|/!) or from a quantity/predicate pair (e.g. getmask(gas, :T, >(1e4); unit=:K)). The mask is computed vectorised through getvar, so it works on any derived quantity; pass it to getvar/projection/ statistics via their mask= keyword without copying the data.

Get mass-array from the dataset (cells/particles/clumps/...):

getmass(dataobject::HydroDataType)
getmass(dataobject::PartDataType)
getmass(dataobject::ClumpDataType)

return Array{Float64,1}

getmovie(path, quantity; unit=:standard, datatype=:hydro, outputs=:all, mera_files=false,
         direction=:z, los=nothing, up=nothing, theta=nothing, phi=nothing,
         inclination=nothing, azimuth=nothing, position_angle=nothing, axis=nothing,
         angle_unit=:deg, center=[:boxcenter], range_unit=:standard,
         xrange=[missing,missing], yrange=[missing,missing], zrange=[missing,missing],
         res=nothing, lmax=nothing, weighting=[:mass, missing],
         time_unit=:Myr, verbose=true) -> MeraMovie

Project quantity for every output of a simulation and collect the maps into a MeraMovie — the frames of a movie of the run evolving. Like timeseries it loads one snapshot at a time (RAM-safe) and discovers outputs the same way (RAMSES or mera_files).

The view is the full projection view and is held fixed across frames so the movie is steady. Axis-aligned by default (direction=:z); for an off-axis movie use any of projection's view controls — a los/up (e.g. from face_on/edge_on), the angles inclination/azimuth (or theta/phi, position_angle, with angle_unit), or axis=:angmom to auto-orient face-on. res/lmax and the region keywords cut cost per frame.

m  = getmovie("/data/sim", :sd)                              # face-up density movie, all outputs
fr = face_on(gethydro(getinfo(1, "/data/sim")))             # a fixed orientation …
m  = getmovie("/data/sim", :sd; los=fr.los, up=fr.up, center=fr.center)
savemovie(m, "density.gif")

Returns a MeraMovie; m.frames[k] is the 2D map of output m.outputs[k] at time m.times[k]. See savemovie to write a GIF.

getparticlemask(dataobject::PartDataType, select; verbose=true) -> Vector{Bool}

Boolean mask selecting a subset of particles, for use as the mask= argument of profile, phase, rotationcurve (and projection, getvar, …). select may be

• a named type — :all, :dm (:dark_matter), :stars (:star), :clouds (:sink), :debris, :other, :tracer (family ≤ 0), :gas (gas tracer, family 0);
• a family code Int, or a vector of codes (matched against the RAMSES :family column);
• a NamedTuple combining family and/or tag, e.g. (family=2,), (tag=3,), (family=2, tag=1).

On the new RAMSES particle format the :family/:tag columns are used (DM=1, star=2, cloud=3, debris=4, other=5, tracers ≤ 0). On the legacy format (no :family column) only :stars (birth ≠ 0) and :dm (birth == 0) are available via the :birth field; other selections raise an error. The required column must be among the loaded particle variables.

parts = getparticles(getinfo(1, "spiral_ugrid"))
profile(parts, :r_cylinder; weight=:mass, mask=getparticlemask(parts, :stars),
        center=[:bc], range_unit=:kpc, xunit=:kpc)
rotationcurve(parts; mask=getparticlemask(parts, :dm), center=[:bc], range_unit=:kpc)

Read the particle-data

• select variables
• limit to a spatial range
• multi-threading
• print the name of each data-file before reading it
• toggle verbose mode
• toggle progress bar
• pass a struct with arguments (myargs)

function getparticles( dataobject::InfoType;
                    lmax::Real=dataobject.levelmax,          # Maximum refinement level to read
                    vars::Array{Symbol,1}=[:all],            # Variables to read (:all for all available)
                    stars::Bool=true,                        # Include star particles
                    xrange::Array{<:Any,1}=[missing, missing], # X spatial range [min, max]
                    yrange::Array{<:Any,1}=[missing, missing], # Y spatial range [min, max]
                    zrange::Array{<:Any,1}=[missing, missing], # Z spatial range [min, max]
                    center::Array{<:Any,1}=[0., 0., 0.],     # Center point for ranges
                    range_unit::Symbol=:standard,            # Units for ranges (:standard, :kpc, etc.)
                    presorted::Bool=true,                    # Sort output table by key variables
                    print_filenames::Bool=false,             # Print each CPU file being read
                    verbose::Bool=true,                      # Print progress information
                    show_progress::Bool=true,                # Show progress bar
                    max_threads::Int=Threads.nthreads(),     # Number of threads for parallel processing
                    myargs::ArgumentsType=ArgumentsType() ) # Struct to override default arguments

Returns an object of type PartDataType, containing the particle-data table, the selected and the simulation ScaleType and summary of the InfoType

return PartDataType()

# get an overview of the returned fields:
# e.g.:
julia> info = getinfo(100)
julia> particles  = getparticles(info)
julia> viewfields(particles)
#or:
julia> fieldnames(particles)

Arguments

Required:

• dataobject: needs to be of type: "InfoType", created by the function getinfo

Predefined/Optional Keywords:

• lmax: maximum AMR level to load (default: info.levelmax)
• stars: include star particles (default: true). Set stars=false to drop star particles from the returned table. On the new RAMSES particle format (pversion > 0) this drops rows with family == 2; on the legacy format (no :family column) it drops rows with birth > 0 (RAMSES convention for stellar formation time). Requires the :family (new) or :birth (legacy) column to be in the loaded variable subset.
• var(s): the selected particle variables in arbitrary order: :all (default), :cpu, :mass, :vx, :vy, :vz, :birth :metals, ...
• xrange: the range between [xmin, xmax] in units given by argument range_unit and relative to the given center; zero length for xmin=xmax=0. is converted to maximum possible length
• yrange: the range between [ymin, ymax] in units given by argument range_unit and relative to the given center; zero length for ymin=ymax=0. is converted to maximum possible length
• zrange: the range between [zmin, zmax] in units given by argument range_unit and relative to the given center; zero length for zmin=zmax=0. is converted to maximum possible length
• range_unit: the units of the given ranges: :standard (code units), :Mpc, :kpc, :pc, :mpc, :ly, :au , :km, :cm (of typye Symbol) ..etc. ; see for defined length-scales viewfields(info.scale)
• center: in units given by argument range_unit; by default [0., 0., 0.]; the box-center can be selected by e.g. [:bc], [:boxcenter], [value, :bc, :bc], etc..
• presorted: presort data according to the key vars (by default)
• print_filenames: print on screen the current processed particle file of each CPU
• verbose: print timestamp, selected vars and ranges on screen; default: true
• show_progress: print progress bar on screen
• myargs: an ArgumentsType struct to override multiple keywords at once: lmax, xrange, yrange, zrange, center, rangeunit, verbose, showprogress
• **max_threads: give a maximum number of threads that is smaller or equal to the number of assigned threads in the running environment

Defined Methods - function defined for different arguments

• getparticles( dataobject::InfoType; ...) # no given variables -> all variables loaded
• getparticles( dataobject::InfoType, var::Symbol; ...) # one given variable -> no array needed
• getparticles( dataobject::InfoType, vars::Array{Symbol,1}; ...) # several given variables -> array needed

Examples

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

# Example 1:
# read particle data of all variables, full-box, all levels
julia> particles = getparticles(info)

# Example 2:
# read particle data of all variables
# data range 20x20x4 kpc; ranges are given in kpc relative to the box (here: 48 kpc) center at 24 kpc
julia> particles = getparticles( info,
                                  xrange=[-10., 10.],
                                  yrange=[-10., 10.],
                                  zrange=[-2., 2.],
                                  center=[24., 24., 24.],
                                  range_unit=:kpc )

# Example 3:
# give the center of the box by simply passing: center = [:bc] or center = [:boxcenter]
# this is equivalent to center=[24.,24.,24.] in Example 2
# the following combination is also possible: e.g. center=[:bc, 12., 34.], etc.
julia> particles = getparticles(    info,
                                    xrange=[-10.,10.],
                                    yrange=[-10.,10.],
                                    zrange=[-2.,2.],
                                    center=[33., :bc, 10.],
                                    range_unit=:kpc )

# Example 4:
# read particle data of the variables mass and the birth-time, full-box, all levels
julia> particles = getparticles( info, [:mass, :birth] ) # use array for the variables

# Example 5:
# read particle data of the single variable mass, full-box, all levels
julia> particles = getparticles( info, :mass ) # no array for a single variable needed
...

getparticles_gadget(info::InfoType; families=:all, xrange, yrange, zrange, center,
                    range_unit, verbose=true) -> PartDataType

Read the particles of a GADGET HDF5 snapshot described by info (from getinfo_gadget) into a PartDataType with columns (:x,:y,:z, :vx,:vy,:vz, :mass, :id, :family). :family is the GADGET particle type (0 gas, 1 halo/DM, 2 disk, 3 bulge, 4 stars, 5 boundary/BH). Restrict to a subset with families (e.g. families=[4] for stars, [1,4] for DM+stars).

xrange/yrange/zrange (+ center, range_unit) select a spatial window at load time — particles outside it are dropped per type as they are read, so a sub-region of a large snapshot never accumulates in memory (the RAMSES/grid getparticles convention).

getparticles_pluto(info::InfoType; verbose=true) -> PartDataType

Read a PLUTO Lagrangian-particle snapshot (particles.NNNN.dbl, single binary file with an ASCII # header) described by info into a Mera PartDataType — columns :x,:y,:z, :id, :vx,:vy,:vz (+ any extra PLUTO particle fields by name), so the particle analysis runs unchanged. Positions are in code length (= info units).

Get the x,y,z positions from the dataset (cells/particles/clumps/...):

getpositions( dataobject::DataSetType, unit::Symbol;
        direction::Symbol=:z,
        center::Array{<:Any,1}=[0., 0., 0.],
        center_unit::Symbol=:standard,
        mask::MaskType=[false])

return x, y, z

Arguments

Required:

• dataobject: needs to be of type: "DataSetType"

Predefined/Optional Keywords:

• center: in unit given by argument center_unit; by default [0., 0., 0.]; the box-center can be selected by e.g. [:bc], [:boxcenter], [value, :bc, :bc], etc..
• center_unit: :standard (code units), :Mpc, :kpc, :pc, :mpc, :ly, :au , :km, :cm (of typye Symbol) ..etc. ; see for defined length-scales viewfields(info.scale)
• direction: todo
• unit: return the variables in given unit
• mask: needs to be of type MaskType which is a supertype of Array{Bool,1} or BitArray{1} with the length of the database (rows)

Defined Methods - function defined for different arguments

• getpositions( dataobject::DataSetType; ...) # one given dataobject
• getpositions( dataobject::DataSetType, unit::Symbol; ...) # one given dataobject and position unit

Read RAMSES radiative-transfer (RT) leaf-cells into an RtDataType.

RT data have the same AMR cell structure as hydro. Each photon group g contributes a photon number density Npgand flux componentsFxg/Fyg/Fzg (so nvarrt = 4 * nGroups). Variable names come from info.rt_variable_list.

getrt(dataobject::InfoType;
      lmax::Real=dataobject.levelmax,
      vars::Array{Symbol,1}=[:all],
      xrange=[missing,missing], yrange=[missing,missing], zrange=[missing,missing],
      center=[0.,0.,0.], range_unit::Symbol=:standard,
      print_filenames::Bool=false, verbose::Bool=true, show_progress::Bool=true,
      myargs::ArgumentsType=ArgumentsType(), max_threads::Int=Threads.nthreads())

Returns an RtDataType with data (IndexedTable: position columns :cx,:cy,:cz, optionally :level/:cpu, then the selected RT variables), and info, lmin, lmax, boxlen, ranges, selected_rtvars, used_descriptors, scale.

info = getinfo(2, "…/rt_stromgren")
rt   = getrt(info)                       # all RT variables
rt   = getrt(info, vars=[:Np1, :Fx1])    # selected

getspectrum(c::LosCubeType, i::Integer, j::Integer) -> (centres, values)
getspectrum(c::LosCubeType; x, y, range_unit=c.range_unit) -> (centres, values)

The per-pixel line-of-sight spectrum from a LOS / velocity cube: the binned quantity distribution along the sightline through sky pixel (i,j), or — second form — through the pixel nearest the physical sky position (x, y) (offsets from the cube centre, in range_unit).

Returns the bin centres and the per-bin weight (e.g. mass), ready to plot as a line: lines(getspectrum(vc; x=0, y=0)...). For a velocity cube the centres are line-of-sight velocities (a synthetic emission-line profile); for a los_cube(:T) they are temperatures (a PDF). Integrating values over the bins recovers that pixel's column (the moment-0 value).

gettime(output::Real; path::String="./", unit::Symbol=:standard)
gettime(dataobject::DataSetType; unit::Symbol=:standard)
gettime(dataobject::InfoType, unit::Symbol=:standard)

Get the physical simulation time in selected units. Returns a Float64.

For a cosmological run (see iscosmological) info.time is conformal time, so gettime instead returns the age of the universe at the snapshot's scale factor (from cosmology), converted to unit. Supported units for cosmological runs: :Gyr, :Myr, :yr, :s (:standard ⇒ seconds). For a non-cosmological run the behaviour is unchanged (info.time scaled to unit).

gettime(1, path="/path/to/sim", unit=:Myr)
gettime(gas, unit=:Gyr)
gettime(info, :Myr)

Arguments Function 1

Required:

• output: give the output-number of the simulation

Predefined/Optional Keywords:

• path: the path to the output folder relative to the current folder or absolute path
• unit: return the variable in given unit

Arguments Function 2

Required:

• dataobject: needs to be of type: "DataSetType"

Predefined/Optional Keywords:

• unit: return the variable in given unit

Arguments Function 3

Required:

• dataobject: needs to be of type: "InfoType"

Predefined/Optional Keywords:

• unit: return the variable in given unit

Get variables or derived quantities from the dataset:

• overview the list of predefined quantities with: getinfo()
• select variable(s) and their unit(s)
• give the spatial center (with units) of the data within the box (relevant e.g. for radius dependency)
• relate the coordinates to a direction (x,y,z)
• pass a modified database
• pass a mask to exclude elements (cells/particles/...) from the calculation

getvar(   dataobject::DataSetType, var::Symbol;
        filtered_db::IndexedTables.AbstractIndexedTable=IndexedTables.table([1]),
        center::Array{<:Any,1}=[0.,0.,0.],
        center_unit::Symbol=:standard,
        direction::Symbol=:z,
        unit::Symbol=:standard,
        mask::MaskType=[false],
        ref_time::Real=dataobject.info.time)

return Array{Float64,1}

Arguments

Required:

• dataobject: needs to be of type: "DataSetType"
• var(s): select a variable from the database or a predefined quantity (see field: info, function getvar(), dataobject.data)

Predefined/Optional Keywords:

• filtered_db: pass a filtered or manipulated database together with the corresponding DataSetType object (required argument)
• center: in units given by argument center_unit; by default [0., 0., 0.]; the box-center can be selected by e.g. [:bc], [:boxcenter], [value, :bc, :bc], etc..
• center_unit: :standard (code units), :Mpc, :kpc, :pc, :mpc, :ly, :au , :km, :cm (of typye Symbol) ..etc. ; see for defined length-scales viewfields(info.scale)
• direction: todo
• unit(s): return the variable in given units
• mask: needs to be of type MaskType which is a supertype of Array{Bool,1} or BitArray{1} with the length of the database (rows)
• ref_time: reference zero-time for particle age calculation

Defined Methods - function defined for different arguments

• getvar( dataobject::DataSetType, var::Symbol; ...) # one given variable -> returns 1d array
• getvar( dataobject::DataSetType, var::Symbol, unit::Symbol; ...) # one given variable with its unit -> returns 1d array
• getvar( dataobject::DataSetType, vars::Array{Symbol,1}; ...) # several given variables -> array needed -> returns dictionary with 1d arrays
• getvar( dataobject::DataSetType, vars::Array{Symbol,1}, units::Array{Symbol,1}; ...) # several given variables and their corresponding units -> both arrays -> returns dictionary with 1d arrays
• getvar( dataobject::DataSetType, vars::Array{Symbol,1}, unit::Symbol; ...) # several given variables that have the same unit -> array for the variables and a single Symbol for the unit -> returns dictionary with 1d arrays

Examples

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

# Example 1: get the mass for each cell of the hydro data (1dim array)
mass1 = getvar(gas, :mass)  # in [code units]
mass = getvar(gas, :mass) * gas.scale.Msol # scale the result from code units to solar masses
mass = getvar(gas, :mass, unit=:Msol) # unit calculation, provided by a keyword argument
mass = getvar(gas, :mass, :Msol) # unit calculation provided by an argument


# Example 2: get the mass and |v| (several variables) for each cell of the hydro data
quantities = getvar(gas, [:mass, :v]) # in [code units]
returns: Dict{Any,Any} with 2 entries:
  :mass => [8.9407e-7, 8.9407e-7, 8.9407e-7, 8.9407e-7, 8.9407e-7, 8.9407e-7, 8…
  :v => [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0  …  2.28274e-7, 2.…

quantities = getvar(gas, [:mass, :v], units=[:Msol, :km_s]) # unit calculation, provided by a keyword argument
quantities = getvar(gas, [:mass, :v], [:Msol, :km_s]) # unit calculation provided by an argument

# Example 3: get several variables in the same units by providing a single argument
quantities = getvar(gas, [:vx, :vy, :vz], :km_s)
...

Radiative transfer (RT) quantities

For an RT run (rt = getrt(info)) the stored variables are, per photon group g, the photon number density :Np<g> and the flux components :Fx<g>, :Fy<g>, :Fz<g> (code units). Derived RT quantities on the RT object:

• :Fmag<g> flux magnitude |F_g| = √(Fx²+Fy²+Fz²) [code units]
• :Np_total photon number density summed over all groups [code units]
• :reducedflux<g> reduced flux f = |Fg| / (c·Npg), dimensionless in 0,1
• :Np<g>_cgs physical photon number density = Npg · unitnp [photons cm⁻³]
• :Fmag<g>_cgs physical flux magnitude = |Fg| · unitpf [photons cm⁻² s⁻¹]
• :photon_energy_density<g> radiation energy density of group g = Npg · unitnp · egyg [erg cm⁻³] (egyg = mean photon energy from info.descriptor.rt[:group_egy])
• :rad_energy_density total radiation energy density summed over all groups [erg cm⁻³]

The per-group photon properties parsed from info_rt (mean energy, energy bounds, photoionization cross-sections, species→group map) are available in info.descriptor.rtPhotonGroups ([g][:egy_eV], [:csn_cm2], [:cse_cm2], plus [:L0_eV], [:L1_eV], [:spec2group]).

The ionization fractions are passive hydro scalars (located via the RT descriptor info.descriptor.rt[:iIons]); request them on the hydro object (gas = gethydro(info)):

• :xHII, :xHeII, :xHeIII ionization fractions (dimensionless)
• :xHI neutral atomic-hydrogen fraction (a stored scalar with H2 chemistry, else the closure 1 − xHII; dimensionless)
• :xH2 molecular-hydrogen fraction = (1 − xHI − xHII)/2 (H2-chemistry runs only; ½ ⇒ fully molecular)
• :n_HII, :n_HI, :n_e, :n_H2 HII / HI / free-electron / H₂ number density cm⁻³
• :em_recomb recombination-emissivity proxy ∝ nₑ·nHII ≈ nHII² cm⁻⁶
• :mu RT-aware mean molecular weight from the ionization (and, with H2 chemistry, molecular) state and metallicity: μ = 1/[XH·hₚ + (XHe/4)(1+xHeII+2xHeIII) + Z/AZ], where hₚ = 1+xHII (no H2) or xHI+2·xHII+xH2 (H2); XH/XHe scaled by the local metal mass fraction Z (the :metallicity scalar, 0 if absent) and AZ≈16. Metal free electrons are neglected (RT does not track metal ionization).

• :T_rt gas temperature [K] using the local μ (= (P/ρ)·scale.Tmu·μ). Plain :T (unit=:K) bakes in a constant μ (= scale.K/scale.Tmu ≈ 1/0.76 ≈ 1.32, the fixed primordial default — independent of the run's X), so it over-estimates the ionized-gas temperature by μconst/μlocal (e.g. ≈1.32/0.5 ≈ 2.6× for fully-ionized pure hydrogen). Prefer :T_rt for RT runs.

rt   = getrt(info)
gas  = gethydro(info)
f    = getvar(rt, :reducedflux1)                 # reduced flux of group 1
nphot = getvar(rt, :Np1_cgs)                     # physical photon density [cm^-3]
xHII = getvar(gas, :xHII)                        # ionization fraction (hydro scalar)
ne   = getvar(gas, :n_e)                         # free-electron density [cm^-3]
T    = getvar(gas, :T_rt)                        # RT-aware temperature [K] (local μ)

:mu and :T_rt also work on non-RT hydro runs: without tracked ionization fractions they fall back to the constant μ Mera's temperature scaling assumes (μ = scale.K/scale.Tmu), so there `:Trtequalsgetvar(:T, :K). The other RT quantities (:xHII,:xHI,:n*,:emrecomb`) require an RT run and error otherwise.

RAMSES-RT field reference (physical quantity → Mera accessor):

Radiation–matter rates (RT object; use the reduced light speed rt_c_frac·c):

• :Gamma_HI<g>, :Gamma_HI HI photoionization rate per group / total [s⁻¹]
• :photoheating_HI<g>, :photoheating_HI HI photoheating rate per HI atom [erg s⁻¹]

Recombination (hydro object): :recomb_rate = αB(T)·nₑ·nHII cm⁻³ s⁻¹.

Combined radiation+gas — request on the RT object with the matching hydro_data (both loaded over the same cells); Mera asserts the cell sets align:

• :photoionizations = ΓHI·nHI [cm⁻³ s⁻¹]
• :ionization_balance = photoionizations − recombinations (≈0 in local equilibrium)

rt  = getrt(info);  gas = gethydro(info)            # same lmax/ranges → aligned cells
Γ   = getvar(rt, :Gamma_HI)                          # photoionization rate [1/s]
bal = getvar(rt, :ionization_balance, hydro_data=gas)  # Γ·n_HI − α_B·nₑ·n_HII  [cm^-3 s^-1]

Most RT quantities are single-object (photon fields on rt, ionization state on gas); only the coupling terms above need both. For other hydro variables you may also pass hydro_data=gas to getvar(rt, …) to fetch them aligned to the RT cells.

Get gravity data with hydro data as second positional argument

New simplified syntax:

# Single variable with unit
getvar(grav, hydro, :jeansmass, :Msol)

# Multiple variables with units  
getvar(grav, hydro, [:jeansmass, :epot], [:Msol, :erg])

# Multiple variables with same unit
getvar(grav, hydro, [:T, :cs], :K)

Get gravity data with optional hydro data for advanced energy analysis

Arguments:

• dataobject: needs to be of type: "GravDataType"
• var: select a variable from the database or a predefined quantity

Keyword Arguments:

• hydro_data: optional hydro data object for energy calculations that require density/mass
• center: center position (default: [0.,0.,0.])
• direction: direction for cylindrical coordinates (default: :z)
• ...

Examples:

# Basic gravity analysis
grav_data = getvar(grav, :epot)

# Advanced energy analysis with hydro data (keyword syntax)
energy_density = getvar(grav, :gravitational_energy_density, hydro_data=hydro)
binding_energy = getvar(grav, :gravitational_binding_energy, hydro_data=hydro)

# NEW: Simplified positional syntax
jeans_mass = getvar(grav, hydro, :jeansmass, :Msol)
thermal_energy = getvar(grav, hydro, :etherm, :erg)
mixed_analysis = getvar(grav, hydro, [:epot, :T, :jeanslength], [:erg, :K, :pc])

getvar_requirements(kind::Symbol, vars) -> Vector{Symbol}

The sorted set of physical stored variables that must be read to compute vars (a Symbol or a collection), with always-present geometry leaves (:cx/:cy/:cz, :level, :x/:y/:z, :cellsize, :volume, …) removed. Unknown/custom symbols are returned as-is (callers can detect these and fall back to reading everything).

getvar_requirements(:hydro, :ekin)        # [:rho, :vx, :vy, :vz]
getvar_requirements(:hydro, [:sd, :T])    # [:rho, :p]   (:sd is an alias of surface density → :rho)

Get the vx,vy,vz velocities from the dataset (cells/particles/clumps/...):

function getvelocities( dataobject::DataSetType, unit::Symbol;
    mask::MaskType=[false])

return vx, vy, vz

Arguments

Required:

• dataobject: needs to be of type: "DataSetType"

Predefined/Optional Keywords:

• unit: return the variables in given unit
• mask: needs to be of type MaskType which is a supertype of Array{Bool,1} or BitArray{1} with the length of the database (rows)

Defined Methods - function defined for different arguments

• getvelocities( dataobject::DataSetType; ...) # one given dataobject
• getvelocities( dataobject::DataSetType, unit::Symbol; ...) # one given dataobject and velocity unit

gridoverlay!(ax, go; color=(:white,0.3), linewidth=0.4)

Draw a gridoverlay result go onto a Makie axis ax (the AMR cell boundaries). Available after using Makie/CairoMakie.

gridoverlay(dataobject; level=:max, direction=:z, center=[:boxcenter], range_unit=:standard,
            xrange=[missing,missing], yrange=[missing,missing], zrange=[missing,missing],
            unit=:standard) -> (segments, extent, level)

Cell-boundary line segments of the AMR cells at one refinement level, viewed along direction (:x/:y/:z), for overlaying the AMR structure on a map. level is :max (default, the finest), :min, or an integer. The cell edges are de-duplicated.

The result is the 2-D footprint of that level's cells (collapsed along direction), so it suits both a projection and a slice:

• slice — pass a thin zrange (the slice plane) → the exact in-plane cell grid there;
• projection — use the full column → where that level's cells project to along the line of sight.

(The two coincide when the refined region is a column-aligned box, and differ for irregular refinement.)

Off-axis views work too: pass the same view keywords as projection — los/up, inclination/azimuth (or theta/phi, position_angle), axis=:angmom, or direction=:faceon/:edgeon. Each cell centre is projected through the camera basis and drawn as a cell-sized square (an approximate indicator; the true tilted-cube silhouette is a hexagon). Off-axis overlays are not edge-de-duplicated, so on dense AMR pick a coarser level or a sub-region to keep the segment count manageable.

Returns a NamedTuple: segments (a Vector{NTuple{4,Float64}} of (x1,y1,x2,y2) in the plane coordinates and unit), extent [xmin,xmax,ymin,ymax], and the level used. Plot with linesegments! — or, after using Makie, the convenience gridoverlay!(ax, go).

p  = projection(gas, :sd)
go = gridoverlay(gas; level=:max)         # the finest-cell grid, where it exists
# overlay go.segments on the heatmap of p.maps[:sd]

Convert a value to human-readable astrophysical units and round to ndigits

(pass the value in code units and the quantity specification (length, time) )

function humanize(value::Float64, scale::ScalesType003, ndigits::Int, quantity::String)

return value, value_unit

Get the simulation overview from RAMSES, saved in JLD2 == function getinfo

infodata(output::Int;
         path::String="./",
         fname = "output_",
         datatype::Any=:nothing,
         verbose::Bool=true)

return InfoType

Keyword Arguments

• output: timestep number
• path: the path to the output JLD2 file relative to the current folder or absolute path
• fname: "output"-> filename = "output***.jld2" by default, can be changed to "myname***.jld2"
• verbose:: informations are printed on the screen by default

Examples

# read simulation information from output `1` in current folder
julia> info = infodata(1) # filename="output_00001.jld2"

# read simulation information from output `420` in given folder (relative path to the current working folder)
julia> info = infodata(420, path="../MySimFolder/")

# or simply use
julia> info = infodata(420, "../MySimFolder/")



# get an overview of the returned field-names
julia> propertynames(info)

# a more detailed overview
julia> viewfields(info)
...
julia> viewallfields(info)
...
julia> namelist(info)
...
julia> makefile(info)
...
julia> timerfile(info)
...
julia> patchfile(info)
...

integrated_spectrum(c::LosCubeType; mask=nothing) -> (bins, values)

The integrated (global) spectrum of a LOS / velocity cube: the per-pixel spectra summed over the whole sky map (or over a boolean mask of size (nx, ny)) — the synthetic global line profile (e.g. an HI/CO single-dish profile). Returns the bin centres and the summed weight per channel. Summing values over the channels equals the cube's total deposited weight (the moment-0 total, e.g. the enclosed mass for a velocity cube).

interactive_mera_converter(input_dir::String, output_dir::String;
                                   safety_margin::Float64=DEFAULT_SAFETY_MARGIN,
                                   min_threads::Int=DEFAULT_MIN_THREADS,
                                   max_threads::Int=DEFAULT_MAX_THREADS)

Interactive mode for file conversion with comprehensive user guidance and system information.

This function provides a user-friendly interface that:

1. Displays comprehensive system information and constraints
2. Analyzes available files and detects potential issues
3. Guides user through range and thread count selection
4. Provides intelligent recommendations based on system state
5. Executes conversion with all safety monitoring features

User Experience Flow

System Information Display

• Shows CPU core count and memory configuration
• Displays current memory usage and safety margin status
• Indicates thread count limits and recommendations
• Warns about any current resource constraints

File Analysis and Validation

• Scans input directory for valid RAMSES files
• Reports total file count and available output ranges
• Detects and reports gaps in file sequences
• Helps user identify potential data integrity issues

Guided Parameter Selection

• Prompts for output number range with sensible defaults
• Recommends thread count based on system capacity and safety constraints
• Allows user override with explanation of implications
• Provides real-time feedback on selections

Safety-Monitored Execution

• Calls main conversion function with user-selected parameters
• Provides same comprehensive monitoring as batch function
• Returns complete results for user review

Parameters

• input_dir: Source directory containing old JLD2 files
• output_dir: Destination directory for converted files
• safety_margin: Memory usage threshold (default: 0.8 = 80%)
• min_threads: Minimum thread count (default: 1)
• max_threads: Maximum thread count (default: 64)

Example Usage

Basic interactive mode interactivemeraconverter("/data/old", "/data/new")

Conservative interactive mode for large files interactivemeraconverter("/data/old", "/data/new"; safetymargin=0.9, maxthreads=8)

iops_test(files; runs=3, levels=[1,2,4,8,16,24,32,48,64],
           max_threads=Threads.nthreads())

Measures file-open IOPS across thread counts. Returns (samples, stats, elapsed).

iscosmological(info::InfoType) -> Bool

Return true if the simulation is a cosmological RAMSES run, false for a non-cosmological ("idealised") run.

The decision uses the physical cosmology fields RAMSES writes into the info file. A non-cosmological run carries the sentinels aexp = 1 and omega_l = 0; any deviation (a dark-energy density, or a scale factor ≠ 1) marks a cosmological run.

info = getinfo(80, "…/yt_cosmo")
iscosmological(info)   # true

list_fields(kind::Symbol=:hydro; builtin::Bool=false) -> Vector{Symbol}

The registered derived-field names for a data-type kind (:hydro, :gravity, :rt, :particle, :clump), sorted.

By default only the user-added fields (registered with add_field) are returned — this is the back-compatible behaviour. With builtin=true the result also includes the built-in derived quantities known to the dependency registry (FIELD_DEPS[kind]), so you get a single combined list of everything resolvable for that kind:

list_fields(:hydro)                 # only the fields you added
list_fields(:hydro; builtin=true)   # built-in registry fields ∪ your custom fields

Note: builtin=true reflects the dependency registry, which covers most but not every built-in quantity (a few specialised fields, e.g. some RT-ionization variables, are computed directly in getvar without a registry entry). For the full human-readable catalogue call getvar() with no arguments.

list_units() -> Vector{Symbol}

The custom unit names registered with add_unit.

load_clumps(filename) -> ClumpCatalog

Reload a ClumpCatalog written by save_clumps.

load_synthetic_clumps(file_or_dir="."; download=false, url=Mera.SYNTH_URL) -> NamedTuple

Load the synthetic clump field, returning (; gas, particles, truth). file_or_dir is either the .jld2 file itself or a directory containing mera_synthetic_clumps.jld2.

With download=true the file is fetched from url (the GitHub release asset) when it is not already present locally. The stored objects are standard Mera data types, so every Mera verb (getvar, projection, clumpfind, …) works on them — using Mera is all that is needed.

D = load_synthetic_clumps(tempdir(); download=true)   # fetch once, then load
clumpfind(D.gas, ThresholdFoF(:rho; threshold=5.0, linking_length=2.0/2^7))

loadcube(filename; verbose=true) -> LosCubeType

Load a LOS / velocity cube saved with savecube from a JLD2 file (the .jld2 extension is added if missing). The cube, its axes, the binned quantity/units, the camera basis and the simulation info all round-trip, and the reconstructed cube is validated.

Read stored simulation data into a dataobject:

• supported datatypes: HydroDataType, PartDataType, GravDataType, ClumpDataType
• select a certain data range (data is fully loaded; the selected subregion is returned)
• toggle verbose mode

function loaddata(output::Int; path::String="./",
            fname = "output_",
            datatype::Symbol,
            xrange::Array{<:Any,1}=[missing, missing],
            yrange::Array{<:Any,1}=[missing, missing],
            zrange::Array{<:Any,1}=[missing, missing],
            center::Array{<:Any,1}=[0., 0., 0.],
            range_unit::Symbol=:standard,
            verbose::Bool=true,
            myargs::ArgumentsType=ArgumentsType() )

return dataobject

Arguments

Required:

• output: output number
• datatype: :hydro, :particles, :gravity, :clumps or :rt

Predefined/Optional Keywords:

• path: path to the file; default is local path.
• fname: default name of the files "output_" and the running number is added. Change the string to apply a user-defined name.
• xrange: the range between [xmin, xmax] in units given by argument range_unit and relative to the given center; zero length for xmin=xmax=0. is converted to maximum possible length
• yrange: the range between [ymin, ymax] in units given by argument range_unit and relative to the given center; zero length for ymin=ymax=0. is converted to maximum possible length
• zrange: the range between [zmin, zmax] in units given by argument range_unit and relative to the given center; zero length for zmin=zmax=0. is converted to maximum possible length
• range_unit: the units of the given ranges: :standard (code units), :Mpc, :kpc, :pc, :mpc, :ly, :au , :km, :cm (of typye Symbol) ..etc. ; see for defined length-scales viewfields(info.scale)
• myargs: pass a struct of ArgumentsType to pass several arguments at once and to overwrite default values of xrange, yrange, zrange, center, range_unit, verbose
• verbose: print timestamp and further information on screen; default: true

Defined Methods - function defined for different arguments

• loaddata(output::Int64; ...) # opens first datatype in the file
• loaddata(output::Int64, datatype::Symbol; ...)
• loaddata(output::Int64, path::String; ...)
• loaddata(output::Int64, path::String, datatype::Symbol; ...)

loadmap(filename; verbose=true) -> DataMapsType

Load a projection result saved with savemap from a JLD2 file (the .jld2 extension is added if missing). The whole AMRMapsType/PartMapsType round-trips — maps, units, geometry, camera basis, and info — ready to plot, re-project, or carry provenance.

loadmovie(filename; verbose=true) -> MeraMovie

Load a MeraMovie saved with savemovie(m, "….jld2"). The numeric frames and metadata round-trip exactly, so you can re-savemovie it to a GIF (with different tags/colormap) without re-running getmovie. JLD2-native, like loadmap/loadcube.

loadreport(filename) -> QuickReport

Reload a [QuickReport] written with render(report, :jld2) (or :file).

localdispersion(dataobject; patchsize=[500,:pc], components=(:vr_cylinder,:vϕ_cylinder,:vz),
                weight=:mass, vunit=:km_s, thermal=true, mu=1.0, Tvar=:T,
                center=[:bc], range_unit=:standard, mask=[false], min_cells_per_patch=20,
                quantiles=[0.16,0.5,0.84]) -> NamedTuple

Local (patch-de-streamed) velocity dispersion — turbulent ⊕ thermal. The TIGRESS/SILCC-style turbulence measure: the field of view is tiled into square patchsize patches in the (x, y) plane, the per-patch mass-weighted mean velocity is subtracted from every cell (so bulk rotation, shear and spiral streaming on scales larger than patchsize are removed), and the residual dispersion is the genuine small-scale turbulence below patchsize.

This differs from velocitydispersion, which removes the mean per radial bin: here the de-streaming is on a spatial grid, so it does not absorb non-circular streaming into "turbulence". Restrict the input first (e.g. shellregion to a solar annulus, and/or a midplane mask) — this returns aggregate scalars over the whole supplied region, not a radial profile.

Per the supplied region it returns the mass-weighted aggregate:

• sigma_r,sigma_phi,sigma_z (the components order), sigma_turb_3d = √(Σσ_i²), sigma_turb_1d = √(Σσ_i²/n);
• with thermal=true: sigma_thermal = √(k_B⟨T⟩/(μ m_H)), sigma_total = √(sigma_turb_1d²+sigma_thermal²);
• mach = sigma_turb_1d/⟨c_s⟩, anisotropy = sigma_z/σ_in-plane (for a 3-component triplet, z last);
• n_cell, n_eff (Kish), n_patch, and the patch-to-patch weighted percentiles of σtotal / Mach / anisotropy at quantiles (`sigmatotalq,machq,anisotropyq) — the physical region-to-region scatter, suitable as error bars. Only patches with ≥mincellsperpatch` cells enter the percentiles.

mu is the tracer mean molecular weight in H-atom masses (2.33 molecular, 1.0 atomic, 0.6 ionized).

log_env()

Prints Julia version, OS, CPU threads, timestamp, hostname, working directory, and project dependencies for reproducibility.

los_component(dataobject, vector; <view kwargs>, weight=:mass, unit=:standard,
              dispersion=false, res=256, pxsize=[size,:unit], center=[:bc], range_unit=:standard)
    -> NamedTuple(map, dispersion, los, up, cam_right, center, pixsize, range_unit, unit, x, y)

Mass-weighted 2D map of the line-of-sight component vector·ŵ of an arbitrary vector field, given as a 3-tuple of getvar symbols — e.g. (:vx,:vy,:vz) ⇒ vₗₒₛ, (:ax,:ay,:az) ⇒ LOS acceleration (gravity), (:bx,:by,:bz) ⇒ LOS magnetic field. dispersion=true returns the dispersion instead of the mean.

Returns a NamedTuple whose .map field holds the 2D array (the mean LOS component, or its dispersion when dispersion=true); the .dispersion flag, the camera basis (los/up/ cam_right), numeric center, pixsize, range_unit, unit, and the code-unit bin-edge axes x/y travel with it (so it can be fed to mock_observe and carries provenance).

los_cube(dataobject; quantity=:vlos, <view kwargs>, nbins=64, qrange=nothing, q_unit=:standard,
         weight=:mass, res=256, pxsize=[size,:unit], xrange=[missing,missing], yrange=[missing,missing], center=[:bc],
         range_unit=:standard, binning=:overlap, mask=[false]) -> LosCubeType

Off-axis line-of-sight distribution cube: cube[i,j,k] is the deposited weight (default mass) at sky pixel (i,j) in bin k of the line-of-sight quantity. The distribution along each sightline, per pixel — i.e. a "spectrum". quantity may be

• a scalar field name (:T, :rho, :cs, …) → its per-sightline distribution (a PDF),
• :vlos → the line-of-sight velocity (a spectral / velocity-channel cube), or
• a 3-vector of component names ((:vx,:vy,:vz), (:ax,:ay,:az), (:bx,:by,:bz)) → its line-of-sight component vector·ŵ.

The view is chosen with the same keywords as projection. binning accepts the centre-deposit previews :cic/:ngp and the hole-free footprint modes :overlap/:exact (default :overlap, recommended for maps when pixels are finer than cells). qrange (the LOS-axis range) is in the scaled q_unit; samples outside an explicit qrange are dropped. weight should be a cumulative/extensive quantity (:mass, default, or :volume) — it is summed along each sightline, so an intensive field like :rho/:T would give a non-physical "summed density" cube. Returns a LosCubeType; store it with savecube. los_moments gives the column/mean/dispersion maps. cube's sky-pixel edges x/y are in code length units.

los_moments(c::LosCubeType) -> (Σ, mean, dispersion)

Moment-0/1/2 maps of a LOS cube c: the column Σ (summed weight, e.g. column mass), the weight-weighted mean of the binned quantity, and its dispersion — each a 2D array.

Get a printout of the makefile:

makefile(object::InfoType)

map_amr_cells_to_grid!(grid, weight_grid, x_coords, y_coords, values, weights, 
                      level, grid_extent, grid_resolution, boxlen)

Map AMR cells from one refinement level to a regular 2D grid with proper geometric handling.

This is the core function that converts AMR simulation data to gridded projections. It handles the coordinate transformation from 1-based RAMSES grid indices to physical coordinates and properly accounts for cell size, overlap, and area weighting.

Arguments

• grid::AbstractMatrix{Float64}: Output grid for accumulated values (modified in-place)
• weight_grid::AbstractMatrix{Float64}: Output grid for accumulated weights (modified in-place)
• x_coords, y_coords::AbstractVector: AMR cell coordinates (1-based grid indices)
• values::AbstractVector{Float64}: Physical quantity values for each cell
• weights::AbstractVector{Float64}: Weighting values for each cell (usually mass)
• level::Int: AMR refinement level (determines cell size = boxlen/2^level)
• grid_extent::NTuple{4,Float64}: (xmin, xmax, ymin, ymax) in physical units
• grid_resolution::NTuple{2,Int}: (nx, ny) pixel dimensions of output grid
• boxlen::Float64: Physical size of simulation domain

Algorithm

1. Transform 1-based grid indices to physical coordinates
2. Calculate cell boundaries (center ± halfcellsize)
3. Find overlapping grid pixels using geometric intersection
4. Distribute cell value/weight proportionally to overlap area
5. Handle boundary cases and ensure no gaps in coverage

Performance Notes

• Uses @inbounds for speed in tight loops
• Pre-computes constants to avoid repeated calculations
• Conservative boundary handling prevents coordinate edge cases

map_amr_cells_to_grid_adaptive!(grid, weight_grid, x_coords, y_coords, values, weights, 
                               level, grid_extent, grid_resolution, boxlen; verbose=false)

Intelligent algorithm dispatcher that selects the optimal mapping approach based on data size.

This function analyzes the dataset characteristics and automatically chooses between:

• Direct mapping: Efficient for small-medium datasets (< 50k cells or < 10k pixels)
• Spatial indexing: Optimized for large datasets with spatial locality benefits

Performance Heuristics

• Large datasets (>50k cells + >10k pixels): Uses hierarchical spatial bins for O(n log n) performance
• Smaller datasets: Uses direct O(n×m) approach with better cache locality

Arguments

Same as base mapping function, plus:

• verbose::Bool=false: Print algorithm selection information

map_amr_cells_to_grid_surface_density!(grid, weight_grid, x_coords, y_coords, values, weights,
                                      level, grid_extent, grid_resolution, boxlen)

Specialized mapping function for surface density calculations with RAMSES-consistent precision.

This function is optimized for surface density (mass per unit area) projections where precise geometric overlap calculations are essential for accurate mass conservation. It uses the same coordinate transformation as the main mapping function but with additional safeguards for mass conservation.

Key Features

• RAMSES-consistent coordinate handling: (gridindex - 0.5) * cellsize
• Exact geometric overlap calculation for precise mass distribution
• Perfect alignment across all AMR refinement levels
• Mass conservation through careful area weighting

Arguments

Same as map_amr_cells_to_grid! but optimized for surface density calculations.

Algorithm

1. Transform coordinates using RAMSES convention
2. Calculate precise cell-pixel overlap areas
3. Distribute mass proportional to overlap area
4. Maintain exact mass conservation across refinement levels

map_amr_cells_to_grid_with_spatial_index!(grid, weight_grid, x_coords, y_coords, values, weights, 
                                         level, grid_extent, grid_resolution, boxlen)

High-performance mapping using hierarchical spatial indexing for large datasets.

This function implements a two-phase algorithm optimized for scenarios with many AMR cells:

1. Spatial Indexing Phase: Divides the grid into spatial bins and indexes which cells affect each bin
2. Processing Phase: Processes cells bin-by-bin for optimal cache locality and reduced redundant calculations

Performance Characteristics

• Time Complexity: O(n log n) vs O(n×m) for direct approach
• Memory: Uses spatial bins that scale with √n for optimal performance
• Cache Locality: Processes spatially adjacent cells together
• Best For: Datasets with >50k cells and large grids (>10k pixels)

Algorithm Details

• Adaptive Bin Sizing: Bin size adapts to cell count for optimal performance
• Hierarchical Indexing: Cells are indexed into spatial bins for fast lookup
• Same Coordinate System: Uses identical RAMSES coordinate transformation as direct method
• Identical Results: Produces exactly the same output as direct method, just faster

massfunctionplot(cat::ClumpCatalog; cumulative=false, nbins=20, kwargs...) -> Makie.Figure

Plot the clump mass function from a ClumpCatalog (via clump_massfunction): the differential dN per mass bin, or the cumulative N(≥M) when cumulative=true, on log axes. Needs a Makie backend loaded (using CairoMakie).