# pyuvsim
[](https://codecov.io/gh/RadioAstronomySoftwareGroup/pyuvsim)
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](https://pyuvsim.readthedocs.io/en/latest/comparison.html).
## 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,
1. High level of test coverage including accuracy (design goal is 97%).
2. Testing against analytic calculations, monitored by continuous integration (see memo #XXX)
3. 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:
1. Design for scalability across many cpus.
2. Defining a clear, user-friendly standard for simulation design.
3. 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.
1. Fully-polarized instrument response (complete)
1. Polarized sources (analytic testing ~90% )
1. Floating-point source position accuracy (complete)
1. Full-sky field of view (complete)
1. Exact antenna positions. (complete)
1. Varied beam models across the array (complete, tested against analytic)
1. Diffuse emission (complete, tested against analytic, paper in prep)
1. Arbitrary spectrum (complete)
1. Non-terrestrial observatories (Lunar observatory complete)
1. Time domain sources (TODO)
1. Ionospheric scintillation (TODO)
# Citation
Please cite pyuvsim by citing our JOSS paper:
Lanman et al., (2019). pyuvsim: A comprehensive simulation package for radio
interferometers in python. Journal of Open Source Software, 4(37), 1234,
https://doi.org/10.21105/joss.01234
[ADS Link](https://ui.adsabs.harvard.edu/abs/2019JOSS....4.1234L/abstract)
## Installation
Simple installation via pip is available for users, developers should follow
the directions under [Developer Installation](#developer-installation) below.
A user-installation is achieved simply with `pip install pyuvsim`, or to get the
bleeding-edge: `pip install https://github.com/RadioAstronomySoftwareGroup/pyuvsim`.
By default, `mpi` capabilities are not enabled -- many of the utilities provided
in `pyuvsim` do not require it. To use the simulator within `pyuvsim`, you
should install `pyuvsim` with `pip install pyuvsim[sim]`. Note that the
`pyuvsim` simulator is intended to run on clusters running the linux operating
system, but we test against Mac OSX as well. We test against both Open MPI and MPICH.
There are a few more optional dependencies for `pyuvsim` which enable some features,
such as `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
`pyuvsim` with `pip install pyuvsim[all]` (or use the `[healpix]`, `[casa]` or `[moon]`
options to only get the dependencies for each of those functionalities).
If you wish to manage dependencies manually read on.
### Dependencies
If you are using `conda` to manage your environment, you may wish to install the
following packages before installing `pyuvsim`:
Required:
* astropy>=6.0
* numpy>=1.23
* psutil
* pyradiosky>=0.2.0
* python>=3.10
* pyuvdata>=2.4.3
* pyyaml>=5.4.1
* scipy>=1.7.3
* setuptools_scm>=7.0.3
Optional:
* astropy-healpix>=1.0.2 (for using healpix based sky catalogs or beams)
* mpi4py>=3.1.1 (for actually running simulations)
* lunarsky>=0.2.2 (for simulating telescopes on the moon)
* python-casacore>=3.5.2 (for writing CASA measurement sets)
### Developer Installation
If you are developing `pyuvsim`, you will need to download and install the
repository using `git clone https://github.com/RadioAstronomySoftwareGroup/pyuvsim.git`.
Navigate into the pyuvsim directory and run `pip install .` or `pip install -e .`
for a developer install (which makes it so that you don't have to reinstall
every time you change the code)
Note that this will attempt to automatically install any missing dependencies.
If you use anaconda or another package manager you might prefer to first install
the dependencies as described in [Dependencies](#dependencies) (as well as the
developer dependencies listed below).
To install without dependencies, run `pip install --no-deps .`
(optionally with the `-e` flag as well).
If you want to do development on pyuvsim, in addition to the other dependencies
you will need the following packages:
* coverage
* line-profiler
* pre-commit
* pytest
* pytest-cov >= 5.0
* pypandoc
* sphinx
One other package, pytest-xdist, is not required, but can be used to speed up running
the test suite by running tests in parallel. To use it call pytest with the
```-n auto``` option.
One way to ensure you have all the needed packages is to use the included
`environment.yaml` file to create a new environment that will
contain all the optional dependencies along with dependencies required for
testing and development (```conda env create -f environment.yaml```).
Alternatively, you can specify `test`, `doc`, or `dev` when installing pyuvdata
(as in `pip install .[dev]`) to install the packages needed for testing
(including coverage and linting) and documentation development;
`dev` includes everything in `test` and `doc`.
Finally, install the pre-commit hook using `pre-commit install` to help prevent
committing code that does not meet our style guidelines.
## Inputs
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](https://pyuvsim.readthedocs.io/en/latest/usage.html).
## Outputs
Data from a simulation run are written out to a file in any format accessible with `pyuvdata`. This includes:
* uvfits
* MIRIAD
* uvh5
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
Example `obsparam` configuration files may be found in the `reference_simulations` directory.
1. Install from github or pip.
2. 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
Documentation on how to run simulations and developer API documentation is hosted on [ReadTheDocs](https://pyuvsim.readthedocs.io).
## Testing
`pyuvsim` uses the `pytest` package for unit testing. If you've cloned the source into a directory `pyuvsim/`, you may verify it as follows:
1. Install `pytest` from anaconda or pip.
2. Run the pytest from `pyuvsim/`
```
pytest
```
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
`pytest.mark.parallel(n)` where `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 `--nompi`.
## Where to find Support
Please feel free to submit new issues to the [issue log](https://github.com/RadioAstronomySoftwareGroup/pyuvsim/issues) to request new features, document new bugs, or ask questions.
## How to contribute
Contributions to this package to add new features or address any of the
issues in the [issue log](https://github.com/RadioAstronomySoftwareGroup/pyuvsim/issues) are very welcome, as are bug reports or feature requests.
Please see our [guide on contributing](.github/CONTRIBUTING.md)
## Versioning Approach
We use a `generation.major.minor` format.
* 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
and which do not include breaking API changes.
Testing: Backed by unittests
We do our best to provide a significant period (usually 2 major generations) of
deprecation warnings for all breaking changes to the API.
We track all changes in our [changelog](https://github.com/RadioAstronomySoftwareGroup/pyuvsim/blob/main/CHANGELOG.md).
### 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.
# Maintainers
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)
Please use the channels discussed in the [guide on contributing](.github/CONTRIBUTING.md)
for code-related discussions. You can contact us privately if needed at
[rasgmanagers@gmail.com](mailto:rasgmanagers@gmail.com).
Raw data
{
"_id": null,
"home_page": "https://github.com/RadioAstronomySoftwareGroup/pyuvsim",
"name": "pyuvsim",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "radio astronomy interferometry",
"author": "Radio Astronomy Software Group",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a7/cd/96554cd3d53475e09c03682e0375926ef1c709fd2c0731fa60687c9159b9/pyuvsim-1.3.0.tar.gz",
"platform": null,
"description": "# pyuvsim\n\n\n[](https://codecov.io/gh/RadioAstronomySoftwareGroup/pyuvsim)\n\npyuvsim is a comprehensive simulation package for radio interferometers in python.\n\nA number of analysis tools are available to simulate the output of a radio\ninterferometer (CASA, OSKAR, FHD, PRISim, et al), however each makes numerical\napproximations to enable speed ups. pyuvsim's goal is to provide a simulated\ninstrument output which emphasizes accuracy and extensibility, and can represent the most\ngeneral simulator design.\n\nA comparison to other simulators may be found [here](https://pyuvsim.readthedocs.io/en/latest/comparison.html).\n\n## pyuvsim, the Interferometer Simulator of Record\npyuvsim's primary goal is to be an interferometer simulator accurate at the level of\nprecision necessary for 21cm cosmology science,\n\n1. High level of test coverage including accuracy (design goal is 97%).\n2. Testing against analytic calculations, monitored by continuous integration (see memo #XXX)\n3. Comparison with external simulations with standardized reference simulations\n\n## Usability and extensibility\nA secondary goal is a community simulation environment which provides well documented and flexible code to support a diversity of use cases.\nKey elements of this approach include:\n1. Design for scalability across many cpus.\n2. Defining a clear, user-friendly standard for simulation design.\n3. Documentation of analytic validation and reference simulations\n\n# Physical Instrumental Effects\nEach 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.\n1. Fully-polarized instrument response (complete)\n1. Polarized sources (analytic testing ~90% )\n1. Floating-point source position accuracy (complete)\n1. Full-sky field of view (complete)\n1. Exact antenna positions. (complete)\n1. Varied beam models across the array (complete, tested against analytic)\n1. Diffuse emission (complete, tested against analytic, paper in prep)\n1. Arbitrary spectrum (complete)\n1. Non-terrestrial observatories (Lunar observatory complete)\n1. Time domain sources (TODO)\n1. Ionospheric scintillation (TODO)\n\n# Citation\nPlease cite pyuvsim by citing our JOSS paper:\n\nLanman et al., (2019). pyuvsim: A comprehensive simulation package for radio\ninterferometers in python. Journal of Open Source Software, 4(37), 1234,\nhttps://doi.org/10.21105/joss.01234\n\n[ADS Link](https://ui.adsabs.harvard.edu/abs/2019JOSS....4.1234L/abstract)\n\n\n## Installation\nSimple installation via pip is available for users, developers should follow\nthe directions under [Developer Installation](#developer-installation) below.\n\nA user-installation is achieved simply with `pip install pyuvsim`, or to get the\nbleeding-edge: `pip install https://github.com/RadioAstronomySoftwareGroup/pyuvsim`.\n\nBy default, `mpi` capabilities are not enabled -- many of the utilities provided\nin `pyuvsim` do not require it. To use the simulator within `pyuvsim`, you\nshould install `pyuvsim` with `pip install pyuvsim[sim]`. Note that the\n`pyuvsim` simulator is intended to run on clusters running the linux operating\nsystem, but we test against Mac OSX as well. We test against both Open MPI and MPICH.\n\nThere are a few more optional dependencies for `pyuvsim` which enable some features,\nsuch as `astropy_healpix` to use healpix based sky catalogs or healpix beams,\n`python-casacore` for writing out measurement sets and `lunarsky` for simulating telescopes\non the moon. If you would like these tools as well as the full simulator, install\n`pyuvsim` with `pip install pyuvsim[all]` (or use the `[healpix]`, `[casa]` or `[moon]`\noptions to only get the dependencies for each of those functionalities).\n\nIf you wish to manage dependencies manually read on.\n\n### Dependencies\nIf you are using `conda` to manage your environment, you may wish to install the\nfollowing packages before installing `pyuvsim`:\n\nRequired:\n\n* astropy>=6.0\n* numpy>=1.23\n* psutil\n* pyradiosky>=0.2.0\n* python>=3.10\n* pyuvdata>=2.4.3\n* pyyaml>=5.4.1\n* scipy>=1.7.3\n* setuptools_scm>=7.0.3\n\nOptional:\n\n* astropy-healpix>=1.0.2 (for using healpix based sky catalogs or beams)\n* mpi4py>=3.1.1 (for actually running simulations)\n* lunarsky>=0.2.2 (for simulating telescopes on the moon)\n* python-casacore>=3.5.2 (for writing CASA measurement sets)\n\n### Developer Installation\nIf you are developing `pyuvsim`, you will need to download and install the\nrepository using `git clone https://github.com/RadioAstronomySoftwareGroup/pyuvsim.git`.\n\nNavigate into the pyuvsim directory and run `pip install .` or `pip install -e .`\nfor a developer install (which makes it so that you don't have to reinstall\nevery time you change the code)\nNote that this will attempt to automatically install any missing dependencies.\nIf you use anaconda or another package manager you might prefer to first install\nthe dependencies as described in [Dependencies](#dependencies) (as well as the\ndeveloper dependencies listed below).\n\nTo install without dependencies, run `pip install --no-deps .`\n(optionally with the `-e` flag as well).\n\nIf you want to do development on pyuvsim, in addition to the other dependencies\nyou will need the following packages:\n\n* coverage\n* line-profiler\n* pre-commit\n* pytest\n* pytest-cov >= 5.0\n* pypandoc\n* sphinx\n\nOne other package, pytest-xdist, is not required, but can be used to speed up running\nthe test suite by running tests in parallel. To use it call pytest with the\n```-n auto``` option.\n\nOne way to ensure you have all the needed packages is to use the included\n`environment.yaml` file to create a new environment that will\ncontain all the optional dependencies along with dependencies required for\ntesting and development (```conda env create -f environment.yaml```).\nAlternatively, you can specify `test`, `doc`, or `dev` when installing pyuvdata\n(as in `pip install .[dev]`) to install the packages needed for testing\n(including coverage and linting) and documentation development;\n`dev` includes everything in `test` and `doc`.\n\nFinally, install the pre-commit hook using `pre-commit install` to help prevent\ncommitting code that does not meet our style guidelines.\n\n\n## Inputs\n\nA 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.\n\n* 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).\n* 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.\n* Multiple beam models may be used throughout the array, allowing for more complex instrument responses to be modeled.\n\nThese input objects may be made from a data file or from a set of `yaml` configuration files. See [Running a simulation](https://pyuvsim.readthedocs.io/en/latest/usage.html).\n\n## Outputs\n\nData from a simulation run are written out to a file in any format accessible with `pyuvdata`. This includes:\n\n* uvfits\n* MIRIAD\n* uvh5\n\nWhen 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.\n\n## Quick start guide\nExample `obsparam` configuration files may be found in the `reference_simulations` directory.\n\n1. Install from github or pip.\n2. Run off of a parameter file with 4 MPI ranks:\n```\nmpirun -n 4 python scripts/run_param_pyuvsim.py reference_simulations/first_generation/obsparam_ref_1.1.yaml\n```\n\n## Documentation\nDocumentation on how to run simulations and developer API documentation is hosted on [ReadTheDocs](https://pyuvsim.readthedocs.io).\n\n## Testing\n\n`pyuvsim` uses the `pytest` package for unit testing. If you've cloned the source into a directory `pyuvsim/`, you may verify it as follows:\n\n1. Install `pytest` from anaconda or pip.\n2. Run the pytest from `pyuvsim/`\n```\npytest\n```\nYou can alternatively run `python -m pytest pyuvsim` or `python setup.py test`.\nYou will need to have all dependencies installed.\n\nSome tests are run in parallel using the mpi4py module. Those tests have a decorator\n`pytest.mark.parallel(n)` where `n` is an integer giving the number\nof parallel processes to run the test on. To temporarily disable parallel tests,\nrun pytest with the option `--nompi`.\n\n## Where to find Support\n\nPlease feel free to submit new issues to the [issue log](https://github.com/RadioAstronomySoftwareGroup/pyuvsim/issues) to request new features, document new bugs, or ask questions.\n\n## How to contribute\nContributions to this package to add new features or address any of the\nissues in the [issue log](https://github.com/RadioAstronomySoftwareGroup/pyuvsim/issues) are very welcome, as are bug reports or feature requests.\nPlease see our [guide on contributing](.github/CONTRIBUTING.md)\n\n## Versioning Approach\nWe use a `generation.major.minor` format.\n\n* Generation - Release combining multiple new physical effects and or major computational improvements.\nTesting: Backed by unittests, internal model validation, and significant external comparison.\n* Major - Adds new physical effect or major computational improvement. Small number of improvements with each release.\nTesting: Backed by unittests, internal model validation and limited external comparison.\n* Minor - Bug fixes and small improvements not expected to change physical model\nand which do not include breaking API changes.\nTesting: Backed by unittests\n\nWe do our best to provide a significant period (usually 2 major generations) of\ndeprecation warnings for all breaking changes to the API.\nWe track all changes in our [changelog](https://github.com/RadioAstronomySoftwareGroup/pyuvsim/blob/main/CHANGELOG.md).\n\n### Some helpful definitions\n* __Physical effects__: things like polarization effects, noise, ionospheric modeling, or nonterrestrial observing positions.\n* __Major computational improvement__: Support for new catalog types (e.g, diffuse maps), new analysis tools, changes to parallelization scheme\n* __Small improvements__: Better documentation or example code, outer framework redesign.\n\n\n# Maintainers\npyuvsim is maintained by the RASG Managers, which currently include:\n\n - Adam Beardsley (Arizona State University)\n - Bryna Hazelton (University of Washington)\n - Daniel Jacobs (Arizona State University)\n - Paul La Plante (University of California, Berkeley)\n - Jonathan Pober (Brown University)\n\nPlease use the channels discussed in the [guide on contributing](.github/CONTRIBUTING.md)\nfor code-related discussions. You can contact us privately if needed at\n[rasgmanagers@gmail.com](mailto:rasgmanagers@gmail.com).\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "A comprehensive simulation package for radio interferometers in python",
"version": "1.3.0",
"project_urls": {
"Homepage": "https://github.com/RadioAstronomySoftwareGroup/pyuvsim"
},
"split_keywords": [
"radio",
"astronomy",
"interferometry"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "06ab1c5d3c9da617d2f4488c0d411011a438ba6e6f197489279caec59220bfa5",
"md5": "a66002897fe3dfad58177f58e3a66b41",
"sha256": "0c17fe730b5f715dbee49ea98199faa0d6c56a8b611c44cf2cc6699fcd45baad"
},
"downloads": -1,
"filename": "pyuvsim-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a66002897fe3dfad58177f58e3a66b41",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 15574083,
"upload_time": "2024-04-02T17:45:42",
"upload_time_iso_8601": "2024-04-02T17:45:42.512191Z",
"url": "https://files.pythonhosted.org/packages/06/ab/1c5d3c9da617d2f4488c0d411011a438ba6e6f197489279caec59220bfa5/pyuvsim-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a7cd96554cd3d53475e09c03682e0375926ef1c709fd2c0731fa60687c9159b9",
"md5": "8390e793728b3166683271118551dfa3",
"sha256": "df92a317210e3625cd44174ef259eb05f60ebf6b615ddbb6932647445b658c4c"
},
"downloads": -1,
"filename": "pyuvsim-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "8390e793728b3166683271118551dfa3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 17514440,
"upload_time": "2024-04-02T17:45:46",
"upload_time_iso_8601": "2024-04-02T17:45:46.105096Z",
"url": "https://files.pythonhosted.org/packages/a7/cd/96554cd3d53475e09c03682e0375926ef1c709fd2c0731fa60687c9159b9/pyuvsim-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-02 17:45:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RadioAstronomySoftwareGroup",
"github_project": "pyuvsim",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "pyuvsim"
}
JSON
