react-cheminfo 0.76.0 → 0.78.0

package/src/osiris/core/fitness.ts

@@ -0,0 +1,59 @@
+/**
+ * How good one predicted number is, from 0 to 1, and where it sits on its bar.
+ *
+ * The fitness is what the green-to-red ramp reads; the position is what the
+ * bar's length reads. They are deliberately two numbers: a molecular weight of
+ * 780 is nearly the full width of its bar and nearly the worst fitness, while
+ * a drug-likeness of 0 is halfway along its bar and exactly half fit.
+ */
+
+import { clamp } from '../../format/core/clamp.ts';
+
+import type { PropertyKey } from './propertyKeys.ts';
+import { propertyScale } from './scales.ts';
+import { getValuation } from './valuation.ts';
+
+/**
+ * How well a value sits in its property's preferred band, from 0 (as bad as
+ * the ramp goes) to 1 (inside the band).
+ *
+ * The drug score is already that fitness — it is the product of the four
+ * valuations `DrugScoreCalculator` computes — so it is returned as it stands
+ * rather than valued a second time.
+ * @param key - Which of the ten properties.
+ * @param value - The predicted number, or `null` when the predictor could not answer.
+ * @returns The fitness, or `null` for an unknown value.
+ */
+export function propertyFitness(
+  key: PropertyKey,
+  value: number | null,
+): number | null {
+  if (value === null || !Number.isFinite(value)) return null;
+  const scale = propertyScale(key);
+  if (scale.halfWidth === null) return clamp(value, 0, 1);
+  return getValuation(
+    value,
+    scale.preferredMin,
+    scale.preferredMax,
+    scale.halfWidth,
+  );
+}
+
+/**
+ * Where a value sits along its bar, from 0 at the left end to 1 at the right.
+ *
+ * Clamped, because a range is a typical spread rather than a bound: cholesterol
+ * runs past the solubility axis and still has to draw.
+ * @param key - Which of the ten properties.
+ * @param value - The predicted number, or `null`.
+ * @returns The position, or `null` for an unknown value.
+ */
+export function propertyPosition(
+  key: PropertyKey,
+  value: number | null,
+): number | null {
+  if (value === null || !Number.isFinite(value)) return null;
+  const { rangeMin, rangeMax } = propertyScale(key);
+  if (rangeMax === rangeMin) return 0;
+  return clamp((value - rangeMin) / (rangeMax - rangeMin), 0, 1);
+}

package/src/osiris/core/index.ts

@@ -0,0 +1,78 @@
+export type { BarGeometry } from './barGeometry.ts';
+export { barGeometry } from './barGeometry.ts';
+export type { ComputePropertiesOptions } from './computeProperties.ts';
+export {
+  EMPTY_MOLECULE_MESSAGE,
+  computeProperties,
+} from './computeProperties.ts';
+export {
+  DRUG_SCORE_RISK_FACTORS,
+  NO_FRAGMENT_MATCHED,
+  RISK_LABELS,
+  RISK_LEVELS,
+  RISK_LEVEL_LABELS,
+  RISK_TYPE_CODES,
+  UNKNOWN_NUMBER,
+  UNKNOWN_SURFACE_AREA,
+  riskCodeOf,
+  riskLevelOf,
+} from './constants.ts';
+export { propertyFitness, propertyPosition } from './fitness.ts';
+export { MAX_POOL_SIZE, predictionPoolSize } from './poolSize.ts';
+export type {
+  PredictionInput,
+  PredictionOutcome,
+  PredictionPool,
+  PredictionPoolOptions,
+  PredictionProgress,
+} from './poolTypes.ts';
+export {
+  UNREADABLE_ID_CODE_MESSAGE,
+  predictIdCode,
+  riskDetailOfIdCode,
+} from './predictIdCode.ts';
+export type {
+  PredictRequest,
+  PredictResponse,
+  PropertiesRequest,
+  RiskDetailRequest,
+} from './predictProtocol.ts';
+export { isPredictRequest } from './predictProtocol.ts';
+export { createPredictionPool } from './predictionPool.ts';
+export type { PredictionQueue } from './predictionQueue.ts';
+export { createPredictionQueue } from './predictionQueue.ts';
+export type { OsirisPredictors, ResourceSource } from './predictors.ts';
+export {
+  PredictorsUnavailableError,
+  loadPredictors,
+  resetPredictors,
+} from './predictors.ts';
+export type { PropertyKey } from './propertyKeys.ts';
+export { PROPERTY_KEYS, isPropertyKey, propertyValue } from './propertyKeys.ts';
+export type { RiskAppearance, RiskTone } from './riskAppearance.ts';
+export {
+  KNOWN_MOLECULE_NOTE,
+  PENDING_RISK_LABEL,
+  RISK_CAVEAT,
+  riskAppearance,
+} from './riskAppearance.ts';
+export { riskDetail } from './riskDetail.ts';
+export { parseRiskFindings } from './riskFindings.ts';
+export { runPredictionJob } from './runPredictionJob.ts';
+export type {
+  PropertyScale,
+  PropertyThreshold,
+  ScaleSource,
+} from './scales.ts';
+export { PROPERTY_SCALES, propertyScale } from './scales.ts';
+export type {
+  DetailEntry,
+  OsirisProperties,
+  RiskDetail,
+  RiskFinding,
+  RiskFindingKind,
+  RiskLevel,
+  RiskType,
+} from './types.ts';
+export { RISK_TYPES } from './types.ts';
+export { getValuation } from './valuation.ts';

