API Reference

Batch class

class indentoolbox.core.Batch(tip, tests, device=None, operators=None, sample=None, date='')

Batch class.

Variables:

  • tip – The tip associated with the batch.

  • tests – A list of tests in the batch.

  • device – The device used for the tests. If not provided, a default Device object is created.

  • operators – A list of operators associated with the batch. If not provided, a default Operator object is created.

  • sample – The sample used for the tests. If not provided, a default Sample object is created.

  • date – The date of the batch.

Parameters:

  • tip – The tip associated with the batch.

  • tests – A list of tests to add to the batch.

  • device – The device used for the tests. Defaults to None.

  • operators – A list of operators associated with the batch. Defaults to None.

  • sample – The sample used for the tests. Defaults to None.

  • date – The date of the batch. Defaults to an empty string.

Raises:

None

Returns:

None

add_test(test)

Add a test to the batch.

Parameters:

test – The test to add.

Raises:

None

Returns:

None

collect_steps(index)

Collect steps from all tests at the given index and return a StepVector object.

Parameters:

index – The index of the steps to collect.

Raises:

None

Returns:

A StepVector object containing the collected steps.

property data

Return the concatenated data from all tests as a pandas DataFrame.

Raises:

None

Returns:

A pandas DataFrame containing the concatenated data from all tests.

get_data()

Return the concatenated data from all tests as a pandas DataFrame.

Raises:

None

Returns:

A pandas DataFrame containing the concatenated data from all tests.

classmethod load(root_path)

Load a Batch object from the specified root path.

The method reads CSV and TOML files to reconstruct the Batch object.

Parameters:

root_path – The root path of the files to load (without extension).

Raises:

None

Returns:

A Batch object loaded from the files.

to_dict(out=None)

Convert the batch object to a dictionary representation.

Parameters:

out – Optional output dictionary. Defaults to None.

Raises:

None

Returns:

The dictionary representation of the batch.

Test class

class indentoolbox.core.Test(steps, name='', path_to_data='', hoffset=0.0, parent=None, reject=False)

Contains data for an indentation experiment.

Variables:

_auto_dump_attr (list) – List of attributes to be automatically dumped.

Parameters:

  • steps (list) – Each element is an instance of the Step class, containing data for one segment (e.g., loading, holding, unloading, ..) of an indentation experiment.

  • name (str, optional) – Name of the test.

  • path_to_data (str, optional) – Path to the test data.

  • hoffset (float, optional) – TODO, not clear to ab. Probably will allow offsetting displacement or force data. TODO, rename as offset?

  • parent (indentoolbox.core.Batch, optional) – Parent Batch to which the test belongs.

  • reject (bool, optional) – Flag to tag bad indentation experiments to be excluded for successive data analysis.

add_step(step)

Add a step to the test.

Parameters:

step (Step) – Step instance to be added.

property data

Get the data from all steps of the test.

Returns:

Concatenated data from all steps.

Return type:

pandas.DataFrame

classmethod from_hysitron_nano(content, protocol, name='', **kwargs)

Create a Test object from Hysitron nano format text content.

Parameters:

  • content (str) – Text content in Hysitron nano format.

  • protocol (list) – List of step types in the indentation experiment.

  • name (str, optional) – Name of the test.

  • kwargs (Any) – Additional keyword arguments for the Test constructor.

Returns:

Test object created from the Hysitron nano text content.

Return type:

Test

Reads a test text output in the Hysitron nano format and creates a corresponding Test object.

Note

The text content should be in the Hysitron nano format.

Note

The protocol parameter is a list [‘Step’, ‘Step’, …] with as many elements as steps in the indentation experiment.

Note

The Step class must be defined and accessible in the itb.core module.

Warning

The function assumes that the text content follows the expected format. Make sure the content is properly formatted before using this method.

classmethod from_txt(content, protocol, name='', file_format='hysitron nano', **kwargs)

Create a Test object from a text content in a specific format.

