cellpy.parameters.internal_settings

Internal settings and definitions and functions for getting them.

Module Contents

Classes

BaseHeaders	Subclass of BaseSetting including option to add postfixes.
BaseSettings	Base class for internal cellpy settings.
CellpyLimits	These are the limits used inside cellpy for finding step types.
CellpyMeta	Base class for meta-data in cellpy.
CellpyMetaCommon	Common (not test-dependent) meta-data for cellpy.
CellpyMetaIndividualTest	Test-dependent meta-data for cellpy.
CellpyUnits	These are the units used inside Cellpy.
DictLikeClass	Add some dunder-methods so that it does not break old code that used
HeaderDict	A Sub-class of dict to allow for tab-completion.
HeadersJournal	Headers used for the journal (batch) (used as column headers for the journal pandas DataFrames)
HeadersNormal	Headers used for the normal (raw) data (used as column headers for the main data pandas DataFrames)
HeadersStepTable	Headers used for the steps table (used as column headers for the steps pandas DataFrames)
HeadersSummary	Headers used for the summary data (used as column headers for the main data pandas DataFrames)
InstrumentSettings	Base class for instrument settings.

Functions

get_cellpy_units(→ CellpyUnits)	Returns an augmented global dictionary with units
get_default_cellpy_file_raw_units(→ CellpyUnits)	Returns a dictionary with units to use as default for old versions of cellpy files
get_default_custom_headers_summary(→ HeadersSummary)	Returns an augmented dictionary that can be used to create custom header-strings for the summary
get_default_output_units(→ CellpyUnits)	Returns an augmented dictionary with units to use as default.
get_default_raw_limits(→ CellpyLimits)	Returns an augmented dictionary with units as default for raw data
get_default_raw_units(→ CellpyUnits)	Returns a dictionary with units as default for raw data
get_headers_journal(→ HeadersJournal)	Returns an augmented global dictionary containing the header-strings for the journal (batch)
get_headers_normal(→ HeadersNormal)	Returns an augmented global dictionary containing the header-strings for the normal data
get_headers_step_table(→ HeadersStepTable)	Returns an augmented global dictionary containing the header-strings for the steps table
get_headers_summary(→ HeadersSummary)	Returns an augmented global dictionary containing the header-strings for the summary

Attributes

ATTRS_TO_IMPORT_FROM_EXCEL_SQLITE
BATCH_ATTRS_TO_IMPORT_FROM_EXCEL_SQLITE
CELLPY_FILE_VERSION
COLUMNS_EXCEL_PK
COLUMNS_RENAMER
MINIMUM_CELLPY_FILE_VERSION
OTHERPATHS
PICKLE_PROTOCOL
RAW_TABLE_VERSION
STEP_TABLE_VERSION
SUMMARY_TABLE_VERSION
TABLE_NAME_SQLITE
base_columns_float
base_columns_int
cellpy_units
headers_journal
headers_normal
headers_step_table
headers_summary
keys_journal_session

class BaseHeaders

Bases: BaseSettings

Subclass of BaseSetting including option to add postfixes.

Example

>>> header["key_postfix"]  # returns "value_postfix"

postfixes = []

class BaseSettings

Bases: DictLikeClass

Base class for internal cellpy settings.

Usage:

@dataclass
class MyCoolCellpySetting(BaseSetting):
    var1: str = "first var"
    var2: int = 12

get(key)

Get the value (postfixes not supported).

to_frame()

Converts to pandas dataframe

class CellpyLimits

Bases: BaseSettings

These are the limits used inside cellpy for finding step types.

Since all instruments have an inherent inaccuracy, it is naive to assume that for example the voltage within a constant voltage step does not change at all. Therefore, we need to define some limits for what we consider to be a constant and what we assume to be zero.

current_hard: float = 1e-13

current_soft: float = 1e-05

ir_change: float = 1e-05

stable_charge_hard: float = 0.9

stable_charge_soft: float = 5.0

stable_current_hard: float = 2.0

stable_current_soft: float = 4.0

stable_voltage_hard: float = 2.0

stable_voltage_soft: float = 4.0

class CellpyMeta

Base class for meta-data in cellpy.

digest(as_list: bool = False, **kwargs)

Pops from dictionary of form {key: [values]}

Parameters:

• as_list (bool) – pick only first scalar if True.

• **kwargs (dict) – key word attributes to pick.

Returns:

Dictionary containing the non-digested part.

to_frame()

Converts to pandas dataframe

update(as_list: bool = False, **kwargs)

Updates from dictionary of form {key: [values]}

Parameters:

• as_list (bool) – pick only first scalar if True.

