Welcome to our second NeuroMechFly video tutorial. In this tutorial, we will cover how to —
different ways to install NeuroMechFly on your local computer.
You can start by visiting our documentation site at neuromechfly.org.
On the top right corner, you'll see a link to the FlyGym GitHub repository where our
code actually resides.
You'll notice that the name of the package is FlyGym. The difference between FlyGym and NeuroMechFly
is that NeuroMechFly is what we call our model, whereas FlyGym is the name
of the software implementation of it.
The current version of FlyGym is 2.1.0. Future releases of FlyGym might differ from
this tutorial, so it's recommended that you always follow the instructions here on the installation page
instead of what I will do verbatim in this video tutorial.
There are four different ways to install NeuroMechFly, or rather FlyGym. I'll cover all of
them. If you simply want it to work,
and if you don't want to change the code
base of NeuroMechFly, then the easiest way to do it is to use pip.
If you have experience with Python, you're probably already familiar with the pip install syntax.
The FlyGym package is published on the Python package index.
Now we'll follow this method of installation. It's recommended that you always create a Python virtual
environment for every project that you work on.
You can use any virtual environment manager. In this case, we'll use Conda.
Let's create a Conda environment.
Let's call it FlyGym and use Python 3.14, which is the latest Python version that's
supported by FlyGym.
As of now, it is also the latest Python version in general.
Conda environment is ready. Let's activate it.
We can simply run this command, pip install flygym.
Let's start a Python interactive loop.
Here we can simply import FlyGym. The first time you run it after installing it,
it's going to take some time.
This is because it needs to internally build up some cache files and just set up
a few things.
The second time you run it, it should be much faster already. Let's try it again.
Much better.
There are optional dependency groups that you may choose to install along with the standard FlyGym base package.
For example, if you want to run GPU-accelerated simulation on a computer with NVIDIA GPUs,
you simply append this part to FlyGym.
If you want to follow examples that are provided with it, you can include the example,
optional dependencies, etc.
Now let's try this.
Sorry, on the Mac you actually have to put this in double quotation marks.
If you're using zsh in general instead of Bash, it's not just because you're on macOS.
Now we will also have optional dependencies to run some tutorials that are included with
the FlyGym package.
If you are running NeuroMechFly on a headless machine, so a machine without a display,
this might be a server that your university or your institution might provide,
or some cloud virtual machine, then you might need to set up a few environment variables
to use the correct rendering backend.
The second way of installing FlyGym is using uv, which is a very, very fast package manager.
We recommend this for people who wish to change the NeuroMechFly or FlyGym codebase
or people who wish to contribute their changes back to our FlyGym project.
Let's start by deactivating the FlyGym Conda environment that we created.
If you use uv, you actually need to clone the GitHub repository.
Let's go into the FlyGym folder that has been created.
Now, we see that everything from the repository is here.
This method of installation obviously requires that you have uv already installed. If you don't have
it installed, please follow the installation instruction from the uv documentation site.
Assuming you have uv, you can run uv sync to install the package.
As before, you can select optional dependency groups. In this case, we will use examples, but
we'll also include an optional dependency group called Dev
for developers. Under this group, you'll get development tools like the packages that
are used to build this very documentation site
and also just linters and unit testing tools and things like that.
uv is very fast. This is why we chose it.
Now, we should have a venv folder that uv has created. There are two ways to
run things using the virtual environment.
The first one is to source this activation script in the virtual environment.
From there, you can simply run Python, for example,
and import FlyGym. Again, the first time you run it after installation, it's going to take some time.
Let's deactivate this environment.
The second way of running things with this virtual environment is to prepend uv run
to the script, which is commands in general that you wish to run.
For example, we can also launch a Python interactive loop like this
and import FlyGym. This time it's also a lot faster.
The advantage of cloning the actual repository is that you also have access to a couple
of scripts that I think are not included in the package that's published to the Python Package Index (PyPI).
For example, there's this very handy interactive viewer that you may launch.
This is basically what we demonstrated in the first tutorial in the interactive viewer on
the FlyGym website, but it runs locally.
Well, technically here it also runs locally because the simulation happens in your browser. It doesn't
happen on our server,
but here it's a Python program that uses the official interactive viewer from MuJoCo.
All of this entire interface comes with MuJoCo. We didn't develop it.
Okay, so this is the second way of installing FlyGym.
Maybe one thing to note is that if
you wish to contribute back to our FlyGym code
or code repository, this also follows the instruction here.
Basically what it does is that it installs a git filter that excludes large output cells
in tutorial notebooks when you make commits.
This prevents very large files like videos from being pushed to the FlyGym GitHub repository, which
would make cloning the repository much, much slower. The third way of installing
FlyGym is that you can also use the git filter to install it.
So this is the second way of doing it.
Maybe I will cover the fourth way first.
The fourth way of using FlyGym actually doesn't require you to install anything at all.
You can run it online using Google's cloud-based notebook service, Google Colab.
What you do here is actually you just go to the tutorial that you're interested
in, for example tutorial 1a, and you just click this open in Colab button.
You can simply run the notebook here. Let's run ourselves.
The first cell block is going to take some time, like maybe a minute.
It's going to install, or rather,
FlyGym on this Colab session. You don't really need to do
much except waiting.
If you wish to use a different FlyGym version, just change this number here.
This is actually an example of having to change this environment variable here.
Now we can go down the notebook.
Since we clicked run all, everything should be ready. And
without covering the details of this notebook, I'll just show you that it works.
You can run simulation simply in the browser on the Google Colab server.
Maybe one thing to note is that Colab can be very slow. It can be, in
our experience, up to 50 times slower depending on service availability on Google's side.
So please use this only for testing and following the documentation.
Maybe one thing that's worth noting is that for the specific tutorial that uses GPU acceleration,
you have to first
select a Colab instance with a GPU attached.
So you can do this by going to runtime, change runtime type, and select
one of these with a GPU with the free version. As of now, you only get T4.
As before, we can click run all. I'm not going to wait until the whole thing
executes, but you get the gist.
The last way to install FlyGym is to do it using Docker.
Docker is a container service, or rather a software for containerized software.
If you're not already familiar with the idea of using containers for software, it basically takes
the inspiration from
actual shipping containers, which are standardized, and it makes shipping much more efficient and cheaper.
Similarly, containerization in software development means that applications are packaged into a consistent format
called containers, and this basically separates the task
of building an application from building an application that
runs those containers.
So Docker is one of the software that runs such applications, and we have prepackaged FlyGym
as an image on Docker Hub.
You can use currently, the latest version is 2.1.0.
I wouldn't recommend this for most users.
However, if you're trying to run FlyGym on a supercomputer or a cluster from institution
or some containerized service providers,
maybe follow this tutorial. We have only in fact tested this on Linux, so now I'm
going to SSH into my Linux machine.
The first thing to make sure of is to make sure that you have Docker installed.
If you do, you may download the FlyGym image,
either the latest version or a specific version. Let's just be explicit here. I have
it already on my computer, so this didn't take much time at all.
Depending on your network connection and how much data has already been cached, this can take,
I don't know, one minute.
Once you have that, you can run this image by running this command.
I means interactive, and T means you'll get a TTY session, namely basically a shell.
You can specify that the program you specifically want to run
is a TTY session. A shell. You can specify that the
program you specifically want to run in this image is bash,
simply to get a shell, and you want to run this image that we have just called.
Now you get a shell. And all you need to do is to activate the
virtual environment that already exists, or instead, use uv run.
I'm sorry. Without that extra activate. Thank you.