Classes
class	DistanceResult

Functions
	_get_codedistance ()

	_get_stim ()

Any	__getattr__ (str name)

None	set_distance_cache_file (Optional[Union[str, Path]] filepath=None)

Dict[str, Any]	load_distance_cache (Optional[Union[str, Path]] filepath=None)

None	save_distance_cache (Optional[Union[str, Path]] filepath=None)

None	clear_distance_cache (Optional[Union[str, Path]] cache_file=None, bool clear_file=False)

None	enable_distance_cache ()

None	disable_distance_cache ()

Dict[str, Any]	get_distance_cache ()

List[int]	format_bounds_list (int dmin, int dmax, int num_rw)

str	format_bounds_str (List[int] bounds)

str	explain_bounds (List[int] bounds, Optional[int] method=None, str label="")

Optional[Dict[str, Any]]	get_cached_distance (Optional[Any] H=None, Optional[Any] G=None, Optional[Any] L=None, Optional[Any] Hx=None, Optional[Any] Hz=None, Optional[Any] Lx=None, Optional[Any] Lz=None, Optional[Any] dem=None, Optional[Any] circuit=None, float pmin=0.0, Optional[Union[str, Path]] cache_file=None)

str	get_sparse_array_state (A)

str	create_unique_file (Union[str, Path] directory="tmp", str extension=".tmp")

List[List[int]]	read_sparse_vectors (str filepath)

str	find_dist_m4ri_binary (Optional[str] custom_path=None)

Tuple[int, int, int]	parse_dist_m4ri_output (str stdout)

Optional[str]	check_finc_outc (Optional[str] finC, Optional[str] outC, bool verbose=False)

Tuple[int, int, int]	run_dist_m4ri (Optional[str] dist_m4ri_path=None, int method=3, Optional[str] finH=None, Optional[str] finG=None, Optional[str] finL=None, Optional[str] fin=None, Optional[str] finC=None, Optional[str] fdem=None, int dmin=0, int dmax=0, int wmax=0, int wmin=1, int dexp=0, int dest=0, Optional[int] steps=None, Optional[int] threads=None, float timeout=60.0, Optional[int] smax=None, Optional[int] start=None, Optional[int] cbeg=None, Optional[int] cend=None, Optional[int] css=None, int noscan=0, int classical=-1, int dW=-1, int maxC=0, float pmin=0.0, Optional[str] outC=None, int seed=0, int debug=0, Optional[threading.Event] stop_event=None)

str	_matrix_to_file (matrix, str extension=".mtx", str temp_dir="tmp")

Any	compute_classical_distance (Any H, Optional[str] dist_m4ri=None, int method=3, Optional[int] threads=None, float timeout=60.0, Optional[int] num_steps=None, int d_exp=0, int d_min=0, int d_max=0, int dmin=0, int dmax=0, int wmin=1, int wmax=0, Optional[int] smax=None, Optional[int] start=None, Optional[int] cbeg=None, Optional[int] cend=None, int noscan=0, int dW=-1, int maxC=0, Optional[str] finC=None, Optional[str] outC=None, bool do_cws=False, bool return_info=False, Optional[Union[str, Path]] cache_file=None, str solver="dist_m4ri", str codedistance_method="QDistEvol", Optional[Dict[str, Any]] codedistance_params=None, int seed=0, int debug=0, bool verbose=False)

Any	compute_quantum_distance (Any H, Optional[Any] G=None, Optional[Any] L=None, Optional[str] dist_m4ri=None, int method=3, Optional[int] threads=None, float timeout=60.0, Optional[int] num_steps=None, int d_exp=0, int d_min=0, int d_max=0, int dmin=0, int dmax=0, int wmin=1, int wmax=0, Optional[int] smax=None, Optional[int] start=None, Optional[int] cbeg=None, Optional[int] cend=None, int noscan=0, int dW=-1, int maxC=0, Optional[str] finC=None, Optional[str] outC=None, bool do_cws=False, bool return_info=False, Optional[Union[str, Path]] cache_file=None, str solver="dist_m4ri", str codedistance_method="QDistEvol", Optional[Dict[str, Any]] codedistance_params=None, int seed=0, int debug=0, bool verbose=False)

