ó
    º.›jê  ã                  óŽ   • S r SSKJr  SSKJr  SSKrSrSr\ " S S5      5       r	S	 r
SS
 jrSS jrSS jrS rSSS.S jrS rg)aB  
Chronology-safe common-coordinate construction for Suite19.

Why this exists
---------------
Each prequential window fits an independent supervised encoder E_t. Raw latent
axis j from E_t has no guarantee of corresponding to axis j from E_{t+1}.

For global OOF probes we therefore do NOT concatenate raw latent coordinates.

Instead, every fitted encoder re-embeds the SAME fixed historical anchor rows.
We whiten that model-specific anchor cloud and express query rows by cosine
similarities to the SAME fixed anchor-landmark identities.

If two native representations differ by an invertible affine
reparameterization, whitening leaves only an orthogonal gauge; pairwise
dot-products/cosines to the same landmark identities are invariant to that
remaining orthogonal transform.

No labels are used to choose anchors or landmarks.
é    )Úannotations)Ú	dataclassNÚanchor_whitened_landmark_v1é   c                  ó„   • \ rS rSr% S\S'   S\S'   S\S'   S\S'   S\S'   S	\S
'   S	\S'   S	\S'   S	\S'   S	\S'   S	\S'   Srg)ÚCoordinateDiagnosticsé    ÚstrÚcoordinate_systemÚintÚanchor_rowsÚlandmark_rowsÚ
native_dimÚwhiten_rankÚfloatÚcovariance_conditionÚmin_eigenvalue_keptÚmax_eigenvalueÚraw_procrustes_r2Úraw_procrustes_nrmseÚraw_procrustes_mean_cosine© N)Ú__name__Ú
__module__Ú__qualname__Ú__firstlineno__Ú__annotations__Ú__static_attributes__r   ó    Úsuite19_coordinates.pyr   r       sC   ‡ àÓØÓØÓØƒOØÓØÓØÓØÓØÓØÓØ %Ö%r   r   c                ó  • [         R                  " U [         R                  S9n[         R                  " U5      n[        U5      [	        U5      ::  a  [         R
                  " U5      $ [         R                  R                  [	        U5      5      n[        [         R                  " XT   5      R                  5       [        S9n/ n[        S[	        [         R                  " [	        U5      [        [        U5      S5      -  5      5      5      n	U H‡  n
XEU   U
:H     n[        U5      U	::  a!  UR                  UR                  5       5        M=  UR                  UR                  X¹SS9R!                  [         R                  5      R                  5       5        M‰     [         R                  " [         R                  " U[         R                  S95      n[        U5      [	        U5      :”  aL  [         R
                  " UR                  U[	        U5      SS9R!                  [         R                  5      5      nO¶[        U5      [	        U5      :  až  [         R"                  " XHSS9n[%        [	        U5      [        U5      -
  [        U5      5      nU(       aX  UR                  XÍSS9R!                  [         R                  5      n[         R
                  " [         R&                  " XŽ/5      5      nUR!                  [         R                  5      $ )z8Deterministic faculty-balanced sampling. Does not use y.©Údtype)Úkeyr   F)ÚsizeÚreplace)Úassume_unique)ÚnpÚasarrayÚint64Úlenr   ÚsortÚrandomÚdefault_rngÚsortedÚuniqueÚtolistr
   ÚmaxÚceilÚextendÚchoiceÚastypeÚ	setdiff1dÚminÚconcatenate)ÚindicesÚfacultyÚnÚseedÚidxÚfacÚrngÚgroupsÚchosenÚperÚgÚgiÚremainÚneedÚextras                  r    Ú_balanced_samplerI   /   s	  € ä
�*Š*�W¤B§H¡HÑ
-€CÜ
�*Š*�WÓ
€Cä
ˆ3ƒx”3�q“6ÓÜ�wŠw�s‹|Ðä
�)‰)×
Ñ
¤ D£	Ó
*€CÜ”B—I’I˜c™hÓ'×.Ñ.Ó0´cÑ:€Fà€FÜ
ˆa””R—W’WœS ›V¤c¬#¨f«+°qÓ&9Ñ9Ó:Ó;Ó
<€CãˆØ�S‘˜Q‘ÑˆÜˆr‹7�c‹>Ø�M‰M˜"Ÿ)™)›+Ö&à�M‰MØ—
‘
˜2°�
Ð7×>Ñ>¼r¿x¹xÓH×OÑOÓQöñ ô �YŠY”r—z’z &´·±Ñ9Ó:€Fä
ˆ6ƒ{”S˜“VÓÜ—’Ø�J‰J�v¤C¨£F°EˆJÐ:×AÑAÄ"Ç(Á(ÓKó
‰ô 
ˆV‹”s˜1“vÓ	Ü—’˜c¸Ñ?ˆÜ”3�q“6œC ›KÑ'¬¨V«Ó5ˆÞØ—J‘J˜v¸%�JÐ@×GÑGÌÏÉÓQˆEÜ—W’WœRŸ^š^¨V¨OÓ<Ó=ˆFà�=‰=œŸ™Ó"Ð"r   c           
     ó
  • [         R                  " U [         R                  S9n[        U5      S:X  a  [	        S5      e[        U[         R                  " U5      [        [        U5      [        U5      5      [        U5      5      $ )z
Choose fixed historical anchor identities from the first legal training
prefix. Selection is label-free and faculty-balanced.
r"   r   z8cannot establish common coordinate frame without history)r(   r)   r*   r+   Ú
ValueErrorrI   r8   r   )Útrain_indicesr;   Úmax_rowsr=   Útrs        r    Úselect_anchor_rowsrO   V   sd   € ô
 
�Š�M¬¯©Ñ	2€BÜ
ˆ2ƒw�!ƒ|ÜÐSÓTÐTäØ
Ü
�
Š
�7ÓÜŒC�‹Mœ3˜r›7Ó#ÜˆD‹	ó	ð r   c                ó|  • [         R                  " U [         R                  S9n [        U 5      [	        U5      :  a  [        SU S[        U 5       35      e[         R                  " [        U 5      [         R                  S9n[         R                  " U5      U    n[        UU[	        U5      [	        U5      S-   5      $ )z?
Select positions INSIDE anchor_indices, again without labels.
r"   zneed >= z anchors, got iï  )r(   r)   r*   r+   r   rK   ÚarangerI   )Úanchor_indicesr;   Ún_landmarksr=   Ú	positionsÚafs         r    Úselect_landmark_positionsrV   g   s¢   € ô —Z’Z ´b·h±hÑ?€Nä
ˆ>ÓœS Ó-Ó-ÜØ�{�m >´#°nÓ2EÐ1FÐGó
ð 	
ô —	’	œ#˜nÓ-´R·X±XÑ>€IÜ	�Š�GÓ	˜^Ñ	,€BäØØ
ÜˆKÓÜˆD‹	�DÑó	ð r   çñhãˆµøä>çH¯¼šò×z>c           	     ó‚  • [         R                  " U [         R                  S9nUR                  S:w  d  [	        U5      S:  a  [        S5      e[         R                  " U5      R                  5       (       d  [        S5      eUR                  SS9nX4-
  n[        [	        U5      S-
  S5      nUR                  U-  U-  nXwR                  -   S	-  n[         R                  R                  U5      u  p‰[         R                  " U5      S S S
2   n
XŠ   nU	S S 2U
4   n	[	        U5      (       a  [        [        US   S5      5      OSn[        [        U5      U[        U5      -  5      nXŒ:„  n[        [         R                   " U5      5      nUS:  a  [#        SU 35      eX�   nU	S S 2U4   nU[         R$                  " US S S 24   [        U5      -   5      -  n[        UR                  5       [        UR'                  5       S5      -  5      nUUUU[        UR'                  5       5      [        UR                  5       5      S.4$ )Nr"   é   é   z*anchor latent matrix must be non-empty 2-Dz'non-finite anchor latent representationr   ©Úaxisr   g      à?éÿÿÿÿg        z,common-coordinate whitening collapsed: rank=çê-�™—q=)r   r   r   r   )r(   r)   Úfloat64Úndimr+   rK   ÚisfiniteÚallÚmeanr2   ÚTÚlinalgÚeighÚargsortr   r   ÚsumÚRuntimeErrorÚsqrtr8   )Úanchor_zÚridgeÚrank_tolÚAÚmuÚCÚdenomÚcovÚeigvalÚeigvecÚorderÚvmaxÚ	thresholdÚkeepÚrankÚvalsÚvecsÚWÚ	conditions                      r    Ú_whiten_fitr   }   sè  € Ü
�
Š
�8¤2§:¡:Ñ.€Aà‡v�v�ƒ{”c˜!“f˜q“jÜÐEÓFÐFä�;Š;�q‹>×Ñ×ÑÜÐBÓCÐCà	
�‰�Qˆˆ€BØ	‰€Aä”�A“˜‘
˜AÓ€EØ�3‰3�‰7�eÑ
€CØ—‘‰;˜#Ñ
€Cä—Y‘Y—^‘^ CÓ(�N€FÜ�JŠJ�vÓ™t ˜tÑ$€EØ‰]€FØ’A�u�HÑ€Fä),¨V¯©Œ5”�V˜A‘Y Ó$Ô%¸#€DÜ”E˜%“L $¬¨x«Ñ"8Ó9€IàÑ€DÜŒr�vŠv�d‹|Ó€DàˆaƒxÜØ:¸4¸&ÐAó
ð 	
ð ‰<€DØ’!�T�'‰?€DàŒr�wŠw�t˜D¢!˜G‘}¤u¨U£|Ñ3Ó4Ñ4€Aä�d—h‘h“j¤3 t§x¡x£z°5Ó#9Ñ9Ó:€IàˆqØØ )Ü$ T§X¡X£ZÓ0Ü §¡£
Ó+ñ	ð ð r   c                óº   • [         R                  " U [         R                  S9n [         R                  R	                  U SSS9nU [         R
                  " US5      -  $ )Nr"   r   T)r]   Úkeepdimsr_   )r(   r)   r`   rf   ÚnormÚmaximum)ÚXr<   s     r    Ú
_unit_rowsr…   ¬   sD   € Ü
�
Š
�1œBŸJ™JÑ'€AÜ
�	‰	�‰�q˜q¨4ˆÐ0€AØŒr�zŠz˜!˜UÓ#Ñ#Ð#r   ©rm   rn   c               ó¸  • [         R                  " U [         R                  S9n[         R                  " U[         R                  S9n[         R                  " U[         R                  S9nUR                  S:w  d  UR                  S:w  a  [        S5      eUR                  S   UR                  S   :w  a  [        S5      e[         R                  " U5      R                  5       (       d  [        S5      e[         R                  " US:  5      (       d'  [         R                  " U[        U5      :¬  5      (       a  [        S5      e[        XSUS	9u  p‰n
XX-
  U	-  nXh-
  U	-  n[        U5      n[        U5      nX·   nXÍR                  -  n[         R                  " U5      R                  5       (       d  [        S
5      eUR                  [         R                   5      U
4$ )zz
Convert a model-specific latent representation to common coordinates.

Output dimension = number of landmark identities.
r"   rZ   z&anchor/query latent arrays must be 2-Dr   z,anchor/query native latent dimensions differz/query representation contains non-finite valuesr   zinvalid landmark positionsr†   z0canonical landmark coordinates became non-finite)r(   r)   r`   r*   ra   rK   Úshaperb   rc   Úanyr+   r   r…   re   rj   r6   Úfloat32)rl   Úquery_zÚlandmark_positionsrm   rn   ro   ÚQÚlprp   r}   ÚdiagÚAwÚQwÚLÚZs                  r    Úlandmark_coordinatesr”   ²   sa  € ô 	�
Š
�8¤2§:¡:Ñ.€AÜ
�
Š
�7¤"§*¡*Ñ-€AÜ	�ŠÐ&¬b¯h©hÑ	7€Bà‡v�v�ƒ{�a—f‘f “kÜÐAÓBÐBØ‡w�wˆq�z�Q—W‘W˜Q‘ZÓÜÐGÓHÐHÜ�;Š;�q‹>×Ñ×ÑÜÐJÓKÐKÜ	‡v‚vˆb�1‰f‡~�~œŸš ¤c¨!£f¡×-Ñ-ÜÐ5Ó6Ð6ä˜a°xÑ@�K€Bˆ4à
‰&�A‰€BØ
‰&�A‰€Bä	�B‹€BÜ	�B‹€Bà
‰€AØ
�S‰S‰€Aä�;Š;�q‹>×Ñ×ÑÜÐMÓNÐNà�8‰8”B—J‘JÓ Ð%Ð%r   c           	     óÄ  • U c0  [         R                  [         R                  [         R                  S.$ [         R                  " U [         R                  S9n[         R                  " U[         R                  S9nUR                  UR                  :w  d  UR
                  S:w  d  [        U5      S:  a0  [         R                  [         R                  [         R                  S.$ X"R                  S5      -
  nX3R                  S5      -
  n[         R                  R                  U5      n[         R                  R                  U5      nUS:  d  US:  a0  [         R                  [         R                  [         R                  S.$ XF-  nXW-  n[         R                  R                  UR                  U-  SS9u  p‰n
XŠ-  nX[-  n[         R                  " XL-
  S-  5      n[         R                  " XDR                  S5      -
  S-  5      nS	U[        US5      -  -
  n[         R                  " [         R                  " XL-
  S-  5      5      [        [         R                  " [         R                  " US-  5      5      S5      -  n[        U5      n[        U5      n[         R                  " UU-  S
S9n[!        U5      [!        U5      [!        [         R                  " U5      5      S.$ )zH
Diagnostic only. Never used to create the canonical probe coordinates.
)r   r   r   r"   rZ   r[   r   r_   F)Úfull_matricesg      ð?r   r\   )r(   Únanr)   r`   rˆ   ra   r+   rd   rf   r‚   Úsvdre   ri   r2   rk   r…   r   )Úreference_anchor_zÚcurrent_anchor_zro   ÚBÚAcÚBcÚsaÚsbÚUÚ_ÚVtÚRÚBalignedÚerrrr   Úr2ÚnrmseÚauÚbuÚcoss                       r    Úprocrustes_diagnosticsr«   Ý   s(  € ð Ñ!ä!#§¡Ü$&§F¡FÜ*,¯&©&ñ
ð 	
ô 	�
Š
Ð%¬R¯Z©ZÑ8€AÜ
�
Š
Ð#¬2¯:©:Ñ6€Aà‡w�w�!—'‘'Ó˜QŸV™V q›[¬C°«F°Q«Jä!#§¡Ü$&§F¡FÜ*,¯&©&ñ
ð 	
ð 
�V‰V�A‹Y‰€BØ	
�V‰V�A‹Y‰€Bä	�‰�‰˜Ó	€BÜ	�‰�‰˜Ó	€Bà	ˆEƒz�R˜%“Zä!#§¡Ü$&§F¡FÜ*,¯&©&ñ
ð 	
ð 
‰€BØ	‰€Bä�y‰y�}‰}˜RŸT™T B™Y°eˆ}Ð<�H€Aˆ"Ø	‰€AØ‰v€Hä
�&Š&�"‘- AÑ%Ó
&€CÜ�FŠF�BŸ™ ›‘O¨Ñ)Ó*€Eà	ˆs”S˜ Ó&Ñ&Ñ	&€BÜ�GŠG”B—G’G˜R™]¨qÑ0Ó1Ó2´SÜ
�Š”—’˜˜a™Ó Ó! 5ó6ñ €Eô 
�B‹€BÜ	�HÓ	€BÜ
�&Š&��b‘˜qÑ
!€Cô # 2›YÜ % e£Ü&+¬B¯GªG°C«LÓ&9ñð r   )i   é)(5)r¬   )rW   rX   )Ú__doc__Ú
__future__r   Údataclassesr   Únumpyr(   ÚCOORDINATE_SYSTEMÚCOORDINATE_VERSIONr   rI   rO   rV   r   r…   r”   r«   r   r   r    Ú<module>r³      sh   ðñõ* #å !Û à1Ð ØÐ ð ÷&ð &ó ð&ò$#ôNô"ô,,ò^$ð Øõ(&óV9r   