Installation

Installing

API Key

You will need an API key prior to installing kdFlex. This key will be used by package managers, e.g., apt or homebrew, to access software packages from Karana Dynamics. The key will be provided upon creation of a Karana Dynamics account along with a license file. If you don’t already have an account, please sign up here before proceeding.

Ubuntu

1. Apt package manager one time setup (and Windows WSL2): This step only has to be done the first time you are installing. Afterwards, you can skip this and just do steps 2 onward.

   First ensure that curl is installed:

   sudo apt install curl
   

   To make things simpler, you can set your API key to an environment variable via

   export API_KEY=<API_KEY_FROM_EMAIL>
   

   for bash or zsh and via setenv API_KEY <API_KEY_FROM_EMAIL> for csh. This only needs to be done for this step. This environment variable is not needed in subsequent steps.

   Set up the GPG signing key:

   curl -H "Authorization: Bearer $API_KEY" https://artifact-keeper.karanadyn.com/debian/karana-debian/gpg-key.asc | sudo gpg --dearmor -o /etc/apt/keyrings/karana-dynamics-debian.gpg
   

   Set up the apt authorization:

   sudo tee /etc/apt/auth.conf.d/karana-dynamics.conf > /dev/null << EOF
   machine artifact-keeper.karanadyn.com
   login token
   password $API_KEY
   EOF
   

   Set up the apt repository:

   sudo tee /etc/apt/sources.list.d/karana-dynamics.sources > /dev/null << EOF 
   Types: deb
   URIs: https://artifact-keeper.karanadyn.com/debian/karana-debian
   Suites: stable
   Components: main
   Signed-By: /etc/apt/keyrings/karana-dynamics-debian.gpg
   EOF
   

2. Debian package (and Windows WSL2): Run

   sudo apt update && sudo apt install kdflex
   

   to install the kdFlex package.

3. Python: Install the Karana Python package located at /usr/share/Karana/python. The recommended way is to do this is in a Python virtual environment. Please note that the Python version should match the version kdFlex is built against. For Ubuntu, this is Python 3.12. To do so, run the following (this will take a few minutes to complete)

   python3.12 -m venv --system-site-packages .venv 
   source .venv/bin/activate 
   pip install /usr/share/Karana/python
   

   The virtual environment can be deactivated at any time using the deactivate command, or re-activated at any time by running source .venv/bin/activate. Alternative ways to install the Python packages are described in the Alternative Python package installation options section below.

4. License setup: Please set the KARANA_LICENSE_FILE environment variable to the location of your license file. This can be done by running one of the following commands in your terminal, or adding the line to your shell configuration file.

• For bash or zsh, use

  export KARANA_LICENSE_FILE=/path/to/license/<user>.license
  

• For csh use setenv KARANA_LICENSE_FILE /path/to/license/<user>.license

5. Verify installation: Run

   /usr/share/Karana/check_installation/check_installation
   

   to verify that the installation is working correctly. This should run a kdFlex example that creates a robot arm multibody model and 3D visualization for it. There may be a start up delay the first time as python generates .pyc files.

MacOS

The macOS (experimental) build is a homebrew package for macOS golden gate.

1. Brew package manager one time setup This step only has to be done the first time you are installing. Afterwards, you can skip this and just do steps 2 onward. If you do not already have homebrew set up, please do so by following the homebrew setup instructions.

   Create a brew tap for the kdFlex package and trust it by running

   brew tap karana/packages https://tickets.karanadyn.com/general/homebrew-packages.git
   brew trust karana/packages
   

2. Install via Brew:

   Run the following to install the kdFlex package. This will require the API key you received in the email with your license.

   HOMEBREW_KARANA_ARTIFACT_KEEPER_TOKEN=<API_KEY_FROM_EMAIL> brew install kdflex
   

   To make things simpler, you can set your API key to an environment variable in your shell configuration file

   export HOMEBREW_KARANA_ARTIFACT_KEEPER_TOKEN=<API_KEY_FROM_EMAIL>
   

   for bash or zsh and via setenv HOMEBREW_KARANA_ARTIFACT_KEEPER_TOKEN <API_KEY_FROM_EMAIL> for csh, so you don’t need to enter it when updating kdFlex in the future.

3. Python: Install the Karana Python packaged located at /opt/homebrew/share/Karana/python. The recommended way is to do this is in a Python virtual environment. Please note that the Python version should match the version kdFlex is built against. For macOS, this is Python 3.14. To do so, run the following (this will take a few minutes to complete)

   python3.14 -m venv --system-site-packages .venv 
   source .venv/bin/activate 
   pip install /opt/homebrew/share/Karana/python
   

   The virtual environment can be deactivated at any time using the deactivate command, and re-activate at any time by running source .venv/bin/activate. Alternative ways to install the Python packages are described in the Alternative Python package installation options section below.

4. License setup: Please set the KARANA_LICENSE_FILE environment variable to the location of your license file. This can be done by running one of the following commands in your terminal, or adding the line to your shell configuration file.

