API Reference

Complete reference for all modules, classes, and functions in wetting_angle_kit.

Parser Module

class wetting_angle_kit.parser.AseParser(filepath: str)

Bases: BaseParser

ASE trajectory parser.

Parameters:

filepath (str) – Path to any ASE-readable trajectory/file pattern (e.g. XYZ, extxyz, POSCAR, etc.).

box_length_max(frame_index: int) → float

Return maximum lattice vector length for frame.

box_size_x(frame_index: int) → float

Return x-dimension (a1x) of simulation cell for frame.

box_size_y(frame_index: int) → float

Return y-dimension (a2y) of simulation cell for frame.

frame_count() → int

Return total number of frames in trajectory.

get_profile_coordinates(frame_indices: Sequence[int], droplet_geometry: str = 'cylinder_y', atom_indices: Sequence[int] | None = None) → Tuple[ndarray, ndarray, int]

Compute 2D projection coordinates (r, z) for contact angle analysis.

Projects 3D atomic positions onto a 2D plane based on the assumed droplet geometry and simulation box boundaries.

Parameters:

• frame_indices (Sequence[int]) – List of frames to process.

• droplet_geometry (str, default 'cylinder_y') –

  The physical shape of the water droplet in the simulation box: * ‘cylinder_y’: A hemi-cylindrical droplet aligned along the Y-axis.

  (Returns x as the radial coordinate).

  • ’cylinder_x’: A hemi-cylindrical droplet aligned along the X-axis.

    (Returns y as the radial coordinate).

  • ’spherical’: A spherical cap droplet.

    (Returns sqrt(x^2 + y^2) as the radial coordinate).

• atom_indices (Sequence[int], optional) – Subset of atom indices to include (e.g., only liquid atoms).

Returns:

• r_values (np.ndarray) – The lateral/radial distances from the droplet center/axis.

• z_values (np.ndarray) – The vertical coordinates (height) of the atoms.

• n_frames (int) – Number of frames processed.

parse(frame_index: int, indices: ndarray | None = None) → ndarray

Return Cartesian coordinates for selected atoms in a frame from there index or the all frame if no index is provided.

Parameters:

• frame_index (int) – Frame index.

• indices (sequence[int], optional) – Atom indices to select; if None all atoms are returned.

Returns:

Cartesian coordinates of requested atoms.

Return type:

ndarray, shape (M, 3)

parse_liquid_particles(liquid_particle_types: List[str], frame_index: int) → ndarray

Return liquid atom coordinates filtering by atomic symbol list.

Parameters:

• liquid_particle_types (sequence[str]) – Symbols identifying liquid particles.

• frame_index (int) – Frame index.

Returns:

Liquid atom positions.

Return type:

ndarray, shape (L, 3)

class wetting_angle_kit.parser.AseWallParser(filepath: str, liquid_particle_types: List[str])

Bases: object

Parser extracting wall particle coordinates (excluding liquid types).

Parameters:

• filepath (str) – Path to trajectory file.

• liquid_particle_types (sequence[str]) – Symbols representing liquid particles to exclude.

box_length_max(frame_index: int) → float

Return maximum lattice vector length for frame.

box_size_y(frame_index: int) → float

Return y-dimension (a2y) of simulation cell for frame.

find_highest_wall_part(*args, **kwargs)

Deprecated alias for find_highest_wall_particle.

find_highest_wall_particle(frame_index: int) → float

Return the maximum z-coordinate among wall particles for a frame.

Parameters:

frame_index (int) – Frame index.

Returns:

Maximum z-coordinate.

Return type:

float

frame_count() → int

Return total number of frames in trajectory.

frame_tot() → int

Deprecated alias for frame_count.

get_profile_coordinates(frame_indices: Sequence[int], droplet_geometry: str = 'cylinder_y', atom_indices: Sequence[int] | None = None) → Tuple[ndarray, ndarray, int]

Compute 2D projection coordinates (r, z) for contact angle analysis.

Projects 3D atomic positions onto a 2D plane based on the assumed droplet geometry and simulation box boundaries.

Parameters:

• frame_indices (Sequence[int]) – List of frames to process.

• droplet_geometry (str, default 'cylinder_y') –

  The physical shape of the water droplet in the simulation box: * ‘cylinder_y’: A hemi-cylindrical droplet aligned along the Y-axis.

  (Returns x as the radial coordinate).

  • ’cylinder_x’: A hemi-cylindrical droplet aligned along the X-axis.

    (Returns y as the radial coordinate).

  • ’spherical’: A spherical cap droplet.

    (Returns sqrt(x^2 + y^2) as the radial coordinate).

