feat(CI): improve readme and code coverage

.bazelrc

@@ -51,4 +51,4 @@ build --action_env=LD_LIBRARY_PATH=
 # use python3 by default
 build --python_path=python3
 
-build --define=WITH_GUROBI=ON
+build --define=WITH_GUROBI=ON

.cirrus.yml

@@ -1,10 +1,14 @@
 registry_config: ENCRYPTED[!88cf0d757d2f8b93dca9e57dc166b65ddedef6378e7ac12a91a022ab3fb28dd47b10d452dc5c53a68e144e6bdbae999b!]
 jammy_task:
+  only_if: "$CIRRUS_PR != ''  || $CIRRUS_BRANCH == 'main'" # This condition ensures the task runs only for PRs or on the main branch.
   timeout_in: 120m
   container:
     image: ghcr.io/dairlab/docker-dair/jammy-dair-base:v1.42
     cpu: 8
     memory: 24
+  format_script:
+    - apt update && apt install -y clang-format
+    - ./tools/scripts/check_format.sh
   test_script:
     - export CC=clang-15
     - export CXX=clang++-15
@@ -17,19 +21,24 @@ jammy_task:
     - bazel test
       --local_resources=ram=24000
       --local_resources=cpu=8
+      --jobs=8
+      --test_output=all
       --remote_cache=http://$CIRRUS_HTTP_CACHE_HOST
       //...
-  always:
-    jammy_test_artifacts:
-      path: "bazel-testlogs/**/test.xml"
-      format: junit
+  jammy_test_artifacts:
+    path: "bazel-testlogs/**/test.xml"
+    format: junit
 
 noble_task:
+  only_if: "$CIRRUS_PR != ''  || $CIRRUS_BRANCH == 'main'" # This condition ensures the task runs only for PRs or on the main branch.
   timeout_in: 120m
   container:
     image: ghcr.io/dairlab/docker-dair/noble-dair-base:v1.42
     cpu: 8
     memory: 24
+  format_script:
+    - apt update && apt install -y clang-format
+    - ./tools/scripts/check_format.sh
   test_script:
     - export CC=clang-15
     - export CXX=clang++-15
@@ -42,9 +51,10 @@ noble_task:
     - bazel test
       --local_resources=ram=24000
       --local_resources=cpu=8
+      --jobs=8
+      --test_output=all
       --remote_cache=http://$CIRRUS_HTTP_CACHE_HOST
       //...
-  always:
-    noble_test_artifacts:
-      path: "bazel-testlogs/**/test.xml"
-      format: junit
+  noble_test_artifacts:
+    path: "bazel-testlogs/**/test.xml"
+    format: junit

.github/workflows/coverage.yml

@@ -0,0 +1,79 @@
+name: C3 Coverage
+on: 
+  push:
+    branches:
+      - main
+  pull_request:
+jobs:
+  # Only run coverage on Noble
+  coverage:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: ci-${{ github.ref }}
+      cancel-in-progress: true
+    container: 
+      image: ghcr.io/dairlab/docker-dair/noble-dair-base:v1.42
+      credentials:
+       username: ${{ github.actor }}
+       password: ${{ secrets.GITHUB_TOKEN }}
+      options: --cpus 4
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v4
+      - name: Install required dependencies
+        run: apt update && apt install -y lcov
+      - name: Restore coverage cache
+        id: c3-cov-cache-restore
+        uses: actions/cache/restore@v4
+        with:
+          path: ~/.cache/bazel
+          key: c3-bazel-cov-cache-${{ hashFiles('**/BUILD.bazel') }}
+          restore-keys: |
+            c3-bazel-cov-cache-
+      - name: Generate Coverage 
+        run: bazel coverage
+              --combined_report=lcov
+              --local_resources=ram=24000
+              --local_resources=cpu=4
+              --jobs=4
+              //...
+      - name: Report code coverage
+        uses: zgosalvez/[email protected]
+        with:
+          coverage-files: bazel-out/_coverage/_coverage_report.dat
+          minimum-coverage: 90
+          artifact-name: noble-code-coverage-report
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          update-comment: true
+      - name: Save coverage cache
+        id: c3-cov-cache-save
+        if: always() && !cancelled() && steps.c3-cov-cache-restore.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          key: ${{ steps.c3-cov-cache-restore.outputs.cache-primary-key }}
+          path: ~/.cache/bazel
+      - run: echo "🍏 This job's status is ${{ job.status }}."
+  # Deploy job
+  deploy:
+    # Add a dependency to the build job
+    needs: coverage
+    if: ${{ github.event_name == 'push' }}
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4 # or specific "vX.X.X" version tag for this action
+        with:
+          artifact_name: noble-code-coverage-report

