API Reference#

VSM-like classes and functions using them.

class magmeas.base.VSM(datfile, read_method='auto')[source]#

Bases: EntityCollection

Class for importing, storing and using of VSM-data aswell as derived parameters.

reload_qd(datfile, read_method)[source]#

Load VSM-data from a quantum systems .DAT file.

Parameters:

datfile (STR | PATH) – Path to quantum systems .DAT file that data is supposed to be imported from
read_method (STR) – Determines whether magmeas will attempt to automatically read the sample parameters necessary for the following calculations or not. Can be “auto” or “manual”

Return type:

None

property path: Path#: Path to the file which was used in the object generation.

property H: Entity#: The internal magnetic field calculated from the measurement data. Calculated according to:

\[H_{int} = H_{ext} - D \cdot M\]

property H_ext: Entity#: The external magnetic field as read from the measurement file.

property M: Entity#

The magnetisation calculated from the measurement data. Calculated according to:

\[M = \frac{m}{V}\]

with m being the magnetic moment and V being the volume.

property m: Quantity#: The magnetic moment as read from the measurement file.

property T: Entity#: The thermodynamic temperature as read from the measurement file.

property t: Entity#: The time since the start of the measurement.

to_csv(filename)[source]#

Write measurement data to CSV-file. See mammos_entity.EntityCollection.to_csv for more details.

filename: STR | PATH: Name of the generated file.

property description: str#

Additional description of the entity collection.

The description is a string containing any information relevant to the entity collection. This can include, e.g., whether it is a set of experimental or simulation quantities or outline the overall workflow.

classmethod from_dataframe(dataframe: pd.DataFrame, metadata: dict[str, dict]) → mammos_entity.EntityCollection#

Create EntityCollection from dataframe and metadata.