• atom_indices (Sequence[int], optional) – Subset of atom indices to include (e.g., only liquid atoms).

Returns:

• r_values (np.ndarray) – The lateral/radial distances from the droplet center/axis.

• z_values (np.ndarray) – The vertical coordinates (height) of the atoms.

• n_frames (int) – Number of frames processed.

parse(frame_index: int) → ndarray

Return wall coordinates for the supplied frame index.

Parameters:

frame_index (int) – Frame index.

Returns:

Wall particle coordinates.

Return type:

ndarray

class wetting_angle_kit.parser.AseWaterMoleculeFinder(filepath: str, particle_type_wall: List[str], oxygen_type: str = 'O', hydrogen_type: str = 'H', oh_cutoff: float = 1.2)

Bases: object

Identify water oxygen atoms by counting hydrogen neighbors.

Uses ASE neighbor list to find oxygens with exactly two hydrogens.

Parameters:

• filepath (str) – Path to ASE-readable trajectory.

• particle_type_wall (sequence[str]) – Symbols representing wall particles (unused presently, reserved for filtering).

• oxygen_type (str, default "O") – Oxygen atom symbol.

• hydrogen_type (str, default "H") – Hydrogen atom symbol.

• oh_cutoff (float, default 1.2) – O–H distance cutoff used to detect bonded hydrogens.

get_water_oxygen_indices(frame_index: int) → ndarray

Return indices of oxygen atoms each bonded to exactly two hydrogens.

Parameters:

frame_index (int) – Frame index.

Returns:

Oxygen atom indices satisfying bonding criterion.

Return type:

ndarray

get_water_oxygen_positions(frame_index: int) → ndarray

Return Cartesian positions of water oxygen atoms for a frame.

Parameters:

frame_index (int) – Frame index.

Returns:

Oxygen atom positions; may be empty if none match criteria.

Return type:

ndarray, shape (N, 3)

class wetting_angle_kit.parser.BaseParser(filepath: str, particle_type_wall: Any)

Bases: ABC

Abstract interface for trajectory parsers consumed by analyzers.

Subclasses must implement frame parsing and frame count methods. Optional geometry helpers (box size, cylindrical conversion) can be overridden where supported by underlying file format.

Parameters:

• filepath (str) – Path to trajectory / structure file.

• particle_type_wall (Any) – Identifier(s) for wall particles (type IDs for LAMMPS dump, symbols for ASE/XYZ).

box_length_max(frame_index: int) → float

Return the maximum box length for a frame. (override if available).

box_size_x(frame_index: int) → float

Return the box x-length for a frame. (override if available).

box_size_y(frame_index: int) → float

Return the box y-length for a frame. (override if available).

abstractmethod frame_count() → int

Return the total number of frames available.

Returns:

Number of frames.

Return type:

int

frame_tot() → int

Return the total number of frames available. (Legacy name).

get_profile_coordinates(frame_indices: Sequence[int], droplet_geometry: str = 'cylinder_y', atom_indices: Sequence[int] | None = None) → Tuple[ndarray, ndarray, int]

Compute 2D projection coordinates (r, z) for contact angle analysis.

Projects 3D atomic positions onto a 2D plane based on the assumed droplet geometry and simulation box boundaries.

Parameters:

• frame_indices (Sequence[int]) – List of frames to process.

• droplet_geometry (str, default 'cylinder_y') –

  The physical shape of the water droplet in the simulation box: * ‘cylinder_y’: A hemi-cylindrical droplet aligned along the Y-axis.

  (Returns x as the radial coordinate).

  • ’cylinder_x’: A hemi-cylindrical droplet aligned along the X-axis.

    (Returns y as the radial coordinate).

  • ’spherical’: A spherical cap droplet.

    (Returns sqrt(x^2 + y^2) as the radial coordinate).

• atom_indices (Sequence[int], optional) – Subset of atom indices to include (e.g., only liquid atoms).

Returns:

• r_values (np.ndarray) – The lateral/radial distances from the droplet center/axis.

• z_values (np.ndarray) – The vertical coordinates (height) of the atoms.

• n_frames (int) – Number of frames processed.

abstractmethod parse(frame_index: int, indices: ndarray | None = None) → ndarray

Return Cartesian coordinates for selected atoms in a frame.

Parameters:

• frame_index (int) – Frame index.

• indices (ndarray[int], optional) – Atom indices to select; if None return all atoms.

Returns:

Particle coordinates.

Return type:

ndarray, shape (M, 3)

class wetting_angle_kit.parser.DumpParser(filepath: str)

Bases: BaseParser

LAMMPS dump trajectory parser.

Parameters:

filepath (str) – Path to LAMMPS dump file.

box_length_max(frame_index: int) → float

Return the maximum dimension of the simulation box.

Parameters:

frame_index (int) – Frame index.

Returns:

Maximum box length.

Return type:

float

box_size_x(frame_index: int) → float

Return x-dimension of simulation box.

box_size_y(frame_index: int) → float

Return y-dimension of simulation box.

frame_count() → int

Return the total number of frames in the trajectory.

Returns:

Number of frames.

Return type:

int

get_profile_coordinates(frame_indices: Sequence[int], droplet_geometry: str = 'cylinder_y', atom_indices: Sequence[int] | None = None) → Tuple[ndarray, ndarray, int]

Compute 2D projection coordinates (r, z) for contact angle analysis.

Projects 3D atomic positions onto a 2D plane based on the assumed droplet geometry and simulation box boundaries.

Parameters:

• frame_indices (Sequence[int]) – List of frames to process.

• droplet_geometry (str, default 'cylinder_y') –

  The physical shape of the water droplet in the simulation box: * ‘cylinder_y’: A hemi-cylindrical droplet aligned along the Y-axis.

  (Returns x as the radial coordinate).

  • ’cylinder_x’: A hemi-cylindrical droplet aligned along the X-axis.

    (Returns y as the radial coordinate).

  • ’spherical’: A spherical cap droplet.

    (Returns sqrt(x^2 + y^2) as the radial coordinate).

• atom_indices (Sequence[int], optional) – Subset of atom indices to include (e.g., only liquid atoms).

Returns:

• r_values (np.ndarray) – The lateral/radial distances from the droplet center/axis.

• z_values (np.ndarray) – The vertical coordinates (height) of the atoms.

• n_frames (int) – Number of frames processed.

parse(frame_index: int, indices: ndarray | None = None) → ndarray

Compute and return particle positions for a single frame, with optional filtering by particle indices.

Parameters:

• frame_index (int) – Frame index.

• indices (ndarray, optional) – Atom indices to select; if None return all atoms.

Returns:

Particle coordinates.

Return type:

ndarray, shape (M, 3)

class wetting_angle_kit.parser.DumpWallParser(filepath: str, liquid_particle_types: List[int])

Bases: object

LAMMPS dump file parser for extracting wall particle coordinates.

Parameters:

• filepath (str) – Path to LAMMPS dump file.

• liquid_particle_types (List[int]) – Type IDs of particles to exclude as liquid.

box_length_max(frame_index)

box_size_y(frame_index: int) → float

Return the y-dimension of the simulation box.

find_highest_wall_particle(frame_index: int) → float

Return the maximum z-coordinate among wall particles for a frame.

Parameters:

frame_index (int) – Frame index.

Returns:

Maximum z-coordinate.

Return type:

float

frame_count() → int

Return total number of frames.

get_profile_coordinates(frame_indices: Sequence[int], droplet_geometry: str = 'cylinder_y', atom_indices: Sequence[int] | None = None) → Tuple[ndarray, ndarray, int]

Compute 2D projection coordinates (r, z) for contact angle analysis.

Projects 3D atomic positions onto a 2D plane based on the assumed droplet geometry and simulation box boundaries.

Parameters:

• frame_indices (Sequence[int]) – List of frames to process.

• droplet_geometry (str, default 'cylinder_y') –

  The physical shape of the water droplet in the simulation box: * ‘cylinder_y’: A hemi-cylindrical droplet aligned along the Y-axis.

  (Returns x as the radial coordinate).

  • ’cylinder_x’: A hemi-cylindrical droplet aligned along the X-axis.

    (Returns y as the radial coordinate).

  • ’spherical’: A spherical cap droplet.

    (Returns sqrt(x^2 + y^2) as the radial coordinate).

• atom_indices (Sequence[int], optional) – Subset of atom indices to include (e.g., only liquid atoms).

Returns:

• r_values (np.ndarray) – The lateral/radial distances from the droplet center/axis.

• z_values (np.ndarray) – The vertical coordinates (height) of the atoms.

• n_frames (int) – Number of frames processed.

load_dump_ovito()

parse(frame_index)

Compute and return wall particle positions for a single frame.

Parameters:

frame_index (int) – Frame index.

Returns:

Array of wall particle positions.

Return type:

np.ndarray

class wetting_angle_kit.parser.DumpWaterMoleculeFinder(filepath: str, particle_type_wall: set, oxygen_type: int = 3, hydrogen_type: int = 2, oh_cutoff: float = 1.2)

Bases: object

Identify water oxygen atoms in a parsed LAMMPS trajectory.

get_water_oxygen_ids(frame_index: int) → ndarray

Return IDs of oxygen atoms belonging to water molecules.

class wetting_angle_kit.parser.XYZParser(filepath: str)

Bases: BaseParser

XYZ trajectory parser.

Parameters:

filepath (str) – Path to extended XYZ trajectory containing per-frame atom count, comment line with lattice vectors, then atom symbol + coordinates.

box_length_max(frame_index: int) → float

Return the maximum lattice vector length for a frame.

Parameters:

frame_index (int) – Frame index.

Returns:

Max |a_i| over lattice vectors.

Return type:

float

box_size_x(frame_index: int) → float

Return the box length along x (a1x component).

Parameters:

frame_index (int) – Frame index.

Returns:

Box x-length.

Return type:

float

box_size_y(frame_index: int) → float

Return the box length along y (a2y component).

Parameters:

frame_index (int) – Frame index.

Returns:

Box y-length.

Return type:

float

frame_count()

Return total number of frames loaded.

get_profile_coordinates(frame_indices: Sequence[int], droplet_geometry: str = 'cylinder_y', atom_indices: Sequence[int] | None = None) → Tuple[ndarray, ndarray, int]

Compute 2D projection coordinates (r, z) for contact angle analysis.

Projects 3D atomic positions onto a 2D plane based on the assumed droplet geometry and simulation box boundaries.

Parameters:

• frame_indices (Sequence[int]) – List of frames to process.

• droplet_geometry (str, default 'cylinder_y') –

  The physical shape of the water droplet in the simulation box: * ‘cylinder_y’: A hemi-cylindrical droplet aligned along the Y-axis.

  (Returns x as the radial coordinate).

  • ’cylinder_x’: A hemi-cylindrical droplet aligned along the X-axis.

    (Returns y as the radial coordinate).

  • ’spherical’: A spherical cap droplet.

    (Returns sqrt(x^2 + y^2) as the radial coordinate).

• atom_indices (Sequence[int], optional) – Subset of atom indices to include (e.g., only liquid atoms).

Returns:

• r_values (np.ndarray) – The lateral/radial distances from the droplet center/axis.

• z_values (np.ndarray) – The vertical coordinates (height) of the atoms.

• n_frames (int) – Number of frames processed.

load_xyz_file() → List[Dict[str, Any]]

Load all frames from the XYZ file into memory.

Returns:

Each entry has keys: symbols, positions, lattice_matrix.

Return type:

list[dict]

parse(frame_index: int, indices: ndarray | None = None) → ndarray

Return Cartesian coordinates for selected atoms in a frame.

Parameters:

• frame_index (int) – Frame index.

• indices (sequence[int], optional) – Atom indices to select; if None all atoms are returned.

Returns:

Coordinates of requested atoms.

Return type:

ndarray, shape (M, 3)

parse_liquid_particles(liquid_particle_types: List[str], frame_index: int) → ndarray

Return positions of liquid particles (filter by symbols).

Parameters:

• liquid_particle_types (sequence[str]) – Atom symbols considered liquid (e.g. water molecule constituents).

• frame_index (int) – Frame index.

Returns:

Cartesian coordinates of liquid atoms.

Return type:

ndarray, shape (L, 3)

class wetting_angle_kit.parser.XYZWaterMoleculeFinder(filepath, particle_type_wall, oxygen_type='O', hydrogen_type='H', oh_cutoff: float = 1.2)

Bases: BaseParser

Parser specialized for identifying water oxygen atoms in XYZ trajectories.

Parameters:

• filepath (str) – Path to XYZ file.

• particle_type_wall (sequence[str]) – Symbols that represent wall (excluded) particles.

• oxygen_type (str, default "O") – Oxygen atom symbol.

• hydrogen_type (str, default "H") – Hydrogen atom symbol.

• oh_cutoff (float, default 1.2) – Distance cutoff (Å) for O-H bonding to identify water molecules.

box_length_max(frame_index: int) → float

Return the maximum lattice vector length for a frame.

Parameters:

frame_index (int) – Frame index.

Returns:

Max |a_i| over lattice vectors.

Return type:

float

