Skip to content

Charges Analysis

Extract per-atom charge series and tables from ChargeData.

This module implements charge-domain analyzer tasks that slice by atom and frame, returning normalized tabular outputs for inspection and plotting. It is scoped to charge values and does not compute dipoles or polarization metrics.

Usage context

  • Charge tracking: Follow charge evolution for selected atoms over time.
  • Snapshot analysis: Build frame-specific charge tables for diagnostics.
  • Electrostatics pipelines: Provide charge tables to downstream analyzers.

Request: ChargeTableRequest

Request for per-atom charge extraction across frames.

Fields

Field Type Default Help Choices
atom_ids Optional[Sequence[int]] Optional atom-id filter. Example: [1, 5, 9].
atom_types Optional[Sequence[str]] Optional atom-type filter used when atom_ids is not provided. Example: ['O', 'H'].
frames Optional[Sequence[int]] Optional frame indices to include. Example: [0, 10, 20].
every int 1 Stride for selected frames. Example: every=5.

Examples

req = ChargeTableRequest(atom_ids=[1, 5, 9], every=5)

Sample output: ChargeTableRequest(...) Meaning: The request configures atom and frame filtering for charge extraction.

Task: ChargeTableTask

Return per-atom charges across selected frames as a tidy table.

Build default table/plot presentations for charge-table outputs.

Works on

Analyzer task output payloads

Parameters

Name Type Description
_result ChargeTableResult Analysis result object for the executed task.
payload dict[str, Any] Serialized result payload used by presentation dispatch.

Returns

Type Description
list[PresentationSpec] Recommended renderer specs for table and charge-vs-iteration plot.

Examples

specs = ChargeTableTask.recommended_presentations(result, payload)

Sample output: A list with table and grouped charge trend plot views. Meaning: Charge outputs can be rendered with default mappings.

Method: run(data: ChargeData, request: ChargeTableRequest, reporter=None)

Extract per-atom charges across selected frames as a tidy table.

Works on

ChargeData plus ChargeTableRequest analyzer inputs

Parameters

Name Type Description
data ChargeData Charge trajectory bundle with per-frame/per-atom charge values.
request ChargeTableRequest Atom and frame filtering configuration.
reporter Any, optional Unused progress callback parameter for task API compatibility.

Returns

Type Description
ChargeTableResult Result table containing selected charge samples.

Examples

result = ChargeTableTask().run(data, ChargeTableRequest(atom_types=["O"]))

Sample output: result.table with columns frame_index, iter, atom_id, charge. Meaning: Charges are normalized into one row per selected frame and atom.

Result: ChargeTableResult

Charge-table extraction result.

Fields

Field Type Default Help Choices
table pd.DataFrame
request ChargeTableRequest

Examples

result = ChargeTableTask().run(data, req)
result.table.head()

Sample output: DataFrame rows containing per-atom charge values at selected frames. Meaning: Each row is one (frame, atom) charge sample.