neuron-technologies/el
3
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases 5 Wiki Activity

M9 refinement: operate geometry descriptor in mean-centered (isotropic) embedding space

Browse Source 
The nomic-embed-text space over the corpus is strongly anisotropic (mean
pairwise cosine ~0.55), which compresses cosine-based domain separation almost
to nothing so the design-doc s5 operators (distance/overlap/Wasserstein) cannot
discriminate. Subtracting the global mean of the normalized embeddings restores
isotropy (mean pairwise cosine ~0) and sharpens the operators.

- add GeoMeanCache (engram_geo_mean_build / _maybe_refresh / _vec / _free): a
  store-derived centering offset over the embed-eligible set, cached and
  refreshed on significant drift; lives in geometry.c, not the store.
- engram_geometry_descriptor gains an optional global_mean: when supplied the
  centroid, per-member cosine distance, and co-registration run in centered
  space (GM=zeros reproduces the legacy raw path exactly).
- co-registration choice (b): the ANN query stays in raw unit space (index
  unchanged) since centering is a rigid translation that ~preserves neighborhood
  membership; only the descriptor statistics move to the centered frame.
  Covariance/axes/radius are translation-invariant and therefore unchanged.
- test: synthetic ground-truth suite stays green (PERF + ASan/UBSan), plus new
  centered/raw/mean-cache assertions.
- add bench_discrimination.c (env-gated, read-only, skips in CI): on a copy of
  the real store the two-domain overlap operator drops 1.13 -> 0.008 and
  cross-centroid cosine 0.899 -> 0.003 after centering, Euclid distance
  unchanged (translation-invariant control).

