gbrl 1.0.0.dev1__tar.gz

gbrl-1.0.0.dev1/LICENSE

@@ -0,0 +1,36 @@
+NVIDIA License
+
+1. Definitions
+
+“Licensor” means any person or entity that distributes its Work.
+“Work” means (a) the original work of authorship made available under this license, which may include software, documentation, or other files, and (b) any additions to or derivative works  thereof  that are made available under this license.
+“NVIDIA Processors” means any central processing unit (CPU), graphics processing unit (GPU), field-programmable gate array (FPGA), application-specific integrated circuit (ASIC) or any combination thereof designed, made, sold, or provided by NVIDIA or its affiliates.
+The terms “reproduce,” “reproduction,” “derivative works,” and “distribution” have the meaning as provided under U.S. copyright law; provided, however, that for the purposes of this license, derivative works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work.
+Works are “made available” under this license by including in or with the Work either (a) a copyright notice referencing the applicability of this license to the Work, or (b) a copy of this license.
+
+2. License Grant
+
+2.1 Copyright Grant. Subject to the terms and conditions of this license, each Licensor grants to you a perpetual, worldwide, non-exclusive, royalty-free, copyright license to use, reproduce, prepare derivative works of, publicly display, publicly perform, sublicense and distribute its Work and any resulting derivative works in any form.
+
+3. Limitations
+
+3.1 Redistribution. You may reproduce or distribute the Work only if (a) you do so under this license, (b) you include a complete copy of this license with your distribution, and (c) you retain without modification any copyright, patent, trademark, or attribution notices that are present in the Work.
+
+3.2 Derivative Works. You may specify that additional or different terms apply to the use, reproduction, and distribution of your derivative works of the Work (“Your Terms”) only if (a) Your Terms provide that the use limitation in Section 3.3 applies to your derivative works, and (b) you identify the specific derivative works that are subject to Your Terms. Notwithstanding Your Terms, this license (including the redistribution requirements in Section 3.1) will continue to apply to the Work itself.
+
+3.3 Use Limitation. The Work and any derivative works thereof only may be used or intended for use non-commercially and with NVIDIA Processors. Notwithstanding the foregoing, NVIDIA Corporation and its affiliates may use the Work and any derivative works commercially. As used herein, “non-commercially” means for research or evaluation purposes only.
+
+3.4 Patent Claims. If you bring or threaten to bring a patent claim against any Licensor (including any claim, cross-claim or counterclaim in a lawsuit) to enforce any patents that you allege are infringed by any Work, then your rights under this license from such Licensor (including the grant in Section 2.1) will terminate immediately.
+
+3.5 Trademarks. This license does not grant any rights to use any Licensor’s or its affiliates’ names, logos, or trademarks, except as necessary to reproduce the notices described in this license.
+
+3.6 Termination. If you violate any term of this license, then your rights under this license (including the grant in Section 2.1) will terminate immediately.
+
+4. Disclaimer of Warranty.
+
+THE WORK IS PROVIDED “AS IS” WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WARRANTIES OR CONDITIONS OF 
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE OR NON-INFRINGEMENT. YOU BEAR THE RISK OF UNDERTAKING ANY ACTIVITIES UNDER THIS LICENSE. 
+
+5. Limitation of Liability.
+
+EXCEPT AS PROHIBITED BY APPLICABLE LAW, IN NO EVENT AND UNDER NO LEGAL THEORY, WHETHER IN TORT (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE SHALL ANY LICENSOR BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR RELATED TO THIS LICENSE, THE USE OR INABILITY TO USE THE WORK (INCLUDING BUT NOT LIMITED TO LOSS OF GOODWILL, BUSINESS INTERRUPTION, LOST PROFITS OR DATA, COMPUTER FAILURE OR MALFUNCTION, OR ANY OTHER DAMAGES OR LOSSES), EVEN IF THE LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

gbrl-1.0.0.dev1/MANIFEST.in

@@ -0,0 +1,4 @@
+include gbrl/src/cuda/*.cu
+include gbrl/src/cuda/*.h
+include gbrl/src/cpp/*.cpp
+include gbrl/src/cpp/*.h

gbrl-1.0.0.dev1/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.1
+Name: gbrl
+Version: 1.0.0.dev1
+Summary: Gradient Boosted Trees for RL
+Author-email: Benjamin Fuhrer <bfuhrer@nvidia.com>, Chen Tesslr <ctessler@nvidia.com>, Gal Dalal <galal@nvidia.com>
+License-File: LICENSE
+Requires-Dist: pybind11==2.11.1
+Requires-Dist: numpy
+Requires-Dist: torch
+Provides-Extra: sklearn
+Requires-Dist: scikit_learn==1.2.2; extra == "sklearn"

gbrl-1.0.0.dev1/README.md

@@ -0,0 +1,91 @@
+# Gradient Boosting Reinforcement Learning (GBRL)
+GBRL is a Python-based GBT library designed and optimized for reinforcement learning (RL). GBRL is implemented in C++/CUDA aimed to seamlessly integrate within popular RL libraries. 
+
+### Key Features:
+- GBTs Tailored for RL: GBRL adapts the power of Gradient Boosting Trees to the unique challenges of RL environments, including non-stationarity and delayed feedback.
+- Optimized Actor-Critic Architecture: GBRL features a shared tree-based structure for policy and value functions. This significantly reduces memory and computational overhead, enabling it to tackle complex, high-dimensional RL problems.
+- Hardware Acceleration: GBRL leverages CUDA for hardware-accelerated computation, ensuring efficiency and speed.
+- Seamless Integration: GBRL is designed for easy integration with popular RL libraries, making it readily accessible for practitioners.
+
+
+## Getting started
+
+```
+pip install gbrl
+```  
+
+For GPU support GBRL looks for `CUDA_PATH` or `CUDA_HOME` environment variables. Unless found, GBRL will automatically compile only for CPU.
+
+Verify that GPU is visible by running
+```
+import gbrl
+
+gbrl.cuda_available()
+```
+
+*OPTIONAL*  
+For tree visualization make sure graphviz is installed before compilation. 
+
+## Usage Example in an RL library
+```
+import torch as th
+from gbrl import ActorCriticGBRL
+from stable_baselines3.common.distributions import CategoricalDistribution
+
+### initialize model ###
+# define tree structure parameters
+tree_struct = {'max_depth': 4, 'min_data_in_leaf': 0, 'n_bins': 256, 'grow_policy': 'oblivious'}
+# define gbrl parameters
+gbrl_params = {'control_variates': False, 'split_score_func': 'cosine', 'generator_type': 'Quantile'}
+# actor and critic optimizers
+policy_optimizer = {'algo': 'SGD', 'lr': 0.05}
+value_optimizer = {'algo': 'SGD', lr: '0.25'}
+
+# Given action_space instance of gym.spaces.Space
+
+model = ActorCriticGBRL(tree_struct=tree_struct, output_dim=action_space.n, pg_optimizer=policy_optimizer, value_optimizer=value_optimizer, shared_tree_struct=True, gbrl_params=gbrl_params, device='cuda')
+model.init_model() 
+
+action_dist = CategoricalDistribution(action_space.n)
+### Training loop ### 
+logits, values = model(obs) # returns numpy arrays
+logits = th.tensor(logits, requires_grad=True)
+values = th.tensor(values, requires_grad=True)
+
+distribution = action_dist.proba_distribution(logits)
+log_prob = distribution.log_prob(actions)
+
+loss = ... calculate loss according to RL algorithm
+
+loss.backward()
+
+self.policy.fit(rollout_data., theta_grad, values_grad)
+
+# calculate grads (GBRL fits numpy arrays)
+logits_grads = logits.grad.detach().cpu().numpy() * len(obs) # gradients w.r.t to the *each sample
+value_grads = values.grad.detach().cpu().numpy() * len(obs)
+
+model.fit(obs, logits_grads, value_grads)
+```
+
+## Current Supported Features
+### Tree Fitting
+- Greedy (Depth-wise) tree building - (CPU/GPU)  
+- Oblivious (Symmetric) tree building - (CPU/GPU)  
+- L2 split score - (CPU/GPU)  
+- Cosine split score - (CPU/GPU) 
+- Uniform based candidate generation - (CPU/GPU)
+- Quantile based candidate generation - (CPU/GPU)
+- Supervised learning fitting / Multi-iteration fitting - (CPU/GPU)
+    - MultiRMSE loss (only)
+- Categorical Inputs
+### GBT Inference
+- SGD optimizer - (CPU/GPU)
+- ADAM optimizer - (CPU only)
+- Control Variates (gradient variance reduction technique) - (CPU only)
+- Shared Tree for policy and value function - (CPU/GPU)
+- Linear and constant learning rate scheduler - (CPU/GPU only constant)
+- Support for up to two different optimizers (e.g, policy/value) - **(CPU/GPU if both are SGD)
+
+## Citing 
+