mammos_entity quickstart#
Some definitions#
a
mammos_units.Quantityis an object that carries a value and a unit.a
mammos_entity.Entitylinks a quantity to its definition in the EMMO ontology and the MaMMoS additions for magnetic materials
[1]:
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 magnetization Ms:
[2]:
Ms = me.Ms(800e3) # defines Ms = 8e5 A/m (default units are SI, i.e. A/m here)
[3]:
Ms
[3]:
If no units are provided, then the ontology units are used, such as A/m in the example above. These units are SI units typically 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.
[4]:
M1 = me.Ms(800e3, "A/m")
M1
[4]:
Providing units can be also useful, if numerical prefactors are used (such as kilo):
[5]:
M2 = me.Ms(800, "kA/m")
M2
[5]:
[6]:
M1 == M2
[6]:
True
We can create an entity from a Quantity as well:
[7]:
import mammos_units as u
Ms_quantity = 800 * u.kA / u.m
Ms_quantity
[7]:
[8]:
me.Ms(Ms_quantity)
[8]:
If we like to express spontaneous magnetization in Tesla, we can convert it to the required A/m. To allow that conversion we must explicitely enable the magnetic_flux_field equivalency (\(B=\mu_0H\)):
[9]:
# enable implicit conversion between A/m and T in the rest of the notebook:
u.set_enabled_equivalencies(u.magnetic_flux_field())
a = 1.2 * u.T # Quantity in Tesla
Ms = me.Ms(a.to("A/m")) # Convert Quantity to A/m and create entity
Ms
[9]:
As a cross-check we can access the quantity attribute and convert that back to Tesla. This operation does not modify Ms.
[10]:
Ms.q.to("T")
[10]:
Initializing with incompatible units fails with an error. In particular, implicit conversion via equivalencies is not supported. Convert to the required units first, as shown above.
[11]:
me.Ms(1.2, "T") # Tesla not compatible with A/m
---------------------------------------------------------------------------
UnitConversionError Traceback (most recent call last)
Cell In[11], line 1
----> 1 me.Ms(1.2, "T") # Tesla not compatible with A/m
File ~/repos/mammos-devtools/packages/mammos-entity/src/mammos_entity/_entities.py:217, in Ms(value, unit)
202 def Ms(
203 value: int | float | numpy.typing.ArrayLike = 0, unit: None | str = None
204 ) -> mammos_entity.Entity:
205 """Create an Entity representing the spontaneous magnetization (Ms).
206
207 Args:
(...) 215
216 """
--> 217 return Entity("SpontaneousMagnetization", value, unit)
File ~/repos/mammos-devtools/packages/mammos-entity/src/mammos_entity/_base.py:151, in Entity.__init__(self, ontology_label, value, unit)
149 with u.set_enabled_equivalencies(None):
150 if not u.Unit(si_unit).is_equivalent(unit):
--> 151 raise u.UnitConversionError(
152 f"The unit '{unit}' is not equivalent to the unit of"
153 f" {ontology_label} '{u.Unit(si_unit)}'"
154 )
155 elif (si_unit is not None) and (unit is None):
156 with u.add_enabled_aliases({"Cel": u.K, "mCel": u.K}):
UnitConversionError: The unit 'T' is not equivalent to the unit of SpontaneousMagnetization 'A / m'
For more details about unit conversion and equivalencies refer to the documentation of mammos-units.
Access to ontology#
Each entity object knows its label in the ontology:
[12]:
Ms.ontology_label
[12]:
'SpontaneousMagnetization'
The ontology attribute links to an owlready2 object created by the EMMOntoPy package.
When saving data to a file, the attribute 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).
[13]:
Ms.ontology_label_with_iri
[13]:
'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:
[14]:
Ms.ontology.get_annotations()
[14]:
{'prefLabel': [locstr('SpontaneousMagnetization', 'en')],
'altLabel': ['Ms'],
'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')],
'IECEntry': ['https://www.electropedia.org/iev/iev.nsf/display?openform&ievref=221-02-41'],
'wikipediaReference': ['https://en.wikipedia.org/wiki/Spontaneous_magnetization']}
[15]:
Ms.ontology.get_class_properties()
[15]:
{magnetic_material.wikipediaReference,
emmo.elucidation,
core.altLabel,
core.prefLabel,
magnetic_material.IECEntry,
emmo.hasMeasurementUnit}
[16]:
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 contain Quantities#
Each entity has a quantity attribute containing the mammos_units.Quantity object. See mammos_units examples for details.
[17]:
Ms.quantity
[17]:
There is also the shorthand q for the quantity attribute:
[18]:
Ms.q
[18]:
The attributes value and unit provide direct access to value and unit of the quantity:
[19]:
Ms.value
[19]:
np.float64(954929.6580315315)
[20]:
Ms.unit
[20]:
Entities do not support numerical operations. To perform these operations, we first need to extract the quantity:
[21]:
Ms.q**2
[21]:
[22]:
Ms.quantity.to("kA/m")
[22]:
[23]:
Ms.quantity.to("T")
[23]:
Defining vector entities (Example Zeeman field)#
[24]:
H = me.H([1e4, 1e4, 1e4], "A/m")
H
[24]:
[25]:
H.ontology
[25]:
magnetic_material.ExternalMagneticField
[26]:
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/api/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”:
[27]:
me.mammos_ontology.get_by_label_all("*Field*")
[27]:
{emmo.ElectricDisplacementFieldUnit,
emmo.ElectricFieldStrength,
emmo.ElectricFieldStrengthUnit,
emmo.MagneticFieldStrength,
emmo.MagneticFieldStrengthUnit,
magnetic_material.AnisotropyField,
magnetic_material.DemagnetizingField,
magnetic_material.ExternalMagneticField,
magnetic_material.InternalMagneticField,
magnetic_material.KneeField,
magnetic_material.KneeFieldExternal,
magnetic_material.SwitchingFieldCoercivity,
magnetic_material.SwitchingFieldCoercivityExternal}
Once identified the right label, we create an entity like this:
[28]:
me.Entity("ElectricFieldStrength", value=230)
[28]:
