Electrostatics Analysis

Run engine-agnostic electrostatics analyzers for dipole and polarization data.

This module computes dipole moments, polarization metrics, and related field-aligned summaries from electrostatics and connectivity inputs. It is bounded to electrostatics-domain calculations and does not handle generic trajectory geometry analyses outside those computations.

Usage context

• Dipole characterization: Compute local/total dipole vectors and magnitudes.
• Polarization analysis: Evaluate polarization trends and derived descriptors.
• Field studies: Relate electrostatic response to configured field directions.

Request: DipoleRequest

Request for dipole analysis.

Fields

Field	Type	Default	Help	Choices
scope	Scope	total	Dipole evaluation mode: 'total' (whole-system) or 'local' (per core atom). Example: 'local'.	total, local
atom_ids	Optional[Sequence[int]]		Optional core atom-id filter used in local mode. Example: [1, 5, 9].
atom_types	Optional[Sequence[str]]		Optional core atom-type filter in local mode (used when atom_ids is not set). 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 = DipoleRequest(scope="local", atom_types=["O"], every=5)

Sample output: DipoleRequest(...) Meaning: The request configures dipole extraction mode and frame/atom selection.

Parameters

• scope: "total" computes one dipole vector per frame for the whole system. "local" computes one dipole vector per selected core atom and frame. Example: scope="local".
• atom_ids: Optional core atom-id filter used in local mode. Example: [1, 5, 9].
• atom_types: Optional core atom-type filter used in local mode when atom_ids is not provided. Example: ["O", "H"].
• frames: Optional frame indices to include. If omitted, all frames are included. Example: [0, 10, 20].
• every: Frame stride after selection. Example: every=5 keeps every fifth selected frame.

Task: DipoleTask

Compute dipole series as total or local.

Method: recommended_presentations(_result: DipoleResult, payload: dict[str, Any])

Build default table/plot presentations for dipole outputs.

Works on

Analyzer task output payloads

Parameters

Name	Type	Description
_result	DipoleResult	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 dipole trend plot.

Examples

specs = DipoleTask.recommended_presentations(result, payload)

Sample output: Table view plus mu_z (debye) vs iter plot view. Meaning: Dipole outputs can be rendered with default mappings.

Method: run(data: ElectrostaticsData, request: DipoleRequest, reporter=None)

Compute dipole series in total or local scope.

Works on

ElectrostaticsData plus DipoleRequest analyzer inputs

Parameters

Name	Type	Description
data	ElectrostaticsData	Electrostatics bundle with trajectory, charges, and connectivity.
request	DipoleRequest	Dipole mode and selection configuration.
reporter	Any, optional	Optional progress callback invoked during local-series processing.

Returns

Type	Description
DipoleResult	Dipole table result with selected rows/components.

Examples

result = DipoleTask().run(data, DipoleRequest(scope="total"))

Sample output: result.table with dipole component columns. Meaning: Dipole vectors are computed per selected frame or core atom.

Result: DipoleResult

Dipole analysis result.

Fields

Field	Type	Default	Help	Choices
table	pd.DataFrame
request	DipoleRequest

Examples

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

Sample output: DataFrame with mu_x/y/z (debye) columns. Meaning: The table stores dipole vectors sampled across selected frames/atoms.

Output structure

• request: the :class:DipoleRequest used to compute this result.
• table: pandas.DataFrame with dipole components per selected frame (total mode) or per selected core atom and frame (local mode).

Common columns

• frame_index: source frame index.
• iter: simulation iteration mapped to the frame.
• mu_x (debye), mu_y (debye), mu_z (debye): dipole components.

Local-mode extra columns

• core_atom_id: selected core atom id.
• core_atom_type: selected core atom type.

Example

A row like frame_index=12, iter=1200, mu_z (debye)=1.45 means the z-component dipole at that frame is 1.45 Debye.

Request: PolarizationRequest

Request for polarization analysis.

Fields

