JenpyROQ

This repository implements an extended, modularised and streamlined version of the PyROQ code (see below for a detailed list of changes), forked in March 2022 from its original repository and developed at the Theoretisch-Physikalisches Institut of the Friedrich-Schiller-Universität Jena.

Older history is available in this fork. If you use this code in your research, please cite the PyROQ paper:

  @article{Qi:2020lfr,
  author = "Qi, Hong and Raymond, Vivien",
  title = "{Python-based reduced order quadrature building code for fast gravitational wave inference}",
  eprint = "2009.13812",
  archivePrefix = "arXiv",
  primaryClass = "gr-qc",
  reportNumber = "LIGO P2000367",
  doi = "10.1103/PhysRevD.104.063031",
  journal = "Phys. Rev. D",
  volume = "104",
  number = "6",
  pages = "063031",
  year = "2021"
  }

and our paper where JenpyROQ was introduced:

  @article{Tissino:2022thn,
  author = "Tissino, Jacopo and Carullo, Gregorio and Breschi, Matteo and Gamba, Rossella and Schmidt, Stefano and Bernuzzi, Sebastiano",
  title = "{Combining effective-one-body accuracy and reduced-order-quadrature speed for binary neutron star merger parameter estimation with machine learning}",
  eprint = "2210.15684",
  archivePrefix = "arXiv",
  primaryClass = "gr-qc",
  doi = "10.1103/PhysRevD.107.084037",
  journal = "Phys. Rev. D",
  volume = "107",
  number = "8",
  pages = "084037",
  year = "2023"
  }

Installation and usage

Starting from the JenpyROQ location, the package can be installed using the command:

python setup.py install

Once JenpyROQ is installed, it is possible to construct an ROQ approximant through a configuration file and running the main routine of the package:

python -m JenpyROQ --config-file config.ini

The user can see the full list of options at:

python -m JenpyROQ --help

A simple example can be run by:

python -m JenpyROQ --config-file config_files/Test_configs/test_config_IMRPv2.ini

Other examples are available in the config_files directory, see the relative README file.

MPI parallelisation

Parallelisation options are described under the [Parallel] section of the help message. For MPI-based parallelisation, the run command should additionally be modified as follows:

mpiexec -n NTASKS python -m JenpyROQ --config-file config_files/Test_configs/test_config_IMRPv2.ini

Where NTASKS corresponds to the requested number of parallel tasks. Moreover, the config file should specify the related flag parallel=2 and n-processes should correspond to NTASKS.

Output

The run directory will automatically contain a copy of the configuration file, git information and the screen output, stored under JenpyROQ.log.

Preselection basis and related parameters, together with the enriched basis, its related parameters, the basis interpolant and empirical nodes are stored at each step of the enrichment loop under the ROQ_data directory.

Basis specifications needed to interface with parameter estimation codes are available under ROQ_data/ROQ_metadata.txt.

Several diagnostic plots (basis parameters, frequency nodes, outliers and error evolution, a single test waveform comparison and validation tests) are stored under the Plots directory.

Algorithm and code description

The algorithm implements what described in the PyROQ paper, but extended to allow for a more flexible pre-basis construction (with user-defined inputs), an arbitrary number of enrichment cycles with arbitrary and variable tolerance thresholds.

The code also speeds up the execution by parallelising wherever possible, implements a more strict parameters and input/output management, a largely increased use of code modularisation, defines generic waveform structures capable of interfacing modern python-based models, including machine learning-based ones.

Additional models supported compared to the original version (which supports any waveform approximant implemented in LALSimulation) are:

• TEOBResumS, a faithful semi-analytical model for compact objects on generic orbits;
• MLGW-BNS, an efficient machine learning version of the frequency-domain TEOBResumSPA model;
• NRPMw, post-merger (including their hybridisation with EOB-inspirals) binary neutron star models, interfaced through bajes.

Adding a new parameter

The parameters structure logic is: a default set of parameters (a combination of the masses) is always included in the training range. For each new set of parameters added (e.g. spins, or tides) a flag will control the activation of such set. Default values of the new set of parameters should be declared, together with activation rules mediating the usage of the new parameter and the interaction with other options.

Specifically, if you intend to add a new set of parameters (following e.g. the appearance of the 'tides' flag and 'lambda1' parameter):

1. Declare the flag activating the new set of parameters here, and document the flag here. Flag conventions are documented here;

2. Document the new parameters here, and declare their default and test values here;

3. Declare the activation rule of the new parameter here, together with possible interaction with other options, e.g. here;

4. Regulate their usage in the waveform call e.g. here.

This is it. Now, the parameter flags and training range can be passed to the configuration files identically to any other parameter, e.g. here.

Dependencies

The package depends on standard Python libraries, except for: numpy for numeric computation, h5py for data storing and matplotlib for plotting. Moreover, if MPI-based parallelisation is requested, the package has an additional dependency on mpi4py.

Development history

SB (sebastiano.bernuzzi@uni-jena.de) 03/2022:

• Forked PyROQ version 0.1.26
• Added support for TEOBResumS GIOTTO and MLW-BNS
• Refactored code
  • Introduced JenpyROQ class
  • Simplified code/reduced duplication
  • Added waveform wrapper classes
  • Changed parameter management

GC (gregorio.carullo@uni-jena.de) 05/2022:

• Debugged and simplified refactored branch.
• Switched to config file usage.
• Implemented algorithm as described in PyROQ paper: pre-selection loop and subsequent enrichment cycles.
• Allow user to determine an arbitrary number of enrichment cycles.
• Allow user to determine variable and arbitrary tolerance thresholds.
• (Almost) maximally streamline code and move logically separated functions to specific files.
• Parallelise linear and quadratic, add more parallelisation steps where possible.
• Improve post-processing and input/output storage (git info, config file, stdout/stderr).

MB (matteo.breschi@uni-jena.de) 05/2022:

• Introduce logger
• Implement MPI-based parallelisation and unify pool usage
• Extend setup.py, improve packaging and include main functionalities

GC (gregorio.carullo@uni-jena.de) 06/2022:

• Introduce inversion stability checks and nodes repetition checks to flag ill-conditioned execution or algorithm failures;
• Enforce controlled parameters set logic (new flag for each set of parameters);
• Add support for several starting basis options;
• Add large number of example config files;

GC (gregorio.carullo@uni-jena.de) and MB (matteo.breschi@uni-jena.de) 08/2022:

• Add support for NRPMw and EOB-NRPMw models.