package/src/osiris/core/poolSize.ts

@@ -0,0 +1,24 @@
+/**
+ * How many workers to run.
+ *
+ * One fewer than the machine's cores, so the thread that draws the table keeps
+ * one to itself, and never more than eight: measured scaling is 2.45x on two
+ * workers and 4.57x on four, and each worker costs its own copy of OpenChemLib
+ * and of the 398 kB resource tables.
+ */
+
+import { clamp } from '../../format/core/clamp.ts';
+
+/** The most workers the pool will ever run. */
+export const MAX_POOL_SIZE = 8;
+
+/**
+ * How many workers a pool should run here.
+ * @param requested - What the caller asked for, or `undefined` to read the machine.
+ * @returns A count between 1 and {@link MAX_POOL_SIZE}.
+ */
+export function predictionPoolSize(requested?: number): number {
+  const cores = globalThis.navigator?.hardwareConcurrency;
+  const wanted = requested ?? (typeof cores === 'number' ? cores - 1 : 1);
+  return Math.trunc(clamp(wanted, 1, MAX_POOL_SIZE, 1));
+}

package/src/osiris/core/poolTypes.ts

@@ -0,0 +1,140 @@
+/**
+ * What a page asks the prediction pool, and what it hears back.
+ *
+ * A prediction costs 210 to 380 ms of one thread, so a set of any size is
+ * answered a molecule at a time rather than all at once: a row appears as soon
+ * as it is read and fills in when its worker returns. Everything here is shaped
+ * around that — a per-result callback rather than a promise over the set, a
+ * progress figure, a cancel that works, and a way to say which rows the reader
+ * can actually see so those are computed first.
+ */
+
+import type { WorkerLike } from '../../worker/core/messages.ts';
+
+import type { PredictRequest, PredictResponse } from './predictProtocol.ts';
+import type { ResourceSource } from './predictors.ts';
+import type { OsirisProperties, RiskDetail, RiskType } from './types.ts';
+
+/** One molecule to predict. */
+export interface PredictionInput {
+  /**
+   * The caller's key for the row, echoed on the answer. It is the row's read
+   * position, never its idCode: a real list holds the same structure twice
+   * under two names, and both rows have to fill in.
+   */
+  key: string;
+  /** The idCode, with the editor's atom coordinates after a space or without. */
+  idCode: string;
+  /**
+   * The name the source carried.
+   * @default the canonical SMILES
+   */
+  label?: string;
+}
+
+/** What came back for one molecule. */
+export type PredictionOutcome =
+  | { key: string; ok: true; properties: OsirisProperties }
+  | { key: string; ok: false; message: string };
+
+/** How far the pool has got. */
+export interface PredictionProgress {
+  /** Molecules answered, whether predicted or refused. */
+  done: number;
+  /** Molecules accepted since the run started. */
+  total: number;
+  /** Molecules still queued or still being worked on. */
+  pending: number;
+  /** Whether anything is still to come. */
+  running: boolean;
+}
+
+/** How a pool is built, and who it reports to. */
+export interface PredictionPoolOptions {
+  /**
+   * Where the workers register OpenChemLib's resources from — the absolute URL
+   * of the site's own `openchemlib-resources.json`, resolved on the main
+   * thread. See {@link ResourceSource}.
+   */
+  resources: ResourceSource;
+  /**
+   * How many workers to run. Clamped to 1 to 8.
+   * @default one fewer than the machine's cores, which measured 2.45x on two workers and 4.57x on four
+   */
+  size?: number;
+  /**
+   * Makes one worker, which serves `runPredictionJob` for the requests
+   * `isPredictRequest` accepts. Only called where the page has a `Worker` at
+   * all. The site writes it because a bundler resolves a worker's address
+   * against the module naming it: written in this package, the URL would point
+   * inside `node_modules` rather than at a chunk the site's build emitted.
+   */
+  createWorker: () => WorkerLike;
+  /**
+   * The same job on this thread, used where there is no `Worker` — Node, a
+   * unit test.
+   * @default `runPredictionJob`, the same function the worker serves
+   */
+  runInProcess?: (request: PredictRequest) => Promise<PredictResponse>;
+  /**
+   * Called once per molecule, as each one comes back.
+   * @default undefined
+   */
+  onResult?: (outcome: PredictionOutcome) => void;
+  /**
+   * Called whenever the count of answered molecules changes.
+   * @default undefined
+   */
+  onProgress?: (progress: PredictionProgress) => void;
+  /**
+   * Called once when the resource tables did not load. Every answer from every
+   * worker would be `unknown`, so the run stops and nothing more is dispatched.
+   * @default undefined
+   */
+  onUnavailable?: (message: string) => void;
+  /**
+   * Milliseconds one molecule may take before it is given up on.
+   * @default 60000
+   */
+  timeoutMs?: number;
+}
+
+/** A pool of workers answering one molecule at a time, each. */
+export interface PredictionPool {
+  /** How many workers it runs. */
+  readonly size: number;
+  /** How far it has got. */
+  readonly progress: PredictionProgress;
+  /**
+   * Add molecules to predict. One already queued or in flight is ignored, so a
+   * page may resubmit its whole set whenever the set changes.
+   * @param molecules - The molecules.
+   */
+  submit: (molecules: readonly PredictionInput[]) => void;
+  /**
+   * Say which rows to answer first — the ones the reader can see. Molecules
+   * already being worked on are left alone; only what is still queued moves.
+   * @param keys - The keys, most wanted first.
+   */
+  prioritize: (keys: readonly string[]) => void;
+  /**
+   * Why one risk came back as it did. Jumps the queue, because it is a click.
+   * A {@link PredictionPool.cancel} is about the set, not about the click, so
+   * an explanation it drops is asked for again.
+   * @param idCode - The molecule, coordinates included or not.
+   * @param risk - Which of the four risks to explain.
+   * @returns The findings, with the matched atoms and bonds of every fragment.
+   * @throws {Error} When even the second ask was dropped, with a sentence to show the reader.
+   */
+  riskDetail: (idCode: string, risk: RiskType) => Promise<RiskDetail>;
+  /**
+   * Drop everything queued and stop reporting. The molecule each worker is
+   * already on cannot be interrupted — the library call is synchronous — so it
+   * finishes and its answer is thrown away, within about 400 ms. A
+   * {@link PredictionPool.submit} made in the same turn is still dispatched, on
+   * the slots those abandoned answers free.
+   */
+  cancel: () => void;
+  /** Cancel, and end every worker. */
+  terminate: () => void;
+}

