openchemlib-search-wasm 2.0.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.
@@ -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,6 +193,33 @@ 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[],
@@ -226,12 +256,42 @@ export interface OCLSearch {
226
256
  from: number,
227
257
  to: number,
228
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;
229
283
  };
230
284
  }
231
285
 
232
- /** 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. */
233
287
  export const INDEX_WORDS = 16;
234
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
+
235
295
  /** What every hash function takes. */
236
296
  export interface HashOptions {
237
297
  /**
@@ -269,6 +329,59 @@ export interface HashOptions {
269
329
  /** {@link HashOptions} under the name the tautomer hashes introduced it with. */
270
330
  export type TautomerHashOptions = HashOptions;
271
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
+
272
385
  /**
273
386
  * The hash of a molecule that has none: its idcode could not be parsed, or OpenChemLib could not
274
387
  * canonize it. A real hash collides with it once in 2^64, so an equality test against it is a