SimPHash/Src/Template/README.md

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.

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 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 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-language-server: $schema=./Schema.json

(VS Code with the YAML extension reads this comment automatically; adjust the relative path if your config.yaml lives elsewhere.)