Tuple[Any,...]	compute_css_distance (Any Hx, Any Hz, Optional[Any] Lx=None, Optional[Any] Lz=None, Optional[str] dist_m4ri=None, int method=3, Optional[int] threads=None, float timeout=60.0, Optional[int] num_steps=None, int d_exp=0, int d_min=0, int d_max=0, int dmin=0, int dmax=0, int wmin=1, int wmax=0, Optional[int] smax=None, Optional[int] start=None, Optional[int] cbeg=None, Optional[int] cend=None, int noscan=0, int dW=-1, int maxC=0, Optional[str] finC=None, Optional[str] outC=None, bool do_cws=False, Optional[Union[str, Path]] cache_file=None, str solver="dist_m4ri", str codedistance_method="QDistEvol", Optional[Dict[str, Any]] codedistance_params=None, int seed=0, int debug=0, bool verbose=False, **kwargs)

Tuple[Any,...]	compute_dem_distance (Optional[Any] dem=None, Optional[Any] circuit=None, Optional[str] dist_m4ri=None, int method=3, Optional[int] threads=None, float timeout=60.0, Optional[int] num_steps=None, int d_exp=0, int d_min=0, int d_max=0, int dmin=0, int dmax=0, int wmin=1, int wmax=0, Optional[int] smax=None, Optional[int] start=None, Optional[int] cbeg=None, Optional[int] cend=None, int noscan=0, int dW=-1, int maxC=0, float pmin=0.0, Optional[str] finC=None, Optional[str] outC=None, bool do_cws=False, Optional[Union[str, Path]] cache_file=None, str solver="dist_m4ri", str codedistance_method="UndetectableErrorStim", Optional[Dict[str, Any]] codedistance_params=None, int seed=0, int debug=0, bool verbose=False, **kwargs)

None	_write_nzlist_file (str filepath, List[List[int]] cws)

Dict[str, Any]	parse_cli_args (List[str] argv)

None	print_cli_help ()

int	main (Optional[List[str]] argv=None)

Variables
	_codedistance_mod = None

	_stim_mod = None

dict	_distance_cache = {}

bool	_use_distance_cache = True

Optional	_distance_cache_file = None

dict	_css_distance_cache = _distance_cache

bool	_use_css_distance_cache = _use_distance_cache

None	clear_css_distance_cache = clear_distance_cache

None	enable_css_distance_cache = enable_distance_cache

None	disable_css_distance_cache = disable_distance_cache

Detailed Description

dist_m4ri.py: Python wrapper for the multithreaded dist_m4ri distance calculator.

Provides high-level APIs for computing:
- Classical code distance: compute_classical_distance(...)
- Single-sided quantum code distance: compute_quantum_distance(...)
- CSS quantum code distance: compute_css_distance(...)
- Detector Error Model (DEM) distance: compute_dem_distance(...)

Supports distance caching, codeword export, and fallback/option for the codedistance library.
Since dist_m4ri natively handles multithreading (via POSIX threads and dynamic bracketing),
no Python-level threading or subprocess-per-core logic is necessary.

Function Documentation

◆ getattr()

Any dist_m4ri.__getattr__ ( str name )

Lazily resolves module attributes without loading heavy dependencies at startup.

Definition at line 56 of file dist_m4ri.py.

◆ _get_codedistance()

dist_m4ri._get_codedistance ( )

protected

Lazily imports the codedistance library only when requested.

Definition at line 32 of file dist_m4ri.py.

Referenced by compute_classical_distance(), compute_css_distance(), compute_dem_distance(), and compute_quantum_distance().

◆ _get_stim()

dist_m4ri._get_stim ( )

protected

Lazily imports stim only when requested.

Definition at line 44 of file dist_m4ri.py.

◆ _matrix_to_file()

str dist_m4ri._matrix_to_file	(		matrix,
		str	extension = `".mtx"`,
		str	temp_dir = `"tmp"`
	)

protected

Helper to convert a matrix (numpy or scipy sparse) or file path to an MTX file path.

Definition at line 666 of file dist_m4ri.py.

References create_unique_file().

Referenced by compute_classical_distance(), compute_css_distance(), and compute_quantum_distance().

◆ _write_nzlist_file()

None dist_m4ri._write_nzlist_file	(	str	filepath,
		List[List[int]]	cws
	)

protected

Writes codewords to a text file in NZLIST format (1-based indices).

Definition at line 1786 of file dist_m4ri.py.

Referenced by compute_classical_distance(), compute_css_distance(), compute_dem_distance(), compute_quantum_distance(), and main().

◆ check_finc_outc()

Optional[str] dist_m4ri.check_finc_outc	(	Optional[str]	finC,
		Optional[str]	outC,
		bool	verbose = `False`
	)

When finC and outC names are identical, an empty or non-existent file is silently ignored
(with a warning if verbose is True).

Returns:
    The effective finC filepath to use (or None if ignored).

Definition at line 544 of file dist_m4ri.py.