get_profile_coordinates(frame_indices: Sequence[int], droplet_geometry: str = 'cylinder_y', atom_indices: Sequence[int] | None = None) → Tuple[ndarray, ndarray, int]

Compute 2D projection coordinates (r, z) for contact angle analysis.

Projects 3D atomic positions onto a 2D plane based on the assumed droplet geometry and simulation box boundaries.

Parameters:

• frame_indices (Sequence[int]) – List of frames to process.

• droplet_geometry (str, default 'cylinder_y') –

  The physical shape of the water droplet in the simulation box: * ‘cylinder_y’: A hemi-cylindrical droplet aligned along the Y-axis.

  (Returns x as the radial coordinate).

  • ’cylinder_x’: A hemi-cylindrical droplet aligned along the X-axis.

    (Returns y as the radial coordinate).

  • ’spherical’: A spherical cap droplet.

    (Returns sqrt(x^2 + y^2) as the radial coordinate).

• atom_indices (Sequence[int], optional) – Subset of atom indices to include (e.g., only liquid atoms).

Returns:

• r_values (np.ndarray) – The lateral/radial distances from the droplet center/axis.

• z_values (np.ndarray) – The vertical coordinates (height) of the atoms.

• n_frames (int) – Number of frames processed.

get_water_oxygen_indices(frame_index)

Return indices of oxygen atoms belonging to water molecules.

Parameters:

frame_index (int) – Frame index.

Returns:

Indices of oxygen atoms with exactly two hydrogens within cutoff.

Return type:

ndarray

get_water_oxygen_positions(frame_index)

Return coordinates of water oxygen atoms for a frame.

Parameters:

frame_index (int) – Frame index.

Returns:

Oxygen atom positions; empty array if none detected.

Return type:

ndarray, shape (N, 3)

load_xyz_file()

Load frames (without lattice) for water oxygen analysis.

parse(liquid_particle_types: List[str], frame_index: int) → ndarray

Return liquid particle coordinates filtering wall types.

Parameters:

• liquid_particle_types (sequence[str]) – Symbols for liquid particles.

• frame_index (int) – Frame index.

Returns:

Liquid atom positions.

Return type:

ndarray, shape (L, 3)

Contact Angle Methods

Base Analyzer

class wetting_angle_kit.contact_angle_method.contact_angle_analyzer.BaseContactAngleAnalyzer

Bases: ABC

Abstract base for contact angle analysis across trajectories.

abstractmethod analyze(frame_range: List[int] | None = None, **kwargs) → Dict[str, Any]

Run the analysis and return statistics.

summary() → Dict[str, float]

Return quick summary statistics.

class wetting_angle_kit.contact_angle_method.contact_angle_analyzer.BinningContactAngleAnalyzer(parser, output_dir: str, **kwargs)

Bases: BaseContactAngleAnalyzer

This class is a wrapper around the ContactAngleBinning class. It is used to analyze the contact angle of a liquid on a solid surface.

analyze(frame_range: List[int] | None = None, split_factor: int | None = None, **kwargs) → Dict[str, Any]

Run the analysis and return statistics.

class wetting_angle_kit.contact_angle_method.contact_angle_analyzer.SlicedContactAngleAnalyzer(parser, output_repo: str, **kwargs)

Bases: BaseContactAngleAnalyzer

This class is a wrapper around the ContactAngleSlicedParallel class. It is used to analyze the contact angle of a liquid on a solid surface.

analyze(frame_range: List[int] | None = None, **kwargs) → Dict[str, Any]

Run the analysis and return statistics.

Sliced Method

Public exports for sliced contact angle method.

class wetting_angle_kit.contact_angle_method.sliced_method.SurfaceDefinition(atom_coords, delta_angle, max_dist, center_geom, gamma, density_conversion=1.0)

Bases: object

Radial line sampling interface estimator for sliced contact angle.

For each attitudinal angle beta the density is sampled along a ray emerging from the droplet geometric center. A simple tanh profile is fitted to obtain the interface position (“re”) which is then projected back to XZ plane.

Parameters:

• atom_coords (ndarray, shape (N, 3)) – Cartesian coordinates of liquid atoms.

• delta_angle (float) – Angular increment (degrees) between successive sampling rays.

• max_dist (float) – Maximum radial distance sampled along each ray.

• center_geom (ndarray, shape (3,)) – Approximate droplet geometric center.

• gamma (float) – Tilt angle (degrees) controlling rotation about the x-axis.

• density_conversion (float, default 1.0) – Factor applied multiplicatively to raw density contributions.

analyze_lines()

Sample density along radial lines and fit interface positions.

