README.md 2.12 KB
Newer Older
Marcel Rieger's avatar
Marcel Rieger committed
1
# Lorentz Boost Network (LBN) [![pipeline status](https://git.rwth-aachen.de/3pia/lbn/badges/master/pipeline.svg)](https://git.rwth-aachen.de/3pia/lbn/pipelines)
Marcel Rieger's avatar
Marcel Rieger committed
2

Marcel Rieger's avatar
Marcel Rieger committed
3
TensorFlow implementation of the Lorentz Boost Network from [arXiv:1812.09722 [hep-ex]](https://arxiv.org/abs/1812.09722).
Marcel Rieger's avatar
Marcel Rieger committed
4 5 6 7 8 9 10

Original repository: [git.rwth-aachen.de/3pia/lbn](https://git.rwth-aachen.de/3pia/lbn)


### Usage example

```python
Marcel Rieger's avatar
Marcel Rieger committed
11
import tensorflow as tf
Marcel Rieger's avatar
Marcel Rieger committed
12 13 14 15 16 17 18 19 20 21 22 23
from lbn import LBN

# initialize the LBN, set 10 combinations and pairwise boosting
lbn = LBN(10, boost_mode=LBN.PAIRS)

# create a feature tensor based on input four-vectors
features = lbn(four_vectors)

# use the features as input for a subsequent, application-specific network
...
```

Marcel Rieger's avatar
Marcel Rieger committed
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42
Or with TensorFlow 2 and Keras:

```python
import tensorflow as tf
from lbn import LBN, LBNLayer

# start a sequential model
model = tf.keras.models.Sequential()

# add the LBN layer
model.add(LBNLayer(10, boost_mode=LBN.PAIRS))

# add a dense layer
model.add(tf.keras.layers.Dense(1024))

# continue builing and training the model
...
```

Marcel Rieger's avatar
Marcel Rieger committed
43 44 45 46 47 48 49 50 51

### Installation and dependencies

Via [pip](https://pypi.python.org/pypi/lbn):

```bash
pip install lbn
```

Marcel Rieger's avatar
Marcel Rieger committed
52
NumPy and TensorFlow are the only dependencies. Both TensorFlow v1 and v2 are supported.
Marcel Rieger's avatar
Marcel Rieger committed
53 54 55 56


### Testing

Marcel Rieger's avatar
Marcel Rieger committed
57
Tests should be run for Python 2 and 3 and for TensorFlow 1 and 2. The following commands assume you are root directory of the LBN respository:
Marcel Rieger's avatar
Marcel Rieger committed
58 59 60 61

```bash
python -m unittest test

Marcel Rieger's avatar
Marcel Rieger committed
62
# or via docker, python 2 and tf 1
Marcel Rieger's avatar
Marcel Rieger committed
63
docker run --rm -v `pwd`:/root/lbn -w /root/lbn tensorflow/tensorflow:1.13.1 python -m unittest test
Marcel Rieger's avatar
Marcel Rieger committed
64

Marcel Rieger's avatar
Marcel Rieger committed
65 66
# or via docker, python 3 and tf 2
docker run --rm -v `pwd`:/root/lbn -w /root/lbn tensorflow/tensorflow:2.0.0a0-py3 python -m unittest test
Marcel Rieger's avatar
Marcel Rieger committed
67 68 69 70 71 72 73 74 75 76 77 78
```


### Contributing

If you like to contribute, we are happy to receive pull requests. Just make sure to add new test cases and run the tests. Also, please use a coding style that is compatible with our `.flake8` config.


### Development

- Original source hosted at [RWTH GitLab](https://git.rwth-aachen.de/3pia/lbn)
- Report issues, questions, feature requests on [RWTH GitLab Issues](https://git.rwth-aachen.de/3pia/lbn/issues)