Skip to content

CSLC‐S1 Gamma Acceptance Testing Instructions

Jump to bottom
Scott Collins edited this page Aug 5, 2024 · 1 revision

This page contains instructions for performing Acceptance Testing for the CSLC-S1 Gamma delivery from the OPERA-ADT team. These instructions pertain to the latest version of the Gamma release, currently v4.2. These instructions assume the user has access to the JPL FN-Artifactory, and has Docker installed on their local machine. Optionally, access to the opera-pge-ci-ol8 AWS machine allows for significantly faster downloads from Artifactory.

Acquiring the CSLC-S1 Gamma Docker Image

The image is currently hosted on JPL FN-Artifactory, which requires JPL VPN access and JPL credentials. You may also need to be added to the gov.nasa.jpl.opera.adt organization.

Once you have access, the container tarball delivery is available under general/gov/nasa/jpl/opera/adt/cslc_s1/r4.2/gamma/dockerimg_cslc_s1_gamma_0.2.1.tar. Sample inputs are available under general/gov/nasa/jpl/opera/adt/cslc_s1/r4/gamma/delivery_cslc_s1_gamma_0.1.zip, but for the current release the expected outputs are in a separate archive under general/gov/nasa/jpl/opera/adt/cslc_s1/r4.2/gamma/expected_output_dir_cslc_s1_gamma_0.2.1.zip. Useful background documentation is also available under general/gov/nasa/jpl/opera/adt/cslc_s1/r4/gamma/documents.

Download all archives to a location on your local machine. This location will be referred to throughout this instructions as <CSLC_DIR> Note that the sample data is quite large, so the download from AF can take some time.

Loading the image into Docker

The first step in running the CSLC-S1 image is to load it into Docker via the following command:

docker load -i <CSLC_DIR>/dockerimg_cslc_s1_gamma_0.2.1.tar

This should add the Docker image to your local repository with the name opera/cslc_s1 and the tag gamma_0.2.1.

Preparing the test data

Once the delivery_cslc_s1_gamma_0.1.zip file is downloaded to your local machine, unpack it to <CSLC_DIR>:

cd <CSLC_DIR>; unzip delivery_cslc_s1_gamma_0.1.zip

This will create a delivery_cslc_s1_gamma_0.1 directory within <CSLC_DIR> containing the following files/directories:

* expected_output_dir/
  |_ t064_135518_iw1/
     |_ 20220501/
        |_ t064_135518_iw1_20220501.h5
        |_ t064_135518_iw1_20220501.png
  |_ <Additional per-burst directories with similar structure>
* input_data/
  |_ dem_4326.tiff
  |_ S1A_IW_SLC__1SDV_20220501T015035_20220501T015102_043011_0522A4_42CC.zip
  |_ S1A_OPER_AUX_POEORB_OPOD_20220521T081912_V20220430T225942_20220502T005942.EOF
  |_ jplg1210.22i
  |_ opera_burst_database_deploy_2022_1212.sqlite3
* output_s1_cslc/
* scratch_s1_cslc/
* runconfig_cslc_gamma.yaml

Once the expected_output_dir_cslc_s1_gamma_0.2.1.zip file is downloaded to your local machine, unpack it to <CSLC_DIR>:

cd <CSLC_DIR>; unzip expected_output_dir_cslc_s1_gamma_0.2.1.zip

This will create a expected_output_dir directory within <CSLC_DIR> containing the following files/directories:

* expected_output_dir/
  |_ t064_135518_iw1/
     |_ 20220501/
        |_ t064_135518_iw1_20220501.h5
        |_ static_layers_t064_135518_iw1.h5
        |_ t064_135518_iw1_20220501.png
  |_ <Additional per-burst directories with similar structure>

