RADMC3D – Nautilus coupling#

The nautilus.coupling module handles the coordinate transformation and interpolation between the RADMC3D spherical grid and the Nautilus Cartesian chemistry grid.

Overview#

RADMC3D operates on a spherical grid \((r, \theta, \phi)\), while Nautilus uses a Cartesian grid \((R, z)\). The full workflow has two directions:

  1. RADMC3D → Nautilus (pre-chemistry): physical quantities (density, temperature, UV field, visual extinction) are remapped from the spherical RT grid onto the Cartesian chemistry columns and written as Nautilus input files by write_nautilus().

  2. Nautilus → RADMC3D (post-chemistry): chemical abundances from the completed Nautilus run are converted back to number densities on the spherical RT grid and written as numberdens_XXX.inp files for line radiative transfer with RADMC3D.

The main coupling functions are:

  • dust_density: remaps dust mass densities and converts to number densities

  • dust_temperature / dust_temperature_single: remaps dust temperatures

  • av_z: computes visual extinction from the RADMC3D local radiation field

  • to_spherical: remaps Nautilus chemical abundances back to the RADMC3D grid

Coordinate conversion#

For a point at Cartesian coordinates \((R, z)\), the corresponding spherical coordinates are:

\[d = \sqrt{R^2 + z^2}, \qquad \theta = \arccos\left(\frac{z}{d}\right)\]

Important

The RADMC3D grid radii (stored in grid.r) are in AU, while the chemistry grid coordinates (grid.rchem, grid.zchem) are passed in cm. The coupling functions convert internally using autocm (AU to cm conversion factor).

Converting RADMC-3D to Nautilus input files#

Density coupling#

dust_density uses bilinear interpolation (RegularGridInterpolator) to remap RADMC3D dust densities onto the chemistry grid. For each grain size:

  1. Extract the 2D density field \(\rho(r, \theta)\) from the RADMC3D data

  2. Interpolate onto the chemistry grid points \((d, \theta)_\mathrm{chem}\)

  3. Convert mass density to number density: \(n_d = \rho_d / m_\mathrm{grain}\)

The gas number density is derived either from the dust-to-gas ratio or from a custom surface density profile.

Temperature coupling#

Two variants exist:

  • dust_temperature / dust_temperature_single: use physical \(z\) coordinates (for set_chem_grid)

  • dust_temperature_disk / dust_temperature_single_disk: use scale-height coordinates (for set_chemdisk_grid)

Both use bilinear interpolation (RegularGridInterpolator) similarly to the dust density.

UV extinction coupling#

av_z computes the visual extinction by comparing the local UV radiation field (from RADMC3D’s local_field) to the unattenuated blackbody spectrum. The extinction in magnitudes is:

\[A_V = -2.5 \log_{10}\left(\frac{F_\mathrm{local}}{F_\mathrm{unattenuated}}\right)\]

Converting Nautilus abundances back to RADMC-3D#

After your Nautilus simulation has completed, use add_chemistry() followed by convert_nautilus2radmc() to create the numberdens_XXX.inp files that RADMC-3D needs for line radiative transfer.

import astromugs.pipeline as pipeline

pipe1 = pipeline.Interface()
pipe1.add_thermal_path(thermpath)   # path to the RADMC-3D thermal output directory
pipe1.add_chemical_path(chempath)   # path to the Nautilus chemistry directory

# Load the chemistry output.
# itime selects which timestep is used for the conversion (default: -1 = last output).
pipe1.add_chemistry(itime=-1)

# Write numberdens_CO.inp into thermpath
pipe1.convert_nautilus2radmc(species='CO', numberdens=True)

# Multiple species at once
pipe1.convert_nautilus2radmc(species=['CO', 'HCO+', 'N2H+'], numberdens=True)

add_chemistry() reads the binary abundances.out files from all completed XXAU/ sub-folders, converts fractional abundances to number densities (\(n_X = n_\mathrm{H} \times (n_X / n_\mathrm{H})\) in cm-3), and stores the result in pipe1.grid.chemmodel, keyed first by species name then by radius in AU.

