Command-line interface

rbfenet command-line entry point.

Standard argparse shape: build_parser() assembles subcommands, dispatch() routes to a thin handler, main() handles exit codes.

Exit codes: 0 success, 1 a package-level failure (unsatisfiable constraints, a missing plugin, unreadable input), 2 argparse usage error.

rbfenetmap.cli.main.build_parser()[source]

Assemble the full argument parser.

Return type:: ArgumentParser

rbfenetmap.cli.main.dispatch(args, parser)[source]

Route parsed arguments to the matching handler.

Parameters:

args (Namespace)
parser (ArgumentParser)

Return type:

int

rbfenetmap.cli.main.main(argv=None)[source]

Entry point for the rbfenet console script.

Package-level errors are reported as a single message rather than a traceback: an unsatisfiable constraint or a missing plugin is a user-facing condition, and its message already says what to do. -v restores the traceback for debugging.

Parameters:: argv (Sequence[str] | None)
Return type:: int

CLI command handlers.

Each cmd_* is a thin adapter: parse arguments into options objects, call the library, format the result. Anything a handler needs to decide is a decision the library should be making, so that an embedding program gets the same behaviour without going through argparse.

rbfenetmap.cli.commands.cmd_export(args)[source]

Export an already-planned network.

Parameters:: args (Namespace)
Return type:: int

rbfenetmap.cli.commands.cmd_inspect(args)[source]

Show everything known about one edge of a planned network.

Parameters:: args (Namespace)
Return type:: int

rbfenetmap.cli.commands.cmd_map(args)[source]

Compute and report mappings for specific pairs, without planning.

Parameters:: args (Namespace)
Return type:: int

rbfenetmap.cli.commands.cmd_plan(args)[source]

Plan a network and write it out.

Parameters:: args (Namespace)
Return type:: int

rbfenetmap.cli.commands.cmd_plugins(args)[source]

List registered plugins and their availability.

Parameters:: args (Namespace)
Return type:: int

rbfenetmap.cli.commands.cmd_replan(args)[source]

Prune high-LMI edges from a planned network and replan the gaps.

The pruned edges are printed rather than only recorded, because the network JSON’s options block does not persist banned_edges: without the printout the fact that anything was pruned would survive only in this terminal.

Parameters:: args (Namespace)
Return type:: int

rbfenetmap.cli.commands.cmd_report(args)[source]

Render a self-contained HTML report of a planned network.

Parameters:: args (Namespace)
Return type:: int

rbfenetmap.cli.commands.cmd_score(args)[source]

Score candidate edges and print a ranked table, without selecting a network.

Parameters:: args (Namespace)
Return type:: int

Shared argument groups and parsing helpers for the CLI.

Factored out so that plan, score, and map accept the same flags with the same defaults. A knob that means one thing under plan and another under score is worse than no knob.

rbfenetmap.cli._args.COMPAT_CLI_PINS: dict[str, dict[str, Any]] = {'v0.4': {'adaptive_batch_size': 32, 'adaptive_initial_neighbors': 3, 'allow_disconnected': False, 'cbfe': 'off', 'cbfe_atom_weight': 0.05, 'cbfe_base_cost': 8.0, 'charge_change_policy': 'penalize', 'cluster_bridges': 2, 'cluster_by': 'none', 'consistency': 'pairwise', 'core_rmsd_threshold': 2.0, 'cycle_coverage_mode': 'node', 'design': 'none', 'design_candidate_factor': 3.0, 'design_lambda_max': 24, 'design_lambda_min': 12, 'design_refine': False, 'design_total_ns': None, 'distance_threshold': 2.0, 'edge_direction': 'fewer_softcore_first', 'edges_per_ligand': 2, 'hub_selection': 'most_partners', 'intermediate_beta': 0.1, 'intermediate_generator': 'pairmap', 'intermediate_max_cycle': 4, 'intermediate_max_dist': 3, 'intermediate_max_subgraph_dist': 4, 'intermediate_min_link_score': 0.2, 'intermediate_pose_attempts': 10, 'intermediate_pose_rmsd_factor': 0.5, 'intermediate_seed': 61453, 'intermediates': 'off', 'intermediates_per_gap': 4, 'mapper': 'mcss-e2', 'mapper_opt': None, 'match_selection': 'fewest_fragments', 'max_cycle_size': None, 'max_diameter': None, 'max_intermediate_gaps': None, 'max_intermediates': None, 'max_softcore_atoms': 12, 'max_softcore_fraction': 0.6, 'mcs_timeout': 60, 'min_core_atoms': 4, 'min_cycle_coverage': 1.0, 'min_mcs_fraction': 0.35, 'n_edges': None, 'n_redundancy': 2, 'pair_evaluation': 'eager', 'pair_strategy': 'all_unordered_pairs', 'planner': 'mst', 'prefilter': 'none', 'prefilter_k': 8, 'prefilter_min_tanimoto': 0.4, 'ring_policy': 'ring_system', 'scorer': 'linear', 'selection_objective': 'uniform_redundancy', 'weights': None, 'weights_file': None}}

What --compat LEVEL pins, as CLI destination names, per level.

These are literal transcriptions of what the named release did, not a view onto the current defaults. Deriving them from the parser would be shorter and would defeat the mechanism entirely: when a later version moves a default, a derived table moves with it and silently stops reproducing the version it names.

The pinned surface is the algorithmic one – the knobs whose meaning or default may change between releases. Deliberately absent are the settings that describe this run rather than this behaviour:

ligand-specific intent (hub, forced_edge, banned_edge, explicit_edge): banning an edge is a statement about one ligand set, not about a version;
input preparation (ligands, align and friends): that is which molecules go in, not how they are planned;
operational knobs (jobs, progress, out, export): they cannot change which network is produced.

All three stay usable alongside a compat level, which is what makes it practical rather than merely principled.

rbfenetmap.cli._args.add_compat_argument(parser)[source]

Add --compat, which pins every algorithmic knob to a released behaviour.

Parameters:: parser (ArgumentParser)
Return type:: None

rbfenetmap.cli._args.add_cost_units_argument(parser)[source]

Add --cost-units, which chooses how a cost report is expressed.

Deliberately absent from COMPAT_CLI_PINS and from NetworkOptions. It is a display unit, on the same footing as --format or --show-rejected: no planner reads it, no edge moves because of it, and pinning it would refuse --compat v0.4 --cost-units gpu_hours, a combination with no contradiction in it at all. Reproducing a released behaviour is a statement about which network comes out, not about what units it is printed in.

Parameters:: parser (ArgumentParser)
Return type:: None

rbfenetmap.cli._args.add_ligand_arguments(parser)[source]

Add the ligand-input flags.

Parameters:: parser (ArgumentParser)
Return type:: None

rbfenetmap.cli._args.add_mapping_arguments(parser)[source]

Add the mapper-selection flags.

Parameters:: parser (ArgumentParser)
Return type:: None

rbfenetmap.cli._args.add_network_arguments(parser)[source]

Add the network-selection flags.

Parameters:: parser (ArgumentParser)
Return type:: None

rbfenetmap.cli._args.add_scorer_arguments(parser)[source]

Add the scorer-selection flags.

Lives here rather than in rbfenetmap.cli.main beside its four siblings, so that the whole plan surface can be assembled from public functions. Anything that wants to reason about the flags – a form generator, a documentation build – needs the same five groups, and one of them being private made that impossible without reaching into another module’s underscore.

Parameters:: parser (ArgumentParser)
Return type:: None

rbfenetmap.cli._args.add_softcore_arguments(parser)[source]

Add the soft-core feasibility flags.

Parameters:: parser (ArgumentParser)
Return type:: None

rbfenetmap.cli._args.build_alignment_options(args)[source]

Assemble AlignmentOptions, or None when --align was not given.

Returning None rather than an options object with alignment switched off keeps the “not requested” case out of the library entirely: nothing downstream has to test for a do-nothing method.

Parameters:: args (Namespace)
Return type:: AlignmentOptions | None

rbfenetmap.cli._args.build_mapping_options(args)[source]

Assemble MappingOptions from parsed arguments.

Parameters:: args (Namespace)
Return type:: MappingOptions

rbfenetmap.cli._args.build_network_options(args)[source]

Assemble NetworkOptions from parsed arguments.

Parameters:: args (Namespace)
Return type:: NetworkOptions

rbfenetmap.cli._args.explicit_dests(parser, argv)[source]

Return the destinations the user actually named on the command line.

Comparing the parsed value against the current default cannot answer this, and the difference is the whole reason --compat exists: once a release moves a default, an unnamed flag and a deliberately-set one become indistinguishable that way, and every run would be reported as conflicting with the level it asked for.

So this re-parses the same argv against a parser whose defaults are all suppressed. Only what the user typed survives, which is exactly the question being asked.

Parameters:

parser (argparse.ArgumentParser) – A throwaway. Its defaults are suppressed in place, which leaves it unfit to parse anything else, so callers pass a freshly built one rather than the parser whose result they intend to use.
argv (Sequence[str], optional) – The same argv the real parse saw. None means sys.argv[1:].

Return type:

frozenset[str]

rbfenetmap.cli._args.parse_key_values(items, *, numeric=True)[source]

Parse repeated key=value arguments into a dictionary.

Parameters:

items (Sequence[str], optional)
numeric (bool, optional) – Convert values that parse as numbers, and true/false to booleans.

Raises:

argparse.ArgumentTypeError – If an item has no =. Failing loudly matters here: a mistyped --weights softcore_atoms 2 would otherwise be read as two separate items and silently ignored, and the run would quietly use the defaults.

Return type:

dict[str, Any]

rbfenetmap.cli._args.resolve_compat(args, explicit)[source]

Apply --compat to args in place, refusing any knob it contradicts.

Parameters:

args (argparse.Namespace) – Parsed arguments. Modified in place.
explicit (frozenset[str]) – Destinations the user named, from explicit_dests().

Raises:

SystemExit – Via argparse-style exit, if the user named an algorithmic knob alongside --compat.

Return type:

None

Notes

Rejecting rather than silently letting one win follows the rule the package already applies to n_edges against require_connected: both resolutions are defensible, so neither may be chosen on the user’s behalf. --compat v0.4 --max-diameter 5 is a request for v0.4’s behaviour and for something v0.4 could not do, and only the user can say which they meant.