Skip to content

Commit 13ba28d

Browse files
Meow404Meow404
authored
feat(CI): improve readme and code coverage (#20)
* feat: add code coverage * fix: improve coverage for multibody * feat: add clang formatting check * test(c3) : add more tests for core module * feat: use github actions for code coverage * feat: improve coverage and add tests for systems * style: correct formatting * feat: update readmes * feat: build python wheel * doc: add readme for bindings * doc: update bibtex * ci: add condition for CI to run on PRs or main
1 parent c58a6aa commit 13ba28d

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

58 files changed

+1238
-261
lines changed

‎.bazelrc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,4 +51,4 @@ build --action_env=LD_LIBRARY_PATH=
5151
# use python3 by default
5252
build --python_path=python3
5353

54-
build --define=WITH_GUROBI=ON
54+
build --define=WITH_GUROBI=ON

‎.cirrus.yml‎

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,14 @@
11
registry_config: ENCRYPTED[!88cf0d757d2f8b93dca9e57dc166b65ddedef6378e7ac12a91a022ab3fb28dd47b10d452dc5c53a68e144e6bdbae999b!]
22
jammy_task:
3+
only_if: "$CIRRUS_PR != '' || $CIRRUS_BRANCH == 'main'" # This condition ensures the task runs only for PRs or on the main branch.
34
timeout_in: 120m
45
container:
56
image: ghcr.io/dairlab/docker-dair/jammy-dair-base:v1.42
67
cpu: 8
78
memory: 24
9+
format_script:
10+
- apt update && apt install -y clang-format
11+
- ./tools/scripts/check_format.sh
812
test_script:
913
- export CC=clang-15
1014
- export CXX=clang++-15
@@ -17,19 +21,24 @@ jammy_task:
1721
- bazel test
1822
--local_resources=ram=24000
1923
--local_resources=cpu=8
24+
--jobs=8
25+
--test_output=all
2026
--remote_cache=http://$CIRRUS_HTTP_CACHE_HOST
2127
//...
22-
always:
23-
jammy_test_artifacts:
24-
path: "bazel-testlogs/**/test.xml"
25-
format: junit
28+
jammy_test_artifacts:
29+
path: "bazel-testlogs/**/test.xml"
30+
format: junit
2631

2732
noble_task:
33+
only_if: "$CIRRUS_PR != '' || $CIRRUS_BRANCH == 'main'" # This condition ensures the task runs only for PRs or on the main branch.
2834
timeout_in: 120m
2935
container:
3036
image: ghcr.io/dairlab/docker-dair/noble-dair-base:v1.42
3137
cpu: 8
3238
memory: 24
39+
format_script:
40+
- apt update && apt install -y clang-format
41+
- ./tools/scripts/check_format.sh
3342
test_script:
3443
- export CC=clang-15
3544
- export CXX=clang++-15
@@ -42,9 +51,10 @@ noble_task:
4251
- bazel test
4352
--local_resources=ram=24000
4453
--local_resources=cpu=8
54+
--jobs=8
55+
--test_output=all
4556
--remote_cache=http://$CIRRUS_HTTP_CACHE_HOST
4657
//...
47-
always:
48-
noble_test_artifacts:
49-
path: "bazel-testlogs/**/test.xml"
50-
format: junit
58+
noble_test_artifacts:
59+
path: "bazel-testlogs/**/test.xml"
60+
format: junit

‎.github/workflows/coverage.yml‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
name: C3 Coverage
2+
on:
3+
push:
4+
branches:
5+
- main
6+
pull_request:
7+
jobs:
8+
# Only run coverage on Noble
9+
coverage:
10+
runs-on: ubuntu-latest
11+
concurrency:
12+
group: ci-${{ github.ref }}
13+
cancel-in-progress: true
14+
container:
15+
image: ghcr.io/dairlab/docker-dair/noble-dair-base:v1.42
16+
credentials:
17+
username: ${{ github.actor }}
18+
password: ${{ secrets.GITHUB_TOKEN }}
19+
options: --cpus 4
20+
steps:
21+
- name: Check out repository code
22+
uses: actions/checkout@v4
23+
- name: Install required dependencies
24+
run: apt update && apt install -y lcov
25+
- name: Restore coverage cache
26+
id: c3-cov-cache-restore
27+
uses: actions/cache/restore@v4
28+
with:
29+
path: ~/.cache/bazel
30+
key: c3-bazel-cov-cache-${{ hashFiles('**/BUILD.bazel') }}
31+
restore-keys: |
32+
c3-bazel-cov-cache-
33+
- name: Generate Coverage
34+
run: bazel coverage
35+
--combined_report=lcov
36+
--local_resources=ram=24000
37+
--local_resources=cpu=4
38+
--jobs=4
39+
//...
40+
- name: Report code coverage
41+
uses: zgosalvez/[email protected]
42+
with:
43+
coverage-files: bazel-out/_coverage/_coverage_report.dat
44+
minimum-coverage: 90
45+
artifact-name: noble-code-coverage-report
46+
github-token: ${{ secrets.GITHUB_TOKEN }}
47+
update-comment: true
48+
- name: Save coverage cache
49+
id: c3-cov-cache-save
50+
if: always() && !cancelled() && steps.c3-cov-cache-restore.outputs.cache-hit != 'true'
51+
uses: actions/cache/save@v4
52+
with:
53+
key: ${{ steps.c3-cov-cache-restore.outputs.cache-primary-key }}
54+
path: ~/.cache/bazel
55+
- run: echo "🍏 This job's status is ${{ job.status }}."
56+
# Deploy job
57+
deploy:
58+
# Add a dependency to the build job
59+
needs: coverage
60+
if: ${{ github.event_name == 'push' }}
61+
62+
# Grant GITHUB_TOKEN the permissions required to make a Pages deployment
63+
permissions:
64+
pages: write # to deploy to Pages
65+
id-token: write # to verify the deployment originates from an appropriate source
66+
67+
# Deploy to the github-pages environment
68+
environment:
69+
name: github-pages
70+
url: ${{ steps.deployment.outputs.page_url }}
71+
72+
# Specify runner + deployment step
73+
runs-on: ubuntu-latest
74+
steps:
75+
- name: Deploy to GitHub Pages
76+
id: deployment
77+
uses: actions/deploy-pages@v4 # or specific "vX.X.X" version tag for this action
78+
with:
79+
artifact_name: noble-code-coverage-report

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,5 @@
66
MODULE.bazel.lock
77
**/__pycache__/**
88
.vscode
9-
*.ps
9+
*.ps
10+
genhtml/*

‎BUILD.bazel‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,28 @@
1-
# This is an empty BUILD file, to ensure that the project's root directory is a
2-
# bazel package.
1+
LIBC3_COMPONENTS = [
2+
"//core:core",
3+
"//multibody:multibody",
4+
"//systems:systems",
5+
]
6+
7+
package(default_visibility = ["//visibility:public"])
8+
9+
# Filegroup collecting all headers
10+
filegroup(
11+
name = "c3_headers",
12+
srcs = [
13+
"//core:headers",
14+
"//multibody:headers",
15+
"//systems:headers",
16+
],
17+
)
18+
19+
# Combined target that provides both the shared library and headers
20+
cc_library(
21+
name = "libc3",
22+
hdrs = [":c3_headers"], # Changed from srcs to hdrs for headers
23+
deps = LIBC3_COMPONENTS + [
24+
"@drake//:drake_shared_library",
25+
],
26+
include_prefix = "c3",
27+
visibility = ["//visibility:public"],
28+
)

‎README.md‎

Lines changed: 152 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,157 @@
1-
# C3
2-
Consensus Complementarity Control
1+
# C3: Consensus Complementarity Control
32

4-
This is a standalone repository for the C3 algorithm. For more in-depth examples, see dairlib.
5-
Currently we only officially support Ubuntu 22.04.
3+
[**Main Paper: Consensus Complementarity Control**](https://arxiv.org/abs/2304.11259)
64

7-
## Build from source
8-
1. Clone C3 (Don't change to the c3 directory yet)
9-
```shell
10-
git clone --filter=blob:none [email protected]:DAIRLab/c3.git
11-
```
5+
<p align="center">
6+
<a href="https://cirrus-ci.com/github/DAIRLab/c3">
7+
<strong style="vertical-align: middle;">Build (Noble)</strong>
8+
<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;"/>
9+
</a>
10+
&nbsp;&nbsp;
11+
<a href="https://cirrus-ci.com/github/DAIRLab/c3">
12+
<strong style="vertical-align: middle;">Build (Jammy)</strong>
13+
<img src="https://api.cirrus-ci.com/github/DAIRLab/c3.svg?task=jammy&script=test&branch=main" alt="Jammy Test" style="vertical-align: middle;"/>
14+
</a>
15+
&nbsp;&nbsp;
16+
<a href="https://github.com/DAIRLab/c3/actions/workflows/coverage.yml"><strong style="vertical-align: middle;">Coverage</strong>
17+
<img src="https://github.com/DAIRLab/c3/actions/workflows/coverage.yml/badge.svg?branch=main&event=push" alt="C3 Coverage" style="vertical-align: middle;"/>
18+
</a>
19+
</p>
1220

13-
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.
14-
```shell
15-
git clone --depth 1 --branch v1.35.0 https://github.com/RobotLocomotion/drake.git
16-
sudo drake/setup/ubuntu/install_prereqs.sh
17-
```
18-
3. Follow the instructions at https://drake.mit.edu/bazel.html to install Gurobi 10.0
19-
4. Change to the C3 Directory, and build the repo:
20-
```shell
21-
cd c3
22-
bazel build ...
21+
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).
22+
**Officially supported OS:** Ubuntu 22.04.
23+
24+
---
25+
26+
## Table of Contents
27+
28+
- [Setup](#setup)
29+
- [Build Instructions](#build-instructions)
30+
- [Testing & Coverage](#testing-and-coverage)
31+
- [Running Examples](#running-examples)
32+
- [Directory Structure](#directory-structure)
33+
- [Reference](#reference)
34+
35+
---
36+
37+
## Setup
38+
39+
1. **Install Bazel or Bazelisk:**
40+
You can install Bazelisk (a user-friendly launcher for Bazel) or Bazel directly. Bazelisk is recommended as it automatically manages Bazel versions.
41+
42+
**To install Bazelisk:**
43+
```sh
44+
sudo apt-get update
45+
sudo apt-get install -y curl
46+
sudo curl -L https://github.com/bazelbuild/bazelisk/releases/latest/download/bazelisk-linux-amd64 -o /usr/local/bin/bazel
47+
sudo chmod +x /usr/local/bin/bazel
48+
```
49+
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.
50+
51+
**Or, to install Bazel directly:**
52+
Follow the instructions at [Bazel's official installation guide](https://bazel.build/install/ubuntu).
53+
2. **Clone C3 (do not `cd` into the directory yet):**
54+
```sh
55+
git clone --filter=blob:none [email protected]:DAIRLab/c3.git
56+
```
57+
58+
2. **Install Drake and its dependencies:**
59+
```sh
60+
git clone --depth 1 --branch v1.35.0 https://github.com/RobotLocomotion/drake.git
61+
sudo drake/setup/ubuntu/install_prereqs.sh
62+
```
63+
64+
3. **Install Gurobi 10.0:**
65+
Follow the instructions at [Drake's Gurobi setup page](https://drake.mit.edu/bazel.html) to install Gurobi 10.0.
66+
67+
4. **(Optional) Remove Drake clone:**
68+
You may delete the Drake directory after installing dependencies.
69+
70+
---
71+
72+
## Build Instructions
73+
74+
1. **Change to the C3 directory:**
75+
```sh
76+
cd c3
77+
```
78+
79+
2. **Build the repository using Bazel:**
80+
```sh
81+
bazel build ...
82+
```
83+
84+
---
85+
86+
## Testing and Coverage
87+
88+
- **Run all unit tests:**
89+
```sh
90+
bazel test ... --test_output=all
91+
```
92+
93+
- **Run a specific test:**
94+
```sh
95+
bazel test //systems:systems_test
96+
```
97+
98+
- **Run coverage:**
99+
```sh
100+
bazel coverage --combined_report=lcov ...
101+
genhtml --branch-coverage --output genhtml "$(bazel info output_path)/_coverage/_coverage_report.dat" # Generates the HTML report to be viewed inside the genhtml folder
102+
```
103+
104+
## Running Examples
105+
106+
This repository provides several C++ and Python examples demonstrating how to use the C3 library for different systems and workflows.
107+
108+
---
109+
110+
### Quick Start
111+
112+
- **C++ Examples:**
113+
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.
114+
115+
- **Python Examples:**
116+
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.
117+
118+
---
119+
120+
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.
121+
122+
---
123+
124+
## Directory Structure
125+
126+
```plaintext
127+
c3/
128+
├── bindings/ # Python bindings and tests
129+
├── core/ # Core algorithm implementation
130+
├── examples/ # Example applications and simulations
131+
├── systems/ # Drake systems and tests
132+
├── multibody/ # algorithms for computation in multibody environments
133+
├── third_party/ # External dependencies
134+
└── MODULE.bazel # Bazel module file
23135
```
24-
5. Run an example program
25-
```shell
26-
bazel-bin/bindings/test/c3_py_test
136+
---
137+
138+
## Reference
139+
140+
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).
141+
142+
## Citation
143+
If you use C3 in your research, please cite:
144+
145+
```bibtex
146+
@article{Aydinoglu2024,
147+
title = {Consensus Complementarity Control for Multi-Contact MPC},
148+
author = {Aydinoglu, Alp and Wei, Adam and Huang, Wei-Cheng and Posa, Michael},
149+
year = {2024},
150+
month = jul,
151+
journal = {IEEE Transactions on Robotics (TRO)},
152+
youtube = {L57Jz3dPwO8},
153+
arxiv = {2304.11259},
154+
doi = {10.1109/TRO.2024.3435423},
155+
url = {https://ieeexplore.ieee.org/document/10614849}
156+
}
27157
```
28-
6. You may delete the copy of Drake we cloned in step 3

0 commit comments

Comments
 (0)