Referenced by compute_classical_distance(), compute_css_distance(), compute_dem_distance(), compute_quantum_distance(), main(), run_dist_m4ri(), and test_dist_m4ri.test_check_finc_outc().

◆ clear_distance_cache()

None dist_m4ri.clear_distance_cache	(	Optional[Union[str, Path]]	cache_file = `None`,
		bool	clear_file = `False`
	)

Clears all cached distance calculations from memory, and optionally deletes the persistent JSON file.

Definition at line 136 of file dist_m4ri.py.

Referenced by test_dist_m4ri.test_caching(), test_dist_m4ri.test_caching_cumulative_rw_steps(), test_dist_m4ri.test_persistent_json_cache(), and test_dist_m4ri.test_quantum_cache_separation().

◆ compute_classical_distance()

Any dist_m4ri.compute_classical_distance	(	Any	H,
		Optional[str]	dist_m4ri = `None`,
		int	method = `3`,
		Optional[int]	threads = `None`,
		float	timeout = `60.0`,
		Optional[int]	num_steps = `None`,
		int	d_exp = `0`,
		int	d_min = `0`,
		int	d_max = `0`,
		int	dmin = `0`,
		int	dmax = `0`,
		int	wmin = `1`,
		int	wmax = `0`,
		Optional[int]	smax = `None`,
		Optional[int]	start = `None`,
		Optional[int]	cbeg = `None`,
		Optional[int]	cend = `None`,
		int	noscan = `0`,
		int	dW = `-1`,
		int	maxC = `0`,
		Optional[str]	finC = `None`,
		Optional[str]	outC = `None`,
		bool	do_cws = `False`,
		bool	return_info = `False`,
		Optional[Union[str, Path]]	cache_file = `None`,
		str	solver = `"dist_m4ri"`,
		str	codedistance_method = `"QDistEvol"`,
		Optional[Dict[str, Any]]	codedistance_params = `None`,
		int	seed = `0`,
		int	debug = `0`,
		bool	verbose = `False`
	)

Computes the minimum distance of a classical linear code given parity check matrix H.

Args:
    H: Parity check matrix (numpy array, scipy sparse matrix, or file path).
    dist_m4ri: Path to dist_m4ri executable (optional).
    method: Solver method (1=RW, 2=CC, 3=Bracketing default).
    threads: Number of worker threads.
    timeout: Execution timeout in seconds.
    num_steps: Maximum RW steps.
    d_exp: Expected distance estimate.
    d_min / dmin: Known lower bound on distance.
    d_max / dmax: Known upper bound on distance.
    wmin: Minimum distance of interest (terminate early if cw of weight <= wmin is found in RW or CC, default: 1).
    wmax: Maximum weight to search in CC.
    smax: Maximum syndrome weight for CC confinement profile.
    start / cbeg / cend: Column search range for CC.
    noscan: Skip CC scan loop if 1.
    dW: Extra weight window above dmin to collect codewords.
    maxC: Maximum number of codewords to collect.
    finC: Input file with initial codewords.
    outC: Output file to save codewords (NZLIST format).
    do_cws: Whether to return extracted codewords.
    return_info: If True, return (dist, d_info) or (dist, d_info, cws) where d_info is [dmin, dmax, num_rw].
    cache_file: Optional JSON file path for persistent distance caching.
    solver: "dist_m4ri" or "codedistance".
    codedistance_method: Method if using codedistance library.
    codedistance_params: Extra parameters for codedistance library.
    seed: Random seed.
    debug: Debug level flags.
    verbose: Verbose reporting flag.

Returns:
    dist or (dist, cws) if do_cws is True (or (dist, d_info) / (dist, d_info, cws) if return_info=True)

Definition at line 686 of file dist_m4ri.py.

References _get_codedistance(), _matrix_to_file(), _write_nzlist_file(), check_finc_outc(), create_unique_file(), format_bounds_list(), get_sparse_array_state(), load_distance_cache(), read_sparse_vectors(), run_dist_m4ri(), and save_distance_cache().

Referenced by main(), test_dist_m4ri.test_caching(), test_dist_m4ri.test_caching_cumulative_rw_steps(), test_dist_m4ri.test_classical_distance_file(), test_dist_m4ri.test_classical_distance_numpy(), test_dist_m4ri.test_dmin_dmax_parameters(), test_dist_m4ri.test_persistent_json_cache(), and test_dist_m4ri.test_quantum_cache_separation().

◆ compute_css_distance()

