diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 0000000..100ed17 --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,34 @@ +name: Deploy Documentation +on: + push: + branches: [main] + paths: + - 'docs/**' + - 'mkdocs.yml' + workflow_dispatch: + +permissions: + contents: write + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: 3.x + + - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV + + - uses: actions/cache@v4 + with: + key: mkdocs-material-${{ env.cache_id }} + path: ~/.cache + restore-keys: | + mkdocs-material- + + - run: pip install mkdocs-material pymdown-extensions + + - run: mkdocs gh-deploy --force diff --git a/agapi/__init__.py b/agapi/__init__.py index b8011a2..82c0e52 100644 --- a/agapi/__init__.py +++ b/agapi/__init__.py @@ -1,6 +1,6 @@ """Version number.""" -__version__ = "2026.2.2" +__version__ = "2026.3.2" import os diff --git a/agapi/agents/schema.py b/agapi/agents/schema.py index 1b37534..7ff022a 100644 --- a/agapi/agents/schema.py +++ b/agapi/agents/schema.py @@ -1,5 +1,7 @@ TOOLS_SCHEMA = [ + # ------------------------------------------------------------------------- # JARVIS-DFT + # ------------------------------------------------------------------------- { "type": "function", "function": { @@ -85,11 +87,33 @@ }, }, }, + { + "type": "function", + "function": { + "name": "list_jarvis_columns", + "description": ( + "Return all column/property names available in the JARVIS-DFT database. " + "Call this first when you are unsure which property name to pass to " + "query_by_property or find_extreme." + ), + "parameters": { + "type": "object", + "properties": {}, + "required": [], + }, + }, + }, + # ------------------------------------------------------------------------- + # Structure manipulation + # ------------------------------------------------------------------------- { "type": "function", "function": { "name": "make_supercell", - "description": "Create a supercell from a POSCAR structure by replicating the unit cell. Use this to create larger simulation cells for defect studies or interface calculations.", + "description": ( + "Create a supercell from a POSCAR structure by replicating the unit cell. " + "Use this to create larger simulation cells for defect studies or interface calculations." + ), "parameters": { "type": "object", "properties": { @@ -100,7 +124,10 @@ "scaling_matrix": { "type": "array", "items": {"type": "integer"}, - "description": "List of 3 integers [nx, ny, nz] for supercell dimensions. Example: [2,1,1] creates 2x1x1 supercell", + "description": ( + "List of 3 integers [nx, ny, nz] for supercell dimensions. " + "Example: [2,1,1] creates 2×1×1 supercell." + ), "minItems": 3, "maxItems": 3, }, @@ -113,7 +140,11 @@ "type": "function", "function": { "name": "substitute_atom", - "description": "Substitute (replace) atoms in a structure. For example, replace Ga with Al to study doping or alloy formation. Useful for creating substitutional defects or alloy structures.", + "description": ( + "Substitute (replace) atoms in a structure. For example, replace Ga with Al " + "to study doping or alloy formation. Useful for creating substitutional defects " + "or alloy structures." + ), "parameters": { "type": "object", "properties": { @@ -143,7 +174,10 @@ "type": "function", "function": { "name": "create_vacancy", - "description": "Create vacancy defects by removing atoms from a structure. Useful for studying point defects, defect formation energies, or creating porous structures.", + "description": ( + "Create vacancy defects by removing atoms from a structure. Useful for studying " + "point defects, defect formation energies, or creating porous structures." + ), "parameters": { "type": "object", "properties": { @@ -165,27 +199,61 @@ }, }, }, - # ALIGNN + # ------------------------------------------------------------------------- + # ALIGNN property prediction + # ------------------------------------------------------------------------- { "type": "function", "function": { "name": "alignn_predict", - "description": "Predict material properties using ALIGNN machine learning models. Predicts formation energy, bandgap (OptB88vdW and MBJ), elastic moduli (bulk and shear), piezoelectric properties, and superconducting critical temperature. Can accept either a POSCAR structure string or a JARVIS-ID.", + "description": ( + "Predict material properties using ALIGNN machine learning models. " + "Predicts formation energy, bandgap (OptB88vdW and MBJ), elastic moduli " + "(bulk and shear), piezoelectric properties, and superconducting critical " + "temperature. Accepts either a POSCAR structure string or a JARVIS-ID." + ), "parameters": { "type": "object", "properties": { "poscar": { "type": "string", - "description": "POSCAR format structure string. Required if jid is not provided. Contains lattice vectors, atomic species, and atomic positions.", + "description": ( + "POSCAR format structure string. Required if jid is not provided." + ), }, "jid": { "type": "string", - "description": "JARVIS-ID (e.g., 'JVASP-1002', 'JVASP-816'). If provided, the structure will be fetched from JARVIS database and poscar parameter will be ignored. Use this when you know the JARVIS-ID of the material.", + "description": ( + "JARVIS-ID (e.g., 'JVASP-1002'). If provided the structure is " + "fetched from JARVIS and poscar is ignored." + ), }, }, - "required": [ - "poscar" - ], # poscar is required by the function signature, but jid can override it + "required": ["poscar"], + }, + }, + }, + # ------------------------------------------------------------------------- + # ALIGNN force field + # ------------------------------------------------------------------------- + { + "type": "function", + "function": { + "name": "alignn_ff_single_point", + "description": ( + "Evaluate energy, forces, and stress for a structure using ALIGNN-FF " + "without relaxing it. Atom limit: 50 (server-enforced). " + "Use this to quickly assess energetics of an as-provided structure." + ), + "parameters": { + "type": "object", + "properties": { + "poscar": { + "type": "string", + "description": "POSCAR format structure string (max 50 atoms)", + } + }, + "required": ["poscar"], }, }, }, @@ -193,20 +261,128 @@ "type": "function", "function": { "name": "alignn_ff_relax", - "description": "Relax structure using ALIGNN force field", + "description": ( + "Relax a crystal structure using the ALIGNN force field (legacy endpoint). " + "For full trajectory data and optimizer control, prefer alignn_ff_optimize." + ), + "parameters": { + "type": "object", + "properties": { + "poscar": { + "type": "string", + "description": "POSCAR format structure string", + }, + "fmax": { + "type": "number", + "description": "Force convergence criterion in eV/Å (default: 0.05)", + "default": 0.05, + }, + "steps": { + "type": "integer", + "description": "Maximum optimization steps (default: 150)", + "default": 150, + }, + }, + "required": ["poscar"], + }, + }, + }, + { + "type": "function", + "function": { + "name": "alignn_ff_optimize", + "description": ( + "Relax a crystal structure using the ALIGNN force field with full trajectory " + "output. Returns converged flag, final POSCAR, energy history, and max-force " + "history. Atom limit: 100 (server-enforced). Supports FIRE, BFGS, and LBFGS " + "optimizers and optional cell relaxation." + ), + "parameters": { + "type": "object", + "properties": { + "poscar": { + "type": "string", + "description": "POSCAR format structure string (max 100 atoms)", + }, + "fmax": { + "type": "number", + "description": "Force convergence criterion in eV/Å (default: 0.05)", + "default": 0.05, + }, + "steps": { + "type": "integer", + "description": "Maximum optimization steps (default: 200)", + "default": 200, + }, + "optimizer": { + "type": "string", + "enum": ["FIRE", "BFGS", "LBFGS"], + "description": "Optimization algorithm (default: 'FIRE')", + "default": "FIRE", + }, + "relax_cell": { + "type": "boolean", + "description": "Whether to also relax cell vectors (default: true)", + "default": True, + }, + }, + "required": ["poscar"], + }, + }, + }, + { + "type": "function", + "function": { + "name": "alignn_ff_md", + "description": ( + "Run NVE molecular dynamics using the ALIGNN force field. Returns trajectory " + "frames, energy vs time, and temperature vs time. Atom limit: 50 " + "(server-enforced). Useful for studying thermal stability or diffusion." + ), "parameters": { "type": "object", - "properties": {"poscar": {"type": "string"}}, + "properties": { + "poscar": { + "type": "string", + "description": "POSCAR format structure string (max 50 atoms)", + }, + "temperature": { + "type": "number", + "description": "Initial temperature in Kelvin (default: 300)", + "default": 300.0, + }, + "timestep": { + "type": "number", + "description": "MD timestep in femtoseconds (default: 0.5)", + "default": 0.5, + }, + "steps": { + "type": "integer", + "description": "Number of MD steps (default: 50)", + "default": 50, + }, + "interval": { + "type": "integer", + "description": "Frame save interval in steps (default: 5)", + "default": 5, + }, + }, "required": ["poscar"], }, }, }, + # ------------------------------------------------------------------------- # SlakoNet + # ------------------------------------------------------------------------- { "type": "function", "function": { "name": "slakonet_bandstructure", - "description": "Calculate electronic band structure and density of states using SlakoNet tight-binding model. Returns band gap, VBM, CBM values AND a band structure plot image. Works best for structures with ≤10 atoms.", + "description": ( + "Calculate electronic band structure and density of states using the SlakoNet " + "tight-binding model. Returns band gap, VBM, CBM values AND a band structure " + "plot image. Works best for structures with ≤10 atoms." + ), "parameters": { "type": "object", "properties": { @@ -229,19 +405,70 @@ }, }, }, - # DiffractGPT + # ------------------------------------------------------------------------- + # XRD / DiffractGPT + # ------------------------------------------------------------------------- + { + "type": "function", + "function": { + "name": "generate_xrd_pattern", + "description": ( + "Generate a powder XRD pattern from a crystal structure. Simulates the XRD " + "experiment and returns peak positions (2θ), relative intensities, and " + "d-spacings. Returns a DiffractGPT-compatible description and a markdown " + "peak table. Useful for comparing theoretical vs experimental patterns." + ), + "parameters": { + "type": "object", + "properties": { + "poscar": { + "type": "string", + "description": "POSCAR format structure string", + }, + "wavelength": { + "type": "number", + "description": ( + "X-ray wavelength in Å. Common values: 1.54184 (Cu Kα, default), " + "1.54056 (Cu Kα1), 0.71073 (Mo Kα)." + ), + "default": 1.54184, + }, + "num_peaks": { + "type": "integer", + "description": "Number of strongest peaks to report (default: 20)", + "default": 20, + }, + "theta_range": { + "type": "array", + "description": "2-theta range in degrees [min, max] (default: [0, 90])", + "items": {"type": "number"}, + "minItems": 2, + "maxItems": 2, + }, + }, + "required": ["poscar"], + }, + }, + }, { "type": "function", "function": { "name": "diffractgpt_predict", - "description": "Predict structure from XRD peaks (format: '30.42(1.0),49.02(0.49)')", + "description": ( + "Predict a crystal structure from XRD peaks using DiffractGPT. " + "Peaks must be provided in the format '2theta(intensity),...' " + "e.g. '30.42(1.0),49.02(0.49)'." + ), "parameters": { "type": "object", "properties": { - "formula": {"type": "string"}, + "formula": { + "type": "string", + "description": "Chemical formula of the material", + }, "peaks": { "type": "string", - "description": "XRD peaks as '2theta(intensity),...'", + "description": "XRD peaks as '2theta(intensity),...' e.g. '30.42(1.0),49.02(0.49)'", }, }, "required": ["formula", "peaks"], @@ -251,77 +478,137 @@ { "type": "function", "function": { - "name": "xrd_match", - "description": "Match experimental XRD to database", + "name": "pxrd_match", + "description": ( + "Match an experimental powder XRD pattern against the JARVIS-DFT database " + "using cosine similarity. Provide two-column data (2theta intensity, one pair " + "per line, space-separated). Returns the best-matching POSCAR from the database." + ), "parameters": { "type": "object", "properties": { - "formula": {"type": "string"}, - "xrd_pattern": {"type": "string"}, + "query": { + "type": "string", + "description": "Chemical formula or element string (e.g. 'LaB6', 'Si')", + }, + "pattern_data": { + "type": "string", + "description": ( + "Two-column XRD data as a string: '2theta intensity\\n...'. " + "One pair per line, space-separated. " + "Example: '21.38 0.69\\n30.42 1.0\\n37.44 0.31'" + ), + }, + "wavelength": { + "type": "number", + "description": "X-ray wavelength in Å (default: 1.54184 = Cu Kα)", + "default": 1.54184, + }, }, - "required": ["formula", "xrd_pattern"], + "required": ["query", "pattern_data"], }, }, }, - # Protein { "type": "function", "function": { - "name": "protein_fold", - "description": "Predict 3D protein structure from amino acid sequence using ESMFold AI. Input is a sequence of one-letter amino acid codes (e.g., 'MKTA...VSLL'). Returns PDB format structure with atomic coordinates. Works for sequences 10-400 amino acids long. ESMFold is a state-of-the-art AI model that predicts protein structure from sequence alone.", + "name": "xrd_match", + "description": ( + "Match an experimental XRD pattern to the JARVIS-DFT database (legacy endpoint). " + "For cosine-similarity matching prefer pxrd_match; " + "for combined pattern-matching + DiffractGPT analysis use xrd_analyze." + ), "parameters": { "type": "object", "properties": { - "sequence": { - "type": "string", - "description": "Amino acid sequence using one-letter codes: A (Ala), R (Arg), N (Asn), D (Asp), C (Cys), Q (Gln), E (Glu), G (Gly), H (His), I (Ile), L (Leu), K (Lys), M (Met), F (Phe), P (Pro), S (Ser), T (Thr), W (Trp), Y (Tyr), V (Val). Remove any whitespace or line breaks.", - } + "formula": {"type": "string"}, + "xrd_pattern": {"type": "string"}, }, - "required": ["sequence"], + "required": ["formula", "xrd_pattern"], }, }, }, - # XRD { "type": "function", "function": { - "name": "generate_xrd_pattern", - "description": "Generate powder X-ray diffraction (XRD) pattern from crystal structure. Simulates XRD experiment and returns peak positions (2θ), intensities, and d-spacings. Useful for predicting what XRD pattern a structure would produce, comparing theoretical vs experimental patterns, or generating training data. Returns DiffractGPT-compatible description.", + "name": "xrd_analyze", + "description": ( + "Full XRD analysis pipeline: match an experimental pattern against JARVIS-DFT " + "and optionally run DiffractGPT structure prediction. Returns best match, " + "top-5 matches, similarity score, and (if method includes 'diffractgpt') a " + "predicted POSCAR. method can be 'pattern_matching', 'diffractgpt', or 'both'." + ), "parameters": { "type": "object", "properties": { - "poscar": { + "formula": { "type": "string", - "description": "POSCAR format structure string containing lattice vectors, atom positions, and elements", + "description": "Chemical formula (e.g. 'LaB6', 'Si,Ge')", + }, + "xrd_data": { + "type": "string", + "description": ( + "Two-column XRD data as a string: '2theta intensity\\n...'. " + "One pair per line, space-separated." + ), }, "wavelength": { "type": "number", - "description": "X-ray wavelength in Angstroms. Common values: 1.54184 (Cu K-alpha, default), 1.54056 (Cu K-alpha1), 0.71073 (Mo K-alpha)", + "description": "X-ray wavelength in Å (default: 1.54184)", "default": 1.54184, }, - "num_peaks": { - "type": "integer", - "description": "Number of strongest peaks to report in summary (default: 20)", - "default": 20, + "method": { + "type": "string", + "enum": ["pattern_matching", "diffractgpt", "both"], + "description": "Analysis method (default: 'pattern_matching')", + "default": "pattern_matching", }, - "theta_range": { - "type": "array", - "description": "2-theta range in degrees [min, max]. Default: [0, 90]", - "items": {"type": "number"}, - "minItems": 2, - "maxItems": 2, + }, + "required": ["formula", "xrd_data"], + }, + }, + }, + # ------------------------------------------------------------------------- + # MicroscopyGPT + # ------------------------------------------------------------------------- + { + "type": "function", + "function": { + "name": "microscopygpt_analyze", + "description": ( + "Analyze a microscopy image (STEM/TEM/SEM) using MicroscopyGPT to predict " + "crystal structure, identify defects, or estimate elemental composition. " + "Accepts PNG, JPG, or TIFF images. Returns predicted structure, confidence, " + "and defect information." + ), + "parameters": { + "type": "object", + "properties": { + "image_path": { + "type": "string", + "description": "Local path to the microscopy image file (PNG, JPG, TIFF)", + }, + "formula": { + "type": "string", + "description": "Chemical formula hint to guide prediction (e.g. 'MoS2', 'GaN')", }, }, - "required": ["poscar"], + "required": ["image_path", "formula"], }, }, }, - # Intermat + # ------------------------------------------------------------------------- + # Intermat – heterostructure interface generation + # ------------------------------------------------------------------------- { "type": "function", "function": { "name": "generate_interface", - "description": "Generate heterostructure interface between two materials (film on substrate). Creates interface by matching lattice parameters and stacking specified crystal surfaces.", + "description": ( + "Generate a heterostructure interface between two materials (film on substrate). " + "Creates the interface by matching lattice parameters and stacking the specified " + "crystal surfaces." + ), "parameters": { "type": "object", "properties": { @@ -335,32 +622,35 @@ }, "film_indices": { "type": "string", - "description": "Miller indices for film surface, format: 'h_k_l' with underscores. Common: '0_0_1' (001), '1_1_1' (111), '1_0_0' (100)", + "description": ( + "Miller indices for the film surface, format: 'h_k_l' with underscores. " + "Common: '0_0_1' (001), '1_1_1' (111), '1_0_0' (100)." + ), "default": "0_0_1", }, "substrate_indices": { "type": "string", - "description": "Miller indices for substrate surface, format: 'h_k_l' with underscores", + "description": "Miller indices for the substrate surface, format: 'h_k_l' with underscores.", "default": "0_0_1", }, "film_thickness": { "type": "number", - "description": "Film layer thickness in Angstroms. Typical: 10-30 Å", + "description": "Film layer thickness in Å (default: 16, typical: 10–30)", "default": 16, }, "substrate_thickness": { "type": "number", - "description": "Substrate layer thickness in Angstroms. Typical: 10-30 Å", + "description": "Substrate layer thickness in Å (default: 16, typical: 10–30)", "default": 16, }, "separation": { "type": "number", - "description": "Interface separation distance in Angstroms. Typical: 2.0-3.0 Å", + "description": "Interface separation distance in Å (default: 2.5, typical: 2.0–3.0)", "default": 2.5, }, "max_area": { "type": "number", - "description": "Maximum interface area in Angstroms². Larger values allow more lattice mismatch", + "description": "Maximum interface area in Ų. Larger values allow more lattice mismatch (default: 300).", "default": 300, }, }, @@ -368,4 +658,169 @@ }, }, }, + # ------------------------------------------------------------------------- + # Protein / biology + # ------------------------------------------------------------------------- + { + "type": "function", + "function": { + "name": "protein_fold", + "description": ( + "Predict the 3D structure of a protein from its amino acid sequence using " + "ESMFold AI. Returns a PDB format structure with atomic coordinates. " + "Accepts sequences of 10–400 amino acids." + ), + "parameters": { + "type": "object", + "properties": { + "sequence": { + "type": "string", + "description": ( + "Amino acid sequence in one-letter codes: " + "A R N D C Q E G H I L K M F P S T W Y V. " + "Remove any whitespace or line breaks before passing." + ), + } + }, + "required": ["sequence"], + }, + }, + }, + { + "type": "function", + "function": { + "name": "openfold_predict", + "description": ( + "Predict a protein-DNA complex 3D structure using NVIDIA OpenFold3. " + "Accepts a protein amino acid sequence and two DNA strand sequences " + "(sense and antisense). Returns a PDB format structure of the complex." + ), + "parameters": { + "type": "object", + "properties": { + "protein_sequence": { + "type": "string", + "description": "Protein amino acid sequence in one-letter codes", + }, + "dna1": { + "type": "string", + "description": "First (sense) DNA strand sequence", + }, + "dna2": { + "type": "string", + "description": "Second (antisense / complementary) DNA strand sequence", + }, + }, + "required": ["protein_sequence", "dna1", "dna2"], + }, + }, + }, + # ------------------------------------------------------------------------- + # External databases + # ------------------------------------------------------------------------- + { + "type": "function", + "function": { + "name": "query_mp", + "description": ( + "Fetch crystal structures from the Materials Project via the OPTIMADE API. " + "Returns structures with POSCAR, formation energy, and related properties." + ), + "parameters": { + "type": "object", + "properties": { + "formula": { + "type": "string", + "description": "Reduced chemical formula (e.g. 'MoS2', 'Al2O3')", + }, + "limit": { + "type": "integer", + "description": "Maximum number of results to return (default: 10, max: 500)", + "default": 10, + }, + }, + "required": ["formula"], + }, + }, + }, + { + "type": "function", + "function": { + "name": "query_oqmd", + "description": ( + "Fetch crystal structures from the Open Quantum Materials Database (OQMD) " + "via the OPTIMADE API. Returns structures with POSCAR and energetics." + ), + "parameters": { + "type": "object", + "properties": { + "formula": { + "type": "string", + "description": "Reduced chemical formula (e.g. 'MoS2', 'Fe2O3')", + }, + "limit": { + "type": "integer", + "description": "Maximum number of results to return (default: 10, max: 500)", + "default": 10, + }, + }, + "required": ["formula"], + }, + }, + }, + # ------------------------------------------------------------------------- + # Literature search + # ------------------------------------------------------------------------- + { + "type": "function", + "function": { + "name": "search_arxiv", + "description": ( + "Search arXiv preprints for materials science literature. " + "Returns title, authors, abstract summary, and submission date. " + "Use for recent/preprint research; use search_crossref for published journals." + ), + "parameters": { + "type": "object", + "properties": { + "query": { + "type": "string", + "description": "Search string (e.g. 'GaN bandgap DFT', 'ALIGNN neural network')", + }, + "max_results": { + "type": "integer", + "description": "Number of results to return (default: 10, max: 100)", + "default": 10, + }, + }, + "required": ["query"], + }, + }, + }, + { + "type": "function", + "function": { + "name": "search_crossref", + "description": ( + "Search published journal articles via the Crossref API. " + "Returns title, authors, DOI, journal, and publication date. " + "Use for peer-reviewed literature; use search_arxiv for preprints." + ), + "parameters": { + "type": "object", + "properties": { + "query": { + "type": "string", + "description": "Search string (e.g. 'silicon bandgap experiment')", + }, + "rows": { + "type": "integer", + "description": "Number of results to return (default: 10, max: 100)", + "default": 10, + }, + }, + "required": ["query"], + }, + }, + }, ] diff --git a/agapi/tests/test_agents.py b/agapi/tests/test_agents.pyskip similarity index 100% rename from agapi/tests/test_agents.py rename to agapi/tests/test_agents.pyskip diff --git a/agapi/tests/test_functions.py b/agapi/tests/test_functions.py index 75e555b..c8bac93 100644 --- a/agapi/tests/test_functions.py +++ b/agapi/tests/test_functions.py @@ -14,7 +14,7 @@ from agapi.agents.client import AGAPIClient from agapi.agents.functions import * import pytest - +import time # pytest.skip("Temporarily disabled", allow_module_level=True) # --------------------------------------------------------------------- @@ -71,28 +71,33 @@ def client(): # ===================================================================== def test_query_by_formula(client): + time.sleep(4) r = query_by_formula("Si", client) assert "error" not in r def test_query_by_jid(client): + time.sleep(4) r = query_by_jid("JVASP-1002", client) assert "error" not in r assert isinstance(r.get("POSCAR"), str) def test_query_by_elements(client): + time.sleep(4) r = query_by_elements("Si", client) assert "error" not in r def test_query_by_property(client): + time.sleep(4) r = query_by_property("bandgap", 0.1, 3.0, elements="Si", api_client=client) assert "error" not in r def test_find_extreme(client): + time.sleep(4) r = find_extreme("bulk modulus", True, elements="Si", api_client=client) assert "error" not in r @@ -103,16 +108,19 @@ def test_find_extreme(client): # ===================================================================== def test_alignn_predict(client): + time.sleep(4) r = alignn_predict(jid="JVASP-1002", api_client=client) assert r.get("status") == "success" -def test_alignn_ff_relax(client): - r = alignn_ff_relax(SI_PRIM, api_client=client) - assert r.get("status") == "success" +#def test_alignn_ff_relax(client): +# time.sleep(4) +# r = alignn_ff_relax(SI_PRIM, api_client=client) +# assert r.get("status") == "success" def test_alignn_ff_single_point(client): + time.sleep(4) r = alignn_ff_single_point(SI_PRIM, api_client=client) assert "energy_eV" in r @@ -133,6 +141,7 @@ def test_alignn_ff_md(client): # ===================================================================== def test_slakonet_bandstructure(client): + time.sleep(4) r = slakonet_bandstructure(SI_PRIM, api_client=client) assert r.get("status") == "success" @@ -142,6 +151,7 @@ def test_slakonet_bandstructure(client): # ===================================================================== def test_generate_interface(client): + time.sleep(4) r = generate_interface(SI_PRIM, GAAS_PRIM, api_client=client) assert r.get("status") == "success" @@ -151,21 +161,25 @@ def test_generate_interface(client): # ===================================================================== def test_make_supercell(): + time.sleep(4) r = make_supercell(SI_PRIM, [2, 2, 1]) assert r["supercell_atoms"] > r["original_atoms"] def test_substitute_atom(): + time.sleep(4) r = substitute_atom(GAAS_PRIM, "Ga", "Al", 1) assert "Al" in r["new_formula"] def test_create_vacancy(): + time.sleep(4) r = create_vacancy(GAAS_PRIM, "Ga", 1) assert r["new_atoms"] == r["original_atoms"] - 1 def test_generate_xrd_pattern(): + time.sleep(4) r = generate_xrd_pattern(SI_PRIM) assert r["formula"] == "Si" @@ -175,6 +189,7 @@ def test_generate_xrd_pattern(): # ===================================================================== def test_diffractgpt_predict(client): + time.sleep(4) r = diffractgpt_predict("Si", "28.4(1.0),47.3(0.49)", client) assert isinstance(r, dict) @@ -184,6 +199,7 @@ def test_diffractgpt_predict(client): # ===================================================================== def test_protein_fold_validation(client): + time.sleep(4) r = protein_fold("MKTAY", api_client=client) assert "error" in r @@ -201,11 +217,13 @@ def test_openfold_predict(client): # ===================================================================== def test_pxrd_match(client): + time.sleep(4) r = pxrd_match("Si", SI_XRD, api_client=client) assert isinstance(r, dict) def test_xrd_analyze(client): + time.sleep(4) r = xrd_analyze("Si", SI_XRD, api_client=client) assert isinstance(r, dict) @@ -226,6 +244,7 @@ def test_query_mp(client): """ def test_query_oqmd(client): + time.sleep(4) r = query_oqmd("Si", limit=2, api_client=client) assert isinstance(r, dict) diff --git a/agapi/tests/test_functions_long.py b/agapi/tests/test_functions_long.pyskip similarity index 100% rename from agapi/tests/test_functions_long.py rename to agapi/tests/test_functions_long.pyskip diff --git a/docs/api/agents.md b/docs/api/agents.md new file mode 100644 index 0000000..2096eb8 --- /dev/null +++ b/docs/api/agents.md @@ -0,0 +1,118 @@ +--- +title: AGAPI Agents +--- + +# AGAPI Agents + +The AGAPI Agent uses natural language to orchestrate multi-step materials science workflows. + +## Setup + +```python +import os +from agapi.agents import AGAPIAgent + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +``` + +## Natural Language Queries + +```python +# Simple property lookup +agent.query_sync("What is the bandgap of Silicon?") + +# Database search +agent.query_sync("Show me all MgB2 polymorphs") +agent.query_sync("Find materials with bulk modulus > 200 GPa") + +# Comparisons +agent.query_sync("Compare bandgaps across BN, AlN, GaN, InN") + +# Predictions +agent.query_sync("Predict properties of JVASP-1002 with ALIGNN") + +# Characterization +agent.query_sync("Identify the phase from this XRD pattern for Silicon") +agent.query_sync("Analyze this STEM image of a GaN thin film") + +# Literature +agent.query_sync("Find recent papers on perovskite solar cells on arXiv") +``` + +## Multi-Step Workflows + +The agent chains multiple tools automatically: + +```python +agent.query_sync(""" +1. Find all GaN materials in JARVIS-DFT +2. Get POSCAR for the most stable one +3. Make a 2x1x1 supercell +4. Substitute one Ga with Al +5. Generate powder XRD pattern +6. Optimize structure with ALIGNN-FF +7. Predict properties with ALIGNN +""", max_context_messages=20, verbose=True) +``` + +```python +agent.query_sync(""" +Create a GaN/AlN heterostructure interface: +1. Find GaN (most stable) +2. Find AlN (most stable) +3. Generate (001)/(001) interface +4. Show POSCAR +""", max_context_messages=20, verbose=True) +``` + +## Supported LLM Backends + +Set `model` when initializing the agent: + +```python +agent = AGAPIAgent( + api_key=os.environ.get("AGAPI_KEY"), + model="openai/gpt-oss-20b" +) +``` + +| Provider | Model | +|----------|-------| +| OpenAI | `openai/gpt-oss-20b` | +| OpenAI | `openai/gpt-oss-120b` | +| Meta | `meta/llama-4-maverick-17b-128e-instruct` | +| Meta | `meta/llama-3.2-90b-vision-instruct` | +| Meta | `meta/llama-3.2-1b-instruct` | +| Google | `google/gemini-2.5-flash` | +| Google | `google/gemma-3-27b-it` | +| DeepSeek | `deepseek-ai/deepseek-v3.1` | +| Moonshot | `moonshotai/kimi-k2-instruct-0905` | +| Qwen | `qwen/qwen3-next-80b-a3b-instruct` | + +## Architecture + +AGAPI implements a modular architecture separating the **reasoning layer** (LLM brain) from the **execution layer** (scientific tools and databases) through a unified REST API interface. + +``` +┌──────────────────┐ +│ Natural Language │ ← user prompt +└────────┬─────────┘ + ▼ +┌──────────────────┐ +│ LLM Backend │ ← GPT-OSS / Llama / Gemini / DeepSeek +│ (Reasoning) │ +└────────┬─────────┘ + ▼ +┌──────────────────┐ +│ AGAPI Functions │ ← query_by_formula, alignn_predict, ... +│ (Execution) │ +└────────┬─────────┘ + ▼ +┌──────────────────┐ +│ AtomGPT.org API │ ← JARVIS-DFT, ALIGNN, ALIGNN-FF, ... +│ (Data + Models) │ +└──────────────────┘ +``` + +!!! info "AGAPI Name" + **AGAPI (ἀγάπη)** is a Greek word meaning *unconditional love*. diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 0000000..3c55b6c --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,6 @@ +--- +title: Index +--- + +# API Reference +REST API for all 50+ AtomGPT apps. diff --git a/docs/api/optimade.md b/docs/api/optimade.md new file mode 100644 index 0000000..73b92ce --- /dev/null +++ b/docs/api/optimade.md @@ -0,0 +1,8 @@ +--- +title: Optimade +--- + +# OPTIMADE API +OPTIMADE-standard access. + +Coming soon. diff --git a/docs/api/python-client.md b/docs/api/python-client.md new file mode 100644 index 0000000..3f1e8b3 --- /dev/null +++ b/docs/api/python-client.md @@ -0,0 +1,142 @@ +--- +title: Python Client +--- + +# Python Client + +The `agapi` package provides both direct function calls and a natural language agent interface. + +```bash +pip install agapi jarvis-tools scipy httpx +``` + +## Client Setup + +```python +import os +from agapi.agents.client import AGAPIClient + +client = AGAPIClient(api_key=os.environ.get("AGAPI_KEY")) +``` + +## Available Functions + +### Database Queries + +| Function | Description | Example | +|----------|-------------|---------| +| `query_by_formula(formula, client)` | Search by chemical formula | `query_by_formula("Si", client)` | +| `query_by_jid(jid, client)` | Fetch by JARVIS ID | `query_by_jid("JVASP-1002", client)` | +| `query_by_elements(elements, client)` | Filter by elements | `query_by_elements("Si", client)` | +| `query_by_property(prop, min, max, ...)` | Filter by property range | `query_by_property("bandgap", 0.1, 3.0, elements="Si", api_client=client)` | +| `find_extreme(prop, is_max, ...)` | Find max/min property material | `find_extreme("bulk modulus", True, elements="Si", api_client=client)` | +| `list_jarvis_columns()` | List available properties | `list_jarvis_columns()` | + +### AI Predictions + +| Function | Description | +|----------|-------------| +| `alignn_predict(jid, api_client)` | GNN property prediction (50+ properties) | +| `alignn_ff_relax(poscar, api_client)` | Structure relaxation with ALIGNN-FF | +| `alignn_ff_single_point(poscar, api_client)` | Single-point energy calculation | +| `alignn_ff_optimize(poscar, api_client)` | Geometry optimization | +| `alignn_ff_md(poscar, api_client)` | Molecular dynamics simulation | +| `slakonet_bandstructure(poscar, api_client)` | Tight-binding band structure | + +### Structure Manipulation (Local, No API Key Needed) + +| Function | Description | +|----------|-------------| +| `make_supercell(poscar, dims)` | Build supercell | +| `substitute_atom(poscar, old, new, count)` | Atomic substitution | +| `create_vacancy(poscar, element, count)` | Vacancy creation | +| `generate_xrd_pattern(poscar)` | Simulated powder XRD | +| `generate_interface(poscar1, poscar2, api_client)` | Heterostructure interface | + +### Characterization + +| Function | Description | +|----------|-------------| +| `pxrd_match(formula, xrd_data, api_client)` | Match XRD pattern to structure | +| `xrd_analyze(formula, xrd_data, api_client)` | Analyze XRD data | +| `diffractgpt_predict(formula, peaks, client)` | AI XRD interpretation | +| `microscopygpt_analyze(description, api_client)` | AI STEM/TEM analysis | + +### Literature & External + +| Function | Description | +|----------|-------------| +| `search_arxiv(query, max_results, api_client)` | Search arXiv papers | +| `search_crossref(query, rows, api_client)` | Search Crossref publications | +| `query_mp(formula)` | Query Materials Project | +| `query_oqmd(formula)` | Query OQMD | +| `protein_fold(sequence, api_client)` | Protein structure prediction | +| `openfold_predict(sequence, api_client)` | OpenFold prediction | + +## Common Input Formats + +### POSCAR String + +```python +SI_PRIM = """Si +1.0 +0 2.734 2.734 +2.734 0 2.734 +2.734 2.734 0 +Si +2 +direct +0 0 0 +0.25 0.25 0.25 +""" +``` + +### XRD Data + +```python +SI_XRD = """28.44 1.00 +47.30 0.55 +56.12 0.30 +""" +``` + +## Usage Examples + +### Search → Predict → Relax Pipeline + +```python +from agapi.agents.functions import * + +# 1. Find material +r = query_by_formula("GaN", client) +jid = r["materials"][0]["jid"] + +# 2. Get structure +r = query_by_jid(jid, client) +poscar = r["POSCAR"] + +# 3. Predict properties +r = alignn_predict(jid=jid, api_client=client) + +# 4. Relax with force field +r = alignn_ff_relax(poscar, api_client=client) + +# 5. Generate XRD +r = generate_xrd_pattern(poscar) +``` + +### Structure Manipulation + +```python +# Supercell +r = make_supercell(SI_PRIM, [2, 2, 1]) +print(f"Atoms: {r['original_atoms']} → {r['supercell_atoms']}") + +# Substitution +r = substitute_atom(GAAS_PRIM, "Ga", "Al", 1) +print(f"New formula: {r['new_formula']}") # AlAs + +# Vacancy +r = create_vacancy(GAAS_PRIM, "Ga", 1) +print(f"Atoms: {r['original_atoms']} → {r['new_atoms']}") +``` diff --git a/docs/api/rest-endpoints.md b/docs/api/rest-endpoints.md new file mode 100644 index 0000000..5056bb5 --- /dev/null +++ b/docs/api/rest-endpoints.md @@ -0,0 +1,114 @@ +--- +title: REST Endpoints +--- + +# REST Endpoints + +Every AtomGPT.org web app exposes REST API endpoints. All `POST` endpoints require authentication. + +## Authentication + +``` +Authorization: Bearer YOUR_API_KEY +``` + +Get your key at [AtomGPT.org](https://atomgpt.org) → Account → Settings. + +## Common Patterns + +Every app follows the same URL pattern: + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/{app_name}` | HTML web interface | +| `POST` | `/{app_name}/search` | Search/query | +| `POST` | `/{app_name}/compute` | Run computation | +| `GET` | `/{app_name}/detail/{id}` | Get single item | + +## Key Endpoints + +### Materials Explorer + +``` +POST /materials_explorer/search +``` +```json +{ + "formula": "SrTiO3", + "elements": ["Ti", "O"], + "element_mode": "all", + "bandgap_min": 0.5, + "bandgap_max": 3.0 +} +``` + +### ALIGNN Predictor + +``` +POST /alignn/predict +``` +```json +{"jid": "JVASP-1002", "model": "jv_optb88vdw_bandgap"} +``` + +### ALIGNN-FF + +``` +POST /alignn_ff_dynamics/relax +POST /alignn_ff_dynamics/single_point +POST /alignn_ff_dynamics/md +``` +```json +{"poscar": "Si\n1.0\n0 2.734 2.734\n..."} +``` + +### SlakoNet + +``` +POST /slakonet/compute +``` +```json +{"poscar": "Si\n1.0\n...", "kpath_density": 20} +``` + +### XRD / DiffractGPT + +``` +POST /pxrd/compute +POST /pxrd/match +``` +```json +{"jid": "JVASP-1002"} +{"formula": "Si", "xrd_data": "28.44 1.00\n47.30 0.55"} +``` + +### Structure Tools + +``` +POST /heterostructure/generate +POST /quantum/vqe +POST /reaction_network/balance +POST /hea/compute +``` + +### OPTIMADE + +``` +POST /optimade_explorer/query +``` +```json +{"filter_string": "elements HAS ANY \"Si\",\"Ge\" AND nelements=2"} +``` + +## Rate Limits + +- 100 requests/minute per API key +- Larger queries (bandstructure, MD) may take 10-60 seconds + +## Error Responses + +```json +{"detail": "Error description here"} +``` + +Common HTTP status codes: `401` (unauthorized), `400` (bad request), `404` (not found), `500` (server error). diff --git a/docs/apps/apply/battery.md b/docs/apps/apply/battery.md new file mode 100644 index 0000000..38cc035 --- /dev/null +++ b/docs/apps/apply/battery.md @@ -0,0 +1,61 @@ +--- +title: Battery Explorer +--- + +# Battery Explorer + +Battery cathode voltage profile and theoretical capacity predictor. Supports model selection: default_path or wt01_path. Uses ALIGNN-FF for intercalation energy calculations. + +[:material-open-in-new: Open App](https://atomgpt.org/battery){ .md-button .md-button--primary } + +--- + +## Overview + +Battery cathode voltage profile and theoretical capacity predictor. Supports model selection: default_path or wt01_path. Uses ALIGNN-FF for intercalation energy calculations. + +!!! info "Data Source" + **ALIGNN-FF battery models** + +## Endpoints + +- `GET /battery` +- `POST /battery/predict` + +**Request Models:** `BatteryPredictRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/battery/predict", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show battery explorer for Silicon") +print(response) +``` + +## Reference + +- Comp. Mat. Sci. 259, 114063 (2025) diff --git a/docs/apps/apply/catalysis.md b/docs/apps/apply/catalysis.md new file mode 100644 index 0000000..89622f5 --- /dev/null +++ b/docs/apps/apply/catalysis.md @@ -0,0 +1,61 @@ +--- +title: Catalysis +--- + +# Catalysis + +Predict adsorption energy of a molecule on a substrate using ALIGNN-FF. Input: substrate POSCAR + catalyst (substrate+adsorbate) POSCAR + adsorbate indices. Computes E_ads = E_cat - E_sub - E_mol. + +[:material-open-in-new: Open App](https://atomgpt.org/catalysis){ .md-button .md-button--primary } + +--- + +## Overview + +Predict adsorption energy of a molecule on a substrate using ALIGNN-FF. Input: substrate POSCAR + catalyst (substrate+adsorbate) POSCAR + adsorbate indices. Computes E_ads = E_cat - E_sub - E_mol. + +!!! info "Data Source" + **ALIGNN-FF** + +## Endpoints + +- `GET /catalysis` +- `POST /catalysis/predict` + +**Request Models:** `CatalysisPredictRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/catalysis/predict", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show catalysis for Silicon") +print(response) +``` + +## Reference + +- Comp. Mat. Sci. 259, 114063 (2025) diff --git a/docs/apps/apply/dac.md b/docs/apps/apply/dac.md new file mode 100644 index 0000000..8b08937 --- /dev/null +++ b/docs/apps/apply/dac.md @@ -0,0 +1,61 @@ +--- +title: Direct Air Capture +--- + +# Direct Air Capture + +Direct Air Capture CO₂ Isotherm Predictor using ALIGNN pretrained on hMOF data. Uses alignn.pretrained.get_figshare_model to auto-download the model. + +[:material-open-in-new: Open App](https://atomgpt.org/dac){ .md-button .md-button--primary } + +--- + +## Overview + +Direct Air Capture CO₂ Isotherm Predictor using ALIGNN pretrained on hMOF data. Uses alignn.pretrained.get_figshare_model to auto-download the model. + +!!! info "Data Source" + **ALIGNN hMOF model** + +## Endpoints + +- `GET /dac` +- `POST /dac/predict` + +**Request Models:** `DACPredictRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/dac/predict", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show direct air capture for Silicon") +print(response) +``` + +## Reference + +- Comp. Mat. Sci. 259, 114063 (2025) diff --git a/docs/apps/apply/index.md b/docs/apps/apply/index.md new file mode 100644 index 0000000..1c9e2ac --- /dev/null +++ b/docs/apps/apply/index.md @@ -0,0 +1,6 @@ +--- +title: Index +--- + +# Apply Apps +See sidebar for individual apps. diff --git a/docs/apps/apply/solar.md b/docs/apps/apply/solar.md new file mode 100644 index 0000000..9959287 --- /dev/null +++ b/docs/apps/apply/solar.md @@ -0,0 +1,62 @@ +--- +title: Solar Cell Screening +--- + +# Solar Cell Screening + +Predict theoretical solar cell performance: SLME (spectroscopic limited maximum efficiency) and Shockley-Queisser limit. Uses jarvis.analysis.solarefficiency.solar.SolarEfficiency directly. Input by JID or upload absorption data. + +[:material-open-in-new: Open App](https://atomgpt.org/solar){ .md-button .md-button--primary } + +--- + +## Overview + +Predict theoretical solar cell performance: SLME (spectroscopic limited maximum efficiency) and Shockley-Queisser limit. Uses jarvis.analysis.solarefficiency.solar.SolarEfficiency directly. Input by JID or upload absorption data. + +!!! info "Data Source" + **dft_3d + jarvis.analysis.solarefficiency** + +## Endpoints + +- `GET /solar` +- `POST /solar/predict-jid` +- `POST /solar/predict-data` + +**Request Models:** `SolarJidRequest`, `SolarDataRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/solar/predict-jid", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show solar cell screening for Silicon") +print(response) +``` + +## Reference + +- Comp. Mat. Sci. 259, 114063 (2025) diff --git a/docs/apps/apply/supercon.md b/docs/apps/apply/supercon.md new file mode 100644 index 0000000..c875448 --- /dev/null +++ b/docs/apps/apply/supercon.md @@ -0,0 +1,64 @@ +--- +title: SuperconGPT +--- + +# SuperconGPT + +3 tabs: (1) Inverse design — generate crystal structures for target Tc using AtomGPT, (2) Database search for known superconductors, (3) Predict Tc for any structure with ALIGNN. + +[:material-open-in-new: Open App](https://atomgpt.org/supercon){ .md-button .md-button--primary } + +--- + +## Overview + +3 tabs: (1) Inverse design — generate crystal structures for target Tc using AtomGPT, (2) Database search for known superconductors, (3) Predict Tc for any structure with ALIGNN. + +!!! info "Data Source" + **dft_3d + AtomGPT + ALIGNN supercon model** + +## Endpoints + +- `GET /supercon` +- `POST /supercon/generate` +- `GET /supercon/generate` +- `GET /supercon/search` +- `POST /supercon/predict_tc` + +**Request Models:** `SuperconGenerateRequest`, `SuperconPredictRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/supercon/generate", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show supercongpt for Silicon") +print(response) +``` + +## Reference + +- NPJ Comp. Mat. 8, 244 (2023); J. Phys. Chem. Lett. 15, 6909 (2024) diff --git a/docs/apps/characterize/index.md b/docs/apps/characterize/index.md new file mode 100644 index 0000000..5808a14 --- /dev/null +++ b/docs/apps/characterize/index.md @@ -0,0 +1,6 @@ +--- +title: Index +--- + +# Characterize Apps +See sidebar for individual apps. diff --git a/docs/apps/characterize/microscopy.md b/docs/apps/characterize/microscopy.md new file mode 100644 index 0000000..d79d77d --- /dev/null +++ b/docs/apps/characterize/microscopy.md @@ -0,0 +1,65 @@ +--- +title: MicroscopyGPT +--- + +# MicroscopyGPT + +Microscopy Suite with 3 tabs: (1) STEM Analyzer — proxy to MicroscopyGPT service (port 7000) for atom column detection and classification, (2) STEM Generator — simulate STEM images from crystal structures, (3) STM Image generator. + +[:material-open-in-new: Open App](https://atomgpt.org/microscopy){ .md-button .md-button--primary } + +--- + +## Overview + +Microscopy Suite with 3 tabs: (1) STEM Analyzer — proxy to MicroscopyGPT service (port 7000) for atom column detection and classification, (2) STEM Generator — simulate STEM images from crystal structures, (3) STM Image generator. + +!!! info "Data Source" + **MicroscopyGPT model + jarvis.io.stm** + +## Endpoints + +- `GET /microscopy` +- `GET /microscopy/health` +- `POST /microscopy/predict` +- `POST /microscopy/segment` +- `POST /microscopy/stem_generate` +- `POST /microscopy/stm_image` + +**Request Models:** — + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/microscopy/predict", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show microscopygpt for Silicon") +print(response) +``` + +## Reference + +- J. Chem. Inf. Model 63, 1708 (2023); J. Phys. Chem. Lett. 16, 7028 (2025) diff --git a/docs/apps/characterize/raman.md b/docs/apps/characterize/raman.md new file mode 100644 index 0000000..0c52e20 --- /dev/null +++ b/docs/apps/characterize/raman.md @@ -0,0 +1,62 @@ +--- +title: Raman Matching +--- + +# Raman Matching + +Raman spectrum matching against JARVIS ramandb (~5K materials). User provides freq_cm vs raman_activity data + optional formula. Cosine similarity matching to find best-fit materials. + +[:material-open-in-new: Open App](https://atomgpt.org/raman){ .md-button .md-button--primary } + +--- + +## Overview + +Raman spectrum matching against JARVIS ramandb (~5K materials). User provides freq_cm vs raman_activity data + optional formula. Cosine similarity matching to find best-fit materials. + +!!! info "Data Source" + **ramandb (~5K entries)** + +## Endpoints + +- `GET /raman` +- `POST /raman/lookup` +- `POST /raman/match` + +**Request Models:** `RamanMatchRequest`, `RamanLookupRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/raman/lookup", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show raman matching for Silicon") +print(response) +``` + +## Reference + +- Comp. Mat. Sci. 259, 114063 (2025) diff --git a/docs/apps/characterize/xrd.md b/docs/apps/characterize/xrd.md new file mode 100644 index 0000000..c821d3e --- /dev/null +++ b/docs/apps/characterize/xrd.md @@ -0,0 +1,68 @@ +--- +title: XRD / DiffractGPT +--- + +# XRD / DiffractGPT + +XRD analysis suite: simulate powder XRD patterns from crystal structures, match experimental data to JARVIS-DFT, Rietveld-style refinement, AI-powered peak identification via DiffractGPT, POSCAR to XYZ conversion. + +[:material-open-in-new: Open App](https://atomgpt.org/xrd){ .md-button .md-button--primary } + +--- + +## Overview + +XRD analysis suite: simulate powder XRD patterns from crystal structures, match experimental data to JARVIS-DFT, Rietveld-style refinement, AI-powered peak identification via DiffractGPT, POSCAR to XYZ conversion. + +!!! info "Data Source" + **dft_3d + DiffractGPT model** + +## Endpoints + +- `GET /xrd` +- `POST /xrd/query` +- `GET /pxrd/query` +- `GET /xrd/analyze` +- `POST /xrd/analyze` +- `POST /xrd/analyze_with_refinement` +- `GET /diffractgpt/query` +- `POST /xrd/poscar_to_xyz` +- `POST /xrd/generate` + +**Request Models:** `XRDAnalysisRequest`, `XRDRefinementRequest`, `XRDGenerateRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/xrd/query", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show xrd / diffractgpt for Silicon") +print(response) +``` + +## Reference + +- J. Phys. Chem. Lett. 16, 2110 (2025) diff --git a/docs/apps/explore/convexhull.md b/docs/apps/explore/convexhull.md new file mode 100644 index 0000000..cfbb788 --- /dev/null +++ b/docs/apps/explore/convexhull.md @@ -0,0 +1,61 @@ +--- +title: Convex Hull +--- + +# Convex Hull + +Convex hull phase diagram from JARVIS-DFT formation energies. Supports 2-element (2D plot), 3-element (ternary), and 4+-element (3D) systems. + +[:material-open-in-new: Open App](https://atomgpt.org/convexhull){ .md-button .md-button--primary } + +--- + +## Overview + +Convex hull phase diagram from JARVIS-DFT formation energies. Supports 2-element (2D plot), 3-element (ternary), and 4+-element (3D) systems. + +!!! info "Data Source" + **dft_3d (formation energies)** + +## Endpoints + +- `GET /convexhull` +- `POST /convexhull/compute` + +**Request Models:** `ConvexHullRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/convexhull/compute", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show convex hull for Silicon") +print(response) +``` + +## Reference + +- NPJ Comp. Mat. 6, 173 (2020) diff --git a/docs/apps/explore/dielectric-function.md b/docs/apps/explore/dielectric-function.md new file mode 100644 index 0000000..481d2e1 --- /dev/null +++ b/docs/apps/explore/dielectric-function.md @@ -0,0 +1,62 @@ +--- +title: Dielectric Function +--- + +# Dielectric Function + +Look up and interactively plot the MBJ dielectric function ε(ω) for any JARVIS-DFT material. Supports search by JARVIS ID, chemical formula, space group, and MBJ band gap range. + +[:material-open-in-new: Open App](https://atomgpt.org/dielectric_function){ .md-button .md-button--primary } + +--- + +## Overview + +Look up and interactively plot the MBJ dielectric function ε(ω) for any JARVIS-DFT material. Supports search by JARVIS ID, chemical formula, space group, and MBJ band gap range. + +!!! info "Data Source" + **dft_3d** + +## Endpoints + +- `GET /dielectric_function` +- `POST /dielectric_function/search` +- `GET /dielectric_function/data/{jid}` + +**Request Models:** `DielectricSearchRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/dielectric_function/search", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show dielectric function for Silicon") +print(response) +``` + +## Reference + +- Nature Sci. Data 5, 180082 (2018) diff --git a/docs/apps/explore/efg.md b/docs/apps/explore/efg.md new file mode 100644 index 0000000..4d142c7 --- /dev/null +++ b/docs/apps/explore/efg.md @@ -0,0 +1,62 @@ +--- +title: EFG +--- + +# EFG + +Visualize and compare electric field gradient (EFG) tensors from JARVIS-DFT for NMR/NQR applications. Vzz, asymmetry parameter η, quadrupole coupling constants parsed from JARVIS XML. + +[:material-open-in-new: Open App](https://atomgpt.org/efg){ .md-button .md-button--primary } + +--- + +## Overview + +Visualize and compare electric field gradient (EFG) tensors from JARVIS-DFT for NMR/NQR applications. Vzz, asymmetry parameter η, quadrupole coupling constants parsed from JARVIS XML. + +!!! info "Data Source" + **dft_3d (JARVIS XML)** + +## Endpoints + +- `GET /efg` +- `POST /efg/search` +- `GET /efg/data/{jid}` + +**Request Models:** `EFGSearchRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/efg/search", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show efg for Silicon") +print(response) +``` + +## Reference + +- Nature Sci. Data 7, 362 (2020) diff --git a/docs/apps/explore/elastic-tensor.md b/docs/apps/explore/elastic-tensor.md new file mode 100644 index 0000000..6ed31bc --- /dev/null +++ b/docs/apps/explore/elastic-tensor.md @@ -0,0 +1,62 @@ +--- +title: Elastic Tensor +--- + +# Elastic Tensor + +Visualize and compare the 6×6 elastic stiffness tensor Cij for any JARVIS-DFT material. Search by JARVIS ID, formula, elements, space group, and modulus ranges. Heatmap, matrix, and comparison views. + +[:material-open-in-new: Open App](https://atomgpt.org/elastic_tensor){ .md-button .md-button--primary } + +--- + +## Overview + +Visualize and compare the 6×6 elastic stiffness tensor Cij for any JARVIS-DFT material. Search by JARVIS ID, formula, elements, space group, and modulus ranges. Heatmap, matrix, and comparison views. + +!!! info "Data Source" + **dft_3d** + +## Endpoints + +- `GET /elastic_tensor` +- `POST /elastic_tensor/search` +- `GET /elastic_tensor/data/{jid}` + +**Request Models:** `ElasticSearchRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/elastic_tensor/search", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show elastic tensor for Silicon") +print(response) +``` + +## Reference + +- Phys. Rev. B 98, 014107 (2018) diff --git a/docs/apps/explore/electronic-dos.md b/docs/apps/explore/electronic-dos.md new file mode 100644 index 0000000..f43c961 --- /dev/null +++ b/docs/apps/explore/electronic-dos.md @@ -0,0 +1,62 @@ +--- +title: Electronic DOS +--- + +# Electronic DOS + +Visualize and compare the electronic density of states from JARVIS-DFT. Spin-resolved up/down channels fetched from JARVIS XML pages. + +[:material-open-in-new: Open App](https://atomgpt.org/electronic_dos){ .md-button .md-button--primary } + +--- + +## Overview + +Visualize and compare the electronic density of states from JARVIS-DFT. Spin-resolved up/down channels fetched from JARVIS XML pages. + +!!! info "Data Source" + **dft_3d (JARVIS XML)** + +## Endpoints + +- `GET /electronic_dos` +- `POST /electronic_dos/search` +- `GET /electronic_dos/data/{jid}` + +**Request Models:** `DOSSearchRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/electronic_dos/search", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show electronic dos for Silicon") +print(response) +``` + +## Reference + +- Comp. Mat. Sci. 259, 114063 (2025); JOM 74, 1395 (2022) diff --git a/docs/apps/explore/ff.md b/docs/apps/explore/ff.md new file mode 100644 index 0000000..652e8c0 --- /dev/null +++ b/docs/apps/explore/ff.md @@ -0,0 +1,61 @@ +--- +title: Force Field DB +--- + +# Force Field DB + +JARVIS Force-Field (FF) database search. Search by elements, JID, formula, crystal system, or force-field type (EAM, Tersoff, ReaxFF, etc.). + +[:material-open-in-new: Open App](https://atomgpt.org/ff){ .md-button .md-button--primary } + +--- + +## Overview + +JARVIS Force-Field (FF) database search. Search by elements, JID, formula, crystal system, or force-field type (EAM, Tersoff, ReaxFF, etc.). + +!!! info "Data Source" + **JARVIS-FF** + +## Endpoints + +- `GET /ff` +- `POST /ff/search` + +**Request Models:** `FFSearchRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/ff/search", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show force field db for Silicon") +print(response) +``` + +## Reference + +- J. Phys. Cond. Matt. 30, 395901 (2018) diff --git a/docs/apps/explore/hea.md b/docs/apps/explore/hea.md new file mode 100644 index 0000000..ca468e8 --- /dev/null +++ b/docs/apps/explore/hea.md @@ -0,0 +1,62 @@ +--- +title: HEA Explorer +--- + +# HEA Explorer + +High-Entropy Alloy design tool. Compute thermodynamic parameters (ΔS_mix, δ, VEC, Ω), predict phases (FCC/BCC/mixed), Hume-Rothery checks, and screen JARVIS-DFT for matching compositions. + +[:material-open-in-new: Open App](https://atomgpt.org/hea){ .md-button .md-button--primary } + +--- + +## Overview + +High-Entropy Alloy design tool. Compute thermodynamic parameters (ΔS_mix, δ, VEC, Ω), predict phases (FCC/BCC/mixed), Hume-Rothery checks, and screen JARVIS-DFT for matching compositions. + +!!! info "Data Source" + **dft_3d + built-in element property database** + +## Endpoints + +- `GET /hea` +- `POST /hea/compute` +- `POST /hea/screen` + +**Request Models:** `HEAComputeRequest`, `HEAScreenRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/hea/compute", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show hea explorer for Silicon") +print(response) +``` + +## Reference + +- Mater. Today 19, 349 (2016) diff --git a/docs/apps/explore/index.md b/docs/apps/explore/index.md new file mode 100644 index 0000000..f662461 --- /dev/null +++ b/docs/apps/explore/index.md @@ -0,0 +1,32 @@ +--- +title: Explore Apps +--- + +# Explore Apps + +Browse databases, search materials, and visualize properties from JARVIS-DFT and other sources. + +| App | Description | Data Source | +|-----|-------------|-------------| +| [Materials Explorer](materials-explorer.md) | Search 76K+ materials by formula, elements, properties | dft_3d | +| [Electronic DOS](electronic-dos.md) | Spin-resolved density of states | dft_3d | +| [Phonon DOS](phonon-dos.md) | Vibrational spectra from DFPT | dft_3d | +| [Dielectric Function](dielectric-function.md) | Frequency-dependent optical properties | dft_3d | +| [Elastic Tensor](elastic-tensor.md) | 6×6 stiffness tensor, moduli | dft_3d | +| [Thermoelectric](thermoelectric.md) | Seebeck, conductivity, power factor | dft_3d | +| [EFG](efg.md) | Electric field gradients | dft_3d | +| [Piezoelectric](piezoelectric.md) | DFPT stress tensors, IR intensities | dft_3d | +| [IR Spectra](ir.md) | Infrared spectra | dft_3d | +| [Spillage](spillage.md) | Topological spin-orbit spillage | dft_3d | +| [Vacancy Explorer](vacancy.md) | 464 vacancy defect structures | vacancydb | +| [Surface Explorer](surface.md) | 607 surface slabs with work functions | surfacedb | +| [Interface Explorer](interface.md) | Heterostructure interfaces | interfacedb | +| [2D Materials](twod.md) | ~1.1K monolayers | dft_2d | +| [Polymer Explorer](polymer.md) | ~690 crystalline polymers | polymer_genome + dft_3d | +| [Force Field DB](ff.md) | Classical force field benchmarks | JARVIS-FF | +| [Periodic Table](periodic-table.md) | Interactive heatmap with JARVIS properties | dft_3d | +| [HEA Explorer](hea.md) | High-entropy alloy design & screening | dft_3d | +| [Reaction Network](reaction-network.md) | Balance equations, compute ΔH, network graphs | dft_3d | +| [PDB Explorer](pdb-explorer.md) | 200K+ protein structures from RCSB | RCSB PDB | +| [OPTIMADE Explorer](optimade.md) | OPTIMADE-standard queries on JARVIS-DFT | dft_3d | +| [Convex Hull](convexhull.md) | Thermodynamic stability phase diagrams | dft_3d | diff --git a/docs/apps/explore/interface.md b/docs/apps/explore/interface.md new file mode 100644 index 0000000..d4efd5a --- /dev/null +++ b/docs/apps/explore/interface.md @@ -0,0 +1,62 @@ +--- +title: Interface Explorer +--- + +# Interface Explorer + +Browse, search, and visualize heterostructure interface properties from the JARVIS interface database (607 entries). Band alignments and interface energies. + +[:material-open-in-new: Open App](https://atomgpt.org/interface_db){ .md-button .md-button--primary } + +--- + +## Overview + +Browse, search, and visualize heterostructure interface properties from the JARVIS interface database (607 entries). Band alignments and interface energies. + +!!! info "Data Source" + **interfacedb (607 entries)** + +## Endpoints + +- `GET /interface_db` +- `POST /interface/search` +- `GET /interface/data/{idx}` + +**Request Models:** `InterfaceSearchRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/interface/search", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show interface explorer for Silicon") +print(response) +``` + +## Reference + +- Phys. Rev. Mat. 7, 014009 (2023) diff --git a/docs/apps/explore/ir.md b/docs/apps/explore/ir.md new file mode 100644 index 0000000..8952d85 --- /dev/null +++ b/docs/apps/explore/ir.md @@ -0,0 +1,62 @@ +--- +title: IR Spectra +--- + +# IR Spectra + +Visualize and compare infrared spectra from JARVIS-DFT DFPT calculations. Born effective charges and phonon frequencies parsed from JARVIS XML. + +[:material-open-in-new: Open App](https://atomgpt.org/ir){ .md-button .md-button--primary } + +--- + +## Overview + +Visualize and compare infrared spectra from JARVIS-DFT DFPT calculations. Born effective charges and phonon frequencies parsed from JARVIS XML. + +!!! info "Data Source" + **dft_3d (DFPT, JARVIS XML)** + +## Endpoints + +- `GET /ir` +- `POST /ir/search` +- `GET /ir/data/{jid}` + +**Request Models:** `IRSearchRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/ir/search", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show ir spectra for Silicon") +print(response) +``` + +## Reference + +- NPJ Comp. Mat. 6, 1 (2020) diff --git a/docs/apps/explore/materials-explorer.md b/docs/apps/explore/materials-explorer.md new file mode 100644 index 0000000..a9a0af5 --- /dev/null +++ b/docs/apps/explore/materials-explorer.md @@ -0,0 +1,188 @@ +--- +title: Materials Explorer +description: Search and explore 76K+ materials in JARVIS-DFT +tags: + - explore + - database + - search +--- + +# Materials Explorer + +Search and explore **76,000+ materials** in the JARVIS-DFT database. Filter by formula, elements, space group, band gap, formation energy, and 50+ properties. + +[:material-open-in-new: Open App](https://atomgpt.org/materials_explorer){ .md-button .md-button--primary } +[:material-github: Source](https://github.com/atomgptlab/jarvis){ .md-button } + +--- + +## Overview + +The Materials Explorer provides full-text search across the JARVIS-DFT database with filters for chemical composition, crystal structure, electronic properties, and more. Each material links to its detailed JARVIS data page. + +!!! info "Data Source" + **JARVIS-DFT** (`dft_3d`) — 76,000+ materials computed with OptB88vdW functional. + Updated from `jarvis.db.figshare.data('dft_3d')`. + +## Quick Start + +1. Enter a formula (e.g., `SrTiO3`) or elements (e.g., `Si, Ge`) +2. Apply filters for band gap range, formation energy, or space group +3. Click **Search** to find matching materials +4. Click any result row to view detailed properties +5. Click the JARVIS ID to open the full XML data page + +## Features + +- **Search by formula**: Exact or partial formula matching +- **Element filter**: ANY/ALL/EXACT mode with interactive periodic table +- **Property filters**: Band gap, formation energy, bulk/shear modulus, magnetic moment, spillage, SLME, and more +- **Results table**: Sortable by any property, paginated +- **Detail view**: Full property card with JARVIS XML link + +## API Reference + +### Search Materials + +``` +POST /materials_explorer/search +``` + +**Request Body:** + +```json +{ + "jid": "JVASP-1002", + "formula": "Si", + "spacegroup": "Fd-3m", + "elements": ["Si", "Ge"], + "element_mode": "any", + "bandgap_min": 0.5, + "bandgap_max": 3.0, + "formation_energy_min": -2.0, + "formation_energy_max": 0.0 +} +``` + +**Response:** + +```json +{ + "total": 1234, + "results": [ + { + "jid": "JVASP-1002", + "formula": "Si", + "spg_symbol": "Fd-3m", + "optb88vdw_bandgap": 0.611, + "formation_energy_peratom": -0.005, + "bulk_modulus_kv": 88.89, + "shear_modulus_gv": 51.47, + "magmom_oszicar": 0.0 + } + ] +} +``` + +!!! note "Authentication" + All POST endpoints require authentication. Include your token in the header: + ``` + Authorization: Bearer YOUR_TOKEN + ``` + +### Get Material Details + +``` +GET /materials_explorer/detail/{jid} +``` + +Returns full property set for a single material. + +## Python Examples + +=== "Search by formula" + + ```python + import requests + + response = requests.post( + "https://atomgpt.org/materials_explorer/search", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"formula": "SrTiO3"}, + ) + data = response.json() + print(f"Found {data['total']} materials") + for m in data["results"][:5]: + print(f" {m['jid']}: {m['formula']} gap={m['optb88vdw_bandgap']} eV") + ``` + +=== "Search by elements" + + ```python + import requests + + response = requests.post( + "https://atomgpt.org/materials_explorer/search", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={ + "elements": ["Ti", "O"], + "element_mode": "all", + "bandgap_min": 1.0, + }, + ) + data = response.json() + for m in data["results"][:10]: + print(f"{m['jid']}: {m['formula']} ({m['spg_symbol']}) gap={m['optb88vdw_bandgap']}") + ``` + +=== "AGAPI Agent" + + ```python + from agapi import AtomGPTClient + + client = AtomGPTClient(api_key="YOUR_KEY") + results = client.search_materials( + elements=["Si", "Ge"], + bandgap_min=0.5, + bandgap_max=2.0, + ) + for m in results: + print(m.formula, m.bandgap) + ``` + +=== "Direct JARVIS" + + ```python + from jarvis.db.figshare import data + + dft = data("dft_3d") + # Filter for Si-containing materials with gap > 1 eV + results = [ + e for e in dft + if "Si" in e.get("atoms", {}).get("elements", []) + and e.get("optb88vdw_bandgap") not in (None, "na") + and float(e["optb88vdw_bandgap"]) > 1.0 + ] + print(f"Found {len(results)} Si materials with gap > 1 eV") + ``` + +## Related Apps + +- [Electronic DOS](electronic-dos.md) — View density of states for any material +- [Elastic Tensor](elastic-tensor.md) — Explore mechanical properties +- [Periodic Table](periodic-table.md) — Heatmap of properties across elements +- [OPTIMADE Explorer](optimade.md) — Query using OPTIMADE standard syntax + +## References + +- K. Choudhary, Comp. Mat. Sci. 259, 114063 (2025). [:material-link: DOI](https://doi.org/10.1016/j.commatsci.2025.114063) +- K. Choudhary et al., npj Comp. Mat. 6, 173 (2020). [:material-link: DOI](https://doi.org/10.1038/s41524-020-00440-1) +- JARVIS-DFT Database: [jarvis.nist.gov](https://jarvis.nist.gov) diff --git a/docs/apps/explore/optimade.md b/docs/apps/explore/optimade.md new file mode 100644 index 0000000..da604cb --- /dev/null +++ b/docs/apps/explore/optimade.md @@ -0,0 +1,62 @@ +--- +title: OPTIMADE Explorer +--- + +# OPTIMADE Explorer + +Query JARVIS-DFT using OPTIMADE-style filters served directly from the dft_3d dataset (no external API calls). Supports elements HAS ANY/ALL/ONLY, formula, nelements, nsites, and numeric property filters. + +[:material-open-in-new: Open App](https://atomgpt.org/optimade_explorer){ .md-button .md-button--primary } + +--- + +## Overview + +Query JARVIS-DFT using OPTIMADE-style filters served directly from the dft_3d dataset (no external API calls). Supports elements HAS ANY/ALL/ONLY, formula, nelements, nsites, and numeric property filters. + +!!! info "Data Source" + **dft_3d (in-memory OPTIMADE filter engine)** + +## Endpoints + +- `GET /optimade_explorer` +- `POST /optimade_explorer/query` +- `GET /optimade_explorer/entry/{jid}` + +**Request Models:** `OptimadeQueryRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/optimade_explorer/query", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show optimade explorer for Silicon") +print(response) +``` + +## Reference + +- NPJ Comp. Mat. 6, 173 (2020) diff --git a/docs/apps/explore/pdb-explorer.md b/docs/apps/explore/pdb-explorer.md new file mode 100644 index 0000000..6210e06 --- /dev/null +++ b/docs/apps/explore/pdb-explorer.md @@ -0,0 +1,62 @@ +--- +title: PDB Explorer +--- + +# PDB Explorer + +Search 200K+ protein structures from RCSB PDB. 3D Mol* viewer (RCSB embed iframe), sequence display with position markers, unit cell and crystallographic data, polymer entities. Uses RCSB REST API (no key needed). + +[:material-open-in-new: Open App](https://atomgpt.org/pdb_explorer){ .md-button .md-button--primary } + +--- + +## Overview + +Search 200K+ protein structures from RCSB PDB. 3D Mol* viewer (RCSB embed iframe), sequence display with position markers, unit cell and crystallographic data, polymer entities. Uses RCSB REST API (no key needed). + +!!! info "Data Source" + **RCSB PDB REST API** + +## Endpoints + +- `GET /pdb_explorer` +- `POST /pdb_explorer/search` +- `GET /pdb_explorer/entry/{pdb_id}` + +**Request Models:** `PDBSearchRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/pdb_explorer/search", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show pdb explorer for Silicon") +print(response) +``` + +## Reference + +- Nucleic Acids Res. 28, 235 (2000) diff --git a/docs/apps/explore/periodic-table.md b/docs/apps/explore/periodic-table.md new file mode 100644 index 0000000..7d5b797 --- /dev/null +++ b/docs/apps/explore/periodic-table.md @@ -0,0 +1,59 @@ +--- +title: Periodic Table +--- + +# Periodic Table + +Interactive periodic table with JARVIS property overlays. Backend provides per-element property statistics aggregated from JARVIS-DFT 3D (76K materials). Fully client-side visualization. + +[:material-open-in-new: Open App](https://atomgpt.org/periodic_table){ .md-button .md-button--primary } + +--- + +## Overview + +Interactive periodic table with JARVIS property overlays. Backend provides per-element property statistics aggregated from JARVIS-DFT 3D (76K materials). Fully client-side visualization. + +!!! info "Data Source" + **dft_3d (aggregated per-element stats)** + +## Endpoints + +- `GET /periodic_table` +- `GET /periodic_table/stats` + +**Request Models:** — + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.get( + "https://atomgpt.org/periodic_table/stats", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + }, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show periodic table for Silicon") +print(response) +``` + +## Reference + +- Comp. Mat. Sci. 259, 114063 (2025) diff --git a/docs/apps/explore/phonon-dos.md b/docs/apps/explore/phonon-dos.md new file mode 100644 index 0000000..50cff8d --- /dev/null +++ b/docs/apps/explore/phonon-dos.md @@ -0,0 +1,62 @@ +--- +title: Phonon DOS +--- + +# Phonon DOS + +Visualize and compare phonon density of states from JARVIS-DFT. Vibrational spectra fetched from JARVIS XML pages. + +[:material-open-in-new: Open App](https://atomgpt.org/phonon_dos){ .md-button .md-button--primary } + +--- + +## Overview + +Visualize and compare phonon density of states from JARVIS-DFT. Vibrational spectra fetched from JARVIS XML pages. + +!!! info "Data Source" + **dft_3d (JARVIS XML)** + +## Endpoints + +- `GET /phonon_dos` +- `POST /phonon_dos/search` +- `GET /phonon_dos/data/{jid}` + +**Request Models:** `PhononDOSSearchRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/phonon_dos/search", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show phonon dos for Silicon") +print(response) +``` + +## Reference + +- Phys. Rev. Mat. 7, 023803 (2023) diff --git a/docs/apps/explore/piezoelectric.md b/docs/apps/explore/piezoelectric.md new file mode 100644 index 0000000..30af31d --- /dev/null +++ b/docs/apps/explore/piezoelectric.md @@ -0,0 +1,62 @@ +--- +title: Piezoelectric +--- + +# Piezoelectric + +Visualize and compare DFPT piezoelectric stress tensors eij (C/m²) and IR intensities from JARVIS-DFT calculations. + +[:material-open-in-new: Open App](https://atomgpt.org/piezoelectric){ .md-button .md-button--primary } + +--- + +## Overview + +Visualize and compare DFPT piezoelectric stress tensors eij (C/m²) and IR intensities from JARVIS-DFT calculations. + +!!! info "Data Source" + **dft_3d (DFPT)** + +## Endpoints + +- `GET /piezoelectric` +- `POST /piezoelectric/search` +- `GET /piezoelectric/data/{jid}` + +**Request Models:** `PiezoSearchRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/piezoelectric/search", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show piezoelectric for Silicon") +print(response) +``` + +## Reference + +- NPJ Comp. Mat. 6, 1 (2020) diff --git a/docs/apps/explore/polymer.md b/docs/apps/explore/polymer.md new file mode 100644 index 0000000..abd4e47 --- /dev/null +++ b/docs/apps/explore/polymer.md @@ -0,0 +1,62 @@ +--- +title: Polymer Explorer +--- + +# Polymer Explorer + +Browse, search, and visualize crystalline polymer properties by cross-referencing Polymer Genome database (1073 entries) with JARVIS-DFT. Dielectrics, band gaps, formation energies. + +[:material-open-in-new: Open App](https://atomgpt.org/polymer){ .md-button .md-button--primary } + +--- + +## Overview + +Browse, search, and visualize crystalline polymer properties by cross-referencing Polymer Genome database (1073 entries) with JARVIS-DFT. Dielectrics, band gaps, formation energies. + +!!! info "Data Source" + **polymer_genome (1073 entries) + dft_3d** + +## Endpoints + +- `GET /polymer` +- `POST /polymer/search` +- `GET /polymer/data/{jid}` + +**Request Models:** `PolymerSearchRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/polymer/search", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show polymer explorer for Silicon") +print(response) +``` + +## Reference + +- Sci. Data 3, 160012 (2016) diff --git a/docs/apps/explore/reaction-network.md b/docs/apps/explore/reaction-network.md new file mode 100644 index 0000000..94037d4 --- /dev/null +++ b/docs/apps/explore/reaction-network.md @@ -0,0 +1,63 @@ +--- +title: Reaction Network +--- + +# Reaction Network + +Balance chemical equations (SVD null-space), compute reaction thermodynamics ΔH from JARVIS-DFT formation energies, and build interactive d3.js bipartite reaction network graphs. + +[:material-open-in-new: Open App](https://atomgpt.org/reaction_network){ .md-button .md-button--primary } + +--- + +## Overview + +Balance chemical equations (SVD null-space), compute reaction thermodynamics ΔH from JARVIS-DFT formation energies, and build interactive d3.js bipartite reaction network graphs. + +!!! info "Data Source" + **dft_3d (formation energies)** + +## Endpoints + +- `GET /reaction_network` +- `POST /reaction_network/balance` +- `POST /reaction_network/thermodynamics` +- `POST /reaction_network/network` + +**Request Models:** `BalanceRequest`, `ThermodynamicsRequest`, `NetworkRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/reaction_network/balance", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"equation": "Fe2O3 + C -> Fe + CO2"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show reaction network for Silicon") +print(response) +``` + +## Reference + +- NPJ Comp. Mat. 6, 173 (2020) diff --git a/docs/apps/explore/spillage.md b/docs/apps/explore/spillage.md new file mode 100644 index 0000000..33bec8d --- /dev/null +++ b/docs/apps/explore/spillage.md @@ -0,0 +1,62 @@ +--- +title: Spillage +--- + +# Spillage + +Visualize and compare SOC spillage data from JARVIS-DFT for identifying topological insulators and semimetals. Data parsed from JARVIS XML. + +[:material-open-in-new: Open App](https://atomgpt.org/spillage){ .md-button .md-button--primary } + +--- + +## Overview + +Visualize and compare SOC spillage data from JARVIS-DFT for identifying topological insulators and semimetals. Data parsed from JARVIS XML. + +!!! info "Data Source" + **dft_3d (JARVIS XML)** + +## Endpoints + +- `GET /spillage` +- `POST /spillage/search` +- `GET /spillage/data/{jid}` + +**Request Models:** `SpillageSearchRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/spillage/search", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show spillage for Silicon") +print(response) +``` + +## Reference + +- Sci. Rep. 9, 8534 (2019) diff --git a/docs/apps/explore/surface.md b/docs/apps/explore/surface.md new file mode 100644 index 0000000..20b14ac --- /dev/null +++ b/docs/apps/explore/surface.md @@ -0,0 +1,62 @@ +--- +title: Surface Explorer +--- + +# Surface Explorer + +Browse, search, and visualize surface properties from the JARVIS surface database (607 entries). Work functions, surface energies, and cleavage energies. + +[:material-open-in-new: Open App](https://atomgpt.org/surface){ .md-button .md-button--primary } + +--- + +## Overview + +Browse, search, and visualize surface properties from the JARVIS surface database (607 entries). Work functions, surface energies, and cleavage energies. + +!!! info "Data Source" + **surfacedb (607 entries)** + +## Endpoints + +- `GET /surface` +- `POST /surface/search` +- `GET /surface/data/{idx}` + +**Request Models:** `SurfaceSearchRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/surface/search", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show surface explorer for Silicon") +print(response) +``` + +## Reference + +- Digital Discovery (2024) diff --git a/docs/apps/explore/thermoelectric.md b/docs/apps/explore/thermoelectric.md new file mode 100644 index 0000000..74ac17e --- /dev/null +++ b/docs/apps/explore/thermoelectric.md @@ -0,0 +1,62 @@ +--- +title: Thermoelectric +--- + +# Thermoelectric + +Visualize and compare thermoelectric (BoltzTrap) data from JARVIS-DFT. Seebeck coefficient, electrical conductivity, and power factor parsed from JARVIS XML pages. + +[:material-open-in-new: Open App](https://atomgpt.org/thermoelectric){ .md-button .md-button--primary } + +--- + +## Overview + +Visualize and compare thermoelectric (BoltzTrap) data from JARVIS-DFT. Seebeck coefficient, electrical conductivity, and power factor parsed from JARVIS XML pages. + +!!! info "Data Source" + **dft_3d (JARVIS XML)** + +## Endpoints + +- `GET /thermoelectric` +- `POST /thermoelectric/search` +- `GET /thermoelectric/data/{jid}` + +**Request Models:** `ThermoelectricSearchRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/thermoelectric/search", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show thermoelectric for Silicon") +print(response) +``` + +## Reference + +- J. Phys. Cond. Matt. 32, 475501 (2020) diff --git a/docs/apps/explore/twod.md b/docs/apps/explore/twod.md new file mode 100644 index 0000000..0d6f7a2 --- /dev/null +++ b/docs/apps/explore/twod.md @@ -0,0 +1,62 @@ +--- +title: 2D Materials +--- + +# 2D Materials + +Browse, search, and visualize properties of 2D materials from the JARVIS-DFT 2D dataset (~1.1K monolayers). Exfoliation energies, band gaps, magnetic properties. + +[:material-open-in-new: Open App](https://atomgpt.org/twod){ .md-button .md-button--primary } + +--- + +## Overview + +Browse, search, and visualize properties of 2D materials from the JARVIS-DFT 2D dataset (~1.1K monolayers). Exfoliation energies, band gaps, magnetic properties. + +!!! info "Data Source" + **dft_2d (~1.1K entries)** + +## Endpoints + +- `GET /twod` +- `POST /twod/search` +- `GET /twod/data/{jid}` + +**Request Models:** `TwoDSearchRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/twod/search", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show 2d materials for Silicon") +print(response) +``` + +## Reference + +- Sci. Rep. 7, 5179 (2017) diff --git a/docs/apps/explore/vacancy.md b/docs/apps/explore/vacancy.md new file mode 100644 index 0000000..7e450bf --- /dev/null +++ b/docs/apps/explore/vacancy.md @@ -0,0 +1,62 @@ +--- +title: Vacancy Explorer +--- + +# Vacancy Explorer + +Browse, search, and visualize vacancy formation energies from the JARVIS vacancy database (464 entries). Dataset loaded from jarvis.db.figshare.data('vacancydb'). + +[:material-open-in-new: Open App](https://atomgpt.org/vacancy){ .md-button .md-button--primary } + +--- + +## Overview + +Browse, search, and visualize vacancy formation energies from the JARVIS vacancy database (464 entries). Dataset loaded from jarvis.db.figshare.data('vacancydb'). + +!!! info "Data Source" + **vacancydb (464 entries)** + +## Endpoints + +- `GET /vacancy` +- `POST /vacancy/search` +- `GET /vacancy/data/{defect_id}` + +**Request Models:** `VacancySearchRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/vacancy/search", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show vacancy explorer for Silicon") +print(response) +``` + +## Reference + +- AIP Advances 13(9) (2023) diff --git a/docs/apps/index.md b/docs/apps/index.md new file mode 100644 index 0000000..36e6863 --- /dev/null +++ b/docs/apps/index.md @@ -0,0 +1,38 @@ +--- +title: Apps Overview +description: All 50+ AtomGPT web applications organized by category +--- + +# Apps Overview + +AtomGPT.org hosts **50+ web applications** for materials science. Each app provides a web interface, REST API endpoints, and Python examples for agentic workflows. + +## Categories + +| Category | Apps | Description | +|----------|------|-------------| +| [**Explore**](explore/) | 22 | Browse databases, search materials, visualize properties | +| [**Build**](build/) | 4 | Construct structures, design workflows, write code | +| [**Predict**](predict/) | 6 | ML predictions, force fields, quantum algorithms | +| [**Characterize**](characterize/) | 3 | Match spectra, analyze images, identify structures | +| [**Apply**](apply/) | 5 | Screen materials for specific applications | +| [**Validate**](validate/) | 2 | Verify AI outputs, check references | + +## Architecture + +Every app follows the same pattern: + +``` +┌─────────────┐ ┌──────────────┐ ┌─────────────┐ +│ HTML/JS │────▶│ FastAPI │────▶│ JARVIS │ +│ Frontend │◀────│ Backend │◀────│ Data/ML │ +└─────────────┘ └──────────────┘ └─────────────┘ + │ │ + ▼ ▼ + Web Browser REST API + (for agents/scripts) +``` + +- **Frontend**: Single HTML file with embedded CSS/JS, dark theme +- **Backend**: FastAPI route with authentication, served from `custom_routes/` +- **Data**: JARVIS-DFT (76K materials), ALIGNN models, Wannier TBH databases diff --git a/docs/apps/predict/alignn-ff.md b/docs/apps/predict/alignn-ff.md new file mode 100644 index 0000000..51804a1 --- /dev/null +++ b/docs/apps/predict/alignn-ff.md @@ -0,0 +1,66 @@ +--- +title: ALIGNN-FF Dynamics +--- + +# ALIGNN-FF Dynamics + +Universal ML force field. Structure relaxation (BFGS), geometry optimization, NVT/NPT molecular dynamics, and phonon calculations — all via ALIGNN-FF. Supports model selection (default or wt01). + +[:material-open-in-new: Open App](https://atomgpt.org/alignn_ff_dynamics){ .md-button .md-button--primary } + +--- + +## Overview + +Universal ML force field. Structure relaxation (BFGS), geometry optimization, NVT/NPT molecular dynamics, and phonon calculations — all via ALIGNN-FF. Supports model selection (default or wt01). + +!!! info "Data Source" + **ALIGNN-FF pretrained model** + +## Endpoints + +- `GET /alignn_ff_dynamics` +- `GET /alignn_ff/query` +- `POST /alignn_ff/query` +- `GET /alignn_ff/relax` +- `POST /alignn_ff/optimize` +- `POST /alignn_ff/md` +- `POST /alignn_ff/phonons` + +**Request Models:** `OptimizationRequest`, `MDRequest`, `PhononRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/alignn_ff/query", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show alignn-ff dynamics for Silicon") +print(response) +``` + +## Reference + +- Digital Discovery 2(2), 346 (2023) diff --git a/docs/apps/predict/alignn.md b/docs/apps/predict/alignn.md new file mode 100644 index 0000000..bfc41dd --- /dev/null +++ b/docs/apps/predict/alignn.md @@ -0,0 +1,63 @@ +--- +title: ALIGNN Predictor +--- + +# ALIGNN Predictor + +Predict 50+ materials properties with ALIGNN graph neural networks. Query by JARVIS ID or upload POSCAR. Web prediction endpoint returns all available model predictions. + +[:material-open-in-new: Open App](https://atomgpt.org/alignn){ .md-button .md-button--primary } + +--- + +## Overview + +Predict 50+ materials properties with ALIGNN graph neural networks. Query by JARVIS ID or upload POSCAR. Web prediction endpoint returns all available model predictions. + +!!! info "Data Source" + **ALIGNN pretrained models** + +## Endpoints + +- `GET /alignn` +- `GET /alignn/query` +- `POST /alignn/query` +- `POST /alignn/web_predict` + +**Request Models:** — + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/alignn/query", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show alignn predictor for Silicon") +print(response) +``` + +## Reference + +- NPJ Comp. Mat. 7, 1 (2021) diff --git a/docs/apps/predict/index.md b/docs/apps/predict/index.md new file mode 100644 index 0000000..b5db632 --- /dev/null +++ b/docs/apps/predict/index.md @@ -0,0 +1,6 @@ +--- +title: Index +--- + +# Predict Apps +See sidebar for individual apps. diff --git a/docs/apps/predict/protein-fold.md b/docs/apps/predict/protein-fold.md new file mode 100644 index 0000000..0e834af --- /dev/null +++ b/docs/apps/predict/protein-fold.md @@ -0,0 +1,64 @@ +--- +title: Protein Fold +--- + +# Protein Fold + +Protein structure prediction using ESMFold/OpenFold. Paste amino acid sequence, get 3D structure with pLDDT confidence. Web endpoint for interactive folding. + +[:material-open-in-new: Open App](https://atomgpt.org/protein_fold){ .md-button .md-button--primary } + +--- + +## Overview + +Protein structure prediction using ESMFold/OpenFold. Paste amino acid sequence, get 3D structure with pLDDT confidence. Web endpoint for interactive folding. + +!!! info "Data Source" + **ESMFold / OpenFold models** + +## Endpoints + +- `GET /protein_fold` +- `GET /protein_fold/query` +- `POST /protein_fold/query` +- `POST /protein_fold/predict` +- `GET /openfold/query` + +**Request Models:** `ProteinFoldRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/protein_fold/query", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show protein fold for Silicon") +print(response) +``` + +## Reference + +- Science (2023) diff --git a/docs/apps/predict/quantum.md b/docs/apps/predict/quantum.md new file mode 100644 index 0000000..15d2f9c --- /dev/null +++ b/docs/apps/predict/quantum.md @@ -0,0 +1,63 @@ +--- +title: Quantum Computation +--- + +# Quantum Computation + +Run Qiskit VQE/VQD on Wannier tight-binding Hamiltonians from JARVIS-DFT using statevector simulator. EfficientSU2 (circuit6) ansatz. Full bandstructure via JARVIS get_bandstruct. + +[:material-open-in-new: Open App](https://atomgpt.org/quantum){ .md-button .md-button--primary } + +--- + +## Overview + +Run Qiskit VQE/VQD on Wannier tight-binding Hamiltonians from JARVIS-DFT using statevector simulator. EfficientSU2 (circuit6) ansatz. Full bandstructure via JARVIS get_bandstruct. + +!!! info "Data Source" + **JARVIS-WTB + Qiskit** + +## Endpoints + +- `GET /quantum` +- `GET /quantum/materials` +- `POST /quantum/vqe` +- `POST /quantum/bandstructure` + +**Request Models:** `VQERequest`, `BandstructureRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/quantum/vqe", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-816", "kpoint": [0.5, 0.0, 0.5], "ham_type": "electron", "reps": 2}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show quantum computation for Silicon") +print(response) +``` + +## Reference + +- J. Phys.: Condens. Matter 33, 385501 (2021) diff --git a/docs/apps/predict/slakonet.md b/docs/apps/predict/slakonet.md new file mode 100644 index 0000000..5e683db --- /dev/null +++ b/docs/apps/predict/slakonet.md @@ -0,0 +1,63 @@ +--- +title: SlakoNet Bands +--- + +# SlakoNet Bands + +Deep learning tight-binding band structures from neural network Slater-Koster parameters. Query by JARVIS ID or upload POSCAR. Web analyze endpoint returns band structure + DOS. + +[:material-open-in-new: Open App](https://atomgpt.org/slakonet){ .md-button .md-button--primary } + +--- + +## Overview + +Deep learning tight-binding band structures from neural network Slater-Koster parameters. Query by JARVIS ID or upload POSCAR. Web analyze endpoint returns band structure + DOS. + +!!! info "Data Source" + **SlakoNet pretrained model** + +## Endpoints + +- `GET /slakonet` +- `GET /slakonet/bandstructure` +- `POST /slakonet/bandstructure` +- `POST /slakonet/web_analyze` + +**Request Models:** — + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/slakonet/bandstructure", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show slakonet bands for Silicon") +print(response) +``` + +## Reference + +- J. Phys. Chem. Lett. 16, 11109 (2025) diff --git a/docs/apps/predict/wtb.md b/docs/apps/predict/wtb.md new file mode 100644 index 0000000..f63a9ff --- /dev/null +++ b/docs/apps/predict/wtb.md @@ -0,0 +1,62 @@ +--- +title: Wannier TB Bands +--- + +# Wannier TB Bands + +Wannier tight-binding Hamiltonian bandstructure and DOS. Selects material by JID from JARVIS-WTB database, downloads wannier90_hr.dat, computes band structure and DOS. + +[:material-open-in-new: Open App](https://atomgpt.org/wtb){ .md-button .md-button--primary } + +--- + +## Overview + +Wannier tight-binding Hamiltonian bandstructure and DOS. Selects material by JID from JARVIS-WTB database, downloads wannier90_hr.dat, computes band structure and DOS. + +!!! info "Data Source" + **JARVIS-WTB (wannier90_hr.dat files)** + +## Endpoints + +- `GET /wtb` +- `GET /wtb/options` +- `POST /wtb/predict` + +**Request Models:** `WtbPredictRequest` + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/wtb/predict", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show wannier tb bands for Silicon") +print(response) +``` + +## Reference + +- Sci. Data 8, 106 (2021) diff --git a/docs/apps/validate/ai-detector.md b/docs/apps/validate/ai-detector.md new file mode 100644 index 0000000..f261c5d --- /dev/null +++ b/docs/apps/validate/ai-detector.md @@ -0,0 +1,61 @@ +--- +title: AI Detector +--- + +# AI Detector + +AI-generated text detector. Hybrid approach: statistical analysis (perplexity, burstiness, entropy variance, sentence length) + LLM judge. Scans text and returns confidence scores. + +[:material-open-in-new: Open App](https://atomgpt.org/ai_detector){ .md-button .md-button--primary } + +--- + +## Overview + +AI-generated text detector. Hybrid approach: statistical analysis (perplexity, burstiness, entropy variance, sentence length) + LLM judge. Scans text and returns confidence scores. + +!!! info "Data Source" + **Statistical analysis + LLM judge** + +## Endpoints + +- `GET /ai_detector` +- `POST /ai_detector/scan` + +**Request Models:** — + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/ai_detector/scan", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"text": "Sample text to analyze"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show ai detector for Silicon") +print(response) +``` + +## Reference + +- — diff --git a/docs/apps/validate/hallucination.md b/docs/apps/validate/hallucination.md new file mode 100644 index 0000000..debe97f --- /dev/null +++ b/docs/apps/validate/hallucination.md @@ -0,0 +1,62 @@ +--- +title: Hallucination Detector +--- + +# Hallucination Detector + +Verify LLM outputs against JARVIS data. Cross-check predicted properties and material claims with the DFT database. Streaming check endpoint for real-time verification. + +[:material-open-in-new: Open App](https://atomgpt.org/hallucination_detector){ .md-button .md-button--primary } + +--- + +## Overview + +Verify LLM outputs against JARVIS data. Cross-check predicted properties and material claims with the DFT database. Streaming check endpoint for real-time verification. + +!!! info "Data Source" + **dft_3d + LLM verification** + +## Endpoints + +- `GET /hallucination_detector` +- `GET /detector` +- `POST /hallucination/check_stream` + +**Request Models:** — + +!!! note "Authentication" + All POST endpoints require `Authorization: Bearer YOUR_TOKEN`. + +## API Example + +```python +import requests + +response = requests.post( + "https://atomgpt.org/hallucination/check_stream", + headers={ + "Authorization": "Bearer sk-XYZ", + "accept": "application/json", + "Content-Type": "application/json", + }, + json={"jid": "JVASP-1002"}, +) +data = response.json() +print(data) +``` + +## AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Show hallucination detector for Silicon") +print(response) +``` + +## Reference + +- — diff --git a/docs/apps/validate/index.md b/docs/apps/validate/index.md new file mode 100644 index 0000000..5d9484d --- /dev/null +++ b/docs/apps/validate/index.md @@ -0,0 +1,6 @@ +--- +title: Index +--- + +# Validate Apps +See sidebar for individual apps. diff --git a/docs/assets/favicon.png b/docs/assets/favicon.png new file mode 100644 index 0000000..902a2a5 Binary files /dev/null and b/docs/assets/favicon.png differ diff --git a/docs/assets/logo.png b/docs/assets/logo.png new file mode 100644 index 0000000..902a2a5 Binary files /dev/null and b/docs/assets/logo.png differ diff --git a/docs/contributing/app-template.md b/docs/contributing/app-template.md new file mode 100644 index 0000000..2ea3795 --- /dev/null +++ b/docs/contributing/app-template.md @@ -0,0 +1,6 @@ +--- +title: App Template +--- + +# App Template +Coming soon. diff --git a/docs/contributing/index.md b/docs/contributing/index.md new file mode 100644 index 0000000..5adb522 --- /dev/null +++ b/docs/contributing/index.md @@ -0,0 +1,6 @@ +--- +title: Index +--- + +# Contributing +How to add apps to AtomGPT.org. diff --git a/docs/contributing/plugin-system.md b/docs/contributing/plugin-system.md new file mode 100644 index 0000000..40c4d7c --- /dev/null +++ b/docs/contributing/plugin-system.md @@ -0,0 +1,6 @@ +--- +title: Plugin System +--- + +# Plugin System +Coming soon. diff --git a/docs/contributing/style-guide.md b/docs/contributing/style-guide.md new file mode 100644 index 0000000..a629e00 --- /dev/null +++ b/docs/contributing/style-guide.md @@ -0,0 +1,6 @@ +--- +title: Style Guide +--- + +# Style Guide +Coming soon. diff --git a/docs/getting-started/api-overview.md b/docs/getting-started/api-overview.md new file mode 100644 index 0000000..586208d --- /dev/null +++ b/docs/getting-started/api-overview.md @@ -0,0 +1,10 @@ +--- +title: Api Overview +--- + +# API Overview + +Every app exposes: +- `GET /{app}` — HTML page +- `POST /{app}/search` — Query +- `GET /{app}/detail/{id}` — Detail diff --git a/docs/getting-started/authentication.md b/docs/getting-started/authentication.md new file mode 100644 index 0000000..7d99a5d --- /dev/null +++ b/docs/getting-started/authentication.md @@ -0,0 +1,6 @@ +--- +title: Authentication +--- + +# Authentication +All endpoints require `Authorization: Bearer YOUR_TOKEN`. diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md new file mode 100644 index 0000000..2018a12 --- /dev/null +++ b/docs/getting-started/index.md @@ -0,0 +1,9 @@ +--- +title: Index +--- + +# Getting Started + +- [Quick Start](quickstart.md) +- [Authentication](authentication.md) +- [API Overview](api-overview.md) diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md new file mode 100644 index 0000000..2f82b08 --- /dev/null +++ b/docs/getting-started/quickstart.md @@ -0,0 +1,68 @@ +--- +title: Quick Start +--- + +# Quick Start + +Get started with AtomGPT.org in 2 minutes. + +## 1. Install + +```bash +pip install agapi jarvis-tools scipy httpx +``` + +## 2. Get Your API Key + +Sign up at [AtomGPT.org](https://atomgpt.org) → Account → Settings: + +```bash +export AGAPI_KEY="sk-your-key-here" +``` + +## 3. Direct API Calls + +```python +import os +from agapi.agents.client import AGAPIClient +from agapi.agents.functions import * + +client = AGAPIClient(api_key=os.environ.get("AGAPI_KEY")) +result = query_by_formula("Si", client) +print(result["materials"][25]["formula"], result["materials"][25]["mbj_bandgap"]) +``` + +## 4. Natural Language Agent + +```python +from agapi.agents import AGAPIAgent + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("What is the bandgap of Silicon?") +print(response) +``` + +## 5. Multi-Step Workflows + +```python +agent.query_sync(""" +1. Find all GaN materials in JARVIS-DFT +2. Get POSCAR for the most stable one +3. Make a 2x1x1 supercell +4. Substitute one Ga with Al +5. Generate powder XRD pattern +6. Optimize structure with ALIGNN-FF +7. Predict properties with ALIGNN +""", max_context_messages=20, verbose=True) +``` + +## 6. Browse Web Apps + +Visit [atomgpt.org/apps](https://atomgpt.org/apps) for 50+ interactive apps — no code needed. + +## Next Steps + +- [Authentication](authentication.md) — API key details +- [Python Client](../api/python-client.md) — All functions +- [AGAPI Agents](../api/agents.md) — LLM agent setup +- [Tutorials](../tutorials/) — Step-by-step guides diff --git a/docs/index.md b/docs/index.md index 17bd5e2..5da1956 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,444 +1,109 @@ -# 🌐 AtomGPT.org API (AGAPI): Agentic AI for Materials Science - -[![Open in Google Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/knc6/jarvis-tools-notebooks/blob/master/jarvis-tools-notebooks/agapi_example.ipynb) -[![PyPI](https://img.shields.io/pypi/v/agapi)](https://pypi.org/project/agapi/) -[![License](https://img.shields.io/badge/license-Apache-blue)](LICENSE) - -Empower your materials science research with AtomGPT's Agentic AI API (**AGAPI**). AGAPI removes complex software setups, commercial API cost allowing you to perform advanced predictions, analyses, and explorations through natural language or Python, accelerating materials discovery and design. AGAPI implements a modular architecture separating the reasoning layer (LLM brain) from the execution layer (scientific tools and databases as hands) through a unified REST API interface. This design follows established principles of agentic AI systems. - - - -## 🚀 Quickstart - -**1. Get your API key** — sign up at [AtomGPT.org](https://atomgpt.org) → Account → Settings, then: - -```bash -pip install agapi jarvis-tools scipy httpx -export AGAPI_KEY="sk-your-key-here" -``` - -**2. Initialize client and agent:** - -```python -import os -from agapi.agents.client import AGAPIClient -from agapi.agents import AGAPIAgent -from agapi.agents.functions import * -from jarvis.io.vasp.inputs import Poscar - -# Direct function calls (API client) -client = AGAPIClient(api_key=os.environ.get("AGAPI_KEY")) -result = query_by_formula("Si", client) -print(result["materials"][25]["formula"], result["materials"][25]["mbj_bandgap"]) - -# Natural language queries (AI agent) -agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) -response = agent.query_sync("What is the bandgap of Silicon?") -print(response) -``` - ---- - -## ✨ Key Capabilities - -### Common Inputs - -```python -SI_PRIM = """Si -1.0 -0 2.734 2.734 -2.734 0 2.734 -2.734 2.734 0 -Si -2 -direct -0 0 0 -0.25 0.25 0.25 -""" - -GAAS_PRIM = """GaAs -1.0 -0 2.875 2.875 -2.875 0 2.875 -2.875 2.875 0 -Ga As -1 1 -direct -0 0 0 -0.25 0.25 0.25 -""" - -SI_XRD = """28.44 1.00 -47.30 0.55 -56.12 0.30 -""" -``` - ---- - -### 1. Materials API Query -Access JARVIS-DFT and more. - -**API Example:** -```python -from agapi.agents.functions import ( - query_by_formula, - query_by_jid, - query_by_elements, - query_by_property, - find_extreme, - alignn_predict, - alignn_ff_relax, - slakonet_bandstructure, - generate_interface, - make_supercell, - substitute_atom, - create_vacancy, - generate_xrd_pattern, - protein_fold, - diffractgpt_predict, - alignn_ff_single_point, - alignn_ff_optimize, - alignn_ff_md, - pxrd_match, - xrd_analyze, - microscopygpt_analyze, - query_mp, - query_oqmd, - search_arxiv, - search_crossref, - openfold_predict, - list_jarvis_columns, -) - -r = query_by_formula("Si", client) -assert "error" not in r - -r = query_by_jid("JVASP-1002", client) -assert isinstance(r.get("POSCAR"), str) - -r = query_by_elements("Si", client) -assert "error" not in r - -r = query_by_property("bandgap", 0.1, 3.0, elements="Si", api_client=client) -assert "error" not in r - -r = find_extreme("bulk modulus", True, elements="Si", api_client=client) -assert "error" not in r -``` - -**Natural Language Example:** -```python -agent.query_sync("Show me all MgB2 polymorphs") -agent.query_sync("What's the Tc_Supercon for MgB2 and what's the JARVIS-ID for it?") -agent.query_sync("What's the stiffest Si,O material?") -agent.query_sync("Find materials with bulk modulus > 200 GPa") -agent.query_sync("Compare bandgaps across BN, AlN, GaN, InN") -agent.query_sync("What are the formation energies of SiC, AlN, MgO?") -``` - ---- - -### 2. AI Property Prediction (ALIGNN) -Predict bandgap, formation energy, elastic moduli, and more using graph neural networks. - -**API Example:** -```python -from agapi.agents.functions import alignn_predict - -r = alignn_predict(jid="JVASP-1002", api_client=client) -assert r.get("status") == "success" -``` - -**Natural Language Example:** -```python -agent.query_sync("Predict properties of JARVIS-ID JVASP-1002 with ALIGNN") -agent.query_sync(f"Predict properties using ALIGNN for this structure:\n\n{SI_PRIM}") -``` - --- - -### 3. AI Force Field (ALIGNN-FF) -Structure relaxation, single-point energy, and MD with near-DFT accuracy. - -**API Example:** -```python -from agapi.agents.functions import alignn_ff_relax, alignn_ff_single_point - -r = alignn_ff_relax(SI_PRIM, api_client=client) -assert r.get("status") == "success" -print(Poscar.from_string(r["relaxed_poscar"])) # view relaxed structure - -r = alignn_ff_single_point(SI_PRIM, api_client=client) -assert "energy_eV" in r -``` - -**Natural Language Example:** -```python -agent.query_sync(f"Optimize structure with ALIGNN-FF:\n\n{SI_PRIM}") -agent.query_sync("Get the single-point energy of this Si primitive cell.") -``` - ---- - -### 4. Band Structure (SlakoNet) -Tight-binding band structures from neural network Slater-Koster parameters. - -**API Example:** -```python -from agapi.agents.functions import slakonet_bandstructure - -r = slakonet_bandstructure(SI_PRIM, api_client=client) -assert r.get("status") == "success" -``` - -**Natural Language Example:** -```python -agent.query_sync("Compute the band structure of Si.") -agent.query_sync(f"Plot the electronic band structure for this POSCAR:\n\n{SI_PRIM}") -``` - +title: AtomGPT.org API (AGAPI) Documentation +description: 50+ web apps for materials science, AI, and quantum computation --- -### 5. XRD / DiffractGPT -Match PXRD patterns, identify phases, and analyze experimental diffraction data. +# AtomGPT.org API(AGAPI) Documentation -**API Example:** -```python -from agapi.agents.functions import pxrd_match, xrd_analyze, diffractgpt_predict +Welcome to the documentation for [AtomGPT.org](https://atomgpt.org) API - a comprehensive platform with **50+ web applications** for materials science, powered by the JARVIS ecosystem. -r = pxrd_match("Si", SI_XRD, api_client=client) -assert isinstance(r, dict) -if "matched_poscar" in r: - print(Poscar.from_string(r["matched_poscar"])) # view matched structure +
-r = xrd_analyze("Si", SI_XRD, api_client=client) -assert isinstance(r, dict) +- :material-magnify: **Explore** -r = diffractgpt_predict("Si", "28.4(1.0),47.3(0.49)", client) -assert isinstance(r, dict) -``` + --- -**Natural Language Example:** -```python -agent.query_sync("Identify the phase from this XRD pattern for Silicon: [XRD data]") -agent.query_sync("Analyze this PXRD pattern and suggest possible structures.") -``` + Browse 76K+ materials, proteins, polymers, surfaces, and more from JARVIS-DFT and other databases. ---- + [:octicons-arrow-right-24: Explore Apps](apps/explore/) -### 6. STEM / MicroscopyGPT -Analyze STEM, TEM, and electron microscopy images using AI — identify atomic columns, measure lattice spacings, detect defects, and interpret microstructure. +- :material-wrench: **Build** -**API Example:** -```python -from agapi.agents.functions import microscopygpt_analyze + --- -r = microscopygpt_analyze("HRTEM image of Si lattice", api_client=client) -assert isinstance(r, dict) -``` + Visualize structures, build heterostructures, design workflows, and write AI-assisted code. -**Natural Language Example:** -```python -agent.query_sync("Analyze this STEM image of a GaN thin film: [image]") -agent.query_sync("What defects are visible in this HRTEM image?") -agent.query_sync("Measure the d-spacing from this electron diffraction pattern.") -``` + [:octicons-arrow-right-24: Build Apps](apps/build/) +- :material-chart-line: **Predict** + --- ---- + ALIGNN, SlakoNet, ALIGNN-FF, AtomGPT — predict properties with GNNs, MLFF, TB, and quantum algorithms. -### 7. Structure Manipulation -Supercells, substitutions, vacancies, and XRD pattern generation — runs locally, no API call needed. + [:octicons-arrow-right-24: Predict Apps](apps/predict/) -**API Example:** -```python -from agapi.agents.functions import make_supercell, substitute_atom, create_vacancy, generate_xrd_pattern +- :material-flask: **Characterize** -r = make_supercell(SI_PRIM, [2, 2, 1]) -assert r["supercell_atoms"] > r["original_atoms"] -print(f"Original atoms: {r['original_atoms']}, Supercell atoms: {r['supercell_atoms']}") -# Expected: Original atoms: 2, Supercell atoms: 8 + --- -r = substitute_atom(GAAS_PRIM, "Ga", "Al", 1) -assert "Al" in r["new_formula"] -# Expected new_formula: AlAs + Match XRD patterns with DiffractGPT, analyze Raman spectra, identify structures from microscopy images. -r = create_vacancy(GAAS_PRIM, "Ga", 1) -assert r["new_atoms"] == r["original_atoms"] - 1 -# Expected: one fewer atom than original + [:octicons-arrow-right-24: Characterize Apps](apps/characterize/) -r = generate_xrd_pattern(SI_PRIM) -assert r["formula"] == "Si" -``` +- :material-atom: **Apply** -**Natural Language Example:** -```python -agent.query_sync("Make a 2x1x1 supercell of the most stable GaN.") -agent.query_sync("Substitute one Ga with Al in this GaAs structure.") -agent.query_sync("Create a Ga vacancy in GaAs and predict its properties.") -``` + --- ---- + Screen superconductors, solar cells, batteries, catalysts, and DAC materials. -### 8. Interface Generation -Build heterostructure interfaces between two materials. + [:octicons-arrow-right-24: Apply Apps](apps/apply/) -**API Example:** -```python -from agapi.agents.functions import generate_interface +- :material-check-circle: **Validate** -r = generate_interface(SI_PRIM, GAAS_PRIM, api_client=client) -assert r.get("status") == "success" -``` + --- -**Natural Language Example:** -```python -agent.query_sync(""" - Create a GaN/AlN heterostructure interface: - 1. Find GaN (most stable) - 2. Find AlN (most stable) - 3. Generate (001)/(001) interface - 4. Show POSCAR -""", max_context_messages=20) -``` - ---- + Detect AI-generated text, check for hallucinations, verify references. -### 9. Literature Search -Search arXiv and Crossref for relevant research papers. + [:octicons-arrow-right-24: Validate Apps](apps/validate/) -**API Example:** -```python -from agapi.agents.functions import search_arxiv, search_crossref +
-r = search_arxiv("GaN", max_results=2, api_client=client) -assert isinstance(r, dict) +## Quick Links -r = search_crossref("GaN", rows=2, api_client=client) -assert isinstance(r, dict) -``` - -**Natural Language Example:** -```python -agent.query_sync("Find recent papers on perovskite solar cells on arXiv.") -agent.query_sync("Search for publications about ALIGNN neural networks.") -``` +| Resource | Link | +|----------|------| +| :material-web: **AtomGPT.org** | [atomgpt.org](https://atomgpt.org) | +| :material-github: **GitHub** | [github.com/atomgptlab](https://github.com/atomgptlab) | +| :material-api: **API** | [API Reference](api/) | +| :material-school: **Tutorials** | [Tutorials](tutorials/) | ---- - -## 🔧 Multi-Step Agentic Workflow - -```python -agent.query_sync(""" -1. Find all GaN materials in the JARVIS-DFT database -2. Get the POSCAR for the most stable one -3. Make a 2x1x1 supercell -4. Substitute one Ga with Al -5. Generate powder XRD pattern -6. Optimize structure with ALIGNN-FF -7. Predict properties with ALIGNN -""", max_context_messages=20, verbose=True) - -agent.query_sync(""" -Create a GaN/AlN heterostructure interface: -1. Find GaN (most stable) -2. Find AlN (most stable) -3. Generate (001)/(001) interface -4. Show POSCAR -""", max_context_messages=20, verbose=True) -``` - ---- +## Citation -## 🤖 Supported LLM Backends +If you use AtomGPT.org in your research, please cite: -AGAPI supports multiple LLM backends. Set `model` when initializing the agent: +```bibtex +@article{lee2025agapi, + title={AGAPI-Agents: An Open-Access Agentic AI Platform for Accelerated Materials Design on AtomGPT. org}, + author={Lee, Jaehyung and Ely, Justin and Zhang, Kent and Ajith, Akshaya and Campbell, Charles Rhys and Choudhary, Kamal}, + journal={arXiv preprint arXiv:2512.11935}, + year={2025} +} +@article{choudhary2025chatgpt, + title={Chatgpt material explorer: Design and implementation of a custom gpt assistant for materials science applications}, + author={Choudhary, Kamal}, + journal={Integrating Materials and Manufacturing Innovation}, + volume={14}, + number={3}, + pages={276--283}, + year={2025}, + publisher={Springer} +} +@article{choudhary2025jarvis, + title={The JARVIS infrastructure is all you need for materials design}, + author={Choudhary, Kamal}, + journal={Computational Materials Science}, + volume={259}, + pages={114063}, + year={2025} +} -```python -agent = AGAPIAgent( - api_key=os.environ.get("AGAPI_KEY"), - model="openai/gpt-oss-20b" -) +@article{choudhary2020jarvis, + title={The joint automated repository for various integrated simulations (JARVIS)}, + author={Choudhary, Kamal and others}, + journal={npj Computational Materials}, + volume={6}, + pages={173}, + year={2020} +} ``` - -Available models: - -| Provider | Model | -|---|---| -| OpenAI | `openai/gpt-oss-20b` | -| OpenAI | `openai/gpt-oss-120b` | -| Meta | `meta/llama-4-maverick-17b-128e-instruct` | -| Meta | `meta/llama-3.2-90b-vision-instruct` | -| Meta | `meta/llama-3.2-1b-instruct` | -| Google | `google/gemini-2.5-flash` | -| Google | `google/gemma-3-27b-it` | -| DeepSeek | `deepseek-ai/deepseek-v3.1` | -| Moonshot | `moonshotai/kimi-k2-instruct-0905` | -| Qwen | `qwen/qwen3-next-80b-a3b-instruct` | - - ---- - -## 📦 Available APIs/Functions - -| Function | Description | -|---|---| -| `query_by_formula` | Search by chemical formula | -| `query_by_jid` | Fetch by JARVIS ID | -| `query_by_elements` | Filter by constituent elements | -| `query_by_property` | Filter by property range | -| `find_extreme` | Find max/min property material | -| `alignn_predict` | GNN property prediction | -| `alignn_ff_relax` | Structure relaxation | -| `alignn_ff_single_point` | Single-point energy | -| `slakonet_bandstructure` | TB band structure | -| `generate_interface` | Heterostructure builder | -| `make_supercell` | Supercell generation | -| `substitute_atom` | Atomic substitution | -| `create_vacancy` | Vacancy creation | -| `generate_xrd_pattern` | Simulated XRD | -| `pxrd_match / xrd_analyze` | XRD phase matching | -| `diffractgpt_predict` | AI XRD interpretation | -| `microscopygpt_analyze` | AI STEM/TEM image analysis | -| `query_mp` | Materials Project query | -| `search_arxiv / search_crossref` | Literature search | -| `protein_fold` | Protein structure prediction | - -... ---- - -## 📖 References - -If you find this work helpful, please cite: - -1. **AGAPI-Agents: An Open-Access Agentic AI Platform for Accelerated Materials Design on AtomGPT.org** - https://doi.org/10.48550/arXiv.2512.11935 - -2. **ChatGPT Material Explorer: Design and Implementation of a Custom GPT Assistant for Materials Science Applications** - https://doi.org/10.1016/j.commatsci.2025.114063 - -3. **The JARVIS Infrastructure Is All You Need for Materials Design** - https://doi.org/10.1016/j.commatsci.2025.114063 - -📄 Full publication list: [Google Scholar](https://scholar.google.com/citations?hl=en&user=YVP36YgAAAAJ&view_op=list_works&sortby=pubdate) - ---- - -## 📚 Resources - -- 🔬 **Research Group**: [AtomGPTLab @ JHU](https://choudhary.wse.jhu.edu/) -- 📖 **Docs**: [AtomGPT.org/docs](https://atomgpt.org/docs) -- 🧪 **Colab**: [AGAPI Example Notebook](https://colab.research.google.com/github/knc6/jarvis-tools-notebooks/blob/master/jarvis-tools-notebooks/agapi_example.ipynb) -- ▶️ **YouTube**: [Demo Playlist](https://www.youtube.com/playlist?list=PLjf6vHVv7AoInTVQmfNSMs_12DBXYCcDd) - ---- - -## ❤️ Note - -**AGAPI (ἀγάπη)** is a Greek word meaning *unconditional love*. - -## Disclaimer - -AtomGPT.org can make mistakes — please verify critical results. We hope this API fosters open, collaborative, and accelerated discovery in materials science. diff --git a/docs/references/changelog.md b/docs/references/changelog.md new file mode 100644 index 0000000..55a3689 --- /dev/null +++ b/docs/references/changelog.md @@ -0,0 +1,6 @@ +--- +title: Changelog +--- + +# Changelog +Coming soon. diff --git a/docs/references/index.md b/docs/references/index.md new file mode 100644 index 0000000..875da87 --- /dev/null +++ b/docs/references/index.md @@ -0,0 +1,6 @@ +--- +title: Index +--- + +# References +Publications and changelog. diff --git a/docs/references/publications.md b/docs/references/publications.md new file mode 100644 index 0000000..f2162b9 --- /dev/null +++ b/docs/references/publications.md @@ -0,0 +1,7 @@ +--- +title: Publications +--- + +# Publications + +See [Google Scholar](https://scholar.google.com/citations?user=klhV2BIAAAAJ&hl=en) for the full list. diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..bceefd4 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,32 @@ +/* AtomGPT custom styles for MkDocs Material */ + +/* Cards grid */ +.md-typeset .grid.cards > ul > li { + border: 1px solid var(--md-default-fg-color--lightest); + border-radius: 8px; + padding: 16px; + transition: border-color 0.2s, box-shadow 0.2s; +} +.md-typeset .grid.cards > ul > li:hover { + border-color: var(--md-accent-fg-color); + box-shadow: 0 4px 12px rgba(0,0,0,0.1); +} + +/* App page buttons */ +.md-typeset .md-button { + margin-right: 8px; + margin-bottom: 8px; +} + +/* Code blocks */ +.md-typeset pre > code { + font-size: 13px; +} + +/* API endpoint headers */ +.md-typeset h3 code { + font-size: 0.9em; + padding: 2px 8px; + background: var(--md-code-bg-color); + border-radius: 4px; +} diff --git a/docs/tutorials/alignn-ff-md.md b/docs/tutorials/alignn-ff-md.md new file mode 100644 index 0000000..3d1973e --- /dev/null +++ b/docs/tutorials/alignn-ff-md.md @@ -0,0 +1,89 @@ +--- +title: ALIGNN-FF Molecular Dynamics +--- + +# ALIGNN-FF Molecular Dynamics + +Run molecular dynamics with near-DFT accuracy using the ALIGNN-FF universal force field. + +## Install + +```bash +pip install alignn jarvis-tools ase +``` + +## Single-Point Energy + +```python +from alignn.ff.ff import AlignnAtomwiseCalculator, default_path +from jarvis.core.atoms import Atoms +from jarvis.db.figshare import get_jid_data +import numpy as np + +calc = AlignnAtomwiseCalculator(path=default_path()) + +atoms = Atoms.from_dict(get_jid_data("JVASP-1002", "dft_3d")["atoms"]) +ase_atoms = atoms.ase_converter() +ase_atoms.calc = calc + +energy = ase_atoms.get_potential_energy() +forces = ase_atoms.get_forces() +print(f"Energy: {energy:.4f} eV") +print(f"Max force: {np.max(np.abs(forces)):.4f} eV/Ang") +``` + +## Structure Relaxation + +```python +from ase.optimize import BFGS + +opt = BFGS(ase_atoms) +opt.run(fmax=0.01) +print(f"Relaxed energy: {ase_atoms.get_potential_energy():.4f} eV") +``` + +## Molecular Dynamics (NVT) + +```python +from ase.md.langevin import Langevin +from ase import units + +dyn = Langevin(ase_atoms, 1.0 * units.fs, temperature_K=300, friction=0.02) + +def print_status(): + T = ase_atoms.get_temperature() + E = ase_atoms.get_potential_energy() + print(f"Step: T={T:.1f}K E={E:.4f}eV") + +dyn.attach(print_status, interval=10) +dyn.run(200) +``` + +## Via AGAPI + +```python +from agapi.agents.functions import alignn_ff_relax, alignn_ff_single_point +import os +from agapi.agents.client import AGAPIClient + +client = AGAPIClient(api_key=os.environ.get("AGAPI_KEY")) + +SI_PRIM = """Si +1.0 +0 2.734 2.734 +2.734 0 2.734 +2.734 2.734 0 +Si +2 +direct +0 0 0 +0.25 0.25 0.25 +""" + +r = alignn_ff_relax(SI_PRIM, api_client=client) +print(r) +``` + +## Reference + +K. Choudhary, Digital Discovery 2(2), 346 (2023) — [DOI](https://doi.org/10.1039/D2DD00096B) diff --git a/docs/tutorials/custom-apps.md b/docs/tutorials/custom-apps.md new file mode 100644 index 0000000..d69b7f0 --- /dev/null +++ b/docs/tutorials/custom-apps.md @@ -0,0 +1,81 @@ +--- +title: Building Custom Apps +--- + +# Building Custom Apps for AtomGPT.org + +Add your own web application to the AtomGPT.org platform using the plugin system. + +## Architecture + +Every app has two files: + +``` +custom_routes/my_app.py # FastAPI backend +custom_templates/my_app.html # HTML frontend +``` + +## 1. Create the Backend + +```python +# custom_routes/my_app.py + +from fastapi import APIRouter, Depends, HTTPException, Request +from fastapi.responses import HTMLResponse +from pydantic import BaseModel + +from open_webui.utils.auth import get_current_user +from .shared import templates + +router = APIRouter(tags=["MyCategory"]) + +class MyRequest(BaseModel): + input_data: str + +@router.get("/my_app", response_class=HTMLResponse) +async def my_app_home(request: Request): + return templates.TemplateResponse("my_app.html", {"request": request}) + +@router.post("/my_app/compute") +async def my_app_compute( + request: MyRequest, + user=Depends(get_current_user), +): + if not user: + raise HTTPException(status_code=401, detail="Unauthorized") + # Your computation here + return {"result": f"Processed: {request.input_data}"} +``` + +## 2. Create the Frontend + +Use the dark theme template matching other AtomGPT apps. + +## 3. Register in custom.py + +```python +from .custom_routes import my_app +metered.include_router(my_app.router) +``` + +## 4. Add to apps.html + +```javascript +{name:"My App", desc:"Description here", + icon:"icon", href:"/my_app", cat:"explore", + status:"new", accent:"#4da6ff", + bg:"rgba(77,166,255,0.08)", + tag:"Tag1 · Tag2"} +``` + +## Plugin System + +For external contributors, use the plugin system: + +1. Fork the [template repo](https://github.com/atomgptlab/atomgpt-app-template) +2. Edit `manifest.json`, `app.py`, `template.html` +3. Submit PR to community-apps repo + +## Reference + +See the AtomGPT.org developer guide for details. diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md new file mode 100644 index 0000000..e1010e4 --- /dev/null +++ b/docs/tutorials/index.md @@ -0,0 +1,18 @@ +--- +title: Tutorials +--- + +# Tutorials + +Step-by-step guides for common materials science workflows using AtomGPT.org and the AGAPI Python client. + +| Tutorial | Description | Time | +|----------|-------------|------| +| [Getting Started with JARVIS](jarvis-basics.md) | Load data, manipulate structures, query databases | 10 min | +| [ML Property Prediction](ml-prediction.md) | Predict band gaps and formation energies with ALIGNN | 15 min | +| [ALIGNN-FF Molecular Dynamics](alignn-ff-md.md) | Run MD simulations with the universal force field | 15 min | +| [Quantum VQE for Solids](quantum-vqe.md) | VQE/VQD on Wannier Hamiltonians with Qiskit | 20 min | +| [Building Custom Apps](custom-apps.md) | Add your own web app to AtomGPT.org | 30 min | + +!!! tip "Run in Colab" + All tutorials can be run in [Google Colab](https://colab.research.google.com/github/knc6/jarvis-tools-notebooks/blob/master/jarvis-tools-notebooks/agapi_example.ipynb) — no local setup needed. diff --git a/docs/tutorials/jarvis-basics.md b/docs/tutorials/jarvis-basics.md new file mode 100644 index 0000000..ddda546 --- /dev/null +++ b/docs/tutorials/jarvis-basics.md @@ -0,0 +1,85 @@ +--- +title: Getting Started with JARVIS +--- + +# Getting Started with JARVIS + +Learn to load materials data, manipulate crystal structures, and query the JARVIS-DFT database. + +## Install + +```bash +pip install jarvis-tools agapi +``` + +## Load a Material by JARVIS ID + +```python +from jarvis.db.figshare import get_jid_data +from jarvis.core.atoms import Atoms + +data = get_jid_data(jid="JVASP-1002", dataset="dft_3d") +atoms = Atoms.from_dict(data["atoms"]) + +print(f"Formula: {data['formula']}") +print(f"Space group: {data['spg_symbol']}") +print(f"Band gap: {data['optb88vdw_bandgap']} eV") +print(f"Atoms: {atoms.num_atoms}") +print(f"Lattice:\n{atoms.lattice_mat}") +``` + +## Query the Full Database + +```python +from jarvis.db.figshare import data + +dft = data("dft_3d") +print(f"{len(dft)} materials loaded") + +# Filter: binary oxides with band gap > 2 eV +oxides = [ + e for e in dft + if e.get("optb88vdw_bandgap") not in (None, "na") + and float(e["optb88vdw_bandgap"]) > 2.0 + and len(set(e["atoms"]["elements"])) == 2 + and "O" in e["atoms"]["elements"] +] +print(f"Found {len(oxides)} binary oxides with gap > 2 eV") +``` + +## Using the AGAPI Client + +```python +import os +from agapi.agents.client import AGAPIClient +from agapi.agents.functions import query_by_formula, query_by_jid + +client = AGAPIClient(api_key=os.environ.get("AGAPI_KEY")) + +# Search by formula +r = query_by_formula("SrTiO3", client) +print(f"Found {len(r['materials'])} SrTiO3 entries") + +# Get POSCAR for a specific material +r = query_by_jid("JVASP-1002", client) +print(r["POSCAR"][:200]) +``` + +## Structure Manipulation + +```python +from jarvis.core.atoms import Atoms + +# Make supercell +supercell = atoms.make_supercell([2, 2, 2]) +print(f"Supercell: {supercell.num_atoms} atoms") + +# Write files +atoms.write_poscar("Si.vasp") +atoms.write_cif("Si.cif") +``` + +## Next Steps + +- [ML Property Prediction](ml-prediction.md) — predict properties with ALIGNN +- [API Reference](../api/python-client.md) — all available functions diff --git a/docs/tutorials/ml-prediction.md b/docs/tutorials/ml-prediction.md new file mode 100644 index 0000000..301393b --- /dev/null +++ b/docs/tutorials/ml-prediction.md @@ -0,0 +1,91 @@ +--- +title: ML Property Prediction +--- + +# ML Property Prediction with ALIGNN + +Predict 50+ materials properties in seconds using ALIGNN graph neural networks. + +## Install + +```bash +pip install alignn jarvis-tools agapi +``` + +## Predict a Single Property + +```python +from alignn.pretrained import get_prediction +from jarvis.core.atoms import Atoms +from jarvis.db.figshare import get_jid_data + +atoms = Atoms.from_dict(get_jid_data("JVASP-1002", "dft_3d")["atoms"]) + +# Band gap +gap = get_prediction(atoms=atoms, model_name="jv_optb88vdw_bandgap") +print(f"Predicted band gap: {gap} eV") + +# Formation energy +ef = get_prediction(atoms=atoms, model_name="jv_formation_energy_peratom") +print(f"Predicted formation energy: {ef} eV/atom") + +# Bulk modulus +kv = get_prediction(atoms=atoms, model_name="jv_bulk_modulus_kv") +print(f"Predicted bulk modulus: {kv} GPa") +``` + +## Via AGAPI Agent + +```python +from agapi.agents import AGAPIAgent +import os + +agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY")) +response = agent.query_sync("Predict properties of JVASP-1002 with ALIGNN") +print(response) +``` + +## Batch Screening + +```python +from jarvis.db.figshare import data +from alignn.pretrained import get_prediction +from jarvis.core.atoms import Atoms + +dft = data("dft_3d") +for entry in dft[:20]: + atoms = Atoms.from_dict(entry["atoms"]) + pred = get_prediction(atoms=atoms, model_name="jv_formation_energy_peratom") + dft_val = entry.get("formation_energy_peratom", "na") + print(f"{entry['jid']}: {entry['formula']:8s} ALIGNN={pred:.3f} DFT={dft_val}") +``` + +## Via AGAPI REST API + +```python +from agapi.agents.functions import alignn_predict + +r = alignn_predict(jid="JVASP-1002", api_client=client) +print(r) +``` + +## Available Models + +Key pre-trained models (50+ total): + +| Model | Property | Units | +|-------|----------|-------| +| `jv_formation_energy_peratom` | Formation energy | eV/atom | +| `jv_optb88vdw_bandgap` | Band gap (OptB88vdW) | eV | +| `jv_mbj_bandgap` | Band gap (mBJ) | eV | +| `jv_bulk_modulus_kv` | Bulk modulus (Voigt) | GPa | +| `jv_shear_modulus_gv` | Shear modulus (Voigt) | GPa | +| `jv_ehull` | Energy above hull | eV/atom | +| `jv_magmom_oszicar` | Magnetic moment | μB | +| `jv_spillage` | Topological spillage | — | +| `jv_slme` | SLME efficiency | % | +| `jv_n_Seebeck` | n-type Seebeck | μV/K | + +## Reference + +K. Choudhary et al., npj Comp. Mat. 7, 1 (2021) — [DOI](https://doi.org/10.1038/s41524-021-00650-1) diff --git a/docs/tutorials/quantum-vqe.md b/docs/tutorials/quantum-vqe.md new file mode 100644 index 0000000..c098f5d --- /dev/null +++ b/docs/tutorials/quantum-vqe.md @@ -0,0 +1,92 @@ +--- +title: Quantum VQE for Solids +--- + +# Quantum VQE for Solids + +Run VQE and VQD on Wannier tight-binding Hamiltonians to predict electronic and phonon bandstructures using quantum algorithms. + +## Install + +```bash +pip install jarvis-tools qiskit==0.41.1 qiskit-aer +``` + +## VQE at a Single K-point + +```python +from jarvis.db.figshare import get_wann_electron, get_hk_tb +from jarvis.io.qiskit.inputs import HermitianSolver +from jarvis.core.circuits import QuantumCircuitLibrary +from qiskit import Aer + +# Load Wannier TB Hamiltonian for Aluminum +backend = Aer.get_backend("statevector_simulator") +wtbh, Ef, atoms = get_wann_electron("JVASP-816") + +# Build H(k) at X-point +hk = get_hk_tb(w=wtbh, k=[0.5, 0., 0.5]) + +# Setup VQE +HS = HermitianSolver(hk) +n_qubits = HS.n_qubits() +circ = QuantumCircuitLibrary(n_qubits=n_qubits, reps=1).circuit6() + +# Run VQE +en, vqe_result, vqe = HS.run_vqe(var_form=circ, backend=backend) +vals, vecs = HS.run_numpy() + +print(f"Classical ground state: {vals[0]-Ef:.4f} eV") +print(f"VQE ground state: {en-Ef:.4f} eV") +print(f"Error: {abs(en-vals[0]):.6f} eV") +``` + +## Full Bandstructure with VQD + +```python +from jarvis.io.qiskit.inputs import get_bandstruct + +out = get_bandstruct(w=wtbh, atoms=atoms, line_density=1, savefig=False) + +# out["eigvals_q"] = VQD eigenvalues (quantum) +# out["eigvals_np"] = numpy eigenvalues (classical) +# out["kpts"] = k-point coordinates +# out["new_labels"] = high-symmetry point labels +``` + +## Plot Bandstructure Comparison + +```python +import matplotlib.pyplot as plt +import numpy as np + +eigvals_q = np.array(out["eigvals_q"]).real +eigvals_np = np.array(out["eigvals_np"]).real +nk, nb = eigvals_np.shape + +for b in range(nb): + plt.plot(range(nk), eigvals_np[:, b], 'b-', linewidth=1.5, + label='Classical' if b == 0 else '') + plt.plot(range(nk), eigvals_q[:, b], 'r.', markersize=3, + label='VQD' if b == 0 else '') + +plt.ylabel("Energy (eV)") +plt.legend() +plt.title("Al Electronic Bandstructure: Classical vs VQD") +plt.savefig("al_bands_vqd.png", dpi=150) +plt.show() +``` + +## Key Concepts + +**Wannier TBH**: Compact representation of DFT electronic structure. 307 electronic + 933 phonon Hamiltonians available in JARVIS. + +**VQE**: Variational Quantum Eigensolver — finds ground state energy using parameterized quantum circuits. + +**VQD**: Variational Quantum Deflation — extends VQE to find excited states by deflating previously found eigenvalues. + +**Circuit-6**: EfficientSU2 ansatz with RY+RZ gates and CNOT entangling layers. + +## Reference + +K. Choudhary, J. Phys.: Condens. Matter 33, 385501 (2021) — [DOI](https://doi.org/10.1088/1361-648X/ac1154) diff --git a/mkdocs.yml b/mkdocs.yml index d7d1ba7..3d9a036 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,19 +1,173 @@ -site_name: AGAPI -site_url: https://knc6.github.io/agapi -repo_url: https://github.com/knc6/agapi -repo_name: knc6/agapi +site_name: AtomGPT.org API (AGAPI) Documentation +site_url: https://atomgptlab.github.io/agapi +site_description: Documentation for AtomGPT.org - 50+ web apps for materials science, AI, and quantum computation +site_author: Kamal Choudhary +repo_url: https://github.com/atomgptlab/agapi +repo_name: atomgptlab/agapi +edit_uri: edit/main/docs/ + +copyright: "© 2025 AtomGPTLab, Johns Hopkins University" theme: name: material + logo: assets/logo.png + favicon: assets/favicon.png + icon: + repo: fontawesome/brands/github palette: - primary: indigo + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: deep purple + accent: amber + toggle: + icon: material/brightness-4 + name: Switch to light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: deep purple + accent: amber + toggle: + icon: material/brightness-7 + name: Switch to dark mode features: + - navigation.instant + - navigation.tracking + - navigation.tabs + - navigation.tabs.sticky + - navigation.sections + - navigation.expand - navigation.top + - navigation.indexes + - search.suggest + - search.highlight - content.code.copy + - content.code.annotate + - content.tabs.link + - toc.follow + font: + text: DM Sans + code: JetBrains Mono -nav: - - Home: index.md +plugins: + - search + - tags markdown_extensions: - - pymdownx.highlight - - pymdownx.superfences + - admonition + - pymdownx.details + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - attr_list + - md_in_html + - tables + - toc: + permalink: true + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/atomgptlab + - icon: fontawesome/brands/youtube + link: https://www.youtube.com/playlist?list=PLjf6vHVv7AoInTVQmfNSMs_12DBXYCcDd + - icon: fontawesome/brands/spotify + link: https://open.spotify.com/show/0BnqIOqf2D2cjlAsrqmTQs + analytics: + provider: google + property: G-DWX5E15SF5 + +extra_css: + - stylesheets/extra.css + +nav: + - Home: index.md + - Getting Started: + - getting-started/index.md + - Quick Start: getting-started/quickstart.md + - Authentication: getting-started/authentication.md + - API Overview: getting-started/api-overview.md + - Apps: + - apps/index.md + - Explore: + - apps/explore/index.md + - Materials Explorer: apps/explore/materials-explorer.md + - Electronic DOS: apps/explore/electronic-dos.md + - Phonon DOS: apps/explore/phonon-dos.md + - Dielectric Function: apps/explore/dielectric-function.md + - Elastic Tensor: apps/explore/elastic-tensor.md + - Thermoelectric: apps/explore/thermoelectric.md + - EFG: apps/explore/efg.md + - Piezoelectric: apps/explore/piezoelectric.md + - IR Spectra: apps/explore/ir.md + - Spillage: apps/explore/spillage.md + - Vacancy Explorer: apps/explore/vacancy.md + - Surface Explorer: apps/explore/surface.md + - Interface Explorer: apps/explore/interface.md + - 2D Materials: apps/explore/twod.md + - Polymer Explorer: apps/explore/polymer.md + - Force Field DB: apps/explore/ff.md + - Periodic Table: apps/explore/periodic-table.md + - HEA Explorer: apps/explore/hea.md + - Reaction Network: apps/explore/reaction-network.md + - PDB Explorer: apps/explore/pdb-explorer.md + - OPTIMADE Explorer: apps/explore/optimade.md + - Convex Hull: apps/explore/convexhull.md + - Build: + - apps/build/index.md + - Structure Visualizer: apps/build/structure-visualizer.md + - Heterostructure Builder: apps/build/heterostructure.md + - Workflow Builder: apps/build/workflow.md + - Predict: + - apps/predict/index.md + - ALIGNN Predictor: apps/predict/alignn.md + - ALIGNN-FF Dynamics: apps/predict/alignn-ff.md + - SlakoNet Bands: apps/predict/slakonet.md + - Wannier TB Bands: apps/predict/wtb.md + - Quantum Computation: apps/predict/quantum.md + - Protein Fold: apps/predict/protein-fold.md + - Characterize: + - apps/characterize/index.md + - XRD / DiffractGPT: apps/characterize/xrd.md + - Raman Matching: apps/characterize/raman.md + - MicroscopyGPT: apps/characterize/microscopy.md + - Apply: + - apps/apply/index.md + - SuperconGPT: apps/apply/supercon.md + - Solar Cell Screening: apps/apply/solar.md + - Battery Explorer: apps/apply/battery.md + - Catalysis: apps/apply/catalysis.md + - Direct Air Capture: apps/apply/dac.md + - Validate: + - apps/validate/index.md + - AI Detector: apps/validate/ai-detector.md + - Hallucination Detector: apps/validate/hallucination.md + - API Reference: + - api/index.md + - Python Client: api/python-client.md + - REST Endpoints: api/rest-endpoints.md + - AGAPI Agents: api/agents.md + - OPTIMADE: api/optimade.md + - Tutorials: + - tutorials/index.md + - Getting Started with JARVIS: tutorials/jarvis-basics.md + - ML Property Prediction: tutorials/ml-prediction.md + - ALIGNN-FF Molecular Dynamics: tutorials/alignn-ff-md.md + - Quantum VQE for Solids: tutorials/quantum-vqe.md + - Building Custom Apps: tutorials/custom-apps.md + - References: + - references/index.md + - Publications: references/publications.md + - Changelog: references/changelog.md diff --git a/setup.py b/setup.py index 95a3741..b9eb89b 100644 --- a/setup.py +++ b/setup.py @@ -5,7 +5,7 @@ setuptools.setup( name="agapi", - version="2026.2.2", + version="2026.3.2", author="Kamal Choudhary", author_email="kchoudh2@jhu.edu", description="agapi",