Command Line Interface#

m4opt#

m4opt Usage: m4opt [OPTIONS] COMMAND [ARGS]... ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--versionPrint version and exit.│ │--install-completionInstall completion for the current shell.│ │--show-completionShow completion for the current shell, to copy│ │it or customize the installation.             │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────╮ │animate Generate an animation for a GW sky map.                           │ │prime   Download and cache all dependencies that m4opt may use at runtime.│ │scheduleGenerate an observing plan for a GW sky map.                      │ ╰──────────────────────────────────────────────────────────────────────────────╯
m4opt Usage: m4opt [OPTIONS] COMMAND [ARGS]... ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--versionPrint version and exit.│ │--install-completionInstall completion for the current shell.│ │--show-completionShow completion for the current shell, to copy│ │it or customize the installation.             │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────╮ │animate Generate an animation for a GW sky map.                           │ │prime   Download and cache all dependencies that m4opt may use at runtime.│ │scheduleGenerate an observing plan for a GW sky map.                      │ ╰──────────────────────────────────────────────────────────────────────────────╯

animate#

animate Usage: m4opt animate [OPTIONS] {SCHEDULE.ecsv} {MOVIE.gif} Generate an animation for a GW sky map. ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │*SCHEDULE.ecsv<filename>Input filename for schedule[required]│ │*MOVIE.gif    <filename>Output filename for animation[required]│ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--time-step<Astropy quantity>Time step for evaluating field of │ │regard                            │ │[default: 1.0 h]                  │ │--duration<Astropy quantity>Duration of animation│ │[default: 5.0 s]     │ │--stillSTILL.pdf         Optional output file for still    │ │frame                             │ │--dpi<float>Output resolution │ │--inset-center<SkyCoord>Center of optional zoomed inset│ │--inset-radius<Astropy quantity>Radius of optional zoomed inset│ │[default: 10.0 deg]            │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯
animate Usage: m4opt animate [OPTIONS] {SCHEDULE.ecsv} {MOVIE.gif} Generate an animation for a GW sky map. ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │*SCHEDULE.ecsv<filename>Input filename for schedule[required]│ │*MOVIE.gif    <filename>Output filename for animation[required]│ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--time-step<Astropy quantity>Time step for evaluating field of │ │regard                            │ │[default: 1.0 h]                  │ │--duration<Astropy quantity>Duration of animation│ │[default: 5.0 s]     │ │--stillSTILL.pdf         Optional output file for still    │ │frame                             │ │--dpi<float>Output resolution │ │--inset-center<SkyCoord>Center of optional zoomed inset│ │--inset-radius<Astropy quantity>Radius of optional zoomed inset│ │[default: 10.0 deg]            │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯

prime#

prime Usage: m4opt prime [OPTIONS] Download and cache all dependencies that m4opt may use at runtime. Under normal operation, m4opt will download and cache various external data sources (for example, IERS Earth orientation data and Planck dust maps). If you need to run m4opt in an environment with no outbound Internet connectivity (for example, some computing clusters), you can run this command to download and cache the external data sources immediately. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯
prime Usage: m4opt prime [OPTIONS] Download and cache all dependencies that m4opt may use at runtime. Under normal operation, m4opt will download and cache various external data sources (for example, IERS Earth orientation data and Planck dust maps). If you need to run m4opt in an environment with no outbound Internet connectivity (for example, some computing clusters), you can run this command to download and cache the external data sources immediately. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯

schedule#

