diffpy.cmi package

Complex modeling infrastructure: a modular framework for multi-modal modeling of scientific data.

Submodules

diffpy.cmi.log module

Centralized logging utilities for the CMI package.

This module exposes a single package logger plog and helpers to switch between a concise user mode and a verbose debug mode.

Modes

user

Only INFO and ERROR/CRITICAL records are shown. WARNING and DEBUG are hidden.

debug

All levels are shown.

Notes

Use set_log_mode() in the CLI to toggle visibility. The logger itself always emits at DEBUG level; a handler-side filter controls what is shown.

diffpy.cmi.log.get_log_mode() → str

Return "user" or "debug".

diffpy.cmi.log.is_debug() → bool

Return True when debug/verbose mode is active.

diffpy.cmi.log.set_log_mode(mode: str | bool = 'user') → None

Set visible logging mode.

Parameters:

mode ({"user","debug"} or bool, optional) –

• "user" (False): INFO and ERROR are visible

• "debug" (True): all levels visible.

diffpy.cmi.conda module

class diffpy.cmi.conda.CondaEnvInfo(available: bool, mamba: bool, env_name: str | None, prefix: str | None)

Bases: object

Snapshot of conda/mamba availability and the active environment.

Parameters:

• available (bool) – Whether conda is available on PATH.

• mamba (bool) – Whether mamba is available on PATH.

• env_name (str or None) – Name of the active environment, if known.

• prefix (str or None) – Filesystem prefix of the active environment, if known.

available: bool

env_name: str | None

mamba: bool

prefix: str | None

diffpy.cmi.conda.available() → bool

Return whether conda is available on PATH.

Returns:

True if the conda executable can be invoked.

Return type:

bool

diffpy.cmi.conda.env_info() → CondaEnvInfo

Return availability and active-environment metadata.

Returns:

Structured information assembled from conda info --json and availability probes.

Return type:

CondaEnvInfo

diffpy.cmi.conda.install_specs(specs: Sequence[str], *, channel: str | None = None, default_channel: str = 'conda-forge') → Tuple[str, int, str]

Install a batch of specs, preferring mamba then conda.

Parameters:

• specs (sequence of str) – Conda spec strings (e.g., "numpy>=1.24").

• channel (str or None, optional) – Preferred channel for this batch.

• default_channel (str, optional) – Channel used when channel is not given.

Returns:

The solver used ("mamba" or "conda"), the exit code, and the captured output (empty when streaming).

Return type:

tuple of (str, int, str)

Notes

This function logs at INFO level when each batch starts, warns when a mamba batch fails and a fallback is attempted, and leaves error decisions to higher-level callers.

diffpy.cmi.conda.list_installed_names() → List[str]

Return conda package names from conda list --json.

Results are cached for the current process to reduce repeated shell calls.

Returns:

Sorted unique package names.

Return type:

list of str

diffpy.cmi.conda.mamba_available() → bool

Return whether mamba is available on PATH.

Returns:

True if the mamba executable can be invoked.

Return type:

bool

diffpy.cmi.conda.reset_cache() → None

Reset the internal cache of installed package names.

diffpy.cmi.conda.run(cmd: Sequence[str], cwd: Path | None = None, *, capture: bool | None = None) → Tuple[int, str]

Run a subprocess with sensible, mode-dependent defaults.

The function does not decide logging policy. It simply runs the command and returns the exit code and combined output. Visibility of the child output follows CMI’s current log mode:

• In debug mode: stream output live by default.

• In user mode: capture output quietly by default.

Parameters:

• cmd (sequence of str) – Command and arguments.

• cwd (path-like, optional) – Working directory for the child process.

• capture (bool or None, optional) – Override the default visibility. True forces capture; False forces streaming; None selects the mode-dependent default.

Returns:

Exit code and captured output (empty string when streaming).

Return type:

tuple of (int, str)

Notes

When capturing in debug mode, the output is also echoed so developers still see live progress.

diffpy.cmi.packsmanager module

class diffpy.cmi.packsmanager.PacksManager(root_path=None)

Bases: object

Discovery, parsing, and installation for pack files.

packs_dir

Absolute path to the installed packs directory. Defaults to requirements/packs under the installed package.

Type:

pathlib.Path

examples_dir

