Package: aiida-optimade
OPTIMADE API implementation for AiiDAThe compatibility matrix below assumes the user always install the latest patch release of the specified minor version, which is recommended.PluginAiiDAPythonSpecificationv1.2 < v2.0v1.0 < v1.2v0.18 <= v0.20Latest releaseBuild statusActivityThis is a RESTful API server created withFastAPIthat exposes an AiiDA database according to theOPTIMADE specification.It is mainly used byMaterials Cloudto expose access to archived AiiDA databases through the OPTIMADE API.
But it may be freely implemented by any to fulfill a similar purpose.The server is based on the test server "template" used in theoptimade-python-toolspackage.
Indeed, the filter grammar and parser andpydanticmodels fromoptimade-python-toolsare used directly here.PrerequisitesEnvironment where AiiDA is installed.AiiDA database containingStructureDatanodes, since these are theonlyAiiDA nodes that are currently exposed with this API (under the/structuresendpoint).InstallationThe package is relased on PyPI, hence you can install it by:$pipinstallaiida-optimadeOtherwise, you can alsogit clonethe repository from GitHub:$gitclonehttps://github.com/aiidateam/aiida-optimade/path/to/aiida-optimade/parent/dir
$pipinstall-e/path/to/aiida-optimadeDevelopmentFor developers, there is a special setuptools extradev, which can be installed by:$pipinstallaiida-optimade[dev]or$pipinstall-e/path/to/aiida-optimade[dev]This package usesBlackfor formatting.
If you wish to contribute, please install the git pre-commit hook:/path/to/aiida-optimade$pre-commitinstallThis will automatically update the formatting when runninggit commit, as well as check the validity of various repository JSON and YAML files.For testing runpytest, which will run with an AiiDA backend as standard.
The tests can also be run with the MongoDB backend by setting the environment variablePYTEST_OPTIMADE_CONFIG_FILE, the value being a path to the config file to be used:$PYTEST_OPTIMADE_CONFIG_FILE=/path/to/aiida-optimade/tests/static/test_mongo_config.jsonpytestHowever, note that themongo_urivalue will have to be updated according to your local setup.InitializationYou should first initialize your AiiDA profile.This can be done by using theaiida-optimadeCLI:$aiida-optimade-p<PROFILE>initWhere<PROFILE>is the AiiDA profile.Note: Currently, the default isoptimade, if the-p / --profileoption is not specified.
This will be changed in the future to use the default AiiDA profile.Initialization goes through your profile'sStructureDatanodes, adding anoptimadeextra, wherein all OPTIMADE-specific fields that do not have an equivalent AiiDA property are stored.If in the future, moreStructureDatanodes are added to your profile's database, these will be automatically updated for the first query, filtering on any of these OPTIMADE-specific fields.
However, if you do not wish a significant lag for the user or risking several GET requests coming in at the same time, trying to update your profile's database, you should re-runaiida-optimade initfor your profile (in between shutting the server down and restarting it again).Running the serverLocallyUsing theaiida-optimadeCLI, you can do the following:$aiida-optimade-p<PROFILE>runWhere<PROFILE>is the AiiDA profile you wish to serve.Note: Currently, the default isoptimade, if the-p / --profileoption is now specified.
This will be changed in the future to use the default AiiDA profile.You also have the opportunity to specify the AiiDA profile via the environment variableAIIDA_PROFILE.
Note, however, that if a profile name is passed to the CLI, it will overruleand replacethe currentAIIDA_PROFILEenvironment variable.# Specifying AiiDA profile as an environment variable$exportAIIDA_PROFILE=optimade
$aiida-optimaderunNavigate tohttp://localhost:5000/v1/infoTip: To see the default AiiDA profile, typeverdi profile listto find the colored profile name marked with an asterisk (*), or typeverdi profile show, which will show you more detailed information about the default profile.Note: Theaiida-optimade runcommand has more options to configure your server, run$aiida-optimaderun--helpfor more information.With DockerAdaptprofiles/test_psql_dos.jsonandprofiles/docker-compose.ymlappropriately.$docker-compose-fprofiles/docker-compose.ymlup--buildNavigate tohttp://localhost:3253/v1/infoStop by using$docker-compose-fprofiles/docker-compose.ymldownJinja templatesIf you are familiar withJinja, there are two templates to create the JSON and YAML files:profiles/config.j2andprofiles/docker-compose.j2, respectively.Configure the serverYou can configure the server with theaiida_optimade/config.jsonfile or set certain environment variables.To learn more about this, see theoptimade-python-toolsrepository.Using AiiDA group for curated dataAnAiiDA Groupcan be used to curate data and serve only this curated data through the OPTIMADE server.
Setting thequery_groupoption inconfig.jsonwill ensure only the valid (StructureData,CifData) data nodes in the given AiiDA Group will be served.
Set thequery_groupparameter tonull(default) to serve all structure data from the database.Design choicesQ: Why create an individualconfig.jsonfile instead of just mounting an existing.aiidadirectory and using that directly?A:This, currently, wouldn't work because theREPOSITORY_URIneeds to point to the right pathinsidethe container, not on the host. Furthermore, storing all configurations in the same file can be fragile.For maintainersTo release the new version, go to GitHub release API of the repo create a new release and update the release information.The release action will be triggered by newly created release.
Note, the tag should start with avand be followed by a full semantic version (seeSemVer).
For example:v2.3.12.