![](doc/img/logo/logo8.png)

# Rofunc: The Full Process Python Package for Robot Learning from Demonstration and Robot Manipulation

[![Release](https://img.shields.io/github/v/release/Skylark0924/Rofunc)](https://pypi.org/project/rofunc/)
![License](https://img.shields.io/github/license/Skylark0924/Rofunc?color=blue)
![](https://img.shields.io/github/downloads/skylark0924/Rofunc/total)
[![](https://img.shields.io/github/issues-closed-raw/Skylark0924/Rofunc?color=brightgreen)](https://github.com/Skylark0924/Rofunc/issues?q=is%3Aissue+is%3Aclosed)
[![](https://img.shields.io/github/issues-raw/Skylark0924/Rofunc?color=orange)](https://github.com/Skylark0924/Rofunc/issues?q=is%3Aopen+is%3Aissue)
[![Documentation Status](https://readthedocs.org/projects/rofunc/badge/?version=latest)](https://rofunc.readthedocs.io/en/latest/?badge=latest)
[![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2FSkylark0924%2FRofunc%2Fbadge%3Fref%3Dmain&style=flat)](https://actions-badge.atrox.dev/Skylark0924/Rofunc/goto?ref=main)

> **Repository address: https://github.com/Skylark0924/Rofunc**

> **Documentation: https://rofunc.readthedocs.io/**

Rofunc package focuses on the **Imitation Learning (IL), Reinforcement Learning (RL) and Learning from Demonstration (LfD)** for **(Humanoid) Robot Manipulation**. It provides valuable and convenient python functions, including
_demonstration collection, data pre-processing, LfD algorithms, planning, and control methods_. We also provide an
`IsaacGym` and `OmniIsaacGym` based robot simulator for evaluation. This package aims to advance the field by building a full-process
toolkit and validation platform that simplifies and standardizes the process of demonstration data collection,
processing, learning, and its deployment on robots.

![](doc/img/pipeline.png)

- [Rofunc: The Full Process Python Package for Robot Learning from Demonstration and Robot Manipulation](#rofunc-the-full-process-python-package-for-robot-learning-from-demonstration-and-robot-manipulation)
  - [Update News 🎉🎉🎉](#update-news-)
  - [Installation](#installation)
  - [Documentation](#documentation)
  - [RofuncRL](#rofuncrl)
  - [Star History](#star-history)
  - [Citation](#citation)
  - [Related Papers](#related-papers)
  - [The Team](#the-team)
  - [Acknowledge](#acknowledge)
    - [Learning from Demonstration](#learning-from-demonstration)
    - [Planning and Control](#planning-and-control)

## Update News 🎉🎉🎉
- [2024-01-24] 🚀 [CURI Synergy-based Softhand grasping tasks](https://github.com/Skylark0924/Rofunc/blob/main/examples/learning_rl/IsaacGym_RofuncRL/example_DexterousHands_RofuncRL.py) are supported to be trained by `RofuncRL`.
- [2023-12-24] 🚀 [Dexterous hand (Shadow Hand, Allegro Hand, qbSofthand) tasks](https://github.com/Skylark0924/Rofunc/blob/main/examples/learning_rl/IsaacGym_RofuncRL/example_DexterousHands_RofuncRL.py) are supported to be trained by `RofuncRL`.
- [2023-12-03] 🖼 [Segment-Anything (SAM)](https://segment-anything.com/) is supported in an interactive mode, check the examples in Visualab ([segment anything](https://github.com/Skylark0924/Rofunc/blob/main/examples/visualab/example_sam_seg.py), [segment with prompt](https://github.com/Skylark0924/Rofunc/blob/main/examples/visualab/example_sam_seg_w_prompt.py)).
- **[2023-10-31] 🚀 [`RofuncRL`](https://rofunc.readthedocs.io/en/latest/lfd/RofuncRL/index.html): A modular easy-to-use Reinforcement Learning sub-package designed for Robot Learning tasks is released. It has been tested with simulators like `OpenAIGym`, `IsaacGym`, `OmniIsaacGym` (see [example gallery](https://rofunc.readthedocs.io/en/latest/examples/learning_rl/index.html)), and also differentiable simulators like `PlasticineLab` and `DiffCloth`.**
- ...
- If you want to know more about the update news, please refer to the [changelog](https://github.com/Skylark0924/Rofunc/blob/main/changelog.md).

## Installation

Please refer to the [installation guide](https://rofunc.readthedocs.io/en/latest/installation.html).

## Documentation

[![Documentation](https://img.shields.io/badge/Documentation-Access-brightgreen?style=for-the-badge)](https://rofunc.readthedocs.io/en/latest/)
[![Example Gallery](https://img.shields.io/badge/Example%20Gallery-Access-brightgreen?style=for-the-badge)](https://rofunc.readthedocs.io/en/latest/examples/index.html)

To give you a quick overview of the pipeline of `rofunc`, we provide an interesting example of learning to play Taichi
from human demonstration. You can find it in the [Quick start](https://rofunc.readthedocs.io/en/latest/quickstart.html)
section of the documentation.

The available functions and plans can be found as follows.

> **Note**
> ✅: Achieved 🔃: Reformatting ⛔: TODO

|                                                  Data                                                   |   |                                                Learning                                                |    |                                                        P&C                                                         |    |                                                        Tools                                                        |   |                                                  Simulator                                                   |    |
|:-------------------------------------------------------------------------------------------------------:|---|:------------------------------------------------------------------------------------------------------:|----|:------------------------------------------------------------------------------------------------------------------:|----|:-------------------------------------------------------------------------------------------------------------------:|---|:------------------------------------------------------------------------------------------------------------:|----|
|              [`xsens.record`](https://rofunc.readthedocs.io/en/latest/devices/xsens.html)               | ✅ |                                                 `DMP`                                                  | ⛔  |                         [`LQT`](https://rofunc.readthedocs.io/en/latest/planning/lqt.html)                         | ✅  |                                                      `config`                                                       | ✅ |                  [`Franka`](https://rofunc.readthedocs.io/en/latest/simulator/franka.html)                   | ✅  |
|              [`xsens.export`](https://rofunc.readthedocs.io/en/latest/devices/xsens.html)               | ✅ |      [`GMR`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.learning.ml.gmr.html)       | ✅  |       [`LQTBi`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.planning_control.lqt.lqt.html)       | ✅  |      [`logger`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.utils.logger.beauty_logger.html)      | ✅ |                    [`CURI`](https://rofunc.readthedocs.io/en/latest/simulator/curi.html)                     | ✅  |
|              [`xsens.visual`](https://rofunc.readthedocs.io/en/latest/devices/xsens.html)               | ✅ |    [`TPGMM`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.learning.ml.tpgmm.html)     | ✅  |                      [`LQTFb`](https://rofunc.readthedocs.io/en/latest/planning/lqt_fb.html)                       | ✅  |            [`datalab`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.utils.datalab.html)            | ✅ |                                                  `CURIMini`                                                  | 🔃 |
|             [`opti.record`](https://rofunc.readthedocs.io/en/latest/devices/optitrack.html)             | ✅ |   [`TPGMMBi`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.learning.ml.tpgmm.html)    | ✅  |                      [`LQTCP`](https://rofunc.readthedocs.io/en/latest/planning/lqt_cp.html)                       | ✅  | [`robolab.coord`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.utils.robolab.coord.transform.html) | ✅ |   [`CURISoftHand`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.simulator.curi_sim.html)    | ✅  |
|             [`opti.export`](https://rofunc.readthedocs.io/en/latest/devices/optitrack.html)             | ✅ | [`TPGMM_RPCtl`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.learning.ml.tpgmm.html)  | ✅  |  [`LQTCPDMP`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.planning_control.lqt.lqt_cp_dmp.html)  | ✅  |   [`robolab.fk`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.utils.robolab.kinematics.fk.html)    | ✅ |     [`Walker`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.simulator.walker_sim.html)      | ✅  |
|             [`opti.visual`](https://rofunc.readthedocs.io/en/latest/devices/optitrack.html)             | ✅ | [`TPGMM_RPRepr`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.learning.ml.tpgmm.html) | ✅  |        [`LQR`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.planning_control.lqr.lqr.html)        | ✅  |   [`robolab.ik`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.utils.robolab.kinematics.ik.html)    | ✅ |                                                   `Gluon`                                                    | 🔃 |
|                [`zed.record`](https://rofunc.readthedocs.io/en/latest/devices/zed.html)                 | ✅ |    [`TPGMR`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.learning.ml.tpgmr.html)     | ✅  |     [`PoGLQRBi`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.planning_control.lqr.lqr.html)      | ✅  |                                                    `robolab.fd`                                                     | ⛔ |                                                   `Baxter`                                                   | 🔃 |
|                [`zed.export`](https://rofunc.readthedocs.io/en/latest/devices/zed.html)                 | ✅ |   [`TPGMRBi`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.learning.ml.tpgmr.html)    | ✅  |                        [`iLQR`](https://rofunc.readthedocs.io/en/latest/planning/ilqr.html)                        | 🔃 |                                                    `robolab.id`                                                     | ⛔ |                                                   `Sawyer`                                                   | 🔃 |
|                [`zed.visual`](https://rofunc.readthedocs.io/en/latest/devices/zed.html)                 | ✅ |   [`TPHSMM`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.learning.ml.tphsmm.html)    | ✅  |    [`iLQRBi`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.planning_control.lqr.ilqr_bi.html)     | 🔃 |  [`visualab.dist`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.utils.visualab.distribution.html)  | ✅ |   [`Humanoid`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.simulator.humanoid_sim.html)    | ✅  |
|  [`emg.record`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.devices.emg.record.html)  | ✅ |         [`RLBaseLine(SKRL)`](https://rofunc.readthedocs.io/en/latest/lfd/RLBaseLine/SKRL.html)         | ✅  |                                                      `iLQRFb`                                                      | 🔃 |   [`visualab.ellip`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.utils.visualab.ellipsoid.html)   | ✅ | [`Multi-Robot`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.simulator.multirobot_sim.html) | ✅  |
|  [`emg.export`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.devices.emg.export.html)  | ✅ |                                          `RLBaseLine(RLlib)`                                           | ✅  |    [`iLQRCP`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.planning_control.lqr.ilqr_cp.html)     | 🔃 |   [`visualab.traj`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.utils.visualab.trajectory.html)   | ✅ |                                                                                |    |
|                                             `mmodal.record`                                             | ⛔ |                                          `RLBaseLine(ElegRL)`                                          | ✅  |  [`iLQRDyna`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.planning_control.lqr.ilqr_dyna.html)   | 🔃 |   [`oslab.dir_proc`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.utils.oslab.dir_process.html)    | ✅ |                                                                                |    |
| [`mmodal.sync`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.devices.mmodal.sync.html) | ✅ |                                            `BCO(RofuncIL)`                                             | 🔃 | [`iLQRObs`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.planning_control.lqr.ilqr_obstacle.html) | 🔃 |  [`oslab.file_proc`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.utils.oslab.file_process.html)   | ✅ |                                                                                |    |
|                                                                                |   |                                            `BC-Z(RofuncIL)`                                            | ⛔  |                                                       `MPC`                                                        | ⛔  |     [`oslab.internet`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.utils.oslab.internet.html)     | ✅ |                                                                                |    |
|                                                                                |   |                                           `STrans(RofuncIL)`                                           | ⛔  |                                                       `RMP`                                                        | ⛔  |         [`oslab.path`](https://rofunc.readthedocs.io/en/latest/apidocs/rofunc/rofunc.utils.oslab.path.html)         | ✅ |                                                                                |    |
|                                                                                |   |                                            `RT-1(RofuncIL)`                                            | ⛔  |                                                                                |    |                                                                                |   |                                                                                |    |
|                                                                                |   |            [`A2C(RofuncRL)`](https://rofunc.readthedocs.io/en/latest/lfd/RofuncRL/A2C.html)            | ✅  |                                                                                |    |                                                                                |   |                                                                                |    |
|                                                                                |   |            [`PPO(RofuncRL)`](https://rofunc.readthedocs.io/en/latest/lfd/RofuncRL/PPO.html)            | ✅  |                                                                                |    |                                                                                |   |                                                                                |    |
|                                                                                |   |            [`SAC(RofuncRL)`](https://rofunc.readthedocs.io/en/latest/lfd/RofuncRL/SAC.html)            | ✅  |                                                                                |    |                                                                                |   |                                                                                |    |
|                                                                                |   |            [`TD3(RofuncRL)`](https://rofunc.readthedocs.io/en/latest/lfd/RofuncRL/TD3.html)            | ✅  |                                                                                |    |                                                                                |   |                                                                                |    |
|                                                                                |   |                                            `CQL(RofuncRL)`                                             | ⛔  |                                                                                |    |                                                                                |   |                                                                                |    |
|                                                                                |   |                                           `TD3BC(RofuncRL)`                                            | ⛔  |                                                                                |    |                                                                                |   |                                                                                |    |
|                                                                                |   |         [`DTrans(RofuncRL)`](https://rofunc.readthedocs.io/en/latest/lfd/RofuncRL/DTrans.html)         | ✅  |                                                                                |    |                                                                                |   |                                                                                |    |
|                                                                                |   |                                            `EDAC(RofuncRL)`                                            | ⛔  |                                                                                |    |                                                                                |   |                                                                                |    |
|                                                                                |   |            [`AMP(RofuncRL)`](https://rofunc.readthedocs.io/en/latest/lfd/RofuncRL/AMP.html)            | ✅  |                                                                                |    |                                                                                |   |                                                                                |    |
|                                                                                |   |            [`ASE(RofuncRL)`](https://rofunc.readthedocs.io/en/latest/lfd/RofuncRL/ASE.html)            | ✅  |                                                                                |    |                                                                                |   |                                                                                |    |
|                                                                                |   |                                          `ODTrans(RofuncRL)`                                           | ⛔  |                                                                                |    |                                                                                |   |                                                                                |    |

## RofuncRL

`RofuncRL` is one of the most important sub-packages of `Rofunc`. It is a modular easy-to-use Reinforcement Learning sub-package designed for Robot Learning tasks. It has been tested with simulators like `OpenAIGym`, `IsaacGym`, `OmniIsaacGym` (see [example gallery](https://rofunc.readthedocs.io/en/latest/examples/learning_rl/index.html)), and also differentiable simulators like `PlasticineLab` and `DiffCloth`. Here is a list of robot tasks trained by `RofuncRL`:

> **Note**\
> You can customize your own project based on RofuncRL by following the [**RofuncRL customize tutorial**](https://rofunc.readthedocs.io/en/latest/tutorial/customizeRL.html).\
> We also provide a [**RofuncRL-based repository template**](https://github.com/Skylark0924/RofuncRL-template) to generate your own repository following the RofuncRL structure by one click.\
> For more details, please check [**the documentation for RofuncRL**](https://rofunc.readthedocs.io/en/latest/examples/learning_rl/index.html).

The list of all supported tasks.

| Tasks                               | Animation                                                                                | Performance | [ModelZoo](https://github.com/Skylark0924/Rofunc/blob/main/rofunc/config/learning/model_zoo.json) |
|-------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|---------------------------------------------------------------------------------------------------|
| Ant                                 | ![](doc/img/task_gifs/AntRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| Cartpole                            |                                                                                |             |                                                                                |
| Franka
Cabinet                  | ![](doc/img/task_gifs/FrankaCabinetRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| Franka
CubeStack                |                                                                                |             |                                                                                |
| CURI
Cabinet                    | ![](doc/img/task_gifs/CURICabinetRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| CURI
CabinetImage               | ![](doc/img/task_gifs/CURICabinetRofuncRLPPO.gif)                                                                                |             |                                                                                |
| CURI
CabinetBimanual            |                                                                                |             |                                                                                |
| CURIQbSoftHand
SynergyGrasp     |  |             | ✅                                                                                |
| Humanoid                            | ![](doc/img/task_gifs/HumanoidRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| HumanoidAMP
Backflip            | ![](doc/img/task_gifs/HumanoidFlipRofuncRLAMP.gif)                                                                                |             | ✅                                                                                |
| HumanoidAMP
Walk                |                                                                                |             | ✅                                                                                |
| HumanoidAMP
Run                 | ![](doc/img/task_gifs/HumanoidRunRofuncRLAMP.gif)                                                                                |             | ✅                                                                                |
| HumanoidAMP
Dance               | ![](doc/img/task_gifs/HumanoidDanceRofuncRLAMP.gif)                                                                                |             | ✅                                                                                |
| HumanoidAMP
Hop                 | ![](doc/img/task_gifs/HumanoidHopRofuncRLAMP.gif)                                                                                |             | ✅                                                                                |
| HumanoidASE
GetupSwordShield    | ![](doc/img/task_gifs/HumanoidASEGetupSwordShieldRofuncRLASE.gif)                                                                                |             | ✅                                                                                |
| HumanoidASE
PerturbSwordShield  | ![](doc/img/task_gifs/HumanoidASEPerturbSwordShieldRofuncRLASE.gif)                                                                                |             | ✅                                                                                |
| HumanoidASE
HeadingSwordShield  | ![](doc/img/task_gifs/HumanoidASEHeadingSwordShieldRofuncRLASE.gif)                                                                                |             | ✅                                                                                |
| HumanoidASE
LocationSwordShield | ![](doc/img/task_gifs/HumanoidASELocationSwordShieldRofuncRLASE.gif)                                                                                |             | ✅                                                                                |
| HumanoidASE
ReachSwordShield    |                                                                                |             | ✅                                                                                |
| HumanoidASE
StrikeSwordShield   | ![](doc/img/task_gifs/HumanoidASEStrikeSwordShieldRofuncRLASE.gif)                                                                                |             | ✅                                                                                |
| BiShadowHand
BlockStack         | ![](doc/img/task_gifs/BiShadowHandBlockStackRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| BiShadowHand
BottleCap          | ![](doc/img/task_gifs/BiShadowHandBottleCapRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| BiShadowHand
CatchAbreast       | ![](doc/img/task_gifs/BiShadowHandCatchAbreastRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| BiShadowHand
CatchOver2Underarm | ![](doc/img/task_gifs/BiShadowHandCatchOver2UnderarmRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| BiShadowHand
CatchUnderarm      | ![](doc/img/task_gifs/BiShadowHandCatchUnderarmRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| BiShadowHand
DoorOpenInward     | ![](doc/img/task_gifs/BiShadowHandDoorOpenInwardRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| BiShadowHand
DoorOpenOutward    | ![](doc/img/task_gifs/BiShadowHandDoorOpenOutwardRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| BiShadowHand
DoorCloseInward    | ![](doc/img/task_gifs/BiShadowHandDoorCloseInwardRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| BiShadowHand
DoorCloseOutward   | ![](doc/img/task_gifs/BiShadowHandDoorCloseOutwardRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| BiShadowHand
GraspAndPlace      | ![](doc/img/task_gifs/BiShadowHandGraspAndPlaceRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| BiShadowHand
LiftUnderarm       | ![](doc/img/task_gifs/BiShadowHandLiftUnderarmRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| BiShadowHand
HandOver           | ![](doc/img/task_gifs/BiShadowHandOverRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| BiShadowHand
Pen                | ![](doc/img/task_gifs/BiShadowHandPenRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| BiShadowHand
PointCloud         |                                                                                |             |                                                                                |
| BiShadowHand
PushBlock          | ![](doc/img/task_gifs/BiShadowHandPushBlockRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| BiShadowHand
ReOrientation      | ![](doc/img/task_gifs/BiShadowHandReOrientationRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| BiShadowHand
Scissors           | ![](doc/img/task_gifs/BiShadowHandScissorsRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| BiShadowHand
SwingCup           | ![](doc/img/task_gifs/BiShadowHandSwingCupRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| BiShadowHand
Switch             | ![](doc/img/task_gifs/BiShadowHandSwitchRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |
| BiShadowHand
TwoCatchUnderarm   | ![](doc/img/task_gifs/BiShadowHandTwoCatchUnderarmRofuncRLPPO.gif)                                                                                |             | ✅                                                                                |

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=Skylark0924/Rofunc&type=Date)](https://star-history.com/#Skylark0924/Rofunc&Date)

## Citation

If you use rofunc in a scientific publication, we would appreciate citations to the following paper:

```
@software{liu2023rofunc,
          title = {Rofunc: The Full Process Python Package for Robot Learning from Demonstration and Robot Manipulation},
          author = {Liu, Junjia and Li, Chenzui and Delehelle, Donatien and Li, Zhihao and Yu, Minghao and Chen, Fei},
          year = {2023},
          publisher = {Zenodo},
          doi = {10.5281/zenodo.10016946},
          url = {https://doi.org/10.5281/zenodo.10016946},
          dimensions = {true},
          google_scholar_id = {0EnyYjriUFMC},
}
```

## Related Papers

1. Robot cooking with stir-fry: Bimanual non-prehensile manipulation of semi-fluid
   objects ([IEEE RA-L 2022](https://arxiv.org/abs/2205.05960) | [Code](rofunc/learning/RofuncIL/structured_transformer/strans.py))

```
@article{liu2022robot,
         title={Robot cooking with stir-fry: Bimanual non-prehensile manipulation of semi-fluid objects},
         author={Liu, Junjia and Chen, Yiting and Dong, Zhipeng and Wang, Shixiong and Calinon, Sylvain and Li, Miao and Chen, Fei},
         journal={IEEE Robotics and Automation Letters},
         volume={7},
         number={2},
         pages={5159--5166},
         year={2022},
         publisher={IEEE}
}
```

2. SoftGPT: Learn Goal-oriented Soft Object Manipulation Skills by Generative Pre-trained Heterogeneous Graph
   Transformer ([IROS 2023](https://arxiv.org/abs/2306.12677)｜Code coming soon)

```
@inproceedings{liu2023softgpt,
               title={Softgpt: Learn goal-oriented soft object manipulation skills by generative pre-trained heterogeneous graph transformer},
               author={Liu, Junjia and Li, Zhihao and Lin, Wanyu and Calinon, Sylvain and Tan, Kay Chen and Chen, Fei},
               booktitle={2023 IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},
               pages={4920--4925},
               year={2023},
               organization={IEEE}
}
```

3. BiRP: Learning Robot Generalized Bimanual Coordination using Relative Parameterization Method on Human
   Demonstration ([IEEE CDC 2023](https://arxiv.org/abs/2307.05933) | [Code](./rofunc/learning/ml/tpgmm.py))

```
@inproceedings{liu2023birp,
               title={Birp: Learning robot generalized bimanual coordination using relative parameterization method on human demonstration},
               author={Liu, Junjia and Sim, Hengyi and Li, Chenzui and Tan, Kay Chen and Chen, Fei},
               booktitle={2023 62nd IEEE Conference on Decision and Control (CDC)},
               pages={8300--8305},
               year={2023},
               organization={IEEE}
}
```

## The Team

Rofunc is developed and maintained by
the [CLOVER Lab (Collaborative and Versatile Robots Laboratory)](https://feichenlab.com/), CUHK.

## Acknowledge

We would like to acknowledge the following projects:

### Learning from Demonstration

1. [pbdlib](https://gitlab.idiap.ch/rli/pbdlib-python)
2. [Ray RLlib](https://docs.ray.io/en/latest/rllib/index.html)
3. [ElegantRL](https://github.com/AI4Finance-Foundation/ElegantRL)
4. [SKRL](https://github.com/Toni-SM/skrl)
5. [DexterousHands](https://github.com/PKU-MARL/DexterousHands)

### Planning and Control

1. [Robotics codes from scratch (RCFS)](https://gitlab.idiap.ch/rli/robotics-codes-from-scratch)


Intel® Extension for Transformers
===========================

An Innovative Transformer-based Toolkit to Accelerate GenAI/LLM Everywhere

[![](https://dcbadge.vercel.app/api/server/Wxk3J3ZJkU?compact=true&style=flat-square)](https://discord.gg/Wxk3J3ZJkU)
[![Release Notes](https://img.shields.io/github/v/release/intel/intel-extension-for-transformers)](https://github.com/intel/intel-extension-for-transformers/releases)

[🏭Architecture](./docs/architecture.md)   |   [💬NeuralChat](./intel_extension_for_transformers/neural_chat)   |   [😃Inference on CPU](https://github.com/intel/neural-speed/tree/main)   |   [😃Inference  on GPU](https://github.com/intel/intel-extension-for-transformers/blob/main/docs/weightonlyquant.md#examples-for-gpu)   |   [💻Examples](./docs/examples.md)   |   [📖Documentations](https://intel.github.io/intel-extension-for-transformers/latest/docs/Welcome.html)

## 🚀Latest News
* [2024/06] Support Qwen2, please find the details in [Blog](https://medium.com/intel-analytics-software/accelerating-qwen2-models-with-intel-extension-for-transformers-99403de82f68)
* [2024/04] Support the launch of **[Meta Llama 3](https://llama.meta.com/llama3/)**, the next generation of Llama models. Check out [Accelerate Meta* Llama 3 with Intel AI Solutions](https://www.intel.com/content/www/us/en/developer/articles/technical/accelerate-meta-llama3-with-intel-ai-solutions.html).
* [2024/04] Demonstrated the chatbot in 4th, 5th, and 6th Gen Xeon Scalable Processors in [**Intel Vision Pat's Keynote**](https://youtu.be/QB7FoIpx8os?t=2280).
* [2024/04] Supported **INT4 inference on Intel Meteor Lake**.
* [2024/04] Achieved a 1.8x performance improvement in GPT-J inference on the 5th Gen Xeon MLPerf v4.0 submission compared to v3.1. [News](https://www.intel.com/content/www/us/en/newsroom/news/new-gaudi-2-xeon-performance-ai-inference.html#gs.71ti1m), [Results](https://mlcommons.org/2024/03/mlperf-inference-v4/).
* [2024/01] Supported **INT4 inference on Intel GPUs** including Intel Data Center GPU Max Series (e.g., PVC) and Intel Arc A-Series (e.g., ARC). Check out the [examples](https://github.com/intel/intel-extension-for-transformers/blob/main/docs/weightonlyquant.md#examples-for-gpu) and [scripts](https://github.com/intel/intel-extension-for-transformers/blob/main/examples/huggingface/pytorch/text-generation/quantization/run_generation_gpu_woq.py).
* [2024/01] Demonstrated **Intel Hybrid Copilot** in **CES 2024 Great Minds** Session "[Bringing the Limitless Potential of AI Everywhere](https://youtu.be/70J3uO3eLZA?t=1348)".
* [2023/12] Supported **QLoRA on CPUs** to make fine-tuning on client CPU possible. Check out the [blog](https://medium.com/@NeuralCompressor/creating-your-own-llms-on-your-laptop-a08cc4f7c91b) and [readme](https://github.com/intel/intel-extension-for-transformers/blob/main/docs/qloracpu.md) for more details.
* [2023/11] Released **top-1 7B-sized LLM** [**NeuralChat-v3-1**](https://huggingface.co/Intel/neural-chat-7b-v3-1) and [DPO dataset](https://huggingface.co/datasets/Intel/orca_dpo_pairs). Check out the [nice video](https://www.youtube.com/watch?v=bWhZ1u_1rlc) published by [WorldofAI](https://www.youtube.com/@intheworldofai).
* [2023/11] Published a **4-bit chatbot demo** (based on NeuralChat) available on [Intel Hugging Face Space](https://huggingface.co/spaces/Intel/NeuralChat-ICX-INT4). Welcome to have a try! To setup the demo locally, please follow the [instructions](https://github.com/intel/intel-extension-for-transformers/blob/main/intel_extension_for_transformers/neural_chat/docs/notebooks/setup_text_chatbot_service_on_spr.ipynb).

---

## 🏃Installation
### Quick Install from Pypi
```bash
pip install intel-extension-for-transformers
```
> For system requirements and other installation tips, please refer to [Installation Guide](./docs/installation.md)

## 🌟Introduction
Intel® Extension for Transformers is an innovative toolkit designed to accelerate GenAI/LLM everywhere with the optimal performance of Transformer-based models on various Intel platforms, including Intel Gaudi2, Intel CPU, and Intel GPU. The toolkit provides the below key features and examples:

*  Seamless user experience of model compressions on Transformer-based models by extending [Hugging Face transformers](https://github.com/huggingface/transformers) APIs and leveraging [Intel® Neural Compressor](https://github.com/intel/neural-compressor)

*  Advanced software optimizations and unique compression-aware runtime (released with NeurIPS 2022's paper [Fast Distilbert on CPUs](https://arxiv.org/abs/2211.07715) and [QuaLA-MiniLM: a Quantized Length Adaptive MiniLM](https://arxiv.org/abs/2210.17114), and NeurIPS 2021's paper [Prune Once for All: Sparse Pre-Trained Language Models](https://arxiv.org/abs/2111.05754))

*  Optimized Transformer-based model packages such as [Stable Diffusion](examples/huggingface/pytorch/text-to-image/deployment/stable_diffusion), [GPT-J-6B](examples/huggingface/pytorch/text-generation/deployment), [GPT-NEOX](examples/huggingface/pytorch/language-modeling/quantization#2-validated-model-list), [BLOOM-176B](examples/huggingface/pytorch/language-modeling/inference#BLOOM-176B), [T5](examples/huggingface/pytorch/summarization/quantization#2-validated-model-list), [Flan-T5](examples/huggingface/pytorch/summarization/quantization#2-validated-model-list), and end-to-end workflows such as [SetFit-based text classification](docs/tutorials/pytorch/text-classification/SetFit_model_compression_AGNews.ipynb) and [document level sentiment analysis (DLSA)](workflows/dlsa)

*  [NeuralChat](intel_extension_for_transformers/neural_chat), a customizable chatbot framework to create your own chatbot within minutes by leveraging a rich set of [plugins](https://github.com/intel/intel-extension-for-transformers/blob/main/intel_extension_for_transformers/neural_chat/docs/advanced_features.md) such as [Knowledge Retrieval](./intel_extension_for_transformers/neural_chat/pipeline/plugins/retrieval/README.md), [Speech Interaction](./intel_extension_for_transformers/neural_chat/pipeline/plugins/audio/README.md), [Query Caching](./intel_extension_for_transformers/neural_chat/pipeline/plugins/caching/README.md), and [Security Guardrail](./intel_extension_for_transformers/neural_chat/pipeline/plugins/security/README.md). This framework supports Intel Gaudi2/CPU/GPU.

*  [Inference](https://github.com/intel/neural-speed/tree/main) of Large Language Model (LLM) in pure C/C++ with weight-only quantization kernels for Intel CPU and Intel GPU (TBD), supporting [GPT-NEOX](https://github.com/intel/neural-speed/tree/main/neural_speed/models/gptneox), [LLAMA](https://github.com/intel/neural-speed/tree/main/neural_speed/models/llama), [MPT](https://github.com/intel/neural-speed/tree/main/neural_speed/models/mpt), [FALCON](https://github.com/intel/neural-speed/tree/main/neural_speed/models/falcon), [BLOOM-7B](https://github.com/intel/neural-speed/tree/main/neural_speed/models/bloom), [OPT](https://github.com/intel/neural-speed/tree/main/neural_speed/models/opt), [ChatGLM2-6B](https://github.com/intel/neural-speed/tree/main/neural_speed/models/chatglm), [GPT-J-6B](https://github.com/intel/neural-speed/tree/main/neural_speed/models/gptj), and [Dolly-v2-3B](https://github.com/intel/neural-speed/tree/main/neural_speed/models/gptneox). Support AMX, VNNI, AVX512F and AVX2 instruction set. We've boosted the performance of Intel CPUs, with a particular focus on the 4th generation Intel Xeon Scalable processor, codenamed [Sapphire Rapids](https://www.intel.com/content/www/us/en/products/docs/processors/xeon-accelerated/4th-gen-xeon-scalable-processors.html).

## 🔓Validated Hardware

			Hardware
			Fine-Tuning
			Inference

			Full
			PEFT
			8-bit
			4-bit

			Intel Gaudi2
			✔
			✔
			WIP (FP8)
			-

			Intel Xeon Scalable Processors
			✔
			✔
			✔ (INT8, FP8)
			✔ (INT4, FP4, NF4)

			Intel Xeon CPU Max Series
			✔
			✔
			✔ (INT8, FP8)
			✔ (INT4, FP4, NF4)

			Intel Data Center GPU Max Series
			WIP
			WIP
			WIP (INT8)
			✔ (INT4)

			Intel Arc A-Series
			-
			-
			WIP (INT8)
			✔ (INT4)

			Intel Core Processors
			-
			✔
			✔ (INT8, FP8)
			✔ (INT4, FP4, NF4)

> In the table above, "-" means not applicable or not started yet.

## 🔓Validated Software

			Software
			Fine-Tuning
			Inference

			Full
			PEFT
			8-bit
			4-bit

			PyTorch
			2.0.1+cpu,
 2.0.1a0 (gpu)
			2.0.1+cpu,
 2.0.1a0 (gpu)
			2.1.0+cpu,
 2.0.1a0 (gpu)
			2.1.0+cpu,
 2.0.1a0 (gpu)

			Intel® Extension for PyTorch
			2.1.0+cpu,
 2.0.110+xpu
			2.1.0+cpu,
 2.0.110+xpu
			2.1.0+cpu,
 2.0.110+xpu
			2.1.0+cpu,
 2.0.110+xpu

			Transformers
			4.35.2(CPU),
 4.31.0 (Intel GPU)
			4.35.2(CPU),
 4.31.0 (Intel GPU)
			4.35.2(CPU),
 4.31.0 (Intel GPU)
			4.35.2(CPU),
 4.31.0 (Intel GPU)

			Synapse AI
			1.13.0
			1.13.0
			1.13.0
			1.13.0

			Gaudi2 driver
			1.13.0-ee32e42
			1.13.0-ee32e42
			1.13.0-ee32e42
			1.13.0-ee32e42

                        intel-level-zero-gpu
                        1.3.26918.50-736~22.04
                        1.3.26918.50-736~22.04
                        1.3.26918.50-736~22.04
                        1.3.26918.50-736~22.04

> Please refer to the detailed requirements in [CPU](intel_extension_for_transformers/neural_chat/requirements_cpu.txt), [Gaudi2](intel_extension_for_transformers/neural_chat/requirements_hpu.txt), [Intel GPU](intel_extension_for_transformers/neural_chat/requirements_xpu.txt).

## 🔓Validated OS
Ubuntu 20.04/22.04, Centos 8.

## 🌱Getting Started

### Chatbot
Below is the sample code to create your chatbot. See more [examples](intel_extension_for_transformers/neural_chat/docs/full_notebooks.md).

#### Serving (OpenAI-compatible RESTful APIs)
NeuralChat provides OpenAI-compatible RESTful APIs for chat, so you can use NeuralChat as a drop-in replacement for OpenAI APIs.
You can start NeuralChat server either using the Shell command or Python code.

```shell
# Shell Command
neuralchat_server start --config_file ./server/config/neuralchat.yaml
```

```python
# Python Code
from intel_extension_for_transformers.neural_chat import NeuralChatServerExecutor
server_executor = NeuralChatServerExecutor()
server_executor(config_file="./server/config/neuralchat.yaml", log_file="./neuralchat.log")
```

NeuralChat service can be accessible through [OpenAI client library](https://github.com/openai/openai-python), `curl` commands, and `requests` library. See more in [NeuralChat](intel_extension_for_transformers/neural_chat/README.md).

#### Offline

```python
from intel_extension_for_transformers.neural_chat import build_chatbot
chatbot = build_chatbot()
response = chatbot.predict("Tell me about Intel Xeon Scalable Processors.")
```

### Transformers-based extension APIs
Below is the sample code to use the extended Transformers APIs. See more [examples](https://github.com/intel/neural-speed/tree/main).

#### INT4 Inference (CPU)
We encourage you to install [NeuralSpeed](https://github.com/intel/neural-speed) to get the latest features (e.g., GGUF support) of LLM low-bit inference on CPUs. You may also want to use v1.3 without NeuralSpeed by following the [document](https://github.com/intel/intel-extension-for-transformers/tree/v1.3/intel_extension_for_transformers/llm/runtime/graph/README.md)

```python
from transformers import AutoTokenizer
from intel_extension_for_transformers.transformers import AutoModelForCausalLM
model_name = "Intel/neural-chat-7b-v3-1"
prompt = "Once upon a time, there existed a little girl,"

tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
inputs = tokenizer(prompt, return_tensors="pt").input_ids

model = AutoModelForCausalLM.from_pretrained(model_name, load_in_4bit=True)
outputs = model.generate(inputs)
```
You can also load GGUF format model from Huggingface, we only support Q4_0/Q5_0/Q8_0 gguf format for now.
```python
from transformers import AutoTokenizer
from intel_extension_for_transformers.transformers import AutoModelForCausalLM

# Specify the GGUF repo on the Hugginface
model_name = "TheBloke/Llama-2-7B-Chat-GGUF"
# Download the the specific gguf model file from the above repo
gguf_file = "llama-2-7b-chat.Q4_0.gguf"
# make sure you are granted to access this model on the Huggingface.
tokenizer_name = "meta-llama/Llama-2-7b-chat-hf"
prompt = "Once upon a time, there existed a little girl,"
tokenizer = AutoTokenizer.from_pretrained(tokenizer_name, trust_remote_code=True)
inputs = tokenizer(prompt, return_tensors="pt").input_ids

model = AutoModelForCausalLM.from_pretrained(model_name, gguf_file = gguf_file)
outputs = model.generate(inputs)
```

You can also load PyTorch Model from Modelscope
>**Note**:require modelscope
```python
from transformers import TextStreamer
from modelscope import AutoTokenizer
from intel_extension_for_transformers.transformers import AutoModelForCausalLM
model_name = "qwen/Qwen-7B"     # Modelscope model_id or local model
prompt = "Once upon a time, there existed a little girl,"

model = AutoModelForCausalLM.from_pretrained(model_name, load_in_4bit=True, model_hub="modelscope")
tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
inputs = tokenizer(prompt, return_tensors="pt").input_ids
streamer = TextStreamer(tokenizer)
outputs = model.generate(inputs, streamer=streamer, max_new_tokens=300)
```

You can also load the low-bit model quantized by GPTQ/AWQ/RTN/AutoRound algorithm.
```python
from transformers import AutoTokenizer
from intel_extension_for_transformers.transformers import AutoModelForCausalLM, GPTQConfig

# Hugging Face GPTQ/AWQ model or use local quantize model
model_name = "MODEL_NAME_OR_PATH"
prompt = "Once upon a time, a little girl"

tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
inputs = tokenizer(prompt, return_tensors="pt").input_ids
model = AutoModelForCausalLM.from_pretrained(model_name, trust_remote_code=True)
outputs = model.generate(inputs)
```

#### INT4 Inference (GPU)
```python
import intel_extension_for_pytorch as ipex
from intel_extension_for_transformers.transformers.modeling import AutoModelForCausalLM
from transformers import AutoTokenizer
import torch

device_map = "xpu"
model_name ="Qwen/Qwen-7B"
tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
prompt = "Once upon a time, there existed a little girl,"
inputs = tokenizer(prompt, return_tensors="pt").input_ids.to(device_map)

model = AutoModelForCausalLM.from_pretrained(model_name, trust_remote_code=True,
                                              device_map=device_map, load_in_4bit=True)

model = ipex.optimize_transformers(model, inplace=True, dtype=torch.float16, quantization_config=True, device=device_map)

output = model.generate(inputs)
```
> Note: Please refer to the [example](https://github.com/intel/intel-extension-for-transformers/blob/main/docs/weightonlyquant.md#examples-for-gpu) and [script](https://github.com/intel/intel-extension-for-transformers/blob/main/examples/huggingface/pytorch/text-generation/quantization/run_generation_gpu_woq.py) for more details.

### Langchain-based extension APIs
Below is the sample code to use the extended Langchain APIs. See more [examples](intel_extension_for_transformers/neural_chat/pipeline/plugins/retrieval/README.md).

```python
from langchain_community.llms.huggingface_pipeline import HuggingFacePipeline
from langchain.chains import RetrievalQA
from langchain_core.vectorstores import VectorStoreRetriever
from intel_extension_for_transformers.langchain.vectorstores import Chroma
retriever = VectorStoreRetriever(vectorstore=Chroma(...))
retrievalQA = RetrievalQA.from_llm(llm=HuggingFacePipeline(...), retriever=retriever)
```

## 🎯Validated  Models
You can access the validated models, accuracy and performance from [Release data](./docs/release_data.md) or [Medium blog](https://medium.com/@NeuralCompressor/llm-performance-of-intel-extension-for-transformers-f7d061556176).

## 📖Documentation

    OVERVIEW

    NeuralChat
    Neural Speed

    NEURALCHAT

    Chatbot on Intel CPU
    Chatbot on Intel GPU
    Chatbot on Gaudi

    Chatbot on Client
    More Notebooks

    NEURAL SPEED

    Neural Speed
    Streaming LLM
    Low Precision Kernels
    Tensor Parallelism

    LLM COMPRESSION

    SmoothQuant (INT8)
    Weight-only Quantization (INT4/FP4/NF4/INT8)
    QLoRA on CPU

    GENERAL COMPRESSION

    Quantization
    Pruning
    Distillation
    Orchestration

    Data Augmentation
    Export
    Metrics
    Objectives

    Pipeline
    Length Adaptive
    Early Exit

    TUTORIALS & RESULTS

    Tutorials
    LLM List
    General Model List
    Model Performance

## 🙌Demo

* LLM Infinite Inference (up to 4M tokens)

https://github.com/intel/intel-extension-for-transformers/assets/109187816/1698dcda-c9ec-4f44-b159-f4e9d67ab15b

* LLM QLoRA on Client CPU

https://github.com/intel/intel-extension-for-transformers/assets/88082706/9d9bdb7e-65db-47bb-bbed-d23b151e8b31

## 📃Selected Publications/Events
* Blog published on Huggingface: [Building Cost-Efficient Enterprise RAG applications with Intel Gaudi 2 and Intel Xeon](https://huggingface.co/blog/cost-efficient-rag-applications-with-intel) (May 2024)
* Blog published on Intel Developer News: [Efficient Natural Language Embedding Models with Intel® Extension for Transformers](https://www.intel.com/content/www/us/en/developer/articles/technical/efficient-natural-language-embedding-models.html) (May 2024)
* Blog published on Techcrunch: [Intel and others commit to building open generative AI tools for the enterprise](https://techcrunch.com/2024/04/16/intel-and-others-commit-to-building-open-generative-ai-tools-for-the-enterprise) (Apr 2024)
* Video on YouTube: [Intel Vision Keynotes 2024](https://www.youtube.com/watch?v=QB7FoIpx8os&t=2280s) (Apr 2024)
* Blog published on Vectara: [Do Smaller Models Hallucinate More?](https://vectara.com/blog/do-smaller-models-hallucinate-more) (Apr 2024)
* Blog of Intel Developer News: [Use the neural-chat-7b Model for Advanced Fraud Detection: An AI-Driven Approach in Cybersecurity](https://www.intel.com/content/www/us/en/developer/articles/technical/bilics-approach-cybersecurity-using-neuralchat-7b.html) (March 2024)
* CES 2024: [CES 2024 Great Minds Keynote: Bringing the Limitless Potential of AI Everywhere: Intel Hybrid Copilot demo](https://youtu.be/70J3uO3eLZA?t=1348) (Jan 2024)
* Blog published on Medium: [Connect an AI agent with your API: Intel Neural-Chat 7b LLM can replace Open AI Function Calling](https://medium.com/11tensors/connect-an-ai-agent-with-your-api-intel-neural-chat-7b-llm-can-replace-open-ai-function-calling-242d771e7c79) (Dec 2023)
* NeurIPS'2023 on Efficient Natural Language and Speech Processing: [Efficient LLM Inference on CPUs](https://arxiv.org/abs/2311.00502) (Nov 2023)
* Blog published on Hugging Face: [Intel Neural-Chat 7b: Fine-Tuning on Gaudi2 for Top LLM Performance](https://huggingface.co/blog/Andyrasika/neural-chat-intel) (Nov 2023)
* Blog published on VMware: [AI without GPUs: A Technical Brief for VMware Private AI with Intel](https://core.vmware.com/resource/ai-without-gpus-technical-brief-vmware-private-ai-intel#section6) (Nov 2023)

> View [Full Publication List](./docs/publication.md)

## Additional Content

* [Release Information](./docs/release.md)
* [Contribution Guidelines](./docs/contributions.md)
* [Legal Information](./docs/legal.md)
* [Security Policy](SECURITY.md)
* [Apache License](./LICENSE)

## Acknowledgements
* Excellent open-source projects: [bitsandbytes](https://github.com/TimDettmers/bitsandbytes), [FastChat](https://github.com/lm-sys/FastChat), [fastRAG](https://github.com/IntelLabs/fastRAG), [ggml](https://github.com/ggerganov/ggml), [gptq](https://github.com/IST-DASLab/gptq), [llama.cpp](https://github.com/ggerganov/llama.cpp), [lm-evauation-harness](https://github.com/EleutherAI/lm-evaluation-harness), [peft](https://github.com/huggingface/peft), [trl](https://github.com/huggingface/trl), [streamingllm](https://github.com/mit-han-lab/streaming-llm) and many others.

* Thanks to all the [contributors](./docs/contributors.md).

## 💁Collaborations

Welcome to raise any interesting ideas on model compression techniques and LLM-based chatbot development! Feel free to reach [us](mailto:itrex.maintainers@intel.com), and we look forward to our collaborations on Intel Extension for Transformers!


# The pokemon showdown Python environment

[![PyPI version fury.io](https://badge.fury.io/py/poke-env.svg)](https://pypi.python.org/pypi/poke-env/)
[![PyPI pyversions](https://img.shields.io/pypi/pyversions/poke-env.svg)](https://pypi.python.org/pypi/poke-env/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation Status](https://readthedocs.org/projects/poke-env/badge/?version=stable)](https://poke-env.readthedocs.io/en/stable/?badge=stable)
[![codecov](https://codecov.io/gh/hsahovic/poke-env/branch/master/graph/badge.svg)](https://codecov.io/gh/hsahovic/poke-env)

A Python interface to create battling pokemon agents. `poke-env` offers an easy-to-use interface for creating rule-based or training Reinforcement Learning bots to battle on [pokemon showdown](https://pokemonshowdown.com/).

![A simple agent in action](rl-gif.gif)

## Getting started

Agents are instance of python classes inheriting from `Player`. Here is what your first agent could look like:

```python
class YourFirstAgent(Player):
    def choose_move(self, battle):
        for move in battle.available_moves:
            if move.base_power > 90:
                # A powerful move! Let's use it
                return self.create_order(move)

        # No available move? Let's switch then!
        for switch in battle.available_switches:
            if switch.current_hp_fraction > battle.active_pokemon.current_hp_fraction:
                # This other pokemon has more HP left... Let's switch it in?
                return self.create_order(switch)

        # Not sure what to do?
        return self.choose_random_move(battle)
```

To get started, take a look at [our documentation](https://poke-env.readthedocs.io/en/stable/)!

## Documentation and examples

Documentation, detailed examples and starting code can be found [on readthedocs](https://poke-env.readthedocs.io/en/stable/).

## Installation

This project requires python >= 3.8 and a [Pokemon Showdown](https://github.com/Zarel/Pokemon-Showdown) server.

```
pip install poke-env
```

You can use [smogon's server](https://play.pokemonshowdown.com/) to try out your agents against humans, but having a development server is strongly recommended. In particular, it is recommended to use the `--no-security` flag to run a local server with most rate limiting and throttling turned off. Please refer to [the docs](https://poke-env.readthedocs.io/en/stable/getting_started.html#configuring-a-showdown-server) for detailed setup instructions.

```
git clone https://github.com/smogon/pokemon-showdown.git
cd pokemon-showdown
npm install
cp config/config-example.js config/config.js
node pokemon-showdown start --no-security
```

## Development version

You can also clone the latest master version with:

```
git clone https://github.com/hsahovic/poke-env.git
```

Dependencies and development dependencies can then be installed with:

```
pip install -r requirements.txt
pip install -r requirements-dev.txt
```

## Acknowledgements

This project is a follow-up of a group project from an artifical intelligence class at [Ecole Polytechnique](https://www.polytechnique.edu/).

You can find the original repository [here](https://github.com/hsahovic/inf581-project). It is partially inspired by the [showdown-battle-bot project](https://github.com/Synedh/showdown-battle-bot). Of course, none of these would have been possible without [Pokemon Showdown](https://github.com/Zarel/Pokemon-Showdown).

Team data comes from [Smogon forums' RMT section](https://www.smogon.com/).

## Data

Data files are adapted version of the `js` data files of [Pokemon Showdown](https://github.com/Zarel/Pokemon-Showdown).

## License
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Citing `poke-env`

```bibtex
@misc{poke_env,
    author       = {Haris Sahovic},
    title        = {Poke-env: pokemon AI in python},
    url          = {https://github.com/hsahovic/poke-env}
}
```


# suncasa

[![pypi](https://img.shields.io/pypi/v/suncasa.svg)](https://pypi.python.org/pypi/suncasa/)

[suncasa](https://github.com/suncasa/suncasa-src) is a Python wrapper around [CASA](https://casa.nrao.edu/) for
importing, calibrating, synthesis imaging and visualizing solar spectral imaging data. CASA is one of the leading
software tools for "supporting the data post-processing needs of the next generation of radio astronomical telescopes
such as ALMA and VLA, an international effort led by
the [National Radio Astronomy Observatory (NRAO)](https://public.nrao.edu/). The current version of CASA uses Python 3.6
to 3.8 on most of the platforms. More information about the compatibility of CASA can be found
on [CASA Compatibility](https://casadocs.readthedocs.io/en/latest/notebooks/introduction.html#Compatibility/).
> **_NOTE:_** CASA is available ONLY on unix-based platforms, and therefore, so as for suncasa. CASA software is compatible with multiple LINUX and Mac computer operating systems, as well as multiple versions of Python. Please refer to the [Compatibility Matrix](https://casadocs.readthedocs.io/en/latest/notebooks/introduction.html#Compatibility) for detailed information on the Operating Systems and Python versions expected to work with current and future versions of CASA.

> **_NOTE:_**  If you're using Windows, you'll need to install a virtual machine running a Linux system. For detailed instructions, please refer to this [guidance](https://docs.google.com/document/d/1DuRoVSVEwHOSIntbYYecXYxC8_pKt-oJ2UK_Q5Ye-vE/edit?usp=sharing).

In principle, suncasa an casa can be installed easily using [pip](https://pypi.org/project/suncasa/), assuming the right
python version is in use. However, YMMV if your do not have prerequisite environment configured.The followinig tutorial
demonstrates the installation of **suncasa** in **python 3.8** environment on **MacOS 12** and **Ubuntu 18.04.6 LTS**.

Full installation instructions of the standalone CASA package (as a Linux (.tar) or Mac (.dmg) files) including the
build-in Python environment are available from NRAO [Downloads](http://casa.nrao.edu/casa_obtaining.shtml)
page ([http://casa.nrao.edu/casa_obtaining.shtml](http://casa.nrao.edu/casa_obtaining.shtml))

The CASA 6.x series is also available as modular packages, giving users the flexibility to build CASA tools and tasks in
their own Python environment. This includes the casatools, casatasks, and casampi modules, allowing for core data
processing capabilities in parallel.

**If you want to use full funtionalities provided by the standalone CASA, please go through all steps.**

**If you just want to install SUNCASA with the modular CASA option in the usual "Pythonic" manner, after Step 1 (Python
installation), you can skip Step 2 and go directly to Step 3.**

## Step 1: Python 3.8 Installation[](#installation)

(Adapted from [this tutorial](https://casadocs.readthedocs.io/en/latest/notebooks/introduction.html#id1))

### Prerequisite OS Libraries[](#Prerequisite-OS-Libraries)

CASA requires certain libraries be installed in the users operating system. Some may already be present by default. In
case they are not, the following list should be checked before using CASA or if errors are encountered at runtime.
Commands and package names are for Red Hat Linux, but equivalents can be found for other Linux distributions.

**On Linux:**

A system administrator may be required to install OS libraries. One can
use [yum](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/system_administrators_guide/ch-yum) (
RHEL) or [apt-get](https://help.ubuntu.com/community/AptGet/Howto) (Ubuntu) to install the missing libraries. For
example, for RHEL8 the following OS libraries should be installed:

```bash
sudo yum install libgfortran3
sudo yum install ImageMagick*
sudo yum install xorg-x11-server-Xvfb
sudo yum install compat-libgfortran-48
sudo yum install libnsl
sudo yum install libcanberra-gtk2
```

For modular CASA, one must supply their own Python environment. There are many, including ipython and Jupyter, here is a
basic example for
RHEL8 ([yum](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/system_administrators_guide/ch-yum))
and Ubuntu ([apt-get](https://help.ubuntu.com/community/AptGet/Howto)), respectively.

```bash
sudo yum install python38-devel
```

```bash
sudo apt install python3.8 python3.8-venv python3-venv
```

**On Macintosh:**

Install [XQuartz](https://www.xquartz.org/)
and [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12).

[comment]: <> (gcc ([brew](https://brew.sh/) install),)

Same as for Linux, one must supply their own Python environment for modular CASA. Here is an example for MacOS to
install python 3.8 using PyEnv.

Clone pyenv to a local directory (e.g., `$HOME/.pyenv`):

```bash
git clone https://github.com/pyenv/pyenv.git $HOME/.pyenv
```

Set up your shell environment for Pyenv. Assuming you are using **bash**, add the configuration commands to `~/.bashrc`
by running the following in your terminal:

~~~bash
bash
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
~~~

Install the Python 3.8.

```bash
pyenv install 3.8.16
```

> **_Troubleshooting:_** If you encounter an error that "C compiler cannot create executables" then the simplest way to solve this is to reinstall Apple's [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12). Xcode is a tool created by Apple that includes all the C libraries and other tools that Python uses when it runs on MacOS. Xcode is a whopping 11 gigabytes, but you'll want to be up-to-date. You may want to run this while you're sleeping. Once it is done, just re-run the above `pyenv install 3.8.16` and it should now work.

Now you can set this version of Python to be the **current** version of Python MacOS uses. This setting is temporary.

```bash
pyenv global 3.8.16
```

If you want to set this version of Python to the the **default** version of Python, add the configuration command
to `~/.bashrc`.

```bash
echo 'pyenv global 3.8.16' >> ~/.bashrc
```

### Step 2: CASA (Standalone Monolithic Distribution) Installation [](#Monolithic-CASA-Distribution)

Download the standalone CASA package (as a Linux (.tar) or Mac (.dmg) files) including the build-in Python environment
following
[http://casa.nrao.edu/casa_obtaining.shtml](http://casa.nrao.edu/casa_obtaining.shtml).

**On Linux:**

1. Download the .tar file and place it in a work directory (e.g. `$HOME/casa`).

2. From a Linux terminal window:
   ~~~ bash
   tar -xvf casa-xyz.tar.xz
   $HOME/casa/casa-xyz/bin/casa
   ~~~
3. Add casa to environment `PATH`. Assuming you are using *bash*, add the configuration commands to `~/.bashrc` by
   running the following in your terminal:

   ~~~ bash
   echo 'export CASAROOT="$HOME/casa/casa-xyz/"' >> ~/.bashrc
   echo 'export PATH="$PATH:$CASAROOT/bin"' >> ~/.bashrc
   ~~~

4. Restart your shell for the `PATH` changes to take effect.

  ```sh
  exec "$SHELL"
  ```

You can now start casa.

  ```sh
  casa
  ```

The one caveat is that CASA on Linux currently will not run if the Security-Enhanced Linux option of the linux operating
system is set to enforcing. For the non-root install to work, SElinux must be set to disabled or permissive (in _
/etc/selinux/config_) or you must run (as root): `$: setsebool -P allow_execheap=1`. Otherwise, you will encounter
errors like:

error while loading shared libraries: /opt/casa/casa-20.0.5653-001/lib/liblapack.so.3.1.1: cannot restore segment prot
after reloc: Permission denied_

> **_WARNING:_** By default, python 3.6 (and earlier versions of python 3) include the current working directory in the python path at startup. Any script in that directory with the same name as a standard python module or a CASA module will be detected and used by python instead of the code that is delivered with CASA. Protections have been included for files called “new.py” and “pickle.py”, but other scripts may cause problems with the CASA startup. For example, do not include a file named runpy.py in the working directory.

**On Macintosh:**

1. Download the .dmg disk image file

2. Double click on the disk image file (if your browser does not automatically open it).

3. Drag the CASA application to the _Applications_ folder of your hard disk.

4. Eject the CASA disk image.

5. Double click the CASA application to run it for the first time. If the OS does not allow you to install apps from
   non-Apple sources, please Change the settings in “System Preferences-> Security & Privacy -> General” and “Allow
   applications downloaded from: Mac App store and identified developers”.

6. Optional: Create symbolic links to the CASA version and its executables (Administrator privileges are required),
   which will allow you to run `casa`, `casaviewer`, `casaplotms`, etc. from any terminal command line. To do so, run

```console
 !create-symlinks
```

### Step 3: Install SUNCASA (along with CASA modular version) [](#Modular-Packages)

Pip wheels for casatools, casatasks, as well as suncasa are available as Python 3 modules. This allows simple
installation and import into standard Python environments. Make sure you have set up your machine with the _necessary
prerequisite libraries_ first. Then a separate installation of desired modules (from a unix terminal window) as follows.
First create a Python virtual environment named `suncasaenv` under the `$HOME` directory:

```bash
cd $HOME
python3.8 -m venv suncasaenv
```

> **_NOTE:_**  We strongly recommend using a Python virtual environment to prevent breaking any packages within a pre-existing Python environment.

Then use [pip](https://pypi.org/project/suncasa/) to install suncasa within the newly-created virtual environment:

```bash
source suncasaenv/bin/activate
pip install --upgrade pip
pip install suncasa
```

> **_NOTE:_**  If this does not work, it could be due to unsuccessful installation of some dependencies. Running these commands should address this.

```bash
pip install casatasks
pip install casatools
pip install casadata
pip install PyQt5
pip install sunpy[all]
pip install suncasa
```

To exit the python venv, type `deactivate` from the terminal. However, the rest of this tutorial **assumes the venv is
active** (to reactivate, type `source $HOME/suncasaenv/bin/activate`)

You can update suncasa to its latest version by running:

```bash
pip install --upgrade suncasa
```

**Sanity check**

With the pip installation, suncasa as well as CASA may be used in a standard Pythonic manner. For example, suncasa
modules and CASA tasks can be invoked using “import”, while CASA tools first need to be instantiated:

```console
(suncasaenv) $ ipython
In [1]: import suncasa
In [2]: help(suncasa)
In [3]: import casatasks
In [4]: help(casatasks)
```

The use of python3 venv is a simple built-in method of containerizing the pip install such that multiple versions of
suncasa can be kept on a single machine in different environments. In addition, suncasa is built and tested using
standard python 3.8 libraries (backward compatible) which can be replicated with a fresh venv, keeping the libraries
needed for suncasa isolated from other libraries which may already be installed on your machine.

**Add EOVSA to CASA observatories list**

The following command creates a configuration file to define the EOVSA instrument so that CASA is aware of it. We plan
to add EOVSA officially to the CASA distribution in the future, after which this step is unnecessary.

```bash
printf "import sys \nimport os \nimport sysconfig \nimport casatools \nimport casadata \nimport time \nlogfile='casalog-{}.log'.format(time.strftime('%%Y%%m%%d-%%H',time.localtime())) \ntelemetry_enabled = False \ncrashreporter_enabled = True \ntb=casatools.table() \nospathsep = os.path.sep \nlibpath = sysconfig.get_paths()['purelib'] \nobsdict = {'MJD': 57447.0, 'Name': 'EOVSA', 'Type': 'WGS84', 'Long': -118.287, \n            'Lat': 37.2332, 'Height': 1207.13, 'X': 0.0, 'Y': 0.0, 'Z': 0.0,  \n            'Source': 'Dale Gary'} \nobstable = os.path.join(casadata.datapath,'geodetic','Observatories') \ntb.open(obstable, nomodify=True) \nif 'EOVSA' not in tb.getcol('Name'): \n    print('Adding EOVSA to the Observatories') \n    tb.close() \n    tb.open(obstable, nomodify=False) \n    nrows = tb.nrows() \n    tb.addrows(1) \n    for k in obsdict.keys(): \n        tb.putcell(k, nrows, obsdict[k])     \ntb.close() \n" > $HOME/.casa/config.py
```

***Last but not least, add the `site-packages` path where the suncasa and its dependent packages installedd to the
Monolithic CASA***

```bash
echo "sitepackagepath = '$HOME/suncasaenv/lib/python3.8/site-packages'" >> $HOME/.casa/config.py
echo "if sitepackagepath not in sys.path:" >> $HOME/.casa/config.py
echo "    sys.path.append(sitepackagepath)"     >> $HOME/.casa/config.py
```

> **_note:_** The `sitepackagepath` may varies for python versions on different platforms.

**Note for Mac M1 users**: For macOS 12 on an ARM-based M1 chip, users will need to install the wheels of CASA version
11 for intel architecture. For that, we recommend to install [Apple Rosetta](https://support.apple.com/en-us/HT211861) to enable a Mac with Apple silicon to use
apps made for an Intel processor ([How-to](https://medium.com/mkdir-awesome/how-to-install-x86-64-homebrew-packages-on-apple-m1-macbook-54ba295230f)).

By now you can use the following command to pip install the CASA wheels:

```bash
arch -x86_64 python3.8 -m pip install ...
```


[![codecov](https://codecov.io/gh/JaxGaussianProcesses/GPJax/branch/master/graph/badge.svg?token=DM1DRDASU2)](https://codecov.io/gh/JaxGaussianProcesses/GPJax)
[![CodeFactor](https://www.codefactor.io/repository/github/jaxgaussianprocesses/gpjax/badge)](https://www.codefactor.io/repository/github/jaxgaussianprocesses/gpjax)
[![Netlify Status](https://api.netlify.com/api/v1/badges/d3950e6f-321f-4508-9e52-426b5dae2715/deploy-status)](https://app.netlify.com/sites/endearing-crepe-c2d5fe/deploys)
[![PyPI version](https://badge.fury.io/py/GPJax.svg)](https://badge.fury.io/py/GPJax)
[![DOI](https://joss.theoj.org/papers/10.21105/joss.04455/status.svg)](https://doi.org/10.21105/joss.04455)
[![Downloads](https://pepy.tech/badge/gpjax)](https://pepy.tech/project/gpjax)
[![Slack Invite](https://img.shields.io/badge/Slack_Invite--blue?style=social&logo=slack)](https://join.slack.com/t/gpjax/shared_invite/zt-1da57pmjn-rdBCVg9kApirEEn2E5Q2Zw)

[**Quickstart**](#simple-example)
| [**Install guide**](#installation)
| [**Documentation**](https://docs.jaxgaussianprocesses.com/)
| [**Slack Community**](https://join.slack.com/t/gpjax/shared_invite/zt-1da57pmjn-rdBCVg9kApirEEn2E5Q2Zw)

GPJax aims to provide a low-level interface to Gaussian process (GP) models in
[Jax](https://github.com/google/jax), structured to give researchers maximum
flexibility in extending the code to suit their own needs. The idea is that the
code should be as close as possible to the maths we write on paper when working
with GP models.

# Package organisation

## Contributions

We would be delighted to receive contributions from interested individuals and
groups. To learn how you can get involved, please read our [guide for
contributing](https://github.com/JaxGaussianProcesses/GPJax/blob/main/docs/contributing.md).
If you have any questions, we encourage you to [open an
issue](https://github.com/JaxGaussianProcesses/GPJax/issues/new/choose). For
broader conversations, such as best GP fitting practices or questions about the
mathematics of GPs, we invite you to [open a
discussion](https://github.com/JaxGaussianProcesses/GPJax/discussions).

Another way you can contribute to GPJax is through [issue
triaging](https://www.codetriage.com/what).  This can include reproducing bug reports,
asking for vital information such as version numbers and reproduction instructions, or
identifying stale issues. If you would like to begin triaging issues, an easy way to get
started is to
[subscribe to GPJax on CodeTriage](https://www.codetriage.com/jaxgaussianprocesses/gpjax).

As a contributor to GPJax, you are expected to abide by our [code of
conduct](docs/CODE_OF_CONDUCT.md). If you feel that you have either experienced or
witnessed behaviour that violates this standard, then we ask that you report any such
behaviours through [this form](https://jaxgaussianprocesses.com/contact/) or reach out to
one of the project's [_gardeners_](https://docs.jaxgaussianprocesses.com/GOVERNANCE/#roles).

Feel free to join our [Slack
Channel](https://join.slack.com/t/gpjax/shared_invite/zt-1da57pmjn-rdBCVg9kApirEEn2E5Q2Zw),
where we can discuss the development of GPJax and broader support for Gaussian
process modelling.

## Governance

GPJax was founded by [Thomas Pinder](https://github.com/thomaspinder). Today, the
project's gardeners are [daniel-dodd@](https://github.com/daniel-dodd),
[henrymoss@](https://github.com/henrymoss), [st--@](https://github.com/st--), and
[thomaspinder@](https://github.com/thomaspinder), listed in alphabetical order. The full
governance structure of GPJax is detailed [here](docs/GOVERNANCE.md). We appreciate all
[the contributors to
GPJax](https://github.com/JaxGaussianProcesses/GPJax/graphs/contributors) who have
helped to shape GPJax into the package it is today.

# Supported methods and interfaces

## Notebook examples

> - [**Conjugate Inference**](https://docs.jaxgaussianprocesses.com/examples/regression/)
> - [**Classification with MCMC**](https://docs.jaxgaussianprocesses.com/examples/classification/)
> - [**Sparse Variational Inference**](https://docs.jaxgaussianprocesses.com/examples/collapsed_vi/)
> - [**Stochastic Variational Inference**](https://docs.jaxgaussianprocesses.com/examples/uncollapsed_vi/)
> - [**BlackJax Integration**](https://docs.jaxgaussianprocesses.com/examples/classification/#mcmc-inference)
> - [**Laplace Approximation**](https://docs.jaxgaussianprocesses.com/examples/classification/#laplace-approximation)
> - [**Inference on Non-Euclidean Spaces**](https://docs.jaxgaussianprocesses.com/examples/constructing_new_kernels/#custom-kernel)
> - [**Inference on Graphs**](https://docs.jaxgaussianprocesses.com/examples/graph_kernels/)
> - [**Pathwise Sampling**](https://docs.jaxgaussianprocesses.com/examples/spatial/)
> - [**Learning Gaussian Process Barycentres**](https://docs.jaxgaussianprocesses.com/examples/barycentres/)
> - [**Deep Kernel Regression**](https://docs.jaxgaussianprocesses.com/examples/deep_kernels/)
> - [**Poisson Regression**](https://docs.jaxgaussianprocesses.com/examples/poisson/)
> - [**Bayesian Optimisation**](https://docs.jaxgaussianprocesses.com/examples/bayesian_optimisation/)

## Guides for customisation
>
> - [**Custom kernels**](https://docs.jaxgaussianprocesses.com/examples/constructing_new_kernels/#custom-kernel)
> - [**UCI regression**](https://docs.jaxgaussianprocesses.com/examples/yacht/)

## Conversion between `.ipynb` and `.py`
Above examples are stored in [examples](docs/examples) directory in the double
percent (`py:percent`) format. Checkout [jupytext
using-cli](https://jupytext.readthedocs.io/en/latest/using-cli.html) for more
info.

* To convert `example.py` to `example.ipynb`, run:

```bash
jupytext --to notebook example.py
```

* To convert `example.ipynb` to `example.py`, run:

```bash
jupytext --to py:percent example.ipynb
```

# Simple example

Let us import some dependencies and simulate a toy dataset $\mathcal{D}$.

```python
from jax import config

config.update("jax_enable_x64", True)

import gpjax as gpx
from jax import grad, jit
import jax.numpy as jnp
import jax.random as jr
import optax as ox

key = jr.key(123)

f = lambda x: 10 * jnp.sin(x)

n = 50
x = jr.uniform(key=key, minval=-3.0, maxval=3.0, shape=(n,1)).sort()
y = f(x) + jr.normal(key, shape=(n,1))
D = gpx.Dataset(X=x, y=y)

# Construct the prior
meanf = gpx.mean_functions.Zero()
kernel = gpx.kernels.RBF()
prior = gpx.gps.Prior(mean_function=meanf, kernel = kernel)

# Define a likelihood
likelihood = gpx.likelihoods.Gaussian(num_datapoints = n)

# Construct the posterior
posterior = prior * likelihood

# Define an optimiser
optimiser = ox.adam(learning_rate=1e-2)

# Define the marginal log-likelihood
negative_mll = jit(gpx.objectives.ConjugateMLL(negative=True))

# Obtain Type 2 MLEs of the hyperparameters
opt_posterior, history = gpx.fit(
    model=posterior,
    objective=negative_mll,
    train_data=D,
    optim=optimiser,
    num_iters=500,
    safe=True,
    key=key,
)

# Infer the predictive posterior distribution
xtest = jnp.linspace(-3., 3., 100).reshape(-1, 1)
latent_dist = opt_posterior(xtest, D)
predictive_dist = opt_posterior.likelihood(latent_dist)

# Obtain the predictive mean and standard deviation
pred_mean = predictive_dist.mean()
pred_std = predictive_dist.stddev()
```

# Installation

## Stable version

The latest stable version of GPJax can be installed via
pip:

```bash
pip install gpjax
```

> **Note**
>
> We recommend you check your installation version:
> ```python
> python -c 'import gpjax; print(gpjax.__version__)'
> ```

## Development version
> **Warning**
>
> This version is possibly unstable and may contain bugs.

> **Note**
>
> We advise you create virtual environment before installing:
> ```
> conda create -n gpjax_experimental python=3.10.0
> conda activate gpjax_experimental
>  ```

Clone a copy of the repository to your local machine and run the setup
configuration in development mode.
```bash
git clone https://github.com/JaxGaussianProcesses/GPJax.git
cd GPJax
poetry install
```

> We recommend you check your installation passes the supplied unit tests:
>
> ```python
> poetry run pytest
> ```

# Citing GPJax

If you use GPJax in your research, please cite our [JOSS paper](https://joss.theoj.org/papers/10.21105/joss.04455#).

```
@article{Pinder2022,
  doi = {10.21105/joss.04455},
  url = {https://doi.org/10.21105/joss.04455},
  year = {2022},
  publisher = {The Open Journal},
  volume = {7},
  number = {75},
  pages = {4455},
  author = {Thomas Pinder and Daniel Dodd},
  title = {GPJax: A Gaussian Process Framework in JAX},
  journal = {Journal of Open Source Software}
}
```


![Test Back End](https://github.com/3cn-ecn/nantralPlatform/actions/workflows/quality.yml/badge.svg)
[![Deploy Server](https://github.com/3cn-ecn/nantralPlatform/actions/workflows/deploy-server.yml/badge.svg?branch=master)](https://nantral-platform.fr)
[![Deploy Staging](https://github.com/3cn-ecn/nantralPlatform/actions/workflows/deploy-staging.yml/badge.svg?branch=staging)](https://dev.nantral-platform.fr)
[![Deploy Docs](https://github.com/3cn-ecn/nantralPlatform/actions/workflows/deploy-docs.yml/badge.svg?branch=master)](https://docs.nantral-platform.fr)

# Nantral Platform

- Nantral Platform Website: [nantral-platform.fr](https://nantral-platform.fr)
- Documentation: [docs.nantral-platform.fr](https://docs.nantral-platform.fr)

## Get started

- Requirements: `python3`, `pipenv` (be sure its in your PATH!), and `node`
- Setup everything the first time:
  ```
  make install
  ```
- Update your local codebase with last changes:
  ```
  git pull
  make update
  ```
- Start the back end server:
  ```
  cd backend && pipenv run start
  ```
- Start the front end server (in another terminal):
  ```
  cd frontend && npm run start
  ```

## Create a local account

- Access the login page on [http://localhost:8000](http://localhost:8000) and
  create your account.
- Access the administration panel at
  [http://localhost:8000/admin](http://localhost:8000/admin) with the default
  login `admin/admin` and grant yourself admin rights (tick the 3 checkboxes).
- Log out from the administration panel, go back to the website and log in with
  your personal account.

> Warning: the admin account is not usable for the website (only for the
> administration panel), you have to create a local account to use the website.

> Debugging: if you can't connect to the admin account, change its password
> with `pipenv run django changepassword admin`

## Contribute

- [Create a [TICKET] issue](https://github.com/3cn-ecn/nantralPlatform/issues) to describe what you want to do. Assign yourself to the issue if you want to work on it.
- Create a new branch linked to the issue and then create a Pull Request.
- Test your code:
  - All-in-one command:
    ```bash
    make test
    ```
  - in the backend:
    ```bash
    pipenv run lint  # use lint:fix to fix errors
    pipenv run test
    ```
  - in the frontend:
    ```bash
    npm run types
    npm run lint  # use lint:fix to fix errors
    npm run jest  # use jest:u to update snapshots
    ```
    _Run these 3 commands at once: `npm run test`_


[![License](https://img.shields.io/pypi/l/morph-kgc.svg)](https://github.com/morph-kgc/morph-kgc/blob/main/LICENSE)
[![DOI](https://zenodo.org/badge/311956260.svg?style=flat)](https://zenodo.org/badge/latestdoi/311956260)
[![Latest PyPI version](https://img.shields.io/pypi/v/morph-kgc?style=flat)](https://pypi.python.org/pypi/morph-kgc)
[![Python Version](https://img.shields.io/pypi/pyversions/morph-kgc.svg)](https://pypi.python.org/pypi/morph-kgc)
[![PyPI status](https://img.shields.io:/pypi/status/morph-kgc?)](https://pypi.python.org/pypi/morph-kgc)
[![build](https://github.com/morph-kgc/morph-kgc/actions/workflows/ci.yml/badge.svg)](https://github.com/morph-kgc/morph-kgc/actions/workflows/ci.yml)
[![Documentation Status](https://readthedocs.org/projects/morph-kgc/badge/?version=latest)](https://morph-kgc.readthedocs.io/en/stable/?badge=latest)
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1ByFx_NOEfTZeaJ1Wtw3UwTH3H3-Sye2O?usp=sharing)

**Morph-KGC** is an engine that constructs **[RDF](https://www.w3.org/TR/rdf11-concepts/)** knowledge graphs from heterogeneous data sources with the **[R2RML](https://www.w3.org/TR/r2rml/)** and **[RML](https://w3id.org/rml/core/spec)** mapping languages. Morph-KGC is built on top of [pandas](https://pandas.pydata.org/) and it leverages *mapping partitions* to significantly reduce execution times and memory consumption for large data sources.

## Features :sparkles:

- Supports the **[R2RML](https://www.w3.org/TR/r2rml/)** and **[RML](https://w3id.org/rml/core/spec)** mapping languages.
- User-friendly mappings with **[YARRRML](https://rml.io/yarrrml/spec/)**.
- Transformation functions with **[RML-FNML](https://w3id.org/rml/fnml/spec)**, including **Python user-defined functions**.
- [RDF-star](https://w3c.github.io/rdf-star/cg-spec/2021-12-17.html) generation with **[RML-star](https://w3id.org/rml/star/spec)**.
- **[RML views](https://2023.eswc-conferences.org/wp-content/uploads/2023/05/paper_Arenas-Guerrero_2023_Boosting.pdf)** over tabular data sources and [JSON](https://www.json.org) files.
- Integration with **[RDFLib](https://rdflib.readthedocs.io)**, **[Oxigraph](https://pyoxigraph.readthedocs.io/en)** and [Kafka](https://kafka-python.readthedocs.io).
- **Optimized** to materialize large knowledge graphs.
- **Remote** data and mapping files.
- Input data formats:
    - **Relational databases**: [MySQL](https://www.mysql.com/), [PostgreSQL](https://www.postgresql.org/), [Oracle](https://www.oracle.com/database/), [Microsoft SQL Server](https://www.microsoft.com/sql-server), [MariaDB](https://mariadb.org/), [SQLite](https://www.sqlite.org).
    - **Tabular files**: [CSV](https://en.wikipedia.org/wiki/Comma-separated_values), [TSV](https://en.wikipedia.org/wiki/Tab-separated_values), [Excel](https://www.microsoft.com/en-us/microsoft-365/excel), [Parquet](https://parquet.apache.org/documentation), [Feather](https://arrow.apache.org/docs/python/feather.html), [ORC](https://orc.apache.org/), [Stata](https://www.stata.com/), [SAS](https://www.sas.com), [SPSS](https://www.ibm.com/analytics/spss-statistics-software), [ODS](https://en.wikipedia.org/wiki/OpenDocument).
    - **Hierarchical files**: [JSON](https://www.json.org), [XML](https://www.w3.org/TR/xml/).
    - **In-memory data structures**: [Python Dictionaries](https://docs.python.org/3/tutorial/datastructures.html#dictionaries), [DataFrames](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html).
    - **Cloud data lake solutions**: [Databricks](https://www.databricks.com/).
    - **Property graph databases**: [Neo4j](https://neo4j.com/), [Kùzu](https://kuzudb.com).

## Documentation :bookmark_tabs:

**[Read the documentation](https://morph-kgc.readthedocs.io/en/stable/documentation/)**.

## Tutorial :woman_teacher:

Learn quickly with the tutorial in **[Google Colaboratory](https://colab.research.google.com/drive/1ByFx_NOEfTZeaJ1Wtw3UwTH3H3-Sye2O?usp=sharing)**!

## Getting Started :rocket:

**[PyPi](https://pypi.org/project/morph-kgc/)** is the fastest way to install Morph-KGC:
```bash
pip install morph-kgc
```

We recommend to use [virtual environments](https://docs.python.org/3/library/venv.html#) to install Morph-KGC.

To run the engine via **command line** you just need to execute the following:
```bash
python3 -m morph_kgc config.ini
```

Check the **[documentation](https://morph-kgc.readthedocs.io/endocumentation/#configuration)** to see how to generate the configuration **INI file**. **[Here](https://github.com/morph-kgc/morph-kgc/blob/main/examples/configuration-file/default_config.ini)** you can also see an example INI file.

It is also possible to run Morph-KGC as a **library** with **[RDFLib](https://rdflib.readthedocs.io)** and **[Oxigraph](https://pyoxigraph.readthedocs.io/en)**:
```python
import morph_kgc

# generate the triples and load them to an RDFLib graph
g_rdflib = morph_kgc.materialize('/path/to/config.ini')
# work with the RDFLib graph
q_res = g_rdflib.query('SELECT DISTINCT ?classes WHERE { ?s a ?classes }')

# generate the triples and load them to Oxigraph
g_oxigraph = morph_kgc.materialize_oxigraph('/path/to/config.ini')
# work with Oxigraph
q_res = g_oxigraph.query('SELECT DISTINCT ?classes WHERE { ?s a ?classes }')

# the methods above also accept the config as a string
config = """
            [DataSource1]
            mappings: /path/to/mapping/mapping_file.rml.ttl
            db_url: mysql+pymysql://user:password@localhost:3306/db_name
         """
g_rdflib = morph_kgc.materialize(config)
```

## License :unlock:

Morph-KGC is available under the **[Apache License 2.0](https://github.com/morph-kgc/morph-kgc/blob/main/LICENSE)**.

## Author & Contact :mailbox_with_mail:

- **[Julián Arenas-Guerrero](https://github.com/arenas-guerrero-julian/) - [julian.arenas.guerrero@upm.es](mailto:julian.arenas.guerrero@upm.es)**

*[Ontology Engineering Group](https://oeg.fi.upm.es)*, *[Universidad Politécnica de Madrid](https://www.upm.es/internacional)*.

## Citing :speech_balloon:

If you used Morph-KGC in your work, please cite the **[SWJ paper](https://www.doi.org/10.3233/SW-223135)**:

```bib
@article{arenas2024morph,
  title     = {{Morph-KGC: Scalable knowledge graph materialization with mapping partitions}},
  author    = {Arenas-Guerrero, Julián and Chaves-Fraga, David and Toledo, Jhon and Pérez, María S. and Corcho, Oscar},
  journal   = {Semantic Web},
  publisher = {IOS Press},
  issn      = {2210-4968},
  year      = {2024},
  doi       = {10.3233/SW-223135},
  volume    = {15},
  number    = {1},
  pages     = {1-20}
}
```

## Sponsor :shield:


# QURI Parts

QURI Parts is an open source library suite for creating and executing quantum algorithms on various quantum computers and simulators. QURI Parts focuses on the followings:

- **Modularity and extensibility**: It provides small parts with which you can assemble your own algorithms. You can also use ready-made algorithms, customizing their details by replacing sub components easily.
- **Platform independence**: Once you assemble an algorithm with QURI Parts, you can execute it on various quantum computers or simulators without modifying the main algorithm code. Typically you only need to replace a few lines to switch to a different device or simulator.
- **Performance**: When dealing with a simulator, it is often the case that classical computation before and after quantum circuit simulation (such as data preparation and post processing) takes considerable time, spoiling performance of the simulator. We put an emphasis on computational performance and try to get the most out of simulators.

## Covered areas and components

Current QURI Parts covers the following areas, provided as individual components.
Please note that more components will be added in future.
You are also encouraged to propose or author new components as necessary.

- Core components
  - `quri-parts-circuit`: Quantum circuit
      - Gate, circuit, noise etc.
  - `quri-parts-core`: General components
      - Operator, state, estimator, sampler etc.
- Platform (device/simulator) support
  - Quantum circuit simulators
      - `quri-parts-qulacs`: [Qulacs](https://github.com/qulacs/qulacs)
      - `quri-parts-stim`: [Stim](https://github.com/quantumlib/Stim)
      - `quri-parts-itensor`: [ITensor](https://github.com/ITensor/ITensors.jl)
      - `quri-parts-tket`: [TKet](https://www.quantinuum.com/developers/tket)
  - Quantum platforms/SDKs
      - `quri-parts-braket`: [Amazon Braket SDK](https://github.com/aws/amazon-braket-sdk-python)
      - `quri-parts-cirq`: [Cirq](https://quantumai.google/cirq) (Only circuit and operator conversion is supported yet)
      - `quri-parts-qiskit`: [Qiskit](https://qiskit.org/)
      - `quri-parts-quantinuum`: [Quantinuum](https://www.quantinuum.com/hardware/)
      - `quri-parts-ionq`: [IONQ](https://ionq.com/docs/)
- Intermediate representation support
  - `quri-parts-openqasm`: [OpenQASM 3.0](https://openqasm.com/)
- `quri-parts-algo`: Algorithms
  - Ansatz, optimizer, error mitigation etc.
- Chemistry
  - `quri-parts-chem`: General concepts
      - Fermion-qubit mapping, electron integrals, ansatz etc.
  - `quri-parts-pyscf`: [PySCF](https://pyscf.org/)
  - Library support
      - `quri-parts-openfermion`: [OpenFermion](https://quantumai.google/openfermion)

## Installation

QURI Parts requires Python 3.9.8 or later.

Use `pip` to install QURI Parts.
Default installation only contains components not depending specific platforms (devices/simulators) or external libraries.
You need to specify *extras* with square brackets (`[]`) to use those platforms and external libraries with QURI Parts:

```
# Default installation, no extras
pip install quri-parts

# Use Qulacs, a quantum circuit simulator
pip install "quri-parts[qulacs]"

# Use Amazon Braket SDK
pip install "quri-parts[braket]"

# Use Qulacs and OpenFermion, a quantum chemistry library for quantum computers
pip install "quri-parts[qulacs,openfermion]"
```

Currently available extras are as follows:

- `qulacs`
- `braket`
- `qiskit`
- `cirq`
- `openfermion`
- `stim`
- `openqasm`
- `itensor`

You can also install individual components (`quri-parts-*`) directly.
In fact, `quri-parts` is a meta package, a convenience method to install those individual components.

### Installation from local source tree

If you check out the QURI Parts repository and want to install from that local source tree, you can use `requirements-local.txt`.
In `requirements-local.txt`, optional components are commented out, so please uncomment them as necessary.

```
pip install -r requirements-local.txt
```

## Documentation and tutorials

Documentation of QURI Parts is available at <https://quri-parts.qunasys.com>.
[Tutorials](https://quri-parts.qunasys.com/tutorials.html) would be a good starting point.

## Release notes

See [Releases page](https://github.com/QunaSys/quri-parts/releases) on GitHub.

## Contribution guidelines

If you are interested in contributing to QURI Parts, please take a look at our [contribution guidelines](CONTRIBUTING.md).

## Authors

QURI Parts developed and maintained by [QunaSys Inc.](https://qunasys.com/en). All contributors can be viewed on [GitHub](https://github.com/QunaSys/quri-parts/graphs/contributors).

## License

QURI Parts is licensed under [Apache License 2.0](https://github.com/QunaSys/quri-parts/blob/main/LICENSE).