# Solutions to the string challenges

This repository holds solutions to the challenges defined in [challenges/string](https://vault1.magland.org/challenges/string). It is one of possibly several solution repositories registered with that challenge repository, which clones each of them, compares every solution against a common reference, and publishes the comparison at [challenges/string/site](https://vault1.magland.org/challenges/string/site/). This repository's own site, at [challenges/string-solutions/site](https://vault1.magland.org/challenges/string-solutions/site/), lists its submissions with audio players and animates the exported displacement fields.

## Layout

```
solutions/<challenge-id>/<submission-id>.json    one submission: metadata and one or more solutions
solutions/<challenge-id>/<submission-id>/*.wav   the scored output files, referenced from the JSON
solutions/<challenge-id>/<submission-id>/*.h5    optional displacement fields for visualization
solvers/                                         source code of the submissions
web/                                             this repository's site (built by web/build.py)
```

## Adding a submission to this repository

1. Read the challenge specification, for example [string-pluck-v1](https://vault1.magland.org/challenges/string/blob/main/challenges/string-pluck-v1/README.md), and produce the output exactly as specified.
2. Choose a submission ID (lowercase letters, digits, hyphens) and write `solutions/<challenge-id>/<submission-id>.json` following the [schema](https://vault1.magland.org/challenges/challenge-tools/blob/main/schema.json). The existing files are complete examples.
3. Put the wav files (and optional field exports) in `solutions/<challenge-id>/<submission-id>/`. Files over 1 MiB must be pushed with git rather than written through the web interface.
4. If the submission contains several solutions of known relative accuracy, record that in `more_accurate_than`; this is what lets the reference be chosen automatically.
5. Open a pull request. The workflow validates the files and, on `main`, rebuilds this site. The comparison on the challenge repository's site is rebuilt when that repository's workflow next runs (on a push there, or by dispatching it).

Timing is self-reported wall-clock time for producing the output signal, excluding file I/O, on the hardware named in the `hardware` field.

## Starting a solution repository of your own

Any public repository with the same `solutions/` layout can be registered by a pull request to the challenge repository adding one entry to `registry/solution-repos.json`. What else the repository contains, including its own visualizations, is up to its authors.

## Validating locally

```
pip install git+https://vault1.magland.org/challenges/challenge-tools
challenge-tools validate --challenges <path-to-string-repo>/challenges --solutions solutions
python web/build.py --out site
```

## Regenerating the example submissions

```
python solvers/modal/modal_string.py <string-repo>/challenges/string-pluck-v1/challenge.json solutions/string-pluck-v1/modal-series --fields 1024 4 8 16 32 64 256 1024
python solvers/fd/fd_string.py <string-repo>/challenges/string-pluck-v1/challenge.json solutions/string-pluck-v1/fd-second-order --fields 16 1 2 4 8 16
```

Each solver prints per-solution metadata as JSON, from which the submission files are assembled.