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)

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

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

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

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.

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

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

AbstractRegion

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

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

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

Mutable Struct: Contains fields to use as arguments in functions

Below(quantity, value; unit=:standard)

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

BelowPercentile(quantity, p; unit=:standard)

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

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

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

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

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

CellLinkedList <: AbstractNeighborIndex

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

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

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

ClumpCatalog

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

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

ClumpDataType <: ContainMassDataSetType

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

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

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

Abstract Supertype of all datasets that contain mass variables

HydroPartType <: ContainMassDataSetType <: DataSetType

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

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

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

CoveringGridResult

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

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

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

Custom(f)

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

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

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

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

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

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

Abstract Supertype of all the different dataset types

HydroPartType <: ContainMassDataSetType <: DataSetType

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

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

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

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

Mutable Struct: Contains the collected information about the descriptors

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

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

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

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

FilterCondition

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

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 gravity data and information about the selected simulation

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

GravDataType <: DataSetType

Mutable Struct: Contains the collected information about grid

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

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

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

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

HashGrid <: AbstractNeighborIndex

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

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

HydroDataType <: HydroPartType

const HydroMapsType = AMRMapsType

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

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

HydroPartType <: ContainMassDataSetType <: DataSetType

IOBenchmark

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

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

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

Mutable Struct: Collected information about the selected simulation output

IsFinite(quantity; unit=:standard)

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

MassAbove(m)

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

MeraMovie

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

MinMembers(n)

Keep only clumps with at least n members.

MortonGrid <: AbstractNeighborIndex

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

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

PartDataType <: HydroPartType

Mutable Struct: Contains the collected information about particles

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

Fields

• maps::SortedDict{Symbol,Array{Float64,2}} — one 2D map per requested quantity, keyed by variable symbol (e.g. :sd surface density, :vx, :age). :sd is the column mass per pixel area; intensive variables are mass- or volume-weighted averages per pixel.
• maps_unit::SortedDict{Symbol,Symbol} — the physical unit of each map (e.g. :Msol_pc2, :km_s, :standard for code units), keyed by the same symbols as maps.
• maps_lmax::SortedDict — 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: Legacy physical-constants layout, retained so older mera/JLD2 files still load

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

Mutable Struct: Contains the physical constants in cgs units

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

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

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

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

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

Provenance

Reproducibility record returned by provenance: mera_version, simulation path, output, simcode, cosmological, the snapshot time_myr (physical time in Myr; the age of the universe for a cosmological run), redshift and aexp, boxlen, ndim, levelmin/levelmax, the serialized scale_type (e.g. :ScalesType003), and the output's file_ctime. Render a one-liner with provenance_string.

QuickLookResult

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

QuickReport

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

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

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

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

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

ReportResultCard

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

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

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

RtDataType <: DataSetType

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

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

Satisfies(quantity, f; unit=:standard)

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

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

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

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

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

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

Mutable Struct: Contains the unit scales of the loaded simulation

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

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

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

_check_unit_factor(factor, unit)

Reject a conversion factor that cannot be real.

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

_fov_selection(dataobject, fov, fov_unit, aperture, center) -> (src, win, fov_code)

Internal. Turn a camera-plane field of view into a ROTATION-INVARIANT selection, the same way rotation_sequence does: a cubic xrange/yrange/zrange window is a world-space box, so its projected outline — and the auto-fitted frame around it — changes with viewing angle, and its faces show up as straight edges across the image. A sphere projects to the same disc at every orientation, so the frame is fixed.

