Subregions API Reference

Cutout sub-regions of the data base of DataSetType

• select shape of a region
• select size of a region (with or w/o intersecting cells)
• give the spatial center (with units) of the data relative to the full box
• relate the coordinates to a direction (x,y,z)
• inverse the selected region
• pass a struct with arguments (myargs)

subregion(dataobject::DataSetType, shape::Symbol=:cuboid;
            xrange::Array{<:Any,1}=[missing, missing],  # cuboid
            yrange::Array{<:Any,1}=[missing, missing],  # cuboid
            zrange::Array{<:Any,1}=[missing, missing],  # cuboid

            radius::Real=0.,              # cylinder, sphere
            height::Real=0.,              # cylinder
            direction::Symbol=:z,         # cylinder

            center::CenterType=[0.,0.,0.],     # all
            range_unit::Symbol=:standard,           # all
            cell::Bool=true,                        # hydro, gravity and RT (AMR cell data)
            inverse::Bool=false,                    # all
    periodic=false,                         # all
            verbose::Bool=true,             # all
            myargs::ArgumentsType=ArgumentsType() ) # all

Arguments

Required:

• dataobject: needs to be of type: "DataSetType"
• shape: select between region shapes: :cuboid, :cylinder/:disc, :sphere

Predefined/Optional Keywords:

For cuboid region, related to a given center:

• 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

For cylindrical region, related to a given center:

• radius: the radius between [0., radius] in units given by argument range_unit and relative to the given center
• height: the hight above and below a plane [-height, height] in units given by argument range_unit and relative to the given center
• direction: todo

For spherical region, related to a given center:

• radius: the radius between [0., radius] in units given by argument range_unit and relative to the given center

Keywords related to all region shapes

• 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 CORNER. That is the right origin for :cuboid, whose ranges are absolute box coordinates. For the distance-based shapes (:sphere, :cylinder, the shell forms) it places the region at the corner, so only the part inside the box is kept; that is a valid region but rarely the intent, and Mera says so once per shape. Give the box centre as [:bc] or [:boxcenter], a point as [x, y, z], or mix them: [value, :bc, :bc]. A single 0.0 component is fine (a sphere on the x = 0 face); only an all-zero centre triggers the note.
• inverse: inverse the region selection = get the data outside of the region
• cell: take intersecting cells of the region boarder into account (true) or only the cells-centers within the selected region (false)
• 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, radius, height, direction, center, range_unit, verbose

subregion(obj, region::AbstractRegion; split=true, inverse=false, nsub=8, verbose=true)

Select the data covered by a composable region (Sphere, Cuboid, Cylinder, SphericalShell, or any boolean combination ∩/∪/\/!). Works on hydro, gravity, RT (AMR cells) and particle data.

For AMR cell data with split=true (default) each kept cell carries an exact :fraction ∈ (0,1] — the volume fraction inside the region — and getvar(:mass) / getvar(:volume) / msum report the exact in-region totals (no boundary over/under- counting). With split=false whole cells are kept by a centre-inside test (the classic behaviour) and no :fraction is attached. nsub (default 8) is the per-axis sub-sampling of boundary cells for curved/composite regions (diminishing returns past ~8).

For particle data the region is a point-membership test (particles are points — there is no fractional volume, so split/nsub do not apply). inverse=true selects the complement.

Accuracy. With split=true an axis-aligned Cuboid is analytic (per-axis overlap product) and matches the exact volume to floating point; curved boundaries are sub-sampled nsub per axis and measure $-0.0015$ % on a 10 kpc sphere. For comparison, on the same sphere the centre test lands $+0.18$ % off with no guaranteed sign, and whole cells $+12$ % over — an upper bound whose size is set by the cell size at the boundary, not by the region. The "How Quantities Are Computed" page carries the full accuracy table.

refine::Int=0 (AMR cell data, split=true only) geometrically subdivides the boundary-straddling cells up to refine levels: each straddling cell is replaced by its octree children (rows at level+1 with the parent's field values — exact for the piecewise-constant AMR data), children fully inside keep fraction = 1, children fully outside are dropped, and still-straddling children recurse. Integrals (msum, volumes) are unchanged — they were already exact through :fraction — but the selection boundary becomes localised to cellsize/2^refine, so projections and maps of the sub-region render correspondingly sharper edges. Cost grows with the boundary area (≤ 8^refine per boundary cell; 2–3 is usually plenty).

refine_to = [length, unit] (e.g. [0.05, :kpc]; a plain number means code units) is the target-size variant: each straddling cell picks its OWN depth so its children are no larger than the given length — match it to a projection's pxsize and the rendered boundary becomes pixel-sharp regardless of the local AMR level. Mutually exclusive with refine; per-cell depth is capped at 10. Cost grows as (cellsize/target)³ per boundary cell, so scope the call to the area you will actually render.

Cutout sub-regions of the data base of DataSetType

• select shape of a shell-region
• select size of a region (with or w/o intersecting cells)
• give the spatial center (with units) of the data relative to the full box
• relate the coordinates to a direction (x,y,z)
• inverse the selected region
• pass a struct with arguments (myargs)

shellregion(dataobject::DataSetType, shape::Symbol=:cylinder;
            radius::Array{<:Real,1}=[0.,0.],  # cylinder, sphere;
            height::Real=0.,                  # cylinder
            direction::Symbol=:z,             # cylinder

            center::CenterType=[0., 0., 0.],   # all
            range_unit::Symbol=:standard,  # all
            cell::Bool=true,                        # hydro and gravity
            inverse::Bool=false,                    # all
    periodic=false,                         # all
            verbose::Bool=true,             # all
            myargs::ArgumentsType=ArgumentsType() ) # all

Arguments

Required:

• dataobject: needs to be of type: "DataSetType"
• shape: select between region shapes: :cylinder/:disc, :sphere

Predefined/Optional Keywords:

For cylindrical shell-region, related to a given center:

• radius: the inner and outer radius of the shell in units given by argument range_unit and relative to the given center
• height: the hight above and below a plane [-height, height] in units given by argument range_unit and relative to the given center
• direction: todo

For spherical shell-region, related to a given center:

• radius: the inner and outer radius of the shell in units given by argument range_unit and relative to the given center

Keywords related to all region shapes

• 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 CORNER. That is the right origin for :cuboid, whose ranges are absolute box coordinates. For the distance-based shapes (:sphere, :cylinder, the shell forms) it places the region at the corner, so only the part inside the box is kept; that is a valid region but rarely the intent, and Mera says so once per shape. Give the box centre as [:bc] or [:boxcenter], a point as [x, y, z], or mix them: [value, :bc, :bc]. A single 0.0 component is fine (a sphere on the x = 0 face); only an all-zero centre triggers the note.
• inverse: inverse the region selection = get the data outside of the region
• cell: take intersecting cells of the region boarder into account (true) or only the cells-centers within the selected region (false)
• 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 radius, height, direction, center, range_unit, verbose

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