API Reference#

Top-level package#

KnowledgeGraph#

Namespace#

Stores#

atomrdf.stores.create_store(kg, store, identifier, store_file=None, structure_store=None)[source]#

Create a store based on the given parameters.

Parameters:#

kgKnowledgeGraph

The knowledge graph object.

storestr or Project

The type of store to create. It can be either “Memory”, “SQLAlchemy”, or a pyiron Project object.

identifierstr

The identifier for the store.

store_filestr, optional

The file path to store the data (only applicable for certain store types).

structure_storestr, optional

The structure store to use (only applicable for certain store types).

Raises:#

ValueError

If an unknown store type is provided.

atomrdf.stores.store_alchemy(kg, store, identifier, store_file=None, structure_store=None)[source]#

Store the knowledge graph using SQLAlchemy.

Parameters:

  • kg (KnowledgeGraph) – The knowledge graph to be stored.

  • store (str) – The type of store to be used.

  • identifier (str) – The identifier for the graph.

  • store_file (str, optional) – The file path for the store. Required if store is not ‘memory’.

  • structure_store (str, optional) – The structure store to be used.

Raises:

ValueError – If store_file is None and store is not ‘memory’.

Return type:

None

atomrdf.stores.store_memory(kg, store, identifier, store_file=None, structure_store=None)[source]#

Store the knowledge graph in memory.

Parameters:

  • kg (KnowledgeGraph) – The knowledge graph to be stored.

  • store (str) – The type of store to use for storing the graph.

  • identifier (str) – The identifier for the graph.

  • store_file (str, optional) – The file to store the graph in. Defaults to None.

  • structure_store (str, optional) – The structure store to use. Defaults to None.

Return type:

None

atomrdf.stores.store_oxigraph(kg, store, identifier, store_file=None, structure_store=None)[source]#

Store the knowledge graph using Oxigraph (via oxrdflib).

Parameters:

  • kg (KnowledgeGraph) – The knowledge graph to be stored.

  • store (str) – The type of store to be used.

  • identifier (str or URIRef) – The URI identifier for the named graph. Must be consistent across open/reopen calls to retrieve the same triples.

  • store_file (str, optional) – Directory path for the persistent on-disk Oxigraph store. If None, an in-memory store is used (data is lost when the object is garbage-collected).

  • structure_store (str, optional) – The structure store to be used.

Raises:

RuntimeError – If oxrdflib is not installed.

Return type:

None

Properties#

atomrdf.properties.get_basis_positions(system)[source]#

Get the basis positions from the given system.

Parameters:

system (object) – The system object containing the structure dictionary.

Returns:

The basis positions if available, otherwise None.

Return type:

numpy.ndarray or None

atomrdf.properties.get_bravais_lattice(structure)[source]#

Get the Bravais lattice of a given system.

Parameters:

system (object) – The system object for which the Bravais lattice is to be determined.

Returns:

The Bravais lattice of the system, or None if the system’s structure dictionary is not available or the lattice is not found in the dictionary.

Return type:

str or None

atomrdf.properties.get_cell_volume(system)[source]#

Get the volume of the simulation cell.

Parameters:

system (object) – The system object.

Returns:

volume – The volume of the simulation cell.

Return type:

float

atomrdf.properties.get_chemical_composition(structure)[source]#

Get the chemical composition of the system.

Parameters:

system (object) – The system object.

Returns:

composition – A dictionary containing the chemical elements as keys and their corresponding counts as values.

Return type:

dict

atomrdf.properties.get_crystal_structure_name(system)[source]#

Get the name of the crystal structure for a given system.

Parameters:

system (object) – The system object containing the crystal structure information.

Returns:

The name of the crystal structure if available, otherwise None.

Return type:

str or None

atomrdf.properties.get_lattice_angle(system)[source]#

Calculate the lattice angles of a given system.

Parameters:

system (object) – The system object containing the structure information.

Returns:

A list of three lattice angles in degrees. If the structure information is not available, [None, None, None] is returned.

Return type:

list

atomrdf.properties.get_lattice_parameter(system)[source]#

Calculate the lattice parameters of a system.

Parameters:

system (object) – The system object containing information about the atoms and structure.

Returns:

A list containing the lattice parameters of the system. If the lattice constant is not available, [None, None, None] is returned. If the system structure is available, the lattice parameters are calculated based on the box dimensions. Otherwise, the lattice constant is returned for all three dimensions.

Return type:

list

Examples

>>> system = System()
>>> system.atoms._lattice_constant = 3.5
>>> system._structure_dict = {"box": [[1, 0, 0], [0, 1, 0], [0, 0, 1]]}
>>> get_lattice_parameter(system)
[3.5, 3.5, 3.5]

>>> system.atoms._lattice_constant = None
>>> get_lattice_parameter(system)
[None, None, None]
atomrdf.properties.get_lattice_vector(system)[source]#

Get the lattice vector of a system.

Parameters:

system (object) – The system object containing the structure information.

Returns:

A list representing the lattice vector of the system. If the structure dictionary is not available or the lattice vector is not defined, it returns [None, None, None].

Return type:

list

atomrdf.properties.get_number_of_atoms(system)[source]#

Get the number of atoms in the system.

Parameters:

system (object) – The system object.

Returns:

natoms – The number of atoms in the system.

Return type:

int

atomrdf.properties.get_position(system)[source]#

Get the positions of the atoms in the system.

Parameters:

system (object) – The system object containing the atom positions.

Returns:

The positions of the atoms if available, otherwise None.

Return type:

numpy.ndarray or None

atomrdf.properties.get_simulation_cell_angle(system)[source]#

Get the angles between the vectors of the simulation cell.

Parameters:

system (object) – The system object containing the simulation cell information.

Returns:

angles – A list containing the angles between the vectors of the simulation cell.

Return type:

list

atomrdf.properties.get_simulation_cell_length(system)[source]#

Get the length of the simulation cell.

Parameters:

system (object) – The system object.

Returns:

length – A list containing the length of each dimension of the simulation cell.

Return type:

list

atomrdf.properties.get_simulation_cell_vector(system)[source]#

Get the simulation cell vector of the given system.

Parameters:

system (object) – The system object containing the simulation cell information.

Returns:

The simulation cell vector of the system.

Return type:

numpy.ndarray

atomrdf.properties.get_spacegroup_number(system)[source]#

Get the spacegroup number of a given system.

Parameters:

system (object) – The system object for which the spacegroup number is to be determined.

Returns:

The spacegroup number of the system if it is available, otherwise None.

Return type:

int or None

atomrdf.properties.get_spacegroup_symbol(system)[source]#

Get the symbol of the spacegroup for a given system.

Parameters:

system (object) – The system object for which to retrieve the spacegroup symbol.

Returns:

The symbol of the spacegroup if available, otherwise None.

Return type:

str

atomrdf.properties.get_species(system)[source]#

Get the species of atoms in the given system.

Parameters:

system (System) – The system object containing atoms.

Returns:

A list of species of atoms in the system.

Return type:

list

Visualisation#

atomrdf.visualize.GEXF_CATEGORY_COLORS = {'Calculation': (192, 57, 43), 'Element': (39, 174, 96), 'Literal': (189, 195, 199), 'Material': (155, 89, 182), 'Other': (149, 165, 166), 'Potential': (243, 156, 18), 'Property': (22, 160, 133), 'Sample': (224, 123, 57), 'Structure': (41, 128, 185)}#

RGB colours for each semantic category used in the GEXF / Gephi export.

atomrdf.visualize.get_string_from_URI(x)[source]#

Extract a presentable string from URI.

Parameters:

x (rdflib.term.URIRef) – The URI object to extract the string from.

Returns:

A tuple containing the presentable string representation of the URI and its type. The string representation is the last part of the URI after splitting by ‘#’ or ‘/’. The type can be either “URIRef” or “BNode”.

