Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/build.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,12 @@ jobs:
- name: "Update dependencies"
run: sudo apt-get update
- name: "Install dependencies"
run: sudo apt-get install -y build-essential cmake pkg-config qtbase5-dev libqt5opengl5-dev libgl1-mesa-dev libglu1-mesa-dev libprotobuf-dev protobuf-compiler libode-dev libboost-dev xvfb libgl1-mesa-dri
run: sudo apt-get install -y build-essential cmake pkg-config qtbase5-dev libqt5opengl5-dev libgl1-mesa-dev libglu1-mesa-dev libprotobuf-dev protobuf-compiler libode-dev libboost-dev libopenblas-dev xvfb libgl1-mesa-dri
- name: "Build"
run: make
- name: "Build regression tests"
run: |
cmake -S . -B build -DBUILD_TESTING=ON
cmake -S . -B build -DBUILD_TESTING=ON -DBUILD_ODE=ON
cmake --build build -j 2
- name: "Run regression tests"
working-directory: build
Expand Down
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,6 @@ Thumbs.db
*.iml
cmake-build-debug
cmake-build-release

# Local experiment reports, raw data and profiles.
/docs/research/
99 changes: 95 additions & 4 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -91,22 +91,30 @@ find_package(Qt5 COMPONENTS Core Widgets OpenGL Network REQUIRED)
list(APPEND libs Qt5::Core Qt5::Widgets Qt5::OpenGL Qt5::Network)

# ODE
find_package(Threads REQUIRED)
list(APPEND libs Threads::Threads)
option(BUILD_ODE "Build the bundled double-precision ODE dependency." OFF)
set(GRSIM_ODE_MIN_VERSION 0.16.6)
if(BUILD_ODE)
include(BuildODE)
add_dependencies(${app} ode_external)
else()
if(WIN32)
find_package(ODE CONFIG)
find_package(ODE ${GRSIM_ODE_MIN_VERSION} QUIET CONFIG)
if(ODE_FOUND AND NOT ODE_DOUBLE_PRECISION)
set(ODE_FOUND FALSE)
endif()
set(ODE_LIB_NAME ODE::ODE)
else()
find_package(ODE)
find_package(ODE ${GRSIM_ODE_MIN_VERSION} QUIET)
set(ODE_LIB_NAME ode::ode)
endif()