• **kwargs (dict) – key word attributes to update.

Returns:

None

class CellpyMetaCommon

Bases: CellpyMeta

Common (not test-dependent) meta-data for cellpy.

active_electrode_area: cellpy.prms.CellPyDataConfig | None

active_electrode_current_collector: cellpy.prms.CellPyDataConfig | None

active_electrode_thickness: cellpy.prms.CellPyDataConfig | None

active_electrode_type: cellpy.prms.CellPyDataConfig | None

cell_name: str | None

cell_type: cellpy.prms.CellPyDataConfig | None

cellpy_file_version: int

comment: cellpy.prms.CellPyDataConfig | None

counter_electrode_type: cellpy.prms.CellPyDataConfig | None

electrolyte_type: cellpy.prms.CellPyDataConfig | None

electrolyte_volume: cellpy.prms.CellPyDataConfig | None

experiment_type: cellpy.prms.CellPyDataConfig | None

file_errors: str | None

mass: cellpy.prms.CellPyDataConfig | None

material: cellpy.prms.CellPyDataConfig | None

nom_cap: cellpy.prms.CellPyDataConfig | None

nom_cap_specifics: cellpy.prms.CellPyDataConfig | None

raw_id: str | None

reference_electrode_current_collector: cellpy.prms.CellPyDataConfig | None

reference_electrode_type: cellpy.prms.CellPyDataConfig | None

separator_type: cellpy.prms.CellPyDataConfig | None

start_datetime: str | None

tester_ID: cellpy.prms.CellPyDataConfig | None

tester_calibration_date: cellpy.prms.CellPyDataConfig | None

tester_client_software_version: cellpy.prms.CellPyDataConfig | None

tester_server_software_version: cellpy.prms.CellPyDataConfig | None

time_zone: str | None

tot_mass: cellpy.prms.CellPyDataConfig | None

class CellpyMetaIndividualTest

Bases: CellpyMeta

Test-dependent meta-data for cellpy.

channel_index: cellpy.prms.CellPyDataConfig | None

creator: str | None

cycle_mode: cellpy.prms.CellPyDataConfig | None

schedule_file_name

test_ID: cellpy.prms.CellPyDataConfig | None

test_type: cellpy.prms.CellPyDataConfig | None

voltage_lim_high: cellpy.prms.CellPyDataConfig | None

voltage_lim_low: cellpy.prms.CellPyDataConfig | None

class CellpyUnits

Bases: BaseSettings

These are the units used inside Cellpy.

At least two sets of units needs to be defined; cellpy_units and raw_units. The data.raw dataframe is given in raw_units where the units are defined inside the instrument loader used. Since the data.steps dataframe is a summary of the step statistics from the data.raw dataframe, this also uses the raw_units. The data.summary dataframe contains columns with values directly from the data.raw dataframe given in raw_units as well as calculated columns given in cellpy_units.

Remark that all input to cellpy through user interaction (or utils) should be in cellpy_units. This is also true for meta-data collected from the raw files. The instrument loader needs to take care of the translation from its raw units to cellpy_units during loading the raw data file for the meta-data (remark that this is not necessary and not recommended for the actual “raw” data that is going to be stored in the data.raw dataframe).

As of 2022.09.29, cellpy does not automatically ensure unit conversion for input of meta-data, but has an internal method (CellPyData.to_cellpy_units) that can be used.

These are the different attributes currently supported for data in the dataframes:

current: str = "A"
charge: str = "mAh"
voltage: str = "V"
time: str = "sec"
resistance: str = "Ohms"
power: str = "W"
energy: str = "Wh"
frequency: str = "hz"

And here are the different attributes currently supported for meta-data:

# output-units for specific capacity etc.
specific_gravimetric: str = "g"
specific_areal: str = "cm**2"  # used for calculating specific capacity etc.
specific_volumetric: str = "cm**3"  # used for calculating specific capacity etc.

# other meta-data
nominal_capacity: str = "mAh/g"  # used for calculating rates etc.
mass: str = "mg"
length: str = "cm"
area: str = "cm**2"
volume: str = "cm**3"
temperature: str = "C"

area: str = 'cm**2'

charge: str = 'mAh'

current: str = 'A'

energy: str = 'Wh'

frequency: str = 'hz'

length: str = 'cm'

mass: str = 'mg'

nominal_capacity: str = 'mAh/g'

power: str = 'W'

pressure: str = 'bar'

resistance: str = 'ohm'

specific_areal: str = 'cm**2'

specific_gravimetric: str = 'g'

specific_volumetric: str = 'cm**3'

temperature: str = 'C'

time: str = 'sec'

voltage: str = 'V'