In order to execute the SAS, the input file directory, runconfig, scratch and output locations will be mounted into the container instance as Docker Volumes. To help streamline this process, we recommend making the following changes within the delivery_cslc_s1_gamma_0.2 directory:

  • Create a directory named runconfig, and copy and rename the existing runconfig YAML file into it:

    mkdir -p <CSLC_DIR>/delivery_cslc_s1_gamma_0.2/runconfig

    cp <CSLC_DIR>/delivery_cslc_s1_gamma_0.1/runconfig_cslc_gamma.yaml <CSLC_DIR>/delivery_cslc_s1_gamma_0.2/runconfig/runconfig_cslc_gamma.yaml

  • In the copied version of the runconfig, modify the following sections to change relative paths for input_data to the absolute path:

    input_file_group:
      # Required. List of SAFE files (min=1)
      safe_file_path: 
      - /home/compass_user/input_data/S1A_IW_SLC__1SDV_20220501T015035_20220501T015102_043011_0522A4_42CC.zip
      # Required. List of orbit (EOF) files (min=1)
      orbit_file_path: 
      - /home/compass_user/input_data/S1A_OPER_AUX_POEORB_OPOD_20220521T081912_V20220430T225942_20220502T005942.EOF
      # Optional. The unique burst ID to process
      burst_id: 

    dynamic_ancillary_file_group:
      # Digital elevation model
      dem_file: /home/compass_user/input_data/dem_4326.tiff
      tec_file: /home/compass_user/input_data/jplg1210.22i

    static_ancillary_file_group:
      burst_database_file: /home/compass_user/input_data/opera_burst_database_deploy_2022_1212.sqlite3

Also make sure static layer generation is enabled by setting the rdr2geo field to True under the processing section of the SAS config:

      processing:
          polarization: co-pol
          ...
          rdr2geo:
              enabled: True  # Set this flag to True to enable static layer generation

  • Create a delivery_cslc_s1_gamma_0.2 directory under <CSLC_DIR>

    mkdir <CSLC_DIR>/delivery_cslc_s1_gamma_0.2

  • Move the input_data, output_s1_slc and scratch_s1_slc directories from delivery_cslc_s1_gamma_0.1 to delivery_cslc_s1_gamma_0.2:

    mv <CSLC_DIR>/delivery_cslc_s1_gamma_0.1/{input_data,output_s1_slc,scratch_s1_slc} <CSLC_DIR>/delivery_cslc_s1_gamma_0.2/

  • Move the expected_output_dir extracted from expected_output_dir_cslc_s1_gamma_0.2.1.zip into the delivery_cslc_s1_gamma_0.2 directory:

    mv <CSLC_DIR>/expected_output_dir <CSLC_DIR>/delivery_cslc_s1_gamma_0.2/

  • Make sure the output and scratch directories have write permissions set

    chmod ga+w output_s1_cslc/ scratch_s1_clsc/

Executing the CSLC-S1 container on the sample datasets

We're now ready to execute the CSLC-S1 Gamma. Run the following the command to kick off execution with the test assets:

docker run --rm -u $(id -u):$(id -g) \
  -w /home/compass_user/scratch_s1_cslc \
  -v <CSLC_DIR>/delivery_cslc_s1_gamma_0.2/runconfig:/home/compass_user/runconfig:ro \
  -v <CSLC_DIR>/delivery_cslc_s1_gamma_0.2/input_data:/home/compass_user/input_data:ro \
  -v <CSLC_DIR>/delivery_cslc_s1_gamma_0.2/output_s1_cslc:/home/compass_user/output_s1_cslc \
  -v <CSLC_DIR>/delivery_cslc_s1_gamma_0.2/scratch_s1_cslc:/home/compass_user/scratch_s1_cslc \
  -i --tty opera/cslc_s1:gamma_0.2.1 s1_cslc.py /home/compass_user/runconfig/runconfig_cslc_gamma.yaml

Execution should take roughly 120 minutes. Once execution is complete, you should see 28 sub-directories within the scratch_s1_cslc/output_s1_cslc directory, one for each burst processed. Each burst subdir should contain a 20220501 directory which itself contains an .h5 file for the burst, an .h5 file for the static layers, and a single .png for the "browse" preview image.

Running the Quality Assurance test

Now that we've successfully executed the SAS container and generated outputs, the last step is to perform a QA check against the expected outputs.

Copy the set of output files generated within the scratch_s1_cslc/output_s1_cslc to the top-level output_s1_cslc directory:

cp -r <CSLC_DIR>/delivery_cslc_s1_gamma_0.2/scratch_s1_cslc/output_s1_cslc/* <CSLC_DIR>/delivery_cslc_s1_gamma_0.2/output_s1_cslc

The following shell script can be used to automated the comparisons across all burst-based products:

#!/bin/bash

declare -a burst_ids=(  "t064_135518_iw1"
                        "t064_135518_iw2"
                        "t064_135518_iw3"
                        "t064_135519_iw1"
                        "t064_135519_iw2"
                        "t064_135519_iw3"
                        "t064_135520_iw1"
                        "t064_135520_iw2"
                        "t064_135520_iw3"
                        "t064_135521_iw1"
                        "t064_135521_iw2"
                        "t064_135521_iw3"
                        "t064_135522_iw1"
                        "t064_135522_iw2"
                        "t064_135522_iw3"
                        "t064_135523_iw1"
                        "t064_135523_iw2"
                        "t064_135523_iw3"
                        "t064_135524_iw1"
                        "t064_135524_iw2"
                        "t064_135524_iw3"
                        "t064_135525_iw1"
                        "t064_135525_iw2"
                        "t064_135525_iw3"
                        "t064_135526_iw1"
                        "t064_135526_iw2"
                        "t064_135526_iw3"
                        "t064_135527_iw1")

for burst_id in "${burst_ids[@]}"; do
  echo "-------------------------------------"
  echo "Comparing results for ${burst_id}"

  docker run --rm -u $(id -u):$(id -g) -it \
    -v $(pwd)/delivery_cslc_s1_gamma_0.2.1/expected_output_dir:/home/compass_user/expected_output_dir:ro \
    -v $(pwd)/delivery_cslc_s1_gamma_0.2.1/output_s1_cslc:/home/compass_user/output_s1_cslc:ro \
    opera/cslc_s1:gamma_0.2 python /home/compass_user/OPERA/COMPASS/src/compass/utils/validate_product.py \
    -r /home/compass_user/expected_output_dir/${burst_id}/20220501/${burst_id}_20220501.h5 \
    -s /home/compass_user/output_s1_cslc/${burst_id}/20220501/${burst_id}_20220501.h5 \
    -p CSLC

  docker run --rm -u $(id -u):$(id -g) -it \
    -v $(pwd)/delivery_cslc_s1_gamma_0.2.1/expected_output_dir:/home/compass_user/expected_output_dir:ro \
    -v $(pwd)/delivery_cslc_s1_gamma_0.2.1/output_s1_cslc:/home/compass_user/output_s1_cslc:ro \
    opera/cslc_s1:gamma_0.2 python /home/compass_user/OPERA/COMPASS/src/compass/utils/validate_product.py \
    -r /home/compass_user/expected_output_dir/${burst_id}/20220501/static_layers_${burst_id}.h5 \
    -s /home/compass_user/output_s1_cslc/${burst_id}/20220501/static_layers_${burst_id}.h5 \
    -p static_layers
done

After giving the script a name, such as cslc_compare_products_gamma_0.2.1.sh and making it executable, you can compare all expected/actual products with the following command. The script must also be stored within <CSLC_DIR>.

<CSLC_DIR>/cslc_compare_products_gamma_0.2.1.sh

A similar console output should be returned for each of the burst products:

-------------------------------------
Comparing results for t064_135518_iw1
Comparing CSLC projection ...
Comparing geo transform arrays ...
Comparing raster arrays...
All CSLC product checks have passed
All CSLC metadata checks have passed
Comparing static_layers projection ...
Comparing geo transform arrays ...
Comparing raster arrays...
All CSLC product checks have passed
All CSLC metadata checks have passed
...

The expected results for this Acceptance Test are to see the All CSLC product checks have passed and All CSLC metadata checks have passed messages returned from the validation script for each burst product and for each static layers product. If any actual results differ, the output products from the Acceptance Test, as well as the results of the comparison script should be provided to ADT for diagnostics.

Known issues

  • This delivery utilizes the RAiDER library as a dependency within the container, and this library will by default output its log file to the current working directory set by the container (either by default or via the -w argument). This causes permission issues when trying to set the working directory to areas other than a scratch directory or location with write permissions set (such as /home/compass_user). This logging location should be set by COMPASS to use the designated scratch directory set by the runconfig.
Clone this wiki locally