epsman.elecStructure.ESclass module

Basic methods for dealing with Gamess & Molden file IO for ePolyScat.

10/06/21 Added some basic error checks during testing. SHOULD SET AS A DECORATOR.

03/02/21 v2 Revisiting and finishing off…

  • Fixed formatting options.

  • Added wrappers for cclib moldenwriter.MOLDEN as new class.

  • Use EShandler class for general IO.

  • Tested with N2O demo file + ePS test job OK for Molden2006 format.

Files from writeMoldenFile2006() are working with ePS (tested for N2O test file). Files from reformatMoldenFile() are NOT working due to line-endings issues. See notes/epsman_EShandler_class_demo_050221.ipynb for demo & testing.

26/08/20 v1 Quick hack from existing functions - needs some more sophistication for file handling. Should have utils for this…

Dev work currently in [Bemo] http://localhost:8888/notebooks/ePS/N2O/N2O_electronic_structure_proc_tests_250820.ipynb

class epsman.elecStructure.ESclass.EShandler(fileName=None, fileBase=None, outFile=None, verbose=1)[source]

Bases: object

Basic class for handling Gamess & Molden file IO.

Uses CCLIB to read Gamess log files & convert to Molden format.

For ePS compatibilty, this is slightly modified to match the “Molden2006” specifications defined therein (see source in MoldenCnv2006.f90).

Parameters:

  • fileName (str or Path obj, optional, default = None) – Gamess or Molden file.

  • fileBase (str or Path obj, optional, default = None) – Path to file location, defaults to current working dir.

  • outFile (str or Path obj, optional, default = None) – Name for output Molden file, defaults to fileName.molden if not set.

  • passed (If no args are) –

  • set (fileName = None will be) –

  • dir. (and filePath = working) –

Examples

>>> fileBase = Path(modPath, 'epsman', 'elecStructure','fileTest')  # Set for test file, where modPath = path to epsman root
>>> fileName = r'N2O_aug-cc-pVDZ_geomOpt.log'
>>> esData = EShandler(fileName, fileBase)  # Create class instance
>>> esData.readGamessLog()  # Read Gamess file
>>> esData.writeMoldenFile2006()  # Write Molden2006 file
>>> esData.writeMoldenFile()  # Write Molden file as per CCLIB defaults.

>>> esData = EShandler(fileName = 'test.molden') # Pass a Molden file to set & use the reformatter
>>> esData.reformatMoldenFile()

Notes

Thanks to the CCLIB authors for making this possible!

To do

  • Implement directory scan (or wrapper class/decorator for this).

  • Better file handling, should implement Pathlib tests for file(s).

  • Fix reformatMoldenFile() method, this currently outputs OS specific line endings.

10/06/21: adding ES file handling & info functions following recent OCS run testing, first version of:

  • setOrbInfoPD, orbInfoSummary (source _orbInfo.py) to pull orbital/molecule info from ES file.

  • setChannel, setePSinputs, genSymList, convertSymList, writeInputConf (source _ePSsetup.py) for setting up ePS parameters based on ES file + additional inputs. Needs further work, may also move to ESjob class in future…?

  • wrapped into ESjob class for main ePS job creation routines.

19/02/21: For full eps job class inheritance, use ESjob class instead.

genSymList(Ssym=None, Csym=None, symKey='ePS')

Generate symmetry paris - crude version.

Pass lists for Ssym and Csym, or set to None for full set generation (brute force).

orbInfoSummary(showSummary=True, showFull=True, showGrouped=False)

Print info from self.orbPD (via CCLIB). If not set, run self.setOrbInfoPD() first.

See also ep.jobSummary() and ep.getOrbInfo() for similar case from ePS output files.

readGamessLog()[source]

Read Gamess log file using CCLIB.io.ccread(self.fullPath).

File parser details:

self.setOrbInfoPD() is used to reformat the CCLIB data to Pandas.