Tuple[Any, ...] dist_m4ri.compute_css_distance	(	Any	Hx,
		Any	Hz,
		Optional[Any]	Lx = `None`,
		Optional[Any]	Lz = `None`,
		Optional[str]	dist_m4ri = `None`,
		int	method = `3`,
		Optional[int]	threads = `None`,
		float	timeout = `60.0`,
		Optional[int]	num_steps = `None`,
		int	d_exp = `0`,
		int	d_min = `0`,
		int	d_max = `0`,
		int	dmin = `0`,
		int	dmax = `0`,
		int	wmin = `1`,
		int	wmax = `0`,
		Optional[int]	smax = `None`,
		Optional[int]	start = `None`,
		Optional[int]	cbeg = `None`,
		Optional[int]	cend = `None`,
		int	noscan = `0`,
		int	dW = `-1`,
		int	maxC = `0`,
		Optional[str]	finC = `None`,
		Optional[str]	outC = `None`,
		bool	do_cws = `False`,
		Optional[Union[str, Path]]	cache_file = `None`,
		str	solver = `"dist_m4ri"`,
		str	codedistance_method = `"QDistEvol"`,
		Optional[Dict[str, Any]]	codedistance_params = `None`,
		int	seed = `0`,
		int	debug = `0`,
		bool	verbose = `False`,
		**	kwargs
	)

Computes CSS quantum code distance d = min(d_X, d_Z).

Args:
    Hx: X-stabilizer parity check matrix.
    Hz: Z-stabilizer parity check matrix.
    Lx: Optional X-logical operator matrix (alternative to Hz as finG).
    Lz: Optional Z-logical operator matrix (alternative to Hx as finG).
    dist_m4ri: Path to dist_m4ri executable (optional).
    method: Solver method (1=RW, 2=CC, 3=Bracketing default).
    threads: Number of worker threads.
    timeout: Execution timeout in seconds.
    num_steps: Maximum RW steps.
    d_exp: Expected distance estimate.
    d_min / dmin: Known lower bound on distance, inclusive.
    d_max / dmax: Known upper bound on distance, inclusive.
    wmin: Minimum distance of interest (terminate early if cw of weight <= wmin is found in RW or CC, default: 1).
    wmax: Maximum weight to search in CC.
    smax: Maximum syndrome weight for CC confinement profile.
    start / cbeg / cend: Column search range for CC.
    noscan: Skip CC scan loop if 1.
    dW: Extra weight window above dmin to collect codewords.
    maxC: Maximum number of codewords to collect.
    finC: Input file with initial codewords.
    outC: Output file to save codewords (NZLIST format).
    do_cws: Whether to return extracted X and Z codewords.
    cache_file: Optional JSON file path for persistent distance caching.
    solver: "dist_m4ri" or "codedistance".
    codedistance_method: Method if using codedistance library.
    codedistance_params: Extra parameters for codedistance library.
    seed: Random seed.
    debug: Debug level flags.
    verbose: Verbose reporting flag.

Returns:
    tuple (dist, dX_info, dZ_info, cws_X, cws_Z) if do_cws
    else (dist, dX_info, dZ_info)

Definition at line 1188 of file dist_m4ri.py.

References _get_codedistance(), _matrix_to_file(), _write_nzlist_file(), check_finc_outc(), create_unique_file(), format_bounds_list(), get_sparse_array_state(), load_distance_cache(), read_sparse_vectors(), run_dist_m4ri(), and save_distance_cache().

Referenced by main(), test_dist_m4ri.test_css_distance_files(), test_dist_m4ri.test_css_distance_sparse(), and test_dist_m4ri.test_persistent_json_cache().

◆ compute_dem_distance()

Tuple[Any, ...] dist_m4ri.compute_dem_distance	(	Optional[Any]	dem = `None`,
		Optional[Any]	circuit = `None`,
		Optional[str]	dist_m4ri = `None`,
		int	method = `3`,
		Optional[int]	threads = `None`,
		float	timeout = `60.0`,
		Optional[int]	num_steps = `None`,
		int	d_exp = `0`,
		int	d_min = `0`,
		int	d_max = `0`,
		int	dmin = `0`,
		int	dmax = `0`,
		int	wmin = `1`,
		int	wmax = `0`,
		Optional[int]	smax = `None`,
		Optional[int]	start = `None`,
		Optional[int]	cbeg = `None`,
		Optional[int]	cend = `None`,
		int	noscan = `0`,
		int	dW = `-1`,
		int	maxC = `0`,
		float	pmin = `0.0`,
		Optional[str]	finC = `None`,
		Optional[str]	outC = `None`,
		bool	do_cws = `False`,
		Optional[Union[str, Path]]	cache_file = `None`,
		str	solver = `"dist_m4ri"`,
		str	codedistance_method = `"UndetectableErrorStim"`,
		Optional[Dict[str, Any]]	codedistance_params = `None`,
		int	seed = `0`,
		int	debug = `0`,
		bool	verbose = `False`,
		**	kwargs
	)

