5.2. DISPATCH Cartesian AMR to RADMC-3D Export

5.2.1. Purpose

This document describes a proposed exporter converting Cartesian DISPATCH AMR snapshots into formats compatible with RADMC-3D.

The exporter shall support two output modes:

Regular Cartesian RADMC-3D grids (grid style 0)
Oct-tree AMR RADMC-3D grids (grid style 1)

The target audience is primarily Codex or similar AI-assisted code generation systems implementing the exporter.

5.2.2. Relevant RADMC-3D documentation

Primary references:

Key points from the RADMC-3D documentation:

Regular Cartesian grids use grid style 0.
Oct-tree AMR uses grid style 1.
Oct-tree AMR starts from a regular Cartesian root grid.
Physical field arrays are serialized in exact leaf traversal order.
Binary formats are strongly preferred for large models.

5.2.3. Objectives

The exporter shall:

operate directly on DISPATCH snapshot metadata and binary patch files;
ignore guard zones;
preserve authoritative leaf coverage;
support very large datasets;
minimize memory duplication;
optionally stream output incrementally.

5.2.4. Assumptions about DISPATCH snapshots

5.2.4.1. Patch structure

Each DISPATCH patch is assumed to contain:

Cartesian geometry;
fixed-size active cell arrays;
refinement level;
patch center coordinates;
physical patch size;
cell spacing;
binary payload excluding guard zones.

5.2.4.2. AMR assumptions

Initial implementation constraints:

Cartesian geometry only;
refinement factor exactly 2;
no rotated patches;
no curvilinear geometry;
no volleyball geometry.

These constraints may later be relaxed.

5.2.4.3. Authoritative ownership

Snapshot export must already have resolved overlaps.

At any physical location:

exactly one leaf patch is authoritative.

The exporter therefore operates only on authoritative leaf coverage.

5.2.5. Export modes

5.2.5.1. Regular Cartesian export

Purpose:

debugging;
visualization;
simplified RT setups;
validation against oct-tree export.

Method:

construct one global Cartesian raster;
interpolate authoritative DISPATCH leaf data onto that raster.

Resolution options:

user-defined;
or equivalent to finest AMR level.

Interpolation options:

nearest-cell;
trilinear;
conservative averaging.

Initial implementation should use nearest-cell mapping.

Generated files include:

amr_grid.inp
dust_density.binp
dust_temperature.bdat
gas_velocity.binp

using RADMC-3D grid style 0.

5.2.5.2. Oct-tree AMR export

5.2.5.2.1. Concept

DISPATCH is patch-based rather than oct-tree-based.

The exporter therefore reconstructs a synthetic oct-tree from:

patch refinement level;
integer logical coordinates;
Cartesian patch extents.

This synthetic oct-tree exists only in the exporter.

The exporter does not need to create synthetic DISPATCH patches, nor does it need DISPATCH itself to expose a native patch-tree matching the RADMC-3D oct-tree.

RADMC-3D requires only:

valid oct-tree topology;
correct leaf traversal order.

It does not require the original simulation to have used a native oct-tree.

5.2.5.2.2. Root grid construction

RADMC-3D oct-tree AMR begins from a regular Cartesian root grid.

Recommended strategy:

choose a root grid matching the coarsest DISPATCH patch tiling.

Example:

If the coarsest DISPATCH decomposition corresponds to 64x64x64 root cells, then choose:

Nx_root = 64
Ny_root = 64
Nz_root = 64

This minimizes synthetic refinement.

5.2.5.2.3. Logical indexing

Define canonical logical coordinates:

(level, ix, iy, iz)

with refinement spacing:

dx(level) = dx_root / 2^level

Patch extents are represented as integer index ranges.

5.2.5.2.4. Oct-tree reconstruction

Traversal begins from root cells.

For each logical cell:

if finer coverage exists, create a branch node;
otherwise emit a leaf node.

This proceeds recursively.

5.2.5.2.5. Missing siblings

Problem:

DISPATCH refinement does not necessarily generate complete octets.

