API Reference

Public Package

ngpb4py

Public package exports for ngpb4py.

NgpbConfig dataclass

Validated NextGenPB configuration plus input-file provenance.

defaults() classmethod

Build a configuration populated with documented upstream defaults.

from_prm(prm_path, schema=None) classmethod

Load a configuration from an existing .prm file.

iter_input_file_keys()

Yield input-file keys that should be staged for execution.

iter_items()

Iterate over stored option/value pairs.

prm_filename()

Return the staged .prm filename to use for a run.

resolve_input_file(key)

Resolve an input-file option against known user and source paths.

to_prm()

Render the configuration to canonical .prm text.

uses_packaged_default_input(key)

Whether an auxiliary input should come from packaged defaults.

validate()

Validate configured values against the known schema.

with_updates(updates)

Return a copy with selected option values overridden.

NgpbResult dataclass

Structured output, parsed logs, and provenance from a solver run.

log property

Parse and cache the structured log on first access.

log_excerpt property

Build and cache the tail excerpt of stdout on first access.

metrics property

Compute and cache derived metrics on first access.

parsed_outputs property

Parse supported output files on first access.

from_logs(run_id, scratch_dir, workdir, kept_files, command, stdout_path, stderr_path, output_paths, provenance, excerpt_lines=80) classmethod

Construct a result object from solver log and output files.

NgpbRunner dataclass

Runner that stages inputs, executes the solver, and parses results.

__enter__()

Enter a context manager that automatically closes backend resources.

__exit__(exc_type, exc, tb)

Ensure persistent backend resources are closed on context exit.

close()

Release any persistent backend resources held by the runner.

run(config, workdir=None, collect_version=None, verbose=None, keep_files=False)

Run NextGenPB for a configuration and return parsed results.

Configuration

config

Configuration objects and schema helpers for NextGenPB runs.

PrmOption dataclass

Schema entry describing a supported .prm option.

has_default property

Whether the option has a concrete default value.

NgpbConfig dataclass

Validated NextGenPB configuration plus input-file provenance.

defaults() classmethod

Build a configuration populated with documented upstream defaults.

from_prm(prm_path, schema=None) classmethod

Load a configuration from an existing .prm file.

iter_input_file_keys()

Yield input-file keys that should be staged for execution.

iter_items()

Iterate over stored option/value pairs.

prm_filename()

Return the staged .prm filename to use for a run.

resolve_input_file(key)

Resolve an input-file option against known user and source paths.

to_prm()

Render the configuration to canonical .prm text.

uses_packaged_default_input(key)

Whether an auxiliary input should come from packaged defaults.

validate()

Validate configured values against the known schema.

with_updates(updates)

Return a copy with selected option values overridden.

packaged_default_input(key)

Return the packaged default resource for an auxiliary input key.

Runner

runner

High-level execution entrypoints for running NextGenPB.

NgpbRunner dataclass

Runner that stages inputs, executes the solver, and parses results.

__enter__()

Enter a context manager that automatically closes backend resources.

__exit__(exc_type, exc, tb)

Ensure persistent backend resources are closed on context exit.

close()

Release any persistent backend resources held by the runner.

run(config, workdir=None, collect_version=None, verbose=None, keep_files=False)

Run NextGenPB for a configuration and return parsed results.

Results

result

Result objects returned from completed NextGenPB runs.

PotentialSampleSet dataclass

Sampled electrostatic potentials paired with 3D coordinates.

NgpbResult dataclass

Structured output, parsed logs, and provenance from a solver run.

log property

Parse and cache the structured log on first access.

log_excerpt property

Build and cache the tail excerpt of stdout on first access.

metrics property

Compute and cache derived metrics on first access.

parsed_outputs property

Parse supported output files on first access.

from_logs(run_id, scratch_dir, workdir, kept_files, command, stdout_path, stderr_path, output_paths, provenance, excerpt_lines=80) classmethod

Construct a result object from solver log and output files.

Log Parsing

logs

Structured parsers for documented NextGenPB terminal output.

AxisBounds dataclass

Minimum and maximum coordinates for one axis.

BoxBounds dataclass

Axis-aligned 3D bounds parsed from the domain section.

GridSubdivisions dataclass

Grid subdivision counts along each axis.

SystemInfo dataclass

Parsed values from the solver's system-information section.

DomainInfo dataclass

Parsed values describing the simulation domain and mesh.

SurfaceBuildInfo dataclass

Parsed status information for surface generation.

GridBuildInfo dataclass

Parsed counts reported while building the computational grid.

SolverInfo dataclass

Parsed solver configuration and convergence information.

ElectrostaticEnergy dataclass

Parsed electrostatic energy terms reported by NextGenPB.

ParsedLog dataclass

Top-level structured representation of a NextGenPB terminal log.

section_count()

Return the number of known log sections that were parsed.

to_metrics()

Flatten selected parsed values into metrics-friendly keys.

parse_log(text)

Parse documented NextGenPB terminal output into structured sections.

parse_log_metrics(text)

Parse a log and return the derived metrics dictionary.

PRM Parsing

prm

Parsing and rendering helpers for NextGenPB .prm files.

load_prm(path)

Load a .prm file into a dictionary with basic scalar coercion.

render_prm(data, schema)

Render configuration data to canonical .prm text.