Computes minimum graph/hypergraph distance of a Stim Detector Error Model (DEM).

Args:
    dem: stim.DetectorErrorModel object or path to .dem file.
    circuit: stim.Circuit object (converted to DEM).
    dist_m4ri: Path to dist_m4ri executable (optional).
    method: Solver method (1=RW, 2=CC, 3=Bracketing default).
    threads: Number of worker threads.
    timeout: Execution timeout in seconds.
    num_steps: Maximum RW steps.
    d_exp: Expected distance estimate.
    d_min / dmin: Known lower bound on distance, inclusive.
    d_max / dmax: Known upper bound on distance, inclusive.
    wmin: Minimum distance of interest (terminate early if cw of weight <= wmin is found in RW or CC, default: 1).
    wmax: Maximum weight to search in CC.
    smax: Maximum syndrome weight for CC confinement profile.
    start / cbeg / cend: Column search range for CC.
    noscan: Skip CC scan loop if 1.
    dW: Extra weight window above dmin to collect codewords.
    maxC: Maximum number of codewords to collect.
    pmin: Probability cutoff for error mechanisms in DEM.
    finC: Input file with initial codewords.
    outC: Output file to save codewords (NZLIST format).
    do_cws: Whether to return extracted error mechanisms / codewords.
    cache_file: Optional JSON file path for persistent distance caching.
    solver: "dist_m4ri" or "codedistance".
    codedistance_method: Method if using codedistance library.
    codedistance_params: Extra parameters for codedistance library.
    seed: Random seed.
    debug: Debug level flags.
    verbose: Verbose reporting flag.

Returns:
    tuple (dist, d_info, cws) if do_cws else (dist, d_info)

Definition at line 1524 of file dist_m4ri.py.

References _get_codedistance(), _write_nzlist_file(), check_finc_outc(), create_unique_file(), format_bounds_list(), get_sparse_array_state(), load_distance_cache(), read_sparse_vectors(), run_dist_m4ri(), and save_distance_cache().

Referenced by main(), test_dist_m4ri.test_dem_distance_file(), test_dist_m4ri.test_dem_distance_stim(), test_dist_m4ri.test_dmin_dmax_parameters(), and test_dist_m4ri.test_persistent_json_cache().

◆ compute_quantum_distance()

Any dist_m4ri.compute_quantum_distance	(	Any	H,
		Optional[Any]	G = `None`,
		Optional[Any]	L = `None`,
		Optional[str]	dist_m4ri = `None`,
		int	method = `3`,
		Optional[int]	threads = `None`,
		float	timeout = `60.0`,
		Optional[int]	num_steps = `None`,
		int	d_exp = `0`,
		int	d_min = `0`,
		int	d_max = `0`,
		int	dmin = `0`,
		int	dmax = `0`,
		int	wmin = `1`,
		int	wmax = `0`,
		Optional[int]	smax = `None`,
		Optional[int]	start = `None`,
		Optional[int]	cbeg = `None`,
		Optional[int]	cend = `None`,
		int	noscan = `0`,
		int	dW = `-1`,
		int	maxC = `0`,
		Optional[str]	finC = `None`,
		Optional[str]	outC = `None`,
		bool	do_cws = `False`,
		bool	return_info = `False`,
		Optional[Union[str, Path]]	cache_file = `None`,
		str	solver = `"dist_m4ri"`,
		str	codedistance_method = `"QDistEvol"`,
		Optional[Dict[str, Any]]	codedistance_params = `None`,
		int	seed = `0`,
		int	debug = `0`,
		bool	verbose = `False`
	)

Computes the minimum distance of a single-sided quantum code given parity check matrix H
and degeneracy generator G (or logical operator matrix L).