Parameters:

  • content (str) – Text content of the test.

  • protocol (list) – List of step types in the indentation experiment.

  • name (str, optional) – Name of the test.

  • file_format (str, optional) – Format of the text file (default: “hysitron nano”).

  • kwargs (Any) – Additional keyword arguments for the Test constructor.

Returns:

Test object created from the text content.

Return type:

Test

Raises:

ValueError – If the file format is not supported.

Note

Currently, only the “hysitron nano” file format is supported.

Note

The protocol parameter is a list [‘Step’, ‘Step’, …] with as many elements as steps in the indentation experiment.

Note

The text content should be in the format of the specified file format.

Note

The Step class must be defined and accessible in the itb.core module.

Warning

The function assumes that the text content follows the expected format. Make sure the content is properly formatted before using this method.

get_data()

Get the data from all steps of the test.

Returns:

Concatenated data from all steps.

Return type:

pandas.DataFrame

get_id()

Get the index of the Test object within its parent Batch.

Returns:

Index of the Test object within its parent Batch.

Return type:

int or None

Returns the index of the Test object within its parent Batch. If the Test object does not have a parent, None is returned.

get_index()

Get the index of the test within its parent batch.

Returns:

Index of the test within its parent batch.

Return type:

int

to_dict(out=None)

Convert the Test object to a dictionary.

Parameters:

out (dict, optional) – Output dictionary to store the converted data.

Returns:

Dictionary representation of the Test object.

Return type:

dict

Step classes

class indentoolbox.core.Step(data, parent=None)

Step class.

Variables:

  • data – The data associated with the step.

  • parent – The parent object of the step.

Parameters:

  • data – The data associated with the step.

  • parent – The parent object of the step. Defaults to None.

Raises:

None

Returns:

None

property batch

Return the batch associated with the step.

Raises:

None

Returns:

The batch associated with the step.

classmethod from_dict(dic, class_map={})

Construct a Step object from a dictionary representation.

Parameters:

  • dic (dict) – The dictionary representation of the step.

  • class_map (dict) – Optional class map for deserialization. Defaults to an empty dictionary.

Raises:

None

Returns:

A Step object constructed from the dictionary representation.

Return type:

Step

get_batch()

Return the batch associated with the step.

Raises:

None

Returns:

The batch associated with the step.

get_corrected_disp()

Returns the corrected displacement based on the compliance provided.

Raises:

None

Returns:

The corrected displacement for the step.

get_id()

Get the ID of the step within its parent’s steps.

Returns:

The ID of the step within its parent’s steps, or None if the step has no parent.

Return type:

int or None

get_index()

Return the index of the step within its parent’s steps.

Raises:

None

Returns:

The index of the step.

get_name()

Get the name of the step.

Returns:

The name of the step in the format “test_{test_id}_step_{step_id}”, or None if the step has no parent.

Return type:

str or None

get_test()

Return the test associated with the step.

Raises:

None

Returns:

The test associated with the step.

get_tip()

Return the tip associated with the step.

Raises:

None

Returns:

The tip associated with the step.

kind()

Return the kind of the step.

Raises:

None

Returns:

The kind of the step.

property test

Return the test associated with the step.

Raises:

None

Returns:

The test associated with the step.

property tip

Return the tip associated with the step.

Raises:

None

Returns:

The tip associated with the step.

to_dict(out=None)

Convert the step object to a dictionary representation.

Parameters:

out – Optional output dictionary. Defaults to None.

Raises:

None

Returns:

The dictionary representation of the step.

class indentoolbox.core.LoadingStep(data, parent=None)

Class representing a loading step in an indentation experiment.

The LoadingStep class inherits from the Step class and represents a loading step in an indentation experiment.

class indentoolbox.core.ConicalLoadingStep(data, parent=None)

Represents a conical loading step in an indentation experiment. This class inherits from the LoadingStep class.

`parabolic_fit(*args, \*\*kwargs)`

Perform a parabolic fit on the conical loading step.

parabolic_fit(*args, **kwargs)

Perform a parabolic fit on the conical loading step.

This method calls the parabolic_fit function, passing the current ConicalLoadingStep instance as the step parameter, along with any additional arguments and keyword arguments.

