.. _installing-opensim:

Installing OpenSim
==================

The easiest way to use the OpenSim python API is via `Anaconda`_. The core OpenSim
development team ensure that each release of the `OpenSim Core API`_ works against
some version of Anaconda. The `OpenSim Condaforge Files Page`_ lists all available
Condaforge packages for OpenSim, where you'll see packages for Windows, MacOS,
and Linux accross Python 3.9, 3.10, and 3.11.

The official `OpenSim "Scripting in Python" Guide`_ also outlines how to setup scripting. This
page is a mostly-redundant copy of that one, but with CBL-specific tweaks based on problems
we've encountered when getting people up to speed.

Although ``cbltoolkit`` focuses on python scripting, we don't recommend conducting your
research with *only* python. You should find the best tool for the job. Sometimes it's
python, sometimes it's `OpenSim Creator`_, and sometimes it's Excel. If you get a chance,
go through the :ref:`other-recommended-resources`

Get Anaconda
------------

Download `Anaconda`_ for your operating system. The process is OS-specific, so you
might need to google around a little bit to figure out what's best for your situation.
**Note**: you don't usually need to register or provide an email in order to download it.


Setup an Anaconda Environment with ``opensim``
----------------------------------------------

Once `Anaconda`_ is installed, you'll want to create an `Anaconda Environment`_ that
you can install the ``opensim`` package into.

You can either create an environment through the `Anaconda Navigator`_ app that is
packaged with Anaconda, or via the command-line. Both approaches are explained here,
and both have the side-effect of creating a new ``cbl`` environment that's based
on `Anaconda`_ 's ``base`` (default) environment, but with ``opensim`` also installed
into it.


Setup an Anaconda Environment via the Command Line
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Open a terminal (e.g. Windows Powershell)
2. You may need to figure out where ``conda`` is installed. For me, it was installed
   on a per-user basis, so it ended up at ``/C/Users/adamk/anaconda3/Scripts/conda.exe``.
   This means that you have to use ``/C/Users/adamk/anaconda3/Scripts/conda.exe`` rather
   than ``conda`` below. Or, alternatively, add the ``Scripts`` directory to the PATH
   (google "add folder to the path $OPERATING_SYSTEM").

.. code-block:: console

    # On Windows, e.g. in a git bash shell, you can add `conda` to the path like so:
    #     export PATH=/c/Users/adamk/anaconda3/Scripts/:$PATH

    # create a conda environment called `opensim-env`
    conda create -n opensim-env python=3.11
    conda activate opensim-env
    conda install opensim-org::opensim

.. _Anaconda: https://www.anaconda.com/
.. _Anaconda Environment: https://docs.anaconda.com/working-with-conda/environments/
.. _Anaconda Navigator: https://docs.anaconda.com/navigator/
.. _OpenSim Core API: https://github.com/opensim-org/opensim-core
.. _OpenSim's Condaforge: https://anaconda.org/opensim-org/opensim
.. _OpenSim Condaforge Files Page: https://anaconda.org/opensim-org/opensim/files
.. _OpenSim "Scripting in Python" Guide: https://opensimconfluence.atlassian.net/wiki/spaces/OpenSim/pages/53085346/Scripting+in+Python
.. _OpenSim Creator: https://www.opensimcreator.com/