View a signed volumetric field before interpreting charge transfer
For a real system, open the total and reference densities on the same grid in a volumetric viewer, then inspect signed difference-density isosurfaces and planar slices beside the atomic structure. Vary the isovalue and colour scale, integrate the full cell, and compare several sections; numerical closure complements visual inspection but cannot assign a unique chemical bond. Use visual tools and specialist field-analysis tools.
Start with real volumetric objects: export the combined and fragment densities, open them on the same grid, and inspect the signed field before interpreting it. This repository supplies no such output. The optional four-cell fixture below is invented arithmetic, not a charge-density field or software result.
Do not use the fixture as a substitute for those exports. It checks only the arithmetic distinction between local positive and negative cells and a closed complete-cell sum; it does not read a Quantum ESPRESSO or VASP density or perform an electronic-structure calculation.
For real work, the parent objects are the combined-system and fragment density fields generated in the same cell, on the same grid, with compatible geometry, density convention, spin/SOC state, occupations, and electron count. This fixture instead creates four invented combined and fragment values internally.
Purpose
If you want to test that arithmetic after inspecting the real grids, run from the repository root:
python3 examples/practical-guides/charge_difference_closure.pyThe command runs the deterministic arithmetic and prints a JSON object. It creates no image.
Inspect the reported quantities
Confirm that the process exits normally and prints the boundary sentence Execution establishes invented-grid arithmetic only; it is not a density field or DFT calculation. This is program-success evidence for the fixture only.
In the JSON output, inspect:
full_cell_delta_integral, which checks the signed complete-cell sum;positive_cell_sumandnegative_cell_sum, which confirm that local accumulation and depletion remain even when the full-cell sum closes;grid_cells, which identifies the four-cell invented object.
For this fixed fixture, full_cell_delta_integral should be zero within the script’s assertion while the positive and negative sums remain nonzero. This verifies the script’s invented arithmetic, not a physical density or its spatial distribution.
If a real subtraction does not close
Do not interpret its lobes yet. Check that every field has the same lattice vectors, grid registration, units, electron-number convention, reconstruction/core treatment, charge state, and frozen or relaxed fragment geometry. Then integrate the complete field using the volume element required by the file format.
The Quantum ESPRESSO pp.x documentation defines code-specific density outputs. VASP documents the contents and PAW one-center information of CHGCAR. These sources define the real parent objects; this guide does not verify them.
Passing this fixture supports only compatible-grid subtraction bookkeeping. It does not calculate a density, converge a grid, perform Bader analysis, assign an atomic charge, establish charge transfer, or support a material claim.