mag4.analysis

Geometric / post-DFT analyses (bridging-angle scans, WIEN2k moment extraction).

mag4.analysis.find_bridging_angles(structure, site_i, site_j, jimage, ligand_elements, bond_cutoff)

Find every ligand L bridging site_i and site_j (at jimage).

A ligand L bridges the pair when dist(site_i, L) < bond_cutoff AND dist(site_j + jimage, L) < bond_cutoff.

Returns a list of dicts sorted by angle.

mag4.analysis.group_into_shells(results, tol=0.01)

Cluster M–M pairs into distance shells (J1, J2, …).

Parameters:

tol (float)

mag4.analysis.compress_angles(ang_vals, tol=0.01)

Group similar angles: [159.07, 159.07, 159.07] → '159.07° (x3)'.

Return type:

str

Parameters:

• ang_vals (List[float])

• tol (float)

mag4.analysis.print_header(structure, element, ligand_elements, cutoff, bond_cutoff)

Print a header summarising the structure and the search parameters.

mag4.analysis.print_shell_summary(groups, element)

Brief summary of the J shells.

mag4.analysis.print_angles_for_shell(group, structure, element, ligand_elements, bond_cutoff, lines_out)

Bond-angle table for one J shell. Appends each printed line to lines_out.

mag4.analysis.extract_moments_from_scf(scf_path, atom_indices)

Parse a WIEN2k .scf file and return the converged :MMIxxx: values.

Line format:

:MMI009: MAGNETIC MOMENT IN SPHERE  9 =  2.85000

The last occurrence of each tag (i.e. the converged value) is kept.

Returns:

{atom_index: float or None}.

Return type:

dict

Parameters:

• scf_path (str)

• atom_indices (Iterable[int])

mag4.analysis.extract_total_moment(scf_path)

Return the last :MMTOT: total magnetic moment in cell.

Return type:

Optional[float]

Parameters:

scf_path (str)

mag4.analysis.find_cases(base_dir='.', scf_basename=None, code='wien2k')

Auto-detect config subdirectories with results for code (sorted).

code='wien2k' → directories with a .scf file (or exactly <scf_basename>.scf when given); code='vasp' → directories with an OUTCAR.

Return type:

List[str]

Parameters:

• base_dir (str)

• scf_basename (str | None)

• code (str)

mag4.analysis.build_table(cases, atom_indices, scf_basename=None, target=None, tol=0.5, code='wien2k')

Textual table of moments for each case + statistics + a target check.

code selects the parser: 'wien2k' reads per-sphere :MMI: values from <dir>/<scf_basename>.scf; 'vasp' reads the per-ion tot column of the last magnetization (x) block in <dir>/OUTCAR (needs LORBIT=10/11). For VASP the indices are 1-based POSCAR ion numbers (mag4 writes the magnetic atoms first, so they are 1 … n_mag).

Returns (lines, summary) where summary carries n_data (configs with a readable SCF), n_missing (SCF not found), failures (list of (case, reason) where a site did not reach the target moment within tol, or collapsed to ~0), and target.

target is the expected per-site |μ| (e.g. 2·S = the generated |MAGMOM|). When None the check only flags collapsed moments (|μ| < 0.1 μ_B), which usually mean the config fell into a non-magnetic solution rather than the intended spin state.

Return type:

Tuple[List[str], dict]

Parameters:

• cases (List[str])

• atom_indices (List[int])

• scf_basename (str | None)

• target (float | None)

• tol (float)

• code (str)

Modules

bond_angles	Bridging-ligand bond-angle analysis (M – L – M).
wien2k	Extract converged magnetic moments from WIEN2k .scf files.