package/src/osiris/core/predictIdCode.ts

@@ -0,0 +1,69 @@
+/**
+ * Prediction from the only thing worth keeping per row.
+ *
+ * A row never holds an `OCL.Molecule` — ten thousand of them cost 198 MB — so
+ * what travels to a worker is the idCode, and the molecule is rebuilt there in
+ * a quarter of a millisecond against the 380 ms the prediction itself costs.
+ */
+
+import { splitIdCode } from '../../structure/core/editorValue.ts';
+
+import type { ComputePropertiesOptions } from './computeProperties.ts';
+import { computeProperties } from './computeProperties.ts';
+import type { OsirisPredictors } from './predictors.ts';
+import { riskDetail } from './riskDetail.ts';
+import type { OsirisProperties, RiskDetail, RiskType } from './types.ts';
+
+/**
+ * What is said when an idCode cannot be read.
+ *
+ * An idCode is written by a program, not typed by a chemist, so there is no
+ * position to point at and no parser reason worth repeating: OpenChemLib
+ * answers a malformed one with `Cannot set properties of undefined`, which
+ * names nothing anyone can act on. Worse, it does not always throw — `zzzz`
+ * reads as a 117-atom molecule — so this is the floor, not the whole guard.
+ */
+export const UNREADABLE_ID_CODE_MESSAGE = 'This structure could not be read.';
+
+/**
+ * Predict everything the tool shows, from an idCode.
+ * @param value - The idCode, with the editor's atom coordinates after a space or without them.
+ * @param predictors - OpenChemLib with its resources registered and checked.
+ * @param options - See {@link ComputePropertiesOptions}.
+ * @returns The ten numbers, the four risks, and what to call the molecule.
+ * @throws {Error} When the idCode cannot be read, or describes no atoms.
+ */
+export function predictIdCode(
+  value: string,
+  predictors: OsirisPredictors,
+  options: ComputePropertiesOptions = {},
+): OsirisProperties {
+  return computeProperties(read(value, predictors), predictors, options);
+}
+
+/**
+ * Why one risk came back as it did, from an idCode.
+ * @param value - The idCode, coordinates included or not.
+ * @param risk - Which of the four risks to explain.
+ * @param predictors - OpenChemLib with its resources registered and checked.
+ * @returns The findings, with the matched atoms and bonds of every fragment.
+ * @throws {Error} When the idCode cannot be read.
+ */
+export function riskDetailOfIdCode(
+  value: string,
+  risk: RiskType,
+  predictors: OsirisPredictors,
+): RiskDetail {
+  return riskDetail(read(value, predictors), risk, predictors);
+}
+
+function read(value: string, predictors: OsirisPredictors) {
+  const { idCode, coordinates } = splitIdCode(value);
+  try {
+    return coordinates === undefined
+      ? predictors.Molecule.fromIDCode(idCode)
+      : predictors.Molecule.fromIDCode(idCode, coordinates);
+  } catch (error) {
+    throw new Error(UNREADABLE_ID_CODE_MESSAGE, { cause: error });
+  }
+}

