cellpy package

cellpy package#

Subpackages#

Submodules#

cellpy.cli module#

dump_env_file(env_filename)[source]#

saves (writes) the env to file

echo_missing_modules()[source]#

prints out the missing modules

get_default_config_file_path(init_filename=None)[source]#

gets the path to the default config-file

get_dst_file(user_dir, init_filename)[source]#

gets the destination path for the config-file

get_package_prm_dir()[source]#

gets the folder where the cellpy package lives

save_prm_file(prm_filename)[source]#

saves (writes) the prms to file

cellpy.exceptions module#

Exceptions defined within cellpy

exception ConfigFileNotRead[source]#

Bases: Error

Raised when the configuration file cannot be read

exception ConfigFileNotWritten[source]#

Bases: Error

Raised when the configuration file cannot be written

exception DeprecatedFeature[source]#

Bases: Error

Raised when the feature is recently deprecated

exception Error[source]#

Bases: Exception

Base class for other exceptions

exception ExportFailed[source]#

Bases: Error

Raised when exporting data failed

exception FileNotFound[source]#

Bases: Error

Raised when the given file is not found

exception IOError[source]#

Bases: Error

Raised when exporting data failed

exception NoDataFound[source]#

Bases: Error

Raised when there are no cells, but a data is needed.

exception NullData[source]#

Bases: Error

Raised when required data is missing (e.g. voltage = None or summary_frames are missing)

exception SearchError[source]#

Bases: Error

Raised when the search function fails

exception UnderDefined[source]#

Bases: Error

Raised when trying something that requires you to set a missing prm on environment variable first

exception WrongFileVersion[source]#

Bases: Error

Raised when the file version is wrong

cellpy.log module#

Set up logger instance

setup_logging(default_level=None, default_json_path=None, env_key='LOG_CFG', custom_log_dir=None, reset_big_log=False, max_size=5000000, testing=False)[source]#

Setup logging configuration.

Parameters:

  • default_level – default log-level to screen (std.out).

  • default_json_path – path to config file for setting up logging.

  • env_key (str) – use this environment prm to try to get default_json_path.

  • custom_log_dir – path for saving logs.

  • reset_big_log (bool) – reset log if too big (max_size).

  • max_size (int) – if reset_log, this is the max limit.

  • testing (bool) – set as True if testing, and you don’t want to create any .log files

Module contents#

get(filename=None, instrument=None, instrument_file=None, cellpy_file=None, cycle_mode=None, mass: str | Number = None, nominal_capacity: str | Number = None, nom_cap_specifics=None, loading=None, area: str | Number = None, estimate_area=True, logging_mode=None, custom_log_dir=None, custom_log_config_path=None, auto_pick_cellpy_format=True, auto_summary=True, units=None, step_kwargs=None, summary_kwargs=None, selector=None, testing=False, refuse_copying=False, initialize=False, debug=False, **kwargs)[source]#

Create a CellpyCell object

Parameters:

  • filename (str, os.PathLike, OtherPath, or list of raw-file names) – path to file(s) or data-set(s) to load.

  • instrument (str) – instrument to use (defaults to the one in your cellpy config file).

  • instrument_file (str or path) – yaml file for custom file type.

  • cellpy_file (str, os.PathLike, or OtherPath) – if both filename (a raw-file) and cellpy_file (a cellpy file) is provided, cellpy will try to check if the raw-file is has been updated since the creation of the cellpy-file and select this instead of the raw file if cellpy thinks they are similar (use with care!).

  • logging_mode (str) – “INFO” or “DEBUG”.

  • cycle_mode (str) – the cycle mode (e.g. “anode” or “full_cell”).

  • mass (float) – mass of active material (mg) (defaults to mass given in cellpy-file or 1.0).

  • nominal_capacity (float) – nominal capacity for the cell (e.g. used for finding C-rates).

  • nom_cap_specifics (str) – either “gravimetric” (pr mass), or “areal” (per area). (“volumetric” is not fully implemented yet - let us know if you need it).

  • loading (float) – loading in units [mass] / [area].

  • area (float) – active electrode area (e.g. used for finding the areal capacity).

  • estimate_area (bool) – calculate area from loading if given (defaults to True).

  • auto_pick_cellpy_format (bool) – decide if it is a cellpy-file based on suffix.

  • auto_summary (bool) – (re-) create summary.

  • units (dict) – update cellpy units (used after the file is loaded, e.g. when creating summary).

  • step_kwargs (dict) – sent to make_steps.

  • summary_kwargs (dict) – sent to make_summary.

  • selector (dict) – passed to load (when loading cellpy-files).

  • testing (bool) – set to True if testing (will for example prevent making .log files)

  • refuse_copying (bool) – set to True if you do not want to copy the raw-file before loading.

  • initialize (bool) – set to True if you want to initialize the CellpyCell object (probably only useful if you want to return a cellpy-file with no data in it).

  • debug (bool) – set to True if you want to debug the loader.

  • **kwargs – sent to the loader.