schedule Usage: m4opt schedule [OPTIONS] {INPUT.multiorder.fits} {SCHEDULE.ecsv} Generate an observing plan for a GW sky map. The scheduler has three modes: 1. Fixed exposure time. Every field has the same exposure time given by the --exptime-min option. This mode is selected if you omit the --absmag-mean option. 2. Variable exposure time. Each field may have a different exposure time,    adjusted for the posterior median distance along each line of sight.    This mode is selected if you specify a value for the --absmag-mean    option but also pass the --no-appmag-dist option. 3. Variable exposure time with an absolute magnitude distribution. Each    field may have a different exposure time, adjusted to optimize the    detection probability given the posterior distance distribution and a    Gaussian distribution of absolute magnitudes. This mode is selected if    you specify the --absmag-mean option (and, optionally, the --absmag-stdev option). Repeating the --bandpass option makes successive visits cycle through the bandpasses; for example, --bandpass g --bandpass r observes every field in g and then every field in r. Visits are grouped into contiguous blocks of a  single bandpass, so that every field is observed for the kth time before any field is observed for the (k+1)th, and the filter is exchanged once per block boundary however many fields are observed. ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │*INPUT.multiorder.fits<filename>Sky map filename[required]│ │*SCHEDULE.ecsv        <filename>Output filename for generated   │ │schedule                        │ │[required]                      │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────╮ │*--exptime-min<Astropy        Minimum exposure │ │quantity>time for each    │ │observation.     │ │Repeat the option│ │to give each     │ │bandpass its own │ │exposure time, in│ │the same order as│ │--bandpass; a    │ │single value     │ │applies to every │ │bandpass         │ │[required]       │ │--mission<rubin|ultrasat|[default: (uvex)]│ │uvex|uvex_downli│ │nk_orientation|z│ │tf>│ │--skygrid<str>Name of sky grid │ │to use, if the   │ │mission supports │ │multiple sky     │ │grids.           │ │--event-time<Astropy time>Time of the      │ │event, which     │ │--delay and      │ │--deadline are   │ │measured from.   │ │Defaults to the  │ │DATE-OBS field in│ │the sky map      │ │header.          │ │--delay<Astropy        Delay from time  │ │quantity>of event until   │ │the start of     │ │observations     │ │[default: 0.0 d] │ │--deadline<Astropy        Maximum time from│ │quantity>event until the  │ │end of           │ │observations     │ │[default: 1.0 d] │ │--time-step<Astropy        Time step for    │ │quantity>evaluating field │ │of regard        │ │[default: 1.0    │ │min]             │ │--exptime-max<Astropy        Maximum exposure │ │quantity>time for each    │ │observation      │ │[default: inf s] │ │--absmag-mean<float>Mean AB absolute │ │magnitude of     │ │source           │ │[default:        │ │(disable adaptive│ │exposure time)]  │ │--absmag-stdev<float>Standard         │ │deviation of AB  │ │absolute         │ │magnitude of     │ │source           │ │[default: (AB    │ │absolute         │ │magnitude is     │ │fixed at the     │ │value provided by│ │--absmag-mean)]  │ │--appmag-dist--no-appmag-distEnable point-wise│ │distribution of  │ │apparent         │ │magnitude        │ │[default:        │ │appmag-dist]     │ │--snr<float>Signal to noise  │ │ratio for        │ │detection        │ │[default: 5]     │ │--bandpass<str>Name of detector │ │bandpass. Repeat │ │the option to    │ │cycle through    │ │several          │ │bandpasses on    │ │successive       │ │visits; for      │ │example,         │ │--bandpass g     │ │--bandpass r     │ │observes each    │ │field in g and   │ │then in r. Visits│ │are grouped into │ │contiguous blocks│ │of a single      │ │bandpass so that │ │the filter is    │ │exchanged only   │ │between blocks.  │ │--visits<int range>     Number of visits│ │[x>=1][default: 2]    │ │--cadence<Astropy        Minimum time     │ │quantity>separation       │ │between visits   │ │[default: 30.0   │ │min]             │ │--nside<int>HEALPix          │ │resolution       │ │[default: 512]   │ │--max-fields<int range>     Consider only    │ │[x>=1]this many of the │ │most probable    │ │fields. Raising  │ │it grows the     │ │problem roughly  │ │quadratically    │ │[default: 50]    │ │--helpShow this message│ │and exit.        │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Solver Options ─────────────────────────────────────────────────────────────╮ │--timelimit<Astropy quantity>Time limit for MILP      │ │solver                   │ │[default: 1e+75 s]       │ │--memory<Astropy quantity>Maximum solver memory    │ │usage before terminating │ │[default: inf Gibyte]    │ │--jobs-j<int range> [x>=0]Number of threads for    │ │parallel processing, or 0│ │for all cores            │ │[default: 0]             │ │--cutoff<float range> [0<=x<=1]Objective cutoff. Give up│ │if there are no feasible │ │solutions with objective │ │value greater than or    │ │equal to this value      │ │--write-progressPROGRESS.ecsv          Save a time series of the│ │CPLEX objective value and│ │best bound to this file  │ │--write-modelMODEL.{lp,mps,sav}[.gz]Export the MILP model in │ │LP, SAV, or MPS format.  │ │Mainly useful for        │ │troubleshooting purposes │ ╰──────────────────────────────────────────────────────────────────────────────╯
schedule Usage: m4opt schedule [OPTIONS] {INPUT.multiorder.fits} {SCHEDULE.ecsv} Generate an observing plan for a GW sky map. The scheduler has three modes: 1. Fixed exposure time. Every field has the same exposure time given by the --exptime-min option. This mode is selected if you omit the --absmag-mean option. 2. Variable exposure time. Each field may have a different exposure time,    adjusted for the posterior median distance along each line of sight.    This mode is selected if you specify a value for the --absmag-mean    option but also pass the --no-appmag-dist option. 3. Variable exposure time with an absolute magnitude distribution. Each    field may have a different exposure time, adjusted to optimize the    detection probability given the posterior distance distribution and a    Gaussian distribution of absolute magnitudes. This mode is selected if    you specify the --absmag-mean option (and, optionally, the --absmag-stdev option). Repeating the --bandpass option makes successive visits cycle through the bandpasses; for example, --bandpass g --bandpass r observes every field in g and then every field in r. Visits are grouped into contiguous blocks of a  single bandpass, so that every field is observed for the kth time before any field is observed for the (k+1)th, and the filter is exchanged once per block boundary however many fields are observed. ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │*INPUT.multiorder.fits<filename>Sky map filename[required]│ │*SCHEDULE.ecsv        <filename>Output filename for generated   │ │schedule                        │ │[required]                      │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────╮ │*--exptime-min<Astropy        Minimum exposure │ │quantity>time for each    │ │observation.     │ │Repeat the option│ │to give each     │ │bandpass its own │ │exposure time, in│ │the same order as│ │--bandpass; a    │ │single value     │ │applies to every │ │bandpass         │ │[required]       │ │--mission<rubin|ultrasat|[default: (uvex)]│ │uvex|uvex_downli│ │nk_orientation|z│ │tf>│ │--skygrid<str>Name of sky grid │ │to use, if the   │ │mission supports │ │multiple sky     │ │grids.           │ │--event-time<Astropy time>Time of the      │ │event, which     │ │--delay and      │ │--deadline are   │ │measured from.   │ │Defaults to the  │ │DATE-OBS field in│ │the sky map      │ │header.          │ │--delay<Astropy        Delay from time  │ │quantity>of event until   │ │the start of     │ │observations     │ │[default: 0.0 d] │ │--deadline<Astropy        Maximum time from│ │quantity>event until the  │ │end of           │ │observations     │ │[default: 1.0 d] │ │--time-step<Astropy        Time step for    │ │quantity>evaluating field │ │of regard        │ │[default: 1.0    │ │min]             │ │--exptime-max<Astropy        Maximum exposure │ │quantity>time for each    │ │observation      │ │[default: inf s] │ │--absmag-mean<float>Mean AB absolute │ │magnitude of     │ │source           │ │[default:        │ │(disable adaptive│ │exposure time)]  │ │--absmag-stdev<float>Standard         │ │deviation of AB  │ │absolute         │ │magnitude of     │ │source           │ │[default: (AB    │ │absolute         │ │magnitude is     │ │fixed at the     │ │value provided by│ │--absmag-mean)]  │ │--appmag-dist--no-appmag-distEnable point-wise│ │distribution of  │ │apparent         │ │magnitude        │ │[default:        │ │appmag-dist]     │ │--snr<float>Signal to noise  │ │ratio for        │ │detection        │ │[default: 5]     │ │--bandpass<str>Name of detector │ │bandpass. Repeat │ │the option to    │ │cycle through    │ │several          │ │bandpasses on    │ │successive       │ │visits; for      │ │example,         │ │--bandpass g     │ │--bandpass r     │ │observes each    │ │field in g and   │ │then in r. Visits│ │are grouped into │ │contiguous blocks│ │of a single      │ │bandpass so that │ │the filter is    │ │exchanged only   │ │between blocks.  │ │--visits<int range>     Number of visits│ │[x>=1][default: 2]    │ │--cadence<Astropy        Minimum time     │ │quantity>separation       │ │between visits   │ │[default: 30.0   │ │min]             │ │--nside<int>HEALPix          │ │resolution       │ │[default: 512]   │ │--max-fields<int range>     Consider only    │ │[x>=1]this many of the │ │most probable    │ │fields. Raising  │ │it grows the     │ │problem roughly  │ │quadratically    │ │[default: 50]    │ │--helpShow this message│ │and exit.        │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Solver Options ─────────────────────────────────────────────────────────────╮ │--timelimit<Astropy quantity>Time limit for MILP      │ │solver                   │ │[default: 1e+75 s]       │ │--memory<Astropy quantity>Maximum solver memory    │ │usage before terminating │ │[default: inf Gibyte]    │ │--jobs-j<int range> [x>=0]Number of threads for    │ │parallel processing, or 0│ │for all cores            │ │[default: 0]             │ │--cutoff<float range> [0<=x<=1]Objective cutoff. Give up│ │if there are no feasible │ │solutions with objective │ │value greater than or    │ │equal to this value      │ │--write-progressPROGRESS.ecsv          Save a time series of the│ │CPLEX objective value and│ │best bound to this file  │ │--write-modelMODEL.{lp,mps,sav}[.gz]Export the MILP model in │ │LP, SAV, or MPS format.  │ │Mainly useful for        │ │troubleshooting purposes │ ╰──────────────────────────────────────────────────────────────────────────────╯