mwatelescope/giant-squid

giant-squid

镜像概述和主要用途

giant-squid 是 MWA ASVO 的替代客户端。它最初是用Haskell编程语言开发的MWA ASVO相关任务库（现已迁移至Rust），但不仅是一个库，其可执行文件还可作为 https://github.com/ICRAR/manta-ray-client 的替代品，为用户提供更优的使用体验。有关MWA ASVO的一般使用帮助，请访问 MWA ASVO wiki。

HPC用户注意
若在HPC系统上运行giant-squid，请阅读 此wiki文章。

核心功能和特性

1. 默认情况下，giant-squid 会对流式下载的MWA ASVO数据进行即时解压缩。无需先下载大型tar文件（可能超过100 GiB）再手动解压缩（从而避免占用双倍空间和昂贵的IO操作），使用 --keep-tar 选项可保留tar文件。

2. 指定 --keep-tar 时，giant-squid 支持恢复中断的部分下载，并在下载命令再次运行时从断点继续。此外，若待下载文件已存在且文件大小和校验和匹配预期值，则会跳过重复下载。

3. 提交作业无需CSV文件，直接通过命令行参数完成。

4. 对于接受obsid或作业ID的命令，支持使用文本文件输入。文本文件中的每个条目会被验证（必须为10位整数），若存在无效条目则报错并终止命令。

5. 支持以JSON格式打印MWA ASVO队列，便于其他编程语言解析作业状态。

6. 默认验证归档文件的哈希值，可通过 --skip-hash 跳过验证。

使用场景和适用范围

• HPC系统用户：需高效处理大型数据下载，关注磁盘空间占用和IO效率。
• MWA望远镜数据用户：需要替代manta-ray-client的客户端，尤其关注下载恢复、流式解压缩和作业管理效率。
• 自动化数据处理流程：通过JSON输出队列状态，便于集成到脚本或程序中进行自动化处理。

详细使用方法和配置说明

基本命令

查看帮助文本

bash
giant-squid -h

所有子命令也支持帮助查看，例如：

bash
giant-squid download -h

查看版本

bash
giant-squid --version
giant-squid -V

作业管理

列出MWA ASVO作业

bash
giant-squid list
giant-squid l

以JSON格式列出作业

以下命令等效：

bash
giant-squid list --json
giant-squid list -j
giant-squid l -j

示例输出：

bash
giant-squid list -j
{"325430":{"obsid":1090528304,"jobId":325430,"jobType":"DownloadVisibilities","jobState":"Ready","files":[{"fileName":"1090528304_vis.zip","fileSize":10762878689,"fileHash":"ca0e89e56cbeb05816dad853f5bab0b4075097da"}]},"325431":{"obsid":1090528432,"jobId":325431,"jobType":"DownloadVisibilities","jobState":"Ready","files":[{"fileName":"1090528432_vis.zip","fileSize":10762875021,"fileHash":"9d9c3c0f56a2bb4e851aa63cdfb79095b29c66c9"}]}}

jobType 允许值：Conversion、DownloadVisibilities、DownloadMetadata、DownloadVoltage、CancelJob。

jobState 允许值：Queued、WaitCal、Staging、Staged、Downloading、Preprocessing、Imaging、Delivering、Ready、Error: Text（如"Error: some error message"）、Expired、Cancelled。

筛选作业列表

giant-squid list 接受可选的标识符列表（obsid或job ID，但不可混合），并支持 --types 和 --states 选项进一步筛选。参数值不区分大小写，支持多种格式（如 dOwNlOaD__vIsIbIlItIeS、download-metadata 等）。

示例：筛选obsid为或、jobType为DownloadVisibilities/DownloadMetadata/CancelJob、jobState为Preprocessing/Queued的作业：

bash
giant-squid list \
   --types dOwNlOaD__vIsIbIlItIeS,download-metadata,CANCELJOB \
   --states PrepRoCeSsInG,__Q_u_e_u_e_D__ \
   1234567890 1234567891

数据下载

基本下载

下载作业ID ***到当前目录：

bash
giant-squid download 12345
# 或简写
giant-squid d 12345

下载obsid ***到当前目录（10位数字被识别为obsid）：

bash
giant-squid download 1065880128
giant-squid d 1065880128

支持通过文本文件指定多个obsid或job ID。

指定下载目录

使用 --download-dir 或 -d 指定目录：

bash
giant-squid download --download-dir /tmp 1065880128
giant-squid d -d /tmp 1065880128

保留tar包与恢复下载

• 默认流式解压缩；使用 -k 或 --keep-tar 保留tar包。
• 配合 --keep-tar 时支持恢复中断的下载，若文件已存在且校验通过则跳过。

并发下载

默认并发下载数为4（当下载作业数≥4时），可通过 --concurrent-downloads N 或 -c N 调整（N≥1）：

bash
giant-squid download -c 2 12345 67890

缓冲区大小调整

默认下载时缓存100 MiB数据后写入磁盘，可通过环境变量 GIANT_SQUID_BUF_SIZE 调整（单位：MiB）：

bash
export GIANT_SQUID_BUF_SIZE=50
giant-squid download 12345

作业提交

交付选项

提交作业前需选择数据交付方式，环境变量 GIANT_SQUID_DELIVERY 可设置默认值（acacia、scratch 或 dug），也可通过 -d 或 --delivery 临时指定。

• Acacia（默认）：文件打包上传至Pawsey的Acacia对象存储，生成7天有效期的下载URL（Voltage作业不支持）。
• scratch：文件交付至Pawsey的/scratch文件系统，需MWA ASVO配置Pawsey组（仅部分用户可用）。
• dug：文件交付至DUG文件系统，需MWA ASVO配置DUG组（仅部分用户可用，Voltage作业不支持）。

提交可见性下载作业

提交obsid ***的可见性数据下载作业：

bash
giant-squid submit-vis 1065880128
# 或简写
giant-squid sv 1065880128

支持文本文件输入obsid，--dry-run 或 -n 可预览提交（不实际执行）。

提交转换作业

提交obsid ***的转换作业：

bash
giant-squid submit-conv 1065880128
# 或简写
giant-squid sc 1065880128

通过 -p 指定转换参数（键值对，逗号分隔）：

bash
giant-squid submit-conv 1065880128 -p avg_time_res=0.5,avg_freq_res=10

提交元数据下载作业

提交obsid ***的元数据下载作业（含metafits和cotter标志文件）：

bash
giant-squid submit-meta 1065880128
# 或简写
giant-squid sm 1065880128

提交电压数据下载作业

提交obsid ***的电压数据下载作业（需指定scratch交付）：

bash
giant-squid submit-volt --delivery scratch --offset 0 --duration 8 1065880128
# 或简写
giant-squid sv -d scratch -o 0 -u 8 1065880128

可选参数 --from_channel 和 --to_channel 限制接收通道范围（0-255，含边界）。

重提交作业

默认不允许提交与现有队列中（非错误状态）作业参数完全相同的作业，使用 --allow-resubmit 或 -r 强制重提交：

bash
giant-squid submit-vis -r 1065880128

Docker部署示例

bash
docker run mwatelescope/giant-squid:latest -h

查看帮助后，可按上述命令格式使用，例如列出作业：

bash
docker run mwatelescope/giant-squid:latest list -j