<?xml version='1.0' encoding='UTF-8' standalone='no'?>
<doxygen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="compound.xsd" version="1.8.14">
  <compounddef id="_r_e_a_d_m_e_8md" kind="file" language="Markdown">
    <compoundname>README.md</compoundname>
    <briefdescription>
    </briefdescription>
    <detaileddescription>
    </detaileddescription>
    <programlisting>
<codeline><highlight class="normal">#<sp/>forpy</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">Elegant<sp/>Decision<sp/>Forests<sp/>in<sp/>Python.<sp/>Fast,<sp/>clean<sp/>and<sp/>clear<sp/>C++14<sp/>implementation</highlight></codeline>
<codeline><highlight class="normal">with<sp/>no<sp/>dependencies<sp/>and<sp/>with<sp/>an<sp/>easy<sp/>to<sp/>use<sp/>interface<sp/>in<sp/>Python<sp/>and<sp/>C++.</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">##<sp/>Principles</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">1.<sp/>Easy<sp/>to<sp/>hack<sp/><sp/></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>The<sp/>library<sp/>provides<sp/>an<sp/>object<sp/>oriented<sp/>implementation<sp/>of<sp/>parts<sp/>of<sp/>the</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>theoretical<sp/>framework</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>of</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>[Criminisi<sp/>et<sp/>al.](https://www.microsoft.com/en-us/research/publication/decision-forests-for-classification-regression-density-estimation-manifold-learning-and-semi-supervised-learning/).</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>This<sp/>makes<sp/>the<sp/>library<sp/>easy<sp/>to<sp/>understand<sp/>and<sp/>extend<sp/>while<sp/>maintaining<sp/>full</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>generality.<sp/>Objects<sp/>are<sp/>easy<sp/>to<sp/>reuse<sp/>and<sp/>recombine.</highlight></codeline>
<codeline><highlight class="normal">2.<sp/>Easy<sp/>to<sp/>compile<sp/><sp/></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>There<sp/>are<sp/>no<sp/>dependencies.<sp/>The<sp/>only<sp/>build<sp/>requirement<sp/>is<sp/>a<sp/>C++14<sp/>compatible</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>compiler<sp/>(tested<sp/>with<sp/>GCC<sp/>and<sp/>clang).<sp/>We<sp/>use<sp/>the<sp/>CMake<sp/>build<sp/>system<sp/>with</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>pre-compiled<sp/>headers<sp/>for<sp/>fast<sp/>builds<sp/>and<sp/>compatibility<sp/>to<sp/>many<sp/>platforms.</highlight></codeline>
<codeline><highlight class="normal">3.<sp/>Easy<sp/>to<sp/>use<sp/><sp/></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>The<sp/>library<sp/>exposes<sp/>a<sp/>Python<sp/>and<sp/>C++<sp/>interface<sp/>that<sp/>accepts<sp/>numpy/Eigen</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>arrays<sp/>of<sp/>many<sp/>types.<sp/>The<sp/>interface<sp/>follows<sp/>the<sp/>widely<sp/>used<sp/>Scikit-learn</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>interface<sp/>with<sp/>`fit`<sp/>and<sp/>`predict`<sp/>methods.</highlight></codeline>
<codeline><highlight class="normal">4.<sp/>Fast<sp/><sp/></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>The<sp/>implementation<sp/>of<sp/>algorithms,<sp/>while<sp/>caring<sp/>for<sp/>readability<sp/>and</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>maintainability,<sp/>is<sp/>highly<sp/>optimized<sp/>for<sp/>speed<sp/>(benchmarks<sp/>see<sp/>below).<sp/>We</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>outperform<sp/>scikit<sp/>learn<sp/>in<sp/>all<sp/>settings<sp/>by<sp/>notable<sp/>margins<sp/>at<sp/>fit<sp/>and<sp/>predict</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>time.<sp/>For<sp/>fitting,<sp/>we<sp/>enable<sp/>fully<sp/>deterministic<sp/>parallelization<sp/>even<sp/>during</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>node<sp/>optimization,<sp/>allowing<sp/>to<sp/>fully<sp/>leverage<sp/>modern<sp/>CPUs<sp/>with<sp/>many<sp/>cores.</highlight></codeline>
<codeline><highlight class="normal">5.<sp/>Efficient<sp/><sp/></highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>We<sp/>use<sp/>the<sp/>[cereal](https://uscilab.github.io/cereal/)<sp/>C++<sp/>serialization</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>library<sp/>enabling<sp/>binary<sp/>persistence<sp/>(C++,<sp/>pickle)<sp/>or<sp/>JSON<sp/>export.<sp/>The<sp/>binary</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>models<sp/>need<sp/>only<sp/>a<sp/>fraction<sp/>of<sp/>space<sp/>of<sp/>the<sp/>corresponding<sp/>scikit<sp/>learn</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/><sp/>models.</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">##<sp/>Approach</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">We<sp/>use<sp/>modern<sp/>C++14<sp/>to<sp/>create<sp/>highly<sp/>flexible,<sp/>highly<sp/>efficient<sp/>data<sp/>structures</highlight></codeline>
<codeline><highlight class="normal">and<sp/>algorithm<sp/>implementations.<sp/>Core<sp/>building<sp/>blocks<sp/>are:</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">*<sp/>A<sp/>highly</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/>efficient<sp/>[`variant`<sp/>implementation](https://github.com/mapbox/variant)</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/>for<sp/>high<sp/>efficiency<sp/>w.r.t.<sp/>datatype<sp/>dependent<sp/>storage<sp/>and<sp/>processing<sp/>while</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/>maintaining<sp/>an<sp/>uncluttered<sp/>interface<sp/>and</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/>implementation.<sp/>[`glog`](https://github.com/google/glog)</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/>and<sp/>[`gperftools`](https://github.com/gperftools/gperftools)<sp/>integration<sp/>is</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/>used<sp/>for<sp/>easy<sp/>debugging<sp/>and<sp/>optimization.<sp/>All<sp/>dependency<sp/>libraries<sp/>don&apos;t<sp/>need</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/>to<sp/>be<sp/>installed<sp/>but<sp/>are<sp/>part<sp/>of<sp/>the<sp/>repository<sp/>and<sp/>completely<sp/>integrated<sp/>into</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/>the<sp/>build.</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">*<sp/>CMake<sp/>is<sp/>used<sp/>as<sp/>a<sp/>build<sp/>system<sp/>so<sp/>that<sp/>many<sp/>platforms<sp/>and<sp/>compilers<sp/>can<sp/>be</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/>targeted<sp/>easily.<sp/>[`cotire`](https://github.com/sakra/cotire)<sp/>is<sp/>used<sp/>for</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/>automatic<sp/>fast<sp/>pre-compiled<sp/>header<sp/>builds.<sp/>The<sp/>whole<sp/>package<sp/>is<sp/>automatically</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/>`pip`<sp/>installable<sp/>even<sp/>without<sp/>an<sp/>installed<sp/>CMake<sp/>thanks</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/>to<sp/>[`scikit-build`](https://github.com/scikit-build/scikit-build).</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">*<sp/>We<sp/>use<sp/>standard<sp/>[`Eigen`](http://eigen.tuxfamily.org)<sp/>datastructures<sp/>wrapped</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/>in<sp/>`variant`<sp/>to<sp/>provide<sp/>an<sp/>easy-to-use<sp/>C++<sp/>interface.<sp/>We<sp/>create<sp/>a<sp/>small<sp/>and</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/>sleek<sp/>Python<sp/>interface<sp/>thanks</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/>to<sp/>[pybind11](https://github.com/pybind/pybind11).</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/></highlight></codeline>
<codeline><highlight class="normal">*<sp/>Threading<sp/>is<sp/>implemented</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/>with<sp/>[cpptask](https://github.com/Kolkir/cpptask)<sp/>to<sp/>be<sp/>efficient<sp/>and</highlight></codeline>
<codeline><highlight class="normal"><sp/><sp/>cross-platform.</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">##<sp/>Compilation<sp/>&amp;<sp/>Installation</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">If<sp/>you<sp/>want<sp/>to<sp/>use<sp/>it<sp/>from<sp/>python,<sp/>a<sp/>simple<sp/>`python<sp/>setup.py<sp/>install`<sp/>should<sp/>do.</highlight></codeline>
<codeline><highlight class="normal">If<sp/>you<sp/>want<sp/>to<sp/>use<sp/>it<sp/>from<sp/>C++,<sp/>you<sp/>can<sp/>rely<sp/>on<sp/>CMake<sp/>and<sp/>do<sp/>`mkdir<sp/>build;<sp/>cd</highlight></codeline>
<codeline><highlight class="normal">build;<sp/>cmake<sp/>..;<sp/>cmake<sp/>--build<sp/>.<sp/>--<sp/>-j`<sp/>for<sp/>an<sp/>out-of-source<sp/>build.</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">##<sp/>Development<sp/>&amp;<sp/>Contributing</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">###<sp/>Formatting<sp/>and<sp/>conventions</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">The<sp/>code<sp/>is<sp/>formatted</highlight></codeline>
<codeline><highlight class="normal">with<sp/>[clang-format](https://clang.llvm.org/docs/ClangFormat.html)<sp/>according<sp/>to</highlight></codeline>
<codeline><highlight class="normal">the<sp/>google<sp/>C++<sp/>style<sp/>guidelines<sp/>(a<sp/>`.clang-format`<sp/>file<sp/>is<sp/>provided<sp/>on<sp/>project</highlight></codeline>
<codeline><highlight class="normal">level).<sp/>We<sp/>use<sp/>abbreviated<sp/>CamCase<sp/>class<sp/>names.<sp/>For<sp/>library<sp/>internal</highlight></codeline>
<codeline><highlight class="normal">functions,<sp/>assertions<sp/>must<sp/>be<sp/>done<sp/>using<sp/>the<sp/>`FASSERT`<sp/>macro<sp/>to<sp/>selectively<sp/>enable<sp/>it,</highlight></codeline>
<codeline><highlight class="normal">but<sp/>should<sp/>be<sp/>disabled<sp/>for<sp/>performance<sp/>reasons<sp/>for<sp/>release<sp/>builds.</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">Error<sp/>messages<sp/>*must*<sp/>be<sp/>meaningful<sp/>and<sp/>provide<sp/>additional<sp/>information<sp/>on<sp/>what</highlight></codeline>
<codeline><highlight class="normal">caused<sp/>the<sp/>error.</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">Design<sp/>decisions<sp/>are<sp/>made<sp/>according<sp/>to<sp/>the<sp/>following<sp/>priorities::<sp/>correctness<sp/>&amp;</highlight></codeline>
<codeline><highlight class="normal">numerical<sp/>stability<sp/>&gt;&gt;<sp/>speed<sp/>&gt;&gt;<sp/>in-memory<sp/>efficiency<sp/>&gt;&gt;<sp/>storage<sp/>efficiency.</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">####<sp/>Rough<sp/>naming<sp/>conventions</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">Raw<sp/>pointer<sp/>variable<sp/>names<sp/>end<sp/>with<sp/>`_p`,<sp/>indicating<sp/>(1)<sp/>high<sp/>performance</highlight></codeline>
<codeline><highlight class="normal">element<sp/>access<sp/>and<sp/>(2)<sp/>special<sp/>care.<sp/>In<sp/>performance<sp/>relevant<sp/>loops,<sp/>only<sp/>`_p`</highlight></codeline>
<codeline><highlight class="normal">variables<sp/>should<sp/>be<sp/>used.<sp/>Variant<sp/>variable<sp/>names<sp/>end<sp/>with<sp/>`_v`.</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">###<sp/>Programming<sp/>concepts</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">**Lock-free<sp/>parallelism:**</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">Memory<sp/>is<sp/>allocated<sp/>for<sp/>the<sp/>tree<sp/>and<sp/>leaf<sp/>storage<sp/>structures<sp/>in<sp/>before<sp/>entering</highlight></codeline>
<codeline><highlight class="normal">parallel<sp/>regions<sp/>in<sp/>a<sp/>pessimistic<sp/>way.<sp/>Since<sp/>it<sp/>is<sp/>linear<sp/>in<sp/>the<sp/>number<sp/>of</highlight></codeline>
<codeline><highlight class="normal">samples,<sp/>this<sp/>is<sp/>not<sp/>too<sp/>much<sp/>of<sp/>an<sp/>overhead.<sp/>The<sp/>pointer<sp/>to<sp/>where<sp/>next</highlight></codeline>
<codeline><highlight class="normal">nodes/leafs<sp/>can<sp/>be<sp/>created<sp/>is<sp/>an<sp/>`std::atomic&lt;size_t&gt;`.<sp/>After<sp/>training,<sp/>the</highlight></codeline>
<codeline><highlight class="normal">datastructures<sp/>are<sp/>resized<sp/>to<sp/>their<sp/>proper<sp/>size.</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">**The<sp/>[Desk](@ref<sp/>forpydeskGroup)<sp/>classes:**<sp/>this<sp/>is<sp/>a<sp/>helper<sp/>concept<sp/>to</highlight></codeline>
<codeline><highlight class="normal">simplify<sp/>safe<sp/>parallelism.<sp/>A<sp/>&apos;desk&apos;<sp/>contains<sp/>all<sp/>thread-local<sp/>variables<sp/>and</highlight></codeline>
<codeline><highlight class="normal">pointers<sp/>to<sp/>the<sp/>shared<sp/>storage.<sp/>Each<sp/>thread<sp/>has<sp/>its<sp/>own<sp/>[desk](@ref<sp/>forpy::Desk)</highlight></codeline>
<codeline><highlight class="normal">with<sp/>sub-objects<sp/>containing<sp/>thread-local<sp/>storage<sp/>for<sp/>the<sp/>corresponding</highlight></codeline>
<codeline><highlight class="normal">sub-functions.<sp/>It<sp/>is<sp/>constructed<sp/>with<sp/>pointers<sp/>to<sp/>the<sp/>memory<sp/>for<sp/>storing<sp/>the</highlight></codeline>
<codeline><highlight class="normal">results<sp/>of<sp/>the<sp/>training.</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">##<sp/>License</highlight></codeline>
<codeline></codeline>
<codeline><highlight class="normal">The<sp/>library<sp/>itself<sp/>is<sp/>available<sp/>under<sp/>the<sp/>2-clause<sp/>BSD<sp/>license.<sp/>All<sp/>libraries</highlight></codeline>
<codeline><highlight class="normal">used<sp/>are<sp/>also<sp/>available<sp/>under<sp/>open<sp/>source<sp/>licenses,<sp/>for<sp/>details<sp/>see</highlight></codeline>
<codeline><highlight class="normal">`build_support/external`.</highlight></codeline>
    </programlisting>
    <location file="/Users/classner/git/forpy/README.md"/>
  </compounddef>
</doxygen>
