Skip to main content

DiskMELTS

DiskMELTS (Machine-learning Enabled Line fitting Tool for Spectra) is a package for continuum subtraction and fitting molecular emission in JWST mid-infrared spectra of protoplanetary disks. Its fitting workflow loads pretrained molecular surrogate models and retrieves temperature (T), column density (logN), and emitting area scaling (A) from observed spectra.

Documentation: diskmelts.readthedocs.io

Installation

Requires Python 3.9 or newer. Once the package is published to PyPI, install it from any directory without cloning this repository:

python -m pip install diskmelts
# Add [io] for FITS input, or [io,notebooks] for JupyterLab.

Until the first PyPI release, install directly from GitHub without a clone:

python -m pip install "diskmelts[io] @ git+https://github.com/wddlx/DiskMELTS.git"

The package includes the production checkpoints and continuum reference tables. Full slab grids for training and direct-grid fitting are separate downloads; pass their local path as grid_root. See the installation guide for details.

Development checkout (macOS, Linux, Windows)

From the repository root, use a native Python 3.10 or 3.11 interpreter to create a virtual environment. For FITS input and the example notebooks:

python3.11 -m venv .venv
.venv/bin/python -m pip install -e ".[io,notebooks]"
.venv/bin/python -c "import diskmelts; print(diskmelts.__name__)"

Use python3.10 if that is the native Python available on your machine. For core fitting and CSV/array inputs only, replace the install command with .venv/bin/python -m pip install -e .. See the installation guide for Windows commands.

Conda or Mamba

The YAML files use Conda only for Python and pip; pip installs the package and its declared dependencies. Choose one from the repository root:

File Contents
environment.yaml Core package
environment-notebooks.yaml Core package, FITS support, JupyterLab
environment-dev.yaml Notebook environment, tests, documentation tools

For the notebook setup, run mamba env create --file environment-notebooks.yaml then conda activate diskmelts-notebooks. conda env create --file works with the same files when using a current Conda release. On Apple Silicon, use a native osx-arm64 installation such as Miniforge; an older Intel Conda can still spend a long time solving even these smaller files.

Runtime dependencies

Package Purpose
torch Pretrained model inference
numpy Array operations
pandas CSV I/O
scipy L-BFGS-B optimizer, NNLS, Sobol sampling
scikit-learn Model scaling and PCA metadata
matplotlib Plotting

Continuum subtraction

Try the continuum subtraction notebook with the included raw Upper Sco J16120505 spectrum. It demonstrates the five-array result and a plot; change RAW_CSV to another file in Realobs_data/Raw_data/ to process another source.

For a CSV with wave,flux,err columns (wavelength in µm and flux/error in the same units):

import diskmelts

wav, flux, error = diskmelts.consub.read_spectrum("raw_spectrum.csv")
wav, consub, err, cont, contOrig = diskmelts.consub.calculate(
    wav, flux, error, preset="ttauri", exclude=[[12, 13]],
)
fig = diskmelts.consub.plot(
    wav, consub, err, cont, contOrig, ranges=[(5, 12), (12, 25)], savedir=None,
)

calculate() returns five NumPy arrays. plot() displays the raw spectrum, continuum, and residual; savedir="figures/consub" also writes continuum.png. Its error and contOrig inputs may be None.

Presets are water, ttauri, carbon_rich, and carbon_extended. Use preset=None, linefreefile="windows.csv" for custom xmin,xmax windows. With preset=None, linefreefile=None (or ""), fitting uses all nonexcluded pixels and skips the line-free correction, so cont equals contOrig. Reference tables are bundled; normal continuum subtraction needs no model grids.

The private 0-Consub/ experiment directory is excluded from Git and is not required by the installed package. Its runtime code and reference tables are maintained under src/diskmelts/consub/. The distributed tests in tests/ exercise the installed continuum API and bundled references without that private directory.

Returned err represents measurement/noise error, not correlated continuum uncertainty. Broad excluded intervals require inspection. See the continuum guide for presets, regional box sizes, special regions, FITS input, saving CSVs, and uncertainty diagnostics.

Quick fitting example

from diskmelts import load_fitting_models, load_observed_spectrum, fit_stage

pretrained = load_fitting_models(['H2O'])

obs_wav, obs_flux = load_observed_spectrum(
    'Realobs_data/Consub_data/j16120505_v9.0_contsub_RVcorr.csv'
)

fit = fit_stage(
    obs_wav,
    obs_flux,
    molecule='H2O',
    wavelength_range=(11.0, 19.0),
    pretrained=pretrained,
    fit_ranges=[(11.0, 12.0), (16.5, 18.5)],
    distance_pc=122.5,
    n_samples=20000,
    n_refine=32,
    n_top=20,
    sigma=0.001,
)