Return type:

tuple

atomrdf.visualize.parse_object(x)[source]#

Parse the given object and return its title and type.

Parameters:

x (RDF term) – The RDF term to parse.

Returns:

A tuple containing the title of the object and its type.

Return type:

tuple

atomrdf.visualize.to_gexf(g, output_file, include_literals=False, positions=None, sizes=None, top_n_labels=None, label_overrides=None, top_label_uris=None, injected_type_map=None)[source]#

Export an RDF graph to GEXF format for visualisation in Gephi.

Nodes are coloured by semantic category:

Category

Colour

Covers

Sample

orange #E07B39

cmso:AtomicScaleSample instances

Material

purple #9B59B6

Material description nodes

Structure

blue #2980B9

Crystal-structure / unit-cell nodes

Element

green #27AE60

Chemical element / species nodes

Calculation

red #C0392B

Simulation / activity nodes

Potential

gold #F39C12

Interatomic potential nodes

Property

teal #16A085

Calculated-property nodes

Literal

l.grey #BDC3C7

RDF literal values

Other

grey #95A5A6

Ontology terms & everything else

The viz:color attribute written into the GEXF file is read natively by Gephi and drives the default node colour. The category attribute is also stored as a node attribute so it can be used in Gephi’s Partition panel for colour/size adjustments after import.

Parameters:

  • g (rdflib.Graph) – The graph to serialise (plain, named, or conjunctive graph).

  • output_file (str) – Destination path for the .gexf file.

  • include_literals (bool, optional) – Whether to create a node for every literal value. Default is False (drops literal nodes and their edges), which produces a cleaner resource-only graph that is easier to explore in Gephi.

  • positions (dict, optional) – Mapping {uri_string: (x, y)} of pre-computed layout coordinates. Written as viz:position elements so Gephi uses them directly. When None no position attributes are written.

  • sizes (dict, optional) – Mapping {uri_string: float} of pre-computed node sizes. Written as viz:size elements. When None Gephi uses its default.

  • top_n_labels (int, optional) – When set, only the top_n_labels highest-degree nodes keep a visible label string; all other nodes are exported with an empty label. This is useful when opening in Gephi with “Show node labels” enabled — only the most connected nodes will display text. When None (the default) every node keeps its label.

  • label_overrides (dict, optional) – Mapping {uri_string: display_label} of explicit label replacements. Applied after _gexf_label() so any URI can be given a clean short name (e.g. {"http://www.vasp.at": "VASP"}).

Returns:

output_file – The path of the file that was written.

Return type:

str

atomrdf.visualize.visualize_graph(g, styledict={'BNode': {'color': '#ffe6ff', 'shape': 'box', 'style': 'filled'}, 'Literal': {'color': '#e6ffcc', 'shape': 'ellipse', 'style': 'filled'}, 'URIRef': {'color': '#ffffcc', 'shape': 'box', 'style': 'filled'}}, rankdir='TB', hide_types=False, workflow_view=False, sample_view=False, size=None, layout='dot')[source]#

Visualizes a graph using Graphviz.

Parameters:

  • g (dict) – The graph to visualize.

  • styledict (dict, optional) – A dictionary containing styles for different types of nodes and edges. Default is styledict.

  • rankdir (str, optional) – The direction of the graph layout. Default is “TB” (top to bottom).

  • hide_types (bool, optional) – Whether to hide nodes with the “type” attribute. Default is False.

  • workflow_view (bool, optional) – Whether to enable the workflow view. Default is False.

  • sample_view (bool, optional) – Whether to enable the sample view. Default is False.

  • size (str, optional) – The size of the graph. Default is None.

  • layout (str, optional) – The layout algorithm to use. Default is “dot”.

Returns:

dot – The graph visualization.

Return type:

graphviz.Digraph

Data models#

Structure#

Activity#

Dataset#

Physical quantities#

Build helpers#

Workflow parser#