Parameters:

  • args – Additional positional arguments to be passed to the parabolic_fit function.

  • kwargs – Additional keyword arguments to be passed to the parabolic_fit function.

Returns:

The return value of the parabolic_fit function.

class indentoolbox.core.UnloadingStep(data, parent=None)

Class representing an unloading step in an indentation experiment.

This class inherits from the base class Step and provides specific functionality for unloading steps.

`unloading_fit(*args, \*\*kwargs)`

Perform unloading fitting on the unloading step.

unloading_fit(*args, **kwargs)

Perform unloading fitting on the unloading step.

This method performs unloading fitting on the unloading step using the provided arguments.

Parameters:

  • args – Positional arguments to be passed to the unloading fitting function.

  • kwargs – Keyword arguments to be passed to the unloading fitting function.

Returns:

The result of the unloading fitting.

Return type:

object

Tip classes

class indentoolbox.core.Tip(young_modulus=1141000000000.0, poisson_coefficient=0.14)

Indentation Tip meta class.

Parameters:

  • young_modulus (float, optional) – Young’s modulus of the tip material. Default is 1141.0e9.

  • poisson_coefficient (float, optional) – Poisson’s coefficient of the tip material. Default is 0.14.

young_modulus

Young’s modulus of the tip material.

Type:

float

poisson_coefficient

Poisson’s coefficient of the tip material.

Type:

float

contact_area(h)

Calculate the contact area of the tip at a given indentation depth.

indentation_modulus()

Calculate the indentation modulus of the tip.

contact_area(h)

Calculate the contact area of the tip at a given indentation depth.

Parameters:

h (float) – Indentation depth.

Returns:

Contact area of the tip.

Return type:

float

indentation_modulus()

Calculate the indentation modulus of the tip E_ind = E / (1 - nu^2).

Returns:

Indentation modulus of the tip.

Return type:

float

class indentoolbox.core.SpheroConicalTip(angle=70.3, htrunc=None, radius=None, *args, **kwargs)

Generic spheroconical tip.

Parameters:

  • angle (float, optional) – Half-angle of the spheroconical tip in degrees. Default is 70.3.

  • htrunc (float, optional) – Truncation height of the spheroconical tip. If not provided, the radius should be specified instead.

  • radius (float, optional) – Radius of the spheroconical tip. If not provided, the truncation height should be specified instead.

  • *args – Additional arguments to be passed to the parent class.

  • **kwargs – Additional arguments to be passed to the parent class.

angle

Half-angle of the spheroconical tip in degrees.

Type:

float

htrunc

Truncation height of the spheroconical tip.

Type:

float

radius

Radius of the spheroconical tip.

Type:

float

get_htrunc()

Get the truncation height of the spheroconical tip.

set_htrunc(htrunc)

Set the truncation height of the spheroconical tip.

get_hcrit()

Get the critical height of the spheroconical tip.

contact_radius(h)

Calculate the contact radius of the spheroconical tip at a given indentation depth.

contact_radius(h)

Calculate the contact radius of the spheroconical tip at a given height.

Parameters:

h (float or array-like) – Height(s) at which to calculate the contact radius.

Returns:

Contact radius(es) of the spheroconical tip.

Return type:

float or array-like

get_hcrit()

Get the critical height of the spheroconical tip.

Returns:

Critical height of the spheroconical tip.

Return type:

float

get_htrunc()

Get the truncation height of the spheroconical tip.

Returns:

Truncation height of the spheroconical tip.

Return type:

float

property hcrit

Get the critical height of the spheroconical tip.

Returns:

Critical height of the spheroconical tip.

Return type:

float

property htrunc

Get the truncation height of the spheroconical tip.

Returns:

Truncation height of the spheroconical tip.

Return type:

float

set_htrunc(htrunc)

Set the truncation height of the spheroconical tip.

Parameters:

htrunc (float) – Truncation height of the spheroconical tip.

class indentoolbox.core.PyramidTip(coefficients, *args, **kwargs)

Pyramidal tip according to Oliver and Pharr function area

