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_DATAenvironment variable, or by the olderPYEMAPS_CRYSTALSif 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:.xyzfiles fromwriteXYZ().stereo: stereodiagram plots.
- Returns:
the folder’s path. If the legacy
PYEMAPS_CRYSTALSvariable 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 isNone.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
crystalsfolder of the pyEMAPS data folder.- Returns:
(name, data): the crystal name, and its data as a dictionary with the keyscell,atoms,spganddw, as taken byfrom_dict().- Return type:
tuple
- Raises:
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()andfrom_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 keyscell,atoms,spganddw, as taken byfrom_dict().- Return type:
tuple
- Raises:
XTLError – if the file can’t be read, or its data is missing or invalid.