aperture=:circle selects a sphere of radius fov (the frame's corners are empty); aperture=:square selects radius √2·fov, which encloses the ±fov square at any angle, and the caller crops to that square for a full rectangular frame.

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

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.

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

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

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

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

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

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

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

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

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

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

See also wstat, center_of_mass, bulk_velocity.

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

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 = batchconvertmera("/data/old", "/data/new", 100, 200; requestedthreads=4, safetymargin=0.9)

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

Split 1:nfiles into chunks of size ≤ chunk.

bell(sound = nothing)

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

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

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

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

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

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

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

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

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

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

Legacy compatibility function for shell region functions.

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

Arguments

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

Returns

• Real: The input value unchanged

Note

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

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

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

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

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

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

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

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

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

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

See also checkoutputs, storageoverview.

clear_mera_cache!()

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

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

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

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

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

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.

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

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

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

Features:

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

Data Processing Workflow:

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

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

return statistics_dictionary

Arguments

Required:

• output: RAMSES output number to convert

Optional Keywords:

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

Return Value:

Returns a comprehensive statistics dictionary containing:

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

Method Overloads:

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

Threading Behavior:

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

Usage Examples:

Convert all datatypes with default settings and available threads

stats = convertdata(42, path, fpath)

Convert specific datatypes with threading control

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

Spatial selection with different compression

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

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

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

createconstants!(info::InfoType) -> InfoType

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

createconstants() -> PhysicalUnitsType

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

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

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

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

See also createconstants!, createscales, getunit.

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

return FileNamesType ```

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

function createscales!(dataobject::InfoType)

return ScalesType003

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

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

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

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

See also createscales!, createconstants, getunit.

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

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

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

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

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

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

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

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

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

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

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

enhanced_fortran_read(file_path, read_function; use_cache=true)

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

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

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

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

Arguments

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

Returns

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

estimate(plan::ReportPlan) -> NamedTuple

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

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

getextent(proj::DataMapsType, unit::Symbol=:standard; center::Bool=false) -> [xmin,xmax,ymin,ymax]

Map extent of a projection result in a physical unit (e.g. :kpc, :pc, :Mpc).

The stored proj.extent/proj.cextent fields are in code length units — so when the map values are physical (e.g. surface density in :Msol_pc2) the plotting axes would otherwise be mismatched. This scales them: getextent(proj, :kpc) gives [xmin,xmax,ymin,ymax] in kpc. center=true returns the centre-relative extent (proj.cextent). Equivalent to proj.extent .* proj.scale.<unit>.

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.

getgroups(info::InfoType; kwargs...)

Read the halo/group catalogue that accompanies info's snapshot, dispatching to the frontend registered for its simcode — for the GADGET-HDF5 family (AREPO, IllustrisTNG, …) that is getgroups_gadget.

Prefer this over the frontend-specific name: it is the generic entry point, matching getinfo / getparticles, and it does not ask you to know which reader serves your data. getinfo already reports the real producer (simcode == "AREPO" for IllustrisTNG), even though one frontend covers the whole shared format.

info = getinfo(33, "/path/to/TNG50-4")     # simcode = "AREPO"
gc   = getgroups(info)                      # FoF catalogue
gas  = getparticles(info; halo=0)           # that group's cells

getgroups_gadget(info::InfoType; fields=:all, verbose=true) -> NamedTuple

Read the FoF group catalogue of a SUBFIND run (AREPO / IllustrisTNG) into plain arrays.

Returns a NamedTuple with one entry per catalogue field (e.g. GroupMassType, GroupLenType, GroupPos, Group_M_Crit200), each concatenated across all catalogue chunks, plus :n (the number of groups) — checked against the header's Ngroups_Total, so a partial download is an error rather than a silently short catalogue.

Masses are in the file's own units (10¹⁰ M⊙/h for TNG); divide by info.H0/100 and multiply by 1e10 for M⊙. fields restricts which datasets are read.

info = getinfo(33, "/path/to/TNG50-4")
gc   = getgroups_gadget(info)
gc.n                                  # number of FoF groups
gc.GroupMassType[1, 1]                # group 1, gas mass  [1e10 Msol/h]

See getparticles_gadget with halo= to load one group's particles.

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_chombo(info; xrange, yrange, zrange, center, range_unit=:standard, verbose=true)

Read cell data from a Chombo HDF5 output into a HydroDataType, optionally restricted to a spatial range.

The Chombo-specific entry point behind gethydro, which dispatches here for Chombo data. Prefer gethydro, which keeps your script code-agnostic.

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_chombo(output, path; verbose=true)

Read the metadata of a Chombo HDF5 output: component names, level count and grid layout, returned as an InfoType.

The Chombo-specific entry point behind getinfo, which dispatches here when it detects a Chombo file. Prefer getinfo, which keeps your script code-agnostic.

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 its snap…_NNN.K.hdf5 chunks / a snapdir_NNN/ chunk directory — or a snapshot 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, vars=: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).

vars limits which stored gas columns are read — the usual dominant memory cost on a large snapshot. The nine base columns above always load; vars selects among :rho, :u, :ne, :metallicity, :sfr, :nh, :mach, :gpot, :bx, :by, :bz and :volume (derived from :rho, which it pulls in automatically). On a 16-chunk CAMELS snapshot: 21 columns 120 MB, vars=[:rho] 61 MB, vars=Symbol[] 51 MB. Derived quantities need their inputs — getvar(:T), :p and :cs come from :u — and say so clearly if it was not loaded. An unknown symbol is rejected immediately.

Multi-file snapshots (snap_NNN.0.hdf5 … snap_NNN.K.hdf5, optionally inside snapdir_NNN/ — the IllustrisTNG layout) are read chunk by chunk with the window applied per chunk. A particle type may be absent from chunk 0, so field discovery scans forward for a chunk that carries it; counts above 2³² are combined from NumPart_Total and NumPart_Total_HighWord. Without a spatial window the columns are sized from the header once, rather than grown per chunk.

getparticles_pluto(info::InfoType; xrange, yrange, zrange, center, range_unit, 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).

xrange/yrange/zrange with center and range_unit select a sub-box, with the same semantics as gethydro_pluto: a particle is kept when its position lies inside the box-normalised range. vars is not supported — every field in the file is returned.

Note this reader provides no :mass column, because PLUTO particle files do not carry one; mass-weighted reductions (msum, center_of_mass, default projection weighting) therefore have no input on PLUTO particles.

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

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

getunit(dataobject, quantity::Symbol, vars, units; uname=false) -> Real
getunit(info::InfoType, unit::Symbol; uname=false) -> Real

Return the numerical factor that converts quantity from Mera's internal code units into the requested unit, or 1.0 when :standard (code units) is asked for.

This is the conversion every getvar(gas, :rho, :g_cm3)-style call performs internally. Reach for it directly when you hold raw arrays and need the same factor Mera would apply — multiplying by it is exactly what the unit argument does.

getunit(info, :Msol)                       # grams-per-code-mass -> Msol factor
rho_cgs = getvar(gas, :rho) .* getunit(info, :g_cm3)   # equivalent to getvar(gas, :rho, :g_cm3)

With uname=true the unit's name is returned alongside the factor, which is what the plotting helpers use to label axes.

Mixing a code-unit array with a CGS constant is the classic source of silently wrong answers — this function is how you avoid it.

See also createscales, createconstants, getvar.

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(gas, :r_sphere, :kpc)                  # about the box CORNER (reminder shown)
getvar(gas, :r_sphere, :kpc, center=[:bc])    # about the box centre
getvar(gas, :x, :kpc)                         # absolute coordinates — no reminder

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]

hint(key::Symbol, headline, body...; verbose=true)

Internal. Render one of Mera's one-off hints, in the single house format every hint uses:

[Mera] Hint: <headline>
             <body line>
             (shown once per session; verbose(false) silences Mera's messages)

Does nothing if key has already been shown this session or output is off. headline says what happened in one line; body lines say what to do about it.

hint_once(key::Symbol; verbose=true) -> Bool

Internal. true the first time key is offered in this session, false afterwards — and always false when output is off, either for this call (verbose=false) or globally (verbose(false)). Callers emit their message only when it returns true.

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