Transferred Parameters:

  • model (str) – model to use (only for loaders that supports models).

  • bad_steps (list of tuples) – (c, s) tuples of steps s (in cycle c) to skip loading (“arbin_res”).

  • dataset_number (int) – the data set number (‘Test-ID’) to select if you are dealing with arbin files with more than one data-set. Defaults to selecting all data-sets and merging them (“arbin_res”).

  • data_points (tuple of ints) – load only data from data_point[0] to data_point[1] (use None for infinite) (“arbin_res”).

  • increment_cycle_index (bool) – increment the cycle index if merging several datasets (default True)

  • (“arbin_res”).

  • sep (str) – separator used in the file (“maccor_txt”, “neware_txt”, “local_instrument”, “custom”).

  • skip_rows (int) – number of rows to skip in the beginning of the file (“maccor_txt”, “neware_txt”, “local_instrument”, “custom”).

  • header (int) – row number of the header (“maccor_txt”, “neware_txt”, “local_instrument”, “custom”).

  • encoding (str) – encoding of the file (“maccor_txt”, “neware_txt”, “local_instrument”, “custom”).

  • decimal (str) – decimal separator (“maccor_txt”, “neware_txt”, “local_instrument”, “custom”).

  • thousand (str) – thousand separator (“maccor_txt”, “neware_txt”, “local_instrument”, “custom”).

  • pre_processor_hook (callable) – pre-processors to use (“maccor_txt”, “neware_txt”, “local_instrument”, “custom”).

  • bad_steps (list) – separator used in the file (not implemented yet) (“pec_csv”).

Returns:

CellpyCell object (if successful, None if not).

Examples

>>> # read an arbin .res file and create a cellpy object with
>>> # populated summary and step-table:
>>> c = cellpy.get("my_data.res", instrument="arbin_res", mass=1.14, area=2.12, loading=1.2, nom_cap=155.2)
>>>
>>> # load a cellpy-file:
>>> c = cellpy.get("my_cellpy_file.clp")
>>>
>>> # load a txt-file exported from Maccor:
>>> c = cellpy.get("my_data.txt", instrument="maccor_txt", model="one")
>>>
>>> # load a raw-file if it is newer than the corresponding cellpy-file,
>>> # if not, load the cellpy-file:
>>> c = cellpy.get("my_data.res", cellpy_file="my_data.clp")
>>>
>>> # load a file with a custom file-description:
>>> c = cellpy.get("my_file.csv", instrument_file="my_instrument.yaml")
>>>
>>> # load three subsequent raw-files (of one cell) and merge them:
>>> c = cellpy.get(["my_data_01.res", "my_data_02.res", "my_data_03.res"])
>>>
>>> # load a data set and get the summary charge and discharge capacities
>>> # in Ah/g:
>>> c = cellpy.get("my_data.res", units=dict(capacity="Ah"))
>>>
>>> # get an empty CellpyCell instance:
>>> c = cellpy.get()  # or c = cellpy.get(initialize=True) if you want to initialize it.
init()#

Initializes cellpy by reading the config file and the environment file