Field	Type	Default	Help	Choices
scope	Scope	total	Polarization evaluation mode: 'total' (whole-system) or 'local' (per core atom). Example: 'local'.	total, local
atom_ids	Optional[Sequence[int]]		Optional core atom-id filter used in local mode. Example: [1, 5, 9].
atom_types	Optional[Sequence[str]]		Optional core atom-type filter in local mode (used when atom_ids is not set). 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.
volume_method	Optional[VolumeMethod]		Volume estimator for polarization normalization. Examples: 'hull', 'bbox', 'cell'.	hull, bbox, cell

Examples

req = PolarizationRequest(scope="total", volume_method="hull")

Sample output: PolarizationRequest(...) Meaning: The request configures polarization mode, sampling, and normalization.

Parameters

• scope: "total" computes one polarization vector per frame for the whole system. "local" computes local polarization around selected core atoms. Example: scope="local".
• atom_ids: Optional core atom-id filter used in local mode. Example: [1, 5, 9].
• atom_types: Optional core atom-type filter used in local mode when atom_ids is not provided. Example: ["O", "H"].
• frames: Optional frame indices to include. If omitted, all frames are included. Example: [0, 10, 20].
• every: Frame stride after selection. Example: every=5.
• volume_method: Volume estimator for polarization normalization. "hull": convex hull, "bbox": axis-aligned bounding box, "cell": simulation cell volume (total mode). Example: volume_method="hull".

Task: PolarizationTask

Compute polarization series as total or local.

Method: recommended_presentations(_result: PolarizationResult, payload: dict[str, Any])

Build default table/plot presentations for polarization outputs.

Works on

Analyzer task output payloads

Parameters

Name	Type	Description
_result	PolarizationResult	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 polarization trend plot.

Examples

specs = PolarizationTask.recommended_presentations(result, payload)

Sample output: Table view plus P_z (uC/cm^2) vs iter plot view. Meaning: Polarization outputs can be rendered with default mappings.

Method: run(data: ElectrostaticsData, request: PolarizationRequest, reporter=None)

Compute polarization series in total or local scope.

Works on

ElectrostaticsData plus PolarizationRequest analyzer inputs

Parameters

Name	Type	Description
data	ElectrostaticsData	Electrostatics bundle with trajectory, charges, and connectivity.
request	PolarizationRequest	Polarization mode, selection, and normalization configuration.
reporter	Any, optional	Optional progress callback invoked during local-series processing.

Returns

Type	Description
PolarizationResult	Polarization table result with selected rows/components.

Examples

result = PolarizationTask().run(data, PolarizationRequest(scope="total"))

Sample output: result.table including P_x/y/z (uC/cm^2) columns. Meaning: Polarization vectors are computed and normalized per selected scope.

Result: PolarizationResult

Polarization analysis result.

Fields

Field	Type	Default	Help	Choices
table	pd.DataFrame
request	PolarizationRequest

Examples

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

Sample output: DataFrame including P_x/y/z (uC/cm^2) columns. Meaning: The table stores normalized polarization responses over selected data.

Output structure

• request: the :class:PolarizationRequest used for computation.
• table: pandas.DataFrame with polarization components and volume terms per selected frame (total mode) or per selected core atom and frame (local mode).

Common columns

• frame_index: source frame index.
• iter: simulation iteration mapped to the frame.
• P_x (uC/cm^2), P_y (uC/cm^2), P_z (uC/cm^2): polarization components.
• volume (angstrom^3): normalization volume used for each row.

Local-mode extra columns

• core_atom_id: selected core atom id.
• core_atom_type: selected core atom type.

Example

A row like frame_index=12, iter=1200, P_z (uC/cm^2)=18.7 means the z-component polarization at that frame is 18.7 uC/cm^2.

Request: PolarizationFieldRequest

Request for polarization/dipole versus electric-field hysteresis analysis.

Fields

