openchemlib-search-wasm 1.2.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/README.md +290 -3
  2. package/lib/functionKeys/dictionary.json +72071 -0
  3. package/lib/functionKeys/index.d.ts +105 -0
  4. package/lib/functionKeys/index.d.ts.map +1 -0
  5. package/lib/functionKeys/index.js +98 -0
  6. package/lib/functionKeys/index.js.map +1 -0
  7. package/lib/functions.d.ts +38 -0
  8. package/lib/functions.d.ts.map +1 -0
  9. package/lib/functions.js +54 -0
  10. package/lib/functions.js.map +1 -0
  11. package/lib/hex.d.ts +31 -0
  12. package/lib/hex.d.ts.map +1 -0
  13. package/lib/hex.js +41 -0
  14. package/lib/hex.js.map +1 -0
  15. package/lib/index.d.ts +140 -2
  16. package/lib/index.d.ts.map +1 -1
  17. package/lib/index.js +184 -7
  18. package/lib/index.js.map +1 -1
  19. package/lib/records.d.ts +45 -0
  20. package/lib/records.d.ts.map +1 -0
  21. package/lib/records.js +96 -0
  22. package/lib/records.js.map +1 -0
  23. package/lib/scan.d.ts +99 -7
  24. package/lib/scan.d.ts.map +1 -1
  25. package/lib/scan.js +158 -11
  26. package/lib/scan.js.map +1 -1
  27. package/lib/strongHash.d.ts +9 -0
  28. package/lib/strongHash.d.ts.map +1 -0
  29. package/lib/strongHash.js +56 -0
  30. package/lib/strongHash.js.map +1 -0
  31. package/lib/substructureSearch.d.ts +8 -5
  32. package/lib/substructureSearch.d.ts.map +1 -1
  33. package/lib/substructureSearch.js +28 -5
  34. package/lib/substructureSearch.js.map +1 -1
  35. package/lib/types.d.ts +120 -3
  36. package/lib/types.d.ts.map +1 -1
  37. package/lib/types.js +17 -1
  38. package/lib/types.js.map +1 -1
  39. package/lib/wasm/load.d.ts.map +1 -1
  40. package/lib/wasm/load.js +9 -1
  41. package/lib/wasm/load.js.map +1 -1
  42. package/lib/wasm/log.d.ts +36 -0
  43. package/lib/wasm/log.d.ts.map +1 -0
  44. package/lib/wasm/log.js +52 -0
  45. package/lib/wasm/log.js.map +1 -0
  46. package/package.json +6 -3
  47. package/src/functionKeys/index.ts +181 -0
  48. package/src/functions.ts +56 -0
  49. package/src/hex.ts +43 -0
  50. package/src/index.ts +269 -5
  51. package/src/records.ts +142 -0
  52. package/src/scan.ts +259 -16
  53. package/src/strongHash.ts +57 -0
  54. package/src/substructureSearch.ts +29 -6
  55. package/src/types.ts +171 -2
  56. package/src/wasm/load.ts +10 -1
  57. package/src/wasm/log.ts +66 -0
  58. package/wasm/data.js +1 -1
  59. package/wasm/runtime.d.ts +6 -0
package/src/scan.ts CHANGED
@@ -1,5 +1,12 @@
1
1
  import type { ResultBuffer, SearchMode } from './types.ts';
2
- import { SimilarityResult, SubstructureResult } from './types.ts';
2
+ import {
3
+ DEFAULT_MAX_TAUTOMERS,
4
+ INDEX_WORDS,
5
+ NO_HASH,
6
+ NO_ID_CODE,
7
+ SimilarityResult,
8
+ SubstructureResult,
9
+ } from './types.ts';
3
10
  import { loadOCL } from './wasm/load.ts';
4
11
 
5
12
  // Top-level await: the WASM module is instantiated when this module is imported, so the searches are
