Initial commit

Author: Lara Chiara Ost

.gitignore

@@ -0,0 +1,7 @@
+build/
+conf/
+.vscode
+.cache
+.clangd
+test*
+!test

LICENSE

@@ -0,0 +1,8 @@
+
+Copyright 2024 Lara Ost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,57 @@
+# Banana Trees
+
+This implements the banana tree data structure introduced by Cultrera di Montesano, Edelsbrunner, Henzinger and Ost at SODA 2024.
+
+# Build Instructions
+
+The code is written in C++20.
+Building requires boost (any reasonably recent version should do; we use the pool library and the intrusive library).
+All other dependencies are in the `ext` directory.
+
+To compile using `meson` and `ninja`:
+```
+mkdir build
+meson setup --buildtype=release build .
+ninja -C build/
+```
+
+If `operator<<` for `std::chrono::duration` types is not available, run `meson setup -D fallback-operator=true build .` instead.
+Alternatively, run `meson configure -D fallback-operator=true build` after the setup step. 
+
+Replace `release` by `debug` for a debug build.
+
+Tests are build if meson finds `GTest` and `gtest_main`.
+
+# Running Experiments
+
+Relevant executables are `ex_construction`, `ex_local_maintenance`, `ex_topological_maintenance`, `ex_time_series`.
+Run with option `--help` to see the available options.
+The string passed to `--gen-args` is described in `docs/generators.md`
+
+`ex_construction` generates a time series and measures the time for constructing the banana tree.
+
+`ex_local_maintenance` generates a time series and measures the time for value changes in an interval $M = [-m,m]$.
+It selects a random item, then, from the original input, changes the value of that item by values in $M$.
+The magnitudes of the changes are chosen from $M$ uniformly spaced; $D$ changes are performed in total.
+The paramters $m$ and $D$ are user specified (`-m` and `-d`, respectively).
+
+`ex_topological_maintenance` generates a time series and measures the time for topological operations.
+The size of the left interval relative to the total time series is given by the option `-c`.
+
+Both `ex_local_maintenance` and `ex_topological_maintenance` can run worst-case scenarios by selecting the appropriate subcommand.
+The `num_items` option works slightly differently in these executables than described in the help string:
+the format is `min number_of_divisions max`; `number_of_divisions` values are selected from the interval `[min, max]`,
+such that they are spaced evenly on a logarithmic scale.
+
+`ex_time_series construct` reads a time series from standard input in the form of a sequence of function values and constructs the banana tree.
+
+Each executable outputs performance statistics to standard output.
+This output can be converted into a csv-file using the python script `tools/convert-to-csv.py`.
+Structural properties of the banana trees can be written to a separate file via the option `-o`.
+This output can be converted into a csv-file using the python script `tools/structure-convert-to-csv.py`.
+
+# License
+
+This repository, except files in `ext/`, is published under the MIT license.
+
+See the files in `ext/` for the respective licenses.

docs/banana_tree_conventions.md

@@ -0,0 +1,36 @@
+# Banana Trees
+
+This document describes conventions used in the implementation. See the paper for a full description of banana trees.
+
+## Nodes in Banana Trees
+
+A node in a banana tree has between two and four neighbors:
+
+- Internal nodes have neighbors on the same trail (pointed to by `up` and `down`) and the first node(s) on their in- and mid-trail (pointed to by `in` and `mid`).
+- The special root has the first nodes on its in- and mid-trail as its only neighbors (pointed to by `in` and `mid`).
+- Leaves have the first nodes on their in- and mid-trails as neighbors (pointed to by `in` and `mid`).
+
+The `up` and `down` pointers of leaves and the special root are `null`.
+All nodes have non-null `low` pointers; only leaves have non-null `death` pointers.
+
+|              | up | down | in | mid | low | death |
+|--------------|----|------|----|-----|-----|-------|
+|internal node | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
+|leaf          | :x: | :x: | :heavy_check_mark: | :heavy_check_mark: | `= this` | :heavy_check_mark: |
+|special root  | :x: | :x: | :heavy_check_mark: | :heavy_check_mark: | `= in->low` | :x: |
+
+### `low` Pointers
+
+`low` pointers generally point to the descendant with the lowest function value.
+For internal nodes this is the lower end of the trail containing the node.
+The `low`-pointers of leaves point to themselves and the `low`-pointer of the special root points to the birth of the global window, i.e., to the lower end of the trails starting at the special root.
+
+### `death` Pointers
+
+`death` pointers are only not `null` at leaves, where they point to the node upper end of the trails starting at the leaf.
+
+## Construction
+
+Which of the trails beginning at the special root is the in-trail and which is the mid-trail is not specified in the paper. However, the construction algorithm always ends up with the left trail being the in-trail and the right trail being the mid-trail. 
+
+For a node on the special banana, we say that it is on the in-trail if its item is left of the item represented by `low` of the special root. Otherwise, it is on the mid-trail.

docs/generators.md

@@ -0,0 +1,54 @@
+# Synthetic Data Generators
+
+## Gaussian Random Walks
+
+Generate a random walk where $f(x_i) = f(x_{i-1}) + \cal{N}(\mu, \sigma)$.
+
+Pass to `--gen_args` as
+```
+    grw:<mean>;<sd>
+```
+`<mean>` is the mean of the normal distribution, `<sd>` its standard deviation.
+All parameters (`<...>`) are converted to a number by `std::stod(...)`.
+Parameter `<sd>` is optional.
+
+## Linear Case for Local Maintenance
+
+Pass to `--gen_args` as `local-wc`.
+
+## Quasi-Periodic Functions
+
+### Method 1 -- Sine Wave + Random Walk
+
+$f(x) = a \cdot sin(\omega x) + R(x; \mu, \sigma)$, where $R(x; \mu, \sigma)$ is a Gaussian random walk.
+
+Parameters:
+- $a$: amplitude of the sine wave
+- $\omega$: angular frequency in items; $\omega = 1/(2\pi \cdot b)$ has period $b$
+- $\mu$: mean of the normal distribution of the random walk
+- $\sigma$: the standard deviation of the normal distribution of the random walk
+
+Pass to `--gen_args` as
+```
+    sqp:<period>;<amplitude>;<mean>;<sd>
+```
+All parameters (`<...>`) are converted to a number by `std::stod(...)`.
+All are optional, but must be specified in the given order,
+i.e., if `<mean>` is given, then `<period>` and `<amplitude>` cannot be omitted. 
+
+### Method 2 -- Sine Wave Modulating a Random Walk
+
+$f(x) = R(x; a \cdot sin(wx), \sigma)$, where $R(x; \mu, \sigma)$ is a Gaussian random walk.
+
+Parameters:
+- $a$: amplitude of the sine wave
+- $\omega$: angular frequency in items; $\omega = 1/(2\pi \cdot b)$ has period $b$
+- $\sigma$: mean of the normal distribution of the random walk as above
+
+Pass to `--gen_args` as
+```
+    mqp:<number of periods>;<amplitude>;<sd>
+```
+All parameters (`<...>`) are converted to a number by `std::stod(...)`.
+All are optional, but must be specified in the given order,
+i.e., if `<sd>` is given, then `<number of periods>` and `<amplitude>` cannot be omitted.