.gitignore

@@ -6,4 +6,5 @@
 MODULE.bazel.lock
 **/__pycache__/** 
 .vscode
-*.ps
+*.ps
+genhtml/*

BUILD.bazel

@@ -1,2 +1,28 @@
-# This is an empty BUILD file, to ensure that the project's root directory is a
-# bazel package.
+LIBC3_COMPONENTS = [
+    "//core:core",
+    "//multibody:multibody",
+    "//systems:systems",
+]
+
+package(default_visibility = ["//visibility:public"])
+
+# Filegroup collecting all headers
+filegroup(
+    name = "c3_headers",
+    srcs = [
+        "//core:headers",
+        "//multibody:headers",
+        "//systems:headers",
+    ],
+)
+
+# Combined target that provides both the shared library and headers
+cc_library(
+    name = "libc3",
+    hdrs = [":c3_headers"],  # Changed from srcs to hdrs for headers
+    deps = LIBC3_COMPONENTS + [
+        "@drake//:drake_shared_library",
+    ],
+    include_prefix = "c3",
+    visibility = ["//visibility:public"],
+)

README.md

@@ -1,28 +1,157 @@
-# C3
-Consensus Complementarity Control
+# C3: Consensus Complementarity Control
 
-This is a standalone repository for the C3 algorithm. For more in-depth examples, see dairlib. 
-Currently we only officially support Ubuntu 22.04. 
+[**Main Paper: Consensus Complementarity Control**](https://arxiv.org/abs/2304.11259)
 
-## Build from source
-1. Clone C3 (Don't change to the c3 directory yet)
-```shell
-git clone --filter=blob:none [email protected]:DAIRLab/c3.git 
-```
+<p align="center">
+    <a href="https://cirrus-ci.com/github/DAIRLab/c3">
+        <strong style="vertical-align: middle;">Build (Noble)</strong>
+        <img src="https://api.cirrus-ci.com/github/DAIRLab/c3.svg?task=noble&script=test&branch=main" alt="Noble Test Report" style="vertical-align: middle;"/>
+    </a>
+    &nbsp;&nbsp;
+    <a href="https://cirrus-ci.com/github/DAIRLab/c3">
+        <strong style="vertical-align: middle;">Build (Jammy)</strong>
+        <img src="https://api.cirrus-ci.com/github/DAIRLab/c3.svg?task=jammy&script=test&branch=main" alt="Jammy Test" style="vertical-align: middle;"/>
+    </a>
+    &nbsp;&nbsp;
+    <a href="https://github.com/DAIRLab/c3/actions/workflows/coverage.yml"><strong style="vertical-align: middle;">Coverage</strong>
+        <img src="https://github.com/DAIRLab/c3/actions/workflows/coverage.yml/badge.svg?branch=main&event=push" alt="C3 Coverage" style="vertical-align: middle;"/>
+    </a>
+</p>
 
-2. Install Drake's dependencies by running the commands below. This will download the specific Drake release used by C3, and install the corresponding dependencies. 
-```shell
-git clone --depth 1 --branch v1.35.0 https://github.com/RobotLocomotion/drake.git
-sudo drake/setup/ubuntu/install_prereqs.sh
-```
-3. Follow the instructions at https://drake.mit.edu/bazel.html to install Gurobi 10.0
-4. Change to the C3 Directory, and build the repo:
-```shell
-cd c3
-bazel build ...
+This repository contains the reference implementation of the [Consensus Complementarity Control (C3)](https://arxiv.org/abs/2304.11259) algorithm. For more in-depth examples, see [dairlib](https://github.com/DAIRLab/dairlib).  
+**Officially supported OS:** Ubuntu 22.04.
+
+---
+
+## Table of Contents
+
+- [Setup](#setup)
+- [Build Instructions](#build-instructions)
+- [Testing & Coverage](#testing-and-coverage)
+- [Running Examples](#running-examples)
+- [Directory Structure](#directory-structure)
+- [Reference](#reference)
+
+---
+
+## Setup
+
+1. **Install Bazel or Bazelisk:**  
+    You can install Bazelisk (a user-friendly launcher for Bazel) or Bazel directly. Bazelisk is recommended as it automatically manages Bazel versions.
+
+    **To install Bazelisk:**
+    ```sh
+    sudo apt-get update
+    sudo apt-get install -y curl
+    sudo curl -L https://github.com/bazelbuild/bazelisk/releases/latest/download/bazelisk-linux-amd64 -o /usr/local/bin/bazel
+    sudo chmod +x /usr/local/bin/bazel
+    ```
+    For more details and to find a specific version, visit the [Bazelisk releases page](https://github.com/bazelbuild/bazelisk/releases). Choose a version compatible with your system and project requirements.
+
+    **Or, to install Bazel directly:**  
+    Follow the instructions at [Bazel's official installation guide](https://bazel.build/install/ubuntu).
+2. **Clone C3 (do not `cd` into the directory yet):**
+    ```sh
+    git clone --filter=blob:none [email protected]:DAIRLab/c3.git
+    ```
+
+2. **Install Drake and its dependencies:**
+    ```sh
+    git clone --depth 1 --branch v1.35.0 https://github.com/RobotLocomotion/drake.git
+    sudo drake/setup/ubuntu/install_prereqs.sh
+    ```
+
+3. **Install Gurobi 10.0:**  
+   Follow the instructions at [Drake's Gurobi setup page](https://drake.mit.edu/bazel.html) to install Gurobi 10.0.
+
+4. **(Optional) Remove Drake clone:**  
+   You may delete the Drake directory after installing dependencies.
+
+---
+
+## Build Instructions
+
+1. **Change to the C3 directory:**
+    ```sh
+    cd c3
+    ```
+
+2. **Build the repository using Bazel:**
+    ```sh
+    bazel build ...
+    ```
+
+---
+
+## Testing and Coverage
+
+- **Run all unit tests:**
+    ```sh
+    bazel test ... --test_output=all
+    ```
+
+- **Run a specific test:**
+    ```sh
+    bazel test //systems:systems_test
+    ```
+
+- **Run coverage:**
+    ```sh
+    bazel coverage --combined_report=lcov ...
+    genhtml --branch-coverage --output genhtml "$(bazel info output_path)/_coverage/_coverage_report.dat" # Generates the HTML report to be viewed inside the genhtml folder
+    ```
+
+## Running Examples
+
+This repository provides several C++ and Python examples demonstrating how to use the C3 library for different systems and workflows.
+
+---
+
+### Quick Start
+
+- **C++ Examples:**  
+  See the [C3 Standalone Example](./examples/README.md#c3-standalone-example), [C3 Controller Example](./examples/README.md#c3-controller-example), and [LCS Factory System Example](./examples/README.md#lcs-factory-system-example) sections in the examples README for build and run instructions.
+
+- **Python Examples:**  
+  See the [Python Examples](./examples/README.md#python-examples) section in the examples README for how to build and run the Python scripts using Bazel.
+
+---
+
+For more information, including how to select different problems, visualize results, and understand the system architectures, refer to the [`examples/README.md`](./examples/README.md) file.
+
+---
+
+## Directory Structure
+
+```plaintext
+c3/
+├── bindings/          # Python bindings and tests
+├── core/              # Core algorithm implementation
+├── examples/          # Example applications and simulations
+├── systems/           # Drake systems and tests
+├── multibody/         # algorithms for computation in multibody environments
+├── third_party/       # External dependencies
+└── MODULE.bazel       # Bazel module file
 ```
-5. Run an example program
-```shell
-bazel-bin/bindings/test/c3_py_test
+---
+
+## Reference
+
+For a detailed explanation of the C3 algorithm, please refer to the [main paper](https://arxiv.org/abs/2304.11259). Additional resources and in-depth examples can be found in the [dairlib repository](https://github.com/DAIRLab/dairlib).
+
+## Citation
+If you use C3 in your research, please cite:
+
+```bibtex
+@article{Aydinoglu2024,
+  title = {Consensus Complementarity Control for Multi-Contact MPC},
+  author = {Aydinoglu, Alp and Wei, Adam and Huang, Wei-Cheng and Posa, Michael},
+  year = {2024},
+  month = jul,
+  journal = {IEEE Transactions on Robotics (TRO)},
+  youtube = {L57Jz3dPwO8},
+  arxiv = {2304.11259},
+  doi = {10.1109/TRO.2024.3435423},
+  url = {https://ieeexplore.ieee.org/document/10614849}
+}
 ```
-6. You may delete the copy of Drake we cloned in step 3