Absolute path to the installed examples directory. Defaults to docs/examples under the installed package.

Type:

pathlib.Path

available_examples() → dict[str, List[tuple[str, Path]]]

Finds all examples for each pack and builds a dict.

Parameters:

root_path (Path) – Root path to the examples directory.

Returns:

A dictionary mapping pack names to lists of example names.

Return type:

dict

Raises:

FileNotFoundError – If the provided root_path does not exist or is not a directory.

available_packs() → List[str]

List all available packs.

Returns:

Pack basenames available under packs_dir.

Return type:

list of str

check_pack(identifier: str | Path) → bool

Return whether a pack is installed.

Parameters:

identifier (str or path-like) – Basename to the pack file.

Returns:

True if the pack is installed, False otherwise.

Return type:

bool

copy_examples(examples_to_copy: List[str], target_dir: Path | str = None, force: bool = False) → None

Copy examples or packs into the target or current working directory.

Parameters:

• examples_to_copy (list of str) – User-specified pack(s), example(s), or “all” to copy all.

• target_dir (pathlib.Path or str, optional) – Target directory to copy examples into. Defaults to current working directory.

• force (bool, optional) – Defaults to False. If True, existing files are overwritten and directories are merged (extra files in the target are preserved).

install_pack(identifier: str | Path) → None

Install a pack and verify presence.

Parameters:

identifier (str) – Basename to the pack file.

pack_requirements(identifier: str | Path) → List[ParsedReq]

Return parsed requirements for a pack.

Parameters:

identifier (str or path-like) – Installed pack name.

Returns:

Parsed requirements from the pack file.

Return type:

list of ParsedReq

print_examples() → None

Print information about available examples.

print_info() → None

Print information about available packs, profiles, and examples.

print_packs() → None

Print information about available packs.

diffpy.cmi.packsmanager.get_package_dir(root_path=None)

Get the package directory as a context manager.

Parameters:

root_path (str, optional) – Used for testing, overrides the files(__name__) call.

Returns:

A context manager that yields a pathlib.Path to the package directory.

Return type:

context manager

diffpy.cmi.installer module

class diffpy.cmi.installer.ParsedReq(raw: str, kind: str, name: str | None = None, spec: str | None = None, channel: str | None = None)

Bases: object

Parsed representation of a single requirement line.

A requirement line may declare a package or a script. Script lines set name to the basename (stem) of the script so presence checking can treat them like packages when appropriate.

Parameters:

• raw (str) – Original, unmodified line (kept verbatim).

• kind ({"script", "pkg", "skip"}) – Classification of the line.

• name (str or None, optional) – Package name (for pkg) or script basename (for script).

• spec (str or None, optional) – Version specifier (e.g., ">=1.2") for packages.

• channel (str or None, optional) – Optional channel (from channel::spec) for packages.

channel: str | None = None

kind: str

name: str | None = None

raw: str

spec: str | None = None

diffpy.cmi.installer.install_requirements(reqs: List[ParsedReq], *, scripts_root: Path, default_channel: str = 'conda-forge') → int

Install requirements, run scripts, and verify presence.

Policy

1. Packages first: batch per channel; solver failures are treated as soft (final presence check decides).

2. Scripts next: run native scripts only; a non-zero exit is a hard failure.

3. Presence check: verify packages and non-meta scripts.

param reqs:

Parsed requirements (from packs and profile extras).

type reqs:

list of ParsedReq

param scripts_root:

Directory containing relative scripts used by recipes.

type scripts_root:

path-like

param default_channel:

Default conda channel for batches. Defaults to "conda-forge".

type default_channel:

str, optional

returns:

0 on success, 1 on failure.

rtype:

int

diffpy.cmi.installer.parse_requirement_line(line: str) → ParsedReq

Parse a single requirement definition.

Supported forms

• Scripts: a line whose first token ends with .sh or .bat. The script’s basename becomes ParsedReq.name.

• Packages: an optional channel:: prefix followed by a valid PEP 508 requirement string (e.g., "numpy>=1.24").

param line:

Raw line from a requirements file.

type line:

str

returns:

Structured representation of the requirement.

rtype:

ParsedReq

diffpy.cmi.installer.presence_check(reqs: List[ParsedReq], *, check_meta: bool | None = True) → Tuple[bool, List[str]]