The EntityCollection is created by combining metadata with data from the dataframe matching key/column names. The available metadata determines whether an element becomes an Entity`, a mammos_units.Quantity or a numpy array.

All column names in the dataframe must also exist as keys in metadata and vice versa.

In addition metadata can have a key description containing a description for the collection.

Parameters:

dataframe – A dataframe containing the values for the individual entities.
metadata – A dictionary with the structure similar to the one defined in metadata(). The keys unit and description for an :py:class`~mammos_entity.Entity` are however optional. If not present, default units from the ontology and an empty description are used.

metadata() → dict[str, str | dict[str, str]]#

Get entity metadata as dictionary.

This method creates a dictionary containing metadata for all entities in the collection. Keys are names of the (entities) attributes of the collection, values are dictionaries with: - keys ontology_label, unit and description if the attribute is an

entity

key unit if the attribute is a quantity
an empty dictionary otherwise

In addition there is one key-value pair description for the collection description.

Example: >>> import mammos_entity as me >>> import mammos_units as u >>> col = me.EntityCollection(“The description”, Tc=me.Tc(), x=1 * u.m, a=0) >>> col.metadata() {‘description’: ‘The description’, ‘Tc’: {‘ontology_label’: ‘CurieTemperature’, ‘unit’: ‘K’, ‘description’: ‘’}, ‘x’: {‘unit’: ‘m’}, ‘a’: {}}

to_dataframe(include_units: bool = False) → DataFrame#

Convert values to dataframe.

Parameters:: include_units – If true, include units in the dataframe column names.

Write a collection to an HDF5 group.

Entities of the collection become datasets in the group. The collection description is added to the group attributes.

Parameters:

base – If it is an open HDF5 file or a group in an HDF5 file, data will be added to it as new group. If it is a str or PathLike a new HDF5 file with the given name will be created. If a file with that name exists already, it will be overwritten without notice.
name – Name for the newly created group. If an element with that name exists already in base the function will fail. If name is None entities of the collection will be added directly to base and the collection description will be added to base attributes.

Returns:

If base is an open File or Group the newly created group. If base is a file name nothing is returned (because the file created internally will be closed before the function returns).

to_yaml(filename: str | PathLike) → None#

Write collection to YAML file.

MaMMoS YAML files have the following format:

one commented line at the top of the file containing the mammos format version in the form # mammos yaml v<version-number>.
a mapping with three top-level keys metadata, description and data
metadata is currently unused and should be empty
the description key contains a (multi-line) string with arbitrary content describing the top-level collection
data contains one key per element in the collection. Each entry is either an entity-like entry or a nested collection node.

Collection nodes are recursive and have two keys description and data:

description: a (multi-line) string with arbitrary content

data: mapping from entry names to entity-like entries or nested collection nodes

Entity-like entries have the following keys:

For Entity:

ontology_label: label in the ontology

description: description string

ontology_iri: IRI of the entity

unit: unit of the entity ("" for dimensionless)

value: value of the data

For Quantity:

unit: unit of the quantity

value: value of the data

For any other value:

value: value of the data

Parameters:: filename – Name of the generated file. An existing file with the same name is overwritten without notice.
Raises:: ValueError – If the top-level collection is empty.

Example

Here is an example with six entries:

an index with no units or ontology label
the entity spontaneous magnetization with an entry in the ontology and a description
a made-up quantity alpha with a unit but no ontology label
demagnetizing factor with an ontology entry but no unit
a column comment containing a string comment without units or ontology label
an element Tc with only a single value

The file has a description reading “Test data”.

>>> from pathlib import Path
>>> import mammos_entity as me
>>> import mammos_units as u
>>> collection = me.EntityCollection(
...     description="Test data",
...     index=[0, 1, 2],
...     Ms=me.Entity("SpontaneousMagnetization", [1e2, 1e2, 1e2], "kA/m", description="Magnetization at 0 Kelvin"),
...     alpha=[1.2, 3.4, 5.6] * u.s**2,
...     DemagnetizingFactor=me.Entity("DemagnetizingFactor", [1, 0.5, 0.5]),
...     comment=[
...         "Comment in the first row",
...         "Comment in the second row",
...         "Comment in the third row",
...     ],
...     Tc=me.Tc(300, "K"),
... )
>>> collection.to_yaml("example.yaml")

The new file has the following content:

>>> print(Path("example.yaml").read_text())
# mammos yaml v2
metadata: null
description: Test data
data:
  index:
    value: [0, 1, 2]
  Ms:
    ontology_label: SpontaneousMagnetization
    description: Magnetization at 0 Kelvin
    ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_032731f8-874d-5efb-9c9d-6dafaa17ef25
    unit: kA / m
    value: [100.0, 100.0, 100.0]
  alpha:
    unit: s2
    value: [1.2, 3.4, 5.6]
  DemagnetizingFactor:
    ontology_label: DemagnetizingFactor
    description: ''
    ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_0f2b5cc9-d00a-5030-8448-99ba6b7dfd1e
    unit: ''
    value: [1.0, 0.5, 0.5]
  comment:
    value: [Comment in the first row, Comment in the second row, Comment in the third
        row]
  Tc:
    ontology_label: CurieTemperature
    description: ''
    ontology_iri: https://w3id.org/emmo#EMMO_6b5af5a8_a2d8_4353_a1d6_54c9f778343d
    unit: K
    value: 300.0

>>> Path("example.yaml").unlink()

Here is a second example with one outer and one inner collection:

>>> properties = me.EntityCollection(
...     description="material properties",
...     Ms=me.Ms(1.3e3, "kA/m"),
...     Tc=me.Tc(1043, "K"),
... )
>>> measurement = me.EntityCollection(
...     description="measurement with device X",
...     sample=properties,
...     T=me.T(300, "K", description="Measurement conditions"),
...     H=me.H([0, 50, 100], "kA/m"),
...     M=me.M([100, 300, 500], "kA/m"),
... )
>>> measurement.to_yaml("nested_example.yaml")
>>> print(Path("nested_example.yaml").read_text())
# mammos yaml v2
metadata: null
description: measurement with device X
data:
  sample:
    description: material properties
    data:
      Ms:
        ontology_label: SpontaneousMagnetization
        description: ''
        ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_032731f8-874d-5efb-9c9d-6dafaa17ef25
        unit: kA / m
        value: 1300.0
      Tc:
        ontology_label: CurieTemperature
        description: ''
        ontology_iri: https://w3id.org/emmo#EMMO_6b5af5a8_a2d8_4353_a1d6_54c9f778343d
        unit: K
        value: 1043.0
  T:
    ontology_label: ThermodynamicTemperature
    description: Measurement conditions
    ontology_iri: https://w3id.org/emmo#EMMO_affe07e4_e9bc_4852_86c6_69e26182a17f
    unit: K
    value: 300.0
  H:
    ontology_label: ExternalMagneticField
    description: ''
    ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_da08f0d3-fe19-58bc-8fb6-ecc8992d5eb3
    unit: kA / m
    value: [0.0, 50.0, 100.0]
  M:
    ontology_label: Magnetization
    description: ''
    ontology_iri: https://w3id.org/emmo#EMMO_b23e7251_a488_4732_8268_027ad76d7e37
    unit: kA / m
    value: [100.0, 300.0, 500.0]

>>> Path("nested_example.yaml").unlink()

class magmeas.base.MH(datfile, read_method='auto')[source]#

Bases: VSM

Class for importing, storing and using of VSM-data from M(H) measurements.

plot(filepath=None, unit='T', bounds=(None, None), fig_ax=None, **kwargs)[source]#

Plot M(H) measurement and save figure if a filepath is given.

Parameters:

filepath (STR | PATH, optional) – Filepath for saving the figure. Default is None, in that case no file is saved and the generated figure as well as all axes objects are returned.
unit (STR | mu.unit | TUPLE(STR | mu.unit), optional) – Unit H and M are going to be plotted in. If string is given then both will have the same unit. Otherwise specify respective units as tuple (H_unit, M_unit). Default is ‘T’.
bounds (TUPLE(NONE | INT), optional) – Indices (start, end) at which the data to be plotted will be cut off. Use None to plot until the respective start or end. Default is (None, None).
fig_ax (TUPLE(matplotlib.figure.Figure, matplotlib.axes.Axes), optional) – Tuple of figure and axes the data should be plotted to. If None is given they will be generated dynamically. Default is None.
kwargs – Keyword arguments to change the appearance of plots. See documentation of matplotlib.pyplot.plot for more information.

Returns:

Return figure and axes object if filepath is not specified.

Return type:

None | (matplotlib.Figure, matplotlib.Axes)

property H: Entity#: The internal magnetic field calculated from the measurement data. Calculated according to:

\[H_{int} = H_{ext} - D \cdot M\]

property H_ext: Entity#: The external magnetic field as read from the measurement file.

property M: Entity#

The magnetisation calculated from the measurement data. Calculated according to:

\[M = \frac{m}{V}\]

with m being the magnetic moment and V being the volume.

property T: Entity#: The thermodynamic temperature as read from the measurement file.

property description: str#

Additional description of the entity collection.

classmethod from_dataframe(dataframe: pd.DataFrame, metadata: dict[str, dict]) → mammos_entity.EntityCollection#

Create EntityCollection from dataframe and metadata.

All column names in the dataframe must also exist as keys in metadata and vice versa.

In addition metadata can have a key description containing a description for the collection.

Parameters:

dataframe – A dataframe containing the values for the individual entities.
metadata – A dictionary with the structure similar to the one defined in metadata(). The keys unit and description for an :py:class`~mammos_entity.Entity` are however optional. If not present, default units from the ontology and an empty description are used.

property m: Quantity#: The magnetic moment as read from the measurement file.

metadata() → dict[str, str | dict[str, str]]#

Get entity metadata as dictionary.

entity

key unit if the attribute is a quantity
an empty dictionary otherwise

In addition there is one key-value pair description for the collection description.

property path: Path#: Path to the file which was used in the object generation.

reload_qd(datfile, read_method)#

Load VSM-data from a quantum systems .DAT file.

Parameters:

datfile (STR | PATH) – Path to quantum systems .DAT file that data is supposed to be imported from
read_method (STR) – Determines whether magmeas will attempt to automatically read the sample parameters necessary for the following calculations or not. Can be “auto” or “manual”

Return type:

None

property t: Entity#: The time since the start of the measurement.

to_csv(filename)#

Write measurement data to CSV-file. See mammos_entity.EntityCollection.to_csv for more details.

filename: STR | PATH: Name of the generated file.

to_dataframe(include_units: bool = False) → DataFrame#

Convert values to dataframe.

Parameters:: include_units – If true, include units in the dataframe column names.

Write a collection to an HDF5 group.

Entities of the collection become datasets in the group. The collection description is added to the group attributes.

Parameters:

base – If it is an open HDF5 file or a group in an HDF5 file, data will be added to it as new group. If it is a str or PathLike a new HDF5 file with the given name will be created. If a file with that name exists already, it will be overwritten without notice.
name – Name for the newly created group. If an element with that name exists already in base the function will fail. If name is None entities of the collection will be added directly to base and the collection description will be added to base attributes.

Returns:

If base is an open File or Group the newly created group. If base is a file name nothing is returned (because the file created internally will be closed before the function returns).

to_yaml(filename: str | PathLike) → None#

Write collection to YAML file.

MaMMoS YAML files have the following format:

one commented line at the top of the file containing the mammos format version in the form # mammos yaml v<version-number>.
a mapping with three top-level keys metadata, description and data
metadata is currently unused and should be empty
the description key contains a (multi-line) string with arbitrary content describing the top-level collection
data contains one key per element in the collection. Each entry is either an entity-like entry or a nested collection node.

Collection nodes are recursive and have two keys description and data:

description: a (multi-line) string with arbitrary content

data: mapping from entry names to entity-like entries or nested collection nodes

Entity-like entries have the following keys:

For Entity:

ontology_label: label in the ontology

description: description string

ontology_iri: IRI of the entity

unit: unit of the entity ("" for dimensionless)

value: value of the data

For Quantity:

unit: unit of the quantity

value: value of the data

For any other value:

value: value of the data

Parameters:: filename – Name of the generated file. An existing file with the same name is overwritten without notice.
Raises:: ValueError – If the top-level collection is empty.

Example

Here is an example with six entries:

an index with no units or ontology label
the entity spontaneous magnetization with an entry in the ontology and a description
a made-up quantity alpha with a unit but no ontology label
demagnetizing factor with an ontology entry but no unit
a column comment containing a string comment without units or ontology label
an element Tc with only a single value

The file has a description reading “Test data”.

>>> from pathlib import Path
>>> import mammos_entity as me
>>> import mammos_units as u
>>> collection = me.EntityCollection(
...     description="Test data",
...     index=[0, 1, 2],
...     Ms=me.Entity("SpontaneousMagnetization", [1e2, 1e2, 1e2], "kA/m", description="Magnetization at 0 Kelvin"),
...     alpha=[1.2, 3.4, 5.6] * u.s**2,
...     DemagnetizingFactor=me.Entity("DemagnetizingFactor", [1, 0.5, 0.5]),
...     comment=[
...         "Comment in the first row",
...         "Comment in the second row",
...         "Comment in the third row",
...     ],
...     Tc=me.Tc(300, "K"),
... )
>>> collection.to_yaml("example.yaml")

The new file has the following content:

>>> print(Path("example.yaml").read_text())
# mammos yaml v2
metadata: null
description: Test data
data:
  index:
    value: [0, 1, 2]
  Ms:
    ontology_label: SpontaneousMagnetization
    description: Magnetization at 0 Kelvin
    ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_032731f8-874d-5efb-9c9d-6dafaa17ef25
    unit: kA / m
    value: [100.0, 100.0, 100.0]
  alpha:
    unit: s2
    value: [1.2, 3.4, 5.6]
  DemagnetizingFactor:
    ontology_label: DemagnetizingFactor
    description: ''
    ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_0f2b5cc9-d00a-5030-8448-99ba6b7dfd1e
    unit: ''
    value: [1.0, 0.5, 0.5]
  comment:
    value: [Comment in the first row, Comment in the second row, Comment in the third
        row]
  Tc:
    ontology_label: CurieTemperature
    description: ''
    ontology_iri: https://w3id.org/emmo#EMMO_6b5af5a8_a2d8_4353_a1d6_54c9f778343d
    unit: K
    value: 300.0

>>> Path("example.yaml").unlink()

Here is a second example with one outer and one inner collection:

>>> properties = me.EntityCollection(
...     description="material properties",
...     Ms=me.Ms(1.3e3, "kA/m"),
...     Tc=me.Tc(1043, "K"),
... )
>>> measurement = me.EntityCollection(
...     description="measurement with device X",
...     sample=properties,
...     T=me.T(300, "K", description="Measurement conditions"),
...     H=me.H([0, 50, 100], "kA/m"),
...     M=me.M([100, 300, 500], "kA/m"),
... )
>>> measurement.to_yaml("nested_example.yaml")
>>> print(Path("nested_example.yaml").read_text())
# mammos yaml v2
metadata: null
description: measurement with device X
data:
  sample:
    description: material properties
    data:
      Ms:
        ontology_label: SpontaneousMagnetization
        description: ''
        ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_032731f8-874d-5efb-9c9d-6dafaa17ef25
        unit: kA / m
        value: 1300.0
      Tc:
        ontology_label: CurieTemperature
        description: ''
        ontology_iri: https://w3id.org/emmo#EMMO_6b5af5a8_a2d8_4353_a1d6_54c9f778343d
        unit: K
        value: 1043.0
  T:
    ontology_label: ThermodynamicTemperature
    description: Measurement conditions
    ontology_iri: https://w3id.org/emmo#EMMO_affe07e4_e9bc_4852_86c6_69e26182a17f
    unit: K
    value: 300.0
  H:
    ontology_label: ExternalMagneticField
    description: ''
    ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_da08f0d3-fe19-58bc-8fb6-ecc8992d5eb3
    unit: kA / m
    value: [0.0, 50.0, 100.0]
  M:
    ontology_label: Magnetization
    description: ''
    ontology_iri: https://w3id.org/emmo#EMMO_b23e7251_a488_4732_8268_027ad76d7e37
    unit: kA / m
    value: [100.0, 300.0, 500.0]

>>> Path("nested_example.yaml").unlink()

class magmeas.base.MH_major(datfile, read_method='auto')[source]#

Bases: _PropertyContainer, MH

Class for importing, storing and using of VSM-data from major loop M(H) measurements aswell as derived properties.

property remanence: Entity#: The remanence calculated from the measurement data. See mammos_analysis.hysteresis.extrinsic_properties for more details.

property coercivity: Entity#: The coercivity calculated from the measurement data. See mammos_analysis.hysteresis.extrinsic_properties for more details.

property BHmax: Entity#: The maximum energy product calculated from the measurement data. See mammos_analysis.hysteresis.extrinsic_properties for more details.

property kneefield: Entity#: The kneefield calculated from the measurement data. This is the internal magnetic field at which a magnetisation of 90 % of the remanence is reached.

property squareness: float#

The hysteresis loop squareness factor calculated from the measurement data. It is calculated according to:

\[S = \frac{H_k}{H_c}\]

with Hk being the kneefield and Hc being the coercivity.

property saturation: Entity#: The saturation magnetisation if it has been calculated. See the method estimate_saturation for more details.

estimate_saturation(threshold=None)[source]#

Calculate an estimation of the saturation magnetisation, return it and simultaneously assign it to the VSM object. A possible high field susceptibility can optionally be corrected for.

Parameters:: threshold (NONE | FLOAT, optional) – If a float instead of None is given, the saturation value will be corrected for a high field susceptibility by substracting any inclination at magnetisation values above the maximum field times the threshold factor. The saturation magnetisation is then the y-intersection from extrapolating M over 1/H to 0. Default value is None.
Returns:: Ms – Saturation magnetisation as SpontaneousMagnetization.
Return type:: ENTITY

segments(edge=0.05, prominence=1000000.0)[source]#

Find indices of segmentation points which can be used to seperate each measurement segment from each other. The segments are seperated by a changing sign of M (root) or a changing sign of dH/dt (peak). The segmentation points are chosen to be the index right after the root and right at the peak. Segmentation points with even indices (including 0) are peaks while segmentation points with uneven indices are roots.

Parameters:

edge (FLOAT, optional) – Percentage of measurement to be treated as edge. Default is 0.05, which means that segmentation points closer than 5 % of the total measurement width to the edges will be discarded.
prominence (FLOAT, optional) – The prominence which is used to find all peaks in H_ext(t). See the documentation of scipy.signal.find_peaks for more details. The default is 1e6.

Returns:

s – Array of segmentation points that can be used to segmentise the measurement.

Return type:

ARRAY[INT]

plot(filepath=None, demag=True, unit='T', segments=(None, None), fig_ax=None, **kwargs)[source]#

Plot major hysteresis loop, optionally with inset of demagnetization curve and save figure if a filepath is given.

Parameters:

filepath (STR | PATH, optional) – Filepath for saving the figure. Default is None, in that case no file is saved and the generated figure as well as all axes objects are returned.
demag (BOOL, optional) – Boolean that determines if demagnetization curve is plotted as an inset next to hysteresis loop. Default is True.
unit (STR | mu.unit | TUPLE(STR | mu.unit), optional) – Unit H and M are going to be plotted in. If string is given then both will have the same unit. Otherwise specify respective units as tuple (H_unit, M_unit). Default is ‘T’.
segments (TUPLE(NONE | INT), optional) – Segmentation points (start, end) at which the data to be plotted will be cut off. See the method ‘segments’ for more information. Note that valid input here are only the indices FOR the output from the segments method and NOT the indices of the actual measurement points. Use None to plot until the respective start or end. The demagnetisation curve will not be affected by this, it is always plotted in the same way between the same bounds. Default is (None, None).
fig_ax (TUPLE(matplotlib.figure.Figure, matplotlib.axes.Axes), optional) – Tuple of figure and axes the data should be plotted to. If None is given they will be generated dynamically. Default is None.
kwargs – Keyword arguments to change the appearance of plots. See documentation of matplotlib.pyplot.plot for more information.

Returns:

Return figure and axes object if filepath is not specified.

Return type:

None | (matplotlib.Figure, matplotlib.Axes)

property H: Entity#: The internal magnetic field calculated from the measurement data. Calculated according to:

\[H_{int} = H_{ext} - D \cdot M\]

property H_ext: Entity#: The external magnetic field as read from the measurement file.

property M: Entity#

The magnetisation calculated from the measurement data. Calculated according to:

\[M = \frac{m}{V}\]

with m being the magnetic moment and V being the volume.

property T: Entity#: The thermodynamic temperature as read from the measurement file.

property description: str#

Additional description of the entity collection.

classmethod from_dataframe(dataframe: pd.DataFrame, metadata: dict[str, dict]) → mammos_entity.EntityCollection#

Create EntityCollection from dataframe and metadata.

All column names in the dataframe must also exist as keys in metadata and vice versa.

In addition metadata can have a key description containing a description for the collection.

Parameters:

dataframe – A dataframe containing the values for the individual entities.
metadata – A dictionary with the structure similar to the one defined in metadata(). The keys unit and description for an :py:class`~mammos_entity.Entity` are however optional. If not present, default units from the ontology and an empty description are used.

property m: Quantity#: The magnetic moment as read from the measurement file.

metadata() → dict[str, str | dict[str, str]]#

Get entity metadata as dictionary.

entity

key unit if the attribute is a quantity
an empty dictionary otherwise

In addition there is one key-value pair description for the collection description.

property path: Path#: Path to the file which was used in the object generation.

reload_qd(datfile, read_method)#

Load VSM-data from a quantum systems .DAT file.

Parameters:

datfile (STR | PATH) – Path to quantum systems .DAT file that data is supposed to be imported from
read_method (STR) – Determines whether magmeas will attempt to automatically read the sample parameters necessary for the following calculations or not. Can be “auto” or “manual”

Return type:

None

property t: Entity#: The time since the start of the measurement.

to_csv(filename)#

Write measurement data and calculated properties to two separate CSV-files.

Parameters:: filename (STR | PATH) – Base of the generated files. Measurement data will have a ‘_data’ attached before the file extension and properties ‘_properties’.
Return type:: None

to_dataframe(include_units: bool = False) → DataFrame#

Convert values to dataframe.

Parameters:: include_units – If true, include units in the dataframe column names.

Write a collection to an HDF5 group.

Entities of the collection become datasets in the group. The collection description is added to the group attributes.

Parameters:

base – If it is an open HDF5 file or a group in an HDF5 file, data will be added to it as new group. If it is a str or PathLike a new HDF5 file with the given name will be created. If a file with that name exists already, it will be overwritten without notice.
name – Name for the newly created group. If an element with that name exists already in base the function will fail. If name is None entities of the collection will be added directly to base and the collection description will be added to base attributes.

Returns:

If base is an open File or Group the newly created group. If base is a file name nothing is returned (because the file created internally will be closed before the function returns).

to_yaml(filename: str | PathLike) → None#

Write collection to YAML file.

MaMMoS YAML files have the following format:

one commented line at the top of the file containing the mammos format version in the form # mammos yaml v<version-number>.
a mapping with three top-level keys metadata, description and data
metadata is currently unused and should be empty
the description key contains a (multi-line) string with arbitrary content describing the top-level collection
data contains one key per element in the collection. Each entry is either an entity-like entry or a nested collection node.

Collection nodes are recursive and have two keys description and data:

description: a (multi-line) string with arbitrary content

data: mapping from entry names to entity-like entries or nested collection nodes

Entity-like entries have the following keys:

For Entity:

ontology_label: label in the ontology

description: description string

ontology_iri: IRI of the entity

unit: unit of the entity ("" for dimensionless)

value: value of the data

For Quantity:

unit: unit of the quantity

value: value of the data

For any other value:

value: value of the data

Parameters:: filename – Name of the generated file. An existing file with the same name is overwritten without notice.
Raises:: ValueError – If the top-level collection is empty.

Example

Here is an example with six entries:

an index with no units or ontology label
the entity spontaneous magnetization with an entry in the ontology and a description
a made-up quantity alpha with a unit but no ontology label
demagnetizing factor with an ontology entry but no unit
a column comment containing a string comment without units or ontology label
an element Tc with only a single value

The file has a description reading “Test data”.

>>> from pathlib import Path
>>> import mammos_entity as me
>>> import mammos_units as u
>>> collection = me.EntityCollection(
...     description="Test data",
...     index=[0, 1, 2],
...     Ms=me.Entity("SpontaneousMagnetization", [1e2, 1e2, 1e2], "kA/m", description="Magnetization at 0 Kelvin"),
...     alpha=[1.2, 3.4, 5.6] * u.s**2,
...     DemagnetizingFactor=me.Entity("DemagnetizingFactor", [1, 0.5, 0.5]),
...     comment=[
...         "Comment in the first row",
...         "Comment in the second row",
...         "Comment in the third row",
...     ],
...     Tc=me.Tc(300, "K"),
... )
>>> collection.to_yaml("example.yaml")

The new file has the following content:

>>> print(Path("example.yaml").read_text())
# mammos yaml v2
metadata: null
description: Test data
data:
  index:
    value: [0, 1, 2]
  Ms:
    ontology_label: SpontaneousMagnetization
    description: Magnetization at 0 Kelvin
    ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_032731f8-874d-5efb-9c9d-6dafaa17ef25
    unit: kA / m
    value: [100.0, 100.0, 100.0]
  alpha:
    unit: s2
    value: [1.2, 3.4, 5.6]
  DemagnetizingFactor:
    ontology_label: DemagnetizingFactor
    description: ''
    ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_0f2b5cc9-d00a-5030-8448-99ba6b7dfd1e
    unit: ''
    value: [1.0, 0.5, 0.5]
  comment:
    value: [Comment in the first row, Comment in the second row, Comment in the third
        row]
  Tc:
    ontology_label: CurieTemperature
    description: ''
    ontology_iri: https://w3id.org/emmo#EMMO_6b5af5a8_a2d8_4353_a1d6_54c9f778343d
    unit: K
    value: 300.0

>>> Path("example.yaml").unlink()

Here is a second example with one outer and one inner collection:

>>> properties = me.EntityCollection(
...     description="material properties",
...     Ms=me.Ms(1.3e3, "kA/m"),
...     Tc=me.Tc(1043, "K"),
... )
>>> measurement = me.EntityCollection(
...     description="measurement with device X",
...     sample=properties,
...     T=me.T(300, "K", description="Measurement conditions"),
...     H=me.H([0, 50, 100], "kA/m"),
...     M=me.M([100, 300, 500], "kA/m"),
... )
>>> measurement.to_yaml("nested_example.yaml")
>>> print(Path("nested_example.yaml").read_text())
# mammos yaml v2
metadata: null
description: measurement with device X
data:
  sample:
    description: material properties
    data:
      Ms:
        ontology_label: SpontaneousMagnetization
        description: ''
        ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_032731f8-874d-5efb-9c9d-6dafaa17ef25
        unit: kA / m
        value: 1300.0
      Tc:
        ontology_label: CurieTemperature
        description: ''
        ontology_iri: https://w3id.org/emmo#EMMO_6b5af5a8_a2d8_4353_a1d6_54c9f778343d
        unit: K
        value: 1043.0
  T:
    ontology_label: ThermodynamicTemperature
    description: Measurement conditions
    ontology_iri: https://w3id.org/emmo#EMMO_affe07e4_e9bc_4852_86c6_69e26182a17f
    unit: K
    value: 300.0
  H:
    ontology_label: ExternalMagneticField
    description: ''
    ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_da08f0d3-fe19-58bc-8fb6-ecc8992d5eb3
    unit: kA / m
    value: [0.0, 50.0, 100.0]
  M:
    ontology_label: Magnetization
    description: ''
    ontology_iri: https://w3id.org/emmo#EMMO_b23e7251_a488_4732_8268_027ad76d7e37
    unit: kA / m
    value: [100.0, 300.0, 500.0]

>>> Path("nested_example.yaml").unlink()

class magmeas.base.MH_recoil(datfile, read_method='auto')[source]#

Bases: MH

Class for importing, storing and using of VSM-data from recoil loop M(H) measurements. Recoil loop measurements are assumed to be measurements where the sample is first saturated at some positive field. After this, a number of recoil loops are performed, where the magnetic field is reduced to some negative value (which often includes fields that do not fully demagnetise the sample) and is then increased to an external field of 0 or to a positive external field which increases the internal field to 0.

segments(prominence=5000.0)[source]#

Get indices of segmentation points. Segmentation point 0 occurs at H = H_max. All uneven segmentation points are the start of a recoil loop (only section with positive change in H) while all subsequent even segmentation points are the respective ends of each recoil loop.

Parameters:: prominence (FLOAT, optional) – The prominence which is used to find all peaks in H_ext(t). See the documentation of scipy.signal.find_peaks for more details. The default is 5e3.
Returns:: segments – Segmentation points used to extract each recoil loop.
Return type:: ARRAY

recoil_susceptibility(prominence=5000.0, take_mean=True)[source]#

Calculate recoil susceptibility from recoil loop measurement as slope of a linear regression of each recoil loop.

Parameters:

prominence (FLOAT, optional) – Prominence used to find segmentation points, see MH_recoil.segments The default is 5e3.
take_mean (BOOL, optional) – Wether to take the mean of all recoil susceptibilities instead of returning an individual one for each loop. Default is True.

Returns:

recoil_susceptibility – Recoil susceptibility calculated from recoil loop measurement.

Return type:

FLOAT | ARRAY

external_comp_field(prominence=5000.0)[source]#

Return external compensation fields, that will lead to an endpoint close to an internal magnetic field of zero for each recoil loop. This only makes sense to be calculated from recoil loop measurements, where the endpoint for each recoil loop was an external magnetic field of 0, which will lead to the respective internal magnetic field being non-zero. The external compensation fields can then be used in a new measurement which will then enable a recoil loop measurement corrected for demagnetisation.

External compensation field is calculated from the internal recoil fields (at the end of each recoil loop) and the recoil susceptibility according to:

\[H^e_{comp} = \frac{- H^i_{recoil}}{1 - D * \chi_{recoil}}\]

Parameters:: prominence (FLOAT, optional) – Prominence used to find segmentation points, see MH_recoil.segments The default is 5e3.
Returns:: external_compensation_field – External compensation fields, that would lead to an internal field close to zero at the end of each recoil loop.
Return type:: ARRAY

plot(filepath=None, demag=True, unit='T', segments=(0, None), fig_ax=None, **kwargs)[source]#

Plot recoil loop measurement and save figure if a filepath is given.

Parameters:

filepath (STR | PATH, optional) – Filepath for saving the figure. Default is None, in that case no file is saved and the generated figure as well as all axes objects are returned.
demag (BOOL, optional) – Plot the recoil loop measurement only in the second quadrant. Default is True.
unit (STR | mu.unit | TUPLE(STR | mu.unit), optional) – Unit H and M are going to be plotted in. If string is given then both will have the same unit. Otherwise specify respective units as tuple (H_unit, M_unit). Default is ‘T’.
segments (TUPLE(NONE | INT), optional) – Segmentation points (start, end) at which the data to be plotted will be cut off. See the method ‘segments’ for more information. Note that valid input here are only the indices FOR the output from the segments method and NOT the indices of the actual measurement points. Use None to plot until the respective start or end. Default is (0, None).
fig_ax (TUPLE(matplotlib.figure.Figure, matplotlib.axes.Axes), optional) – Tuple of figure and axes the data should be plotted to. If None is given they will be generated dynamically. Default is None.
kwargs – Keyword arguments to change the appearance of plots. See documentation of matplotlib.pyplot.plot for more information.

Returns:

Return figure and axes object if filepath is not specified.

Return type:

None | (matplotlib.Figure, matplotlib.Axes)

property H: Entity#: The internal magnetic field calculated from the measurement data. Calculated according to:

\[H_{int} = H_{ext} - D \cdot M\]

property H_ext: Entity#: The external magnetic field as read from the measurement file.

property M: Entity#

The magnetisation calculated from the measurement data. Calculated according to:

\[M = \frac{m}{V}\]

with m being the magnetic moment and V being the volume.

property T: Entity#: The thermodynamic temperature as read from the measurement file.

property description: str#

Additional description of the entity collection.

classmethod from_dataframe(dataframe: pd.DataFrame, metadata: dict[str, dict]) → mammos_entity.EntityCollection#

Create EntityCollection from dataframe and metadata.

All column names in the dataframe must also exist as keys in metadata and vice versa.

In addition metadata can have a key description containing a description for the collection.

Parameters:

dataframe – A dataframe containing the values for the individual entities.
metadata – A dictionary with the structure similar to the one defined in metadata(). The keys unit and description for an :py:class`~mammos_entity.Entity` are however optional. If not present, default units from the ontology and an empty description are used.

property m: Quantity#: The magnetic moment as read from the measurement file.

metadata() → dict[str, str | dict[str, str]]#

Get entity metadata as dictionary.

entity

key unit if the attribute is a quantity
an empty dictionary otherwise

In addition there is one key-value pair description for the collection description.

property path: Path#: Path to the file which was used in the object generation.

reload_qd(datfile, read_method)#

Load VSM-data from a quantum systems .DAT file.

Parameters:

datfile (STR | PATH) – Path to quantum systems .DAT file that data is supposed to be imported from
read_method (STR) – Determines whether magmeas will attempt to automatically read the sample parameters necessary for the following calculations or not. Can be “auto” or “manual”

Return type:

None

property t: Entity#: The time since the start of the measurement.

to_csv(filename)#

Write measurement data to CSV-file. See mammos_entity.EntityCollection.to_csv for more details.

filename: STR | PATH: Name of the generated file.

to_dataframe(include_units: bool = False) → DataFrame#

Convert values to dataframe.

Parameters:: include_units – If true, include units in the dataframe column names.

Write a collection to an HDF5 group.

Entities of the collection become datasets in the group. The collection description is added to the group attributes.

Parameters:

base – If it is an open HDF5 file or a group in an HDF5 file, data will be added to it as new group. If it is a str or PathLike a new HDF5 file with the given name will be created. If a file with that name exists already, it will be overwritten without notice.
name – Name for the newly created group. If an element with that name exists already in base the function will fail. If name is None entities of the collection will be added directly to base and the collection description will be added to base attributes.

Returns:

If base is an open File or Group the newly created group. If base is a file name nothing is returned (because the file created internally will be closed before the function returns).

to_yaml(filename: str | PathLike) → None#

Write collection to YAML file.

MaMMoS YAML files have the following format:

one commented line at the top of the file containing the mammos format version in the form # mammos yaml v<version-number>.
a mapping with three top-level keys metadata, description and data
metadata is currently unused and should be empty
the description key contains a (multi-line) string with arbitrary content describing the top-level collection
data contains one key per element in the collection. Each entry is either an entity-like entry or a nested collection node.

Collection nodes are recursive and have two keys description and data:

description: a (multi-line) string with arbitrary content

data: mapping from entry names to entity-like entries or nested collection nodes

Entity-like entries have the following keys:

For Entity:

ontology_label: label in the ontology

description: description string

ontology_iri: IRI of the entity

unit: unit of the entity ("" for dimensionless)

value: value of the data

For Quantity:

unit: unit of the quantity

value: value of the data

For any other value:

value: value of the data

Parameters:: filename – Name of the generated file. An existing file with the same name is overwritten without notice.
Raises:: ValueError – If the top-level collection is empty.

Example

Here is an example with six entries:

an index with no units or ontology label
the entity spontaneous magnetization with an entry in the ontology and a description
a made-up quantity alpha with a unit but no ontology label
demagnetizing factor with an ontology entry but no unit
a column comment containing a string comment without units or ontology label
an element Tc with only a single value

The file has a description reading “Test data”.

>>> from pathlib import Path
>>> import mammos_entity as me
>>> import mammos_units as u
>>> collection = me.EntityCollection(
...     description="Test data",
...     index=[0, 1, 2],
...     Ms=me.Entity("SpontaneousMagnetization", [1e2, 1e2, 1e2], "kA/m", description="Magnetization at 0 Kelvin"),
...     alpha=[1.2, 3.4, 5.6] * u.s**2,
...     DemagnetizingFactor=me.Entity("DemagnetizingFactor", [1, 0.5, 0.5]),
...     comment=[
...         "Comment in the first row",
...         "Comment in the second row",
...         "Comment in the third row",
...     ],
...     Tc=me.Tc(300, "K"),
... )
>>> collection.to_yaml("example.yaml")

The new file has the following content:

>>> print(Path("example.yaml").read_text())
# mammos yaml v2
metadata: null
description: Test data
data:
  index:
    value: [0, 1, 2]
  Ms:
    ontology_label: SpontaneousMagnetization
    description: Magnetization at 0 Kelvin
    ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_032731f8-874d-5efb-9c9d-6dafaa17ef25
    unit: kA / m
    value: [100.0, 100.0, 100.0]
  alpha:
    unit: s2
    value: [1.2, 3.4, 5.6]
  DemagnetizingFactor:
    ontology_label: DemagnetizingFactor
    description: ''
    ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_0f2b5cc9-d00a-5030-8448-99ba6b7dfd1e
    unit: ''
    value: [1.0, 0.5, 0.5]
  comment:
    value: [Comment in the first row, Comment in the second row, Comment in the third
        row]
  Tc:
    ontology_label: CurieTemperature
    description: ''
    ontology_iri: https://w3id.org/emmo#EMMO_6b5af5a8_a2d8_4353_a1d6_54c9f778343d
    unit: K
    value: 300.0

>>> Path("example.yaml").unlink()

Here is a second example with one outer and one inner collection:

>>> properties = me.EntityCollection(
...     description="material properties",
...     Ms=me.Ms(1.3e3, "kA/m"),
...     Tc=me.Tc(1043, "K"),
... )
>>> measurement = me.EntityCollection(
...     description="measurement with device X",
...     sample=properties,
...     T=me.T(300, "K", description="Measurement conditions"),
...     H=me.H([0, 50, 100], "kA/m"),
...     M=me.M([100, 300, 500], "kA/m"),
... )
>>> measurement.to_yaml("nested_example.yaml")
>>> print(Path("nested_example.yaml").read_text())
# mammos yaml v2
metadata: null
description: measurement with device X
data:
  sample:
    description: material properties
    data:
      Ms:
        ontology_label: SpontaneousMagnetization
        description: ''
        ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_032731f8-874d-5efb-9c9d-6dafaa17ef25
        unit: kA / m
        value: 1300.0
      Tc:
        ontology_label: CurieTemperature
        description: ''
        ontology_iri: https://w3id.org/emmo#EMMO_6b5af5a8_a2d8_4353_a1d6_54c9f778343d
        unit: K
        value: 1043.0
  T:
    ontology_label: ThermodynamicTemperature
    description: Measurement conditions
    ontology_iri: https://w3id.org/emmo#EMMO_affe07e4_e9bc_4852_86c6_69e26182a17f
    unit: K
    value: 300.0
  H:
    ontology_label: ExternalMagneticField
    description: ''
    ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_da08f0d3-fe19-58bc-8fb6-ecc8992d5eb3
    unit: kA / m
    value: [0.0, 50.0, 100.0]
  M:
    ontology_label: Magnetization
    description: ''
    ontology_iri: https://w3id.org/emmo#EMMO_b23e7251_a488_4732_8268_027ad76d7e37
    unit: kA / m
    value: [100.0, 300.0, 500.0]

>>> Path("nested_example.yaml").unlink()

class magmeas.base.FORC(datfile, read_method='auto')[source]#

Bases: MH

Class for importing, storing and using VSM data of FORC measurements.

segments(prominence=5000.0)[source]#

Get indices of segmentation points. Segmentation point 0 occurs at H = H_max. All uneven segmentation points are the start of a FORC (only section with positive change in H) while all subsequent even segmentation points are the respective ends of each FORC.

Parameters:: prominence (FLOAT, optional) – The prominence which is used to find all peaks in H_ext(t). See the documentation of scipy.signal.find_peaks for more details. The default is 5e3.
Returns:: segments – Segmentation points used to extract each recoil loop.
Return type:: ARRAY

forc_grid(demag_correction=False, prominence=5000.0)[source]#

Extract grid of magnetic fields, reversal fields and magnetisations from the FORC-measurement.

Parameters:

demag_correction (BOOL, optional) – Whether to correct the magnetic field for Demagnetisation. The default is True.
prominence (FLOAT, optional) – Prominence used to find segmentation points, see FORC.segments The default is 5e3.

Returns:

h_grid (QUANTITY) – Magnetic field at each grid point of the FORC-measurement. If demag_correction was True, this is the internal magnetic field. Otherwise it’s the external magnetic field.
h_r_grid (QUANTITY) – Magnetic reversal field of each FORC. Has the same shape as h_grid. If demag_correction was True, this is the internal magnetic field. Otherwise it’s the external magnetic field.
m_grid (QUANTITY) – Magnetisation at each grid point of the FORC-measurement.

forc_dist(SF, demag_correction=True, prominence=5000.0)[source]#

Calculate the transformed coordinates H_c and H_i as well as the FORC distribution. Takes a grid of (2*SF+1)**2 measurement points from the grid of M(H_r, H) points and fits a quadratic function. The FORC distribution is then the mixed partial derivative of this fitted polynomial.

Parameters:

SF (INT) – Smoothing factor to be used in the calculation of the FORC distribution. The number of points contributing to a point in the FORC distribution is a square grid with a side length of (2*SF+1) measurement points.
demag_correction (BOOL, optional) – Whether to correct the magnetic field for Demagnetisation. The default is True.
prominence (FLOAT, optional) – Prominence used to find segmentation points, see FORC.segments The default is 5e3.

Returns:

H_c (QUANTITY) – Local coercive field H_c = (H_r - H) / 2 defined for H > 0
H_i (QUANTITY) – Local interaction field H_i = (H_r + H) / 2
rho (ARRAY) – FORC distribution at each point of the FORC measurement grid.

property H: Entity#: The internal magnetic field calculated from the measurement data. Calculated according to:

\[H_{int} = H_{ext} - D \cdot M\]

property H_ext: Entity#: The external magnetic field as read from the measurement file.

property M: Entity#

The magnetisation calculated from the measurement data. Calculated according to:

\[M = \frac{m}{V}\]

with m being the magnetic moment and V being the volume.

property T: Entity#: The thermodynamic temperature as read from the measurement file.

property description: str#

Additional description of the entity collection.

classmethod from_dataframe(dataframe: pd.DataFrame, metadata: dict[str, dict]) → mammos_entity.EntityCollection#

Create EntityCollection from dataframe and metadata.

All column names in the dataframe must also exist as keys in metadata and vice versa.

In addition metadata can have a key description containing a description for the collection.

Parameters:

dataframe – A dataframe containing the values for the individual entities.
metadata – A dictionary with the structure similar to the one defined in metadata(). The keys unit and description for an :py:class`~mammos_entity.Entity` are however optional. If not present, default units from the ontology and an empty description are used.

property m: Quantity#: The magnetic moment as read from the measurement file.

metadata() → dict[str, str | dict[str, str]]#

Get entity metadata as dictionary.

entity

key unit if the attribute is a quantity
an empty dictionary otherwise

In addition there is one key-value pair description for the collection description.

property path: Path#: Path to the file which was used in the object generation.

plot(filepath=None, unit='T', bounds=(None, None), fig_ax=None, **kwargs)#

Plot M(H) measurement and save figure if a filepath is given.

Parameters:

filepath (STR | PATH, optional) – Filepath for saving the figure. Default is None, in that case no file is saved and the generated figure as well as all axes objects are returned.
unit (STR | mu.unit | TUPLE(STR | mu.unit), optional) – Unit H and M are going to be plotted in. If string is given then both will have the same unit. Otherwise specify respective units as tuple (H_unit, M_unit). Default is ‘T’.
bounds (TUPLE(NONE | INT), optional) – Indices (start, end) at which the data to be plotted will be cut off. Use None to plot until the respective start or end. Default is (None, None).
fig_ax (TUPLE(matplotlib.figure.Figure, matplotlib.axes.Axes), optional) – Tuple of figure and axes the data should be plotted to. If None is given they will be generated dynamically. Default is None.
kwargs – Keyword arguments to change the appearance of plots. See documentation of matplotlib.pyplot.plot for more information.

Returns:

Return figure and axes object if filepath is not specified.

Return type:

None | (matplotlib.Figure, matplotlib.Axes)

reload_qd(datfile, read_method)#

Load VSM-data from a quantum systems .DAT file.

Parameters:

datfile (STR | PATH) – Path to quantum systems .DAT file that data is supposed to be imported from
read_method (STR) – Determines whether magmeas will attempt to automatically read the sample parameters necessary for the following calculations or not. Can be “auto” or “manual”

Return type:

None

property t: Entity#: The time since the start of the measurement.

to_csv(filename)#

Write measurement data to CSV-file. See mammos_entity.EntityCollection.to_csv for more details.

filename: STR | PATH: Name of the generated file.

to_dataframe(include_units: bool = False) → DataFrame#

Convert values to dataframe.

Parameters:: include_units – If true, include units in the dataframe column names.

Write a collection to an HDF5 group.

Entities of the collection become datasets in the group. The collection description is added to the group attributes.

Parameters:

base – If it is an open HDF5 file or a group in an HDF5 file, data will be added to it as new group. If it is a str or PathLike a new HDF5 file with the given name will be created. If a file with that name exists already, it will be overwritten without notice.
name – Name for the newly created group. If an element with that name exists already in base the function will fail. If name is None entities of the collection will be added directly to base and the collection description will be added to base attributes.

Returns:

If base is an open File or Group the newly created group. If base is a file name nothing is returned (because the file created internally will be closed before the function returns).

to_yaml(filename: str | PathLike) → None#

Write collection to YAML file.

MaMMoS YAML files have the following format:

one commented line at the top of the file containing the mammos format version in the form # mammos yaml v<version-number>.
a mapping with three top-level keys metadata, description and data
metadata is currently unused and should be empty
the description key contains a (multi-line) string with arbitrary content describing the top-level collection
data contains one key per element in the collection. Each entry is either an entity-like entry or a nested collection node.

Collection nodes are recursive and have two keys description and data:

description: a (multi-line) string with arbitrary content

data: mapping from entry names to entity-like entries or nested collection nodes

Entity-like entries have the following keys:

For Entity:

ontology_label: label in the ontology

description: description string

ontology_iri: IRI of the entity

unit: unit of the entity ("" for dimensionless)

value: value of the data

For Quantity:

unit: unit of the quantity

value: value of the data

For any other value:

value: value of the data

Parameters:: filename – Name of the generated file. An existing file with the same name is overwritten without notice.
Raises:: ValueError – If the top-level collection is empty.

Example

Here is an example with six entries:

an index with no units or ontology label
the entity spontaneous magnetization with an entry in the ontology and a description
a made-up quantity alpha with a unit but no ontology label
demagnetizing factor with an ontology entry but no unit
a column comment containing a string comment without units or ontology label
an element Tc with only a single value

The file has a description reading “Test data”.

>>> from pathlib import Path
>>> import mammos_entity as me
>>> import mammos_units as u
>>> collection = me.EntityCollection(
...     description="Test data",
...     index=[0, 1, 2],
...     Ms=me.Entity("SpontaneousMagnetization", [1e2, 1e2, 1e2], "kA/m", description="Magnetization at 0 Kelvin"),
...     alpha=[1.2, 3.4, 5.6] * u.s**2,
...     DemagnetizingFactor=me.Entity("DemagnetizingFactor", [1, 0.5, 0.5]),
...     comment=[
...         "Comment in the first row",
...         "Comment in the second row",
...         "Comment in the third row",
...     ],
...     Tc=me.Tc(300, "K"),
... )
>>> collection.to_yaml("example.yaml")

The new file has the following content:

>>> print(Path("example.yaml").read_text())
# mammos yaml v2
metadata: null
description: Test data
data:
  index:
    value: [0, 1, 2]
  Ms:
    ontology_label: SpontaneousMagnetization
    description: Magnetization at 0 Kelvin
    ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_032731f8-874d-5efb-9c9d-6dafaa17ef25
    unit: kA / m
    value: [100.0, 100.0, 100.0]
  alpha:
    unit: s2
    value: [1.2, 3.4, 5.6]
  DemagnetizingFactor:
    ontology_label: DemagnetizingFactor
    description: ''
    ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_0f2b5cc9-d00a-5030-8448-99ba6b7dfd1e
    unit: ''
    value: [1.0, 0.5, 0.5]
  comment:
    value: [Comment in the first row, Comment in the second row, Comment in the third
        row]
  Tc:
    ontology_label: CurieTemperature
    description: ''
    ontology_iri: https://w3id.org/emmo#EMMO_6b5af5a8_a2d8_4353_a1d6_54c9f778343d
    unit: K
    value: 300.0

>>> Path("example.yaml").unlink()

Here is a second example with one outer and one inner collection:

>>> properties = me.EntityCollection(
...     description="material properties",
...     Ms=me.Ms(1.3e3, "kA/m"),
...     Tc=me.Tc(1043, "K"),
... )
>>> measurement = me.EntityCollection(
...     description="measurement with device X",
...     sample=properties,
...     T=me.T(300, "K", description="Measurement conditions"),
...     H=me.H([0, 50, 100], "kA/m"),
...     M=me.M([100, 300, 500], "kA/m"),
... )
>>> measurement.to_yaml("nested_example.yaml")
>>> print(Path("nested_example.yaml").read_text())
# mammos yaml v2
metadata: null
description: measurement with device X
data:
  sample:
    description: material properties
    data:
      Ms:
        ontology_label: SpontaneousMagnetization
        description: ''
        ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_032731f8-874d-5efb-9c9d-6dafaa17ef25
        unit: kA / m
        value: 1300.0
      Tc:
        ontology_label: CurieTemperature
        description: ''
        ontology_iri: https://w3id.org/emmo#EMMO_6b5af5a8_a2d8_4353_a1d6_54c9f778343d
        unit: K
        value: 1043.0
  T:
    ontology_label: ThermodynamicTemperature
    description: Measurement conditions
    ontology_iri: https://w3id.org/emmo#EMMO_affe07e4_e9bc_4852_86c6_69e26182a17f
    unit: K
    value: 300.0
  H:
    ontology_label: ExternalMagneticField
    description: ''
    ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_da08f0d3-fe19-58bc-8fb6-ecc8992d5eb3
    unit: kA / m
    value: [0.0, 50.0, 100.0]
  M:
    ontology_label: Magnetization
    description: ''
    ontology_iri: https://w3id.org/emmo#EMMO_b23e7251_a488_4732_8268_027ad76d7e37
    unit: kA / m
    value: [100.0, 300.0, 500.0]

>>> Path("nested_example.yaml").unlink()

class magmeas.base.MT(datfile, read_method='auto')[source]#

Bases: _PropertyContainer, VSM

Class for importing, storing and using of VSM-data from M(T)-measurement aswell as derived properties.

property Tc: Entity#: The Curie-temperature(s) calculated from the measurement data.

segments(edge=0.05)[source]#

Find indices of segmentation points which can be used to seperate each measurement segment from each other. The segments are seperated by a changing sign of dT/dt.

Parameters:: edge (FLOAT, optional) – Percentage of measurement to be treated as edge. Default is 0.05, which means that segmentation points closer than 5 % of the total measurement width to the edges will be discarded.
Returns:: s – Array of segmentation points that can be used to segmentise the measurement.
Return type:: ARRAY[INT]

plot(filepath=None, derivative=True, segments=(None, None), fig_ax=None, **kwargs)[source]#

Plot cooling curve of M(T) measurement. Save to file if path is given.

Parameters:

filepath (STR | PATH, optional) – Filepath for saving the figure. Default is None, in that case no file is saved.
derivative (BOOL, optional) – Whether to plot the first derivative dM/dT on a second axes. Default is True.
segments (TUPLE(NONE | INT), optional) – Segmentation points (start, end) at which the data to be plotted will be cut off. See the method ‘segments’ for more information. Note that valid input here are only the indices FOR the output from the segments method and NOT the indices of the actual measurement points. Use None to plot until the respective start or end. Default is (None, None).
fig_ax (TUPLE(matplotlib.figure.Figure, matplotlib.axes.Axes), optional) – Tuple of figure and axes the data should be plotted to. If None is given they will be generated dynamically. Default is None.
kwargs – Keyword arguments to change the appearance of plots. See documentation of matplotlib.pyplot.plot for more information.

Returns:

Return figure and axes object if filepath is not specified.

Return type:

None | (matplotlib.Figure, matplotlib.Axes)

property H: Entity#: The internal magnetic field calculated from the measurement data. Calculated according to:

\[H_{int} = H_{ext} - D \cdot M\]

property H_ext: Entity#: The external magnetic field as read from the measurement file.

property M: Entity#

The magnetisation calculated from the measurement data. Calculated according to:

\[M = \frac{m}{V}\]

with m being the magnetic moment and V being the volume.

property T: Entity#: The thermodynamic temperature as read from the measurement file.

property description: str#

Additional description of the entity collection.

classmethod from_dataframe(dataframe: pd.DataFrame, metadata: dict[str, dict]) → mammos_entity.EntityCollection#

Create EntityCollection from dataframe and metadata.

All column names in the dataframe must also exist as keys in metadata and vice versa.

In addition metadata can have a key description containing a description for the collection.

Parameters:

dataframe – A dataframe containing the values for the individual entities.
metadata – A dictionary with the structure similar to the one defined in metadata(). The keys unit and description for an :py:class`~mammos_entity.Entity` are however optional. If not present, default units from the ontology and an empty description are used.

property m: Quantity#: The magnetic moment as read from the measurement file.

metadata() → dict[str, str | dict[str, str]]#

Get entity metadata as dictionary.

entity

key unit if the attribute is a quantity
an empty dictionary otherwise

In addition there is one key-value pair description for the collection description.

property path: Path#: Path to the file which was used in the object generation.

reload_qd(datfile, read_method)#

Load VSM-data from a quantum systems .DAT file.

Parameters:

datfile (STR | PATH) – Path to quantum systems .DAT file that data is supposed to be imported from
read_method (STR) – Determines whether magmeas will attempt to automatically read the sample parameters necessary for the following calculations or not. Can be “auto” or “manual”

Return type:

None

property t: Entity#: The time since the start of the measurement.

to_csv(filename)#

Write measurement data and calculated properties to two separate CSV-files.

Parameters:: filename (STR | PATH) – Base of the generated files. Measurement data will have a ‘_data’ attached before the file extension and properties ‘_properties’.
Return type:: None

to_dataframe(include_units: bool = False) → DataFrame#

Convert values to dataframe.

Parameters:: include_units – If true, include units in the dataframe column names.

Write a collection to an HDF5 group.

Entities of the collection become datasets in the group. The collection description is added to the group attributes.

Parameters:

base – If it is an open HDF5 file or a group in an HDF5 file, data will be added to it as new group. If it is a str or PathLike a new HDF5 file with the given name will be created. If a file with that name exists already, it will be overwritten without notice.
name – Name for the newly created group. If an element with that name exists already in base the function will fail. If name is None entities of the collection will be added directly to base and the collection description will be added to base attributes.

Returns:

If base is an open File or Group the newly created group. If base is a file name nothing is returned (because the file created internally will be closed before the function returns).

to_yaml(filename: str | PathLike) → None#

Write collection to YAML file.

MaMMoS YAML files have the following format:

one commented line at the top of the file containing the mammos format version in the form # mammos yaml v<version-number>.
a mapping with three top-level keys metadata, description and data
metadata is currently unused and should be empty
the description key contains a (multi-line) string with arbitrary content describing the top-level collection
data contains one key per element in the collection. Each entry is either an entity-like entry or a nested collection node.

Collection nodes are recursive and have two keys description and data:

description: a (multi-line) string with arbitrary content

data: mapping from entry names to entity-like entries or nested collection nodes

Entity-like entries have the following keys:

For Entity:

ontology_label: label in the ontology

description: description string

ontology_iri: IRI of the entity

unit: unit of the entity ("" for dimensionless)

value: value of the data

For Quantity:

unit: unit of the quantity

value: value of the data

For any other value:

value: value of the data

Parameters:: filename – Name of the generated file. An existing file with the same name is overwritten without notice.
Raises:: ValueError – If the top-level collection is empty.

Example

Here is an example with six entries:

an index with no units or ontology label
the entity spontaneous magnetization with an entry in the ontology and a description
a made-up quantity alpha with a unit but no ontology label
demagnetizing factor with an ontology entry but no unit
a column comment containing a string comment without units or ontology label
an element Tc with only a single value

The file has a description reading “Test data”.

>>> from pathlib import Path
>>> import mammos_entity as me
>>> import mammos_units as u
>>> collection = me.EntityCollection(
...     description="Test data",
...     index=[0, 1, 2],
...     Ms=me.Entity("SpontaneousMagnetization", [1e2, 1e2, 1e2], "kA/m", description="Magnetization at 0 Kelvin"),
...     alpha=[1.2, 3.4, 5.6] * u.s**2,
...     DemagnetizingFactor=me.Entity("DemagnetizingFactor", [1, 0.5, 0.5]),
...     comment=[
...         "Comment in the first row",
...         "Comment in the second row",
...         "Comment in the third row",
...     ],
...     Tc=me.Tc(300, "K"),
... )
>>> collection.to_yaml("example.yaml")

The new file has the following content:

>>> print(Path("example.yaml").read_text())
# mammos yaml v2
metadata: null
description: Test data
data:
  index:
    value: [0, 1, 2]
  Ms:
    ontology_label: SpontaneousMagnetization
    description: Magnetization at 0 Kelvin
    ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_032731f8-874d-5efb-9c9d-6dafaa17ef25
    unit: kA / m
    value: [100.0, 100.0, 100.0]
  alpha:
    unit: s2
    value: [1.2, 3.4, 5.6]
  DemagnetizingFactor:
    ontology_label: DemagnetizingFactor
    description: ''
    ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_0f2b5cc9-d00a-5030-8448-99ba6b7dfd1e
    unit: ''
    value: [1.0, 0.5, 0.5]
  comment:
    value: [Comment in the first row, Comment in the second row, Comment in the third
        row]
  Tc:
    ontology_label: CurieTemperature
    description: ''
    ontology_iri: https://w3id.org/emmo#EMMO_6b5af5a8_a2d8_4353_a1d6_54c9f778343d
    unit: K
    value: 300.0

>>> Path("example.yaml").unlink()

Here is a second example with one outer and one inner collection:

>>> properties = me.EntityCollection(
...     description="material properties",
...     Ms=me.Ms(1.3e3, "kA/m"),
...     Tc=me.Tc(1043, "K"),
... )
>>> measurement = me.EntityCollection(
...     description="measurement with device X",
...     sample=properties,
...     T=me.T(300, "K", description="Measurement conditions"),
...     H=me.H([0, 50, 100], "kA/m"),
...     M=me.M([100, 300, 500], "kA/m"),
... )
>>> measurement.to_yaml("nested_example.yaml")
>>> print(Path("nested_example.yaml").read_text())
# mammos yaml v2
metadata: null
description: measurement with device X
data:
  sample:
    description: material properties
    data:
      Ms:
        ontology_label: SpontaneousMagnetization
        description: ''
        ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_032731f8-874d-5efb-9c9d-6dafaa17ef25
        unit: kA / m
        value: 1300.0
      Tc:
        ontology_label: CurieTemperature
        description: ''
        ontology_iri: https://w3id.org/emmo#EMMO_6b5af5a8_a2d8_4353_a1d6_54c9f778343d
        unit: K
        value: 1043.0
  T:
    ontology_label: ThermodynamicTemperature
    description: Measurement conditions
    ontology_iri: https://w3id.org/emmo#EMMO_affe07e4_e9bc_4852_86c6_69e26182a17f
    unit: K
    value: 300.0
  H:
    ontology_label: ExternalMagneticField
    description: ''
    ontology_iri: https://w3id.org/emmo/domain/magnetic-materials#EMMO_da08f0d3-fe19-58bc-8fb6-ecc8992d5eb3
    unit: kA / m
    value: [0.0, 50.0, 100.0]
  M:
    ontology_label: Magnetization
    description: ''
    ontology_iri: https://w3id.org/emmo#EMMO_b23e7251_a488_4732_8268_027ad76d7e37
    unit: kA / m
    value: [100.0, 300.0, 500.0]

>>> Path("nested_example.yaml").unlink()

magmeas.base.plot_batch(data, filepath=None, labels=None, unit='T', segments=(None, None), cmap='inferno', color_range=(0, 0.9), demag=True, derivative=True, fig_ax=None, **kwargs)[source]#

Plot several VSM-derived objects together. Must be of the same type.

Parameters:

data (LIST[MH | MH_major | MT] | mammos_entity.EntityCollection) – List or EntityCollection of several objects which have to be of magmeas classes that have a plotting method. All contained objects need to be of the same class.
filepath (STR | PATH, optional) – Filepath for saving the figure. If None is given, then instead the generated figure and axes objects will be returned. Default is None.
labels (LIST, optional) – List of labels that are going to be used in the legend of the plot. Has to have the same length as data. If none is given then the names of the .DAT files each VSM object was calculated from will be used.
unit (STR | mu.unit | TUPLE(STR | mu.unit)) – Only supported for MH-derived measurements. Unit H and M are going to be plotted in. If string is given then both will have the same unit. Otherwise specify respective units as tuple (H_unit, M_unit). Default is ‘T’.
segments (TUPLE(NONE | INT), optional) – Segmentation points (start, end) at which the data to be plotted will be cut off. See the method ‘segments’ for more information. Note that valid input here are only the indices FOR the output from the segments method and NOT the indices of the actual measurement points. Use None to plot until the respective start or end. The demagnetisation curve will not be affected by this, it is always plotted in the same way between the same bounds. Default is (None, None).
cmap (STR | matplotlib.colors.Colormap | matplotlib.colors.ListedColormap) – Colormap that will be used to generate the colours of all lines. Each colormap will be filled with np.linspace according to color_range. Please keep the visibility of ALL lines in mind! Colormaps such as ‘gray’ or ‘hot’ will definitely lead to invisible/barely visible lines. Default is ‘inferno’.
color_range (TUPLE(FLOAT | INT), optional) – Color range to control from which range of the colormap gradient the colors will be picked. Full range would be (0, 1). Often it makes sense to restrict the range towards smaller maximum values as many colormaps have very bright colors at values getting closer to 1, which will lead to poorly visible lines. This can also be used to reverse the color gradient when switching maximum and minimum, as in (1, 0). Default is (0, 0.9).
demag (BOOL, optional) – Determines, whether demagnetization curve is plotted as an inset next to hysteresis loop if MH_major objects are in data. Will not do anything otherwise. Default is True.
derivative (BOOL, optional) – Determines, whether derivative dM/dT is plotted as another subplot below the M(T) plot if MT objects are in data. Will not do anything otherwise. Default is True.
fig_ax (TUPLE(matplotlib.figure.Figure, matplotlib.axes.Axes), optional) – Tuple of figure and axes the data should be plotted to. If None is given they will be generated dynamically. Default is None.
kwargs – Keyword arguments to change the appearance of lines. All arguments are applied to every line. The arguments ‘color’ and ‘c’ are not allowed as they would lead to all lines having the same colour, making them indistinguishable. See documentation of matplotlib.pyplot.plot for more information.

Returns:

Return figure and axes object if filepath is not specified.

Return type:

None | (matplotlib.Figure, matplotlib.Axes)

magmeas.base.to_batch(data, labels=None, prop_only=False)[source]#

Generate batch of VSM-derived objects as mammos_entity.EntityCollection.

Parameters:

data (LIST[MH_major | MT]) – List of VSM objects that will be exported.
labels (LIST[STR], optional) – List of strings to identify the VSM objects more easily. If not given, the filenames of each VSM-object are used instead.
prop_only (BOOL, optional) – Whether to only export the the properties and no measurement data. Will lead to an AttributeError if this is True but the objects in data only contain measurement data and no properties. Default is False.

Return type:

None

magmeas.base.to_yaml(data, filepath, labels=None, prop_only=False)[source]#

Save all properties derived from list of VSM-measurements to YAML file.

Parameters:

data (LIST[MH_major | MT]) – List of VSM objects that will be exported.
filepath (STR | PATH) – Filepath to save the file to.
labels (LIST[STR], optional) – List of strings to identify the VSM objects more easily. If not given, the filenames of each VSM-object are used instead.
prop_only (BOOL, optional) – Whether to only export the the properties and no measurement data. Will lead to an AttributeError if this is True but the objects in data only contain measurement data and no properties. Default is False.

Return type:

None

magmeas.base.to_hdf5(data, filepath, labels=None, prop_only=False)[source]#

Save all properties derived from list of VSM-measurements to HDF5 file.

Parameters:

data (LIST[MH_major | MT]) – List of VSM objects that will be exported.
filepath (STR | PATH) – Filepath to save the file to.
labels (LIST[STR], optional) – List of strings to identify the VSM objects more easily. If not given, the filenames of each VSM-object are used instead.
prop_only (BOOL, optional) – Whether to only export the the properties and no measurement data. Will lead to an AttributeError if this is True but the objects in data only contain measurement data and no properties. Default is False.

Return type:

None