Returns:

• list_rbeta (list[list[float]]) –

  Fitted interface distance and its azimuth angle

  [interface_re, beta_deg].

• list_xz (list[list[float]]) – Projected interface coordinates [x_proj, z_proj] in XZ plane.

static density_contribution(positions, coords, sigma=2.0)

Return Gaussian-smoothed density contributions at sampling positions.

Parameters:

• positions (ndarray, shape (M, 3)) – Ray sampling coordinates.

• coords (ndarray, shape (N, 3)) – Atom coordinates contributing to density.

• sigma (float, default 2.0) – Gaussian standard deviation (Å). Larger values broaden contributions.

Returns:

Density values at each sampling position.

Return type:

ndarray, shape (M,)

static density_profile(z, zd, d, h)

Simple hyperbolic tangent profile used for interface localization.

Parameters:

• z (ndarray) – Distances along the sampling ray (Å).

• zd (float) – Interface position parameter to be fitted.

• d (float) – Amplitude scaling parameter.

• h (float) – Offset parameter.

Returns:

Modeled density values at each z.

Return type:

ndarray

fit_density_profile(z_data, density, param_bounds)

Fit the profile and return estimated interface position.

Parameters:

• z_data (ndarray) – Distances along the ray.

• density (ndarray) – Observed (smoothed) density values.

• param_bounds (tuple(list, list)) – Lower and upper bounds for (zd, d, h).

Returns:

Fitted zd value (interface location).

Return type:

float

Binning Method

Public exports for binning contact angle method.

class wetting_angle_kit.contact_angle_method.binning_method.HyperbolicTangentModel(initial_params=None)

Bases: SurfaceModel

Liquid–vapor interface model using a hyperbolic tangent profile.

The density field is modeled as the product of two sigmoidal (tanh) terms: one depending on the spherical radial distance and one along the vertical axis.

Parameters:

initial_params (list[float], optional) –

Seven parameters [rho1, rho2, R_eq, zi_c, zi_0, t1, t2]:

• rho1 : Liquid-phase density.

• rho2 : Vapor-phase density.

• R_eq : Equivalent spherical radius.

• zi_c : z-coordinate of the sphere center.

• zi_0 : Reference wall z-coordinate.

• t1 : Interface thickness (radial component).

• t2 : Interface thickness (vertical component).

compute_contact_angle()

Return the contact angle (degrees) implied by fitted parameters.

Returns:

Contact angle in degrees.

Return type:

float

compute_isoline(scale_factor=0.95)

Compute an iso-surface circle and wall line approximation.

Parameters:

scale_factor (float, default 0.95) – Factor applied to fitted radius for visualization.

Returns:

(circle_xi, circle_zi, wall_line_xi, wall_line_zi) arrays.

Return type:

tuple(ndarray, ndarray, ndarray, ndarray)

evaluate(x)

Evaluate the fitted hyperbolic tangent model at x.

Parameters:

x (tuple(float, float)) – Coordinates (xi, zi).

Returns:

Density value at the given point.

Return type:

float

fit(x_data, density_data)

Fit the model parameters to provided density samples.

Parameters:

• x_data (tuple(ndarray, ndarray)) – Coordinate arrays (xi_array, zi_array) flattened or broadcastable.

• density_data (ndarray) – Density values corresponding to x_data.

Returns:

Fitted model instance (self).

Return type:

HyperbolicTangentModel

get_parameter_strings()

Return formatted parameter strings suitable for logging.

Returns:

Formatted parameter strings ("name:value\n").

Return type:

list[str]

get_parameters()

Return a mapping of parameter names to fitted values.

Returns:

Dictionary of parameter names and values.

Return type:

dict[str, float]

Visualization and Statistics

class wetting_angle_kit.visualization_angles.BaseTrajectoryAnalyzer(directories, time_unit='ps')

Bases: ABC

analyze(output_filename='output_stats.txt')

Analyze and save statistics for each directory to an output file.

compute_statistics(directory)

Compute mean surface area, mean angle, and standard error.

Parameters:

directory (str) – Directory path.

Returns:

(x_value, y_value, y_error) where: - x_value: 1/sqrt(mean_surface_area) - y_value: mean contact angle - y_error: standard error of the mean

Return type:

tuple

get_clean_label(directory)

Generate a clean label from directory name.

Parameters:

directory (str) – Directory path.

Returns:

Cleaned directory name for plotting.

Return type:

str

abstractmethod get_contact_angles(directory)

Get contact angles for a given directory.

Parameters:

directory (str) – Directory path.

Returns:

Array of contact angle values.

Return type:

numpy.ndarray

abstractmethod get_method_name()

Return the name of this analysis method.

Returns:

Method name for labels and titles.

Return type:

str

abstractmethod get_surface_areas(directory)

Get surface areas for a given directory.

Parameters:

directory (str) – Directory path.

Returns:

Array of surface area values.

Return type:

numpy.ndarray

abstractmethod load_data()

Read and parse data from files in each directory.

plot_mean_angle_vs_surface(labels=None, color=None, save_path=None)

Generate a plot comparing mean angle vs surface area scaling. If no analysis output is found, run the analysis first.

Parameters:

• labels (list of str, optional) – Labels for each dataset. If None, directory names are used.

• color (str, optional) – Base color for all datasets. If None, a default set of unique colors is used.

• save_path (str, optional) – Path to save the figure.

class wetting_angle_kit.visualization_angles.BinningTrajectoryAnalyzer(directories, split_factor=1, time_steps=None, time_unit='ps')

Bases: BaseTrajectoryAnalyzer

Analyze binning trajectory data using circular segment calculations.

static circular_segment_area(R, z_center, z_cut)

Compute the area of a circular segment for any cut position.

get_contact_angles(directory)

Return contact angles for a directory.

get_method_name()

Return method name.

get_surface_areas(directory)

Return surface areas for a directory.

load_data()

Read and parse data from log files in each directory.

load_files()

Load and sort all relevant log files from each directory.

read_data()

Alias for load_data for backward compatibility.

class wetting_angle_kit.visualization_angles.ContactAngleAnimator(filename: str, particle_type_wall: set, oxygen_type: int, hydrogen_type: int, particule_liquid_type: set, n_frames: int = 10, droplet_geometry: str = 'cylinder_y', delta_cylinder: int = 5, max_dist: int = 100, width_cylinder: int = 21)

Bases: object

Generate interactive Plotly slider animation of median slice angle per frame.

generate_animation(output_filename: str = 'ContactAngle_Median_PerFrame_Slider.html')

Build and write HTML with slider of median contact angles over frames. :param output_filename: Output HTML file path. :type output_filename: str, default “ContactAngle_Median_PerFrame_Slider.html”

Returns:

Writes HTML file and prints path.

Return type:

None

class wetting_angle_kit.visualization_angles.DropletSlicedPlotter(center: bool = True, show_wall: bool = True, molecule_view: bool = True)

Bases: object

Plot droplet slice: surface contours, fitted circle and tangent line.

Parameters:

• center (bool, default True) – If True recentre z coordinates by subtracting mean wall z.

• show_wall (bool, default True) – Whether to draw wall particles.

• molecule_view (bool, default True) – If True draw fake hydrogens around each oxygen (schematic water view).

plot_surface_points(oxygen_position, surface_data, popt, wall_coords=None, output_filename=None, y_com=None, pbc_y=None, alpha=None)

Render slice figure and save to file.

Parameters:

• oxygen_position (ndarray (N, 3)) – Cartesian coordinates of oxygen atoms for the frame.

• surface_data (list[array]) – List of arrays with surface line coordinates (x, z) for each slice.

• popt (sequence) – Fitted circle parameters (Xc, Zc, R, extra) for chosen slice.

• wall_coords (ndarray (M, 3)) – Wall particle coordinates.

• output_filename (str or Path) – Path to save the PNG figure.

• y_com (float, optional) – Y centre used to select atoms in a thin slice. If None computed.

• pbc_y (float, optional) – Box length in y for PBC wrapping; if provided shortest-distance used.

• alpha (float, optional) – Contact angle in degrees; if given draw tangent line and arc.

Returns:

Saves figure to output_filename and closes it.

Return type:

None

class wetting_angle_kit.visualization_angles.DropletSlicedPlotterPlotly(center: bool = True)

Bases: object

Interactive Plotly slice visualization with toggleable layers.

plot_surface_points(oxygen_position, surface_data, popt, wall_coords, alpha=None, y_com=None, pbc_y=None, show_water=True, show_surface=True, show_circle=True, show_tangent=True, show_wall=True)

Create interactive Plotly figure for a single frame slice.

Parameters:

• oxygen_position (ndarray (N, 3)) – Oxygen atom coordinates.

• surface_data (list[array]) – List of surface contours for selected slice.

• popt (sequence) – Fitted circle parameters (Xc, Zc, R, extra).

• wall_coords (ndarray (M, 3)) – Wall particle coordinates.

