The echemsuite.cellcycling.read_input sub-module

The Instrument enumeration

class echemsuite.cellcycling.read_input.Instrument(value)

Simple enumeration class to easily reference instrument types.

GAMRY

GAMRY instrument producing .DTA files (value [str]: “GAMRY”)

BIOLOGIC

BIOLOGIC instrument producing .mpt files (value [str]: “BIOLOGIC”)

The FileManager class

class echemsuite.cellcycling.read_input.FileManager(verbose=False)

Universal loader class for cell-cycling files. The class provides a simple interface to load .dta and .mpt files from a user-specified path. The class stores the loaded files in memory using a dictionary of BytesIO objects. The class implements parse and sorting functions that allow the user to read the halfcycles files, organize them based on their timestamp and join them in a specified order to build a list of complete cycles. The class also supports the joining of partial halfcycles files.

Parameters:

verbose (bool) – if set to True, a progress report for the main functions will be reported on terminal

property bytestreams: Dict[str, BytesIO]

Dictionary containing the BytesIO of the loaded files orderd by a filename sting key.

Return type:

Dict[str, BytesIO]

fetch_files(filelist, autoparse=True)

Loads, as BytesIO streams, multiple files contained in a user defined filelist.

Parameters:

  • filelist (List[str]) – list containing the path to the files that needs to be loaded

  • autoparse (bool) – if set to True, will automatically call the parse() member function at the end of the fetching operation

Raises:

  • ValueError – if the extensions of the files in the provided file-list do not match

  • TypeError – if the extensions of the provided files does not match the supported types (.DTA or .mpt)

Return type:

None

fetch_from_folder(folder, extension, autoparse=True)

Loads, as BytesIO streams, multiple files from a folder filtering them by extension.

Parameters:

  • folder (str) – string containing the path to the folder from which the files needs to be loaded

  • extension (str) – string containing the extension of the files to be loaded

  • autoparse (bool) – if set to True will automatically call the parse member function at the end of the fetching operation

Raises:

  • ValueError – if the provided path does not correspond to a valid folder

  • TypeError – if the extensions of the provided files does not match the supported types (.DTA or .mpt)

Return type:

None

get_cellcycling(custom_order=[], clean=False)

Build a CellCycling object from a given halfcycles order.

Parameters:

  • custom_order (List[str]) – list of lists of filenames. Each list contains the half-cycles entries that must be merged in a single HalfCycle object. If left empty the ordering generated by the suggest_ordering method will be used.

  • clean (bool) – if set to True, only displays cycles with physical meaning (efficiencies < 100% and both charge + discharge available). If False (default), load everything.

Returns:

CellCycling instance containing all the charge/discharge Cycles objects.

Return type:

CellCycling

get_cycles(custom_order=[], clean=False)

Build the Cycles list from a given halfcycles order.

Parameters:

  • custom_order (List[str]) – list of lists of filenames. Each list contains the half-cycles entries that must be merged in a single HalfCycle object. If left empty the ordering generated by the suggest_ordering method will be used.

  • clean (bool) – if set to True, only displays cycles with physical meaning (efficiencies < 100% and both charge + discharge available). If False (default), load everything.

Returns:

list containing the set of charge/discharge Cycles objects created from the given dataset

Return type:

List[Cycle]

property halfcycles: Dict[str, HalfCycle]

Dictionary containing the HalfCycle objects parsed from the bytestreams register each object is associated with a key that coincides with the filename in the case of .dta files or with a fictitious key (reporting type and cycle number o the halfcycle) in case of the .mpt files.

Dict[str, HalfCycle]

property instrument: str

Type of instrument used to acquire the loaded dataset. The strings are encoded as key of the Instrument enumeration

Return type:

str

parse()

Parse the BytesIO streams contained in the “bytestreams” buffer and update the “halfcycles” dictionary.

Raises:

RuntimeError – if the bytestream buffer is empty or if one of the required fields is not present in one of the loaded files

Return type:

None

suggest_ordering()

Examine the bytestreams buffer and suggests a possible file ordering and merging scheme based on half-cycle type and timestamp.

Returns:

list of lists of filenames. Each list contains the halfcycles entries that must be merged in a single HalfCycle class.

Return type:

List[List[str]]

The quickload_folder function

echemsuite.cellcycling.read_input.quickload_folder(folder, extension, clean=False)

Simple helper function to be used in scripting to quicky load cell-cycling data from a user-specified folder. The function uses the fetch_from_folder method of the file manager class and applies all the default options. If a custom order needs to be specified, the function cannot be used.

Parameters:

  • folder (str) – The path to the folder where the data are stored.

  • extension (str) – The extension of the file to be loaded.

  • clean (bool) – If set to True, will activate the clean option in the get_cellcycling method used to generate the output CellCycling object

Return type:

CellCycling