Skip to content

Commit 8656538

Browse files
zferguszfergus
authored
Update docs (#173)
1 parent 4c68063 commit 8656538

File tree

12 files changed

+377
-193
lines changed

12 files changed

+377
-193
lines changed

‎README.md‎

Lines changed: 8 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -26,98 +26,28 @@ IPC Toolkit is a set of reusable functions to integrate Incremental Potential Co
2626

2727
This is not a full simulation library. As such it does not include any physics or solvers. For a full simulation implementation, we recommend [PolyFEM](https://polyfem.github.io/) (a finite element library) or [Rigid IPC](https://github.com/ipc-sim/rigid-ipc) (rigid-body dynamics) both of which utilize the IPC Toolkit.
2828

29-
<!--- BEGIN C++ README 1 --->
30-
3129
## Build
3230

33-
The easiest way to add the toolkit to an existing CMake project is to download it through CMake.
34-
CMake provides functionality for doing this called [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html) (requires CMake ≥ 3.14).
35-
We use a very similar process to download all external dependencies (using [CPM](https://github.com/cpm-cmake/CPM.cmake)).
36-
37-
For example,
38-
39-
```cmake
40-
include(FetchContent)
41-
FetchContent_Declare(
42-
ipc_toolkit
43-
GIT_REPOSITORY https://github.com/ipc-sim/ipc-toolkit.git
44-
GIT_TAG ${IPC_TOOLKIT_GIT_TAG}
45-
)
46-
FetchContent_MakeAvailable(ipc_toolkit)
47-
```
48-
49-
where `IPC_TOOLKIT_GIT_TAG` is set to the version of the toolkit you want to use. This will download and add the toolkit to CMake. The toolkit can then be linked against using
50-
51-
```cmake
52-
# Link against the IPC Toolkit
53-
target_link_libraries(${PROJECT_NAME} PUBLIC ipc::toolkit)
54-
```
55-
56-
where `PROJECT_NAME` is the name of your library/binary.
57-
58-
<!--- BEGIN C++ README 2 --->
31+
Instruction for building and including the IPC Toolkit in your CMake project can be found on the website [here](https://ipctk.xyz/bulding.html).
5932

6033
### Dependencies
6134

62-
**All required dependencies are downloaded through CMake** depending on the build options.
63-
64-
The following libraries are used in this project:
35+
The IPC Toolkit depends on a handful of third-party libraries, which are used to provide various functionality.
6536

66-
* [Eigen](https://eigen.tuxfamily.org/): linear algebra
67-
* [libigl](https://github.com/libigl/libigl): basic geometry functions and predicates
68-
* [oneTBB](https://github.com/oneapi-src/oneTBB): parallelism
69-
* [Tight-Inclusion](https://github.com/Continuous-Collision-Detection/Tight-Inclusion): provably conservative CCD of [Wang and Ferguson et al. 2021]
70-
* [SimpleBVH](https://github.com/ipc-sim/SimpleBVH): a simple bounding volume hierarchy data structure
71-
* [Scalable-CCD](https://github.com/Continuous-Collision-Detection/Scalable-CCD): scalable (GPU) CCD of [Belgrod et al. 2023]
72-
* [spdlog](https://github.com/gabime/spdlog): logging information
37+
**All required dependencies are downloaded through CMake** depending on the build options, and are built automatically when you build the IPC Toolkit. You do not need to install them separately.
7338

74-
#### Optional
39+
A full list of dependencies can be found on the [dependencies page](https://ipctk.xyz/dependencies.html).
7540

76-
The following dependencies are optionally used based on CMake options:
41+
## Python Bindings
7742

78-
* [robin-map](https://github.com/Tessil/robin-map): faster hash set/map than `std::unordered_set`/`std::unordered_map`
79-
* Enable by using the CMake option `IPC_TOOLKIT_WITH_ROBIN_MAP`
80-
* Enabled by default
81-
* [Abseil](https://abseil.io/): hashing utilities
82-
* Enable by using the CMake option `IPC_TOOLKIT_WITH_ABSEIL`
83-
* Enabled by default
84-
* [filib](https://github.com/zfergus/filib): interval arithmetic for nonlinear trajectories/CCD
85-
* Enable by using the CMake option `IPC_TOOLKIT_WITH_FILIB`
86-
* Enabled by default
87-
* [rational-cpp](https://github.io/zfergus/rational-cpp): rational arithmetic used for exact intersection checks
88-
* Enable by using the CMake option `IPC_TOOLKIT_WITH_RATIONAL_INTERSECTION`
89-
* Requires [GMP](https://gmplib.org/) to be installed at a system level
90-
* [Etienne Vouga's Collision Detection Library](https://github.com/evouga/collisiondetection): inexact CCD
91-
* Included for comparison with the original IPC library
92-
* Enable by using the CMake option `IPC_TOOLKIT_WITH_INEXACT_CCD`
43+
We provide Python bindings for functions in the toolkit using [pybind11](https://github.com/pybind/pybind11).
9344

94-
<!--- FILIB DEPENDENCY NOTE --->
45+
For more information see the [Python documentation](https://ipctk.xyz/python.html).
9546

9647
## Usage
9748

9849
See the [tutorial](https://ipctk.xyz/tutorial/getting_started.html) for a quick introduction to the toolkit, or the [documentation](https://ipctk.xyz/cpp.html) for a full reference.
9950

100-
## Unit Tests
101-
102-
We provide unit tests to ensure the correctness of our algorithmic pieces.
103-
To enable the unit tests use the CMake option `IPC_TOOLKIT_BUILD_TESTS`.
104-
105-
### Dependencies
106-
107-
The following are downloaded when unit tests are enabled:
108-
109-
* [Catch2](https://github.com/catchorg/Catch2.git): testing framework
110-
* [finite-diff](https://github.com/zfergus/finite-diff): finite-difference comparisons
111-
* [Nlohman's JSON library](https://github.com/nlohmann/json): loading test data from JSON files
112-
113-
<!--- END C++ README --->
114-
115-
## Python Bindings
116-
117-
We provide Python bindings for functions in the toolkit using [pybind11](https://github.com/pybind/pybind11).
118-
119-
For more information see the [Python documentation](https://ipctk.xyz/python.html).
120-
12151
## Contributing
12252

12353
This project is open to contributors! Contributions can come in the form of feature requests, bug fixes, documentation, tutorials, and the like. We highly recommend filing an Issue first before submitting a Pull Request.
@@ -131,7 +61,7 @@ Simply fork this repository and make a Pull Request! We would appreciate:
13161

13262
## Citation
13363

134-
If you use the IPC Toolkit in your project, please consider citing our work:
64+
IPC Toolkit is created and maintained by academics: citations let us know our work is having impact! Please cite the IPC Toolkit or otherwise give a shout-out if and when it contributes to published works.
13565

13666
```bibtex
13767
@software{ipc_toolkit,

‎docs/source/_static/css/custom.css‎

Lines changed: 44 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,36 @@
1+
:root [data-md-color-scheme="slate"] {
2+
--md-default-bg-color: #2e303e;
3+
}
4+
5+
html {
6+
/* a bit less goofily large than the material default */
7+
/* font-size: 125%; */
8+
}
9+
10+
/* justify and slightly decrease spacing */
11+
p,
12+
ul,
13+
li {
14+
text-align: justify;
15+
line-height: 1.25;
16+
}
17+
18+
td p {
19+
text-align: left;
20+
}
21+
22+
/* Emphasize sections of nav on left hand side */
23+
24+
nav.md-nav {
25+
padding-left: 5px;
26+
}
27+
28+
/* Decrease spacing on the left side nav bar */
29+
.md-nav__link {
30+
margin-top: 0.25rem;
31+
text-align: left;
32+
}
33+
134
.md-grid {
235
max-width: max(1250px, 75vw) !important;
336
}
@@ -53,35 +86,14 @@ table.autosummary {
5386
font-size: 0.75rem !important;
5487
}
5588

56-
/* .breatheparameterlist li tt + p {
57-
display: inline;
58-
}
59-
60-
dd.field-odd {
61-
padding: 0 !important;;
62-
margin: 0 !important;;
63-
}
64-
65-
dl.api-field {
66-
width: 100%;
67-
overflow: hidden;
68-
}
69-
70-
dl.api-field > dt {
71-
float: left;
72-
width: 60%;
73-
padding: 0;
74-
margin: 10px;
75-
}
76-
77-
dl.api-field > dd {
78-
float: left;
79-
width: calc(40%-10px);
80-
padding: 0 !important;
81-
margin: 0 !important;
82-
}
83-
84-
dl.api-field > dd > p {
85-
padding: 0 !important;
86-
margin: 0 !important;
87-
} */
89+
#__nav_1_label,
90+
#__nav_2_label,
91+
#__nav_3_label,
92+
#__nav_4_label,
93+
#__nav_5_label,
94+
#__nav_6_label,
95+
#__nav_7_label,
96+
.md-nav--secondary .md-nav__title,
97+
.md-nav--primary .md-nav__title {
98+
margin-bottom: 10px;
99+
}

‎docs/source/building.rst‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
Building Library
2+
================
3+
4+
.. role:: cpp(code)
5+
:language: c++
6+
.. role:: cmake(code)
7+
:language: cmake
8+
9+
IPC Toolkit uses CMake to configure its build system. It is designed to be used as a submodule in your project, and as such does not have a proper install target. Instead, you can include it in your project using CMake's ``FetchContent`` module.
10+
11+
Adding IPC Toolkit to your CMake
12+
--------------------------------
13+
14+
The easiest way to add the toolkit to an existing CMake project is to download it through CMake.
15+
CMake provides functionality for doing this called `FetchContent <https://cmake.org/cmake/help/latest/module/FetchContent.html>`_ (requires CMake ≥ 3.14).
16+
We use a very similar process to download all external dependencies (using `CPM.cmake <https://github.com/cpm-cmake/CPM.cmake>`_).
17+
18+
For example,
19+
20+
.. code-block:: cmake
21+
22+
include(FetchContent)
23+
FetchContent_Declare(
24+
ipc_toolkit
25+
GIT_REPOSITORY https://github.com/ipc-sim/ipc-toolkit.git
26+
GIT_TAG ${IPC_TOOLKIT_GIT_TAG}
27+
)
28+
FetchContent_MakeAvailable(ipc_toolkit)
29+
30+
where ``IPC_TOOLKIT_GIT_TAG`` is set to the version of the toolkit you want to use. This will download and add the toolkit to CMake. The toolkit can then be linked against using
31+
32+
.. code-block:: cmake
33+
34+
# Link against the IPC Toolkit
35+
target_link_libraries(${PROJECT_NAME} PUBLIC ipc::toolkit)
36+
37+
where ``PROJECT_NAME`` is the name of your library/binary.
38+
39+
.. tip::
40+
If your ``IPC_TOOLKIT_GIT_TAG`` is a tag (e.g. ``v1.3.1``), then you can use the ``FetchContent_Declare`` argument ``GIT_SHALLOW TRUE`` to download only a single commit. Otherwise, you should use the default ``GIT_SHALLOW FALSE``.
41+
42+
Building the Library
43+
--------------------
44+
45+
You can build the IPC Toolkit using CMake as you would any other CMake project. The following is a minimal example of how to build the toolkit:
46+
47+
.. code-block:: bash
48+
49+
mkdir build
50+
cd build
51+
cmake -DIPC_TOOLKIT_BUILD_TESTS=ON -DIPC_TOOLKIT_BUILD_PYTHON=ON ..
52+
make -j$(nproc)
53+
54+
This will build the IPC Toolkit and all of its dependencies. The ``IPC_TOOLKIT_BUILD_TESTS`` option enables building the unit tests, and the ``IPC_TOOLKIT_BUILD_PYTHON`` option enables building the Python bindings.
55+
56+
.. warning::
57+
Installing the IPC Toolkit using the ``make install`` has not been tested and is not recommended. The IPC Toolkit is designed to be used as a submodule in your project, and as such does not have a proper install target.
58+
59+
Dependencies
60+
------------
61+
62+
**All required dependencies are downloaded through CMake** depending on the build options, and are built automatically when you build the IPC Toolkit. You do not need to install them separately.
63+
64+
A full list of dependencies can be found on the `dependencies page <https://ipctk.xyz/dependencies.html>`_.

‎docs/source/conf.py‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -175,8 +175,6 @@
175175
"repo_name": "ipc-sim/ipc-toolkit",
176176
"icon": {"repo": "fontawesome/brands/github"},
177177

178-
"edit_uri": "blob/main/docs/source",
179-
180178
"features": [
181179
"navigation.expand",
182180
"navigation.tabs",
@@ -193,8 +191,6 @@
193191
"code": "Roboto Mono" # used for literal code blocks
194192
},
195193

196-
"toc_title": "Contents",
197-
198194
"version_dropdown": True,
199195
"version_json": "https://ipctk.xyz/versions.json",
200196
}

‎docs/source/cpp.rst‎

Lines changed: 0 additions & 55 deletions
This file was deleted.

0 commit comments

Comments
 (0)