• alpha (float, optional) – Contact angle for tangent construction.

• y_com (float, optional) – Mean y used for slicing; computed if None.

• pbc_y (float, optional) – Y box length for periodic slicing.

• show_water (bool) – Layer visibility toggles.

• show_surface (bool) – Layer visibility toggles.

• show_circle (bool) – Layer visibility toggles.

• show_tangent (bool) – Layer visibility toggles.

• show_wall (bool) – Layer visibility toggles.

Returns:

Configured figure object (not saved).

Return type:

plotly.graph_objects.Figure

class wetting_angle_kit.visualization_angles.MethodComparison(analyzers, method_names=None)

Bases: object

Utility to compare statistics from multiple trajectory analyzers. :param analyzers: Analyzer instances exposing directories and required API methods. :type analyzers: list :param method_names: Custom display names. If None, uses each analyzer’s get_method_name. :type method_names: list[str], optional

compare_statistics()

Print summary statistics aggregated across methods and directories.

plot_overlay_comparison(save_path=None, figsize=(8, 6), color='purple')

Overlay mean angle vs surface area scaling across all analyzers. Inspired by plot_mean_angle_vs_surface().

plot_side_by_side_comparison(save_path=None, figsize=(14, 5), color='purple')

Produce side-by-side comparison of mean contact angle vs. surface area scaling. Inspired by plot_mean_angle_vs_surface().

class wetting_angle_kit.visualization_angles.SlicedTrajectoryAnalyzer(directories, time_steps=None, time_unit='ps')

Bases: BaseTrajectoryAnalyzer

static calculate_polygon_area(points)

Calculate the area of a polygon given its vertices using the Shoelace formula.

Parameters:

points (numpy.ndarray) – Array of shape (N, 2) containing polygon vertices.

Returns:

Area of the polygon.

Return type:

float

get_contact_angles(directory)

Get contact angles (median alfas) for a directory.

get_method_name()

Return method name.

get_surface_areas(directory)

Get surface areas for a directory.

load_data()

Load the combined .npy files for all directories and calculate mean surface areas per frame.

mean_surface_frame(surfaces)

Calculate the mean surface area for a given surfaces file.

Parameters:

surfaces_file (str) – Path to the surfaces file.

Returns:

Mean surface area across all surfaces in the frame.

Return type:

float

plot_mean_alfas_evolution(save_path, labels=None)

Plot evolution of mean angle (Alfas) with standard deviation.

plot_median_alfas_evolution(save_path, labels=None, plot_std=True)

Plot evolution of median angle (Alfas) with standard deviation.

Align trajectories by truncating to shortest.

wetting_angle_kit.visualization_angles.plot_liquid_particles(positions, ax=None, color='tab:blue', subsample=None)

Scatter plot 3D particle positions with optional subsampling.

Parameters:

• positions (ndarray, shape (N, 3)) – Particle coordinates.

• ax (mpl_toolkits.mplot3d.Axes3D, optional) – Existing axes to plot on; new figure created if None.

• color (str, default "tab:blue") – Marker color.

• subsample (int, optional) – If provided and smaller than N, random subset size to plot.

Returns:

Axes object used for plotting.

Return type:

mpl_toolkits.mplot3d.Axes3D

wetting_angle_kit.visualization_angles.plot_slice(x, y)

Plot 2D slice given x,y arrays.

wetting_angle_kit.visualization_angles.plot_surface_and_points(x_surf, y_surf, z_surf, x_points, y_points, z_points)

Render 3D plot of surface curve and point cloud.

Parameters:

• x_surf (ndarray) – Surface coordinates.

• y_surf (ndarray) – Surface coordinates.

• z_surf (ndarray) – Surface coordinates.

• x_points (ndarray) – Point cloud coordinates.

• y_points (ndarray) – Point cloud coordinates.

• z_points (ndarray) – Point cloud coordinates.

wetting_angle_kit.visualization_angles.plot_surface_file(file_path)

Return x,y columns from surface text file.

Parameters:

file_path (str) – Path to whitespace-delimited file with at least two columns.

Returns:

(x, y) coordinate arrays.

Return type:

tuple(ndarray, ndarray)

wetting_angle_kit.visualization_angles.read_surface_file(file_path)

Load surface file returning x,y,z arrays (z zeros if absent).

Parameters:

file_path (str) – Path to surface file with 2 or 3 columns.

Returns:

(x, y, z) arrays; z is zeros if file has only two columns.

Return type:

tuple(ndarray, ndarray, ndarray)