volume: str = 'cm**3'

update(new_units: dict)

Update the units.

class DictLikeClass

Add some dunder-methods so that it does not break old code that used dictionaries for storing settings

Remarks: it is not a complete dictionary experience - for example, setting new attributes (new keys) is not supported (raises KeyError if using the typical dict setting method) since it uses the dataclasses.fields method to find its members.

items()

keys()

values()

class HeaderDict(dict=None, /, **kwargs)

Bases: collections.UserDict

A Sub-class of dict to allow for tab-completion.

class HeadersJournal

Bases: BaseHeaders

Headers used for the journal (batch) (used as column headers for the journal pandas DataFrames)

area: str = 'area'

argument: str = 'argument'

cell_type: str = 'cell_type'

cellpy_file_name: str = 'cellpy_file_name'

comment: str = 'comment'

experiment: str = 'experiment'

filename: str = 'filename'

fixed: str = 'fixed'

group: str = 'group'

instrument: str = 'instrument'

label: str = 'label'

loading: str = 'loading'

mass: str = 'mass'

nom_cap: str = 'nom_cap'

raw_file_names: str = 'raw_file_names'

sub_group: str = 'sub_group'

total_mass: str = 'total_mass'

class HeadersNormal

Bases: BaseHeaders

Headers used for the normal (raw) data (used as column headers for the main data pandas DataFrames)

ac_impedance_txt: str = 'ac_impedance'

aci_phase_angle_txt: str = 'aci_phase_angle'

amplitude_txt: str = 'amplitude'

channel_id_txt: str = 'channel_id'

charge_capacity_txt: str = 'charge_capacity'

charge_energy_txt: str = 'charge_energy'

current_txt: str = 'current'

cycle_index_txt: str = 'cycle_index'

data_flag_txt: str = 'data_flag'

data_point_txt: str = 'data_point'

datetime_txt: str = 'date_time'

discharge_capacity_txt: str = 'discharge_capacity'

discharge_energy_txt: str = 'discharge_energy'

dv_dt_txt: str = 'dv_dt'

frequency_txt: str = 'frequency'

internal_resistance_txt: str = 'internal_resistance'

is_fc_data_txt: str = 'is_fc_data'

power_txt: str = 'power'

ref_ac_impedance_txt: str = 'ref_ac_impedance'

ref_aci_phase_angle_txt: str = 'ref_aci_phase_angle'

ref_voltage_txt: str = 'reference_voltage'

step_index_txt: str = 'step_index'

step_time_txt: str = 'step_time'

sub_step_index_txt: str = 'sub_step_index'

sub_step_time_txt: str = 'sub_step_time'

test_id_txt: str = 'test_id'

test_name_txt: str = 'test_name'

test_time_txt: str = 'test_time'

voltage_txt: str = 'voltage'

class HeadersStepTable

Bases: BaseHeaders

Headers used for the steps table (used as column headers for the steps pandas DataFrames)

charge: str = 'charge'

current: str = 'current'

cycle: str = 'cycle'

discharge: str = 'discharge'

info: str = 'info'

internal_resistance: str = 'ir'

internal_resistance_change: str = 'ir_pct_change'

point: str = 'point'

rate_avr: str = 'rate_avr'

step: str = 'step'

step_time: str = 'step_time'

sub_step: str = 'sub_step'

sub_type: str = 'sub_type'

test: str = 'test'

test_time: str = 'test_time'

type: str = 'type'

ustep: str = 'ustep'

voltage: str = 'voltage'

class HeadersSummary

Bases: BaseHeaders

Headers used for the summary data (used as column headers for the main data pandas DataFrames)

In addition to the headers defined here, the summary might also contain specific headers (ending in _gravimetric or _areal).

property areal_charge_capacity: str

property areal_discharge_capacity: str

property specific_columns: List[str]

Returns a list of the columns that can be “specific” (e.g. pr. mass or pr. area) for the summary table.

channel_id: str = 'channel_id'

charge_c_rate: str = 'charge_c_rate'

charge_capacity: str = 'charge_capacity'

charge_capacity_loss: str = 'charge_capacity_loss'

charge_capacity_raw: str = 'charge_capacity'

coulombic_difference: str = 'coulombic_difference'

coulombic_efficiency: str = 'coulombic_efficiency'

cumulated_charge_capacity: str = 'cumulated_charge_capacity'

cumulated_charge_capacity_loss: str = 'cumulated_charge_capacity_loss'

cumulated_coulombic_difference: str = 'cumulated_coulombic_difference'

cumulated_coulombic_efficiency: str = 'cumulated_coulombic_efficiency'