convert_nautilus2radmc() then calls nautilus.coupling.to_spherical() to remap each chemistry column onto the full RADMC-3D spherical grid by bilinear interpolation (RegularGridInterpolator), and writes the result to numberdens_XXX.inp in thermpath.

The interpolation works in two steps:

  1. Each vertical column (one per radius) is resampled onto a common \(z\) grid built from the union of all column \(z\) arrays. This handles the fact that different radii may have different numbers of vertical points after surface truncation (controlled by min_gas_density in write_nautilus()). Points above a column’s truncation height are set to zero; points below the midplane use the midplane value.

  2. The resulting regular 2-D field \(n_X(R_\mathrm{cyl}, z)\) is passed to RegularGridInterpolator, which evaluates it at every spherical cell centre \((d \sin\theta,\, |d \cos\theta|)\) in one vectorised call.

Note

The Nautilus chemistry grid typically has far fewer radial points than the RADMC-3D grid. Bilinear interpolation produces smooth abundance maps between chemistry columns, avoiding the step discontinuities that nearest-neighbour assignment would introduce. Cells inside the inner chemistry radius are set to 1e-20; cells outside the outermost radius are set to 0.

Note

add_chemistry() silently skips any radius whose abundances.out is not yet present (e.g. still running on a cluster). You can call it again later and then repeat convert_nautilus2radmc() once more radii have finished.

API Reference#

astromugs.nautilus.coupling.moving_average(x, w)[source]#

Compute a moving average using a uniform convolution kernel.

Parameters:

  • x (array_like) – Input array to smooth.

  • w (int) – Width of the rolling window (number of points).

Returns:

Smoothed array with the same length as x.

Return type:

numpy.ndarray

astromugs.nautilus.coupling.dust_density(dtogas, rho_m, sizes, dens_radmc3d, rchem, zchem, d, theta)[source]#

Interpolate RADMC3D dust density onto the Nautilus chemistry grid.

Converts dust mass densities from the RADMC3D spherical grid to the Nautilus cylindrical grid using bilinear interpolation, preserving radial drift gradients and smooth disk boundaries. Returns both dust number densities per grain size and gas number density.

Parameters:

  • dtogas (float) – Dust-to-gas mass ratio.

  • rho_m (float) – Material (intrinsic) density of dust grains, in g/cm^3.

  • sizes (array_like) – Array of grain radii for each dust species, in cm.

  • dens_radmc3d (numpy.ndarray) – Dust mass density from RADMC3D with shape (nbspecies, nphi, ntheta, nr), in g/cm^3.

  • rchem (numpy.ndarray) – Radial grid of the Nautilus chemistry model, in cm.

  • zchem (numpy.ndarray) – Vertical grid of the Nautilus chemistry model with shape (nrchem, nzchem), in cm. Values can differ per radius.

  • d (numpy.ndarray) – Radial (spherical) distance grid of the RADMC3D model, in AU.

  • theta (numpy.ndarray) – Co-latitude grid of the RADMC3D model, in radians.

Returns:

  • dens_naut_nd (numpy.ndarray) – Dust number density per grain size, shape (nbspecies, nrchem, nzchem), in cm^-3.

  • dens_naut_nH (numpy.ndarray) – Gas hydrogen number density, shape (nrchem, nzchem), in cm^-3.

astromugs.nautilus.coupling.dust_temperature_disk(temp_radmc3d, rchem, zchem, d, theta, hg=None)[source]#

Remap multi-species RADMC3D dust temperatures onto the Nautilus grid using scale heights.

Converts temperatures from the RADMC3D spherical grid to the Nautilus cylindrical grid via bilinear interpolation, then smooths vertical profiles with a 5-point moving average.

Parameters:

  • temp_radmc3d (numpy.ndarray) – Dust temperature from RADMC3D with shape (nbspecies, nphi, ntheta, nr), in K.

  • rchem (numpy.ndarray) – Radial grid of the Nautilus chemistry model, in cm.

  • zchem (numpy.ndarray) – Normalised vertical grid points (dimensionless, scaled by hg).

  • d (numpy.ndarray) – Radial (spherical) distance grid of the RADMC3D model, in AU.

  • theta (numpy.ndarray) – Co-latitude grid of the RADMC3D model, in radians.

  • hg (array_like, optional) – Gas scale height at each radial point, in cm. Used to convert normalised zchem to physical heights.

