Data Inspection API Reference

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

This is the starting point of almost every workflow, because gethydro, getparticles, getgravity and the rest all take the InfoType it returns. It reads headers only and never touches cell or particle data.

For a first impression of an unfamiliar output rather than an object to work with, see quicklook: it reports the same header facts and then reads a budgeted sample to add projections along all three axes, a phase diagram and a mass budget. Use getinfo in a script, quicklook when you open a directory and want to know what is in it.

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.

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

Get an overview of the fields from MERA composite types:

viewfields(object)

Get a detailed overview of many fields from the MERA InfoType:

viewallfields(dataobject::InfoType)

namelist(object::InfoType)
namelist(object::Dict{Any,Any})

Pretty-print the RAMSES namelist content stored in object.

For an InfoType, the namelist is read from the simulation's namelist.txt and stored in object.namelist_content. Each namelist block header and its parameters are printed to stdout.

Examples

info = getinfo(1, "path/to/sim")
namelist(info)               # show all namelist blocks
namelist(info.namelist_content)  # equivalent, passing the Dict directly

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::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::ClumpDataType)

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

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.

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

storageoverview(dataobject::InfoType; verbose::Bool=true)

Provide a storage overview for loaded data, showing memory usage and data structure information.

Arguments

• dataobject::InfoType: Simulation info object
• verbose: Control level of output detail

Description

Displays comprehensive information about the storage characteristics of the selected simulation output. It helps users understand the resource requirements and structure of their data.

For RAMSES outputs it tallies the on-disc size per file type — folder total, and the amr, hydro, gravity, particle, clump, rt and sink files present — returned in a Dict. For other codes (GADGET/AREPO, PLUTO, Athena++, FLASH, Chombo) every quantity is packed into one file or folder, so a per-datatype split is not meaningful; instead the snapshot's disc footprint is reported under :snapshot (the file size for a single-file snapshot, else the folder total).

Examples

# Get storage overview for hydro data
storageoverview(info, true)

# Brief storage information
storageoverview(info, false)

overviewplot(dataobject; size=nothing) -> Makie figure

Visual statistics overview of a loaded object (needs a Makie backend: using CairoMakie).

• Hydro / AMR: cells per level, mass per level, the mass-weighted density PDF, and the ρ–T phase diagram (when a temperature is available).
• Gravity / AMR: cells per level, the acceleration |a| and potential distributions, and the |a|–potential relation.
• Particles: the per-family census, the mass distribution, the projected x–y density, and the speed distribution.

All panels use getvar (physical units, derived fields) and are computed in one pass over the cells/particles — the visual companion to amroverview / dataoverview.

Get a list of all exported Mera types and functions:

function viewmodule(modulename::Module)

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

usedmemory(object, verbose::Bool=true)
usedmemory(obj_value::Real, verbose::Bool=true)

Calculate and display memory usage of an object or raw byte value in human-readable units.

Arguments

• object: Any Julia object whose memory usage should be calculated
• obj_value::Real: Raw memory size in bytes
• verbose::Bool=true: Whether to print the result to console

Returns

• value::Float64: Memory usage value in the appropriate unit
• unit::String: Unit string ("Bytes", "KB", "MB", "GB", or "TB")

Examples

# Check memory usage of a data object
data = rand(1000, 1000)
value, unit = usedmemory(data)  # Prints: "Memory used: 7.629 MB"

# Silent calculation
value, unit = usedmemory(data, false)  # Returns (7.629, "MB") without printing

# Direct byte value
value, unit = usedmemory(1048576, false)  # Returns (1.0, "MB")

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