print(fit['params'])

You can also read spectra with your own code. DiskMELTS only requires one-dimensional obs_wav and obs_flux arrays.

For a complete staged fit-and-subtract workflow from a checkout, edit and run:

python examples/dev_v2_realobs.py

The v2 fitting API is load_fitting_models, fit_stage, fit_observation, and plot_saved_observation. The production checkpoints are packaged under src/diskmelts/models/ and included in the wheel. Model fitting requires no Model_grids/ or Pretrain_grid/ directory. The model metadata, including PCA counts and network layers, are in diskmelts.MODEL_SPECS and checked when loading. The checkpoint flux convention is 1 au² at 140 pc; distance_pc sets the source distance and makes the returned emitting area physical. The fitting notebook requires 13C12CH2 to be no hotter than C2H2 and gives them the same emitting area. It ties 13CO2 to CO2 in both temperature and area. Set isotopologue_groups, Tshare (free, equal, or less), and Ashare in a joint stage to choose those constraints. See the fitting guide for examples.

For an optional fit directly from slab grids, use fit_grid_stage or fit_observation_grids and supply grid_root='Model_grids' explicitly. This separate method does require the full local grids. See the quick start for both workflows and saved-result plotting.

Training and validation data

Model_grids/ and Pretrain_grid/ are intentionally ignored by Git because they contain the full local training data. The generated checkpoint directories under the top-level Trained_model/ are also optional; the package bundles only the production checkpoints needed for v2 fitting. To run examples/dev_v2_pt_validation.py or notebooks/Example_Training_Validation.ipynb, place the complete model grids under Model_grids/<molecule>/. The workflows create or reuse the corresponding pretraining CSV under Pretrain_grid/.

The maintained v2 workflow uses a hybrid design after restricting the expanded IRIS grids to the intended physical domain. H2O uses five overlapping wavelength checkpoints covering 4.9–25.0 µm, all sharing T=100–1400 K and logN=13–19. Primary carbon-bearing and rarer molecules use one checkpoint each, the same temperature range, and logN=13–19.5. The new C2HD checkpoint spans 11.5–20.5 µm to include its 19 µm band; CO17O and CO18O span 13–18 µm. The updated 13C12CH2 checkpoint keeps 11.5–17 µm. To retrain these four grids, run:

DISKMELTS_MOLECULES=13C12CH2,C2HD,CO17O,CO18O python examples/dev_v2_pt_validation.py

Five to ten percent of complete (T, logN) grid spectra are excluded before PCA or neural-network training. They are used to select the PCA dimension and to validate spectral reconstruction and full parameter fitting. The run_H2O, run_Cmol, and run_rarer switches select which groups run.

Forward model convention

flux(T, logN, A, d) = A * (140 pc / d)^2 * peak(T, logN) * shape(T, logN)

Each molecule has two pretrained MLPs:

  • net_shape: (T, logN) to PCA coefficients of the peak-normalized spectral shape
  • net_peak: (T, logN) to log10(peak flux) in Jy

The linear amplitude A is solved analytically with NNLS or bounded least squares after the nonlinear (T, logN) search.

Contributors

  • Chengyan Xie (University of Arizona)
  • Dingshan Deng (University of Arizona)

Metadata

Release files for diskmelts 2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for diskmelts 2.1
File Size Uploaded Provenance Actions
diskmelts-2.1.tar.gz 9.6 MB Without provenance Details for diskmelts-2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for diskmelts 2.1
File Interpreter ABI Platform Actions
diskmelts-2.1-py3-none-any.whl Python 3 none any Details for diskmelts-2.1-py3-none-any.whl

Total release size: 19.3 MB

Release files / diskmelts-2.1.tar.gz

Download URL diskmelts-2.1.tar.gz
Size 9.6 MB
Tags Source
SHA-256 checksum
How to use checksums
720f798a7fde8a2320266bc9b849b1744b68b48bb47aa07694d6712f600cf459
BLAKE2b-256 checksum
How to use checksums
4c41712674a2e21812cee36a68d3aa2d28f66158961320e91a16dd2a661ecf3d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.12

Release files / diskmelts-2.1-py3-none-any.whl

Download URL diskmelts-2.1-py3-none-any.whl
Size 9.6 MB
Tags Python 3
SHA-256 checksum
How to use checksums
7e8ee3e57f7dbb942ca1e25bb9a5edcf6b2d895308269ac979b53b5dbc041d00
BLAKE2b-256 checksum
How to use checksums
1f8e0cec4f546120e921f7d6a683dc42dd0fbecdf72dcc10ec9ce99ca7f05f83
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.12

Security for diskmelts 2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page