Skip to content

CSLC‐S1 Final 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 Final delivery from the OPERA-ADT team. These instructions pertain to the latest version of the Final release, currently v6.4. 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-dev-pge AWS machine allows for significantly faster downloads from Artifactory.

Acquiring the CSLC-S1 Final 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/r6.4/final/dockerimg_cslc_s1_final_0.5.5.tar. Sample inputs are available under general/gov/nasa/jpl/opera/adt/cslc_s1/r6.4/final/delivery_cslc_s1_final_0.5.5.zip. Useful background documentation is also available under general/gov/nasa/jpl/opera/adt/cslc_s1/r6/final/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_final_0.5.5.tar

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

Preparing the test data

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

cd <CSLC_DIR>; unzip delivery_cslc_s1_final_0.5.5.zip

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

* expected_output_s1_cslc/
  |_ t064_135518_iw1/
     |_ 20220501/
        |_ t064_135518_iw1_20220501.h5
        |_ t064_135518_iw1_20220501.png
  |_ <Additional per-burst directories with similar structure>
* expected_output_s1_cslc_static/
  |_ t064_135518_iw1/
     |_ 20220501/
        |_ static_layers_t064_135518_iw1.h5
  |_ <Additional per-burst directories with similar structure>
* input_data/
  |_ burst_db_0.2.0_230831-bbox-only.sqlite
  |_ dem_4326.tiff
  |_ jplg1210.22i
  |_ S1A_IW_SLC__1SDV_20220501T015035_20220501T015102_043011_0522A4_42CC.zip
  |_ S1A_OPER_AUX_POEORB_OPOD_20220521T081912_V20220430T225942_20220502T005942.EOF
* runconfig_cslc_s1_r6.1.yaml
* runconfig_cslc_s1_static_r6.1.yaml
* scratch_s1_cslc/
* scratch_s1_cslc_static/

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_final_0.5.5 directory:

  • Create directories for the SAS to write output products to:

    mkdir -p <CSLC_DIR>/delivery_cslc_s1_final_0.5.5/{output_s1_cslc,output_s1_cslc_static}

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

    mkdir -p <CSLC_DIR>/delivery_cslc_s1_final_0.5.5/runconfig

    cp <CSLC_DIR>/delivery_cslc_s1_final_0.5.5/runconfig_cslc_s1_*.yaml <CSLC_DIR>/delivery_cslc_s1_final_0.5.5/runconfig/

  • In the copied versions of both runconfigs, 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/burst_db_0.2.0_230831-bbox-only.sqlite

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

    chmod ga+w <CSLC_DIR>/delivery_cslc_s1_final_0.5.5/{output_s1_cslc,output_s1_cslc_static,scratch_s1_cslc,scratch_s1_cslc_static}

Executing the CSLC-S1 container on the sample datasets

We're now ready to execute the CSLC-S1 Final delivery. 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 \
  -v <CSLC_DIR>/delivery_cslc_s1_final_0.5.5/runconfig:/home/compass_user/runconfig:ro \
  -v <CSLC_DIR>/delivery_cslc_s1_final_0.5.5/input_data:/home/compass_user/input_data:ro \
  -v <CSLC_DIR>/delivery_cslc_s1_final_0.5.5/output_s1_cslc:/home/compass_user/output_s1_cslc \
  -v <CSLC_DIR>/delivery_cslc_s1_final_0.5.5/scratch_s1_cslc:/home/compass_user/scratch_s1_cslc \
  -i --tty opera/cslc_s1:final_0.5.5 s1_cslc.py /home/compass_user/runconfig/runconfig_cslc_s1_r6.1.yaml

On a c6i.2xlarge instance, execution should take about 50 minutes.

To run the container in static layer generation mode:

docker run --rm -u $(id -u):$(id -g) \
  -w /home/compass_user \
  -v <CSLC_DIR>/delivery_cslc_s1_final_0.5.5/runconfig:/home/compass_user/runconfig:ro \
  -v <CSLC_DIR>/delivery_cslc_s1_final_0.5.5/input_data:/home/compass_user/input_data:ro \
  -v <CSLC_DIR>/delivery_cslc_s1_final_0.5.5/output_s1_cslc_static:/home/compass_user/output_s1_cslc_static \
  -v <CSLC_DIR>/delivery_cslc_s1_final_0.5.5/scratch_s1_cslc_static:/home/compass_user/scratch_s1_cslc_static \
  -i --tty opera/cslc_s1:final_0.5.5 s1_cslc.py /home/compass_user/runconfig/runconfig_cslc_s1_static_r6.1.yaml

On a c6i.2xlarge instance, execution should take about 135 minutes.

Once execution is complete, you should see 28 sub-directories within the output_s1_cslc and output_s1_cslc_static directories, one for each burst processed. Each burst subdir should contain a 20220501 directory which itself contains the products.

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.

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_final_0.5.5/expected_output_s1_cslc:/home/compass_user/expected_output_s1_cslc:ro \
    -v $(pwd)/delivery_cslc_s1_final_0.5.5/output_s1_cslc:/home/compass_user/output_s1_cslc:ro \
    opera/cslc_s1:final_0.5.5 python /home/compass_user/OPERA/COMPASS/src/compass/utils/validate_product.py \
    -r /home/compass_user/expected_output_s1_cslc/${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_final_0.5.5/expected_output_s1_cslc_static:/home/compass_user/expected_output_s1_cslc_static:ro \
    -v $(pwd)/delivery_cslc_s1_final_0.5.5/output_s1_cslc_static:/home/compass_user/output_s1_cslc_static:ro \
    opera/cslc_s1:final_0.5.5 python /home/compass_user/OPERA/COMPASS/src/compass/utils/validate_product.py \
    -r /home/compass_user/expected_output_s1_cslc_static/${burst_id}/20220501/static_layers_${burst_id}.h5 \
    -s /home/compass_user/output_s1_cslc_static/${burst_id}/20220501/static_layers_${burst_id}.h5 \
    -p static_layers
done

After giving the script a name, such as cslc_compare_products_final_0.5.5.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_final_0.5.5.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.

Clone this wiki locally