A comprehensive simulation package for radio interferometers in python
pyuvsim is a comprehensive simulation package for radio interferometers in python.
A number of analysis tools are available to simulate the output of a radio interferometer (CASA, OSKAR, FHD, PRISim, et al), however each makes numerical approximations to enable speed ups. pyuvsim's goal is to provide a simulated instrument output which emphasizes accuracy and extensibility, and can represent the most general simulator design.
A comparison to other simulators may be found here.
pyuvsim, the Interferometer Simulator of Record
pyuvsim's primary goal is to be an interferometer simulator accurate at the level of precision necessary for 21cm cosmology science,
- High level of test coverage including accuracy (design goal is 97%).
- Testing against analytic calculations, monitored by continuous integration (see memo #XXX)
- Comparison with external simulations with standardized reference simulations
Usability and extensibility
A secondary goal is a community simulation environment which provides well documented and flexible code to support a diversity of use cases. Key elements of this approach include:
- Design for scalability across many cpus.
- Defining a clear, user-friendly standard for simulation design.
- Documentation of analytic validation and reference simulations
Physical Instrumental Effects
Each addition of new physics is validated against analytic calculations and included in a new reference simulation. Physics that have been included or are on the roadmap.
- Fully-polarized instrument response (complete)
- Polarized sources (analytic testing ~90% )
- Floating-point source position accuracy (complete)
- Full-sky field of view (complete)
- Exact antenna positions. (complete)
- Varied beam models across the array (complete, tested against analytic)
- Diffuse emission (complete, tested against analytic, paper in prep)
- Arbitrary spectrum (complete)
- Non-terrestrial observatories (Lunar observatory complete)
- Time domain sources (TODO)
- Ionospheric scintillation (TODO)
Simple installation via pip is available for users, developers should follow the directions under Developer Installation below.
A user-installation is achieved simply with
pip install pyuvsim, or to get the
pip install https://github.com/RadioAstronomySoftwareGroup/pyuvsim.
mpi capabilities are not enabled -- many of the utilities provided
pyuvsim do not require it. To use the simulator within
pip install pyuvsim[sim]. Note that the
pyuvsim simulator is intended to run on clusters running the linux operating
system, but we do test against Mac OSX as well.
There are a few more optional dependencies for
pyuvsim which enable some features,
astropy_healpix to use healpix based sky catalogs or healpix beams,
python-casacore for writing out measurement sets and
lunarsky for simulating telescopes
on the moon. If you would like these tools as well as the full simulator, install
pip install pyuvsim[all] (or use the
options to only get the dependencies for each of those functionalities).
If you wish to manage dependencies manually read on.
If you are using
conda to manage your environment, you may wish to install the
following packages before installing
- astropy-healpix>=0.6 (for using healpix based sky catalogs or beams)
- mpi4py>=3.0.0 (for actually running simulations)
- lunarsky>=0.1.2 (for simulating telescopes on the moon)
- python-casacore>=3.3.1 (for writing CASA measurement sets)
If you are developing
pyuvsim, you will need to download and install the
git clone https://github.com/RadioAstronomySoftwareGroup/pyuvsim.git.
If you use conda, you may wish to use a fresh environment, in which case you can
use the included
environment.yaml file to make a conda environment with all
the extra dependencies required for testing/development as well as the
standard ones using
conda env create -f environment.yml. If you do not wish to
make a fresh dedicated environment, you should verify that the environment you
are using contains the packages listed in that file.
Then do a developer install of pyuvsim using
pip install -e . (or
pip install --no-deps -e . if you do not want pip to install any missing
If you do not use conda, after downloading the repository, install using
pip install -e .[dev] to install all the extra dependencies required for
testing/development as well as the standard ones.
Finally, install the pre-commit hook using
pre-commit install to help prevent
committing code that does not meet our style guidelines.
A simulation requires sets of times, frequencies, source positions and brightnesses, antenna positions, and direction-dependent primary beam responses. pyuvsim specifies times, frequencies, and array configuration via a UVData object (from the pyuvdata package), source positions and brightnesses via Source objects, and primary beams either through UVBeam or AnalyticBeam objects.
- All sources are treated as point sources, with flux specified in Stokes parameters and position in right ascension / declination in the International Celestial Reference Frame (equivalently, in J2000 epoch).
- Primary beams are specified as full electric field components, and are interpolated in angle and frequency. This allows for an exact Jones matrix to be constructed for each desired source position.
- Multiple beam models may be used throughout the array, allowing for more complex instrument responses to be modeled.
These input objects may be made from a data file or from a set of
yaml configuration files. See Running a simulation.
Data from a simulation run are written out to a file in any format accessible with
pyuvdata. This includes:
When read into a UVData object, the
history string will contain information on the pyuvsim and pyuvdata versions used for that run (including the latest git hash, if available), and details on the catalog used.
Quick start guide
obsparam configuration files may be found in the
- Install from github or pip.
- Run off of a parameter file with 4 MPI ranks:
mpirun -n 4 python scripts/run_param_pyuvsim.py reference_simulations/first_generation/obsparam_ref_1.1.yaml
Documentation on how to run simulations and developer API documentation is hosted on ReadTheDocs.
pyuvsim uses the
pytest package for unit testing. If you've cloned the source into a directory
pyuvsim/, you may verify it as follows:
pytestfrom anaconda or pip.
- Run the pytest from
You can alternatively run
python -m pytest pyuvsim or
python setup.py test.
You will need to have all dependencies installed.
Some tests are run in parallel using the mpi4py module. Those tests have a decorator
n is an integer giving the number
of parallel processes to run the test on. To temporarily disable parallel tests,
run pytest with the option
Where to find Support
Please feel free to submit new issues to the issue log to request new features, document new bugs, or ask questions.
How to contribute
We use a
- Generation - Release combining multiple new physical effects and or major computational improvements. Testing: Backed by unittests, internal model validation, and significant external comparison.
- Major - Adds new physical effect or major computational improvement. Small number of improvements with each release. Testing: Backed by unittests, internal model validation and limited external comparison.
- Minor - Bug fixes and small improvements not expected to change physical model. Testing: Backed by unittests
Some helpful definitions
- Physical effects: things like polarization effects, noise, ionospheric modeling, or nonterrestrial observing positions.
- Major computational improvement: Support for new catalog types (e.g, diffuse maps), new analysis tools, changes to parallelization scheme
- Small improvements: Better documentation or example code, outer framework redesign.
pyuvsim is maintained by the RASG Managers, which currently include:
- Adam Beardsley (Arizona State University)
- Bryna Hazelton (University of Washington)
- Daniel Jacobs (Arizona State University)
- Paul La Plante (University of California, Berkeley)
- Jonathan Pober (Brown University)
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.