mat-ret 0.1.0__tar.gz → 0.3.0__tar.gz

{mat_ret-0.1.0 → mat_ret-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mat_ret
-Version: 0.1.0
+Version: 0.3.0
 Summary: Unified retrieval and property mapping for materials databases (Materials Project, JARVIS, AFLOW, Alexandria, Materials Cloud, MPDS)
 Author-email: Aadhityan A <aadhityan1995@gmail.com>
 License: CeCILL FREE SOFTWARE LICENSE AGREEMENT
@@ -532,6 +532,7 @@ Requires-Dist: scipy
 Requires-Dist: mp-api
 Requires-Dist: jarvis-tools
 Requires-Dist: optimade[http_client]
+Requires-Dist: zstandard
 Requires-Dist: ase
 Requires-Dist: aflow
 Requires-Dist: matplotlib
@@ -539,6 +540,7 @@ Requires-Dist: pandas
 Requires-Dist: tqdm
 Requires-Dist: urllib3
 Requires-Dist: mpds-client
+Requires-Dist: PyQt6>=6.4.0
 Dynamic: license-file
 
 # mat_ret
@@ -554,6 +556,7 @@ This project is intended to extract materials data from various databases (see t
   5. MATERIALS CLOUD
   6. MPDS
   7. OQMD
+  8. OPTIMADE providers (registry search)
 
 ## Installation
 
@@ -616,6 +619,10 @@ if results:
     for key, value in entry.items():
         if key != 'structure':
             print(f"{key}: {value}")
+
+## OPTIMADE Search
+
+mat_ret can query OPTIMADE providers through the registry when you select **OPTIMADE** in the database list. The GUI shows OPTIMADE providers as a tree: select the parent to toggle all providers or pick specific providers. The same formula filter (e.g., `MgO`) applies, and the **limit per DB** is applied **per provider**.
 ``` 
 
 ## Running in a Virtual Environment (.venv)
@@ -636,6 +643,34 @@ Then run scripts using the environment's Python interpreter:
 .venv/bin/python comprehensive_database_test.py --formula Al2O3 --limit 2
 ```
 
+## Graphical User Interface (GUI)
+
+mat_ret includes a modern PyQt6-based graphical interface for easy materials retrieval.
+
+![mat_ret GUI Screenshot](doc/Screenshot.png?raw=true)
+
+### Launching the GUI
+
+```bash
+# After installation, use the command-line entry point:
+mat-ret-gui
+
+# Or using Python module syntax:
+python -m mat_ret.gui
+```
+
+### GUI Features
+
+- **Database Selection**: Checkbox interface to select which databases to query
+- **OPTIMADE Provider Tree**: Select OPTIMADE providers individually or all at once
+- **Composition Search**: Enter any chemical formula (e.g., MgO, Fe2O3, LiFePO4)
+- **Results Table**: Interactive table showing material properties from all selected databases
+- **Structure Viewer**: 3D/2D visualization of crystal structures
+  - Multiple view projections (3D, XY, XZ, YZ planes)
+  - Adjustable atom sizes
+  - Toggle bonds and unit cell display
+- **Export Options**: Save results as JSON/CSV, export structures as CIF files
+
 ## Project Structure
 
 ```
@@ -644,10 +679,19 @@ mat_ret/
 │   ├── api.py                  # High-level fetch helpers
 │   ├── property_mapping.py     # Mapping config and helpers
 │   └── databases.py            # Database client implementations
+├── gui/                        # Graphical user interface
+│   ├── main.py                 # GUI entry point
+│   ├── main_window.py          # Main application window
+│   ├── workers.py              # Async fetch workers
+│   ├── utils.py                # Utility functions and styling
+│   └── widgets/                # UI widgets
+│       ├── database_selector.py    # Database selection panel
+│       ├── results_view.py         # Results table and JSON view
+│       └── structure_viewer.py     # Crystal structure visualization
 ├── doc/                        # Documentation assets (CSV, guides)
-├── example_fetch.py            # Demo script intended to retirive information from all the above mentioned database
-├── example_single_fetch.py            # Demo script intended to retirive information from anyone of the above mentioned database
-├── README                      # Project overview
+├── example_fetch.py            # Demo script intended to retrieve information from all databases
+├── example_single_fetch.py     # Demo script intended to retrieve information from one database
+├── README.md                   # Project overview
 ├── requirements.txt            # Python dependencies
 └── LICENSE                     # CeCILL license
 ```
@@ -658,4 +702,4 @@ Keep in touch to contribute !!!
 We welcome others to develop/fix the functionalities of this python library with these existing databases and/or provide new databases.
 https://github.com/Aadhityan-A/mat_ret
 
-*Note:* It's still in the developing phase. If you face any issues let us know through github issues. Also there are some lines of code not in use are present for future development purpose.
+*Note:* It's still in the developing phase. If you face any issues let us know through github issues. Also there are some lines of code not in use are for future development purpose.

{mat_ret-0.1.0 → mat_ret-0.3.0}/README.md

@@ -11,6 +11,7 @@ This project is intended to extract materials data from various databases (see t
   5. MATERIALS CLOUD
   6. MPDS
   7. OQMD
+  8. OPTIMADE providers (registry search)
 
 ## Installation
 
@@ -73,6 +74,10 @@ if results:
     for key, value in entry.items():
         if key != 'structure':
             print(f"{key}: {value}")
+
+## OPTIMADE Search
+
+mat_ret can query OPTIMADE providers through the registry when you select **OPTIMADE** in the database list. The GUI shows OPTIMADE providers as a tree: select the parent to toggle all providers or pick specific providers. The same formula filter (e.g., `MgO`) applies, and the **limit per DB** is applied **per provider**.
 ``` 
 
 ## Running in a Virtual Environment (.venv)
@@ -93,6 +98,34 @@ Then run scripts using the environment's Python interpreter:
 .venv/bin/python comprehensive_database_test.py --formula Al2O3 --limit 2
 ```
 
+## Graphical User Interface (GUI)
+
+mat_ret includes a modern PyQt6-based graphical interface for easy materials retrieval.
+
+![mat_ret GUI Screenshot](doc/Screenshot.png?raw=true)
+
+### Launching the GUI
+
+```bash
+# After installation, use the command-line entry point:
+mat-ret-gui
+
+# Or using Python module syntax:
+python -m mat_ret.gui
+```
+
+### GUI Features
+
+- **Database Selection**: Checkbox interface to select which databases to query
+- **OPTIMADE Provider Tree**: Select OPTIMADE providers individually or all at once
+- **Composition Search**: Enter any chemical formula (e.g., MgO, Fe2O3, LiFePO4)
+- **Results Table**: Interactive table showing material properties from all selected databases
+- **Structure Viewer**: 3D/2D visualization of crystal structures
+  - Multiple view projections (3D, XY, XZ, YZ planes)
+  - Adjustable atom sizes
+  - Toggle bonds and unit cell display
+- **Export Options**: Save results as JSON/CSV, export structures as CIF files
+
 ## Project Structure
 
 ```
@@ -101,10 +134,19 @@ mat_ret/
 │   ├── api.py                  # High-level fetch helpers
 │   ├── property_mapping.py     # Mapping config and helpers
 │   └── databases.py            # Database client implementations
+├── gui/                        # Graphical user interface
+│   ├── main.py                 # GUI entry point
+│   ├── main_window.py          # Main application window
+│   ├── workers.py              # Async fetch workers
+│   ├── utils.py                # Utility functions and styling
+│   └── widgets/                # UI widgets
+│       ├── database_selector.py    # Database selection panel
+│       ├── results_view.py         # Results table and JSON view
+│       └── structure_viewer.py     # Crystal structure visualization
 ├── doc/                        # Documentation assets (CSV, guides)
-├── example_fetch.py            # Demo script intended to retirive information from all the above mentioned database
-├── example_single_fetch.py            # Demo script intended to retirive information from anyone of the above mentioned database
-├── README                      # Project overview
+├── example_fetch.py            # Demo script intended to retrieve information from all databases
+├── example_single_fetch.py     # Demo script intended to retrieve information from one database
+├── README.md                   # Project overview
 ├── requirements.txt            # Python dependencies
 └── LICENSE                     # CeCILL license
 ```
@@ -115,4 +157,4 @@ Keep in touch to contribute !!!
 We welcome others to develop/fix the functionalities of this python library with these existing databases and/or provide new databases.
 https://github.com/Aadhityan-A/mat_ret
 
-*Note:* It's still in the developing phase. If you face any issues let us know through github issues. Also there are some lines of code not in use are present for future development purpose.
+*Note:* It's still in the developing phase. If you face any issues let us know through github issues. Also there are some lines of code not in use are for future development purpose.

{mat_ret-0.1.0 → mat_ret-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mat_ret"
-version = "0.1.0"
+version = "0.3.0"
 description = "Unified retrieval and property mapping for materials databases (Materials Project, JARVIS, AFLOW, Alexandria, Materials Cloud, MPDS)"
 authors = [
     { name = "Aadhityan A", email = "aadhityan1995@gmail.com" }
@@ -20,15 +20,20 @@ dependencies = [
     "mp-api",
     "jarvis-tools",
     "optimade[http_client]",
+    "zstandard",
     "ase",
     "aflow",
     "matplotlib",
     "pandas",
     "tqdm",
     "urllib3",
-    "mpds-client"
+    "mpds-client",
+    "PyQt6>=6.4.0"
 ]
 
+[project.scripts]
+mat-ret-gui = "mat_ret.gui:main"
+
 [project.urls]
 Homepage = "https://github.com/Aadhityan-A/mat_ret"
 BugTracker = "https://github.com/Aadhityan-A/mat_ret/issues"

{mat_ret-0.1.0 → mat_ret-0.3.0}/src/mat_ret/__init__.py

@@ -28,7 +28,10 @@ from .api import (
     fetch_materials_cloud,
     fetch_oqmd,
     fetch_mpds,
+    fetch_optimade,
     fetch_all_databases,
+    list_optimade_providers,
+    harvest_optimade,
 )
 
 __all__ = [
@@ -55,5 +58,8 @@ __all__ = [
     "fetch_materials_cloud",
     "fetch_oqmd",
     "fetch_mpds",
+    "fetch_optimade",
     "fetch_all_databases",
+    "list_optimade_providers",
+    "harvest_optimade",
 ]

{mat_ret-0.1.0 → mat_ret-0.3.0}/src/mat_ret/api.py

@@ -14,7 +14,10 @@ from .databases import (
     MaterialsDatabaseRetriever,
     MaterialsProjectClient,
     OQMDClient,
+    OptimadeSearchClient,
 )
+from .optimade.harvester import OptimadeHarvester
+from .optimade.registry import fetch_registry_links
 
 
 def _sanitize_output_directory(output_directory: Optional[Path]) -> Optional[Path]:
@@ -109,6 +112,86 @@ def fetch_mpds(
     return client.get_structures(formula, limit=limit)
 
 
+def fetch_optimade(
+    formula: str,
+    *,
+    limit: int = 10,
+    output_directory: Optional[Path] = None,
+    registry_url: Optional[str] = None,
+    providers: Optional[List[Dict[str, str]]] = None,
+) -> List[Dict]:
+    """Retrieve structures from OPTIMADE providers."""
+    client = OptimadeSearchClient(
+        output_directory=_sanitize_output_directory(output_directory),
+        registry_url=registry_url,
+        providers=providers,
+    )
+    return client.get_structures(formula, limit=limit)
+
+
+def list_optimade_providers(
+    registry_url: Optional[str] = None,
+    cache_path: Optional[Path] = None,
+) -> List[Dict]:
+    """List OPTIMADE providers from the registry."""
+    if registry_url is None:
+        try:
+            import config  # type: ignore
+
+            registry_url = getattr(config, "OPTIMADE_REGISTRY_URL", None)
+        except ImportError:
+            registry_url = None
+    if not registry_url:
+        raise ValueError("OPTIMADE registry URL is required")
+
+    return fetch_registry_links(
+        registry_url,
+        cache_path=cache_path,
+    )
+
+
+def harvest_optimade(
+    output_directory: Path,
+    *,
+    registry_url: Optional[str] = None,
+    include_providers: Optional[List[str]] = None,
+    exclude_providers: Optional[List[str]] = None,
+    page_limit: int = 1000,
+    shard_size: int = 5000,
+    resume: bool = True,
+    request_timeout: int = 30,
+    rate_limit_per_host: float = 1.0,
+) -> None:
+    """Harvest all OPTIMADE providers into CIF + metadata shards."""
+    if registry_url is None:
+        try:
+            import config  # type: ignore
+
+            registry_url = getattr(config, "OPTIMADE_REGISTRY_URL", None)
+        except ImportError:
+            registry_url = None
+    if not registry_url:
+        raise ValueError("OPTIMADE registry URL is required")
+
+    providers = fetch_registry_links(
+        registry_url,
+        include=include_providers,
+        exclude=exclude_providers,
+        request_timeout=request_timeout,
+    )
+
+    harvester = OptimadeHarvester(
+        providers,
+        Path(output_directory),
+        page_limit=page_limit,
+        shard_size=shard_size,
+        resume=resume,
+        request_timeout=request_timeout,
+        rate_limit_per_host=rate_limit_per_host,
+    )
+    harvester.harvest()
+
+
 def fetch_all_databases(
     formula: str,
     *,

{mat_ret-0.1.0 → mat_ret-0.3.0}/src/mat_ret/databases.py

@@ -59,6 +59,7 @@ from .property_mapping import (
     STANDARD_PROPERTIES,
     DATABASE_PROPERTY_MAPPINGS,
 )
+from .optimade.registry import fetch_registry_links
 
 
 AFLOW_REST_URL = os.getenv("AFLOW_BASE_URL", "http://aflowlib.duke.edu/search/API/")
@@ -1043,6 +1044,213 @@ class MaterialsCloudClient(MaterialsDatabaseClient):
         return str(cif_path)
 
 
+class OptimadeSearchClient(MaterialsDatabaseClient):
+    """Generic OPTIMADE client for formula-based searches across providers."""
+
+    def __init__(
+        self,
+        output_directory: Optional[Path] = None,
+        *,
+        registry_url: Optional[str] = None,
+        providers: Optional[List[Dict[str, str]]] = None,
+        request_timeout: int = 30,
+        max_providers: Optional[int] = None,
+    ):
+        super().__init__("optimade", output_directory=output_directory)
+        self.request_timeout = request_timeout
+        self.max_providers = max_providers
+        self._providers: Optional[List[Dict[str, str]]] = None
+
+        if registry_url is None:
+            try:
+                import config  # type: ignore
+
+                registry_url = getattr(config, "OPTIMADE_REGISTRY_URL", None)
+            except ImportError:
+                registry_url = None
+
+        self.registry_url = registry_url
+
+        if providers is not None:
+            cleaned: List[Dict[str, str]] = []
+            for provider in providers:
+                if not isinstance(provider, dict):
+                    continue
+                base_url = provider.get("base_url")
+                if not base_url:
+                    continue
+                provider_id = provider.get("id") or base_url
+                provider_name = provider.get("name") or provider_id
+                cleaned.append(
+                    {
+                        "id": provider_id,
+                        "name": provider_name,
+                        "base_url": base_url,
+                    }
+                )
+            self._providers = cleaned
+
+    def _normalize_formula(self, formula: str) -> str:
+        try:
+            return Composition(formula).reduced_formula
+        except Exception:
+            return formula
+
+    def _get_providers(self) -> List[Dict[str, str]]:
+        if self._providers is not None:
+            return self._providers
+
+        if not self.registry_url:
+            self._providers = []
+            return self._providers
+
+        try:
+            self._providers = fetch_registry_links(
+                self.registry_url,
+                request_timeout=self.request_timeout,
+                max_providers=self.max_providers,
+            )
+        except Exception as exc:
+            print(f"  OPTIMADE registry fetch failed: {exc}")
+            self._providers = []
+
+        return self._providers
+
+    def _create_pymatgen_structure(self, attributes: Dict[str, Any]) -> Optional[PymatgenStructure]:
+        required_keys = {"lattice_vectors", "cartesian_site_positions", "species_at_sites"}
+        if not required_keys.issubset(attributes):
+            return None
+
+        lattice_vectors = attributes["lattice_vectors"]
+        cart_positions = attributes["cartesian_site_positions"]
+        site_species = attributes["species_at_sites"]
+
+        try:
+            from pymatgen.core.lattice import Lattice
+
+            lattice = Lattice(lattice_vectors)
+            return PymatgenStructure(lattice, site_species, cart_positions, coords_are_cartesian=True)
+        except Exception:
+            return None
+
+    def _convert_optimade_structure(self, entry: Dict[str, Any]) -> Optional[PymatgenStructure]:
+        if OptimadeStructure is None:
+            return None
+
+        attributes = entry.get("attributes", {}) if isinstance(entry.get("attributes"), dict) else {}
+        entry_for_conversion = entry
+        if "structure_features" not in attributes:
+            entry_for_conversion = {
+                **entry,
+                "attributes": {
+                    **attributes,
+                    "structure_features": [],
+                },
+            }
+        try:
+            structure = OptimadeStructure(entry_for_conversion).convert("pymatgen")
+            if isinstance(structure, PymatgenStructure):
+                return structure
+        except OptimadeConversionError as exc:
+            print(f"  OPTIMADE conversion error for {entry.get('id')}: {exc}")
+        except Exception as exc:
+            print(f"  OPTIMADE conversion failed for {entry.get('id')}: {exc}")
+        return None
+
+    def get_structures(self, formula: str, limit: int = 10) -> List[Dict]:
+        """Search OPTIMADE providers for a given formula."""
+        providers = self._get_providers()
+        if not providers or limit <= 0:
+            return []
+
+        normalized_formula = self._normalize_formula(formula)
+        filter_str = f'chemical_formula_reduced="{normalized_formula}"'
+        available_props = get_available_properties("optimade")
+        results: List[Dict] = []
+
+        for provider in providers:
+
+            base_url = provider.get("base_url")
+            if not base_url:
+                continue
+
+            provider_id = provider.get("id") or base_url
+            provider_name = provider.get("name") or provider_id
+
+            params = {
+                "filter": filter_str,
+                "page_limit": str(limit),
+            }
+
+            try:
+                response = requests.get(
+                    f"{base_url.rstrip('/')}/v1/structures",
+                    params=params,
+                    timeout=self.request_timeout,
+                )
+                response.raise_for_status()
+                payload = response.json()
+            except Exception as exc:
+                print(f"  OPTIMADE query failed for {provider_id}: {exc}")
+                continue
+
+            entries = payload.get("data", []) if isinstance(payload, dict) else []
+            if not isinstance(entries, list):
+                continue
+
+            for entry in entries[:limit]:
+                if not isinstance(entry, dict):
+                    continue
+
+                attributes = entry.get("attributes", {}) if isinstance(entry.get("attributes"), dict) else {}
+                full_data = {**entry, **attributes}
+
+                structure_data: Dict[str, Any] = {
+                    "database": "OPTIMADE",
+                    "source_database": provider_id,
+                    "provider_id": provider_id,
+                    "provider_name": provider_name,
+                    "provider_base_url": base_url,
+                }
+
+                for prop_name in available_props:
+                    value = get_property_value(full_data, "optimade", prop_name)
+                    if value is not None:
+                        structure_data[STANDARD_PROPERTIES[prop_name]] = value
+
+                structure = self._create_pymatgen_structure(attributes)
+                if structure is None:
+                    structure = self._convert_optimade_structure(entry)
+                if structure is not None:
+                    structure_data["structure"] = structure
+
+                results.append(structure_data)
+
+        return results
+
+    def save_cif(self, structure_data: Dict, filename: str) -> str:
+        """Save OPTIMADE structure as CIF file."""
+        cif_path = self.output_dir / f"{filename}.cif"
+
+        if "structure" in structure_data:
+            structure = structure_data["structure"]
+            cif_writer = CifWriter(structure)
+            cif_writer.write_file(str(cif_path))
+        else:
+            with open(cif_path, "w") as handle:
+                handle.write("# OPTIMADE structure\n")
+                handle.write(f"# Formula: {structure_data.get('formula', 'unknown')}\n")
+                handle.write(f"# Material ID: {structure_data.get('material_id', 'unknown')}\n")
+                handle.write(f"# Provider: {structure_data.get('provider_id', 'unknown')}\n")
+
+        metadata = {k: v for k, v in structure_data.items() if k != "structure"}
+        metadata_path = self.output_dir / f"{filename}_metadata.json"
+        with open(metadata_path, "w") as handle:
+            json.dump(metadata, handle, indent=2, default=str)
+
+        return str(cif_path)
+
+
 class MPDSClient(MaterialsDatabaseClient):
     """MPDS (Materials Platform for Data Science) database client."""
 
@@ -1503,6 +1711,15 @@ class MaterialsDatabaseRetriever:
             print("✓ Materials Cloud client initialized")
         except Exception as e:
             print(f"✗ Materials Cloud client failed: {e}")
+
+        # OPTIMADE (generic)
+        try:
+            self.clients['optimade'] = OptimadeSearchClient(
+                output_directory=self.output_directory,
+            )
+            print("✓ OPTIMADE client initialized")
+        except Exception as e:
+            print(f"✗ OPTIMADE client failed: {e}")
         
         # OQMD
         try:
@@ -1571,5 +1788,3 @@ class MaterialsDatabaseRetriever:
             print(f"  Successful databases: {successful_dbs}/{len(self.clients)}")
         
         return test_results
-
-

mat_ret-0.3.0/src/mat_ret/gui/__init__.py

@@ -0,0 +1,20 @@
+"""
+mat_ret GUI Package
+
+A PyQt6-based graphical interface for searching, retrieving, 
+and visualizing materials data from multiple databases.
+
+Usage:
+    # From command line (after installing mat_ret):
+    mat-ret-gui
+    
+    # Or programmatically:
+    from mat_ret.gui import main
+    main()
+"""
+
+__version__ = "1.0.0"
+
+from .main import main
+
+__all__ = ["main"]

mat_ret-0.3.0/src/mat_ret/gui/__main__.py

@@ -0,0 +1,11 @@
+"""
+Allow running mat_ret.gui as a module.
+
+Usage:
+    python -m mat_ret.gui
+"""
+
+from .main import main
+
+if __name__ == "__main__":
+    main()