**********************************
Structure of the User Code Package
**********************************

In order to be able to execute your code on our robots, you need to follow a few
rules regarding the structure:

- All code needs to be in a single git repository.  You may use git submodules
  to add content of other repositories.

- Your code should be provided as a regular Python package that can be installed by calling:

  .. code-block:: console

      pip install .

  at the root directory of the repository.

- Apart from your code, the repository needs to contain a configuration file
  called ``trifinger.toml``, see `Configuration File`_.


.. note::

   We provide an `example package`_ (the one that was already used for the pre-stage).
   You can use this package as base for your own one.


Python Package
==============

When running your code on the robot, your git repository is expected to contain a
Python package that will be installed via pip.

This means that if your code depends on other Python packages, that are not
already included in our :doc:`Apptainer image <../singularity>`, you can simply
specify them as dependencies (e.g. in the ``setup.cfg`` when using
`setuptools`_).  If you have dependencies that cannot be installed with pip, you
can provide a custom Apptainer image (see :ref:`singularity_custom_image`).


Configuration File
==================

Your git repository must have a TOML file ``trifinger.toml`` in its root
directory which specifies the classes that implement your policies as well as
the task you want to run.
For example if your package is called ``my_trifinger_rl_package`` and contains a
module ``policies`` in which the classes ``MyPushPolicy`` and ``MyLiftPolicy``
are defined:

.. code-block:: toml
     
    [trifinger_rl_experiment]
    task = "push"  # "push" or "lift"
    
    # Specify a policy for each task.
    push_policy = "my_trifinger_rl_example.policies.TorchPushPolicy"
    lift_policy = "my_trifinger_rl_example.policies.TorchLiftPolicy"

``task`` has to be set to either "push" or "lift" and determines which
environment is used when you submit a job to the robot.

``{TASK}_policy`` specifies the class that implements the policy
for the corresponding task.

To run jobs on the robots, it is enough if you specify a policy for the task set
in the file.  

The Policy Classes
==================

The policy classes specified in the configuration file (see above) are expected to
implement the interface of :class:`trifinger_rl_datasets.PolicyBase`. See 
:ref:`starting_from_the_example_package` for more information.


Run Code inside the Container
=============================

To locally test your code inside the Apptainer container, please follow the 
instructions given in the simulation section: :ref:`setup_workspace_with_apptainer`.


.. _validate_package:

Validate Your Package Before Submitting to the Robots
=====================================================

The `example package`_ contains a script ``validate.py`` which runs some basic checks to
verify that your package has the correct structure (e.g. if the package can be
installed, if a policy is configured and if it follows the expected interface, etc.).
It is recommended to run this script to check for basic errors before you start
submitting jobs to the robots.  Assuming your package is based on the example
package, you can run it like this from the root directory of the package:

.. code-block:: bash

    cd path/to/your_package
    apptainer run -e --no-home --bind=$(pwd),${HOME}/.cache/pip ./path/to/trifinger_rl.sif python3 scripts/validate.py

Replace ``trifinger_rl.sif`` accordingly, if using a custom container.

Binding ``~/.cache/pip`` is not strictly needed but it avoids unnecessary
downloads of packages which can make a significant difference if large packages
(e.g. torch) are involved.



.. _setuptools: https://setuptools.pypa.io/en/latest/userguide/quickstart.html