Args:
    H: Parity check matrix (numpy array, scipy sparse matrix, or file path).
    G: Degeneracy generator matrix (numpy array, scipy sparse matrix, or file path).
    L: Logical operator matrix (numpy array, scipy sparse matrix, or file path).
    dist_m4ri: Path to dist_m4ri executable (optional).
    method: Solver method (1=RW, 2=CC, 3=Bracketing default).
    threads: Number of worker threads.
    timeout: Execution timeout in seconds.
    num_steps: Maximum RW steps.
    d_exp: Expected distance estimate.
    d_min / dmin: Known lower bound on distance.
    d_max / dmax: Known upper bound on distance.
    wmin: Minimum distance of interest (terminate early if cw of weight <= wmin is found in RW or CC, default: 1).
    wmax: Maximum weight to search in CC.
    smax: Maximum syndrome weight for CC confinement profile.
    start / cbeg / cend: Column search range for CC.
    noscan: Skip CC scan loop if 1.
    dW: Extra weight window above dmin to collect codewords.
    maxC: Maximum number of codewords to collect.
    finC: Input file with initial codewords.
    outC: Output file to save codewords (NZLIST format).
    do_cws: Whether to return extracted codewords.
    return_info: If True, return (dist, d_info) or (dist, d_info, cws) where d_info is [dmin, dmax, num_rw].
    cache_file: Optional JSON file path for persistent distance caching.
    solver: "dist_m4ri" or "codedistance".
    codedistance_method: Method if using codedistance library.
    codedistance_params: Extra parameters for codedistance library.
    seed: Random seed.
    debug: Debug level flags.
    verbose: Verbose reporting flag.

Returns:
    dist or (dist, cws) if do_cws is True (or (dist, d_info) / (dist, d_info, cws) if return_info=True)

Definition at line 921 of file dist_m4ri.py.

References _get_codedistance(), _matrix_to_file(), _write_nzlist_file(), check_finc_outc(), create_unique_file(), format_bounds_list(), get_sparse_array_state(), load_distance_cache(), read_sparse_vectors(), run_dist_m4ri(), and save_distance_cache().

Referenced by main(), test_dist_m4ri.test_quantum_cache_separation(), and test_dist_m4ri.test_quantum_distance_single_sided().

◆ create_unique_file()

str dist_m4ri.create_unique_file	(	Union[str, Path]	directory = `"tmp"`,
		str	extension = `".tmp"`
	)

Creates a unique temporary file path and ensures the parent directory exists.

Definition at line 347 of file dist_m4ri.py.

Referenced by _matrix_to_file(), compute_classical_distance(), compute_css_distance(), compute_dem_distance(), and compute_quantum_distance().

◆ disable_distance_cache()

None dist_m4ri.disable_distance_cache ( )

Disables distance caching.

Definition at line 156 of file dist_m4ri.py.

Referenced by main().

◆ enable_distance_cache()

None dist_m4ri.enable_distance_cache ( )

Enables distance caching.

Definition at line 150 of file dist_m4ri.py.

Referenced by test_dist_m4ri.test_caching(), test_dist_m4ri.test_caching_cumulative_rw_steps(), and test_dist_m4ri.test_quantum_cache_separation().

◆ explain_bounds()

str dist_m4ri.explain_bounds	(	List[int]	bounds,
		Optional[int]	method = `None`,
		str	label = `""`
	)

Returns a human-readable explanation of [dmin, dmax, num_rw] following README.md.

Args:
    bounds: [dmin, dmax, rw_steps] list.
    method: Optional solver method (1=RW, 2=CC, 3=Bracketing).
    label: Optional prefix/label (e.g. "dX", "dZ", "").

Returns:
    Multi-line formatted explanation string.

Definition at line 197 of file dist_m4ri.py.

Referenced by main(), and test_dist_m4ri.test_explain_bounds().

◆ find_dist_m4ri_binary()

str dist_m4ri.find_dist_m4ri_binary ( Optional[str] custom_path = None )

Finds the dist_m4ri executable.

Definition at line 398 of file dist_m4ri.py.

Referenced by run_dist_m4ri(), and test_dist_m4ri.test_find_binary().

◆ format_bounds_list()

List[int] dist_m4ri.format_bounds_list	(	int	dmin,
		int	dmax,
		int	num_rw
	)

Returns [dmin, dmax, num_rw] according to:
- [d, d, 0] if known exactly
- [dmin, 0, 0] if there is no upper bound (dmax == 0)
- [0, dmax, num_rw] if there is no lower bound (dmin <= 1)
- [dmin, dmax, num_rw] otherwise

Definition at line 168 of file dist_m4ri.py.

Referenced by compute_classical_distance(), compute_css_distance(), compute_dem_distance(), compute_quantum_distance(), get_cached_distance(), and test_dist_m4ri.test_format_bounds_list_and_str().

◆ format_bounds_str()

str dist_m4ri.format_bounds_str ( List[int] bounds )

Formats a bounds list [dmin, dmax, num_rw] as a string, stating '(exact)' if bounds coincide.

Definition at line 189 of file dist_m4ri.py.

Referenced by main(), and test_dist_m4ri.test_format_bounds_list_and_str().

◆ get_cached_distance()

