mammos_entity quickstart

Some definitions

• a mammos_units.Quantity is an object that carries a value and units.

• a mammos_entity.Entity is a quantity, which in addition links its definition in the EMMO ontology and the MaMMoS additions for magnetic materials

import mammos_entity as me

Creating entities

For entities that are important in MaMMoS, there are convenient attributes to define those. For example for the saturation magnetisation Ms:

Ms = me.Ms(800e3)  # defines Ms = 8e5 A/m  (default units are SI, i.e. A/m here)

Ms

SpontaneousMagnetization(value=800000.0, unit=A / m)

If no units are provided, then the ontology units are used, such as A/m in the example above. These units are SI units without numerical prefactors (such as kilo, milli, etc.)

If units are provided, these are compared with the units expected for that entity. An error is raised if they do not match. This is good practice for extra clarity.

M1 = me.Ms(800e3, "A/m")
M1

SpontaneousMagnetization(value=800000.0, unit=A / m)

Providing units can be useful, if numerical prefactors are used (such as kilo):

M2 = me.Ms(800, "kA/m")
M2

SpontaneousMagnetization(value=800.0, unit=kA / m)

M1 == M2

np.True_

We can create an entity from a Quantity as well:

import mammos_units as u

Ms_quantity = 800e3 * u.A / u.m
Ms_quantity

$800000 \; \mathrm{\frac{A}{m}}$

me.Ms(Ms_quantity)

SpontaneousMagnetization(value=800000.0, unit=A / m)

If we like to express spontaneous magnetization in Tesla, we can convert it to the required A/m:

me.Ms(1.2, "T")  # Tesla not compatible with A/m

---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
Cell In[9], line 1
----> 1 me.Ms(1.2, "T")  # Tesla not compatible with A/m

File ~/git/mammos-devtools/packages/mammos-entity/src/mammos_entity/_entities.py:35, in Ms(value, unit)
     20 def Ms(
     21     value: int | float | typing.ArrayLike = 0, unit: None | str = None
     22 ) -> mammos_entity.Entity:
     23     """Create an Entity representing the spontaneous magnetization (Ms).
     24
     25     Args:
   (...)     33
     34     """
---> 35     return Entity("SpontaneousMagnetization", value, unit)

File ~/git/mammos-devtools/packages/mammos-entity/src/mammos_entity/_base.py:124, in Entity.__new__(cls, ontology_label, value, unit, **kwargs)
    122 if (si_unit is not None) and (unit is not None):
    123     if not u.Unit(si_unit).is_equivalent(unit):
--> 124         raise TypeError(
    125             f"The unit {unit} does not match the units of {ontology_label}"
    126         )
    127 elif (si_unit is not None) and (unit is None):
    128     with u.add_enabled_aliases({"Cel": u.K, "mCel": u.K}):

TypeError: The unit T does not match the units of SpontaneousMagnetization

# enable implicit conversion from here on:
u.set_enabled_equivalencies(u.magnetic_flux_field())

Js = 1.2 * u.T  # Quantity in Tesla

me.Ms(Js.to("A/m"))  # Convert Quantity to A/m and create entity

SpontaneousMagnetization(value=954929.6580315315, unit=A / m)

Access to ontology

Each entity object knows its label in the ontology:

Ms.ontology_label

'SpontaneousMagnetization'

The ontology attribute links to an owlready2 object created by the EMMOntoPy package.

When saving data to a file, this ontology_label_with_iri might be useful to save in the metadata as it returns a string containing the ontology label together with the unique identifier of the ontology entry (IRI is the Internationalized Resource Identifier).

Ms.ontology_label_with_iri

'SpontaneousMagnetization https://w3id.org/emmo/domain/magnetic_material#EMMO_032731f8-874d-5efb-9c9d-6dafaa17ef25'

We can use all attributes of the ontology object through Ms.ontology:

Ms.ontology.get_annotations()

{'prefLabel': [locstr('SpontaneousMagnetization', 'en')],
 'elucidation': [locstr('The spontaneous magnetization, Ms, of a ferromagnet is the result\nof alignment of the magnetic moments of individual atoms. Ms exists\nwithin a domain of a ferromagnet.', 'en')],
 'altLabel': ['Ms'],
 'wikipediaReference': ['https://en.wikipedia.org/wiki/Spontaneous_magnetization'],
 'IECEntry': ['https://www.electropedia.org/iev/iev.nsf/display?openform&ievref=221-02-41']}

Ms.ontology.get_class_properties()

{emmo.hasMeasurementUnit,
 magnetic_material_mammos.IECEntry,
 core.prefLabel,
 magnetic_material_mammos.wikipediaReference,
 core.altLabel,
 emmo.elucidation}

print(Ms.ontology.elucidation[0])

The spontaneous magnetization, Ms, of a ferromagnet is the result
of alignment of the magnetic moments of individual atoms. Ms exists
within a domain of a ferromagnet.

Entities behaves like Quantity

Each Entity has all the attributes and methods that are available for Quantities. See mammos_units examples for details.

Ms.value

np.float64(800000.0)

Ms.unit

$\mathrm{\frac{A}{m}}$

Ms.to("kA/m")

SpontaneousMagnetization(value=800000.0, unit=A / m)

Numerical operations with entities result in quantities (because EMMOntoPy does not support this):

Ms**2

$6.4 \times 10^{11} \; \mathrm{\frac{A^{2}}{m^{2}}}$

To convent an entity to a quantity, we can use the quantity attribute:

Ms.quantity

$800000 \; \mathrm{\frac{A}{m}}$

Defining vector entities (Example Zeeman field)

H = me.H([1e4, 1e4, 1e4], "A/m")
H

ExternalMagneticField(value=[10000. 10000. 10000.], unit=A / m)

H.ontology

magnetic_material_mammos.ExternalMagneticField

print(H.ontology.elucidation[0])

The external field H′, acting on a sample that is produced by
electric currents or the stray field of magnets outside the sample
volume, is often called the applied field.

Does mammos_entity not provide your preferred entity?

The list of convenience attributes is at https://mammos-project.github.io/mammos/_autosummary/mammos_entity.html

If the desired entity is not available, we can search the EMMO ontology (including the magnetic_material_mammos additions), for example for entity labels containing the string “Magnetization”:

me.mammos_ontology.get_by_label_all("*Field*")

{emmo.ElectricDisplacementFieldUnit,
 emmo.ElectricFieldStrength,
 emmo.ElectricFieldStrengthUnit,
 emmo.MagneticFieldStrength,
 emmo.MagneticFieldStrengthUnit,
 magnetic_material_mammos.AnisotropyField,
 magnetic_material_mammos.DemagnetizingField,
 magnetic_material_mammos.ExternalMagneticField,
 magnetic_material_mammos.InternalMagneticField,
 magnetic_material_mammos.KneeField,
 magnetic_material_mammos.KneeFieldExternal,
 magnetic_material_mammos.SwitchingFieldCoercivity,
 magnetic_material_mammos.SwitchingFieldCoercivityExternal}

Once identified the right label, we create an entity like this:

me.Entity("ElectricFieldStrength", value=230)

ElectricFieldStrength(value=230.0, unit=kg m / (A s3))