Returns:

Smoothed dust temperature on the Nautilus grid with shape (nbspecies, nrchem, nzchem), in K.

Return type:

numpy.ndarray

astromugs.nautilus.coupling.dust_temperature_single_disk(temp_radmc3d, rchem, zchem, d, theta, hg=None)[source]#

Remap single-species RADMC3D dust temperature onto the Nautilus grid using scale heights.

Same as dust_temperature_disk but for a single dust species (no species dimension). Uses nearest-neighbor lookup followed by 5-point moving-average smoothing of vertical profiles.

Parameters:

  • temp_radmc3d (numpy.ndarray) – Dust temperature from RADMC3D with shape (nphi, ntheta, nr), in K.

  • rchem (numpy.ndarray) – Radial grid of the Nautilus chemistry model, in cm.

  • zchem (numpy.ndarray) – Normalised vertical grid points (dimensionless, scaled by hg).

  • d (numpy.ndarray) – Radial (spherical) distance grid of the RADMC3D model, in AU.

  • theta (numpy.ndarray) – Co-latitude grid of the RADMC3D model, in radians.

  • hg (array_like, optional) – Gas scale height at each radial point, in cm. Used to convert normalised zchem to physical heights.

Returns:

Smoothed dust temperature on the Nautilus grid with shape (nrchem, nzchem), in K.

Return type:

numpy.ndarray

astromugs.nautilus.coupling.dust_temperature(temp_radmc3d, rchem, zchem, d, theta)[source]#

Remap multi-species RADMC3D dust temperatures onto the Nautilus grid.

Converts temperatures from the RADMC3D spherical grid to the Nautilus cylindrical grid via bilinear interpolation, where zchem provides physical heights per radius. Vertical profiles are smoothed with a 5-point moving average.

Parameters:

  • temp_radmc3d (numpy.ndarray) – Dust temperature from RADMC3D with shape (nbspecies, nphi, ntheta, nr), in K.

  • rchem (numpy.ndarray) – Radial grid of the Nautilus chemistry model, in cm.

  • zchem (numpy.ndarray) – Vertical grid with shape (nrchem, nzchem), in cm. Heights can differ per radial point.

  • d (numpy.ndarray) – Radial (spherical) distance grid of the RADMC3D model, in AU.

  • theta (numpy.ndarray) – Co-latitude grid of the RADMC3D model, in radians.

Returns:

Smoothed dust temperature on the Nautilus grid with shape (nbspecies, nrchem, nzchem), in K.

Return type:

numpy.ndarray

astromugs.nautilus.coupling.dust_temperature_single(temp_radmc3d, rchem, zchem, d, theta)[source]#

Remap single-species RADMC3D dust temperature onto the Nautilus grid.

Same as dust_temperature but for a single dust species (no species dimension). Uses nearest-neighbor lookup followed by 5-point moving-average smoothing of vertical profiles.

Parameters:

  • temp_radmc3d (numpy.ndarray) – Dust temperature from RADMC3D with shape (nphi, ntheta, nr), in K.

  • rchem (numpy.ndarray) – Radial grid of the Nautilus chemistry model, in cm.

  • zchem (numpy.ndarray) – Vertical grid with shape (nrchem, nzchem), in cm. Heights can differ per radial point.

  • d (numpy.ndarray) – Radial (spherical) distance grid of the RADMC3D model, in AU.

  • theta (numpy.ndarray) – Co-latitude grid of the RADMC3D model, in radians.

Returns:

Smoothed dust temperature on the Nautilus grid with shape (nrchem, nzchem), in K.

Return type:

numpy.ndarray

astromugs.nautilus.coupling.local_field()[source]#

Compute the local radiation field (placeholder, not yet implemented).

astromugs.nautilus.coupling.avz_disk(field_radmc3d, lam_mono, R_star, T_star, rchem, zchem, d, theta, hg)[source]#

Compute the vertical visual extinction map using scale-height-based vertical coordinates.

Integrates the RADMC3D radiation field over UV wavelengths, remaps it onto the Nautilus cylindrical grid (with heights derived from gas scale heights), and computes Av by comparing the attenuated field to an unattenuated blackbody reference.