Optional[Dict[str, Any]] dist_m4ri.get_cached_distance	(	Optional[Any]	H = `None`,
		Optional[Any]	G = `None`,
		Optional[Any]	L = `None`,
		Optional[Any]	Hx = `None`,
		Optional[Any]	Hz = `None`,
		Optional[Any]	Lx = `None`,
		Optional[Any]	Lz = `None`,
		Optional[Any]	dem = `None`,
		Optional[Any]	circuit = `None`,
		float	pmin = `0.0`,
		Optional[Union[str, Path]]	cache_file = `None`
	)

Retrieves the cached distance entry (including bounds and cumulative rw_steps)
for a given code matrix, CSS code, or DEM.

Returns:
    dict with keys {"dist", "dmin", "dmax", "rw_steps", ...} or None if not cached.

Definition at line 241 of file dist_m4ri.py.

References format_bounds_list(), get_sparse_array_state(), and load_distance_cache().

Referenced by test_dist_m4ri.test_caching_cumulative_rw_steps(), and test_dist_m4ri.test_persistent_json_cache().

◆ get_distance_cache()

Dict[str, Any] dist_m4ri.get_distance_cache ( )

Returns the global distance cache dictionary.

Definition at line 162 of file dist_m4ri.py.

Referenced by test_dist_m4ri.test_quantum_cache_separation().

◆ get_sparse_array_state()

str dist_m4ri.get_sparse_array_state ( A )

Returns a deterministic string representation for JSON-compatible cache keys.

Definition at line 318 of file dist_m4ri.py.

Referenced by compute_classical_distance(), compute_css_distance(), compute_dem_distance(), compute_quantum_distance(), and get_cached_distance().

◆ load_distance_cache()

Dict[str, Any] dist_m4ri.load_distance_cache ( Optional[Union[str, Path]] filepath = None )

Loads distance cache from a JSON file into memory.

Definition at line 95 of file dist_m4ri.py.

Referenced by compute_classical_distance(), compute_css_distance(), compute_dem_distance(), compute_quantum_distance(), get_cached_distance(), and set_distance_cache_file().

◆ main()

int dist_m4ri.main ( Optional[List[str]] argv = None )

Definition at line 2028 of file dist_m4ri.py.

References _write_nzlist_file(), check_finc_outc(), compute_classical_distance(), compute_css_distance(), compute_dem_distance(), compute_quantum_distance(), disable_distance_cache(), explain_bounds(), format_bounds_str(), main(), parse_cli_args(), and print_cli_help().

Referenced by main(), test_dist_m4ri.test_cli_css_dx_dz_bounds(), test_dist_m4ri.test_cli_identical_finc_outc_nonexistent(), and test_dist_m4ri.test_cli_verbose_mode().

◆ parse_cli_args()

Dict[str, Any] dist_m4ri.parse_cli_args ( List[str] argv )

Parses CLI arguments supporting both key=value pairs and standard --flags.

Definition at line 1795 of file dist_m4ri.py.

Referenced by main(), and test_dist_m4ri.test_cli_argument_parsing().

◆ parse_dist_m4ri_output()

Tuple[int, int, int] dist_m4ri.parse_dist_m4ri_output ( str stdout )

Parses the standard output of dist_m4ri.
Expected format on stdout: "dmin dmax rw_steps", "dmin dmax", or a single integer.

Returns:
    tuple (dmin, dmax, rw_steps)

Definition at line 427 of file dist_m4ri.py.

Referenced by run_dist_m4ri().

◆ print_cli_help()

None dist_m4ri.print_cli_help ( )

Definition at line 1985 of file dist_m4ri.py.

Referenced by main().

◆ read_sparse_vectors()

List[List[int]] dist_m4ri.read_sparse_vectors ( str filepath )

Reads a list of sparse vectors from a text file in NZLIST format,
converting from 1-based indexing (in the file) to 0-based indexing (in Python).

Args:
    filepath (str): The path to the text file.

Returns:
    list of list of int: A list where each element is a 0-based sparse vector.

Definition at line 355 of file dist_m4ri.py.

Referenced by compute_classical_distance(), compute_css_distance(), compute_dem_distance(), and compute_quantum_distance().

◆ run_dist_m4ri()

Tuple[int, int, int] dist_m4ri.run_dist_m4ri	(	Optional[str]	dist_m4ri_path = `None`,
		int	method = `3`,
		Optional[str]	finH = `None`,
		Optional[str]	finG = `None`,
		Optional[str]	finL = `None`,
		Optional[str]	fin = `None`,
		Optional[str]	finC = `None`,
		Optional[str]	fdem = `None`,
		int	dmin = `0`,
		int	dmax = `0`,
		int	wmax = `0`,
		int	wmin = `1`,
		int	dexp = `0`,
		int	dest = `0`,
		Optional[int]	steps = `None`,
		Optional[int]	threads = `None`,
		float	timeout = `60.0`,
		Optional[int]	smax = `None`,
		Optional[int]	start = `None`,
		Optional[int]	cbeg = `None`,
		Optional[int]	cend = `None`,
		Optional[int]	css = `None`,
		int	noscan = `0`,
		int	classical = `-1`,
		int	dW = `-1`,
		int	maxC = `0`,
		float	pmin = `0.0`,
		Optional[str]	outC = `None`,
		int	seed = `0`,
		int	debug = `0`,
		Optional[threading.Event]	stop_event = `None`
	)