if(ODE_FOUND)
message(STATUS "Using system ODE ${ODE_VERSION}")
list(APPEND libs ${ODE_LIB_NAME})
else()
# if ODE could not be found just build it
# Older and single-precision system libraries cannot satisfy this build.
include(BuildODE)
add_dependencies(${app} ode_external)
endif()
Expand Down Expand Up @@ -201,6 +209,7 @@ set(SOURCES
src/physics/pfixedbox.cpp
src/physics/pcylinder.cpp
src/physics/pchassiscollision.cpp
src/physics/pcollisionsphere.cpp
src/physics/pbox.cpp
src/physics/pray.cpp
src/net/robocup_ssl_server.cpp
Expand All @@ -227,6 +236,7 @@ set(HEADERS
include/physics/pfixedbox.h
include/physics/pcylinder.h
include/physics/pchassiscollision.h
include/physics/pcollisionsphere.h
include/physics/pbox.h
include/physics/pray.h
include/net/robocup_ssl_server.h
Expand Down Expand Up @@ -348,6 +358,85 @@ if(BUILD_TESTING)
add_test(NAME geometry_regression COMMAND grSim_geometry_test)
set_tests_properties(geometry_regression PROPERTIES
ENVIRONMENT "QT_QPA_PLATFORM=offscreen" TIMEOUT 15)
add_test(NAME worker_ode_policy_regression COMMAND grSim_worker_test --ode-worker-policy)
set_tests_properties(worker_ode_policy_regression PROPERTIES
ENVIRONMENT "QT_QPA_PLATFORM=offscreen" TIMEOUT 30)
add_test(NAME worker_regression_ode_threads COMMAND grSim_worker_test)
set_tests_properties(worker_regression_ode_threads PROPERTIES
ENVIRONMENT "QT_QPA_PLATFORM=offscreen;GRSIM_ODE_THREADS=2" TIMEOUT 30)
if(TARGET ode_external)
set(kernel_test_dir "${CMAKE_CURRENT_BINARY_DIR}/ode-kernel-tests")
set(kernel_test_headers "")
foreach(variant reference optimized)
foreach(kernel fastlsolve_impl.h fastltsolve_impl.h fastdot_impl.h)
list(APPEND kernel_test_headers "${kernel_test_dir}/${variant}_${kernel}")
endforeach()
endforeach()
add_custom_command(OUTPUT ${kernel_test_headers}
COMMAND "${CMAKE_COMMAND}"
"-DSOURCE_DIR=${GRSIM_BUNDLED_ODE_SOURCE_DIR}"
"-DOUTPUT_DIR=${kernel_test_dir}" "-DGIT_EXECUTABLE=${GIT_EXECUTABLE}"
-P "${PROJECT_SOURCE_DIR}/cmake/ode/PrepareKernelTests.cmake"
DEPENDS ode_external "${PROJECT_SOURCE_DIR}/cmake/ode/PrepareKernelTests.cmake"
"${PROJECT_SOURCE_DIR}/cmake/ode/cpu-math.patch"
"${PROJECT_SOURCE_DIR}/cmake/ode/grsim_ode_math.h")
add_custom_target(grSim_ode_kernel_headers DEPENDS ${kernel_test_headers})
add_executable(grSim_ode_math_fallback_test tests/ode_math_regression.cpp)
add_dependencies(grSim_ode_math_fallback_test grSim_ode_kernel_headers)
set_target_properties(grSim_ode_math_fallback_test PROPERTIES AUTOMOC OFF AUTORCC OFF)
target_compile_definitions(grSim_ode_math_fallback_test PRIVATE GRSIM_ODE_USE_BLAS=0)
target_include_directories(grSim_ode_math_fallback_test PRIVATE "${kernel_test_dir}"
"${PROJECT_SOURCE_DIR}/cmake/ode")
target_link_libraries(grSim_ode_math_fallback_test Threads::Threads)
add_test(NAME ode_math_fallback_regression COMMAND grSim_ode_math_fallback_test)
set_tests_properties(ode_math_fallback_regression PROPERTIES TIMEOUT 30)
if(GRSIM_ODE_MATH_AVAILABLE)
add_executable(grSim_ode_math_test tests/ode_math_regression.cpp)
add_dependencies(grSim_ode_math_test grSim_ode_kernel_headers)
set_target_properties(grSim_ode_math_test PROPERTIES AUTOMOC OFF AUTORCC OFF)
target_compile_definitions(grSim_ode_math_test PRIVATE GRSIM_ODE_USE_BLAS=1)
target_include_directories(grSim_ode_math_test PRIVATE "${kernel_test_dir}"
"${PROJECT_SOURCE_DIR}/cmake/ode" ${GRSIM_ODE_MATH_INCLUDE_DIR})
target_link_libraries(grSim_ode_math_test ${GRSIM_ODE_MATH_LIBRARIES} Threads::Threads)
add_test(NAME ode_math_regression COMMAND grSim_ode_math_test)
set_tests_properties(ode_math_regression PROPERTIES TIMEOUT 30)
endif()
endif()
add_executable(grSim_ode_test tests/ode_regression.cpp)
target_link_libraries(grSim_ode_test grSim_core)
add_test(NAME ode_regression COMMAND grSim_ode_test)
set_tests_properties(ode_regression PROPERTIES
ENVIRONMENT "QT_QPA_PLATFORM=offscreen" TIMEOUT 180)
add_executable(grSim_collision_filtering_test tests/collision_filtering_regression.cpp)
target_link_libraries(grSim_collision_filtering_test grSim_core)
add_test(NAME collision_filtering_regression COMMAND grSim_collision_filtering_test)
set_tests_properties(collision_filtering_regression PROPERTIES TIMEOUT 30)
add_executable(grSim_physics_defaults_test tests/physics_defaults_regression.cpp)
target_link_libraries(grSim_physics_defaults_test grSim_core)
add_test(NAME physics_defaults_regression COMMAND grSim_physics_defaults_test)
set_tests_properties(physics_defaults_regression PROPERTIES
ENVIRONMENT "QT_QPA_PLATFORM=offscreen" TIMEOUT 30)
add_executable(grSim_physics_experiments tests/physics_experiments.cpp)
target_link_libraries(grSim_physics_experiments grSim_core)
add_executable(grSim_ode_performance_experiments tests/ode_performance_experiments.cpp)
target_link_libraries(grSim_ode_performance_experiments grSim_core)
if(TARGET ode_external)
target_include_directories(grSim_ode_performance_experiments PRIVATE
"${PROJECT_SOURCE_DIR}/cmake/ode" ${GRSIM_ODE_MATH_INCLUDE_DIR})
target_compile_definitions(grSim_ode_performance_experiments PRIVATE
GRSIM_ODE_USE_BLAS=$<BOOL:${GRSIM_ODE_MATH_AVAILABLE}>)
endif()
find_program(GRSIM_PYTHON3_EXECUTABLE python3)
if(GRSIM_PYTHON3_EXECUTABLE)
add_test(NAME collision_filtering_trajectories
COMMAND ${GRSIM_PYTHON3_EXECUTABLE} ${PROJECT_SOURCE_DIR}/tests/check_collision_filtering.py
$<TARGET_FILE:grSim_ode_performance_experiments>)
set_tests_properties(collision_filtering_trajectories PROPERTIES TIMEOUT 180)
add_test(NAME physics_analytic_regression
COMMAND ${GRSIM_PYTHON3_EXECUTABLE} ${PROJECT_SOURCE_DIR}/tests/check_physics_experiments.py
$<TARGET_FILE:grSim_physics_experiments>)
set_tests_properties(physics_analytic_regression PROPERTIES TIMEOUT 60)
endif()
endif()

if(APPLE AND GRSIM_MACOSX_BUNDLE)
Expand Down Expand Up @@ -396,7 +485,9 @@ set(CPACK_RESOURCE_FILE_README "${CMAKE_BINARY_DIR}/README.txt")
#set(CPACK_RESOURCE_FILE_WELCOME "${CMAKE_SOURCE_DIR}/WELCOME.txt")
set(CPACK_PACKAGE_VERSION ${VERSION})
# Debian based specific
set(CPACK_DEBIAN_PACKAGE_DEPENDS "libode1 (>=0.11), vartypes (>=0.7.0)")
set(CPACK_DEBIAN_PACKAGE_DEPENDS "vartypes (>=0.7.0)")
# Derive shared-library dependencies, including ODE only for a system build.
set(CPACK_DEBIAN_PACKAGE_SHLIBDEPS ON)
if(FLAVOR)
set(CPACK_PACKAGE_FILE_NAME "${CMAKE_PROJECT_NAME_LOWER}_${CPACK_PACKAGE_VERSION}-${FLAVOR}_${ARCH}")
else()
Expand Down
4 changes: 1 addition & 3 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,6 @@ RUN apt-get update && apt-get install -y \
libglu1-mesa-dev \
libprotobuf-dev \
protobuf-compiler \
libode-dev \
libboost-dev

WORKDIR /vartypes
Expand All @@ -34,7 +33,7 @@ COPY src /grsim/src
COPY CMakeLists.txt README.md LICENSE.md /grsim/
RUN mkdir build && \
cd build && \
cmake -DCMAKE_INSTALL_PREFIX=/usr/local .. && \
cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Release -DBUILD_ODE=ON .. && \
make && \
make install

Expand All @@ -47,7 +46,6 @@ RUN apt-get update && apt-get install -y \
tini \
qt5-default \
libqt5opengl5 \
libode8 \
libprotobuf17 \
# virtual display and VNC server
x11vnc xvfb && \
Expand Down
71 changes: 63 additions & 8 deletions INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,17 @@ GrSim depends on:
- [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/)
- [OpenGL](https://www.opengl.org)
- [Qt5 Development Libraries](https://www.qt.io)
- [Open Dynamics Engine (ODE)](http://www.ode.org)
- [Open Dynamics Engine (ODE)](https://www.ode.org/) 0.16.6 or newer, double precision
- [VarTypes Library](https://github.com/jpfeltracco/vartypes) forked from [Szi's Vartypes](https://github.com/szi/vartypes)
- [Google Protobuf](https://github.com/google/protobuf)
- [Boost development libraries](http://www.boost.org/) (needed by VarTypes)

**Note:** It's necessary to compile ODE in double precision. This is default when installing the ODE binaries in Ubuntu. However, if you are compiling ODE from source (e.g on Mac OS), please make sure to enable the double precision during the configuration step: `./configure --enable-double-precision`.


grSim uses a compatible system ODE when available. Otherwise, CMake downloads and
builds the pinned 0.16.6 release in double precision. Pass `-DBUILD_ODE=ON` to
select this bundled build explicitly. It also enables ODE's threading interface
and collision thread-local storage for independent concurrent worlds. The first
build needs Git and access to the upstream repository. Installing a distribution's
ODE package is optional when using the bundled build.

## Run from pre-build packages
### Installing from Arch Linux package manager
Expand Down Expand Up @@ -62,7 +65,7 @@ For Debian, or derivative
```
sudo apt install git build-essential cmake pkg-config qtbase5-dev \
libqt5opengl5-dev libgl1-mesa-dev libglu1-mesa-dev \
libprotobuf-dev protobuf-compiler libode-dev libboost-dev
libprotobuf-dev protobuf-compiler libode-dev libboost-dev libopenblas-dev
```

#### Mac OS X
Expand Down Expand Up @@ -126,7 +129,7 @@ $ cd build
Run CMake to generate the makefile (note: if you proceed with the installation, grSim will be installed into directory chosen, by default `/usr/local`):

```bash
$ cmake -DCMAKE_INSTALL_PREFIX=/usr/local ..
$ cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Release -DBUILD_ODE=ON ..
```

Then compile the program:
Expand Down Expand Up @@ -163,7 +166,58 @@ grSim will be — by default — installed on the `/usr/local` directory.

If you face any problem regarding of updating the grsim version, you can try removing the `grsim.xml`.
If grSim crashes almost instantly with some ODE error the issue might by your ODE version.
Try adding -DBUILD_ODE=TRUE to build ODE from source instead of using the system dependency.
Try adding `-DBUILD_ODE=ON` to build the pinned ODE dependency from source.

## Ball physics defaults

Ground rolling/spin resistance applies through ball-ground contacts. Under
Physics → Ball, **Ball rolling deceleration (m/s^2)** defaults to 0.35 m/s².
Spin resistance and held-ball traction retain the Ball-ground friction control;
the published rolling model follows the rolling-deceleration setting.
Slip and linear/angular damping default to zero. A one-time migration replaces
the old unused defaults (slip 1 and damping 0.004); other custom values are kept.
Nonzero body damping affects flight as well as ground motion.

## ODE CPU workers

Physics and networking run on a simulation worker independently of the display.
For games with at least six robots per team and at least three available logical
CPUs, the app automatically uses up to three ODE helpers, leaving one logical CPU
available for other work. Smaller games and lower-core systems stay serial.

Helpers process independent contact islands. Collision detection stays on the
simulation worker; contacts that connect robots stay in the same island.
Preparation and solving within each island remain serial, using the direct solver
and the same five substeps, contact geometry and materials.

GRSIM_ODE_THREADS explicitly overrides automatic selection, including after world
resets. It accepts 0 to 16 helpers; zero runs stepping on the simulation worker alone.

```bash
GRSIM_ODE_THREADS=0 ./bin/grSim # explicit serial mode on Linux
GRSIM_ODE_THREADS=2 ./bin/grSim.app/Contents/MacOS/grSim # explicit macOS override
```

Helper scheduling can change subsequent contact ordering, so crowded trajectories
can diverge numerically. Use GRSIM_ODE_THREADS=0 for reproducible comparisons.
The offline performance harness selects workers explicitly with --helpers.

## CPU math kernels in bundled ODE

The bundled ODE build uses double-precision Accelerate on macOS and OpenBLAS
when available on other platforms for triangular solves and dot products with
at least 64 entries. On x86-64 CPUs with AVX2, contiguous triangular solves
read ODE's matrix layout directly with vectorized kernels instead of packing
through BLAS. CPU support is checked at runtime; other CPUs and strided solves
retain the platform BLAS path. Small kernels retain ODE's implementation. These synchronous
CPU calls keep the direct solver, collision shapes, materials and five substeps.
OpenBLAS runs with one active math thread per calling ODE worker.

On Ubuntu, install libopenblas-dev before configuring. CMake prints the selected
backend; the performance harness reports the BLAS provider as math_backend and
large contiguous triangular dispatch as triangular_backend. Set
GRSIM_ODE_OPTIMIZED_MATH=OFF when configuring to compare the scalar fallback.
A compatible system ODE is used without this bundled patch.

## Notes on the performance

Expand Down Expand Up @@ -191,7 +245,8 @@ To build locally with Xcode Command Line Tools and Homebrew:
bash tests/package_macos.sh build

The packaged app uses ad-hoc signing; Developer ID signing and notarization
are not configured. The runtime check exercises normal/Low Spec OpenGL images,
are not configured. Browser downloads may require
[Open Anyway](https://support.apple.com/en-us/102445). The runtime check exercises normal/Low Spec OpenGL images,
robot configuration and textures, advancing vision packets, robot commands and
feedback, motion and clean worker shutdown. It does not establish visual fidelity
or performance on every Apple Silicon model. Intel/universal builds are not
Expand Down
31 changes: 30 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ grSim compiles on Linux (tested on Ubuntu and Arch Linux variants only) and Mac
- [pkg-config](https://freedesktop.org/wiki/Software/pkg-config/)
- [OpenGL](https://www.opengl.org)
- [Qt5 Development Libraries](https://www.qt.io)
- [Open Dynamics Engine (ODE)](http://www.ode.org)
- [Open Dynamics Engine (ODE)](https://www.ode.org/) 0.16.6+, double precision, with a pinned source fallback
- [VarTypes Library](https://github.com/jpfeltracco/vartypes) forked from [Szi's Vartypes](https://github.com/szi/vartypes)
- [Google Protobuf](https://github.com/google/protobuf)
- [Boost development libraries](http://www.boost.org/) (needed by VarTypes)
Expand Down Expand Up @@ -78,13 +78,42 @@ outgoing vision packets, plus wall placement after live settings edits.
Collision tests check side and rear ball contact, dribbler access, roller
retention while stationary and moving, and flat/chip kicks for separate team
sizes and rotated robots, including ball acquisition with recessed dribblers.
Robot-pair regressions also cover side/rear pushing, rotated and different-sized
robots, with serial and parallel ODE stepping. Robot contact spheres match the
outer shell radius and attach directly to the chassis, avoiding an extra fixed
body while preserving the previous combined mass and inertia. The kinematic
ball/hull fixtures isolate wheel-ground and rolling constraints; dynamic physics
and robot-pair tests retain the production defaults.
The ball-contact hull keeps the body outline and cuts its front back when needed
to reach the configured dribbler. Render quality does not change this shape.
Tests use temporary configuration values without reading or writing personal
simulator settings. In the configuration tree, **Desired FPS** caps rendering and
**ODE time step** sets the fixed physics step; their names remain stable for saved
settings compatibility.

Kernel regressions compare native CPU math and scalar fallback against the pinned
ODE implementation, including equation residuals, strides and concurrent callers.
The ODE regressions cover ball resistance, cylinder inertia, settings migration,
collision-filtered contacts/trajectories, helper stepping and concurrent worlds.
The app selects CPU helpers automatically for large games on multicore machines;
see the [worker policy and overrides](INSTALL.md#ode-cpu-workers).
Ball physics defaults and migration are described in the
[installation guide](INSTALL.md#ball-physics-defaults).

For a repeatable physics-only benchmark after building the tests (6 v 6 by default):

python3 tests/benchmark_ode.py bin/grSim_ode_test --repeats 3 --steps 300 --output /tmp/grsim-ode-benchmark.json

For sustained opposing-team contact on a Division B field:

QT_QPA_PLATFORM=offscreen ./bin/grSim_ode_performance_experiments --scenario pushing-6 --helpers 3 --islands 3 --steps 300

The performance harness also provides spaced-6 and crowded-6; each uses twelve
robots total. Add `--audit 1` to report maximum planar robot-shell overlap and
contact/constraint diagnostics. The six-a-side regression rejects overlap above
2 mm. These benchmarks exclude rendering, networking and real-time
throttling. Compare builds using the same geometry, physics settings and workload.

Star History
------
[![Star History Chart](https://api.star-history.com/svg?repos=robocup-ssl/grsim&type=Date)](https://star-history.com/#robocup-ssl/grsim&Date)
Expand Down
Loading
Loading