User Guide
Using as a python library
Under Construction
See Examples:
Command Line Use
For large scale runs, it is recommended to make use of SERVAL's command line interface (CLI), especially for runs on HPC systems. The parameters for these commands can be specified with either TOML configuration files or command line arguments.
Currently supported CLI commands are:
and
These are described below. Help for both can be accessed with e.g.:
and configuration templates can be printed to stdout with e.g.:
Note: Parameters can be expressed across multiple config files as well as command line arguments. Parameters given in command line arguments take priroty over those given in configuration files. Parameters given in more than one configuration file will take the value specified in the last configuration file listed.
These commands can parallelize over multiple MPI tasks with a given memory target for each task. Some examples of submission scripts for large runs on HPCs will be provided in the future. To get a sense of how many resources a run will use, you can do a dry run that only produces a task distribution plan using the --plan-only flag.
Generating an Integrator Cache using the CLI
SERVAL supports generating an integrator cache in the form of a cached set of PowerBeamVisProjector's from the command line.
This can be done through the command serval gencache fixed-sky whose usage is as follows:
serval gencache fixed-sky --help
Usage: serval gencache fixed-sky [OPTIONS]
Generate a stored integrator cache to be used with power beams at a later
stage to generate visibilities. Fixes a telescope and sky model.
Options:
--config-template Output a template configuration file and
exit.
--plan-only Output the run plan only and exit.
--config PATH One or more optional TOML configuration
files to use for parameters. The last file
specified has the highest priority for
overlapping parameters.
--store-location PATH The location of the zarr store for the
generate cache. Must be specified here or in
a config file.
--sky-model PATH The location of the harmonic sky model,
frequencies must match those specified for
the cache generation. Must be specified here
or in a config file.
--latitude TEXT Telescope TIRS latitude, must be astropy
convertable or floats in degrees. Must be
specified here or in a config file.
--longitude TEXT Telescope TIRS longitude, must be astropy
convertable or floats in degrees. Must be
specified here or in a config file.
-b, --baselines_enu <TEXT TEXT TEXT>...
Telescope TIRS ENU Baselines, must be tree-
tuples of astropy convertable distances or
floats in meters. Must be specified here or
in a config file.
--power-beam-lmax INTEGER Maximum harmonic degree for the power beams.
Must be specified here or in a config file.
-f, --frequencies TEXT Telescope frequency channel centres, must be
astropy convertable or floats in MHz. Must
be specified here or in a config file.
--memory-per-task TEXT Target maxium memory usage per MPI task, not
a hard limit. Astropy convertable or float
in GiB. [default: 4 GiB]
--max-absms-per-chunk INTEGER Maximum number of sky ms to compute per MPI
task. If unbounded integration cache size
can blow up. [default: 128]
--start-chunk INTEGER Chunk index to start at if e.g. restarting
run. [default: 0]
--optimized-cache / --no-optimized-cache
Whether to use a Gaunt Cache optimized for
this operation. [default: optimized-cache]
--pointing-contract / --no-pointing-contract
Whether to contract the cache to a specific
pointing. [default: no-pointing-contract]
--pointing-altitude TEXT If contracting to a pointing, the altitude
of the telescope pointing. Must be astropy
convertable or floats in degrees. [default:
90 deg]
--pointing-azimuth TEXT If contracting to a pointing, the azimuth of
the telescope pointing. Must be astropy
convertable or floats in degrees. [default:
180 deg]
--pointing-boresight TEXT If contracting to a pointing, the boresight
angle of the telescope pointing. Must be
astropy convertable or floats in degrees.
[default: 0 deg]
--pointed-beam_mmax INTEGER If contracting to a pointing, the harmonic
order maximum of the pointing relative power
beams. [default: 40]
--help Show this message and exit.
an example configuration file can be produced with serval gencache fixed-sky --config-template > example_gencache.toml which will produce a file like:
# Example serval gencache fixed-sky TOML configuration file
# Required:
# ---------
# The location of the zarr store for the generate cache
store_location = "/path/to/my/store.zarr"
# The location of the harmonic sky model, frequencies must match those specified for
# the cache generation
sky_model = "/path/to/my/sky_model.zarr"
# Telescope TIRS Coordinates, must be astropy convertable or floats in degrees
latitude = '-30d41m47.0s'
longitude = '21d34m20.0s'
# Telescope TIRS ENU Baselines, must be astropy convertable or floats in meters
baselines_enu = [
['0m', '8.5m', '0m'],
['6.5m', '0m', '0m'],
['6.5m', '8.5m', '0m']
]
# Maximum harmonic degree for the power beams.
power_beam_lmax = 100
# Telescope frequency channel centres, must be astropy convertable or floats in MHz
frequencies = [
'400MHz',
'500MHz',
]
# Optional:
# ---------
# Target maximum memory usage per MPI task, not a hard limit. Astropy convertable or float in GiB.
memory_per_task = '4 GiB'
# Maximum number of sky ms to compute per MPI task. If unbounded integration cache size can blow up
max_absms_per_chunk = 128
# Chunk index to start at if e.g. restarting run.
start_chunk = 0
# Whether to use a Gaunt Cache optimized for this operation
optimized_cache = true
# Whether to contract the cache to a specific pointing
pointing_contract = false
# If true, the harmonic order maximum of the pointing relative power beams
pointed_beam_mmax = 40
# And the pointing coordinates, must be astropy convertable or floats in degrees
pointing_altitude = '90 deg'
pointing_azimuth = '180 deg'
pointing_boresight = '0 deg'
Generating an Visibilities from an Integrator Cache
SERVAL additionally supports generating visibilities from an integrator cache produced using serval gencache fixedsky.
This can be done through the command serval genvis from-power-beams whose usage is as follows:
Usage: serval genvis from-power-beams [OPTIONS]
Generate visibilities from a stored integrator cache with given power beams.
Options:
--config-template Output a template configuration file and
exit.
--plan-only Output the run plan only and exit.
--config PATH One or more optional TOML configuration
files to use for parameters. The last file
specified has the highest priority for
overlapping parameters.
--store-location PATH The location of the output zarr store for
the visibilities (and mmodes). Must be
specified here or in a config file.
--integrator-cache PATH The location of the input zarr store for the
integrator cache. Must be specified here or
in a config file.
--power-beams PATH The location of the power beam store, must
have matching frequencies of integrator
cache. Must be specified here or in a config
file.
-bm, --baseline-mapping <TEXT TEXT>...
Mapping between baseline groups in the
integrator cache power beam groups in power
beam store. The output visibility groups
will correspond to these pair a hierarchy of
these pairs. Accepts glob patterns for the
beam term.
--memory-per-task TEXT Target maxium memory usage per MPI task, not
a hard limit. Astropy convertable or float
in GiB. [default: 4 GiB]
--start-chunk INTEGER Chunk index to start at if e.g. restarting
run. [default: 0]
--help Show this message and exit.
an example configuration file can be produced with serval genvis from-power-beams --config-template > example_gencache.toml which will produce a file like:
# Example serval genvis from-power-beams TOML configuration file
# Required:
# ---------
# The location of the output zarr store for the visibilities (and mmodes)
store_location = "/path/to/my/visibility/store.zarr"
# The location of the input zarr store for the integrator cache
integrator_cache = "/path/to/my/integrator_cache/store.zarr"
# The location of the input power beam store, must have matching frequencies of
# integrator cache
power_beams = "/path/to/my/power_beams.zarr"
# Mapping between baseline groups in the integrator cache power beam groups in power beam
# store. The output visibility groups will correspond to a hierarchy of these
# pairs. Accepts glob patterns for the beam term.
baseline_mapping = [
['bl_E_6p5m_N_0p0m_U_0p0m', 'dish0_X_dish1_X'],
['bl_E_6p5m_N_0p0m_U_0p0m', 'dish0_Y_dish1_Y'],
]
# Optional:
# ---------
# Target maximum memory usage per MPI task, not a hard limit. Astropy convertable or float in GiB.
memory_per_task = '4 GiB'
# Chunk index to start at if e.g. restarting run.
start_chunk = 0