Parameters:

  • field_radmc3d (numpy.ndarray) – Monochromatic mean intensity from RADMC3D with shape (nlam, nphi, ntheta, nr), in cgs units.

  • lam_mono (numpy.ndarray) – Wavelength grid of the radiation field, in microns.

  • R_star (float) – Stellar radius, in cm.

  • T_star (float) – Stellar effective temperature, in K.

  • rchem (numpy.ndarray) – Radial grid of the Nautilus chemistry model, in cm.

  • zchem (numpy.ndarray) – Normalised vertical grid points (dimensionless, scaled by hg).

  • d (numpy.ndarray) – Radial (spherical) distance grid of the RADMC3D model, in AU.

  • theta (numpy.ndarray) – Co-latitude grid of the RADMC3D model, in radians.

  • hg (array_like) – Gas scale height at each radial point, in cm.

Returns:

Visual extinction Av on the Nautilus grid with shape (nrchem, nzchem), in magnitudes.

Return type:

numpy.ndarray

astromugs.nautilus.coupling.av_z(field_radmc3d, lam_mono, R_star, T_star, rchem, zchem, d, theta)[source]#

Compute the vertical visual extinction map using physical vertical coordinates.

Integrates the RADMC3D radiation field over UV wavelengths, remaps it onto the Nautilus cylindrical grid (where zchem contains physical heights per radius), and derives Av by comparing the attenuated field to an unattenuated blackbody reference. Both vertical and radial profiles are smoothed with a 5-point moving average.

Parameters:

  • field_radmc3d (numpy.ndarray) – Monochromatic mean intensity from RADMC3D with shape (nlam, nphi, ntheta, nr), in cgs units.

  • lam_mono (numpy.ndarray) – Wavelength grid of the radiation field, in microns.

  • R_star (float) – Stellar radius, in cm.

  • T_star (float) – Stellar effective temperature, in K.

  • rchem (numpy.ndarray) – Radial grid of the Nautilus chemistry model, in cm.

  • zchem (numpy.ndarray) – Vertical grid with shape (nrchem, nzchem), in cm. Heights can differ per radial point.

  • d (numpy.ndarray) – Radial (spherical) distance grid of the RADMC3D model, in AU.

  • theta (numpy.ndarray) – Co-latitude grid of the RADMC3D model, in radians.

Returns:

Smoothed visual extinction Av on the Nautilus grid with shape (nrchem, nzchem), in magnitudes.

Return type:

numpy.ndarray

astromugs.nautilus.coupling.to_spherical(chemmodel, nr, nt, dist, theta, struct='numberdens_species')[source]#

Convert a Nautilus chemistry structure from cylindrical to spherical coordinates.

Maps a quantity stored on the Nautilus cylindrical grid (keyed by radial position) onto a regular spherical (r, theta) grid via bilinear interpolation. Each chemistry column is first interpolated onto a common z grid (built from the union of all column z arrays), producing a regular 2-D field in (R_cyl, z) that is then passed to RegularGridInterpolator. Points outside the chemistry domain — above the disk surface, beyond the outermost radius, or inside the inner radius — receive floor values.

Parameters:

  • chemmodel (dict) – Dictionary keyed by cylindrical radius in AU (int or float). Each value is a dict containing:

    • 'z': 1-D array of vertical heights in AU, stored surface → midplane (descending order).

    • the field named by struct: 1-D array of the quantity to remap, same length and order as 'z'.

  • nr (int) – Number of radial cell centres in the output spherical grid.

  • nt (int) – Number of co-latitude cell centres in the output spherical grid.

  • dist (numpy.ndarray) – Spherical radial distance grid (cell centres) in AU, shape (nr,).

  • theta (numpy.ndarray) – Co-latitude grid (cell centres) in radians, shape (nt,).

  • struct (str, optional) – Key in each chemmodel entry for the quantity to remap. Default is 'numberdens_species'.

Returns:

Remapped quantity on the spherical grid, shape (nr, nt). Cells inside the inner radius are set to 1e-20; cells outside the modelled domain are set to 0.0.

Return type:

numpy.ndarray