Area function is defined as A(hc) = C0 * hc**2 + C1 * hc + C2*hc**(1/2) + C3*hc**(1/4) + … + CN*hc**(1/(2**(N-1))) or A(hc) = sum_{i=0}^N Ci * hc**(1/(2**(i-1))) where hc is contact height and A is projected contact area.

Parameters:

  • coefficients (list, optional) – Coefficients for area function accoring to Oliver-Pharr. Default is [24.5]

  • *args – Additional arguments to be passed to the parent class.

  • **kwargs – Additional arguments to be passed to the parent class.

coefficients

Coefficients for area function accoring to Oliver-Pharr.

Type:

list

contact_radius(hc)

Calculate the contact radius of the spheroconical tip at a given height.

Parameters:

hc (float or array-like) – Height(s) at which to calculate the contact radius.

Returns:

Contact radius(es) of the spheroconical tip.

Return type:

float or array-like

Metaclasses

class indentoolbox.core.Container(**kwargs)

A container meta class for load and dump purposes.

data_to_csv(path=None)

Converts the data attribute of the class instance to a CSV string representation or saves it as a CSV file.

Parameters:

path (str or None) – Optional path to save the CSV string or file. Defaults to None.

Returns:

The CSV string representation of the data attribute.

Return type:

str

dump(root_path)

Dumps the class instance to TOML and CSV files.

Parameters:

root_path (str) – The root path for the output files.

Returns:

None

classmethod from_dict(dic, class_map={})

Loads a class instance from a dict/list structure.

Note

Needs better description.

Parameters:

  • dic (dict) – The dictionary representation of the class instance.

  • class_map (dict) – Optional class map for deserialization. Defaults to an empty dictionary.

Returns:

The loaded class instance.

Return type:

Container

classmethod from_list(lst, class_map={})

Loads a list of class instances from a list structure.

Parameters:

  • lst (list) – The list representation of class instances.

  • class_map (dict) – Optional class map for deserialization. Defaults to an empty dictionary.

Returns:

The loaded list of class instances.

Return type:

list[Container]

classmethod from_toml(path, **kwargs)

Loads a class instance from a TOML file.

Parameters:

  • path (str) – The path to the TOML file.

  • kwargs – Additional keyword arguments to pass to from_dict method.

Returns:

The loaded class instance.

Return type:

Container

to_dict(out=None)

Converts the class instance to a dictionary representation.

Parameters:

out (dict or None) – Optional dictionary to store the converted representation. Defaults to None.

Returns:

The dictionary representation of the class instance.

Return type:

dict

to_toml(path=None)

Converts the class instance to a TOML string representation.

Parameters:

path (str or None) – Optional path to save the TOML string as a file. Defaults to None.

Returns:

The TOML string representation of the class instance.

Return type:

str

class indentoolbox.core.StepVector(steps, index=None)

Represents a vector of steps in an indentation experiment.

Parameters:

  • steps (list) – A list of Step objects.

  • index (int or None, optional) – The index of the StepVector.

__repr__()

Returns a string representation of the StepVector.

__getattr__(attr)

Retrieves an attribute from each Step in the StepVector and returns an AttrArray.

index

The index of the StepVector.

Type:

int or None

steps

A list of Step objects.

Type:

list

class indentoolbox.core.AttrArray(attrs)

Represents an array of attributes.

Parameters:

attrs (list) – A list of attributes.

`__call__(*args, \*\*kwargs)`

Calls each attribute with the given arguments and returns a concatenated DataFrame.

attrs

A list of attributes.

Type:

list

Post-processing

indentoolbox.processing.OliverPharr(data, tip, disp_key='hm', force_key='Pm', epsilon=0.72, beta=1.04)

Perform Oliver-Pharr analysis on indentation data.

Parameters:

  • data (pandas.DataFrame) – DataFrame containing indentation data.

  • tip (Tip) – Tip object representing the indentation tip.

  • disp_key (str, optional) – Key for the displacement column in the data DataFrame. Default is “hm”.

  • force_key (str, optional) – Key for the force column in the data DataFrame. Default is “Pm”.

  • epsilon (float, optional) – Constant factor for calculating the contact depth. Default is 0.72.

  • beta (float, optional) – Constant factor for calculating the reduced modulus. Default is 1.04.