Low-level invocation of the multithreaded dist_m4ri binary.

Returns:
    tuple (dmin, dmax, rw_steps)

Definition at line 562 of file dist_m4ri.py.

References check_finc_outc(), find_dist_m4ri_binary(), and parse_dist_m4ri_output().

Referenced by compute_classical_distance(), compute_css_distance(), compute_dem_distance(), compute_quantum_distance(), test_dist_m4ri.test_dmin_dmax_parameters(), and test_dist_m4ri.test_run_dist_m4ri_three_numbers().

◆ save_distance_cache()

None dist_m4ri.save_distance_cache ( Optional[Union[str, Path]] filepath = None )

Saves the in-memory distance cache to a JSON file.
Uses atomic write via a temporary file to prevent corruption.

Definition at line 112 of file dist_m4ri.py.

Referenced by compute_classical_distance(), compute_css_distance(), compute_dem_distance(), and compute_quantum_distance().

◆ set_distance_cache_file()

None dist_m4ri.set_distance_cache_file ( Optional[Union[str, Path]] filepath = None )

Sets the default JSON file for persistent distance caching.
If the file exists, its contents are loaded into memory.

Definition at line 82 of file dist_m4ri.py.

References load_distance_cache().

Variable Documentation

◆ _codedistance_mod

dist_m4ri._codedistance_mod = None

protected

Definition at line 28 of file dist_m4ri.py.

◆ _css_distance_cache

dict dist_m4ri._css_distance_cache = _distance_cache

protected

Definition at line 78 of file dist_m4ri.py.

◆ _distance_cache

dict dist_m4ri._distance_cache = {}

protected

Definition at line 73 of file dist_m4ri.py.

◆ _distance_cache_file

Optional dist_m4ri._distance_cache_file = None

protected

Definition at line 75 of file dist_m4ri.py.

◆ _stim_mod

dist_m4ri._stim_mod = None

protected

Definition at line 29 of file dist_m4ri.py.

◆ _use_css_distance_cache

bool dist_m4ri._use_css_distance_cache = _use_distance_cache

protected

Definition at line 79 of file dist_m4ri.py.

◆ _use_distance_cache

bool dist_m4ri._use_distance_cache = True

protected

Definition at line 74 of file dist_m4ri.py.

◆ clear_css_distance_cache

None dist_m4ri.clear_css_distance_cache = clear_distance_cache

Definition at line 313 of file dist_m4ri.py.

◆ disable_css_distance_cache

None dist_m4ri.disable_css_distance_cache = disable_distance_cache

Definition at line 315 of file dist_m4ri.py.

◆ enable_css_distance_cache

None dist_m4ri.enable_css_distance_cache = enable_distance_cache

Definition at line 314 of file dist_m4ri.py.

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ __getattr__()

◆ _get_codedistance()

◆ _get_stim()

◆ _matrix_to_file()

◆ _write_nzlist_file()

◆ check_finc_outc()

◆ clear_distance_cache()

◆ compute_classical_distance()

◆ compute_css_distance()

◆ compute_dem_distance()

◆ compute_quantum_distance()

◆ create_unique_file()

◆ disable_distance_cache()

◆ enable_distance_cache()

◆ explain_bounds()

◆ find_dist_m4ri_binary()

◆ format_bounds_list()

◆ format_bounds_str()

◆ get_cached_distance()

◆ get_distance_cache()

◆ get_sparse_array_state()

◆ load_distance_cache()

◆ main()

◆ parse_cli_args()

◆ parse_dist_m4ri_output()

◆ print_cli_help()

◆ read_sparse_vectors()

◆ run_dist_m4ri()

◆ save_distance_cache()

◆ set_distance_cache_file()

Variable Documentation

◆ _codedistance_mod

◆ _css_distance_cache

◆ _distance_cache

◆ _distance_cache_file

◆ _stim_mod

◆ _use_css_distance_cache

◆ _use_distance_cache

◆ clear_css_distance_cache

◆ disable_css_distance_cache

◆ enable_css_distance_cache

◆ getattr()