haptic-device

Code for the FRI haptic device project

NOTE: When launching the program, you may need to calibrate the device by pushing it in and out until it is recognized.

Desktop Launcher

launcher/ contains a cross-platform (Mac/Windows) PySide6 GUI for configuring parameters and launching haptic-device, plus a "Live controls" panel (freeze, haptic mode, potential, anchors) that talks to a loopback IPC server built into LJ.cpp while the simulation is running. See launcher/README.md for setup and usage.

OPTIONS

Specify the # of atoms at launch like so:

./haptic-device 38

If you don't pass in anything, the default is five.

You can also read in an existing configuration:

./haptic-device example.con

Make sure the .con file is in ../resources/data.

Choose the potential energy surface by adding a second argument:

./haptic-device 25 morse

The default is Lennard-Jones(lj). Other options are morse and ase.

When using ase, you can optionally provide a third argument to choose a full ASE calculator spec:

./haptic-device structure.xyz ase
./haptic-device structure.xyz ase lj
./haptic-device structure.xyz ase morse
./haptic-device structure.xyz ase ase.calculators.emt:EMT
./haptic-device structure.xyz ase ase.calculators.lj:LennardJones:{'sigma': 2.5, 'epsilon': 0.8}

Supported ASE shortcuts are lj, morse, emt, and uma (Meta's universal ML potential; uma:omol, uma:omat, uma:oc20 select the prediction head). For any other ASE calculator, use module:Class[:kwargs].

A fifth argument controls periodic boundary conditions: on forces PBC on, off forces it off, and keep (or omitting the argument) leaves whatever the loaded structure file specified untouched:

./haptic-device 25 lj "" off

(the empty 4th argument is a placeholder for the ASE calculator spec, which is only meaningful when the potential is ase)

The simulation time step (seconds) can be set at launch via the HAPTIC_DEVICE_TIME_STEP environment variable (default 0.001, valid range 0.0001-0.005), and changed live while running through the desktop launcher or the IPC command server (see below).

Build Instructions

Windows

Native Windows builds go through CMake rather than make (which needs WSL/Linux or macOS — see below). WINDOWS.md documents an old, abandoned Visual Studio project-file approach; ignore it.

1. Install a Python 3 build from python.org (it bundles the dev headers/import library CMake's find_package(Python3) needs — the Microsoft Store build does not).
2. Download or clone a CHAI3D tree and build it first

   cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
   cmake --build build --config Release
   

3. Clone this repo into the CHAI3D directory so it sits next to src, examples, and build
4. Create the directory data in bin/resources and move the file global_minima.txt there
5. Build haptic-device itself

   cd haptic-device
   cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
   cmake --build build --config Release
   

6. The binary will be written to bin/win-x64/haptic-device.exe (or bin/win-Win32 for a 32-bit build)

Force Dimension/Novint Falcon (DHD) support isn't compiled in on Windows — upstream CHAI3D only links it on macOS/Linux/QNX — so a native Windows build always runs in keyboard/mouse-only mode. If you need the physical haptic device on a Windows box, build and run through WSL instead (uses the Linux instructions below); see launcher/README.md's "Running under WSL" section for USB passthrough details.

Linux

1. Download or clone a CHAI3D tree and build it first

   cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
   cmake --build build -j"$(nproc)"
   

2. Run the following commands

   sudo add-apt-repository universe
   sudo apt update
   

3. Install the required packages using the command

   sudo apt-get install libusb-1.0-0-dev libasound2-dev freeglut3-dev xorg-dev python3-dev
   

4. Clone this repo into the CHAI3D directory so it sits next to src, examples, and build
5. Create the directory data in bin/resources and move the file global_minima.txt there
6. Run make -C haptic-device in the Chai3D folder
7. Your directory structure should look like so:

chai3d/
├── bin
│   ├── lin-x86_64
│   ├── resources
│       └── data
│           └── global_minima.txt
│
├── build
└── haptic-device
    ├── build
    ├── CMakeLists.txt
    ├── LJ.cpp
    ├── Makefile
    └── README.md

At this point, the software should run with mouse and keyboard. The following steps are for setting up the haptic device 8. The binary will be written to bin/lin-x86_64/haptic-device 9. You may to change lines involving the relative file path

bool fileload = texture->loadFromFile(RESOURCE_PATH("../resources/images/spheremap-3.jpg"));

to the absolute file path.

10. Run the following commands while in the CHAI3D root:

• sudo cp ./externals/DHD/doc/linux/51-forcedimension.rules /etc/udev/rules.d
• sudo udevadm control --reload-rules && udevadm trigger

MacOS

1. Download the latest release of CHAI3D for Mac OS X from chai3d
2. Make sure you have XCode downloaded, and follow instructions from the file entitled "getting-started.html" located in the doc folder of chai3d
3. Copy over all of the files from haptic-device into one of the CHAI3D examples, and rename LJ.cpp to to the same name of the .cpp file already in the CHAI3D example, such as "01-mydevice.cpp". If you're getting an error, make sure that you don't have a dupicate LJ.cpp file.
4. Run the example.

Reference

The textbook is too big to upload so here's the link: http://www.charleshouserjr.com/Cplus2.pdf

Notes

Controls

• The buttons are labeled 0-3, starting at the center and going clockwise for user switches
• Button naming convention in LJ-test.cpp (example = name in LJ-test.cp
• p)
  • button 0 = button
    • turns off forces while pressed
  • button 1 = button2
    • this button changes the current atom being used
  • button3 = freebutton
    • also does nothing
  • button2 = button3
    • this changes the camera position
• Keyboard hotkeys:
  • q or ESC
    • quit program
  • f
    • toggle fullscreen
  • u
    • unanchor all atoms
  • s
    • screenshot atomic configuration without graph
  • SPACE
    • freeze atom movement
  • c
    • save configuration to .con file
  • a
    • anchor all atoms
  • ARROW KEYS
    • move camera
  • [ and ]
    • zoom in/out
  • r
    • reset camera
  • CTRL
    • toggle help panel