No change to activation/retrieval behavior; wiring geometry into retrieval is a
separate, behavior-changing cutover.
This commit is contained in:
Will Anderson
2026-08-12 19:54:41 -05:00
parent 2a4c5c645a
commit 8cae0f94eb
5 changed files with 355 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
engram/test/bench_discrimination.c
+149
View File
@@ -0,0 +1,149 @@
/* bench_discrimination.c — M9 REFINEMENT bench: measures whether mean-centering
* the anisotropic nomic-embed-text space sharpens the §5 geometry operators on
* REAL data. Read-only over a COPY of the live store (never the live file).
*
* usage: bench_discrimination [store.egm]
* (or set ENGRAM_BENCH_STORE). If no store is given/openable it prints
* SKIP and exits 0 — so it is safe in CI without live data.
*
* It picks two semantically distinct cohorts by keyword (domain A vs domain B),
* computes the global mean over the embed-eligible set (via engram_geo_mean_build
* — the same offset the descriptor uses), then reports BEFORE (raw unit space)
* vs AFTER (mean-centered space):
* - cross-centroid cosine (lower = better separated)
* - cross-centroid Euclid dist (translation-invariant: a control)
* - intra-cohesion per domain (member cos to own centroid)
* - overlap operator (cross_cos / sqrt(intraA*intraB): ~1 = domains
* indistinguishable, ~0 = cleanly separated)
* - angular separation ratio z (centroid angle / summed angular spread)
* - mean pairwise cosine sample (the anisotropy headline; ~0.55 raw -> ~0 ctr)
*
* Pure C11; links engram_store.c + engram_geometry.c; -lm.
*/
#include "engram_store.h"
#include "engram_geometry.h"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <strings.h>
#include <math.h>
#define CAP_DOMAIN 400
#define CAP_SAMPLE 800
typedef struct { float** v; int n, cap, dim; } VecSet;
static void vs_init(VecSet* s){ s->v=NULL; s->n=0; s->cap=0; s->dim=0; }
static void vs_push(VecSet* s, const float* e, int dim, int cap){
if(s->n>=cap) return;
if(s->dim==0) s->dim=dim;
if(s->n==s->cap){ int nc=s->cap?s->cap*2:64; s->v=realloc(s->v,(size_t)nc*sizeof*s->v); s->cap=nc; }
float* c=malloc((size_t)dim*sizeof(float));
double nn=0; for(int d=0;d<dim;d++) nn+=(double)e[d]*e[d]; nn=sqrt(nn);
if(nn<1e-12){ free(c); return; }
for(int d=0;d<dim;d++) c[d]=(float)(e[d]/nn); /* L2-normalized copy */
s->v[s->n++]=c;
}
static void vs_free(VecSet* s){ for(int i=0;i<s->n;i++) free(s->v[i]); free(s->v); }
typedef struct { VecSet A, B, S; long idx; } Coh;
static int has(const char* h, const char* n){ return h && strcasestr(h,n)!=NULL; }
static void cb(const StoreNode* n, void* ctx){
Coh* c=ctx;
if(!(n->emb && n->emb_dim>0)) return;
/* every 5th embedded node -> isotropy sample */
if((c->idx++ % 5)==0) vs_push(&c->S, n->emb, n->emb_dim, CAP_SAMPLE);
const char* t=n->content; const char* g=n->tags;
int A = has(t,"quantiz")||has(g,"quantiz")||has(t,"lorablation")||has(t,"70B")||has(t,"LoRA merge");
int B = has(t,"kubernetes")||has(t,"terraform")||has(t,"argo")||has(g,"infrastructure")||has(t,"vault")||has(t,"cloudflare");
if(A && !B) vs_push(&c->A, n->emb, n->emb_dim, CAP_DOMAIN);
else if(B && !A) vs_push(&c->B, n->emb, n->emb_dim, CAP_DOMAIN);
}
/* mean of a VecSet into out (dim doubles). */
static void mean_of(const VecSet* s, const float* gm, double* out){
int dim=s->dim; for(int d=0;d<dim;d++) out[d]=0;
for(int i=0;i<s->n;i++) for(int d=0;d<dim;d++) out[d]+=(double)s->v[i][d]-(gm?gm[d]:0.0);
if(s->n) for(int d=0;d<dim;d++) out[d]/=s->n;
}
static double dnorm(const double* a, int dim){ double s=0; for(int d=0;d<dim;d++) s+=a[d]*a[d]; return sqrt(s); }
static double dcos(const double* a, const double* b, int dim){
double na=dnorm(a,dim), nb=dnorm(b,dim); if(na<1e-12||nb<1e-12) return 0;
double s=0; for(int d=0;d<dim;d++) s+=a[d]*b[d]; double c=s/(na*nb);
if(c>1)c=1; if(c<-1)c=-1; return c;
}
static double deuclid(const double* a, const double* b, int dim){
double s=0; for(int d=0;d<dim;d++){ double x=a[d]-b[d]; s+=x*x; } return sqrt(s);
}
/* mean cosine of members (minus gm) to centroid c (already gm-subtracted). */
static double cohesion(const VecSet* s, const float* gm, const double* c){
int dim=s->dim; double nc=dnorm(c,dim); if(nc<1e-12||s->n==0) return 0;
double acc=0; for(int i=0;i<s->n;i++){
double dot=0, nv=0;
for(int d=0;d<dim;d++){ double v=(double)s->v[i][d]-(gm?gm[d]:0.0); dot+=v*c[d]; nv+=v*v; }
nv=sqrt(nv); if(nv<1e-12) continue; double cc=dot/(nv*nc);
if(cc>1)cc=1; if(cc<-1)cc=-1; acc+=cc;
}
return acc/s->n;
}
/* mean pairwise cosine over a sample (isotropy metric). */
static double mean_pairwise_cos(const VecSet* s, const float* gm){
int dim=s->dim; if(s->n<2) return 0; double acc=0; long np=0;
for(int i=0;i<s->n;i++) for(int j=i+1;j<s->n;j++){
double dot=0, na=0, nb=0;
for(int d=0;d<dim;d++){ double a=(double)s->v[i][d]-(gm?gm[d]:0.0), b=(double)s->v[j][d]-(gm?gm[d]:0.0);
dot+=a*b; na+=a*a; nb+=b*b; }
na=sqrt(na); nb=sqrt(nb); if(na<1e-12||nb<1e-12) continue;
double c=dot/(na*nb); if(c>1)c=1; if(c<-1)c=-1; acc+=c; np++;
}
return np? acc/np : 0;
}
static void report(const char* label, Coh* c, const float* gm){
int dim=c->A.dim; double* ca=malloc((size_t)dim*sizeof(double)); double* cb=malloc((size_t)dim*sizeof(double));
mean_of(&c->A, gm, ca); mean_of(&c->B, gm, cb);
double xcos=dcos(ca,cb,dim), xeuc=deuclid(ca,cb,dim);
double cohA=cohesion(&c->A,gm,ca), cohB=cohesion(&c->B,gm,cb);
double overlap = (cohA>0&&cohB>0)? xcos/sqrt(cohA*cohB) : xcos;
double theta = acos(xcos<-1?-1:(xcos>1?1:xcos));
double sig = acos(cohA<-1?-1:(cohA>1?1:cohA)) + acos(cohB<-1?-1:(cohB>1?1:cohB));
double z = (sig>1e-9)? theta/sig : 0;
double mpc = mean_pairwise_cos(&c->S, gm);
printf(" [%s]\n", label);
printf(" cross-centroid cosine = %+.4f (lower = better separated)\n", xcos);
printf(" cross-centroid Euclid = %.4f (translation-invariant control)\n", xeuc);
printf(" intra-cohesion A / B = %.4f / %.4f\n", cohA, cohB);
printf(" OVERLAP operator = %.4f (~1 = indistinguishable, ~0 = clean)\n", overlap);
printf(" angular separation z = %.3f (centroid-angle / summed spread; >1 = separated)\n", z);
printf(" mean pairwise cosine = %+.4f (isotropy: ~0.55 anisotropic -> ~0 isotropic)\n", mpc);
free(ca); free(cb);
}
int main(int argc, char** argv){
const char* path = (argc>1)? argv[1] : getenv("ENGRAM_BENCH_STORE");
if(!path){ printf("SKIP: no store path (arg or ENGRAM_BENCH_STORE)\n"); return 0; }
EngramPagedStore* st=store_open(path);
if(!st){ printf("SKIP: could not open %s\n", path); return 0; }
Coh c; vs_init(&c.A); vs_init(&c.B); vs_init(&c.S); c.idx=0;
store_scan_nodes(st, cb, &c);
printf("=== two-domain discrimination bench (real store copy) ===\n");
printf("domain A (quantization) n=%d ; domain B (infrastructure) n=%d ; sample n=%d ; dim=%d\n",
c.A.n, c.B.n, c.S.n, c.A.dim);
if(c.A.n<3 || c.B.n<3){ printf("SKIP: a cohort is too small to be meaningful\n");
vs_free(&c.A); vs_free(&c.B); vs_free(&c.S); store_close(st); return 0; }
GeoMeanCache* mc=engram_geo_mean_build(st);
const float* gm=engram_geo_mean_vec(mc);
printf("global-mean cache: dim=%d over %llu embedded nodes\n\n",
engram_geo_mean_dim(mc), (unsigned long long)engram_geo_mean_count(mc));
printf("BEFORE (raw anisotropic unit space):\n");
report("RAW", &c, NULL);
printf("\nAFTER (mean-centered isotropic space):\n");
report("CENTERED", &c, gm);
engram_geo_mean_free(mc);
vs_free(&c.A); vs_free(&c.B); vs_free(&c.S);
store_close(st);
return 0;
}
engram/test/run_geometry_tests.sh
+9
View File
@@ -19,3 +19,12 @@ echo
echo "### PASS 2: SAFETY (ASan/UBSan)"
$CC $WARN -O1 -g -fsanitize=address,undefined -fno-omit-frame-pointer -I"$RT" $SRC -lm -o "$TMP/safe"
ASAN_OPTIONS=${ASAN_OPTIONS:-detect_leaks=0} UBSAN_OPTIONS=halt_on_error=1 "$TMP/safe"
# PASS 3 (OPTIONAL): mean-centering discrimination bench on a COPY of a real
# store. Skips cleanly unless ENGRAM_BENCH_STORE points at a store .egm — never
# touches the live store. Read-only; not part of the pass/fail gate.
echo
echo "### PASS 3: DISCRIMINATION BENCH (optional; set ENGRAM_BENCH_STORE)"
BSRC="$HERE/bench_discrimination.c $RT/engram_geometry.c $RT/engram_store.c $RT/engram_vindex.c"
$CC $WARN -O2 -I"$RT" $BSRC -lm -o "$TMP/bench"
"$TMP/bench" "${ENGRAM_BENCH_STORE:-}"
engram/test/test_geometry.c
+26 -8
View File
@@ -78,18 +78,31 @@ int main(void){
/* seed inside cluster A -> expect an A-dominated neighborhood */
st=store_open(path);
/* global-mean cache over the embedded set: the centering offset */
GeoMeanCache* mc=engram_geo_mean_build(st);
const float* gm=engram_geo_mean_vec(mc);
CHECK(mc!=NULL && engram_geo_mean_dim(mc)==DIM, "global-mean cache built over embedded set");
CHECK(engram_geo_mean_count(mc)==(uint64_t)(NA+NB), "global mean averaged all embedded nodes");
const char* seeds[1]={aids[0]};
GeoDescriptor* g=engram_geometry_descriptor(st, ix, ids, nids, seeds, 1, &P);
/* CENTERED descriptor: pass the global mean so geometry runs in isotropic space */
GeoDescriptor* g=engram_geometry_descriptor(st, ix, ids, nids, seeds, 1, &P, gm);
CHECK(g!=NULL, "descriptor computed");
if(g){
printf(" members=%d embedded=%d edges=%d k_core=%d radius=%.4f co_reg=%.3f n_axes=%d\n",
g->n_members,g->n_embedded,g->n_edges,g->k_core,g->radius,g->co_registration,g->n_axes);
/* centroid near cluster-A center (+e0): centroid[0] should dominate */
int argmax=0; for(int d=1;d<g->dim;d++) if(fabsf(g->centroid[d])>fabsf(g->centroid[argmax])) argmax=d;
printf(" centroid dominant axis = %d (expect 0), centroid[0]=%.3f centroid[1]=%.3f\n",
/* geometry ran in CENTERED space: g->centroid is the centered centroid,
* g->global_mean the applied offset. Reconstruct the raw prototype
* (centroid + global_mean) and check it sits on cluster-A's axis. */
CHECK(g->global_mean!=NULL, "descriptor recorded the centering offset (centered mode)");
int argmax=0; float best=-1.f;
for(int d=0;d<g->dim;d++){ float raw=g->centroid[d]+(g->global_mean?g->global_mean[d]:0.f);
if(fabsf(raw)>best){ best=fabsf(raw); argmax=d; } }
printf(" raw-prototype dominant axis = %d (expect 0); centered c[0]=%.3f c[1]=%.3f\n",
argmax, g->centroid[0], g->centroid[1]);
CHECK(argmax==0, "centroid sits on cluster-A's axis (near members)");
CHECK(argmax==0, "raw prototype sits on cluster-A's axis (near members)");
/* centering pushes A off cluster-B's axis: centered c[0] > c[1] */
CHECK(g->centroid[0] > g->centroid[1], "centered centroid leans off B's axis (isotropy)");
/* hub should be A0 (the intra-A hub with NA-1 strong edges) */
CHECK(g->hub_id && strcmp(g->hub_id,"A0")==0, "hub = the relational center A0");
@@ -128,12 +141,17 @@ int main(void){
engram_geo_free(g);
/* edge cases: NULL store, no seeds, relational-only (NULL vindex) */
CHECK(engram_geometry_descriptor(NULL,ix,ids,nids,seeds,1,&P)==NULL, "NULL store -> NULL");
CHECK(engram_geometry_descriptor(st,ix,ids,nids,seeds,0,&P)==NULL, "zero seeds -> NULL");
GeoDescriptor* g2=engram_geometry_descriptor(st, NULL, NULL, 0, seeds, 1, &P);
CHECK(engram_geometry_descriptor(NULL,ix,ids,nids,seeds,1,&P,gm)==NULL, "NULL store -> NULL");
CHECK(engram_geometry_descriptor(st,ix,ids,nids,seeds,0,&P,gm)==NULL, "zero seeds -> NULL");
GeoDescriptor* g2=engram_geometry_descriptor(st, NULL, NULL, 0, seeds, 1, &P, gm);
CHECK(g2!=NULL && g2->n_members>=NA-1, "relational-only path (no vindex) works");
engram_geo_free(g2);
/* raw (uncentered) mode still supported: global_mean=NULL -> no offset recorded */
GeoDescriptor* g3=engram_geometry_descriptor(st, ix, ids, nids, seeds, 1, &P, NULL);
CHECK(g3!=NULL && g3->global_mean==NULL, "raw mode (global_mean=NULL) leaves offset unset");
engram_geo_free(g3);
engram_geo_mean_free(mc);
for(int i=0;i<nids;i++) free(ids[i]); free(ids);
vindex_free(ix); store_close(st); unlink(path);
printf("\n=== %s ===\n", g_fail?"FAILURES PRESENT":"ALL TESTS PASSED");