CLI reference¶
Many pirate features are accessed via the command-line interface:
pirate_frb SUBCOMMAND [ARGS...]
where the list of subcommands, and documentation for each subcommand, are given below.
Subcommands¶
Subcommand |
Description |
|---|---|
|
Start FRB server(s) from an |
|
Toy FrbGrouper consumer(s): per-chunk peak SNR + argmax, optionally reported to a sifter |
|
Toy FrbSifter gRPC server: print a one-line summary of each received message |
|
Send fake X-engine data to one or more running FrbServers |
|
Connect to FrbServer(s) and stream status + filenames |
|
Send |
|
Run unit tests (use flags to select specific tests) |
|
Run simpulse tests (pulse-upsampling self-consistency) and write example plots to cwd |
|
Compare exact vs approximate analytic peak-finding variance for a config |
|
Monte-Carlo check of analytic peak-finding variance vs a ReferenceDedisperser |
|
Run timings (use flags to select specific timings) |
|
Run timing benchmarks from a dedisperser .yml file |
|
Print the YAML header of an ASDF file. (Note: ‘asdftool –info’ is also useful) |
|
Make an asdf file from an |
|
Parse a dedisperser .yml file and write info to stdout |
|
Show hardware information, including cpu affinity |
|
Show registered cuda kernels (use flags to select specific registries) |
|
For debugging: generate random DedispersionConfig(s) and print as YAML |
|
Parse |
|
Run hardware test from hwtest.yml (use -s to send data instead of receiving) |
|
A utility for maintaining |
|
A utility for maintaining |
|
For debugging: run whatever code is currently in |
|
Re-test the ~511 GiB cudaHostRegister cap (failure expected). |
Detailed usage¶
run_server¶
usage: pirate_frb run_server [-h] [-d SECONDS] [-G] [-D] [-q] server_config dedispersion_config
Start FRB server(s) from an frb_server .yml file and a dedispersion .yml file
positional arguments:
server_config Path to FrbServer YAML config file
dedispersion_config Path to DedispersionConfig YAML file
options:
-h, --help show this help message and exit
-d SECONDS, --delay SECONDS
Artificial per-frame delay in the processing thread (seconds; default 0). Used to simulate slow GPU work for testing FakeXEngine pacing.
-G, --no-grouper Disable FrbGrouper RPC even if grouper_ip_addrs is set in the config (GpuDedisperser runs with num_consumers=0).
-D, --no-dedispersion
Skip ALL GPU work in the processing thread: data is not even copied host->GPU, and no dequantization or dedispersion kernels run. The receive/assemble/ringbuf path still runs in full (the dedisperser is still
built, just never fed). Implies --no-grouper. Infrequently used corner case.
-q, --quiet Suppress the per-chunk "FrbServer: beamset=..." line (printed once per assembled time chunk).
run_toy_grouper¶
usage: pirate_frb run_toy_grouper [-h] [-d SECONDS] [-t SNR_THRESHOLD] (-s SIFTER_ADDR | -S) grouper_addr [grouper_addr ...]
Toy FrbGrouper consumer(s): per-chunk peak SNR + argmax, optionally reported to a sifter
positional arguments:
grouper_addr FrbGrouper listen address(es) 'ip:port' (e.g. 127.0.0.1:7000). With more than one, each grouper runs in its own child subprocess; if any child exits, the parent and all siblings exit.
options:
-h, --help show this help message and exit
-d SECONDS, --delay SECONDS
Artificial per-chunk delay (seconds) inserted into the grouper loop, e.g. -d 0.001 for a 1 ms delay (default: 0, no delay).
-t SNR_THRESHOLD, --snr-threshold SNR_THRESHOLD
Emit one event per chunk per beam whose peak SNR exceeds this threshold (default: 10).
-s SIFTER_ADDR, --sifter SIFTER_ADDR
Report to the FrbSifter at this 'ip:port' (e.g. 127.0.0.1:7100):
-S, --no-sifter Run without a sifter (don't send any sifter RPCs).
run_toy_sifter¶
usage: pirate_frb run_toy_sifter [-h] ADDR
Toy FrbSifter gRPC server: print a one-line summary of each received message
positional arguments:
ADDR Listen address 'ip:port' for the sifter gRPC server (e.g. 127.0.0.1:7100; use [::]:7100 or 0.0.0.0:7100 for all interfaces).
options:
-h, --help show this help message and exit
run_fake_xengine¶
usage: pirate_frb run_fake_xengine [-h] [-w WORKERS] [-P] [-N] [-G] [-j] [-f] [-g GAP_SEC] [-s SIFTER_ADDR] RPC_ADDR [RPC_ADDR ...]
Send fake X-engine data to one or more running FrbServers
positional arguments:
RPC_ADDR One or more "ip:port" strings (one per receiver)
options:
-h, --help show this help message and exit
-w WORKERS, --workers WORKERS
Number of worker threads per FakeXEngine (default 128)
-P, --unpaced Disable pacing -- send chunks as fast as possible (default: pace to stay <=5 chunks ahead of server)
-N, --unnormalized Send unnormalized data -- leave scales/offsets arbitrary (default: calibrate them to the per-zone noise variance)
-G, --non-gaussian Fill int4 data with uniform noise over [-8,+7] (default: simulated Gaussian noise clamped to [-7,+7])
-j, --send-junk Randomize+send only the first chunk; send all-zero junk for every subsequent chunk (skips per-chunk randomization)
-f, --frbs Inject simulated FRBs (parameters derived from the server GetConfig: max DM, base-tree width, and the frequency subbands). Prints one line per injected FRB. Incompatible with -N, -G, and -j.
-g GAP_SEC, --gap GAP_SEC
Extra padding (seconds) between consecutive simulated FRBs on a beam (default 0). Requires -f.
-s SIFTER_ADDR, --sifter SIFTER_ADDR
Send the simulated FRB events (from_simulator=True) to an FrbSifter at this "ip:port". Requires -f.
rpc_status¶
usage: pirate_frb rpc_status [-h] ADDRESS [ADDRESS ...]
Connect to FrbServer(s) and stream status + filenames
positional arguments:
ADDRESS Server address(es) (e.g. 127.0.0.1:6000)
options:
-h, --help show this help message and exit
rpc_write¶
usage: pirate_frb rpc_write [-h] ADDRESS [ADDRESS ...]
Send write_files RPC to FrbServer(s) with random beams/time range
positional arguments:
ADDRESS Server address(es) (e.g. 127.0.0.1:6000)
options:
-h, --help show this help message and exit
test¶
usage: pirate_frb test [-h] [-g GPU] [-n NITER] [--rt] [--pfwr] [--pfom] [--gldk] [--gddk] [--gpfk] [--grck] [--gtgk] [--gdqk] [--cdd2] [--casm] [--zomb] [--dd] [--avar] [--chime] [--net] [--serv] [--sim]
Run unit tests (use flags to select specific tests)
options:
-h, --help show this help message and exit
-g GPU, --gpu GPU GPU to use for tests (default 0)
-n NITER, --niter NITER
Number of unit test iterations (default 100)
--rt Runs ReferenceTree and ReferenceLagbuf tests
--pfwr Runs PfWeightReaderMicrokernel.test_random()
--pfom Runs PfOutputMicrokernel.test_random()
--gldk Runs GpuLaggedDownsamplingKernel.test_random()
--gddk Runs GpuDedispersionKernel.test_random()
--gpfk Runs GpuPeakFindingKernel.test_random()
--grck Runs GpuRingbufCopyKernel.test_random()
--gtgk Runs GpuTreeGriddingKernel.test_random()
--gdqk Runs GpuDequantizationKernel.test_random()
--cdd2 Runs CoalescedDdKernel2.test_random()
--casm Runs some casm tests
--zomb Runs "zombie" tests (code that I wrote during protoyping that may never get used)
--dd Runs GpuDedisperser.test_random()
--avar Runs tests related to analytic variance
--chime Runs test_chime_frb_upchan()
--net Runs network/allocator tests (AssembledFrameAllocator, etc.)
--serv Runs end-to-end FakeXEngine -> FrbServer -> GpuDedisperser -> FrbGrouper test
--sim Runs avx2_simulate_4bit_noise() distribution test + AssembledFrame pulse-injection test
test_simpulse¶
usage: pirate_frb test_simpulse [-h] [-n NITER]
Run simpulse tests (pulse-upsampling self-consistency) and write example plots to cwd
options:
-h, --help show this help message and exit
-n NITER, --niter NITER
Number of upsampling-test iterations (default 100)
check_avar_approximation¶
usage: pirate_frb check_avar_approximation [-h] [-r] config_file
Compare exact vs approximate analytic peak-finding variance for a config
positional arguments:
config_file Path to dedispersion YAML config file
options:
-h, --help show this help message and exit
-r, --random-variances
Use random per-channel variances (config.make_random_freq_variances) instead of all-ones
check_avar_mc¶
usage: pirate_frb check_avar_mc [-h] [-r] [-s SOPHISTICATION] config_file
Monte-Carlo check of analytic peak-finding variance vs a ReferenceDedisperser
positional arguments:
config_file Path to dedispersion YAML config file
options:
-h, --help show this help message and exit
-r, --random-variances
Use random per-channel input variances (config.make_random_freq_variances) instead of all-ones
-s SOPHISTICATION, --sophistication SOPHISTICATION
ReferenceDedisperser sophistication (0, 1, or 2; default 1)
time¶
usage: pirate_frb time [-h] [-g GPU] [-t NTHREADS] [--ncu] [--gldk] [--gddk] [--casm] [--chime] [--zomb] [--cdd2] [--gdqk] [--gtgk] [--sim]
Run timings (use flags to select specific timings)
options:
-h, --help show this help message and exit
-g GPU, --gpu GPU GPU to use for timing (default 0)
-t NTHREADS, --nthreads NTHREADS
number of CPU threads (only for time_cpu_downsample)
--ncu Just run a single kernel (intended for profiling with nvidia 'ncu')
--gldk Runs time_lagged_downsampling_kernels()
--gddk Runs time_gpu_dedispersion_kernels()
--casm Runs CasmBeamformer.run_timings()
--chime Runs time_chime_frb_{beamform,upchan}()
--zomb Runs "zombie" timings (code that I wrote during protoyping that may never get used)
--cdd2 Runs CoalescedDdKernel2.time_selected()
--gdqk Runs GpuDequantizationKernel.time_selected()
--gtgk Runs GpuTreeGriddingKernel.time_selected()
--sim Runs avx2_simulate_4bit_noise() timing
time_dedisperser¶
usage: pirate_frb time_dedisperser [-h] [-n NITER] [-b BEAMS] [-g MAX_GPU_CLAG] [-H] [--python] config_file
Run timing benchmarks from a dedisperser .yml file
positional arguments:
config_file Path to YAML config file
options:
-h, --help show this help message and exit
-n NITER, --niter NITER
Number of iterations for timing (default 1000)
-b BEAMS, --beams BEAMS
Override config.beams_per_gpu with specified value
-g MAX_GPU_CLAG, --max-gpu-clag MAX_GPU_CLAG
Override config.max_gpu_clag with specified value
-H, --no-hugepages Disable hugepages
--python Use Python/cupy timing instead of C++ (for testing pybind11 interface)
show_asdf¶
usage: pirate_frb show_asdf [-h] asdf_file
Print the YAML header of an ASDF file. (Note: 'asdftool --info' is also useful)
positional arguments:
asdf_file Path to ASDF file
options:
-h, --help show this help message and exit
show_file_format¶
usage: pirate_frb show_file_format [-h] [-n] metadata_yaml
Make an asdf file from an xengine_metadata YAML file, and write the header to stdout.
positional arguments:
metadata_yaml Path to xengine_metadata YAML file
options:
-h, --help show this help message and exit
-n, --non-verbose Emit the YAML header without the documentation comments (verbose=False).
show_dedisperser¶
usage: pirate_frb show_dedisperser [-h] [-v] [-c] [-t] [-z] [-s STREAMS] [-b BEAMS] [-g MAX_GPU_CLAG] [--channel-map] [-r] [-R] [--test] config_file
Parse a dedisperser .yml file and write info to stdout
positional arguments:
config_file Path to YAML config file
options:
-h, --help show this help message and exit
-v, --verbose Include comments explaining the meaning of each field
-c, --config Also print the DedispersionConfig, with a separator, before the plan (by default only the plan is printed, matching the dedispersion_plan_yaml sent to the grouper)
-t, --time Also print how long DedispersionPlan and C++ PfAvarApproximation construction took (non-deterministic lines; off by default so the output is reproducible)
-z, --zones Include the per-clag mega_ringbuf host/gpu zone breakdown (independent of -v, which controls comments)
-s STREAMS, --streams STREAMS
Override config.num_active_batches with specified value
-b BEAMS, --beams BEAMS
Override config.beams_per_gpu with specified value
-g MAX_GPU_CLAG, --max-gpu-clag MAX_GPU_CLAG
Override config.max_gpu_clag with specified value
--channel-map Show channel map tree->freq (warning: produces long output!)
-r, --resources Show resource tracking (all kernels must be precompiled)
-R, --fine-grained-resources
Like -r, but shows fine-grained per-kernel info
--test Run GpuDedisperser.test_one() with config
show_hardware¶
usage: pirate_frb show_hardware [-h]
Show hardware information, including cpu affinity
options:
-h, --help show this help message and exit
show_kernels¶
usage: pirate_frb show_kernels [-h] [--pfom] [--pfwr] [--gddk] [--gpfk] [--cdd2]
Show registered cuda kernels (use flags to select specific registries)
options:
-h, --help show this help message and exit
--pfom Show PfOutputMicrokernel registry
--pfwr Show PfWeightReaderMicrokernel registry
--gddk Show GpuDedispersionKernel registry
--gpfk Show GpuPeakFindingKernel registry
--cdd2 Show CoalescedDdKernel2 registry
show_random_config¶
usage: pirate_frb show_random_config [-h] [-n NCONFIG] [-a] [-v]
For debugging: generate random DedispersionConfig(s) and print as YAML
options:
-h, --help show this help message and exit
-n NCONFIG generate multiple random configs
-a generate arbitrary random config, without restricting to precompiled kernels
-v verbose
show_xengine_metadata¶
usage: pirate_frb show_xengine_metadata [-h] [-v] config_file
Parse xengine_metadata yml file and write info to stdout
positional arguments:
config_file Path to YAML config file
options:
-h, --help show this help message and exit
-v, --verbose Include comments explaining the meaning of each field
hwtest¶
usage: pirate_frb hwtest [-h] [-t TIME] [-s] config_file
Run hardware test using YAML config file (use -s to send data instead of receiving).
Runs and times parallel synthetic loads: network IO, disk IO, PCIe transfers
between GPU and host, GPU compute kernels, CPU compute kernels, host memory
bandwidth.
Example networking-only run::
# On cf05. The test will pause after "listening for TCP connections".
python -m pirate_frb hwtest configs/hwtest/cf05_net64.yml
# On cf00. Send to all four IP addresses on cf05.
python -m pirate_frb hwtest -s configs/hwtest/cf05_net64.yml
See configs/hwtest/*.yml for more examples.
positional arguments:
config_file Path to YAML config file
options:
-h, --help show this help message and exit
-t TIME, --time TIME Number of seconds to run test (default 20)
-s, --send Send data to test server (uses ip_addrs from config file)
make_subbands¶
usage: pirate_frb make_subbands [-h] [-r PF_RANK] fmin fmax threshold
A utility for maintaining makefile_helper.py.
The 'threshold' argument is a "target" fractional bandwidth. For example, if threshold=0.2,
then the make_subbands command will try to make bands whose fractional bandwidth is <= 20%.
However, some subbands may be wider than the threshold, due to technical constraints.
Example usage::
# Specify frequency min, max, and threshold
python -m make_subbands 300 1500 0.2
python -m make_subbands 400 800 0.1 -r 4
positional arguments:
fmin Minimum frequency (MHz)
fmax Maximum frequency (MHz)
threshold Threshold for fmin/fmax
options:
-h, --help show this help message and exit
-r PF_RANK, --pf-rank PF_RANK
Peak finding rank (default: 4)
random_kernels¶
usage: pirate_frb random_kernels [-h] [-n N] [--pf] [--cdd2] [--pfwr]
A utility for maintaining makefile_helper.py
options:
-h, --help show this help message and exit
-n N Number of random kernels to print (default 20)
--pf Print random PeakFinder kernel params
--cdd2 Print random CoalescedDdKernel2 kernel params
--pfwr Print random PfWeightReader kernel params
scratch¶
usage: pirate_frb scratch [-h]
For debugging: run whatever code is currently in src_lib/scratch.cu)
options:
-h, --help show this help message and exit
revisit_512gb¶
usage: pirate_frb revisit_512gb [-h] [-H]
Re-test the ~511 GiB single-call cudaHostRegister() cap on the current CUDA / driver version. The cap is an undocumented driver limit that currently forces pirate's BumpAllocator to register memory in chunks (see comments in BumpAllocator.hpp and constants.hpp). If this command starts succeeding on some future CUDA / driver release, the chunked-register workaround could potentially be simplified or removed.
Test: mmap 550 GiB (hugepages with -H, 4 KiB pages otherwise), prefault, then attempt a single cudaHostRegister() over the entire region. Cleans up either way.
Requires ~600 GiB of free memory of the requested type.
options:
-h, --help show this help message and exit
-H, --hugepages Use 2 MiB hugepages (default: 4 KiB regular pages).