File utilities#

Fileutils is a helper module in assisting pyemaps file i/o functions. Its methods include reading crystal data files and writing simulation output files.

It also detects pyemaps data home environment variables and directs file i/o accoridng to the rule set in Environment Variables.

pyemaps.fileutils.find_datahome()#

Return the pyEMAPS data folder.

That’s the folder named by the PYEMAPS_DATA environment variable, or by the older PYEMAPS_CRYSTALS if it’s set. The folder is created if it doesn’t exist. If neither variable is set, or the folder can’t be created, the current working directory is used. See Environment Variables.

Returns:

the folder’s path.

Return type:

str

pyemaps.fileutils.auto_fn(cn)#

Make a file name for simulation output from a crystal name and the current time.

Parameters:

cn (str) – the crystal name.

Returns:

the name, <cn>-<yyyymmddHHMMSS>, without an extension.

Return type:

str

pyemaps.fileutils.find_pyemaps_datahome(home_type='crystals')#

Return the folder for one kind of pyEMAPS data: a subfolder of the pyEMAPS data folder (find_datahome()), created if needed.

Parameters:

home_type (str, optional) –

the subfolder name, for example:

  • crystals: crystal data files.

  • bloch: dynamic diffraction output.

  • mxtal: .xyz files from writeXYZ().

  • stereo: stereodiagram plots.

Returns:

the folder’s path. If the legacy PYEMAPS_CRYSTALS variable is set, or the subfolder can’t be created, the data folder itself.

Return type:

str

pyemaps.fileutils.compose_ofn(fn, name, ty='diffraction')#

Return the path of an output file.

Parameters:
  • fn (str or None) – the file name. A name without a folder is put in the ty folder of the pyEMAPS data folder (find_pyemaps_datahome()); a path is used as it is.

  • name (str) – the crystal name, used to make a file name (auto_fn()) if fn is None.

  • ty (str, optional) – the kind of output, which names its folder.

Returns:

the file’s path.

Return type:

str

Raises:

FileNotFoundError – if fn includes a folder that doesn’t exist.

pyemaps.fileutils.loadCrystalCIFData(fn)#

Read crystal data from a CIF file.

Used by from_cif(), which most code should call instead.

Parameters:

fn (str) – the file’s path. If it isn’t found, it’s looked for in the crystals folder of the pyEMAPS data folder.

Returns:

(name, data): the crystal name, and its data as a dictionary with the keys cell, atoms, spg and dw, as taken by from_dict().

Return type:

tuple

Raises:
  • CIFError – if the file can’t be found or read, or the data is missing or invalid.

  • SPGError – if the space group can’t be identified uniquely.

The space group is matched against pyEMAPS’ space group database, from the symmetry operators, the Hermann-Mauguin symbol or the space group number in the file.

pyemaps.fileutils.loadCrystalData(fn, cn=None)#

Read crystal data from a pyEMAPS crystal data (.xtl) file.

Used by from_xtl() and from_builtin(), which most code should call instead.

Parameters:
  • fn (str) – the file’s path.

  • cn (str, optional) – the expected crystal name. If given, the name in the file must match it, ignoring case.

Returns:

(name, data): the crystal name, and its data as a dictionary with the keys cell, atoms, spg and dw, as taken by from_dict().

Return type:

tuple

Raises:

XTLError – if the file can’t be read, or its data is missing or invalid.