For point-group, CCLIB metadata[symmetry_detected] and metadata[symmetry_used], see https://cclib.github.io/data_notes.html#metadata Not set for Gamess file import?

reformatMoldenFile(inplace=True, backup='', verbose=False)[source]

Reformat atom details & coords in an exisiting Molden file to match ePS IO “Molden2006” formatting.

Uses data in existing file, as set in self.moldenFile.

Notes

Default settings use inplace writing to replace existing file, pass backup=’.bk’ to set backup file extension for original file contents.

See https://docs.python.org/3/library/fileinput.html#fileinput.FileInput for details.

setChannel(channelInd, orbOcc=None)

Set ionizing channel (final state) in self.orbGrps, or reset orbOcc number.

Parameters:

  • channelInd (int) – Index matching OrbGrpOcc to remove electron from.

  • orbOcc (int, optional, default = None) – If specified, set this occupation number. If None, new occ number = original - 1

TODO:

  • Generalise for setting any orb occ sets.

  • Set/reset options? Currently ALWAYS resets final state.

setFiles(fileName=None, fileBase=None, outFile=None)[source]

Set fileName, fileBase and outFile

Parameters:

  • fileName (str or Path obj, optional, default = None) – Gamess or Molden file.

  • fileBase (str or Path obj, optional, default = None) – Path to file location, defaults to current working dir.

  • outFile (str or Path obj, optional, default = None) – Name for output Molden file, defaults to fileName.molden if not set.

  • passed (If no args are) –

  • set (fileName = None will be) –

  • dir. (and filePath = working) –

setInitialState(occDict)

Set initial state in self.orbGrps.

06/03/25: added for setting initial states. Basically duplicates setChannel() function, so some repetition here. But use dict syntax for setting multiple cases.

Parameters:

occDict (dict) – Specifies updated occs by channel, e.g. {8:1, 9:1} to set orbs 8 and 9 to single occupancy. Orbs are indexed by ‘iOrbGrp’.

setMoldenFile(fileName, fileBase=None)[source]

Set self.moldenFile with new fileName and existing path, or new path.

Parameters:

  • fileName (str or Path obj, optional, default = None) – Molden filename.

  • fileBase (str or Path obj, optional, default = None) – Path to file location, defaults to currently set path.

setOrbInfoPD(groups=['E', 'syms'], zeroInd=False)

Set info to self.orbPD, from electronic structure file (via CCLIB).

See also ep.jobSummary() and ep.getOrbInfo() for similar case from ePS output files.

Parameters:

  • groups (str or list of strs, optional, default = ['E','syms']) – Groups to use when determining degeneracies. If using ‘E’ only, some cases may produce incorrect results if there are multiple symmetry states with same E.

  • zeroInd (bool, optional, default = False) – If true use start index at 0 for orbitals/states. Otherwise start index at 1.

Notes

For point-group, CCLIB metadata[symmetry_detected] and metadata[symmetry_used], see https://cclib.github.io/data_notes.html#metadata Not set for Gamess file import?

08/02/22 Updated Gamess symmetry handling with new look-up functions.

02/02/22 Added additional symmetry handling routines for Gamess case.

Note this requies self.fullPath for the input file to be set.

25/01/22 Added groups and zeroInd parameters, and updates & debugged code.

TODO:

  • multindex for output table? As of 08/02/22 something like this look reasonable:

    ` testOrbPD.columns = [['Symmetries', 'Occupation', 'Occupation', 'Misc', 'Misc', 'Symmetries', 'Symmetries'], testOrbPD.columns] testOrbPD = testOrbPD[testOrbPD.columns.sort_values()] ` But may cause issue elsewhere in current implementation.

setPG(PG=None)

Set point group to self.PG & set ePS group info to self.PGinfo.

setePSglobals(overwriteFlag=True, **kwargs)

Set global options for ePS job, and store as self.ePSglobals.

Minimally this will set self.ePSglobals = {‘LMax’: 30}. All options set here will be written to the ePS input file header in “key value” style, as defined in setePSinputs().

