(gettingstarted_page)= # Installation (installing_sec)= ## Installing ### Ubuntu Download the [ubuntu 24 kdFlex Debian file](https://portal.karanadyn.com/download) and 1. **Debian package (and Windows WSL2):** Run ```sh sudo apt update && sudo apt install ./kdflex-*-Linux.deb ``` to install the {{ kdflex }} package. 2. **Python dependencies:** Install the Python requirements located in `/usr/share/Karana/requirements.txt`. 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) ```sh python3.12 -m venv --system-site-packages .venv source .venv/bin/activate pip install --upgrade -r /usr/share/Karana/requirements.txt ``` 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](python_pkg_install_sec) section below. 3. **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 ```bash export KARANA_LICENSE_FILE=/path/to/license/.license ``` * For `csh` use `setenv KARANA_LICENSE_FILE /path/to/license/.license` 4. **Verify installation:** Run ```sh /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 is a `homebrew` package for *macOS sequoia*. Since the files require login access, you will need to create a *brew tap* yourself (instructions below). To begin, download *macOS sequoia* {{ kdflex }} package from the [downloads page](https://portal.karanadyn.com/download). Then: 1. **Install via Brew:** If you do not already have `homebrew` set up, please do so by following the [homebrew setup instructions](https://brew.sh/). a. **Brew tap:** Create a brew tap for the {{ kdflex }} package by running ```sh brew tap-new karana/kdflex ``` b. **Brew formula:** Untar the `*.tar.gz` file from the [downloads page](https://portal.karanadyn.com/download) into `/opt/homebrew/Library/Taps/karana/homebrew-kdflex/Formula`. From the directory where you originally downloaded the files, run ```sh tar -vxf kdflex*.tar.gz -C /opt/homebrew/Library/Taps/karana/homebrew-kdflex/Formula ``` c. **Brew install:** Run the following to install the {{ kdflex }} package: ```sh brew install karana/kdflex/kdflex ``` 2. **Python dependencies:** Install the Python requirements located in `/opt/homebrew/share/Karana/requirements.txt`. 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) ```sh python3.14 -m venv --system-site-packages .venv source .venv/bin/activate pip install --upgrade -r /opt/homebrew/share/Karana/requirements.txt ``` 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](python_pkg_install_sec) section below. 3. **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 ```bash export KARANA_LICENSE_FILE=/path/to/license/.license ``` * For `csh` use `setenv KARANA_LICENSE_FILE /path/to/license/.license` 4. **Verify installation:** Run ```sh /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](https://learn.microsoft.com/en-us/windows/wsl/install). {{ kdflex }} installation instruction 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](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](./examples.md) section. These working examples illustrate the use of **kdFlex's** Python API. The [Program Skeletons](procedures) area summarizes the steps needed for setting up your own simulations, and the [Recipes](recipes.md) area has details for specific steps that may be needed. The online [kdFlex Chatbot](https://portal.karanadyn.com/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](https://forum.karanadyn.com) and [issue tracker](https://tickets.karanadyn.com) for additional support resources. ### Documentation - [kdFlex Chatbot](https://portal.karanadyn.com/chatbot/) - [Examples](./examples.md) - [Usage Guide](usage_guide) - [Program Skeletons](procedures) - [Recipes](recipes.md) - [Documentation](https://portal.karanadyn.com/docs/) - [Concepts](concepts) - [Spatial Operator Algebra (SOA) theory (book)](https://link.springer.com/book/10.1007/978-1-4419-7267-5) - **Working with C++:** See the [C++ and Python layers](cpp_python_sec) 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](installing_sec) 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](https://docs.docker.com/). 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. ```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 --upgrade -r /usr/share/Karana/requirements.txt) # 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: ```sh docker build -f Dockerfile -t kdflex:latest . ``` The image can be run using: ```sh 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. (python_pkg_install_sec)= ### Alternative Python package installation options The following describe alternative options (instead of the recommended virtual environment option described in the [Installing](installing_sec) section) for installing the Python packages needed by {{ kdflex }}: 1. **User local installation:** Install the requirements for your user by running ```sh pip install --break-system-packages -r /usr/share/Karana/requirements.txt ``` or ```sh pip install --break-system-packages -r /opt/homebrew/share/Karana/requirements.txt ``` 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 ```sh 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 ```sh sudo pip install --break-system-packages -r /usr/share/Karana/requirements.txt ``` This may require uninstalling some Python packages installed via `apt` with conflicting versions. This can be done using ```sh sudo apt remove ```