return FileNamesType ```

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::CenterType=[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

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

getpositions( dataobject::DataSetType, unit::Symbol;
        direction::Symbol=:z,
        center::CenterType=[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

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

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

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

supports(info::InfoType, what::Symbol) -> Bool

Whether the reader that produced info provides the entry point what (one of :info, :hydro, :particles, :gravity, :rt, :clumps). This is a capability of the READER, not of the snapshot — e.g. supports(info, :hydro) is true for any RAMSES run even if that run wrote no hydro files.

info = getinfo(300, "sim/")        # e.g. a PLUTO run
supports(info, :hydro)             # true
supports(info, :gravity)           # false

register_reader!(code::Symbol; simcodes, name="", detect=nothing, priority=100,
                 note="", info=nothing, hydro=nothing, particles=nothing, groups=nothing,
                 gravity=nothing, rt=nothing, clumps=nothing)

Register a simulation-code frontend (internal API). code is the symbol accepted by getinfo(...; code=…); simcodes lists the InfoType.simcode strings the reader serves. Entry-function contracts:

• info(output::Int, path::String; verbose::Bool) → InfoType
• hydro(info::InfoType; xrange, yrange, zrange, center, range_unit, verbose) → HydroDataType
• particles(info::InfoType; xrange, yrange, zrange, center, range_unit, verbose) → PartDataType
• gravity / rt / clumps: analogous to hydro.

Wrap a function in a closure if it does not accept the full keyword set. The public entry points also pass any EXTRA user keywords through to the frontend (e.g. getparticles(info; families=[0]) reaches getparticles_gadget), so a frontend with code-specific options just declares them; unknown keywords raise its MethodError. A capability left nothing marks the code as not supporting it — the public entry points then raise a clear error, supports returns false, and the docs capability matrix shows a gap. detect (optional) is tried by detect_simcode before the built-in detection chain.

select_vars=true declares that the hydro entry point implements COLUMN SELECTION: it accepts vars=[…] and reads only what those columns need. gethydro then forwards the user's vars. By default it refuses a vars= it cannot honour, rather than silently returning every variable. Only claim this when the reader really reads less. A format whose records interleave every field cannot.

provenance(x) -> Provenance

Build a Provenance record from an InfoType or from any result that carries one: a data object (gethydro/getparticles/getgravity/getclumps/getrt), a projection map, or a velocity_cube/los_cube. Deterministic: it reads only the snapshot's own metadata, so it is safe to compare across runs.

gas = gethydro(getinfo(100, "/data/sim"))
provenance(gas)                      # data object
provenance(projection(gas, :sd))     # projection map
provenance(velocity_cube(gas))       # LOS / velocity cube
provenance(gas.info)                 # the InfoType directly

For a NamedTuple-style result that carries no .info (a pdf, a timeseries table, a position_velocity diagram), take the provenance of the source data object you computed it from.

provenance_string(x) -> String

A compact one-line provenance string, ready for a figure caption, a COMMENT card when you export to FITS, or a log. Accepts the same inputs as provenance (or a Provenance). The time is shown as z=… for a cosmological run, otherwise in Myr/Gyr.

The version names the build. On a normal install it is the plain version; on a git checkout it carries the branch and commit, and marks an uncommitted working tree, so a result made on a development version cannot be mistaken for one made on the release:

Mera v1.8.0 | mw_L10/output_00300 | 445.89 Myr | L=48.0 ndim=3 lmin=6 lmax=10 | ScalesType003
Mera v1.8.0 (dev multicode @ 3a91f2c +uncommitted) | mw_L10/output_00300 | 445.89 Myr | ...

Set the environment variable MERA_PROVENANCE_PLAIN=1 to force the plain version, which is how these pages are rendered.

mera_build() -> String

Which Mera actually ran, as a string. On a registered install this is the version, "1.8.0". On a git checkout it adds the branch and the commit, and marks a working tree with uncommitted changes, "1.8.0 (dev multicode @ 3a91f2c +uncommitted)", because pkgversion alone reports the same version either way and cannot tell a release from somebody's branch.

Use it when you share a script or a notebook, so a reader knows what produced the result. It is the version field of provenance_string. Set MERA_PROVENANCE_PLAIN=1 to force the plain version. Never throws: if git is absent or the checkout is unreadable, it falls back to the version.

quicklook(output; path=".", budget=2_000_000, read=true, res=256, lmax=nothing,
          particle_subsample=1.0, datatypes=[:hydro,:stars,:dm], directions=[:z,:x,:y],
          verbose=true) -> QuickLookResult

A first impression of a simulation output. Reads the header for instant facts (box, levels, finest cell, time/redshift, and the cell & particle census) and — unless read=false — does a single budgeted hydro read (only the coarse AMR levels when the full output would exceed budget cells), then builds surface-density projections along each axis (.maps.x/.y/.z — face-on plus the two edge-on views), a ρ–T phase diagram, a global snapshot budget (gas / stellar / dark-matter mass and the current SFR), and prints a compact dashboard. On an MHD run it additionally reads the magnetic field and adds a face-on |B| map (.maps.bmag, μG) plus |B| and plasma-β ranges.

How long it takes. read=false returns immediately whatever the run size: it touches no data. A reading call is dominated by the number of per-CPU files, not by the box size, because every one of them has to be opened. On a 640-CPU output that is tens of seconds; on a run with several thousand CPU domains, expect minutes. The reader threads over those files, so julia -t N helps, and progress is printed as it goes. budget and lmax reduce the cells taken from each file but not the number of files opened; only a spatial range does that, by skipping the CPU domains that fall outside it (see gethydro's xrange/yrange/zrange).

• budget — cell-count cap; if the full output is predicted larger, only coarse levels are read and the result is flagged sampled=true (estimates labelled APPROXIMATE). lmax overrides the choice.
• read=false — header-only (sub-second): box, levels, finest cell, ncpu, fields, time/redshift.
• res — pixel size of the quick map.
• datatypes — which components to show, any subset of [:hydro, :stars, :dm] (default all that are present). [:hydro] reads gas only; [:stars] or [:dm] skip the gas read entirely (faster); the panels and census adapt to what was read.
• directions — which projection axes, any subset of [:z, :x, :y] (:z = face-on for a disk in the xy-plane; :x, :y = the two edge-on views). Applies to the gas maps and to the stellar and dark-matter maps alike. Use directions=[:z] for a single, compact map per component. The face-on map keeps the bare key (q.maps.stars); edge-on views are q.maps.stars_x / .stars_y (and dm_x / dm_y).
• particle_subsample — for very large particle runs, read only ~this fraction of the particle CPU files (e.g. 0.1); RAMSES balances ~equal particles per CPU, so this reads ~that fraction of particles (skipping whole files → cuts I/O & memory). The particle census, masses and SFR are then scaled up by 1/fraction and flagged approximate. (Gas is bounded separately by budget/lmax.)

When a particle file is present, the budget includes the stellar and dark-matter mass and the current star-formation rate (10/100 Myr windows + lifetime mean, see sfr_snapshot); these are exact even when the hydro read is coarse. Returns a QuickLookResult; figure/summary data is in .maps, .phase, .budget.

For radial density profiles and any other composable cards, use report — the composable form of this first look: report(output) runs a default card trio (map, phase, radial profile), and you can add/replace cards (projections, phases, profiles, SFR, scalars, …) and render to ascii / plot / JLD2 / file.

Not a replacement for getinfo. With read=false the two report much the same header facts, but getinfo returns the InfoType that gethydro, getparticles and the other readers require, so it is what a script calls. quicklook returns a QuickLookResult and is what you call on a directory you have not seen before.

quicklookplot(q::QuickLookResult; kwargs...) -> Makie.Figure

Render a QuickLookResult as a multi-panel dashboard that adapts to what was read: gas surface density along each requested axis (:z face-on, :x/:y edge-on), face-on stellar and dark-matter surface density when particles are present, the ρ–T phase diagram, and a text census (cells, particles, masses, SFR, ranges). Panels fill a tight 3-column grid; colormaps are the colorblind-safe viridis/inferno. Needs a Makie backend loaded (using CairoMakie or GLMakie); the figure is returned, so save it with Makie.save("ql.png", fig).

using CairoMakie
q = quicklook(300; path="…")
fig = quicklookplot(q)

Get a printout of the makefile:

makefile(object::InfoType)

Get a printout of the patchfile:

patchfile(object::InfoType)

Get a printout of the timerfile:

timerfile(object::InfoType)