{"id":22007069,"url":"https://github.com/exabyte-io/express","last_synced_at":"2026-04-02T13:32:26.660Z","repository":{"id":34367277,"uuid":"98949355","full_name":"Exabyte-io/express","owner":"Exabyte-io","description":"ExPrESS: Exabyte Property Extractor, Sourcer, Serializer. A python package allowing to extract and standardize materials data from native format for physics-based simulation engines.","archived":false,"fork":false,"pushed_at":"2026-03-25T19:22:37.000Z","size":1378,"stargazers_count":3,"open_issues_count":3,"forks_count":2,"subscribers_count":9,"default_branch":"main","last_synced_at":"2026-03-26T19:43:48.165Z","etag":null,"topics":["density-functional-theory","materials","materials-design","materials-genome","materials-informatics","materials-science"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Exabyte-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-08-01T02:16:21.000Z","updated_at":"2026-03-25T19:21:06.000Z","dependencies_parsed_at":"2023-12-14T14:30:10.196Z","dependency_job_id":"2211013d-6a15-4e6c-801d-acfbc712686e","html_url":"https://github.com/Exabyte-io/express","commit_stats":null,"previous_names":["exabyte-io/exabyte-express"],"tags_count":113,"template":false,"template_full_name":null,"purl":"pkg:github/Exabyte-io/express","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Exabyte-io%2Fexpress","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Exabyte-io%2Fexpress/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Exabyte-io%2Fexpress/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Exabyte-io%2Fexpress/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Exabyte-io","download_url":"https://codeload.github.com/Exabyte-io/express/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Exabyte-io%2Fexpress/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31307136,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["density-functional-theory","materials","materials-design","materials-genome","materials-informatics","materials-science"],"created_at":"2024-11-30T01:16:50.455Z","updated_at":"2026-04-02T13:32:26.641Z","avatar_url":"https://github.com/Exabyte-io.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![PyPI version](https://badge.fury.io/py/express-py.svg)](https://badge.fury.io/py/express-py)\n[![License: Apache](https://img.shields.io/badge/License-Apache-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)\n\n# ExPreSS\n\nExabyte Property Extractor, Sourcer, Serializer (ExPreSS) is a Python package to extract material- and simulation-related properties and serialize them according to the Exabyte Data Convention (EDC) outlined in [Exabyte Source of Schemas and Examples (ESSE)](https://github.com/Exabyte-io/exabyte-esse). \n\n## 1. Overview\n\nThe following Functionality is supported:\n\n- Extract structural information, material properties and from simulation data\n- Serialize extracted information according to [ESSE](#links) data standard\n- Support for multiple simulation engines, including:\n  - [VASP](#links)\n  - [Quantum ESPRESSO](#links)\n  - [JARVIS](#links)\n  - others, to be added\n\nThe package is written in a modular way easy to extend for additional applications and properties of interest. Contributions can be in the form of additional [functionality](#todo-list) and [bug/issue reports](https://help.github.com/articles/creating-an-issue/).\n\n## 2. Installation\n\nExPreSS can be installed as a Python package either via PyPi or the repository as below.\n\n### 2.1. From PyPi\n\n```bash\npip install express-py\n```\n\n### 2.2. From GitHub repository\n\nSee \"Development\" section below.\n\n## 3. Usage\n\n### 3.1. Extract Total Energy\n\nThe following example demonstrates how to initialize an ExPreSS class instance to extract and serialize total energy produced in a Quantum ESPRESSO calculation. The full path to the calculation directory (`work_dir`) and the file containing standard output (`stdout_file`) are required to be passed as arguments to the underlying Espresso parser.\n\n```python\n\nimport json\nfrom express import ExPrESS\n\nkwargs = {\n    \"work_dir\": \"./tests/fixtures/espresso/test-001\",\n    \"stdout_file\": \"./tests/fixtures/espresso/test-001/pw-scf.out\"\n\n}\n\nhandler = ExPrESS(\"espresso\", **kwargs)\ndata = handler.property(\"total_energy\", **kwargs)\nprint(json.dumps(data, indent=4))\n\n```\n\n### 3.2. Extract Relaxed Structure\n\nIn this example the final structure of a VASP calculation is extracted and is serialized to a material. The final structure is extracted from the `CONTCAR` file located in the calculation directory (`work_dir`). `is_final_structure=True` argument should be passed to the [Material Property](express/properties/material.py) class to let it know to extract final structure.\n\n```python\n\nimport json\nfrom express import ExPrESS\n\nkwargs = {\n    \"work_dir\": \"./tests/fixtures/vasp/test-001\",\n    \"stdout_file\": \"./tests/fixtures/vasp/test-001/vasp.out\"\n\n}\n\nhandler = ExPrESS(\"vasp\", **kwargs)\ndata = handler.property(\"material\", is_final_structure=True, **kwargs)\nprint(json.dumps(data, indent=4))\n\n```\n\n### 3.3. Extract Structure from input file\n\nOne can use [StructureParser](express/parsers/structure.py) to extract materials from POSCAR or PW input files. Please note that `StructureParser` class only works with strings and not files and therefore the input files should be read first and then passed to the parser.\n\n```python\n\nimport json\nfrom express import ExPrESS\n\nwith open(\"./tests/fixtures/vasp/test-001/POSCAR\") as f:\n    poscar = f.read()\n\nkwargs = {\n    \"structure_string\": poscar,\n    \"structure_format\": \"poscar\"\n}\n\nhandler = ExPrESS(\"structure\", **kwargs)\ndata = handler.property(\"material\", **kwargs)\nprint(json.dumps(data, indent=4))\n\nwith open(\"./tests/fixtures/espresso/test-001/pw-scf.in\") as f:\n    pwscf_input = f.read()\n\nkwargs = {\n    \"structure_string\": pwscf_input,\n    \"structure_format\": \"espresso-in\"\n}\n\nhandler = ExPrESS(\"structure\", **kwargs)\ndata = handler.property(\"material\", **kwargs)\nprint(json.dumps(data, indent=4))\n```\n\n## 4. Development\n\n### 4.1. Install From GitHub\n\n1. Install [git-lfs](https://help.github.com/articles/installing-git-large-file-storage/) in order to pull the files stored on Git LFS.\n2. Clone repository:\n    ```bash\n    git clone git@github.com:Exabyte-io/express.git\n    ```\n3. Install [virtualenv](https://virtualenv.pypa.io/en/stable/) using [pip](https://pip.pypa.io/en/stable/) if not already present:\n    ```bash\n    pip install virtualenv\n    ```\n4. Create virtual environment and install required packages:\n    ```bash\n    cd express\n    virtualenv venv\n    source venv/bin/activate\n    export GIT_LFS_SKIP_SMUDGE=1\n    pip install -e PATH_TO_EXPRESS_REPOSITORY\n    ```\n\n### 4.2. Tests\n\nThere are two types of tests in ExPreSS: unit and integration, implemented in [Python Unit Testing Framework](https://docs.python.org/2/library/unittest.html).\n\n#### 4.2.1. Unit Tests\n\nUnit tests are used to assert properties are serialized according to EDC. Properties classes are initialized with mocked parser data and then are serialized to assert functionality.\n\n#### 4.2.2. Integration Tests\n\nParsers functionality is tested through integration tests. The parsers are initialized with the configuration specified in the [Tests Manifest](./tests/manifest.yaml) and then the functionality is asserted.\n\n#### 4.2.3. Running Tests\n\n\u003e Note that the CI tests are run using a github action in `.github`, and not using the script below, so there could be discrepancies.\n\nRun the following commands to run the tests (\"unit\" tests only in this case).\n\n```bash\npython -m unittest discover --verbose --catch --start-directory tests/unit\n```\n\n## 5. Architecture\n\nThe following diagram presents the package architecture. The package provides an [interface](express/__init__.py) to extract properties in EDC format. Inside the interface `Property` classes are initialized with a `Parser` (Vasp, Espresso, or Structure) depending on the given parameters through the parser factory. Each `Property` class implements required calls to `Parser` functions listed in these [Mixins Classes](express/parsers/mixins) to extract raw data either from the textual files, XML files or input files in string format and implements a serializer to form the final property according to the EDC format.\n\n![ExPreSS](https://user-images.githubusercontent.com/10528238/53124591-9958e700-3510-11e9-9222-3aedacfd7943.png)\n\n### 5.1. Parsers\n\nAs explained above, ExPreSS parsers are responsible for extracting raw data from different sources such as data on the disk and provide the raw data to properties classes. In order to make sure all parsers implement the same interfaces and abstract properties classes from the parsers implementations, a set a [Mixin Classes](express/parsers/mixins) are provided which should be mixed with the parsers. The parsers must implement Mixins' abstract methods at the time of inheritance.\n\n### 5.2. Properties\n\nExPreSS properties classes are responsible to form the properties based on the raw data provided by the parsers and serialize the property according to EDC. A list of supported properties are available in [here](express/settings.py).\n\n### 5.3. Extractors\n\nExtractors are classes that are composed with the parsers to extract raw data from the corresponding sources such as text or XML.\n\n\n## 6. Contribution\n\nThis repository is an [open-source](LICENSE.md) work-in-progress and we welcome contributions. We suggest forking this repository and introducing the adjustments there. The changes in the fork can further be considered for merging into this repository as explained in [GitHub Standard Fork and Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).\n\n\n## 7. TODO list\n\nDesirable features for implementation:\n\n- Add support for other properties\n- Add support for other types of applications, parsers and extractors\n- other (TBA)\n\n## Links\n\n1. [Excellent Source of Schemas and Examples (ESSE), Github Repository](https://github.com/exabyte-io/esse)\n1. [Vienna Ab-initio Simulation Package (VASP), official website](https://cms.mpi.univie.ac.at/vasp/)\n1. [Quantum ESPRESSO, Official Website](https://www.quantum-espresso.org/)\n1. [JARVIS NIST](https://pages.nist.gov/jarvis/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexabyte-io%2Fexpress","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexabyte-io%2Fexpress","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexabyte-io%2Fexpress/lists"}