@@ -122,9 +129,8 @@ function firstPending(
122
129
  /**
123
130
  * Fingerprints `idCodes[from .. to)` into `result`, sixteen words per molecule.
124
131
  *
125
- * Unlike the searches, a malformed idcode needs no recovery here: the WASM side writes sixteen
126
- * zeros for it and carries on, because a fingerprint no query can be a subset of is the safe answer
127
- * for a molecule that could not be read.
132
+ * A molecule that cannot be read gets sixteen zeros, which no non-empty query is a subset of, so it
133
+ * is never a false candidate.
128
134
  * @param idCodes - The molecules to fingerprint.
129
135
  * @param result - The caller's buffer, `16 * idCodes.length` words long.
130
136
  * @param from - The first index to fingerprint.
@@ -137,20 +143,117 @@ export function buildIndexes(
137
143
  from: number,
138
144
  to: number,
139
145
  ): number {
140
- return Search.getIndexes(idCodes, result, from, to);
146
+ return recoveringFromTraps(
147
+ (first, last) => Search.getIndexes(idCodes, result, first, last),
148
+ (index) => result.fill(0, index * INDEX_WORDS, (index + 1) * INDEX_WORDS),
149
+ from,
150
+ to,
151
+ );
152
+ }
153
+
154
+ /**
155
+ * Screens `idCodes[from .. to)` into `result`, sixteen words per molecule.
156
+ *
157
+ * Fails like {@link buildIndexes}: sixteen zeros for an idcode the WASM side cannot read.
158
+ * @param idCodes - The molecules to screen.
159
+ * @param result - The caller's buffer, `16 * idCodes.length` words long.
160
+ * @param from - The first index to screen.
161
+ * @param to - One past the last index to screen.
162
+ * @returns How many molecules were parsed and screened.
163
+ */
164
+ export function buildScreens(
165
+ idCodes: string[],
166
+ result: Int32Array,
167
+ from: number,
168
+ to: number,
169
+ ): number {
170
+ return Search.getScreens(idCodes, result, from, to);
171
+ }
172
+
173
+ /**
174
+ * Builds the function bits of `idCodes[from .. to)` into `result`, sixteen words per molecule.
175
+ *
176
+ * Fails like {@link buildIndexes}: sixteen zeros for an idcode the WASM side cannot read.
177
+ * @param idCodes - The molecules to read.
178
+ * @param result - The caller's buffer, `16 * idCodes.length` words long.
179
+ * @param from - The first index to read.
180
+ * @param to - One past the last index to read.
181
+ * @returns How many molecules were parsed and read.
182
+ */
183
+ export function buildFunctions(
184
+ idCodes: string[],
185
+ result: Int32Array,
186
+ from: number,
187
+ to: number,
188
+ ): number {
189
+ return recoveringFromTraps(
190
+ (first, last) => Search.getFunctions(idCodes, result, first, last),
191
+ (index) => result.fill(0, index * INDEX_WORDS, (index + 1) * INDEX_WORDS),
192
+ from,
193
+ to,
194
+ );
195
+ }
196
+
197
+ /**
198
+ * Reads the fragments of the 512 stored function keys, in bit order.
199
+ * @returns Per key, its fragment idcodes.
200
+ */
201
+ export function readFunctionKeys(): string[][] {
202
+ return Search.getFunctionKeys()
203
+ .split('\n')
204
+ .map((key) => key.split(' '));
205
+ }
206
+
207
+ /**
208
+ * Builds what every molecule a query matches has: its FragFp words, or its screen words.
209
+ * @param kind - `'index'` for the FragFp words, `'screen'` for the screen words.
210
+ * @param idCodeQuery - The query, as an idcode.
211
+ * @returns Sixteen words.
212
+ * @throws {Error} If the query cannot be parsed.
213
+ */
214
+ export function buildQueryWords(
215
+ kind: 'index' | 'screen',
216
+ idCodeQuery: string,
217
+ ): Int32Array {
218
+ const result = new Int32Array(INDEX_WORDS);
219
+ try {
220
+ if (kind === 'index') {
221
+ Search.getQueryIndex(idCodeQuery, result);
222
+ } else {
223
+ Search.getQueryScreen(idCodeQuery, result);
224
+ }
225
+ } catch (error) {
226
+ throw new Error(`"${idCodeQuery}" is not a valid query idcode`, {
227
+ cause: error,
228
+ });
229
+ }
230
+ return result;
231
+ }
232
+
233
+ /**
234
+ * Reads the key fragments behind the bits of the FragFp words, or of the screen words.
235
+ * @param kind - `'index'` for FragFp's keys, `'screen'` for the screen's.
236
+ * @returns 512 idcodes, in bit order.
237
+ */
238
+ export function readKeys(kind: 'index' | 'screen'): string[] {
239
+ const joined =
240
+ kind === 'index' ? Search.getFragFpKeys() : Search.getScreenKeys();
241
+ return joined.split('\n');
141
242
  }
142
243
 
143
244
  /**
144
245
  * Hashes `idCodes[from .. to)` into `result`, one no-stereo tautomer hash per molecule.
145
246
  *
146
- * Like the fingerprints and unlike the searches, a malformed idcode needs no recovery here: the
147
- * WASM side writes `0` for one it cannot read and carries on, and `0` is also what OpenChemLib
148
- * returns for a molecule it cannot canonize, so the two failures are reported the same way.
247
+ * A molecule that cannot be read gets `NO_HASH`, which is also what OpenChemLib returns for one it
248
+ * cannot canonize, so the two failures are reported the same way.
149
249
  * @param idCodes - The molecules to hash.
150
250
  * @param result - The caller's buffer, `idCodes.length` entries long.
151
251
  * @param largestFragmentOnly - Whether to strip and neutralize down to the largest fragment first.
152
252
  * @param from - The first index to hash.
153
253
  * @param to - One past the last index to hash.
254
+ * @param tautomerCounts - Filled with how many tautomers each molecule needed; an entry that reached
255
+ * `maxTautomers` is one OpenChemLib stopped early on.
256
+ * @param maxTautomers - The ceiling on that enumeration, which is what bounds the cost.
154
257
  * @returns How many molecules were hashed.
155
258
  */
156
259
  export function buildNoStereoTautomerHashes(
@@ -159,11 +262,23 @@ export function buildNoStereoTautomerHashes(
159
262
  largestFragmentOnly: boolean,
160
263
  from: number,
161
264
  to: number,
265
+ tautomerCounts: Int32Array = new Int32Array(idCodes.length),
266
+ maxTautomers: number = DEFAULT_MAX_TAUTOMERS,
162
267
  ): number {
163
- return Search.getNoStereoTautomerHashes(
164
- idCodes,
165
- result,
166
- largestFragmentOnly,
268
+ return recoveringFromTraps(
269
+ (first, last) =>
270
+ Search.getNoStereoTautomerHashes(
271
+ idCodes,
272
+ result,
273
+ tautomerCounts,
274
+ largestFragmentOnly,
275
+ maxTautomers,
276
+ first,
277
+ last,
278
+ ),
279
+ (index) => {
280
+ result[index] = NO_HASH;
281
+ },
167
282
  from,
168
283
  to,
169
284
  );
@@ -188,11 +303,139 @@ export function buildNoStereoHashes(
188
303
  from: number,
189
304
  to: number,
190
305
  ): number {
191
- return Search.getNoStereoHashes(
192
- idCodes,
193
- result,
194
- largestFragmentOnly,
306
+ return recoveringFromTraps(
307
+ (first, last) =>
308
+ Search.getNoStereoHashes(
309
+ idCodes,
310
+ result,
311
+ largestFragmentOnly,
312
+ first,
313
+ last,
314
+ ),
315
+ (index) => {
316
+ result[index] = NO_HASH;
317
+ },
195
318
  from,
196
319
  to,
197
320
  );
198
321
  }
322
+
323
+ /**
324
+ * Canonizes `idCodes[from .. to)` into `result`, one no-stereo idcode per molecule.
325
+ *
326
+ * This is the string {@link buildNoStereoHashes} hashes, for a caller that stores the canonical form
327
+ * rather than a 64-bit key. A molecule that cannot be read keeps the `NO_ID_CODE` the caller's array
328
+ * was filled with.
329
+ * @param idCodes - The molecules to canonize.
330
+ * @param result - The caller's array, `idCodes.length` entries long, filled with `NO_ID_CODE`.
331
+ * @param largestFragmentOnly - Whether to strip and neutralize down to the largest fragment first.
332
+ * @param from - The first index to canonize.
333
+ * @param to - One past the last index to canonize.
334
+ * @returns How many molecules were canonized.
335
+ */
336
+ export function buildNoStereoIdCodes(
337
+ idCodes: string[],
338
+ result: string[],
339
+ largestFragmentOnly: boolean,
340
+ from: number,
341
+ to: number,
342
+ ): number {
343
+ return recoveringFromTraps(
344
+ (first, last) =>
345
+ Search.getNoStereoIdCodes(
346
+ idCodes,
347
+ result,
348
+ largestFragmentOnly,
349
+ first,
350
+ last,
351
+ ),
352
+ (index) => {
353
+ result[index] = NO_ID_CODE;
354
+ },
355
+ from,
356
+ to,
357
+ );
358
+ }
359
+
360
+ /**
361
+ * Canonizes `idCodes[from .. to)` into `result`, one no-stereo generic-tautomer idcode per molecule.
362
+ *
363
+ * Fails the same way {@link buildNoStereoIdCodes} does.
364
+ * @param idCodes - The molecules to canonize.
365
+ * @param result - The caller's array, `idCodes.length` entries long, filled with `NO_ID_CODE`.
366
+ * @param largestFragmentOnly - Whether to strip and neutralize down to the largest fragment first.
367
+ * @param from - The first index to canonize.
368
+ * @param to - One past the last index to canonize.
369
+ * @param tautomerCounts - Filled with how many tautomers each molecule needed; an entry that reached
370
+ * `maxTautomers` is one OpenChemLib stopped early on.
371
+ * @param maxTautomers - The ceiling on that enumeration, which is what bounds the cost.
372
+ * @returns How many molecules were canonized.
373
+ */
374
+ export function buildNoStereoTautomerIdCodes(
375
+ idCodes: string[],
376
+ result: string[],
377
+ largestFragmentOnly: boolean,
378
+ from: number,
379
+ to: number,
380
+ tautomerCounts: Int32Array = new Int32Array(idCodes.length),
381
+ maxTautomers: number = DEFAULT_MAX_TAUTOMERS,
382
+ ): number {
383
+ return recoveringFromTraps(
384
+ (first, last) =>
385
+ Search.getNoStereoTautomerIdCodes(
386
+ idCodes,
387
+ result,
388
+ tautomerCounts,
389
+ largestFragmentOnly,
390
+ maxTautomers,
391
+ first,
392
+ last,
393
+ ),
394
+ (index) => {
395
+ result[index] = NO_ID_CODE;
396
+ },
397
+ from,
398
+ to,
399
+ );
400
+ }
401
+
402
+ /**
403
+ * Runs a ranged WASM call, and redoes the range one molecule at a time if it traps.
404
+ *
405
+ * A malformed idcode makes OpenChemLib's bit-stream parser read past its input, which WebAssembly
406
+ * traps on — the same trap {@link scanRange} recovers from. The Java guard catches an empty or
407
+ * non-ASCII idcode, but a malformed ASCII one reaches the parser and traps there, which would
408
+ * otherwise lose every molecule in the range including the good ones. The trap leaves the module
409
+ * usable, and a per-molecule call costs what a batched one does because the 512 key fragments are
410
+ * parsed once for the module's lifetime, so redoing the range singly costs nothing that was not
411
+ * already going to be spent.
412
+ *
413
+ * There is no cap on the failures: these functions promise a per-molecule "could not read this"
414
+ * answer rather than an exception, so an array that is entirely garbage yields one of those per
415
+ * entry.
416
+ * @param call - Runs the WASM call over a range, returning how many molecules it handled.
417
+ * @param markUnreadable - Writes the "could not read this" answer for one molecule.
418
+ * @param from - The first index to handle.
419
+ * @param to - One past the last index to handle.
420
+ * @returns How many molecules were handled.
421
+ */
422
+ export function recoveringFromTraps(
423
+ call: (from: number, to: number) => number,
424
+ markUnreadable: (index: number) => void,
425
+ from: number,
426
+ to: number,
427
+ ): number {
428
+ try {
429
+ return call(from, to);
430
+ } catch {
431
+ let handled = 0;
432
+ for (let index = from; index < to; index++) {
433
+ try {
434
+ handled += call(index, index + 1);
435
+ } catch {
436
+ markUnreadable(index);
437
+ }
438
+ }
439
+ return handled;
440
+ }
441
+ }
@@ -0,0 +1,57 @@
1
+ /**
2
+ * OpenChemLib's 64-bit StrongHasher, which is how every `CanonizerUtil` hash is defined: the
3
+ * molecule is reduced to a canonical idcode, and that string is hashed. `openchemlib` exposes the
4
+ * canonical forms but not the hasher, so this is its `CanonizerUtil.StrongHasher` transcribed.
5
+ *
6
+ * It is here so a caller that already holds a canonical idcode — one of this package's, or a column
7
+ * of them in a database — can get its hash without canonizing again. That matters because
8
+ * canonizing a generic tautomer is the most expensive thing this package does, and asking for both
9
+ * the idcode and the hash would otherwise pay for it twice.
10
+ *
11
+ * ```js
12
+ * strongHash(getNoStereoTautomerIdCode(idCode)) === getNoStereoTautomerHash(idCode);
13
+ * ```
14
+ */
15
+ const MASK_64 = (1n << 64n) - 1n;
16
+ const HSTART = 0xbb40e64da205b064n;
17
+ const HMULT = 7664345821815920749n;
18
+ const BYTE_TABLE = buildByteTable();
19
+
20
+ /**
21
+ * `openchemlib-js` exposes `CanonizerUtil.getIDCode` but not the hash built from it, so the hash
22
+ * tests hash that idcode here. This is OpenChemLib's `StrongHasher.hash` transcribed, and having it
23
+ * written a second way is what makes those comparisons a real cross-check.
24
+ * @param text - The idcode to hash.
25
+ * @returns Its 64-bit hash, signed, as a `BigInt64Array` entry holds it.
26
+ */
27
+ export function strongHash(text: string): bigint {
28
+ let h = HSTART;
29
+ for (let i = text.length - 1; i >= 0; i--) {
30
+ const character = BigInt(text.codePointAt(i) as number);
31
+ h =
32
+ ((h * HMULT) & MASK_64) ^
33
+ (BYTE_TABLE[Number(character & 0xffn)] as bigint);
34
+ h =
35
+ ((h * HMULT) & MASK_64) ^
36
+ (BYTE_TABLE[Number((character >> 8n) & 0xffn)] as bigint);
37
+ }
38
+ return BigInt.asIntN(64, h);
39
+ }
40
+
41
+ /**
42
+ * OpenChemLib's `CanonizerUtil.StrongHasher` byte table, built the same way the Java does.
43
+ * @returns The 256 seeds, as unsigned 64-bit values.
44
+ */
45
+ function buildByteTable(): bigint[] {
46
+ const table = new Array<bigint>(256);
47
+ let h = 0x544b2fbacaaf1684n;
48
+ for (let i = 0; i < 256; i++) {
49
+ for (let j = 0; j < 31; j++) {
50
+ h = ((h >> 7n) ^ h) & MASK_64;
51
+ h = ((h << 11n) ^ h) & MASK_64;
52
+ h = ((h >> 10n) ^ h) & MASK_64;
53
+ }
54
+ table[i] = h;
55
+ }
56
+ return table;
57
+ }
@@ -7,7 +7,8 @@ import type {
7
7
  import { SubstructureResult } from './types.ts';
8
8
 
9
9
  /**
10
- * Tests a query fragment against many molecules and returns the ones that contain it.
10
+ * Tests a query fragment, or any of several, against many molecules and returns the ones that
11
+ * contain it.
11
12
  *
12
13
  * The entries are either idcodes or objects carrying one — a database row, a candidate a prescreen
13
14
  * yielded — and what comes back is those same objects, so nothing has to map positions back onto
@@ -17,20 +18,22 @@ import { SubstructureResult } from './types.ts';
17
18
  * The scan is synchronous. `onStep` reports it and can stop it, but the thread is not yielded:
18
19
  * a caller that needs a responsive main thread slices the array across calls, or runs this in a
19
20
  * worker.
20
- * @param idCodeQuery - The query, as an idcode. It is searched as a fragment whatever its own
21
+ * @param idCodeQuery - The query, as an idcode, or several: a molecule then matches when it holds
22
+ * any of them, which is how a function key of `openchemlib-search-wasm/function-keys` is searched
23
+ * (`substructureSearch(key.fragments, entries)`). Each is searched as a fragment whatever its own
21
24
  * fragment flag says, which is what `openchemlib`'s `SSSearcher` does with `setFragment(true)`.
22
25
  * @param entries - The molecules to test: idcodes, or objects holding one at `options.jpath`.
23
26
  * @param options - Where the idcode sits, how many matches are enough, and how to report progress.
24
27
  * @returns The matching entries, their positions, the status buffer and the counts.
25
- * @throws {Error} If the query cannot be parsed, if more than 100 idcodes cannot be, or if no entry
26
- * holds a string at the jpath.
28
+ * @throws {Error} If the query cannot be parsed or is an empty list, if more than 100 idcodes cannot
29
+ * be, or if no entry holds a string at the jpath.
27
30
  * @example
28
31
  * ```js
29
32
  * const { matches } = substructureSearch('gFp@DiTt@@B', rows, { jpath: 'molecule.idCode' });
30
33
  * ```
31
34
  */
32
35
  export function substructureSearch<Entry>(
33
- idCodeQuery: string,
36
+ idCodeQuery: string | readonly string[],
34
37
  entries: readonly Entry[],
35
38
  options: SubstructureSearchOptions = {},
36
39
  ): SubstructureSearchResult<Entry> {
@@ -67,7 +70,7 @@ export function substructureSearch<Entry>(
67
70
 
68
71
  const run = runSearch({
69
72
  mode: 'substructure',
70
- idCodeQuery,
73
+ idCodeQuery: joinQueries(idCodeQuery),
71
74
  idCodes,
72
75
  result,
73
76
  tally,
@@ -95,3 +98,23 @@ export function substructureSearch<Entry>(
95
98
  stopped: run.stopped,
96
99
  };
97
100
  }
101
+
102
+ /**
103
+ * The query as the WebAssembly side reads it: one idcode, or several joined by `'\n'`, which no
104
+ * idcode contains.
105
+ * @param idCodeQuery - The query, as an idcode or several.
106
+ * @returns The query string.
107
+ * @throws {Error} If the list is empty or an entry holds a line break.
108
+ */
109
+ function joinQueries(idCodeQuery: string | readonly string[]): string {
110
+ if (typeof idCodeQuery === 'string') return idCodeQuery;
111
+ if (idCodeQuery.length === 0) {
112
+ throw new Error('the query list is empty: give at least one idcode');
113
+ }
114
+ for (const idCode of idCodeQuery) {
115
+ if (idCode.includes('\n')) {
116
+ throw new Error(`"${idCode}" is not a valid query idcode`);
117
+ }
118
+ }
119
+ return idCodeQuery.join('\n');
120
+ }
package/src/types.ts CHANGED
@@ -167,7 +167,10 @@ export interface SimilaritySearchResult<Entry> extends SearchResult<Entry> {
167
167
  /** The shape TeaVM exports from the WasmGC module. Both take a half-open `[from, to)` range. */
168
168
  export interface OCLSearch {
169
169
  Search: {
170
- /** Returns how many molecules in the range contain the fragment. */
170
+ /**
171
+ * Returns how many molecules in the range contain the fragment, or any of the fragments when
172
+ * the query holds several idcodes joined by `'\n'`.
173
+ */
171
174
  ssSearch: (
172
175
  idCodeQuery: string,
173
176
  idCodes: string[],
@@ -190,11 +193,40 @@ export interface OCLSearch {
190
193
  from: number,
191
194
  to: number,
192
195
  ) => number;
196
+ /** Returns how many molecules in the range were parsed and screened. */
197
+ getScreens: (
198
+ idCodes: string[],
199
+ result: Int32Array,
200
+ from: number,
201
+ to: number,
202
+ ) => number;
203
+ /** Writes the query's sixteen screen words into `result`. */
204
+ getQueryScreen: (idCodeQuery: string, result: Int32Array) => void;
205
+ /** Writes the query's sixteen FragFp words into `result`. */
206
+ getQueryIndex: (idCodeQuery: string, result: Int32Array) => void;
207
+ /** Returns FragFp's 512 key idcodes, in bit order, joined by `'\n'`. */
208
+ getFragFpKeys: () => string;
209
+ /** Returns the screen's 512 key idcodes, in bit order, joined by `'\n'`. */
210
+ getScreenKeys: () => string;
211
+ /** Returns how many molecules in the range were parsed and read. */
212
+ getFunctions: (
213
+ idCodes: string[],
214
+ result: Int32Array,
215
+ from: number,
216
+ to: number,
217
+ ) => number;
218
+ /**
219
+ * Returns the 512 stored function keys, in bit order, joined by `'\n'`: each key's fragment
220
+ * idcodes joined by a space.
221
+ */
222
+ getFunctionKeys: () => string;
193
223
  /** Returns how many molecules in the range were hashed. */
194
224
  getNoStereoTautomerHashes: (
195
225
  idCodes: string[],
196
226
  result: BigInt64Array,
227
+ tautomerCounts: Int32Array,
197
228
  largestFragmentOnly: boolean,
229
+ maxTautomers: number,
198
230
  from: number,
199
231
  to: number,
200
232
  ) => number;
@@ -206,12 +238,60 @@ export interface OCLSearch {
206
238
  from: number,
207
239
  to: number,
208
240
  ) => number;
241
+ /** Returns how many molecules in the range were canonized. */
242
+ getNoStereoIdCodes: (
243
+ idCodes: string[],
244
+ result: string[],
245
+ largestFragmentOnly: boolean,
246
+ from: number,
247
+ to: number,
248
+ ) => number;
249
+ /** Returns how many molecules in the range were canonized. */
250
+ getNoStereoTautomerIdCodes: (
251
+ idCodes: string[],
252
+ result: string[],
253
+ tautomerCounts: Int32Array,
254
+ largestFragmentOnly: boolean,
255
+ maxTautomers: number,
256
+ from: number,
257
+ to: number,
258
+ ) => number;
259
+ /** Returns how many molecules in the range were read. */
260
+ getMoleculeRecords: (
261
+ idCodes: string[],
262
+ canonical: string[],
263
+ words: Int32Array,
264
+ atomCounts: Int32Array,
265
+ weights: Float64Array,
266
+ noStereoHashes: BigInt64Array,
267
+ tautomerHashes: BigInt64Array,
268
+ tautomerCounts: Int32Array,
269
+ maxTautomers: number,
270
+ from: number,
271
+ to: number,
272
+ ) => number;
273
+ /** Returns how many molecules in the range were read. */
274
+ getMoleculeSizes: (
275
+ idCodes: string[],
276
+ atomCounts: Int32Array,
277
+ weights: Float64Array,
278
+ from: number,
279
+ to: number,
280
+ ) => number;
281
+ /** Returns the query's atom floor. */
282
+ getQueryAtomFloor: (idCodeQuery: string) => number;
209
283
  };
210
284
  }
211
285
 
212
- /** How many 32-bit words one molecule's FragFp fingerprint occupies. */
286
+ /** How many 32-bit words one molecule's FragFp fingerprint, its screen, or its function bits occupy. */
213
287
  export const INDEX_WORDS = 16;
214
288
 
289
+ /**
290
+ * How many 32-bit words one molecule's record holds in `getMoleculeRecords`: its FragFp, its screen,
291
+ * then its function bits, {@link INDEX_WORDS} each.
292
+ */
293
+ export const RECORD_WORDS = 3 * INDEX_WORDS;
294
+
215
295
  /** What every hash function takes. */
216
296
  export interface HashOptions {
217
297
  /**
@@ -221,14 +301,103 @@ export interface HashOptions {
221
301
  * @default false
222
302
  */
223
303
  largestFragmentOnly?: boolean;
304
+
305
+ /**
306
+ * The ceiling on how many tautomers OpenChemLib enumerates before it settles for what it has.
307
+ * Only the tautomer functions read it.
308
+ *
309
+ * The cost of a tautomer key is set by this, not by the molecule's size: the median molecule needs
310
+ * a hundred microseconds and one in a hundred runs into the ceiling and spends the better part of
311
+ * a second getting there. Lowering it bounds that tail, at the price of a key that may not be
312
+ * canonical for the molecules that hit it — compare `tautomerCounts` against this value to find
313
+ * them.
314
+ * @default 100000 — OpenChemLib's own
315
+ */
316
+ maxTautomers?: number;
317
+
318
+ /**
319
+ * Filled with how many tautomers were enumerated for each molecule, if given. An entry that
320
+ * reached {@link HashOptions.maxTautomers} is one OpenChemLib stopped early on, which is the only
321
+ * signal that a key may not be canonical.
322
+ *
323
+ * It is the caller's buffer, `idCodes.length` entries long, so a table of flags costs one
324
+ * allocation. Only the tautomer functions write it.
325
+ */
326
+ tautomerCounts?: Int32Array;
224
327
  }
225
328
 
226
329
  /** {@link HashOptions} under the name the tautomer hashes introduced it with. */
227
330
  export type TautomerHashOptions = HashOptions;
228
331
 
332
+ /** What `getMoleculeRecords` takes. */
333
+ export interface MoleculeRecordsOptions {
334
+ /**
335
+ * The ceiling on the tautomer enumeration. A molecule that reaches it takes its no-stereo hash as
336
+ * its tautomer hash, because a key from a truncated enumeration is not canonical.
337
+ * @default DEFAULT_MAX_TAUTOMERS
338
+ */
339
+ maxTautomers?: number;
340
+ }
341
+
342
+ /**
343
+ * Everything a molecule table stores about each molecule, one entry per input idcode, in input
344
+ * order. A molecule whose idcode cannot be read gets `NO_ID_CODE`, 48 zero words, 0 atoms, a `NaN`
345
+ * weight, `NO_HASH` twice and a tautomer count of 0.
346
+ */
347
+ export interface MoleculeRecords {
348
+ /**
349
+ * The canonical idcode, stereochemistry included: what `openchemlib-js` gives for
350
+ * `Molecule.fromIDCode(idCode).getIDCode()`.
351
+ */
352
+ idCodes: string[];
353
+ /**
354
+ * {@link RECORD_WORDS} words per molecule, at `48 * i`: the FragFp (the 16 words of `getIndexes`),
355
+ * the screen (the 16 words of `getScreens`), then the function bits (the 16 words of
356
+ * `getFunctions`).
357
+ */
358
+ words: Int32Array;
359
+ /** `getAllAtoms()` of the molecule parsed without coordinates, explicit hydrogens included. */
360
+ atomCounts: Int32Array;
361
+ /** OpenChemLib's relative molecular weight. */
362
+ weights: Float64Array;
363
+ /** The value of `getNoStereoHashes`. */
364
+ noStereoHashes: BigInt64Array;
365
+ /**
366
+ * The value of `getNoStereoTautomerHashes`, except for a molecule whose enumeration reached
367
+ * `maxTautomers` or could not be canonized: that one gets its no-stereo hash.
368
+ */
369
+ tautomerHashes: BigInt64Array;
370
+ /** How many tautomers were enumerated; at or above `maxTautomers` the enumeration was cut short. */
371
+ tautomerCounts: Int32Array;
372
+ }
373
+
374
+ /** The size of each molecule, one entry per input idcode, in input order. */
375
+ export interface MoleculeSizes {
376
+ /**
377
+ * `getAllAtoms()` of the molecule parsed without coordinates, explicit hydrogens included; 0 when
378
+ * the idcode cannot be read.
379
+ */
380
+ atomCounts: Int32Array;
381
+ /** OpenChemLib's relative molecular weight; `NaN` when the idcode cannot be read. */
382
+ weights: Float64Array;
383
+ }
384
+
229
385
  /**
230
386
  * The hash of a molecule that has none: its idcode could not be parsed, or OpenChemLib could not
231
387
  * canonize it. A real hash collides with it once in 2^64, so an equality test against it is a
232
388
  * usable "no hash" check.
233
389
  */
234
390
  export const NO_HASH = 0n;
391
+
392
+ /**
393
+ * The canonical idcode of a molecule that has none: its idcode could not be parsed, or OpenChemLib
394
+ * could not canonize it. The empty string is never a valid idcode, so an equality test against it is
395
+ * the idcode counterpart of {@link NO_HASH}.
396
+ */
397
+ export const NO_ID_CODE = '';
398
+
399
+ /**
400
+ * How many tautomers OpenChemLib enumerates before it settles for what it has, unless
401
+ * {@link HashOptions.maxTautomers} says otherwise. It is OpenChemLib's own ceiling.
402
+ */
403
+ export const DEFAULT_MAX_TAUTOMERS = 100_000;
package/src/wasm/load.ts CHANGED
@@ -2,6 +2,8 @@ import { wasmGzipBase64 } from '../../wasm/data.js';
2
2
  import { load } from '../../wasm/runtime.js';
3
3
  import type { OCLSearch } from '../types.ts';
4
4
 
5
+ import { createConsoleImport } from './log.ts';
6
+
5
7
  let modulePromise: Promise<OCLSearch> | undefined;
6
8
 
7
9
  /**
@@ -27,7 +29,14 @@ export function loadOCL(): Promise<OCLSearch> {
27
29
 
28
30
  async function instantiate(): Promise<OCLSearch> {
29
31
  const wasmBytes = await gunzip(base64ToBytes(wasmGzipBase64));
30
- const teavm = await load(wasmBytes, { memory: { maxSize: MAX_LINEAR_MEMORY } });
32
+ const teavm = await load(wasmBytes, {
33
+ memory: { maxSize: MAX_LINEAR_MEMORY },
34
+ // The runtime's own `teavmConsole` puts Java's System.out on `console.log`, so OpenChemLib's
35
+ // "Tautomer count exceeds maximum" lands on the host's stdout — see src/wasm/log.ts.
36
+ installImports(imports) {
37
+ imports.teavmConsole = createConsoleImport();
38
+ },
39
+ });
31
40
  return teavm.exports as unknown as OCLSearch;
32
41
  }
33
42