package/src/osiris/core/predictProtocol.ts

@@ -0,0 +1,78 @@
+/**
+ * What the page asks a prediction worker, and what it answers.
+ *
+ * One molecule per request. Two of the three answers are ordinary results; the
+ * third, `unavailable`, is how a worker says its resource tables did not load.
+ * That one travels as a *successful* answer on purpose: a rejection would be
+ * indistinguishable from the ordinary failure of one unreadable structure,
+ * whereas this one means every answer from every worker is worthless and the
+ * run must stop and say so.
+ */
+
+import type { ResourceSource } from './predictors.ts';
+import type { OsirisProperties, RiskDetail, RiskType } from './types.ts';
+
+/** What every request carries, whichever job it asks for. */
+interface BaseRequest {
+  /**
+   * Where the worker registers OpenChemLib's resources from. In a browser this
+   * is always the absolute URL of the site's own `openchemlib-resources.json`,
+   * resolved on the main thread: a worker has no `document`, so it cannot read
+   * the deployment's mount path itself. The parsed tables are accepted as well,
+   * for the in-process fallback where there is no worker to post them to.
+   */
+  resources: ResourceSource;
+}
+
+/** Predict everything the tool shows for one molecule. */
+export interface PropertiesRequest extends BaseRequest {
+  kind: 'properties';
+  /** The caller's key for the row, echoed back so answers can arrive in any order. */
+  key: string;
+  /** The idCode, with the editor's atom coordinates after a space or without. */
+  idCode: string;
+  /**
+   * The name the source carried.
+   * @default the canonical SMILES
+   */
+  label?: string;
+}
+
+/** Explain why one risk came back as it did. */
+export interface RiskDetailRequest extends BaseRequest {
+  kind: 'riskDetail';
+  /** The idCode, coordinates included or not. */
+  idCode: string;
+  /** Which of the four risks to explain. */
+  risk: RiskType;
+}
+
+/** One job for a prediction worker. */
+export type PredictRequest = PropertiesRequest | RiskDetailRequest;
+
+/** What a prediction worker answers. */
+export type PredictResponse =
+  | { kind: 'properties'; key: string; properties: OsirisProperties }
+  | { kind: 'riskDetail'; detail: RiskDetail }
+  | { kind: 'unavailable'; message: string };
+
+/**
+ * Whether a message is a job this worker handles, so anything else is refused
+ * rather than read as one.
+ * @param value - Whatever was posted.
+ * @returns True when it is a well-formed request.
+ */
+export function isPredictRequest(value: unknown): value is PredictRequest {
+  if (typeof value !== 'object' || value === null) return false;
+  const request = value as {
+    kind?: unknown;
+    resources?: unknown;
+    idCode?: unknown;
+    key?: unknown;
+    risk?: unknown;
+  };
+  if (typeof request.idCode !== 'string') return false;
+  if (request.resources === undefined) return false;
+  if (request.kind === 'properties') return typeof request.key === 'string';
+  return request.kind === 'riskDetail' && typeof request.risk === 'string';
+}

