forked from nique_372/SimPHash
74 lines
No EOL
4.8 KiB
Markdown
74 lines
No EOL
4.8 KiB
Markdown
# SimPHash — Config Reference
|
|
|
|
This document describes every parameter accepted by the YAML config consumed by SimPHash.
|
|
For the general overview, install steps and end-to-end usage flow, see the [main README](../../README.md).
|
|
|
|
`config.yaml` in this same folder is a fully commented, ready-to-copy template — start from it.
|
|
|
|
---
|
|
|
|
## Parameters
|
|
|
|
| Parameter | Description |
|
|
|---|---|
|
|
| `max_attepms` | Maximum displacement attempts (seed values `0, 1, 2, ...`) tried per bucket before giving up. |
|
|
| `namespace` | Namespace the generated tables/function are wrapped in (leave empty/`null` to skip). |
|
|
| `file_name_out` | Path of the `.mqh` file to generate. |
|
|
| `table_prefix` | Prefix used for all generated table names (`<prefix>_seeds`, `<prefix>_hashes`, `<prefix>_values`/`<prefix>_tindex`). |
|
|
| `copyright` | Text written into the generated file's `#property copyright`. |
|
|
| `link` | Text written into the generated file's `#property link`. |
|
|
| `func_name` | Name of the generated lookup function. |
|
|
| `def_name_table_size` | Name of the `#define` for the final table size. |
|
|
| `def_bucket_size_name` | Name of the `#define` for the bucket count. |
|
|
| `invalid_value` | Value returned by the generated function when a key isn't found (also used to fill unused slots). |
|
|
| `comment_funct` | If `true`, the generated function body is wrapped in `/* */` (useful when you only want the tables and will write the function yourself). |
|
|
| `guard_name` | Optional `#ifndef`/`#define` include guard name for the generated file. |
|
|
| `bin` | Optional object with `seeds`, `values`, `hash` and `meta` file paths — if present, the raw tables are also written as binary files. |
|
|
| `hash.type` | Bucket hash algorithm: `TSN_PHASH_TYPE_FNV1A_64` or `TSN_PHASH_TYPE_XXHASH_64`. |
|
|
| `hash.config.basis` / `hash.config.prime` | FNV-1a offset basis / prime (use `def` for the standard FNV-1a-64 constants). |
|
|
| `hash.config.seed` | xxHash64 seed (only used when `hash.type` is `TSN_PHASH_TYPE_XXHASH_64`). |
|
|
| `final_hash` | Final displacement hash: `HASH_UL1_MUR_MUR`, `HASH_UL1_SPLITMIX`, `HASH_UL1_FMIX` or `HASH_UL1_FIBBO`. |
|
|
| `perfect_hash.elements_por_bucket` | Target average number of keys per bucket (lower = more buckets, generally faster to find a working seed). |
|
|
| `perfect_hash.load_factor` | Final table load factor (keys / final table size) — lower leaves more free slots, easing displacement at the cost of memory. |
|
|
| `map_use_value` | `true` = generate a values table (function returns the value directly); `false` = generate an indices table (function returns a position for you to index your own array with). |
|
|
| `map` | The key set itself: a YAML object (`KEY: value`) when `map_use_value: true`, or an array of keys otherwise. |
|
|
|
|
### Files
|
|
In any parameter that mentions a path or route to a file, keep in mind that if you are using the market version, you must specify the relative path
|
|
(if common_flag=true then relative to the Common\ folder, otherwise to the Files\ folder of your terminal), otherwise the full path C:\
|
|
|
|
### The two hash stages
|
|
|
|
SimPHash mirrors how [PerfectHashByLeo](https://forge.mql5.io/nique_372/PerfectHashByLeo) works internally — a bucket hash followed by a final displacement hash:
|
|
|
|
- **Bucket hash (`hash.type`)** — converts each string key into a `ulong` before bucketing.
|
|
- `TSN_PHASH_TYPE_FNV1A_64`: FNV-1a 64-bit, with configurable `basis`/`prime`.
|
|
- `TSN_PHASH_TYPE_XXHASH_64`: xxHash64, with a configurable `seed`.
|
|
- **Final hash (`final_hash`)** — the per-bucket displacement hash, applied to the already-bucketed `ulong` key plus a seed.
|
|
- `HASH_UL1_MUR_MUR`: MurMur-style finalizer.
|
|
- `HASH_UL1_SPLITMIX`: SplitMix64.
|
|
- `HASH_UL1_FMIX`: MurmurHash3 fmix64 finalizer.
|
|
- `HASH_UL1_FIBBO`: Fibonacci hashing.
|
|
|
|
### Output modes
|
|
|
|
- `map_use_value: true` -> a **values table**: the generated function returns your mapped value directly.
|
|
- `map_use_value: false` -> an **indices table**: the function returns a position into your own array — useful when the value is too complex to inline (structs, objects, etc.).
|
|
|
|
Either mode can additionally be exported as raw `.bin` files via the `bin` block, if you'd rather load the table at runtime than compile it in.
|
|
|
|
---
|
|
|
|
## Editing by hand? Use the JSON Schema
|
|
|
|
[`Schema.json`](./Schema.json) in this same folder describes the exact shape above every field, its type, and which values are valid
|
|
so if you're editing `config.yaml` directly in an editor instead of copying an existing one, you get autocomplete and inline validation instead of guessing.
|
|
|
|
Most editors pick it up with a single line at the top of your YAML file:
|
|
|
|
```yaml
|
|
# yaml-language-server: $schema=./Schema.json
|
|
```
|
|
|
|
(VS Code with the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) reads this comment automatically;
|
|
adjust the relative path if your `config.yaml` lives elsewhere.) |