pmoired 26.10.1

Overview

PMOIRED is a Python3 module which allows to model astronomical spectro-interferometric data stored in the OIFITS format (Duvert et al. 2017). Parametric modeling is used to describe the observed scene as blocks such as disks, rings and Gaussians which can be combined and their parameters linked. It includes plotting, least-square fitting and bootstrapping estimation of uncertainties. For spectroscopic instruments (such as GRAVITY), tools are provided to model spectral lines and correct spectra for telluric lines.

The modelling of data is based on several principles:

• The model is composed of a combination of basic building blocks (see the model definition notebook)
• Simple building blocks include uniform disks, uniform rings, Gaussians.
• Building blocks can be deformed (analytically), including stretched in one preferred direction, or slanted. This can efficiently simulate inclined components.
• More complicated blocks are available, such as disks/rings with arbitrary radial profile, and possibility to include azimuthal intensity variations.
• Each component has a spectrum, including modelling of emission or absorption lines (Gaussian or Lorentzian)
• In order for the computation to be fast (a requirement to perform data fitting), basic blocks have analytical or semi-analytical complex visibilities. Moreover, for the same reason, their spectral component is independent of the geometry.

The principles are close to tools such as LITpro. However, PMOIRED offers additional features:

• Modelling in the spectral dimension. For this reason, it contains a module to do basic telluric correction (only for VLTI/GRAVITY at the moment)
• Models' parameters can be expressed a function of each others, which allows to build complex geometrical shapes: astronomical realistic models can be build this way, without compromising on execution speed.
• Uncertainties can be estimated using bootstrapping (data resampling by date+telescope) to mitigate the effects of correlations between data.
• The values of parameters can be explored using grid and or random search.
• Synthetic data for VLTI array observations can be generated from data cubes.

Install

Use pmrd.py script

The simplest way to use PMOIRED on MacOS / Linux, with python3 and git installed (requires about 1G of disk space):

wget https://raw.githubusercontent.com/amerand/PMOIRED/refs/heads/master/pmrd.py
chmod +x pmrd.py
./pmrd.py --install

which will install PMOIRED from this repository in the environment located in ~/.pmrd.

Then, you can start a python console, ipython, notebook or jupyter-lab by typing ./pmrd -p, ./pmrd -i, ./pmrd -n or ./pmrd -j respectively. Run the examples by typing ./pmrd.py -e

You can update PMOIRED from github with ./pmrd.py -u. Removing the environment is achieved with ./python pmrd.py --remove.

Install with git

The Github version is the most up-to-date. To install from the github repository directly:

pip3 install git+https://github.com/amerand/PMOIRED

you can also clone the repository and install with pip:

git clone https://github.com/amerand/PMOIRED
cd PMOIRED
pip3 install .

Install with pip

PMOIRED is regularly pushed to PyPI at https://pypi.org/project/pmoired/ so you can install directly using pip, by typing:

pip3 install pmoired

Note that the pip version is not updated as often, and to get the latests features and bug fix, it is recommended to use the git version, or better yet, pmrd.py (see above).

Uninstall

To uninstall (works for both PyPI and github versions):

pip3 uninstall pmoired

if you use pmrd.py, the following will remove the whole environment:

python pmrd.py --remove

Examples and tutorials

This repository comes with a Jupyter Notebook showing basic model syntax. You can call this page from Python:

>>> import pmoired
>>> pmoired.modelsDefinitions()

Full examples, how to load real data and analyse them, are available in a separate repository: PMOIRED_examples. These examples are Jupyter Notebooks reproducing published results with other tools, and serve both as tutorials and verification of PMOIRED. They cover most of the features of PMOIRED, from the basics to more advanced operations.

You can also check the following material:

• Tutorial from the 2024 VLTI School: modelling of GRAVITY observations of the Herbig Ae star HD 58647: in the continuum and in the Brackett gamma Hydrogen line.
• Binary fit tutorial from Robert Klement, for the 2026 CHARA Days

Using and quoting PMOIRED

References to PMOIRED should point to the 2022 SPIE Telescopes+Instrumentation conference proceeding paper.

This code is a research project in continuous development and not properly fully documented. If you want to get the best analysis for your data, do not hesitate to contact me: I try to be responsive, in particular with junior scientists. New features are driven by collaborations: if you think PMOIRED is missing something, definitely contact me!

I maintain a list of works published using PMOIRED in a curated bibliography.

I used to to request co-authorship on publications using PMOIRED (until Feb 2023): this is no longer the case, unless I contributed directly to the work in question

Limitations and known issues

Running a script in ipython hangs

PMOIRED uses the multiprocessing library to parallelise some computations (e.g. bootstrapping, grid search). This library has some issues if you run a script containing such computation is an interactive shell (using %run or run in ipython or Spyder). The provided examples as notebooks do not suffer from this problem. If you want to use PMOIRED in .py scripts you run in iPython, you should structure your .py script more or less as follow:

import pmoired
import matplotlib

matplotlib.interactive(True)
__spec__ = None
if __name__=='__main__':
    [code]

in iPython, you can now type %run myscript.py.

Dependencies

The latest version of PMOIRED has been tested on:

• python 3.13.1
• numpy 2.2.0 (need >2.0)
• scipy 1.14.1
• astropy 7.0.0
• astroquery 0.4.7
• matplotlib 4.3.3
• jupyterlab 4.4.1

Acknowledgments

• PMOIRED uses extensively Numpy, Scipy, Matplotlib, Astropy and Astroquery. It is optimised to be used with Jupyter notebooks.
• Telluric corrections use HITRANS models computed by A. Smette (private comm.), similar to those used for MOLECFIT
• The Keplerian disk model is adapted from Delaa+2011 and Meilland+2012
• The rotating star model is adapted from Aufdenberg+2006
• The spherical ATLAS models used for center-to-limb darkening have been computed by Neilson and Lester (2013), for red giants and FGK dwarfs
• The JSDC is used for calibrators' angular diameters

PMOIRED has received contributions from Akke Corporaal, Evgenia Koumpia and Robert Klement.

This project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 101004719.