Compiling and Running

Python Package Index

Some compiled wheels are available within the pip package manager, as well as a source distribution.

$ pip install xcsf

If installed in this way, the examples and notebooks will need to be copied from the repository.

If this fails to work, see the instructions below.

---

Building

Requirements

Stand-alone binary:

• C11 compliant compiler.
• CMake (>= 3.12)
• OpenMP (optional): supported by GCC and Clang with libomp.

Python library:

• All of the above for building the stand-alone executable.
• C++11 compliant compiler.
• Python (>= 3.8)

Compiler Options

• XCSF_MAIN=ON : Build the stand-alone main executable (CMake default = ON)
• XCSF_PYLIB=ON : Build the Python library (CMake default = OFF)
• PARALLEL=ON : CPU parallelised matching, predicting, and updating with OpenMP (CMake default = ON)
• ENABLE_TESTS=ON : Build and execute unit tests (CMake default = OFF)
• PYTEST=ON : Execute Python tests within a virtual environment (CMake default = OFF)
• NATIVE_OPT=ON : Optimise for the native system architecture (CMake default = ON)
• SANITIZE=ON : Enable AddressSanitizer and UndefinedBehaviorSanitizer - compile as Debug (CMake default = OFF)

Ubuntu

$ sudo apt install python3 python3-dev cmake
$ git clone --recurse-submodules https://github.com/xcsf-dev/xcsf.git
$ cd xcsf/build
$ cmake -DCMAKE_BUILD_TYPE=Release -DXCSF_PYLIB=ON -DENABLE_TESTS=ON ..
$ make

macOS

$ brew install libomp cmake python
$ git clone --recurse-submodules https://github.com/xcsf-dev/xcsf.git
$ cd xcsf/build
$ cmake -DCMAKE_BUILD_TYPE=Release -DXCSF_PYLIB=ON -DENABLE_TESTS=ON ..
$ make

For AppleClang, the path to OpenMP may need to be set. For example:

export OpenMP_ROOT=$(brew --prefix)/opt/libomp
export LDFLAGS="$LDFLAGS -L${OpenMP_ROOT}/lib"

Note: Try GCC if having problems with AppleClang and OpenMP.

Windows

Git + CMake + MinGW64-gcc-8.1.0 + Python 3.10.0 x86-64

Notes: use 64-bit versions for both Python and mingw. Tested with: python-3.10.0-amd64.exe and mingw-w64-install.exe (8.1.0; x86_64; posix; seh; 0). A simple method to get started is: Start → MinGW-W64 project → Run terminal → change to the desired install location and enter the commands below. [Compilation should also be possible within an IDE such as Visual Studio or Eclipse.]

$ git clone --recurse-submodules https://github.com/xcsf-dev/xcsf.git
$ cd xcsf\build
$ cmake -DCMAKE_BUILD_TYPE=Release -DXCSF_PYLIB=ON -DENABLE_TESTS=ON -G "MinGW Makefiles" ..
$ cmake --build . --config Release

Documentation

Doxygen + graphviz

After running CMake:

$ make doc

Alternatively see: XCSF documentation.

---

Running

Stand-alone

Default parameters are hard-coded. These are overridden by default.json at runtime. The JSON configuration file follows a similar structure to the Python library. Currently there are 3 built-in problem environments: {csv, mp, maze}.

Example real-multiplexer classification:

$ ./xcsf/main mp 6

Example discrete mazes:

$ ./xcsf/main maze ../env/maze/maze4.txt

Example regression: learning env/csv/sine_3var_train.csv and testing env/csv/sine_3var_test.csv

$ ./xcsf/main csv ../env/csv/sine_3var

Python

After building with CMake option: -DXCSF_PYLIB=ON

See the Python examples and notebooks.

For example, single-step reinforcement learning:

$ python3 example_rmux.py

Note that many of the examples require a few other Python packages, which can be installed:

$ pip install numpy matplotlib tqdm scikit-learn gymnasium

See Python Library Usage for more information.