RADMC-3D oct-tree refinement requires complete child sets once refinement begins.

Solution:

If some children exist and others are absent:

synthesize missing oct-tree child cells or nodes in the exported representation.

These are not synthetic DISPATCH patches. They are exporter-side oct-tree elements constructed directly from authoritative DISPATCH coverage and coarser-level values where needed.

Initial implementation:

use constant replication prolongation.

Advantages:

conservative;
exact parent averages preserved;
simple implementation.

Optional later enhancement:

trilinear prolongation for smoother gradients.

5.2.5.2.6. Leaf ordering

This is critical.

RADMC-3D serializes physical fields in exact oct-tree traversal order.

Therefore:

the tree descriptor;
all leaf-cell field arrays;

must use identical traversal order.

Any mismatch corrupts the dataset.

5.2.5.2.7. Recommended internal representation

Avoid pointer-heavy recursive structures.

Preferred representation:

contiguous node arrays;
Morton/Z-order indexing where practical.

Suggested node structure:

type octnode_t
  integer :: level
  integer :: ix, iy, iz
  logical :: leaf
  integer :: child(8)
  integer :: source_patch
end type

5.2.5.2.8. Streaming strategy

The exporter should avoid constructing the entire tree and all field arrays simultaneously in memory.

Recommended approach:

Pass 1:

construct topology only;
determine branch/leaf structure;
determine traversal order.

Pass 2:

stream field data in traversal order;
lazily read patch payloads as needed.

This enables scaling toward very large datasets.

5.2.5.2.9. Metadata overhead

RADMC-3D oct-tree metadata overhead is modest.

Approximate cost:

about 4 to 5 bytes per leaf cell.

This is typically negligible relative to physical field arrays.

5.2.6. Physical field mapping

5.2.6.1. Dust density

Typical mapping:

gas density multiplied by dust fraction;
or multiple explicit dust species.

Output:

dust_density.binp

5.2.6.2. Temperature

Temperature may either:

be exported directly from DISPATCH;
or later computed by RADMC-3D Monte Carlo equilibrium calculations.

5.2.6.3. Velocity

For line transfer:

gas_velocity.binp

containing:

vx;
vy;
vz;

per leaf cell.

5.2.6.4. Units

RADMC-3D expects CGS units.

Exporter must convert:

length -> cm
density -> g cm^-3
velocity -> cm s^-1

5.2.7. Coordinate conventions

RADMC-3D Cartesian grids use cell wall positions.

DISPATCH snapshots typically define:

cell centers;
cell sizes.

Exporter must reconstruct monotonic wall arrays.

5.2.8. Parallelization

Recommended initial implementation:

single-rank output generation.

Later enhancement possibilities:

distributed Morton sorting;
MPI-parallel topology generation;
parallel field streaming.

5.2.9. Validation tests

5.2.9.1. Uniform density

Single refinement level.

Expected result:

exact reproduction.

5.2.9.2. Single refined cube

Known refinement topology.

Verify:

branch structure;
leaf ordering;
geometry.

5.2.9.3. Spherical profile

Use analytic density profile.

Compare:

direct evaluation;
RADMC-rendered slices.

5.2.9.4. Overlap consistency

Verify:

no duplicated leaf coverage;
no missing regions.

5.2.10. Recommended implementation phases

5.2.10.1. Phase 1

Regular Cartesian export.

5.2.10.2. Phase 2

Oct-tree topology reconstruction directly from DISPATCH patch metadata and authoritative leaf coverage.

5.2.10.3. Phase 3

Synthetic oct-tree sibling completion for partially refined regions.

5.2.10.4. Phase 4

Streaming support for large datasets.

5.2.10.5. Phase 5

Velocity fields and line-transfer support.

5.2.11. Implementation language

Recommended workflow:

Python prototype;
Fortran production implementation.

Python advantages:

rapid experimentation;
leverage radmc3dPy utilities.

Fortran advantages:

direct DISPATCH integration;
scalable binary I/O;
MPI integration;
efficient streaming.