Metadata-Version: 2.4
Name: falcata
Version: 1.0.4
Summary: Falcata: GPU-first gradient boosted decision trees
Author-Email: Felix Jonas Kroner <felix@mechafauna.ai>, Max <max@mechafauna.ai>
Maintainer-Email: Felix Jonas Kroner <felix@mechafauna.ai>, Max <max@mechafauna.ai>
License-Expression: MIT
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Environment :: GPU :: NVIDIA CUDA :: 12
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Project-URL: homepage, https://github.com/MechaFauna-ai/Falcata
Project-URL: repository, https://github.com/MechaFauna-ai/Falcata.git
Project-URL: changelog, https://github.com/MechaFauna-ai/Falcata/releases
Requires-Python: >=3.10
Requires-Dist: narwhals>=1.15
Requires-Dist: numpy>=1.21.3
Requires-Dist: nvidia-cuda-nvrtc-cu12
Requires-Dist: scipy
Provides-Extra: arrow
Requires-Dist: narwhals[pyarrow]; extra == "arrow"
Requires-Dist: pyarrow>=16.0.0; extra == "arrow"
Provides-Extra: multigpu
Requires-Dist: nvidia-nccl-cu12; extra == "multigpu"
Provides-Extra: dask
Requires-Dist: dask[array,dataframe,distributed]>=2.0.0; extra == "dask"
Requires-Dist: narwhals[pandas]; extra == "dask"
Requires-Dist: pandas>=1.3.4; extra == "dask"
Provides-Extra: pandas
Requires-Dist: narwhals[pandas]; extra == "pandas"
Requires-Dist: pandas>=1.3.4; extra == "pandas"
Provides-Extra: plotting
Requires-Dist: graphviz; extra == "plotting"
Requires-Dist: matplotlib; extra == "plotting"
Provides-Extra: polars
Requires-Dist: narwhals[polars]; extra == "polars"
Requires-Dist: polars>=1.0.0; extra == "polars"
Provides-Extra: scikit-learn
Requires-Dist: scikit-learn>=1.0.2; extra == "scikit-learn"
Description-Content-Type: text/x-rst

Falcata
=======

GPU-first gradient boosted decision trees.

*Falcataria moluccana* — the falcata — is one of the fastest-growing trees on
earth. This one grows them faster too.

Falcata is a CUDA-native GBDT library: a leaf-wise learner whose training loop
was rebuilt around batched, level-parallel GPU kernels rather than one split at
a time.

What makes it fast
------------------

- **Hybrid level-batched growth** — whole levels of sibling pairs are scored,
  synchronized and applied in one launch each instead of per split, turning a
  latency-bound loop into a throughput-bound one, with leaf-wise-identical trees.
- **CUDA-graph level loops** — the per-level launch sequence is captured once and
  replayed by a device-side controller, removing host round-trips.
- **NVRTC runtime JIT** — construct kernels are specialized at runtime to the
  actual data shape, self-tested against the ahead-of-time kernel, and promoted
  only if bit-identical.
- **Per-tree compact column view** — with any ``feature_fraction < 1``, only
  the sampled columns are materialized for histogram construction; the win
  scales with the excluded fraction (~3.4× end-to-end at
  ``feature_fraction = 0.1`` on wide, low-cardinality data).
- **GPU-native dataset construction** — dense binning, row-data build and EFB
  pre-checking run on the device; CuPy and ``__cuda_array_interface__`` inputs
  are ingested without a host round-trip.
- **Quantized training, two ways** — ``quant_mode=stochastic`` is the speed
  end: 4-bin gradients with seeded stochastic rounding; ``quant_mode=fixedpoint``
  is the near-lossless end: deterministic rounding with an internal
  outlier-robust gradient scale. Bin counts are overridable with
  ``quant_bins``; both modes are bit-reproducible run to run.
- **GPU inference via NVIDIA FIL** — with cuML installed,
  ``Booster.predict()`` transparently runs on the Forest Inference Library;
  CuPy arrays stay on the device end to end.
- **An execution planner** — shape-conditional kernel choices are resolved once
  from the data and parameters (``cuda_plan=auto``), every decision guaranteed
  bit-identical and individually overridable.

Every optimization above is required to be bit-identical to the reference path,
and that is enforced mechanically: a 38-cell regression lattice of
(config × data-shape) training cells fingerprinted by model md5 runs on a real
GPU on every commit, alongside plan-flip equality cells, validity assertions,
metric floors and a perf gate.

Install
-------

.. code:: sh

    pip install falcata

That builds the CUDA library from source, so you need the CUDA toolkit
(>= 11.0), CMake >= 3.28, a C++17 compiler and Python >= 3.10. Nothing else:
the source distribution vendors every dependency, so no ``git clone`` and no
submodule dance.

The build detects the GPU(s) in the machine and compiles only for those
(15–20 minutes on typical hardware). When no GPU is visible at build time it
targets every architecture the toolkit supports instead, which takes several
times longer. To pick an architecture explicitly:

.. code:: sh

    # RTX 5090 = 120, RTX 4090 = 89, A100 = 80, T4 = 75
    pip install falcata --config-settings=cmake.define.CMAKE_CUDA_ARCHITECTURES=89

There is a CPU build, though it is not what this library is for:

.. code:: sh

    pip install falcata --config-settings=cmake.define.USE_CUDA=OFF

Multi-GPU training additionally needs NCCL *and its headers*
(``libnccl-dev`` on Debian/Ubuntu):

.. code:: sh

    pip install falcata \
      --config-settings=cmake.define.USE_NCCL=ON \
      --config-settings=cmake.define.BUILD_WITH_SHARED_NCCL=ON

Installing the wheel also installs a ``lightgbm`` import shim. If the target
environment already has stock LightGBM, uninstall it first or use a fresh
environment — pip will not report the collision.

Quick start
-----------

.. code:: python

    import falcata as flc

    ds = flc.Dataset(X_train, label=y_train, params={"device_type": "cuda"})
    model = flc.train(
        {
            "objective": "regression",
            "device_type": "cuda",
            "num_leaves": 255,
            "quant_mode": "stochastic",   # none | stochastic | fixedpoint
            "cuda_precision": "fp32",     # fp64 (default) | fp32
            "cuda_plan": "auto",          # the planner picks the kernels
        },
        ds,
        num_boost_round=1000,
    )

Compatibility with LightGBM
---------------------------

Falcata began as a fork of LightGBM and deliberately stays interoperable at the
data boundaries:

- **Models** written by Falcata load in stock LightGBM (and vice versa) with
  bit-identical predictions — verified in CI.
- **Binary datasets** (``.dataset``) interchange in both directions.
- **Parameter names** are unchanged; Falcata's additions (``quant_mode``,
  ``cuda_precision``, ``cuda_plan``) are new names upstream simply ignores.
- The historical ``LGBM_*`` C API names remain as aliases for ``FLC_*``. The
  Python package is ``import falcata`` only — code written against
  ``import lightgbm`` needs its import changed, nothing else.

License
-------

MIT. Falcata derives from LightGBM (copyright Microsoft Corporation and the
LightGBM developers, MIT); that copyright is retained. Falcata is not affiliated
with, endorsed by, or supported by Microsoft or the LightGBM maintainers.