Check whether requirements appear satisfied.

Semantics

• Packages: mark missing when _is_installed() is False.

• Scripts: use the basename as a pseudo-package name. * If the basename starts with "_" (meta-scripts), count them as

  missing only when check_meta=True (profile checks). During post-install verification check_meta=False so meta-scripts are ignored (script exit code already enforced).

  • Otherwise, treat like a package and require the basename to be present.

param reqs:

Parsed requirements to check.

type reqs:

list of ParsedReq

param check_meta:

Whether meta-scripts should be considered missing. Defaults to True.

type check_meta:

bool, optional

returns:

(ok, missing) where ok is True when all checks pass and missing lists raw lines deemed missing.

rtype:

tuple of (bool, list of str)

diffpy.cmi.fit_tools module

diffpy.cmi.fit_tools.optimize_recipe(recipe, optimizer: str = 'leastsq', **kwargs)

Optimize the recipe using any selected SciPy optimizer.

minimize the residuals (FitRecipe().residual) of a FitRecipe by using a SciPy optimization function.

Parameters:

• recipe (FitRecipe) – The FitRecipe to be optimized.

• optimizer (str, optional) – The SciPy optimizer to use. Options are: ‘leastsq’, ‘least_squares’, ‘minimize’. Default is ‘leastsq’.

• **kwargs – Additional keyword arguments to pass to the optimizer.

diffpy.cmi.fit_tools.plot_results(x, yobs, ycalc, difference_offset=None)

Plot the results contained within a refined FitRecipe.

Parameters:

• x (array-like) – The independent variable.

• yobs (array-like) – The observed/experimental data.

• ycalc (array-like) – The calculated/fitted data.

• difference_offset (int or float, optional) – The y-axis offset for the difference curve. If None, defaults to -0.8 * max(yobs).

diffpy.cmi.cli module

diffpy.cmi.cli.main(argv: List[str] | None = None) → int

Run the CMI CLI.

Parameters:

argv (list of str, optional) – Argument vector to parse. When None, defaults to sys.argv[1:].

Returns:

Process exit code (0 success, 1 failure, 2 usage error).

Return type:

int

diffpy.cmi.cli.open_manual_and_exit() → None

Open the manual in a web browser and exit.

Notes

This function terminates the process with SystemExit(0).

diffpy.cmi.profilesmanager module

class diffpy.cmi.profilesmanager.Profile(name: str, packs: List[str], extras: List[str], source: Path)

Bases: object

Container for a resolved profile.

Parameters:

• name (str) – Profile name (defaults to the YAML stem).

• packs (list of str) – Pack basenames this profile depends on.

• extras (list of str) – Extra requirement lines (scripts or packages).

• source (path-like) – Absolute path to the YAML file that defined the profile.

• Format (Profile)

• --------------

• structure:: (All profile .yaml files must have the following) –

  packs:

  • <pack_name>

  extras:

  • <additional_package_name>

• profiles. (The file name is the profile identifier used for installing)

• example. (See requirements/profiles/all.yml for an)

extras: List[str]

name: str

packs: List[str]

source: Path

class diffpy.cmi.profilesmanager.ProfilesManager(packs_mgr: PacksManager | None = None, root_path=None)

Bases: object

Discovery, loading, checking and installation for profiles.

packs_mgr

The packs manager used for discovery and installation policy.

Type:

PacksManager, optional

profiles_dir

Absolute path to the installed profiles directory. Defaults to requirements/profiles under the installed package.

Type:

pathlib.Path

available_profiles() → List[str]

Return available installed profiles by basename.

Returns:

Profile basenames available under profiles_dir.

Return type:

list of str

check_profile(identifier: str | Path) → bool

Return whether a profile appears installed on this system.

Parameters:

identifier (str or path-like) – Basename or absolute YAML path.

Returns:

True if all packages and non-meta scripts appear present.

Return type:

bool

install(identifier: str | Path) → None

Install a profile and verify presence.

Parameters:

identifier (str or path-like) – Basename or absolute YAML path.

load(identifier: str | Path) → Profile

Load a profile file into a Profile object.

Parameters:

identifier (str or path-like) – Basename or absolute YAML path.

Returns:

Loaded profile with metadata.

Return type:

Profile

print_profiles() → None

Print available and installed profiles.