jarvis

Convert an OPTIMADE structure, in the format of StructureResource to a JARVIS Atoms object.

For more information on the NIST-JARVIS repository, see their website.

This conversion function relies on the jarvis-tools package.

Contributing author

This conversion function was contributed by Kamal Choudhary (@knc6).

JARVIS_NOT_FOUND = 'jarvis-tools package not found, cannot convert structure to a JARVIS Atoms. Visit https://github.com/usnistgov/jarvis' module-attribute

__all__ = ('get_jarvis_atoms') module-attribute

AdapterPackageNotFound

Bases: OptimadeWarning

The package for an adapter cannot be found.

Source code in optimade/adapters/warnings.py

class AdapterPackageNotFound(OptimadeWarning):
    """The package for an adapter cannot be found."""

ConversionError

Bases: Exception

Could not convert entry to format

Source code in optimade/adapters/exceptions.py

class ConversionError(Exception):
    """Could not convert entry to format"""

OptimadeStructure

Bases: EntryResource

Representing a structure.

Source code in optimade/models/structures.py

class StructureResource(EntryResource):
    """Representing a structure."""

    type: Annotated[
        Literal["structures"],
        StrictField(
            description="""The name of the type of an entry.

- **Type**: string.

- **Requirements/Conventions**:
    - **Support**: MUST be supported by all implementations, MUST NOT be `null`.
    - **Query**: MUST be a queryable property with support for all mandatory filter features.
    - **Response**: REQUIRED in the response.
    - MUST be an existing entry type.
    - The entry of type `<type>` and ID `<id>` MUST be returned in response to a request for `/<type>/<id>` under the versioned base URL.

- **Examples**:
    - `"structures"`""",
            pattern="^structures$",
            support=SupportLevel.MUST,
            queryable=SupportLevel.MUST,
        ),
    ] = "structures"

    attributes: StructureResourceAttributes

StructureFeatures

Bases: Enum

Enumeration of structure_features values

Source code in optimade/models/structures.py

class StructureFeatures(Enum):
    """Enumeration of structure_features values"""

    DISORDER = "disorder"
    IMPLICIT_ATOMS = "implicit_atoms"
    SITE_ATTACHMENTS = "site_attachments"
    ASSEMBLIES = "assemblies"

get_jarvis_atoms(optimade_structure)

Get jarvis Atoms from OPTIMADE structure.

Caution

Cannot handle partial occupancies.

Parameters:

Name	Type	Description	Default
optimade_structure	StructureResource	OPTIMADE structure.	required

Returns:

Type	Description
Atoms	A jarvis Atoms object.

Source code in optimade/adapters/structures/jarvis.py

def get_jarvis_atoms(optimade_structure: OptimadeStructure) -> Atoms:
    """Get jarvis `Atoms` from OPTIMADE structure.

    Caution:
        Cannot handle partial occupancies.

    Parameters:
        optimade_structure: OPTIMADE structure.

    Returns:
        A jarvis `Atoms` object.

    """
    if "optimade.adapters" in repr(globals().get("Atoms")):
        warn(JARVIS_NOT_FOUND, AdapterPackageNotFound)
        return None

    attributes = optimade_structure.attributes

    # Cannot handle partial occupancies
    if StructureFeatures.DISORDER in attributes.structure_features:
        raise ConversionError(
            "jarvis-tools cannot handle structures with partial occupancies."
        )

    return Atoms(
        lattice_mat=attributes.lattice_vectors,
        elements=[specie.name for specie in attributes.species],  # type: ignore[union-attr]
        coords=attributes.cartesian_site_positions,
        cartesian=True,
    )