For a full list of parameters, see the ePS manual, https://epolyscat.droppages.com/.

Parameters:

  • overwriteFlag (bool, optional, default = True) – Overwrite existing settings if True. If False skip if self.ePSglobals exists. Note there is no update/add params option at the moment.

  • kwargs (optional keyword args.) – These are used to set the values. e.g. self.setePSglobals(LMax = 30, VCorr = ‘PZ’)

Notes

If no parameters are passed, to following default settings will be used:

  • LMax = 30, this is a single integer which is the maximum l to be used for wave functions.

  • FegeEng = channel IP (if set), this is the energy correction used in the fege potential

Values are set to a dictionary, self.ePSglobals, which can also be configured manually.

setePSinputs(Ssym=None, Csym=None, InitSym=None, TargSym=None, CnvOrbSel=None, symKey='ePS', **kwargs)

Create ePS input records from existing data (from electronic structure file).

Set as dictionary of params that match input card keywords (cf. pygamess routines).

NOTE: if PG is set, additionally run self.convertSymList() to convert to ePolyScat symmetry labels. * CURRENTLY NOT FULLY IMPLEMENTED, for symTest case pass full list of ePS symmetries manually instead (otherwise Gamess defaults from self.orbPD[‘syms’] are used).

Update 08/02/22: symmetries should now be implemented, but mostly untested. Also added ‘symKey’ option to define table from orbPD to use for symmetry labels, defaults to ‘ePS’ labels.

Use **kwargs to define any further global settings, passed to setePSglobals().

Update 17/03/25: added InitSym and TargSym options, default = None (and will use defaults if so).

Should generate output to match current file format, roughly:

# Symmetry pairs for ScatSym (==ion x electron symm) and ScatContSym (==electron symm), input file will loop through these Ssym=({’ ‘.join([item[0] for item in symList])}) Csym=({’ ‘.join([item[1] for item in symList])})

# Global symmetries & spin SpinDeg=1 # Spin degeneracy of the total scattering state (=1 singlet) TargSym=’HG’ # Symmetry of the target state TargSpinDeg=2 # Target spin degeneracy InitSym=’AG’ # Initial state symmetry InitSpinDeg=1 # Initial state spin degeneracy’ ___________

Notes/TODO:

  • Pretty basic sym handling to improve.

    • If self.symList is missing, generate it (using defaults if Csym=None and Ssym=None)

    • If Csym or Ssym are set, self.symList will be regenerated and overwritten (if present).

  • Test for open shell systems, likely logic currently fails here.

  • Currently set for existing output via .conf file > shell script, which is a bit messy and needs replacing.

  • These are set to handle a single job, with the exception of Eke and Syms, which might be split into separate files. For multiple jobs use multiple instances…? BUT may need to modify job writing routines first…?

writeInputConf()

Basic dictionary > ePS job conf template

10/02/22 Added self.ePSglobals parsing. Ugly.

writeMoldenFile()[source]

Write data to Molden format file using CCLIB.io.ccwrite(self.data)

writeMoldenFile2006()[source]

Write data to Molden format file using reformatted CCLIB code, for ePS compatible ‘Molden2006’ formatting.

See moldenCCLIBReformatted for details.

class epsman.elecStructure.ESclass.moldenCCLIBReformatted(*args: Any, **kwargs: Any)[source]

Bases: MOLDEN

Patch for cclib’s modenwriter to conform to ePS ‘Molden2006’ format spec.

This class inherits from cclib.io.moldenwriter.MOLDEN (github source), and:

  • Redefines _coords_from_ccdata() and _gto_from_ccdata().

  • _coords_from_ccdata() uses super() to run the original function, than applies a slightly different coordinates format spec. to the output.

  • _gto_from_ccdata() is basically a modified version of the original cclib code, again with just a modified format spec.

Thanks to the CCLIB authors for making this possible!