https://github.com/flashlight/sequence
Sequence algorithms for use in Flashlight.
https://github.com/flashlight/sequence
Last synced: 9 months ago
JSON representation
Sequence algorithms for use in Flashlight.
- Host: GitHub
- URL: https://github.com/flashlight/sequence
- Owner: flashlight
- License: mit
- Created: 2022-08-22T21:11:12.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-03-18T03:02:25.000Z (about 1 year ago)
- Last Synced: 2025-03-27T18:13:05.006Z (about 1 year ago)
- Language: C++
- Homepage:
- Size: 75.2 KB
- Stars: 14
- Watchers: 29
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION
Awesome Lists containing this project
README
# Flashlight Sequence: Algorithms for Sequence Data
[**Quickstart**](#quickstart)
| [**Installation**](#building-and-installing)
| [**Python Documentation**](bindings/python)
| [**Citing**](#citing)
[](https://app.circleci.com/pipelines/github/flashlight/sequence)
[](https://gitter.im/flashlight-ml/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [](https://codecov.io/gh/flashlight/sequence) [](https://vcpkg.link/ports/flashlight-sequence)
*Flashlight Sequence* is a library with fast implementations of sequence-based operations. It includes:
- A fast, parallel CPU implementation of the Viterbi algorithm for greedy "`argmax`-style" decoding
- Fast implementations (CPU and CUDA) of the [Wav2letter ASG loss](https://arxiv.org/pdf/1609.03193.pdf) function including the fully-connected and forced-alignment algorithms.
## Quickstart
Flashlight Sequence has Python bindings. To install the bindings from source, [optionally install CUDA] then clone the repo and build:
```shell
git clone https://github.com/flashlight/sequence && cd sequence
pip install .
```
To install with CUDA support, set the environment variable `USE_CUDA=1` when running the install command. By default, bindings are installed with OpenMP support; to build and install without OpenMP, set the environment to have `USE_OPENMP=0` when buildling.
See the [full Python binding documentation](bindings/python) for examples and more.
## Building and Installing
[**From Source (C++)**](#building-from-source) | [**With `vcpkg` (C++)**](#with-vcpkg) | [**From Source (Python)**](bindings/python#build-instructions) | [**Adding to Your Own Project (C++)**](#adding-flashlight-sequence-to-a-c-project)
### Requirements
At minimum, C++ compilation requires:
- A C++ compiler with good C++17 support (e.g. gcc/g++ >= 7)
- [CMake](https://cmake.org/) — version 3.16 or later, and ``make``
- A Linux-based operating system.
**CUDA Support:** If building with CUDA support, CUDA >= 9 is recommended. To toggle CUDA support use the `FL_SEQUENCE_USE_CUDA` CMake option or the `USE_CUDA` environment variable when building the Python bindings. To toggle OpenMP support, use the `FL_SEQUENCE_USE_OPENMP` CMake option or use the `USE_OPENMP` environment variable when building the Python bindings.
**Tests:** If building tests, [Google Test](https://github.com/google/googletest) >= 1.12 is required, but is installed automatically on build if not found. The `FL_SEQUENCE_BUILD_TESTS` CMake option toggles building tests.
Instructions for building/installing the Python bindings from source [can be found here](bindings/python/README.md).
### Building from Source
Building the C++ project from source is simple:
```bash
git clone https://github.com/flashlight/sequence && cd sequence
cmake -S . -B build
cmake --build build --parallel
cd build && ctest && cd .. # run tests
cmake --install build # install at the CMAKE_INSTALL_PREFIX
```
To enable CUDA while building, pass `-DFL_SEQUENCE_USE_CUDA=ON` to CMake. To enable building with OpenMP, pass `-DFL_SEQUENCE_USE_OPENMP=ON` to CMake. To disable building tests, pass `-DFL_SEQUENCE_BUILD_TESTS=OFF`.
If building with CUDA < 11, [NVIDIA cub](https://github.com/NVIDIA/cub) is required. It will be downloaded automatically if not found; the `FL_SEQUENCE_BUILD_STANDALONE` build option controls this behavior.
#### With [`vcpkg`](https://vcpkg.io/)
Flashlight Sequence can also be installed and used downstream with the [`vcpkg`](https://vcpkg.io/) package manager. The [port](https://github.com/microsoft/vcpkg/blob/master/ports/flashlight-sequence/) contains optional features for building with OpenMP and/or CUDA:
```bash
vcpkg install flashlight-sequence # no dependencies, or:
vcpkg install "flashlight-sequence[cuda]" # with CUDA
vcpkg install "flashlight-sequence[openmp]" # with OpenMP
vcpkg install "flashlight-sequence[cuda,openmp]" # with both!
```
### Adding Flashlight Sequence to a C++ Project
Given a simple `project.cpp` file that includes and links to Flashlight Sequence:
```c++
#include
#include
int main() {
auto res = fl::lib::cpu::ViterbiPath::compute(...);
std::cout << "ViterbiPath result[0] " << res[0] << std::endl;
return 0;
}
```
The following CMake configuration links Flashlight and sets include directories:
```cmake
cmake_minimum_required(VERSION 3.16)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
add_executable(myProject project.cpp)
find_package(flashlight-sequence CONFIG REQUIRED)
target_link_libraries(myProject PRIVATE flashlight::flashlight-sequence)
```
### Contributing and Contact
Contact: jacobkahn@fb.com
Flashlight Sequence is actively developed. See
[CONTRIBUTING](CONTRIBUTING.md) for more on how to help out.
## Citing
You can cite [Flashlight](https://arxiv.org/abs/2201.12465) using:
```
@misc{kahn2022flashlight,
title={Flashlight: Enabling Innovation in Tools for Machine Learning},
author={Jacob Kahn and Vineel Pratap and Tatiana Likhomanenko and Qiantong Xu and Awni Hannun and Jeff Cai and Paden Tomasello and Ann Lee and Edouard Grave and Gilad Avidov and Benoit Steiner and Vitaliy Liptchinsky and Gabriel Synnaeve and Ronan Collobert},
year={2022},
eprint={2201.12465},
archivePrefix={arXiv},
primaryClass={cs.LG}
}
```
For the AutoSegmentation Criterion (ASG), cite:
```
@article{collobert2016wav2letter,
title={Wav2letter: an end-to-end convnet-based speech recognition system},
author={Collobert, Ronan and Puhrsch, Christian and Synnaeve, Gabriel},
journal={arXiv preprint arXiv:1609.03193},
year={2016}
}
```
## License
Flashlight Sequence is under an MIT license. See [LICENSE](LICENSE) for more information.