Field	Type	Default	Help	Choices
frames	Optional[Sequence[int]]		Optional frame indices to include. Example: [0, 10, 20].
every	int	1	Stride for selected frames. Example: every=5.
aggregate	AggregateKind		Optional aggregation over rows sharing the same field value. Example: 'mean'.	mean, max, min, last
field_direction	FieldDirection	z	Field axis used as hysteresis x-axis. 'z' maps to field_z. Example: 'z'.	x, y, z
dipole_or_polaization_direction	DipoleOrPolarizationDirection	p_z	Response axis for hysteresis. Example: 'mu_z' for dipole-z or 'p_z' for polarization-z.	mu_x, mu_y, mu_z, p_x, p_y, p_z

Examples

req = PolarizationFieldRequest(field_direction="z", dipole_or_polaization_direction="p_z")

Sample output: PolarizationFieldRequest(...) Meaning: The request defines field-response pairing and aggregation behavior.

Parameters

• frames: Optional frame indices to include. If omitted, all available frames are used. Example: [0, 10, 20].
• every: Frame stride after selection. Example: every=5.
• aggregate: Optional aggregation applied after pairing field and response values. Choices: - mean: average all rows sharing the same field value - max: maximum over grouped rows - min: minimum over grouped rows - last: keep the last row by iteration per field value - None: no aggregation
• field_direction: Electric-field axis used for hysteresis x-axis, mapped to field_x / field_y / field_z. Example: "z".
• dipole_or_polaization_direction: Response axis used for hysteresis y-axis. - mu_x/mu_y/mu_z map to dipole components - p_x/p_y/p_z map to polarization components Example: "p_z".

Task: PolarizationFieldTask

Compute polarization-field data and hysteresis roots.

Method: recommended_presentations(_result: PolarizationFieldResult, payload: dict[str, Any])

Build default presentations for polarization-field hysteresis outputs.

Works on

Analyzer task output payloads

Parameters

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

Returns

Type	Description
list[PresentationSpec]	Table presentations for full/aggregated tables plus optional hysteresis plot presentation.

Examples

specs = PolarizationFieldTask.recommended_presentations(result, payload)

Sample output: Full table view, aggregated table view, and optional hysteresis plot. Meaning: Field-response outputs are rendered with source-key-aware views.

Method: run(data: ElectrostaticsData, request: PolarizationFieldRequest)

Compute field-response hysteresis tables and zero-crossing metrics.

Works on

ElectrostaticsData plus PolarizationFieldRequest analyzer inputs

Parameters

Name	Type	Description
data	ElectrostaticsData	Electrostatics bundle including polarization inputs and electric field.
request	PolarizationFieldRequest	Hysteresis pairing, frame sampling, and aggregation configuration.

Returns

Type	Description
PolarizationFieldResult	Full/aggregated tables and computed zero-crossing lists.

Examples

result = PolarizationFieldTask().run(data, PolarizationFieldRequest())

Sample output: Aggregated hysteresis table with crossing metrics. Meaning: Electric-field and polarization/dipole series are paired for hysteresis analysis.

Result: PolarizationFieldResult

Hysteresis analysis result for field-response curves.

Fields

Field	Type	Default	Help	Choices
full_table	pd.DataFrame
aggregated_table	pd.DataFrame
polarization_zero_crossings	list[float]
field_zero_crossings	list[float]
request	PolarizationFieldRequest

Examples

result = PolarizationFieldTask().run(data, req)
result.aggregated_table.head()

Sample output: Aggregated field-response table plus zero-crossing lists. Meaning: The result packages hysteresis-ready data and derived crossing metrics.

Output structure

• request: the :class:PolarizationFieldRequest used to build the result.
• full_table: per-frame joined table with field and response values.
• aggregated_table: grouped table after optional aggregation.
• polarization_zero_crossings: x-values where y crosses zero.
• field_zero_crossings: y-values where x crosses zero.

Table semantics

full_table always contains: - iter and frame_index from polarization series - dipole columns mu_x/y/z (debye) - polarization columns P_x/y/z (uC/cm^2) - one field column chosen by request.field_direction: field_x or field_y or field_z (scaled to MV/cm)

Example

With field_direction='z' and dipole_or_polaization_direction='p_z', hysteresis is computed from x=field_z and y=P_z (uC/cm^2).