Returns:

DataFrame containing Oliver-Pharr analysis results with the following columns: - ‘h’: Displacement values from the data DataFrame. - ‘P’: Force values from the data DataFrame. - ‘S’: Stiffness values from the data DataFrame. - ‘hc’: Contact depth calculated using the Oliver-Pharr method. - ‘Ac’: Contact area calculated using the indentation tip. - ‘Eeq’: Equivalent elastic modulus. - ‘Eeqsamp’: Sample elastic modulus corrected for the indentation tip.

Return type:

pandas.DataFrame

indentoolbox.processing.GIAN99(hm, hf, S, C, nu=0.3, E_ind=inf, nu_ind=0.1, *args, **kwargs)

Perform elastoplastic analysis using the GIAN99 method.

This method refers to the following article:

Parameters:

  • hm (float) – Maximum penetration depth.

  • hf (float) – Final unloading penetration depth.

  • S (float) – Stiffness.

  • C (float) – Contact compliance.

  • nu (float, optional) – Poisson’s ratio. Default is 0.3.

  • E_ind (float, optional) – Indentation modulus. Default is np.inf.

  • nu_ind (float, optional) – Indentation Poisson’s ratio. Default is 0.1.

  • *args – Additional positional arguments.

  • **kwargs – Additional keyword arguments.

Returns:

Dictionary containing the following outputs:

  • ’dsigma’: …

  • ’Eeq’: Equivalent elastic modulus.

  • ’Ac’: Contact area.

  • ’k0’: …

  • ’sy’: Yield strength.

  • ’n’: Work-hardening exponent.

Return type:

dict

indentoolbox.processing.DAO01(S, C, Pm=0.0, Wfrac=0.0, hm=0.0, hf=0.0, *args, **kwargs)

Perform forward and reverse analysis using the DAO01 method.

This method refers to the following article:

Parameters:

  • S (float) – Unloading stiffness (needed data).

  • C (float) – Curvature of the loading curve (needed data).

  • Pm (float, optional) – Maximum load. Default is 0.0.

  • Wfrac (float, optional) – Ratio of the plastic work to the total work. Default is 0.0.

  • hm (float, optional) – Maximum penetration depth. Default is 0.0.

  • hf (float, optional) – Final unloading penetration depth. Default is 0.0.

  • *args – Additional positional arguments.

  • **kwargs – Additional keyword arguments.

Returns:

Dictionary containing the following outputs:

  • ’sy’list

    Yield strength.

  • ’n’list

    Work-hardening exponent.

  • ’Eeq’float

    Equivalent elastic modulus.

  • ’E’float

    Elastic modulus.

  • ’sigma0033’float

    True stress at 0.033% offset.

  • ’Pav’float

    Average pressure.

Return type:

dict

indentoolbox.processing.CASA05(hm, hf, Pm, S, C, nu=0.3, Ac=None)

Perform mechanical property extractions using the CASA05 method.

This method refers to the following article:

Parameters:

  • hm (float) – Maximum penetration depth.

  • hf (float) – Final unloading penetration depth.

  • Pm (float) – Maximum load.

  • S (float) – Unloading stiffness (needed data).

  • C (float) – Curvature of the loading curve (needed data).

  • nu (float, optional) – Poisson’s ratio. Default is 0.3.

  • Ac (float or None, optional) – Contact area. Default is None.

Returns:

Dictionary containing the following outputs:

  • ’sigma_005’float or nan

    True stress at 0.005% offset.

  • ’sigma_008’float or nan

    True stress at 0.008% offset.

  • ’sy’float or nan

    Yield strength.

  • ’n’float or nan

    Work-hardening exponent.

  • ’E_eq’float or nan

    Equivalent elastic modulus.

  • ’E’float or nan

    Elastic modulus.

Return type:

dict