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
DiskMELTS is available on PyPI and
requires Python 3.9 or newer. It bundles 46 production checkpoints, 23 each
for the sigma=0 and sigma=2 grids, covering the same 18 species (see
Available molecules).
Install it from any directory. These commands use
python in an activated environment; the
installation guide
shows how to create one on macOS, Linux, Windows, or Conda:
python -m pip install diskmelts
python -c "import diskmelts; print('DiskMELTS is ready')"
Optional features can be installed in the same way:
python -m pip install "diskmelts[io]" # FITS input
python -m pip install "diskmelts[io,notebooks]" # FITS input and JupyterLab
The pip 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.
Example notebooks and spectra can be downloaded from the repository when
needed; they are not installed by pip.
To install from a checkout with Conda or Mamba, run:
git clone https://github.com/wddlx/DiskMELTS.git
cd DiskMELTS
conda env create -f environment.yaml
conda activate diskmelts
Use environment-notebooks.yaml or environment-dev.yaml for the corresponding
notebook or contributor dependencies.
Minimal workflow
Subtract the continuum, fit one molecule, and print the result:
from diskmelts import consub, fit_stage, load_fitting_models
# 1. Raw spectrum: CSV with wave (µm), flux (Jy), and optional err columns.
raw_wave, raw_flux, raw_err = consub.read_spectrum("my_raw_spectrum.csv")
wave, flux, err, cont, cont_unshifted = consub.calculate(
raw_wave, raw_flux, raw_err, preset="ttauri",
)
# 2. Fit C2H2 near 13.7 µm with the bundled surrogate model.
models = load_fitting_models("C2H2")
fit = fit_stage(
wave, flux, molecule="C2H2", pretrained=models,
wavelength_range=(13.0, 15.0), fit_ranges=(13.5, 14.1),
distance_pc=140.0, n_samples=1024, n_refine=4, n_top=4,
)
# 3. Best-fit T (K), logN (cm^-2), A (au^2), and the spread of top solutions.
print(fit["params"]["C2H2"])
print(fit["uncertainty"]["C2H2"])
The sections below explain each step, and the first-spectrum guide covers multi-stage fits, saved outputs, and plots.
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 |
PCA and scaling when training new models |
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.
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
Use a continuum-subtracted CSV with a header and wave,flux as its first two
columns, with wavelength in µm and flux in Jy. For a runnable example without
cloning the repository, download the
J16120505 spectrum
as j16120505_contsub.csv, or run:
curl -L -o j16120505_contsub.csv https://raw.githubusercontent.com/wddlx/DiskMELTS/main/Realobs_data/Consub_data/j16120505_v9.0_contsub_RVcorr.csv
from diskmelts import fit_stage, load_fitting_models, load_observed_spectrum
models = load_fitting_models('C2H2')
obs_wav, obs_flux = load_observed_spectrum(
'j16120505_contsub.csv'
)
fit = fit_stage(
obs_wav,
obs_flux,
molecule='C2H2',
wavelength_range=(13.0, 15.0),
pretrained=models,
fit_ranges=(13.5, 14.1),
distance_pc=122.5,
n_samples=1024,
n_refine=4,
n_top=4,
)
print(fit['params']['C2H2'])
You can also read spectra with your own code. DiskMELTS only requires
one-dimensional obs_wav and obs_flux arrays. Replace the sample CSV with
your own file to fit your source; update distance_pc and fit intervals.
For a complete staged fit-and-subtract workflow from a clone of the repository, run:
python examples/dev_v2_realobs.py
python examples/dev_v2_realobs.py --input /path/to/my_spectrum.csv --name my_source --distance-pc 140 --sigma 2
Adjust that script's stage windows for your spectrum.
python examples/synthetic_array_fit.py generates an HCN spectrum and fits it
from in-memory arrays, without an observation file.
The v2 fitting API is load_fitting_models, fit_stage, fit_observation, and
plot_saved_observation. The production checkpoints are included in the
wheel, so model fitting needs no local model grids. The checkpoint flux
convention is 1 au² at 140 pc; distance_pc sets the source distance and
makes the returned emitting area physical. fit_observation accepts either a
CSV path or in-memory obs_wav, obs_flux, and optional obs_err arrays
(new in 2.2.1).
For a synthetic spectrum, wave, flux = diskmelts.synthesize_spectrum('HCN', T=300, logN=18, A=1) returns the native wavelength axis and model flux (new
in 2.2.1). See the
generation guide.
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. Point its input at
your own continuum-subtracted CSV, or pass arrays. 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/sigma0' explicitly. This
separate method does require the full local grids. See the
quick start for both workflows and saved-result
plotting.
For complete sigma=2 grids, pass grid_root='Model_grids/sigma2'.
Available molecules
Each molecule is available for two slab-model grids: sigma=0 (default) assumes
no turbulent broadening, so lines are only thermally broadened, and sigma=2
assumes 2 km/s turbulent broadening. Select sigma=2 with load_fitting_models(..., sigma=2) or
fit_observation(..., sigma=2). Fit windows must lie inside a model's band.
| Molecule | Band (µm) | T (K) | logN (cm⁻²) |
|---|---|---|---|
| H2O | 4.9–25.0 (five overlapping tiles) | 100–1400 | 13–19 |
| C2H2 | 6–9 and 11.5–17 | 100–1400 | 13–19.5 |
| HCN, CO2, 13C12CH2, 13CO2 | 11.5–17 | 100–1400 | 13–19.5 |
| HC3N, CO17O, CO18O | 13–18 | 100–1400 | 13–19.5 |
| C4H2 | 14–18 | 100–1400 | 13–19.5 |
| C3H4, CH3 | 15–18 | 100–1400 | 13–19.5 |
| C6H6 | 13–17 | 100–675 | 13–19.5 |
| C2H6 | 9–15 | 100–1400 | 13–19.5 |
| C2H4 | 8–14 | 100–1400 | 13–19.5 |
| CH4 | 5–9 | 100–1400 | 13–19.5 |
| C2HD | 11.5–20.5 | 100–1400 | 13–19.5 |
| OH | 15–26 | 100–1400 | 13–19.5 |
diskmelts.MODEL_SPECS records the exact domains, PCA sizes, and network
layers. Version 2.2.0 lacks the sigma=0 OH and 6–9 µm C2H2 checkpoints;
upgrade with python -m pip install -U diskmelts.
Training and validation data
Generated data under Model_grids/ and Pretrain_grid/ are intentionally
ignored by Git because they contain the full local training data. 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/sigma0/<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 and logN=13–19.5; C6H6 is limited to T=100–675 K, while the others
use T=100–1400 K.
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
C6H6 and C3H4 also have bundled fitting checkpoints. The C6H6 checkpoint
covers 13–17 µm and 100–675 K; C3H4 covers 15–18 µm and 100–1400 K. Load
either by name with load_fitting_models. Direct grid fitting
uses the same names with local Model_grids/sigma0/C6H6/ and Model_grids/sigma0/C3H4/
files. See the training guide
for peak audits and retraining commands.
The package also includes a CH3 checkpoint for 15–18 µm,
T=100–1400 K, and logN=13–19.5. Its strongest grid feature in this window
is near 16.4–16.6 µm. Use load_fitting_models('CH3') after installing this
package; direct-grid fitting uses local Model_grids/sigma0/CH3/ files.
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 shapenet_peak:(T, logN)tolog10(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.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| diskmelts-2.2.2.tar.gz | 21.8 MB | Without provenance | Details for diskmelts-2.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| diskmelts-2.2.2-py3-none-any.whl | Python 3 | none | any | Details for diskmelts-2.2.2-py3-none-any.whl |
Total release size: 43.6 MB
Release files / diskmelts-2.2.2.tar.gz
| Download URL | diskmelts-2.2.2.tar.gz |
|---|---|
| Size | 21.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
69f2e717085ef327c85e261dc84c9c5bd95d896eb821112f013b5539e31d59f3
|
|
BLAKE2b-256 checksum How to use checksums |
5186f26fc85ecf90a6586c09c7626a5787bf90baff8a3d92c20e70ed0b28a165
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.13
|
Release files / diskmelts-2.2.2-py3-none-any.whl
| Download URL | diskmelts-2.2.2-py3-none-any.whl |
|---|---|
| Size | 21.8 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5a1104b6d21748bc567f613e6143f472dac208861584a33afac60296c5debe25
|
|
BLAKE2b-256 checksum How to use checksums |
1ed319f68a61a34557498c90f95b57e427117a3fd5126e6ab55dc504f6c98a58
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.13
|
Security for diskmelts 2.2.2
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.