Metadata-Version: 2.4
Name: falcata
Version: 1.0.0rc1
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: scipy
Provides-Extra: arrow
Requires-Dist: narwhals[pyarrow]; extra == "arrow"
Requires-Dist: pyarrow>=16.0.0; extra == "arrow"
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 targets every GPU architecture your toolkit supports, plus PTX for
the newest, which is why it takes a while. Building for just your own card is
far faster:

.. 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.
