Inference API

Single Inferencer

SingleInferencer Class

Distributed Inference

cryoPARES.inference.infer.distributed_inference(particles_star_fname, checkpoint_dir, results_dir, data_halfset='allParticles', model_halfset='matchingHalf', particles_dir=None, batch_size=<autoCLI_config.config_param.CONFIG_PARAM object>, n_jobs=None, num_dataworkers=<autoCLI_config.config_param.CONFIG_PARAM object>, use_cuda=<autoCLI_config.config_param.CONFIG_PARAM object>, n_cpus_if_no_cuda=<autoCLI_config.config_param.CONFIG_PARAM object>, compile_model=False, top_k_poses_nnet=<autoCLI_config.config_param.CONFIG_PARAM object>, top_k_poses_localref=<autoCLI_config.config_param.CONFIG_PARAM object>, grid_distance_degs=<autoCLI_config.config_param.CONFIG_PARAM object>, reference_map=None, reference_mask=None, directional_zscore_thr=<autoCLI_config.config_param.CONFIG_PARAM object>, skip_localrefinement=<autoCLI_config.config_param.CONFIG_PARAM object>, skip_reconstruction=<autoCLI_config.config_param.CONFIG_PARAM object>, subset_idxs=None, n_first_particles=None, check_interval_secs=2.0)[source]

Distributed inference across particles and devices, mirroring the halfset selection logic used by cryoPARES.inference.inference.SingleInferencer.

Parameters:

  • particles_star_fname (str) – Path to input RELION particles .star file

  • checkpoint_dir (str) – Path to training directory (or .zip file) containing half-set models with checkpoints and hyperparameters. By default they are called version_0, version_1, etc.

  • results_dir (str) – Output directory for inference results including predicted poses and optional reconstructions

  • data_halfset (Literal['half1', 'half2', 'allParticles']) – Which particle half-set(s) to process: “half1”, “half2”, or “allParticles”

  • model_halfset (Literal['half1', 'half2', 'allCombinations', 'matchingHalf', 'allParticles']) – Model half-set selection policy: “half1”, “half2”, “allCombinations”, or “matchingHalf” (uses matching data/model pairs)

  • particles_dir (Optional[str]) – Root directory for particle image paths. If provided, overrides paths in the .star file

  • batch_size (int) – Number of particles per batch for inference

  • n_jobs (Optional[int]) – Number of worker processes. Defaults to number of GPUs if CUDA enabled, otherwise 1

  • num_dataworkers (int) – Number of parallel data loading workers per GPU. Each worker is a separate CPU process. Set to 0 to load data in the main thread (useful only for debugging). Try not to oversubscribe by asking more workers than CPUs

  • use_cuda (bool) – Enable GPU acceleration for inference. If False, runs on CPU only

  • n_cpus_if_no_cuda (int) – Maximum CPU threads per worker when CUDA is disabled

  • compile_model (bool) – Compile model with torch.compile for faster inference (experimental, requires PyTorch 2.0+)

  • top_k_poses_nnet (int) – Number of top pose predictions to retrieve from neural network before local refinement

  • top_k_poses_localref (int) – Number of best matching poses to keep after local refinement

  • grid_distance_degs (float) – Maximum angular distance in degrees for local refinement search. Grid ranges from -grid_distance_degs to +grid_distance_degs around predicted pose

  • reference_map (Optional[str]) – Path to reference map (.mrc) for FSC computation during validation

  • reference_mask (Optional[str]) – Path to reference mask (.mrc) for masked FSC calculation

  • directional_zscore_thr (Optional[float]) – Confidence z-score threshold for filtering particles. Particles with scores below this are discarded as low-confidence

  • skip_localrefinement (bool) – Skip local pose refinement step and use only neural network predictions

  • skip_reconstruction (bool) – Skip 3D reconstruction step and output only predicted poses

  • subset_idxs (Optional[List[int]]) – List of particle indices to process (for debugging or partial processing)

  • n_first_particles (Optional[int]) – Process only the first N particles from dataset (debug feature)

  • check_interval_secs (float) – Polling interval in seconds for parent loop in distributed processing

Notes

  • For n_jobs == 1, this function delegates completely to SingleInferencer, which internally handles data_halfset and model_halfset (including “matchingHalf” and “allCombinations”).

  • For n_jobs > 1, particles are split by half-set and distributed across workers; model half selection follows the resolved policy per half to avoid cross-half coupling.

cryoPARES.inference.infer.worker(worker_id, output_q, *args, **kwargs)[source]
cryoPARES.inference.infer.main()[source]

Daemon Mode

Queue Manager

manager_server.py - Creates and manages the shared queue server. This script must be run first to establish the Manager server.

A single server instance can host multiple independent queues distinguished by name. Queues are created on demand the first time a client requests a given name, so the server does not need to know queue names in advance.

class cryoPARES.inference.daemon.queueManager.QueueManager(address=None, authkey=None, serializer='pickle', ctx=None, *, shutdown_timeout=1.0)[source]

Bases: BaseManager

Custom Manager class to handle our shared queues.

cryoPARES.inference.daemon.queueManager.connect_to_queue(ip='localhost', port=50000, authkey='shared_queue_key', queue_name='default')[source]

Connect to a named queue on the shared queue server.

Parameters:

  • ip – IP address of the queue manager server.

  • port – Port of the queue manager server.

  • authkey – Authentication key for the queue manager server.

  • queue_name (str) – Name of the queue to connect to. The server creates the queue on demand if it does not yet exist.

Returns:

Tuple of (queue proxy, manager) or (None, None) on failure.

cryoPARES.inference.daemon.queueManager.queue_manager_server(ip, port, authkey, queue_maxsize)[source]

Context manager that starts a QueueManager server.

The server hosts multiple independent named queues. Queues are created lazily on the first client request for a given name.

Yields (server, queue_store) where queue_store is the live {name: Queue} dict (useful for introspection in tests).

Parameters:

  • ip – IP address to bind the server to.

  • port – Port to bind the server to.

  • authkey – Authentication key for the server.

  • queue_maxsize – Maximum size for each queue (None = unlimited).

cryoPARES.inference.daemon.queueManager.signal_handler(signum, frame)[source]

Handle Ctrl+C or SIGTERM gracefully.

cryoPARES.inference.daemon.queueManager.queue_connection(ip='localhost', port=50000, authkey='shared_queue_key', queue_name='default')[source]

Context manager for connecting to a named queue on the shared server.

Parameters:

  • ip – IP address of the queue manager server.

  • port – Port of the queue manager server.

  • authkey – Authentication key for the queue manager server.

  • queue_name (str) – Name of the queue to connect to. The server creates the queue on demand if it does not yet exist.

cryoPARES.inference.daemon.queueManager.get_all_available_items(q)[source]

Gets all items from a queue. If the queue is empty, it waits for the first item. Then, it retrieves all other items without blocking.

Parameters:

q (Queue)

cryoPARES.inference.daemon.queueManager.main(ip='localhost', port=50000, authkey='shared_queue_key', queue_maxsize=None)[source]

Start the queue manager server.

A single server can host multiple independent named queues on the same port. Queues are created on demand when first requested by a client.

Parameters:

  • ip (str) – IP address to bind the server to.

  • port (int) – Port to bind the server to.

  • authkey (str) – Authentication key (password) for the server.

  • queue_maxsize (Optional[int]) – Maximum number of items per queue (None = unlimited).

Spooling Filler

spooler.py - Monitors a directory for new .star files and adds them to the shared queue for DaemonInferencer.

cryoPARES.inference.daemon.spoolingFiller.monitor_directory(directory, pattern='*.star', interval=10)[source]

Monitor a directory for new files matching the pattern and yield their paths.

Parameters:

  • directory (str) – Directory to monitor

  • pattern (str) – File pattern to match (default: *.star)

  • interval (int) – Time interval (seconds) between directory checks

cryoPARES.inference.daemon.spoolingFiller.main(directory, ip='localhost', port=50000, authkey='shared_queue_key', queue_name='default', pattern='*.star', check_interval=10)[source]

Main function to monitor a directory and feed new .star files to the queue.

Parameters:

  • directory (str) – Directory to monitor for .star files

  • ip (str) – Queue manager IP address

  • port (int) – Queue manager port

  • authkey (str) – Queue manager authentication key

  • queue_name (str) – Name of the queue to submit jobs to

  • pattern (str) – File pattern to match

  • check_interval (int) – Seconds between directory checks

Daemon Inference