openchemlib-search-wasm 1.0.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.
- package/LICENSE +275 -0
- package/README.md +172 -0
- package/lib/index.d.ts +42 -0
- package/lib/index.d.ts.map +1 -0
- package/lib/index.js +55 -0
- package/lib/index.js.map +1 -0
- package/lib/jpath.d.ts +28 -0
- package/lib/jpath.d.ts.map +1 -0
- package/lib/jpath.js +73 -0
- package/lib/jpath.js.map +1 -0
- package/lib/runSearch.d.ts +41 -0
- package/lib/runSearch.d.ts.map +1 -0
- package/lib/runSearch.js +50 -0
- package/lib/runSearch.js.map +1 -0
- package/lib/scan.d.ts +40 -0
- package/lib/scan.d.ts.map +1 -0
- package/lib/scan.js +103 -0
- package/lib/scan.js.map +1 -0
- package/lib/similaritySearch.d.ts +28 -0
- package/lib/similaritySearch.d.ts.map +1 -0
- package/lib/similaritySearch.js +86 -0
- package/lib/similaritySearch.js.map +1 -0
- package/lib/substructureSearch.d.ts +26 -0
- package/lib/substructureSearch.d.ts.map +1 -0
- package/lib/substructureSearch.js +81 -0
- package/lib/substructureSearch.js.map +1 -0
- package/lib/types.d.ts +169 -0
- package/lib/types.d.ts.map +1 -0
- package/lib/types.js +30 -0
- package/lib/types.js.map +1 -0
- package/lib/wasm/load.d.ts +10 -0
- package/lib/wasm/load.d.ts.map +1 -0
- package/lib/wasm/load.js +42 -0
- package/lib/wasm/load.js.map +1 -0
- package/package.json +80 -0
- package/src/index.ts +68 -0
- package/src/jpath.ts +77 -0
- package/src/runSearch.ts +99 -0
- package/src/scan.ts +141 -0
- package/src/similaritySearch.ts +104 -0
- package/src/substructureSearch.ts +97 -0
- package/src/types.ts +197 -0
- package/src/wasm/load.ts +50 -0
- package/wasm/data.d.ts +2 -0
- package/wasm/data.js +3 -0
- package/wasm/runtime.d.ts +25 -0
- package/wasm/runtime.js +30 -0
package/src/scan.ts
ADDED
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
import type { ResultBuffer, SearchMode } from './types.ts';
|
|
2
|
+
import { SimilarityResult, SubstructureResult } from './types.ts';
|
|
3
|
+
import { loadOCL } from './wasm/load.ts';
|
|
4
|
+
|
|
5
|
+
// Top-level await: the WASM module is instantiated when this module is imported, so the searches are
|
|
6
|
+
// plain calls. A worker pays it once, at startup, for about 25 ms from the built package.
|
|
7
|
+
const { Search } = await loadOCL();
|
|
8
|
+
|
|
9
|
+
// A malformed idcode makes OpenChemLib's bit-stream parser read past its input, which WebAssembly
|
|
10
|
+
// traps on. The trap unwinds into JS and leaves the module usable, so the entry it died on is
|
|
11
|
+
// recorded as unparsable and the scan resumes after it. Beyond this many, the input is not a list
|
|
12
|
+
// of idcodes at all and guessing further would cost one call per entry.
|
|
13
|
+
const MAX_UNPARSABLE = 100;
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* Scans `idCodes[from .. to)` into `result`, recording an entry the parser chokes on and carrying on.
|
|
17
|
+
*
|
|
18
|
+
* The range is passed through to WebAssembly rather than sliced in JavaScript, because the idcodes
|
|
19
|
+
* are read out of the JS array one at a time: a caller can scan the same array in as many pieces as
|
|
20
|
+
* it likes without re-converting it.
|
|
21
|
+
* @param mode - Which search to run.
|
|
22
|
+
* @param idCodeQuery - The query, as an idcode.
|
|
23
|
+
* @param idCodes - The molecules to scan.
|
|
24
|
+
* @param result - The caller's buffer, already reset.
|
|
25
|
+
* @param from - The first index to scan.
|
|
26
|
+
* @param to - One past the last index to scan.
|
|
27
|
+
* @throws {Error} If more than 100 idcodes in the range cannot be parsed.
|
|
28
|
+
*/
|
|
29
|
+
export function scanRange(
|
|
30
|
+
mode: SearchMode,
|
|
31
|
+
idCodeQuery: string,
|
|
32
|
+
idCodes: string[],
|
|
33
|
+
result: ResultBuffer,
|
|
34
|
+
from: number,
|
|
35
|
+
to: number,
|
|
36
|
+
): void {
|
|
37
|
+
const unparsable =
|
|
38
|
+
mode === 'similarity'
|
|
39
|
+
? SimilarityResult.unparsable
|
|
40
|
+
: SubstructureResult.unparsable;
|
|
41
|
+
let cursor = from;
|
|
42
|
+
let failures = 0;
|
|
43
|
+
while (cursor < to) {
|
|
44
|
+
try {
|
|
45
|
+
run(mode, idCodeQuery, idCodes, result, cursor, to);
|
|
46
|
+
return;
|
|
47
|
+
} catch (error) {
|
|
48
|
+
const failed = firstPending(mode, result, cursor, to);
|
|
49
|
+
if (failed === -1 || failures >= MAX_UNPARSABLE) {
|
|
50
|
+
throw new Error(
|
|
51
|
+
`the scan failed at index ${failed === -1 ? cursor : failed} after ${failures}` +
|
|
52
|
+
` unparsable idcode(s): check that "${idCodeQuery}" is a valid query idcode and that` +
|
|
53
|
+
' idCodes holds idcodes',
|
|
54
|
+
{ cause: error },
|
|
55
|
+
);
|
|
56
|
+
}
|
|
57
|
+
result[failed] = unparsable;
|
|
58
|
+
failures++;
|
|
59
|
+
cursor = failed + 1;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* Parses the query against an empty range, so a query the parser chokes on is reported as such.
|
|
66
|
+
*
|
|
67
|
+
* Without it the recovery above would blame the molecules for a bad query and walk the whole array
|
|
68
|
+
* one wasted call at a time.
|
|
69
|
+
* @param mode - Which search the query is for.
|
|
70
|
+
* @param idCodeQuery - The query, as an idcode.
|
|
71
|
+
* @throws {Error} If the query cannot be parsed.
|
|
72
|
+
*/
|
|
73
|
+
export function checkQuery(mode: SearchMode, idCodeQuery: string): void {
|
|
74
|
+
const empty = mode === 'similarity' ? new Float32Array(0) : new Uint8Array(0);
|
|
75
|
+
try {
|
|
76
|
+
run(mode, idCodeQuery, [], empty, 0, 0);
|
|
77
|
+
} catch (error) {
|
|
78
|
+
throw new Error(`"${idCodeQuery}" is not a valid query idcode`, {
|
|
79
|
+
cause: error,
|
|
80
|
+
});
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
function run(
|
|
85
|
+
mode: SearchMode,
|
|
86
|
+
idCodeQuery: string,
|
|
87
|
+
idCodes: string[],
|
|
88
|
+
result: ResultBuffer,
|
|
89
|
+
from: number,
|
|
90
|
+
to: number,
|
|
91
|
+
): void {
|
|
92
|
+
if (mode === 'similarity') {
|
|
93
|
+
Search.similaritySearch(
|
|
94
|
+
idCodeQuery,
|
|
95
|
+
idCodes,
|
|
96
|
+
result as Float32Array,
|
|
97
|
+
from,
|
|
98
|
+
to,
|
|
99
|
+
);
|
|
100
|
+
} else {
|
|
101
|
+
Search.ssSearch(idCodeQuery, idCodes, result as Uint8Array, from, to);
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
function firstPending(
|
|
106
|
+
mode: SearchMode,
|
|
107
|
+
result: ResultBuffer,
|
|
108
|
+
from: number,
|
|
109
|
+
to: number,
|
|
110
|
+
): number {
|
|
111
|
+
for (let index = from; index < to; index++) {
|
|
112
|
+
const value = result[index] as number;
|
|
113
|
+
const pending =
|
|
114
|
+
mode === 'similarity'
|
|
115
|
+
? Number.isNaN(value)
|
|
116
|
+
: value === SubstructureResult.unprocessed;
|
|
117
|
+
if (pending) return index;
|
|
118
|
+
}
|
|
119
|
+
return -1;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Fingerprints `idCodes[from .. to)` into `result`, sixteen words per molecule.
|
|
124
|
+
*
|
|
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.
|
|
128
|
+
* @param idCodes - The molecules to fingerprint.
|
|
129
|
+
* @param result - The caller's buffer, `16 * idCodes.length` words long.
|
|
130
|
+
* @param from - The first index to fingerprint.
|
|
131
|
+
* @param to - One past the last index to fingerprint.
|
|
132
|
+
* @returns How many molecules were parsed and fingerprinted.
|
|
133
|
+
*/
|
|
134
|
+
export function buildIndexes(
|
|
135
|
+
idCodes: string[],
|
|
136
|
+
result: Int32Array,
|
|
137
|
+
from: number,
|
|
138
|
+
to: number,
|
|
139
|
+
): number {
|
|
140
|
+
return Search.getIndexes(idCodes, result, from, to);
|
|
141
|
+
}
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
import { toIdCodes } from './jpath.ts';
|
|
2
|
+
import { runSearch } from './runSearch.ts';
|
|
3
|
+
import type {
|
|
4
|
+
SimilaritySearchOptions,
|
|
5
|
+
SimilaritySearchResult,
|
|
6
|
+
} from './types.ts';
|
|
7
|
+
import { SimilarityResult } from './types.ts';
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* Ranks many molecules by how similar they are to a query, on OpenChemLib's 512-bit FragFp
|
|
11
|
+
* fingerprint.
|
|
12
|
+
*
|
|
13
|
+
* The entries are either idcodes or objects carrying one, and `matches` comes back **most similar
|
|
14
|
+
* first**, with `similarities` holding each one's Tanimoto coefficient at the same position. The
|
|
15
|
+
* two arrays are read together: the entries are the caller's own objects, so hanging the number on
|
|
16
|
+
* a copy of each would allocate the result set twice.
|
|
17
|
+
*
|
|
18
|
+
* The fingerprint has to be built from each idcode, and that is essentially the whole cost: 947 µs
|
|
19
|
+
* per molecule against 0.03 µs for the comparison itself. When the caller already stores
|
|
20
|
+
* fingerprints — as `openchemlib-sqlite` does — comparing those directly is about 30,000 times
|
|
21
|
+
* cheaper than calling this. Use this when idcodes are all you have.
|
|
22
|
+
* @param idCodeQuery - The query, as an idcode.
|
|
23
|
+
* @param entries - The molecules to compare against: idcodes, or objects holding one at
|
|
24
|
+
* `options.jpath`.
|
|
25
|
+
* @param options - Where the idcode sits, the threshold, how many to keep, and progress reporting.
|
|
26
|
+
* @returns The entries at or above the threshold, most similar first, with their coefficients.
|
|
27
|
+
* @throws {Error} If the query cannot be parsed, if more than 100 idcodes cannot be, or if no entry
|
|
28
|
+
* holds a string at the jpath.
|
|
29
|
+
* @example
|
|
30
|
+
* ```js
|
|
31
|
+
* const { matches, similarities } = similaritySearch(query, rows, { threshold: 0.8, limit: 20 });
|
|
32
|
+
* ```
|
|
33
|
+
*/
|
|
34
|
+
export function similaritySearch<Entry>(
|
|
35
|
+
idCodeQuery: string,
|
|
36
|
+
entries: readonly Entry[],
|
|
37
|
+
options: SimilaritySearchOptions = {},
|
|
38
|
+
): SimilaritySearchResult<Entry> {
|
|
39
|
+
const {
|
|
40
|
+
jpath = 'idCode',
|
|
41
|
+
threshold = 0,
|
|
42
|
+
limit = Number.MAX_SAFE_INTEGER,
|
|
43
|
+
collect = true,
|
|
44
|
+
onStep,
|
|
45
|
+
stepSize,
|
|
46
|
+
} = options;
|
|
47
|
+
|
|
48
|
+
const idCodes = toIdCodes(entries, jpath);
|
|
49
|
+
const result = new Float32Array(entries.length);
|
|
50
|
+
result.fill(SimilarityResult.unprocessed);
|
|
51
|
+
const tally = { matched: 0, unparsable: 0 };
|
|
52
|
+
const indexes: number[] = [];
|
|
53
|
+
|
|
54
|
+
const collectRange = (from: number, to: number): boolean => {
|
|
55
|
+
for (let i = from; i < to; i++) {
|
|
56
|
+
const value = result[i] as number;
|
|
57
|
+
if (value === SimilarityResult.unparsable) {
|
|
58
|
+
tally.unparsable++;
|
|
59
|
+
} else if (value >= threshold) {
|
|
60
|
+
tally.matched++;
|
|
61
|
+
if (collect) indexes.push(i);
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
// A better match can always still be coming, so `limit` decides what is kept, never when to
|
|
65
|
+
// stop. Only `onStep` returning false ends a similarity scan early.
|
|
66
|
+
return false;
|
|
67
|
+
};
|
|
68
|
+
|
|
69
|
+
const run = runSearch({
|
|
70
|
+
mode: 'similarity',
|
|
71
|
+
idCodeQuery,
|
|
72
|
+
idCodes,
|
|
73
|
+
result,
|
|
74
|
+
tally,
|
|
75
|
+
collectRange,
|
|
76
|
+
stepSize,
|
|
77
|
+
onStep,
|
|
78
|
+
stoppable: false,
|
|
79
|
+
});
|
|
80
|
+
|
|
81
|
+
indexes.sort((a, b) => (result[b] as number) - (result[a] as number));
|
|
82
|
+
if (indexes.length > limit) indexes.length = limit;
|
|
83
|
+
|
|
84
|
+
const matches = new Array<Entry>(indexes.length);
|
|
85
|
+
const similarities = new Float32Array(indexes.length);
|
|
86
|
+
for (let i = 0; i < indexes.length; i++) {
|
|
87
|
+
const index = indexes[i] as number;
|
|
88
|
+
matches[i] = entries[index] as Entry;
|
|
89
|
+
similarities[i] = result[index] as number;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
return {
|
|
93
|
+
matches,
|
|
94
|
+
similarities,
|
|
95
|
+
indexes,
|
|
96
|
+
result,
|
|
97
|
+
matched: tally.matched,
|
|
98
|
+
unparsable: tally.unparsable,
|
|
99
|
+
processed: run.processed,
|
|
100
|
+
total: entries.length,
|
|
101
|
+
elapsed: run.elapsed,
|
|
102
|
+
stopped: run.stopped,
|
|
103
|
+
};
|
|
104
|
+
}
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
import { toIdCodes } from './jpath.ts';
|
|
2
|
+
import { runSearch } from './runSearch.ts';
|
|
3
|
+
import type {
|
|
4
|
+
SubstructureSearchOptions,
|
|
5
|
+
SubstructureSearchResult,
|
|
6
|
+
} from './types.ts';
|
|
7
|
+
import { SubstructureResult } from './types.ts';
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* Tests a query fragment against many molecules and returns the ones that contain it.
|
|
11
|
+
*
|
|
12
|
+
* The entries are either idcodes or objects carrying one — a database row, a candidate a prescreen
|
|
13
|
+
* yielded — and what comes back is those same objects, so nothing has to map positions back onto
|
|
14
|
+
* the array they came from. `result` still holds one status code per entry for a caller that wants
|
|
15
|
+
* the whole picture rather than the hits.
|
|
16
|
+
*
|
|
17
|
+
* The scan is synchronous. `onStep` reports it and can stop it, but the thread is not yielded:
|
|
18
|
+
* a caller that needs a responsive main thread slices the array across calls, or runs this in a
|
|
19
|
+
* worker.
|
|
20
|
+
* @param idCodeQuery - The query, as an idcode. It is searched as a fragment whatever its own
|
|
21
|
+
* fragment flag says, which is what `openchemlib`'s `SSSearcher` does with `setFragment(true)`.
|
|
22
|
+
* @param entries - The molecules to test: idcodes, or objects holding one at `options.jpath`.
|
|
23
|
+
* @param options - Where the idcode sits, how many matches are enough, and how to report progress.
|
|
24
|
+
* @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.
|
|
27
|
+
* @example
|
|
28
|
+
* ```js
|
|
29
|
+
* const { matches } = substructureSearch('gFp@DiTt@@B', rows, { jpath: 'molecule.idCode' });
|
|
30
|
+
* ```
|
|
31
|
+
*/
|
|
32
|
+
export function substructureSearch<Entry>(
|
|
33
|
+
idCodeQuery: string,
|
|
34
|
+
entries: readonly Entry[],
|
|
35
|
+
options: SubstructureSearchOptions = {},
|
|
36
|
+
): SubstructureSearchResult<Entry> {
|
|
37
|
+
const {
|
|
38
|
+
jpath = 'idCode',
|
|
39
|
+
limit = Number.MAX_SAFE_INTEGER,
|
|
40
|
+
collect = true,
|
|
41
|
+
onStep,
|
|
42
|
+
stepSize,
|
|
43
|
+
} = options;
|
|
44
|
+
|
|
45
|
+
const idCodes = toIdCodes(entries, jpath);
|
|
46
|
+
// A fresh Uint8Array is already all zeros, which is `unprocessed`.
|
|
47
|
+
const result = new Uint8Array(entries.length);
|
|
48
|
+
const tally = { matched: 0, unparsable: 0 };
|
|
49
|
+
const indexes: number[] = [];
|
|
50
|
+
const bounded = limit < entries.length;
|
|
51
|
+
|
|
52
|
+
// A whole step is tallied before the limit is checked, so `matched` and `unparsable` always
|
|
53
|
+
// describe exactly the entries that were scanned. The overshoot that buys is under one step, and
|
|
54
|
+
// `indexes` is cut back to `limit` below.
|
|
55
|
+
const collectRange = (from: number, to: number): boolean => {
|
|
56
|
+
for (let i = from; i < to; i++) {
|
|
57
|
+
const value = result[i] as number;
|
|
58
|
+
if (value === SubstructureResult.match) {
|
|
59
|
+
tally.matched++;
|
|
60
|
+
if (collect) indexes.push(i);
|
|
61
|
+
} else if (value === SubstructureResult.unparsable) {
|
|
62
|
+
tally.unparsable++;
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
return bounded && tally.matched >= limit;
|
|
66
|
+
};
|
|
67
|
+
|
|
68
|
+
const run = runSearch({
|
|
69
|
+
mode: 'substructure',
|
|
70
|
+
idCodeQuery,
|
|
71
|
+
idCodes,
|
|
72
|
+
result,
|
|
73
|
+
tally,
|
|
74
|
+
collectRange,
|
|
75
|
+
stepSize,
|
|
76
|
+
onStep,
|
|
77
|
+
stoppable: bounded,
|
|
78
|
+
});
|
|
79
|
+
|
|
80
|
+
if (indexes.length > limit) indexes.length = limit;
|
|
81
|
+
const matches = new Array<Entry>(indexes.length);
|
|
82
|
+
for (let i = 0; i < indexes.length; i++) {
|
|
83
|
+
matches[i] = entries[indexes[i] as number] as Entry;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
return {
|
|
87
|
+
matches,
|
|
88
|
+
indexes,
|
|
89
|
+
result,
|
|
90
|
+
matched: tally.matched,
|
|
91
|
+
unparsable: tally.unparsable,
|
|
92
|
+
processed: run.processed,
|
|
93
|
+
total: entries.length,
|
|
94
|
+
elapsed: run.elapsed,
|
|
95
|
+
stopped: run.stopped,
|
|
96
|
+
};
|
|
97
|
+
}
|
package/src/types.ts
ADDED
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The status of one entry of a `substructureSearch` result buffer.
|
|
3
|
+
*
|
|
4
|
+
* `unprocessed` is what a scan that stopped on `limit` or on `onStep` leaves behind.
|
|
5
|
+
*/
|
|
6
|
+
export const SubstructureResult = Object.freeze({
|
|
7
|
+
/** Not tested yet. */
|
|
8
|
+
unprocessed: 0,
|
|
9
|
+
/** The query is a substructure of this molecule. */
|
|
10
|
+
match: 1,
|
|
11
|
+
/** The query is not a substructure of this molecule. */
|
|
12
|
+
noMatch: 2,
|
|
13
|
+
/** The idcode could not be parsed; nothing was tested. */
|
|
14
|
+
unparsable: 3,
|
|
15
|
+
});
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* The similarity of one entry of a `similaritySearch` result buffer: `NaN` while the entry
|
|
19
|
+
* has not been compared yet, `-1` when its idcode could not be parsed, otherwise the Tanimoto
|
|
20
|
+
* coefficient in [0, 1]. `0` is a legitimate similarity, which is why the "not yet" sentinel is
|
|
21
|
+
* `NaN` and not `0`.
|
|
22
|
+
*/
|
|
23
|
+
export const SimilarityResult = Object.freeze({
|
|
24
|
+
/** Not compared yet. */
|
|
25
|
+
unprocessed: Number.NaN,
|
|
26
|
+
/** The idcode could not be parsed; nothing was compared. */
|
|
27
|
+
unparsable: -1,
|
|
28
|
+
});
|
|
29
|
+
|
|
30
|
+
/** What a search fills: bytes for a substructure scan, floats for a similarity one. */
|
|
31
|
+
export type ResultBuffer = Uint8Array | Float32Array;
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Which search to run. The names are the ones `openchemlib-utils` and `openchemlib-sqlite` already
|
|
35
|
+
* use for the same two searches.
|
|
36
|
+
*/
|
|
37
|
+
export type SearchMode = 'substructure' | 'similarity';
|
|
38
|
+
|
|
39
|
+
/** What a search has done so far, reported to `onStep`. */
|
|
40
|
+
export interface SearchStep {
|
|
41
|
+
/**
|
|
42
|
+
* The buffer being filled, so a caller can render as the scan runs. It is the same buffer at
|
|
43
|
+
* every step, and the one the result carries.
|
|
44
|
+
*/
|
|
45
|
+
result: ResultBuffer;
|
|
46
|
+
/** How many entries have been scanned. */
|
|
47
|
+
processed: number;
|
|
48
|
+
/** How many entries there are. */
|
|
49
|
+
total: number;
|
|
50
|
+
/** How many of the scanned entries matched. */
|
|
51
|
+
matched: number;
|
|
52
|
+
/** How many of them could not be parsed. */
|
|
53
|
+
unparsable: number;
|
|
54
|
+
/** Milliseconds since the search started. */
|
|
55
|
+
elapsed: number;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** What both searches take. */
|
|
59
|
+
export interface SearchOptions {
|
|
60
|
+
/**
|
|
61
|
+
* Where the idcode sits in an entry, as a dot-separated jpath: `idCode`, `molecule.idCode`,
|
|
62
|
+
* `spectra.0.idCode`. Ignored when the entries are idcodes rather than objects.
|
|
63
|
+
* @default 'idCode'
|
|
64
|
+
*/
|
|
65
|
+
jpath?: string;
|
|
66
|
+
/**
|
|
67
|
+
* Called after each step with what has been scanned so far. Return `false` to stop the search.
|
|
68
|
+
*
|
|
69
|
+
* It is synchronous and the scan does not yield: chunking for a responsive main thread is the
|
|
70
|
+
* caller's to do, by slicing the array across calls or running this in a worker.
|
|
71
|
+
*/
|
|
72
|
+
onStep?: (step: SearchStep) => boolean | void;
|
|
73
|
+
/**
|
|
74
|
+
* How many entries one step covers. Only meaningful alongside `onStep` or `limit`; without
|
|
75
|
+
* either, the whole array is scanned in a single call.
|
|
76
|
+
* @default 4096 for a substructure search, 128 for a similarity one — both about 100 ms
|
|
77
|
+
*/
|
|
78
|
+
stepSize?: number;
|
|
79
|
+
/**
|
|
80
|
+
* Whether to collect `matches` and `indexes`. Turn it off to fill `result` alone, which is what a
|
|
81
|
+
* worker writing into a shared buffer wants: on a corpus that matches often, collecting allocates
|
|
82
|
+
* one array slot per hit for nothing.
|
|
83
|
+
* @default true
|
|
84
|
+
*/
|
|
85
|
+
collect?: boolean;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
export interface SubstructureSearchOptions extends SearchOptions {
|
|
89
|
+
/**
|
|
90
|
+
* Stop once this many matches have been found. The scan stops at the end of the step that reached
|
|
91
|
+
* it, so `matches` can overshoot by less than one step before being cut back to `limit`.
|
|
92
|
+
* @default Number.MAX_SAFE_INTEGER
|
|
93
|
+
*/
|
|
94
|
+
limit?: number;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
export interface SimilaritySearchOptions extends SearchOptions {
|
|
98
|
+
/**
|
|
99
|
+
* The Tanimoto coefficient at or above which an entry counts as a match.
|
|
100
|
+
* @default 0
|
|
101
|
+
*/
|
|
102
|
+
threshold?: number;
|
|
103
|
+
/**
|
|
104
|
+
* Keep only the `limit` most similar entries. Unlike a substructure search this cannot stop the
|
|
105
|
+
* scan early — a better match may still be coming — so it only decides how many are kept.
|
|
106
|
+
* @default Number.MAX_SAFE_INTEGER
|
|
107
|
+
*/
|
|
108
|
+
limit?: number;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/** What every search returns, whatever it computed. */
|
|
112
|
+
export interface SearchResult<Entry> {
|
|
113
|
+
/**
|
|
114
|
+
* The entries that matched, in the order the search defines: input order for a substructure
|
|
115
|
+
* search, most similar first for a similarity one.
|
|
116
|
+
*/
|
|
117
|
+
matches: Entry[];
|
|
118
|
+
/**
|
|
119
|
+
* Their positions in the input, aligned with `matches`. Cheaper than the entries to post back
|
|
120
|
+
* from a worker, whose caller already holds them.
|
|
121
|
+
*/
|
|
122
|
+
indexes: number[];
|
|
123
|
+
/**
|
|
124
|
+
* How many of the scanned entries matched. Larger than `matches.length` when `limit` cut the
|
|
125
|
+
* list back, and the only count there is when `collect` is off.
|
|
126
|
+
*/
|
|
127
|
+
matched: number;
|
|
128
|
+
/** How many idcodes could not be parsed. */
|
|
129
|
+
unparsable: number;
|
|
130
|
+
/** How many entries were scanned. Short of `total` when the search stopped early. */
|
|
131
|
+
processed: number;
|
|
132
|
+
/** How many entries there were. */
|
|
133
|
+
total: number;
|
|
134
|
+
/** How long the search took, in milliseconds. */
|
|
135
|
+
elapsed: number;
|
|
136
|
+
/** True when `limit` or `onStep` stopped the scan before the end. */
|
|
137
|
+
stopped: boolean;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* `matches` and `indexes` are in **input order**, and `limit` therefore keeps the first matches
|
|
142
|
+
* rather than an arbitrary subset. A caller that has ordered its entries by a preference — cheapest
|
|
143
|
+
* first, lightest first — gets that preference back, which is what makes `limit` a first page
|
|
144
|
+
* rather than a sample.
|
|
145
|
+
*/
|
|
146
|
+
export interface SubstructureSearchResult<Entry> extends SearchResult<Entry> {
|
|
147
|
+
/**
|
|
148
|
+
* One {@link SubstructureResult} code per entry, in input order. Entries past `processed` are
|
|
149
|
+
* left `unprocessed` when the search stopped early.
|
|
150
|
+
*/
|
|
151
|
+
result: Uint8Array;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/** `matches` is ordered by descending similarity, so `limit` keeps the best. */
|
|
155
|
+
export interface SimilaritySearchResult<Entry> extends SearchResult<Entry> {
|
|
156
|
+
/**
|
|
157
|
+
* The Tanimoto coefficient of each entry of `matches`, in the same order — so the two arrays are
|
|
158
|
+
* read together. It is a separate array rather than a field on the entry because the entries are
|
|
159
|
+
* the caller's own objects: copying each one just to hang a number on it would allocate the whole
|
|
160
|
+
* result set a second time.
|
|
161
|
+
*/
|
|
162
|
+
similarities: Float32Array;
|
|
163
|
+
/** One coefficient per entry, in input order, with the {@link SimilarityResult} sentinels. */
|
|
164
|
+
result: Float32Array;
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/** The shape TeaVM exports from the WasmGC module. Both take a half-open `[from, to)` range. */
|
|
168
|
+
export interface OCLSearch {
|
|
169
|
+
Search: {
|
|
170
|
+
/** Returns how many molecules in the range contain the fragment. */
|
|
171
|
+
ssSearch: (
|
|
172
|
+
idCodeQuery: string,
|
|
173
|
+
idCodes: string[],
|
|
174
|
+
result: Uint8Array,
|
|
175
|
+
from: number,
|
|
176
|
+
to: number,
|
|
177
|
+
) => number;
|
|
178
|
+
/** Returns how many molecules in the range were parsed and compared. */
|
|
179
|
+
similaritySearch: (
|
|
180
|
+
idCodeQuery: string,
|
|
181
|
+
idCodes: string[],
|
|
182
|
+
result: Float32Array,
|
|
183
|
+
from: number,
|
|
184
|
+
to: number,
|
|
185
|
+
) => number;
|
|
186
|
+
/** Returns how many molecules in the range were parsed and fingerprinted. */
|
|
187
|
+
getIndexes: (
|
|
188
|
+
idCodes: string[],
|
|
189
|
+
result: Int32Array,
|
|
190
|
+
from: number,
|
|
191
|
+
to: number,
|
|
192
|
+
) => number;
|
|
193
|
+
};
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/** How many 32-bit words one molecule's FragFp fingerprint occupies. */
|
|
197
|
+
export const INDEX_WORDS = 16;
|
package/src/wasm/load.ts
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { wasmGzipBase64 } from '../../wasm/data.js';
|
|
2
|
+
import { load } from '../../wasm/runtime.js';
|
|
3
|
+
import type { OCLSearch } from '../types.ts';
|
|
4
|
+
|
|
5
|
+
let modulePromise: Promise<OCLSearch> | undefined;
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* The ceiling on the module's linear memory. The runtime otherwise declares the largest maximum it
|
|
9
|
+
* can — 2 GiB — for every instantiation, and a page that scans in eight workers declares eight of
|
|
10
|
+
* them. The module's own `teavm.memoryRequirements` section asks for 33 pages and 17 KB of static
|
|
11
|
+
* data, and the memory has never been observed to grow past its 33-page initial, so this is three
|
|
12
|
+
* orders of magnitude of headroom over anything measured.
|
|
13
|
+
*/
|
|
14
|
+
const MAX_LINEAR_MEMORY = 256 * 1024 * 1024;
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Loads and instantiates the embedded OpenChemLib WasmGC module. The module is compiled once and
|
|
18
|
+
* cached; subsequent calls return the same instance. Decoding uses only Web Platform APIs (atob +
|
|
19
|
+
* DecompressionStream), so Node and the browser take the same path, with no filesystem and no
|
|
20
|
+
* fetch — which is what lets a worker instantiate it from the bundle it was loaded from.
|
|
21
|
+
* @returns The module's exports.
|
|
22
|
+
*/
|
|
23
|
+
export function loadOCL(): Promise<OCLSearch> {
|
|
24
|
+
modulePromise ??= instantiate();
|
|
25
|
+
return modulePromise;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
async function instantiate(): Promise<OCLSearch> {
|
|
29
|
+
const wasmBytes = await gunzip(base64ToBytes(wasmGzipBase64));
|
|
30
|
+
const teavm = await load(wasmBytes, { memory: { maxSize: MAX_LINEAR_MEMORY } });
|
|
31
|
+
return teavm.exports as unknown as OCLSearch;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function base64ToBytes(base64: string): Uint8Array<ArrayBuffer> {
|
|
35
|
+
const binary = atob(base64);
|
|
36
|
+
const bytes = new Uint8Array(binary.length);
|
|
37
|
+
for (let i = 0; i < binary.length; i++) {
|
|
38
|
+
bytes[i] = binary.codePointAt(i) ?? 0;
|
|
39
|
+
}
|
|
40
|
+
return bytes;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
async function gunzip(
|
|
44
|
+
bytes: Uint8Array<ArrayBuffer>,
|
|
45
|
+
): Promise<Uint8Array<ArrayBuffer>> {
|
|
46
|
+
const stream = new Blob([bytes])
|
|
47
|
+
.stream()
|
|
48
|
+
.pipeThrough(new DecompressionStream('gzip'));
|
|
49
|
+
return new Uint8Array(await new Response(stream).arrayBuffer());
|
|
50
|
+
}
|
package/wasm/data.d.ts
ADDED