package/src/osiris/core/predictionPool.ts

@@ -0,0 +1,237 @@
+/**
+ * A pool of prediction workers, answering one molecule at a time each.
+ *
+ * `createWorkerChannel` from `react-cheminfo/core` does the per-worker half —
+ * request identifiers so answers match callers whatever order they arrive in,
+ * timeouts, cancellation, and the in-process fallback where a page has no
+ * `Worker` at all. What it does not do is spread work over several workers, so
+ * that is what this adds: one channel per worker, a queue the pool owns, and at
+ * most one outstanding job per channel, which is what makes reordering possible
+ * at all. A channel asked for everything at once would post everything at once,
+ * and the row the reader is looking at would be answered forty-eighth.
+ */
+
+import { errorMessage } from '../../error/core/toError.ts';
+import { CancelledRequestError } from '../../worker/core/errors.ts';
+import { createWorkerChannel } from '../../worker/core/workerChannel.ts';
+import type { WorkerChannel } from '../../worker/core/workerChannelTypes.ts';
+
+import { predictionPoolSize } from './poolSize.ts';
+import type {
+  PredictionInput,
+  PredictionPool,
+  PredictionPoolOptions,
+  PredictionProgress,
+} from './poolTypes.ts';
+import type { PredictRequest, PredictResponse } from './predictProtocol.ts';
+import { createPredictionQueue } from './predictionQueue.ts';
+import { PredictorsUnavailableError } from './predictors.ts';
+import { requestRiskDetail } from './riskDetailRequest.ts';
+import { runPredictionJob } from './runPredictionJob.ts';
+import type { RiskDetail, RiskType } from './types.ts';
+
+type Channel = WorkerChannel<PredictRequest, PredictResponse>;
+
+interface Slot {
+  channel: Channel;
+  busy: boolean;
+}
+
+/**
+ * Start a pool of prediction workers.
+ *
+ * Workers are created lazily by the channels, on their first job, so a page
+ * that never predicts anything never loads OpenChemLib.
+ * @param options - See {@link PredictionPoolOptions}.
+ * @returns The pool.
+ */
+export function createPredictionPool(
+  options: PredictionPoolOptions,
+): PredictionPool {
+  const {
+    resources,
+    onResult,
+    onProgress,
+    onUnavailable,
+    createWorker,
+    runInProcess,
+    timeoutMs = 60_000,
+  } = options;
+  const size = predictionPoolSize(options.size);
+  const run = runInProcess ?? runPredictionJob;
+
+  const slots: Slot[] = [];
+  for (let index = 0; index < size; index++) {
+    slots.push({
+      channel: createWorkerChannel<PredictRequest, PredictResponse>(
+        createWorker,
+        {
+          name: `osiris-prediction-${index}`,
+          defaultTimeoutMs: timeoutMs,
+          runInProcess: run,
+        },
+      ),
+      busy: false,
+    });
+  }
+
+  const queue = createPredictionQueue();
+  const inFlight = new Set<string>();
+  let generation = 0;
+  let done = 0;
+  let total = 0;
+  let running = false;
+  let terminated = false;
+  let unavailable: string | null = null;
+
+  function progress(): PredictionProgress {
+    return { done, total, pending: queue.size + inFlight.size, running };
+  }
+
+  function report(): void {
+    onProgress?.(progress());
+  }
+
+  function pump(): void {
+    if (unavailable !== null) return;
+    for (const slot of slots) {
+      if (slot.busy) continue;
+      const next = queue.take();
+      if (next === undefined) break;
+      dispatch(slot, next);
+    }
+  }
+
+  function dispatch(slot: Slot, input: PredictionInput): void {
+    const era = generation;
+    slot.busy = true;
+    inFlight.add(input.key);
+    const request: PredictRequest = {
+      kind: 'properties',
+      resources,
+      key: input.key,
+      idCode: input.idCode,
+      ...(input.label === undefined ? {} : { label: input.label }),
+    };
+    slot.channel.request(request).then(
+      (response) => {
+        settle(slot, input, era, response, null);
+      },
+      (error: unknown) => {
+        settle(slot, input, era, null, error);
+      },
+    );
+  }
+
+  function settle(
+    slot: Slot,
+    input: PredictionInput,
+    era: number,
+    response: PredictResponse | null,
+    error: unknown,
+  ): void {
+    slot.busy = false;
+    inFlight.delete(input.key);
+
+    // An answer from a cancelled run is not counted and not reported, but the
+    // slot it just freed is still dispatched from: a submit made in the same
+    // turn as the cancel found every slot busy and queued its molecules here.
+    if (era === generation) {
+      if (response?.kind === 'unavailable') {
+        stop(response.message);
+        return;
+      }
+      if (response?.kind === 'properties') {
+        done += 1;
+        onResult?.({
+          key: input.key,
+          ok: true,
+          properties: response.properties,
+        });
+      } else if (error !== null && !(error instanceof CancelledRequestError)) {
+        done += 1;
+        onResult?.({ key: input.key, ok: false, message: errorMessage(error) });
+      }
+    }
+
+    pump();
+    if (queue.size === 0 && inFlight.size === 0) running = false;
+    report();
+  }
+
+  function clear(): void {
+    generation += 1;
+    queue.clear();
+    inFlight.clear();
+    running = false;
+    for (const slot of slots) slot.channel.cancel();
+  }
+
+  function stop(message: string): void {
+    clear();
+    unavailable = message;
+    report();
+    onUnavailable?.(message);
+  }
+
+  function leastBusy(): Slot {
+    let best = slots[0] as Slot;
+    for (const slot of slots) {
+      if (slot.channel.pendingCount < best.channel.pendingCount) best = slot;
+    }
+    return best;
+  }
+
+  return {
+    size,
+    get progress() {
+      return progress();
+    },
+
+    submit(molecules) {
+      if (unavailable !== null) return;
+      if (!running && queue.size === 0 && inFlight.size === 0) {
+        done = 0;
+        total = 0;
+      }
+      for (const input of molecules) {
+        if (inFlight.has(input.key)) continue;
+        if (queue.add(input)) total += 1;
+      }
+      running = queue.size > 0 || inFlight.size > 0;
+      pump();
+      report();
+    },
+
+    prioritize(keys) {
+      queue.prioritize(keys);
+    },
+
+    async riskDetail(idCode: string, risk: RiskType): Promise<RiskDetail> {
+      const response = await requestRiskDetail(
+        () => leastBusy().channel,
+        { kind: 'riskDetail', resources, idCode, risk },
+        () => !terminated && unavailable === null,
+      );
+      if (response.kind === 'unavailable') {
+        stop(response.message);
+        throw new PredictorsUnavailableError(response.message);
+      }
+      if (response.kind !== 'riskDetail') {
+        throw new Error('The worker answered something other than a detail.');
+      }
+      return response.detail;
+    },
+
+    cancel() {
+      clear();
+      report();
+    },
+
+    terminate() {
+      terminated = true;
+      clear();
+      for (const slot of slots) slot.channel.terminate();
+    },
+  };
+}