cumulated_discharge_capacity: str = 'cumulated_discharge_capacity'

cumulated_discharge_capacity_loss: str = 'cumulated_discharge_capacity_loss'

cumulated_ric: str = 'cumulated_ric'

cumulated_ric_disconnect: str = 'cumulated_ric_disconnect'

cumulated_ric_sei: str = 'cumulated_ric_sei'

cycle_index: str = 'cycle_index'

data_flag: str = 'data_flag'

data_point: str = 'data_point'

datetime: str = 'date_time'

discharge_c_rate: str = 'discharge_c_rate'

discharge_capacity: str = 'discharge_capacity'

discharge_capacity_loss: str = 'discharge_capacity_loss'

discharge_capacity_raw: str = 'discharge_capacity'

end_voltage_charge: str = 'end_voltage_charge'

end_voltage_discharge: str = 'end_voltage_discharge'

high_level: str = 'high_level'

ir_charge: str = 'ir_charge'

ir_discharge: str = 'ir_discharge'

low_level: str = 'low_level'

normalized_charge_capacity: str = 'normalized_charge_capacity'

normalized_cycle_index: str = 'normalized_cycle_index'

normalized_discharge_capacity: str = 'normalized_discharge_capacity'

ocv_first_max: str = 'ocv_first_max'

ocv_first_min: str = 'ocv_first_min'

ocv_second_max: str = 'ocv_second_max'

ocv_second_min: str = 'ocv_second_min'

postfixes = ['gravimetric', 'areal']

pre_aux: str = 'aux_'

shifted_charge_capacity: str = 'shifted_charge_capacity'

shifted_discharge_capacity: str = 'shifted_discharge_capacity'

temperature_last: str = 'temperature_last'

temperature_mean: str = 'temperature_mean'

test_name: str = 'test_name'

test_time: str = 'test_time'

class InstrumentSettings

Bases: DictLikeClass

Base class for instrument settings.

Usage:

@dataclass
class MyCoolInstrumentSetting(InstrumentSettings):
    var1: str = "first var"
    var2: int = 12

Remark! Try to use it as you would use a normal dataclass.

get_cellpy_units(*args, **kwargs) → CellpyUnits

Returns an augmented global dictionary with units

get_default_cellpy_file_raw_units(*args, **kwargs) → CellpyUnits

Returns a dictionary with units to use as default for old versions of cellpy files

get_default_custom_headers_summary() → HeadersSummary

Returns an augmented dictionary that can be used to create custom header-strings for the summary (used as column headers for the summary pandas DataFrames)

This function is mainly implemented to provide an example.

get_default_output_units(*args, **kwargs) → CellpyUnits

Returns an augmented dictionary with units to use as default.

get_default_raw_limits() → CellpyLimits

Returns an augmented dictionary with units as default for raw data

get_default_raw_units(*args, **kwargs) → CellpyUnits

Returns a dictionary with units as default for raw data

get_headers_journal() → HeadersJournal

Returns an augmented global dictionary containing the header-strings for the journal (batch) (used as column headers for the journal pandas DataFrames)

get_headers_normal() → HeadersNormal

Returns an augmented global dictionary containing the header-strings for the normal data (used as column headers for the main data pandas DataFrames)

get_headers_step_table() → HeadersStepTable

Returns an augmented global dictionary containing the header-strings for the steps table (used as column headers for the steps pandas DataFrames)

get_headers_summary() → HeadersSummary

Returns an augmented global dictionary containing the header-strings for the summary (used as column headers for the summary pandas DataFrames)

ATTRS_TO_IMPORT_FROM_EXCEL_SQLITE = ['name', 'label', 'project', 'cell_group', 'cellpy_file_name', 'instrument', 'cell_type',...

BATCH_ATTRS_TO_IMPORT_FROM_EXCEL_SQLITE = ['comment_history', 'sub_batch_01', 'sub_batch_02', 'sub_batch_03', 'sub_batch_04',...

CELLPY_FILE_VERSION = 8

COLUMNS_EXCEL_PK = 'id'

COLUMNS_RENAMER

MINIMUM_CELLPY_FILE_VERSION = 4

OTHERPATHS = ['rawdatadir', 'cellpydatadir']

PICKLE_PROTOCOL = 4

RAW_TABLE_VERSION = 5

STEP_TABLE_VERSION = 5

SUMMARY_TABLE_VERSION = 7

TABLE_NAME_SQLITE = 'cells'

base_columns_float

base_columns_int

cellpy_units

headers_journal

headers_normal

headers_step_table

headers_summary

keys_journal_session = ['starred', 'bad_cells', 'bad_cycles', 'notes']