ShelXFile_EDiSFAC

ShelXFile_EDiSFAC is a modification of ShelXFile[1] for the quick application of iSFAC modeling[2], which quantifies atomic charges in crystals with electron diffraction datasets using SHELXL[3], via Python. Visualization of the resulting models is supported through RDKit[4] and py3Dmol[5]. A table of scattering factors for ionic spiecies needs to be prepared separatey. edSFAC[6] can be used for that, as of July 2025.

Typical workflow

*Jupyternotebook examples with ED-data collected at CCSA in Univ. Vienna (L-histidine, tartrate crystal from a wine bottle) and a published data (rhodamine-6g) are available.

0. (Complete a conventional modeling and refinement beforehand.)
1. Prepare an SFAC table. All ions to be used must be defined there.
2. Prepare a working directory and place the .res and .hkl files (or symbolic links) inside it.
3. (Optional) Generate a new .ins with riding-hydrogens at elongated distances and run SHELXL (through Python).
4. (Optional) Generate a control file and modify it as needed.
5. Run SHELXL (through Python)
6. Check if the refinement converges without flipping the sign of the atomic charges. If not, optimize the starting pair of atomic charge signs (and other parameters).
7. Run another SHELXL refinement for esd calculation (through Python)
8. Visualize the results with 1D/2D/3D charts and check consistency with chemistry of the sample.
   • *3D charts are currently supported only in Jupyter Notebook interface.

from shelxfile.shelx.shelx import Shelxfile as Sfx
from extension import tools, visualize
import shutil

isfac_table = tools.load_iSFAC('sfac-electron_22Oct2024KT.dfx')
res_neutral = 'dials_a.res' # starting model
tools.prep_ctrl(res_neutral, 'control.list')

elongh_run_model = tools.run_for_elongh(res_neutral)
elongh_run_model.write_shelx_file('isfac_eh.ins')
shutil.copy('isfac_eh.ins', 'isfac_eh.res')
elongh_run = Sfx(verbose=False)
elongh_run.read_file('isfac_eh.res')
elongh_run.refine_myins(1, verbose=False)

isfac_model = tools.isfac(res_neutral, isfac_table, input_list='control.list')
isfac_model.write_shelx_file('isfac.ins')
shutil.copy('isfac.ins', 'isfac.res')
shx_run = Sfx(verbose=False)
shx_run.read_file('isfac.res')
shx_run.refine_myins(1, verbose=False)

tools.chkoutput('isfac.res', verbose=False)
visualize.showchargebars('isfac.lst', shx_run, 'control.list', png='1dview.png')

rdkit_mol, df_mol = visualize.res2rdkit('isfac.res', 'control.list')
visualize.rdkit_2d(rdkit_mol, df_mol, png='2dimage.png')

Features

• ShelXFile_EDiSFAC supports:
  • Creating a control file for iSFAC refinement.
  • Generating .ins file with riding hydrogens with the longer distances.
  • Generating .ins file with SHELXL commands required for iSFAC modeling (SFAC, EADP, EXYZ, SUMP, FVAR, PART).
  • Creating .ins file for e.s.d. calculation.
• Once SHELXL runs (via Python), results can be visualized in ways inspired by the original iSFAC publication [2]:
  • Bar-chart summary
  • 2D / 3D molecular representations

Examples

• L-histidine

• Tartrate

• Rhodamine-6g

Specification

• iSFAC modeling is the simpliest approach to quantify atomic charges with electron diffraction, while keeping atomic models spherical. Note that this definition is not identical to other charge-density methods (MAM, HAR, XRW, etc.). Results depend on the scattering factors defined by the user, and the data quality should be a critical factor as well.
• Signs of atomic charges do not always follow the electronegativity trend of isolated elements. If refinements suggest charge inversion, re-run refinements starting with the inverted signs. If this happens on multiple atoms, the better combination of signs must be explored. ShelXFile_EDiSFAC does not automate this step currently, as chemical reasoning is essential.
• Hydrogen atoms in the original iSFAC are defined as bare protons, where the contribution of electron accountted for via the bonding partners. Therefore as a simple aspect, X-H bond lengths are expected to follow neutron diffraction values (e.g. [8]). Refinement with NEUT command before iSFAC may help. ShelXFile_EDiSFAC can help this elongation. Then the model can constrained as mimicked-riding, where the geometry is strictly restrained by DFIXs. This is because AFIX does not work for 'H+'. The constraints can be optionally removed (non-riding).
• A control.list file defines initial paramaters and constraints:
  • Flags for refinement (for all), bare proton and riding model (for hydrogen atoms)
  • Initial signs and values of atomic charges.
  • Constraints to enforce equivalent charges on related hydrogens (e.g. for the same alkyl group).
• For now large stuctures with more than 99 atoms are not supported due to the limitaion of SHELXL's FVAR. This might be extended in the future.
• Application to atoms at special positions has not yet been tested.

Funding

Development undergoes as part of the SNF/FWF project, EPOC[7].

References

[1] https://github.com/dkratzert/ShelXFile

[2] S. Mahmoudi et al., Nature (2025). 645, 88–94. https://doi.org/10.1038/s41586-025-09405-0

[3] http://shelx.uni-goettingen.de/, G. Sheldrick, Acta Cryst. (2015). C71, 3-8. https://doi.org/10.1107/S2053229614024218

[4] https://www.rdkit.org/

[5] https://github.com/3dmol

[6] https://github.com/CF-CSA/edSFAC

[7] https://github.com/epoc-ed

[8] F. Allen and I. Bruno, Acta Cryst. (2010). B66, 380-386. https://doi.org/10.1107/S0108768110012048