• For bash or zsh, use

  export KARANA_LICENSE_FILE=/path/to/license/<user>.license
  

• For csh use setenv KARANA_LICENSE_FILE /path/to/license/<user>.license

5. Verify installation: Run

   /opt/homebrew/share/Karana/check_installation/check_installation
   

   to verify that the installation is working correctly. This should run a kdFlex example that creates a robot arm multibody model and 3D visualization for it. There may be a start up delay the first time as python generates .pyc files.

Windows WSL

kdFlex can be run on a Windows system via WSL. Instructions on setting up WSL itself are available here. kdFlex installation instructions are the same as for ubuntu above.

Next steps

You now have a working installation of kdFlex. The next step would be to review the Usage Guide for an overview of kdFlex’s capabilities, API, and usage. You can explore the Jupyter notebook tutorial examples included in the installation are described in the Examples section. These working examples illustrate the use of kdFlex’s Python API. The Program Skeletons area summarizes the steps needed for setting up your own simulations, and the Recipes area has details for specific steps that may be needed. The online kdFlex Chatbot is another handy way to get answers to your questions.

Forum, Issue tracker: You may want to create accounts on the online kdFlex community forum and issue tracker for additional support resources.

Documentation

• kdFlex Chatbot

• Examples

• Usage Guide

• Program Skeletons

• Recipes

• Documentation

• Concepts

• Spatial Operator Algebra (SOA) theory (book)

• Working with C++: See the C++ and Python layers section for details about how to build and use your application with kdFlex.

Upgrading

To upgrade kdFlex to a newer version, you can repeat the instructions given in steps 1 and 2 above in the Installing section. This will remove the old version of kdFlex and install the new version. In addition, it will update the Python dependencies if required.

Docker image

This section is for users interested in running the Ubuntu kdFlex build on a different Linux OS. The following describes the process for creating a docker container to host kdFlex. The instructions below assume that you are already familiar with basic docker usage. Docker documentation is available here.

The Dockerfile below can be used to build a basic container with kdFlex installed. This should be built with the kdFlex DEB package and license file in the same directory as the Dockerfile.

# Use Ubuntu 24 image
FROM ubuntu:24.04

# Set the shell to /bin/bash
SHELL ["/bin/bash", "-ec"]

# Set LANG
ENV LANG="C.UTF-8"

# Update apt update
RUN apt update

# Install kdFlex
COPY ./kdflex*.deb /tmp
RUN apt install -y --fix-broken /tmp/kdflex*.deb

# Install Python dependencies 
RUN (cd /opt && python3 -m venv --system-site-packages .venv && source .venv/bin/activate && pip install /usr/share/Karana/python)

# Add source command to bashrc so the venv is automatically sourced
RUN echo "source /opt/.venv/bin/activate" >> ~/.bashrc

# Copy license file to /opt
COPY ./*.license /opt

# Add license file to bashrc
RUN echo "export KARANA_LICENSE_FILE=`ls /opt/*.license | head -n 1`" >> ~/.bashrc

The image can be built by running the following command:

docker build -f Dockerfile -t kdflex:latest .

The image can be run using:

docker run --net=host -ti kdflex:latest bash

The --net=host is added to map ports from the docker container to the local machine. This allows one to view the graphics, data plots, etc. by connecting to the appropriate URL with a web browser. The image above does not contain any logic to forward graphics applications from the docker image to the localhost, so bringing up a local window via the electron app is not an option from within the container as written above. Doing so is possible, but is OS and machine specific.

Known issues

• When using web browsers on Windows operating systems for remote viewing of kdFlex 3D graphics, render updates do not work properly for Chrome based browsers such as Chromium and Edge. Firefox does work properly.

Alternative Python package installation options

The following describe alternative options (instead of the recommended virtual environment option described in the Installing section) for installing the Python packages needed by kdFlex:

1. User local installation: Install the requirements for your user by running

   pip install --break-system-packages /usr/share/Karana/python
   

   or

   pip install --break-system-packages /opt/homebrew/share/Karana/python
   

   if on macOS. This will install the packages to locally. You will likely need to add ~/.local/bin to your path if it is not on there already, e.g., for bash run

   export PATH=~/.local/bin:$PATH
   

   to do it for the current terminal session or add the export line to your shell configuration file.

2. System level installation: (Ubuntu only) (CAUTION: This will modify the system-wide Python install so please use with care.) This should not be done on macOS, as the system Python version is too old to work with kdFlex. Install the requirements at the system level by running

   sudo pip install --break-system-packages /usr/share/Karana/python
   

   This may require uninstalling some Python packages installed via apt with conflicting versions. This can be done using

   sudo apt remove <package_name>
   

Installing to alternative location

It is rare, but sometimes users will want to install the kdFlex package to an alternative location. For Ubuntu, one can download the deb file using

apt download kdflex

and then use dpkg to install to an alternative location.

For macOS, one can use

brew fetch kdflex
brew --cache kdflex

to download the .tar.gz file and get its location on the filesystem. Then, one can untar it to unpack it in a location of their choosing.