Submission

Contents

Submission#

This page provides a step-by-step guide for submitting your code for the competition. See the schedule for submission dates.

Smoke Test (Optional)

The smoke test is an optional preliminary evaluation to:

  • Validate your submission process

  • Ensure your code runs on the evaluation infrastructure

  • Help identify issues before the final submission

Note

Teams are not expected to have fully operational submissions at this stage. The goal is to verify your code runs without crashing.

Finals (Required)

The finals submission is the scored evaluation that determines your final team ranking.

Submission Steps#

  1. Get Repository Access

    1. Submit team information: Complete the Google form before the smoke test deadline. You’ll receive an email invitation within 24-48 hours.

    2. Accept the GitHub invitation: Check your email and accept the invitation to your team’s private repository.

    Important

    Set up SSH key (if not already done): Follow GitHub’s guide to generate an SSH key and add it to your GitHub account.

  2. Upload Your Code

    Choose the option that matches your current setup:

    Option 1: You already use Git

    Add the submission repository as a remote and push your existing code:

    # Navigate to your existing repository
    cd your-existing-repo
    
    # Add the new repository as a remote
    git remote add submission [email protected]:usnistgov/ariac2025_{team_name}.git
    
    # Push your existing code
    git push submission main
    

    Option 2: You don’t use Git

    Clone the empty repository and copy your files:

    # Clone the empty repository
    git clone [email protected]:usnistgov/ariac2025_{team_name}.git
    cd ariac2025_{team_name}
    
    # Copy your existing files into this directory
    # Replace {path_to_existing_files} with your actual file path
    cp -r {path_to_existing_files}/* .
    
    # Add and commit your files
    git add .
    git commit -m "Initial commit with team code"
    git push origin main
    
  3. Create a Dockerfile

    Create a Dockerfile in your repository’s root directory. This file tells the evaluation system how to build and run your code. Your Dockerfile must include the base image, environment variables, and any setup needed for your solution.

    1. Use the correct base image:

      # For smoke test
      FROM nistariac/ariac2025:smoke_test
      
      # For finals
      FROM nistariac/ariac2025:final
      
    2. Set required environment variables:

      ENV TEAM_CONFIG=/team_ws/config/team_config.yaml
      ENV TEAM_COMMAND="ros2 launch your_package your_launch.py"
      

      Important

      TEAM_COMMAND can be a ROS 2 command or shell script. For shell scripts, set proper permissions with RUN chmod +x /path/to/script.sh.

    In addition the Dockerfile should:

    • Install all dependencies for your solution

    • Build your ROS workspace

    • Source the workspace in the container’s .bashrc

    Example Dockerfile:

    # ================================================================
    # Team overlay image extending ARIAC base
    # ================================================================
    
    FROM nistariac/ariac2025:final
    
    # Include neccessary environment variables
    ENV TEAM_COMMAND="ros2 run example_team submit_kit"
    ENV TEAM_CONFIG="/team_ws/src/example_team/config/example_team_config.yaml"
    
    # Create a new overlay workspace
    ENV TEAM_WS=/team_ws
    RUN mkdir -p $TEAM_WS/src
    WORKDIR $TEAM_WS
    
    # Copy team packages into the overlay workspace
    COPY ./ $TEAM_WS/src/
    
    # Update apt and install any OS dependencies needed for rosdep
    RUN apt-get update && \
        rosdep update && \
        rosdep install --from-paths src --ignore-src -r -y
    
    # This is how you can run a pip install for Python packages
    # RUN pip3 install -r $TEAM_WS/src/requirements.txt --break-system-packages
    
    # Build the workspace (symlink install is fine for overlays)
    RUN /bin/bash -c "source /opt/ros/jazzy/setup.bash && \
                      source /ariac_ws/install/setup.bash && \
                      colcon build --symlink-install"
    
    # Source automatically in container
    RUN echo "source /team_ws/install/setup.bash" >> /root/.bashrc
    
    WORKDIR $TEAM_WS
    CMD ["bash"]
    
  4. Test Your Submission

    1. Add a docker compose configuration to your repository:

      Example:

      services:
        ariac:
          build:
            context: .
            dockerfile: Dockerfile
          container_name: example_team
          ports:
            - "8080:8080"
          volumes:
            - /tmp/.X11-unix:/tmp/.X11-unix:rw
            - ./:/team_ws/src/
          environment:
            - DISPLAY=${DISPLAY}
          stdin_open: true
          tty: true
          
        ariac_nvidia:
          extends: ariac
          runtime: nvidia
          environment:
            - QT_X11_NO_MITSHM=1
            - NVIDIA_VISIBLE_DEVICES=all
            - NVIDIA_DRIVER_CAPABILITIES=all
            - XDG_RUNTIME_DIR=${XDG_RUNTIME_DIR}
            - __NV_PRIME_RENDER_OFFLOAD=1
            - __GLX_VENDOR_LIBRARY_NAME=nvidia
            - XAUTHORITY=${XAUTHORITY}
          volumes:
            - ${XAUTHORITY}:${XAUTHORITY}
      
    2. Start the container using docker compose:

      If you have an NVIDIA graphics card:

      docker compose up ariac_nvidia
      

      Otherwise:

      docker compose up ariac
      
    3. Launch the environment (in a new terminal):

      Open a new terminal in the container and launch the environment with your team config:

      docker exec -it your_container_name bash
      ros2 launch ariac_gz ariac.launch.py user_config:=$TEAM_CONFIG trial_config:=/path/to/trial/config.yaml
      
    4. Run your team command (in another new terminal):

      Open another terminal in the container and execute your team’s solution:

      docker exec -it your_container_name bash
      $TEAM_COMMAND
      
  5. Create Tagged Release

    NIST will evaluate your code using specific tagged versions. Create the appropriate tag for each submission:

    1. Create and push a git tag:

      # For smoke test
      git tag smoketest
      git push submission smoketest
      
      # For finals
      git tag final
      git push submission final
      

    Important

    Ensure all your code and Dockerfile are committed and pushed before creating a tag. Tags must be created before the submission deadline.