diff --git a/.github/workflows/build-tests.yml b/.github/workflows/build-tests.yml index 26aca33b1..b2919afdc 100644 --- a/.github/workflows/build-tests.yml +++ b/.github/workflows/build-tests.yml @@ -3,10 +3,10 @@ name: Build tests and GitHub release on: push: branches: - - master + - main pull_request: branches: - - master + - main jobs: run-py-tests: @@ -16,42 +16,87 @@ jobs: os: ["ubuntu-24.04"] python-version: - "3.10" - - "3.11" - - "3.12" - - "3.13" + # No need to run with many Py versions - as long as one is passing, we should be OK + # - "3.11" + # - "3.12" + # - "3.13" steps: - name: Checkout repository and submodules - uses: actions/checkout@v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 0 lfs: true submodules: true - name: Setup python 3 - uses: actions/setup-python@v5 + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: python-version: ${{ matrix.python-version }} - - name: Build documentation - uses: Exabyte-io/action-mkdocs-build@main + - name: Install dependencies + run: | + pip install -r requirements.txt + + - name: Build documentation (legacy) + run: | + python -m mkdocs build -f mkdocs.yml + + - name: Build split sites + run: | + python -m mkdocs build -f mkdocs-guide.yml -d site/guide + python -m mkdocs build -f mkdocs-interface.yml -d site/interface + python -m mkdocs build -f mkdocs-concepts.yml -d site/reference + python -m mkdocs build -f mkdocs-resources.yml -d site/resources + python -m mkdocs build -f mkdocs-developers.yml -d site/developers + python -m mkdocs build -f mkdocs-cli.yml -d site/command-line + python -m mkdocs build -f mkdocs-standards.yml -d site/standards + + # Fix and copy subsite homepages to root of each subsite + fix_homepage() { + local src="$1" + local dst="$2" + if [ -f "$src" ]; then + sed \ + -e 's|"base": ".."|"base": "."|' \ + -e 's|"\.\./assets/|"./assets/|g' \ + -e 's|"\.\./search/|"./search/|g' \ + -e 's|"\.\./extra/|"./extra/|g' \ + -e 's|"\.\./images/|"./images/|g' \ + -e 's|href="\.\./|href="./|g' \ + -e 's|src="\.\./|src="./|g' \ + "$src" > "$dst" + fi + } + fix_homepage site/guide/index-guide/index.html site/guide/index.html + fix_homepage site/interface/index-interface/index.html site/interface/index.html + fix_homepage site/reference/index-concepts/index.html site/reference/index.html + fix_homepage site/resources/index-resources/index.html site/resources/index.html + fix_homepage site/developers/index-developers/index.html site/developers/index.html + fix_homepage site/command-line/index-cli/index.html site/command-line/index.html + fix_homepage site/standards/index-standards/index.html site/standards/index.html + + + + - name: Check for broken internal links + run: python scripts/links/check-links.py site publish-py-package: needs: - run-py-tests runs-on: ubuntu-24.04 - if: (github.repository != 'Exabyte-io/template-definitions-js-py') && (github.ref_name == 'master') + if: (github.ref_name == 'main') steps: - name: Checkout this repository - uses: actions/checkout@v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: lfs: true - name: Checkout actions repository - uses: actions/checkout@v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: - repository: Exabyte-io/actions + repository: mat3ra/actions token: ${{ secrets.BOT_GITHUB_TOKEN }} path: actions diff --git a/.github/workflows/docs-agent-index.yml b/.github/workflows/docs-agent-index.yml new file mode 100644 index 000000000..11beceb58 --- /dev/null +++ b/.github/workflows/docs-agent-index.yml @@ -0,0 +1,39 @@ +name: Refresh the documentation agent index + +# The agent answers from a snapshot of this repository's content, baked into +# its container image. When the content changes, the snapshot is stale until +# the service is rebuilt. +# +# This workflow does no ingestion of its own: all agent logic lives in the +# documentation-agent repository, which checks this repository out at the +# commit below and builds its own index. The two pipelines stay decoupled — +# this one only says "the documentation moved, here is where". + +on: + push: + branches: + - main + paths: + - "lang/en/docs/**" + workflow_dispatch: + +jobs: + notify: + runs-on: ubuntu-24.04 + steps: + - name: Tell the agent repository to rebuild + # A token with `repo` scope on mat3ra/documentation-agent. The default + # GITHUB_TOKEN cannot dispatch across repositories. + env: + TOKEN: ${{ secrets.DOCS_AGENT_DISPATCH_TOKEN }} + run: | + if [ -z "$TOKEN" ]; then + echo "DOCS_AGENT_DISPATCH_TOKEN is not set; skipping the rebuild trigger." >&2 + exit 0 + fi + curl -fsS -X POST \ + -H "Authorization: Bearer $TOKEN" \ + -H "Accept: application/vnd.github+json" \ + https://api.github.com/repos/mat3ra/documentation-agent/dispatches \ + -d "{\"event_type\":\"documentation-updated\",\"client_payload\":{\"sha\":\"${GITHUB_SHA}\"}}" + echo "Requested a rebuild from documentation@${GITHUB_SHA}" diff --git a/.github/workflows/s3-deploy.yml b/.github/workflows/s3-deploy.yml index 702ed0f12..f6144a5da 100644 --- a/.github/workflows/s3-deploy.yml +++ b/.github/workflows/s3-deploy.yml @@ -18,23 +18,58 @@ jobs: AWS_SECRET_ACCESS_KEY: ${{ secrets.S3_SECRET_KEY }} steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 0 lfs: true submodules: true - name: Set python 3 version - uses: actions/setup-python@v5 + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: python-version: "3.10" - - name: Build pages - uses: Exabyte-io/action-mkdocs-build@main + - name: Build pages (legacy) + uses: mat3ra/action-mkdocs-build@main + + - name: Build split sites + run: | + python -m mkdocs build -f mkdocs-guide.yml -d site/guide + python -m mkdocs build -f mkdocs-interface.yml -d site/interface + python -m mkdocs build -f mkdocs-concepts.yml -d site/reference + python -m mkdocs build -f mkdocs-resources.yml -d site/resources + python -m mkdocs build -f mkdocs-developers.yml -d site/developers + python -m mkdocs build -f mkdocs-cli.yml -d site/command-line + python -m mkdocs build -f mkdocs-standards.yml -d site/standards + + # Fix and copy subsite homepages to root of each subsite + fix_homepage() { + local src="$1" + local dst="$2" + if [ -f "$src" ]; then + sed \ + -e 's|"base": ".."|"base": "."|' \ + -e 's|"\.\./assets/|"./assets/|g' \ + -e 's|"\.\./search/|"./search/|g' \ + -e 's|"\.\./extra/|"./extra/|g' \ + -e 's|"\.\./images/|"./images/|g' \ + -e 's|href="\.\./|href="./|g' \ + -e 's|src="\.\./|src="./|g' \ + "$src" > "$dst" + fi + } + fix_homepage site/guide/index-guide/index.html site/guide/index.html + fix_homepage site/interface/index-interface/index.html site/interface/index.html + fix_homepage site/reference/index-concepts/index.html site/reference/index.html + fix_homepage site/resources/index-resources/index.html site/resources/index.html + fix_homepage site/developers/index-developers/index.html site/developers/index.html + fix_homepage site/command-line/index-cli/index.html site/command-line/index.html + fix_homepage site/standards/index-standards/index.html site/standards/index.html + - name: Deploy to Production (dev branch, old docs) if: github.ref == 'refs/heads/dev' - uses: Reggionick/s3-deploy@v4 + uses: Reggionick/s3-deploy@04c48f45adfd7a34c66348cf9cd1b6cd117cc467 # v4.0.0 with: folder: site bucket: docs.mat3ra.com @@ -46,7 +81,7 @@ jobs: - name: Deploy to Development (main branch, new docs) if: github.ref == 'refs/heads/main' - uses: Reggionick/s3-deploy@v4 + uses: Reggionick/s3-deploy@04c48f45adfd7a34c66348cf9cd1b6cd117cc467 # v4.0.0 with: folder: site bucket: docs-new.mat3ra.com @@ -55,3 +90,4 @@ jobs: invalidation: /* no-cache: true private: true + diff --git a/.github/workflows/widget-tests.yml b/.github/workflows/widget-tests.yml new file mode 100644 index 000000000..ce9d57cec --- /dev/null +++ b/.github/workflows/widget-tests.yml @@ -0,0 +1,56 @@ +name: Ask AI widget tests + +# The widget ships to every documentation page, so a regression in it is a +# regression on the whole site. These tests need no cloud access and no model +# calls: the agent service is faked at the network boundary. + +on: + push: + branches: + - main + paths: + - "extra/js/docs-agent.js" + - "extra/css/docs-agent.css" + - "tests/widget/**" + - ".github/workflows/widget-tests.yml" + pull_request: + paths: + - "extra/js/docs-agent.js" + - "extra/css/docs-agent.css" + - "tests/widget/**" + - ".github/workflows/widget-tests.yml" + +jobs: + playwright: + runs-on: ubuntu-24.04 + defaults: + run: + working-directory: tests/widget + + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + lfs: false + + - name: Set up Node + uses: actions/setup-node@v4 + with: + node-version: "20" + + - name: Install + run: npm ci || npm install + + - name: Install the browser + run: npx playwright install --with-deps chromium + + - name: Run the tests + run: npx playwright test + + - name: Upload the report on failure + if: failure() + uses: actions/upload-artifact@v4 + with: + name: playwright-report + path: tests/widget/playwright-report + retention-days: 7 diff --git a/.gitignore b/.gitignore index 03e11d42c..1d87bde09 100644 --- a/.gitignore +++ b/.gitignore @@ -16,5 +16,19 @@ service-account-key.json scripts/*.mp3 scripts/*.mp4 +# RAG demo generated index +scripts/rag/chunks.jsonl + # Pyenv .python-version +# Agents workdir +tmp +.local-mkdocs*.yml + +# Local clone of the documentation-agent service repo (see plans/) +reference/ + +# Widget browser tests +tests/widget/node_modules/ +tests/widget/test-results/ +tests/widget/playwright-report/ diff --git a/.gitmodules b/.gitmodules index 4fb0abd1c..6205cf7da 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +1,3 @@ [submodule "esse"] path = data/esse - url = https://github.com/Exabyte-io/esse.git + url = https://github.com/mat3ra/esse.git diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..d028a7285 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,341 @@ +# AGENTS.md + +Guidance for AI coding agents working in the Mat3ra documentation +repository. Read this alongside [`WRITING-STYLE.md`](WRITING-STYLE.md) +and [`README.md`](README.md), which remain the canonical references for +prose style and formatting respectively. For running structured quality +reviews, see [`REVIEW.md`](REVIEW.md). + +## Repository at a Glance + +- Source for [docs.mat3ra.com](http://docs.mat3ra.com), built with + [MkDocs](http://www.mkdocs.org/) using the + [Material](https://squidfunk.github.io/mkdocs-material/) theme. +- English Markdown lives in `lang/en/docs/`. Other languages under + `lang//docs/` are regenerated by `translate.py` — do not edit + them by hand. +- Navigation is wired in `mkdocs.yml`. Any page that is added, renamed, + or moved must be updated there in the same change. +- Some tutorial pages have a sibling `.json` metadata file used by the + voiceover/video tooling described in [`INTERNAL.md`](INTERNAL.md). When + renaming the `.md`, rename the `.json` to match. +- Images live under `images/
/` and are tracked with Git LFS. + Prefer `.webp`, keep each file below 1 MB, and use natural-language + hyphen-case names. + +## Multi-Site Architecture + +The documentation is split into four MkDocs sites, each with its own +config file and URL prefix: + +| Site | Config | URL path | Landing page | +| ------------------ | -------------------- | ------------- | ----------------------- | +| Top-level (legacy) | `mkdocs.yml` | `/` | `index.md` | +| Tutorials / Guide | `mkdocs-guide.yml` | `/guide/` | `index-guide.md` | +| Concepts/Reference | `mkdocs-concepts.yml`| `/reference/` | `index-concepts.md` | +| Developer Docs | `mkdocs-dev.yml` | `/dev/` | `index-dev.md` | + +Key points: + +- The top-level site (`mkdocs.yml`) contains the full navigation and + acts as a hub. Its `index.md` has clickable cards linking to the three + sub-sites. +- Each sub-site config inherits common settings (theme, CSS, JS) but + defines its own `nav:`, `site_name`, and `site_url`. +- Each sub-site has a `← All Docs` entry at the top of its `nav:` that + links back to the root (`/`). This is a hardcoded absolute path — Jinja2 + macros do not render inside `nav:` definitions. + +### Cross-Site Links + +Links between sub-sites use Jinja2 macro variables defined in `extra:` +of each config: + +```yaml +extra: + guide_url: https://docs.mat3ra.com/guide + reference_url: https://docs.mat3ra.com/reference + dev_url: https://docs.mat3ra.com/dev +``` + +#### When to use relative vs macro links + +| Link target is… | Use this form | +| ----------------------------- | --------------------------------------------------- | +| In the **same** sub-site | Relative path: `[text](../path/to/page.md)` | +| In a **different** sub-site | Macro link: `[text]({{ reference_url }}/path/to/page/)` | + +Never hardcode `https://docs.mat3ra.com/guide/…` in Markdown — always +use the macro variable so `serve-all.sh` can rewrite it for local +development. + +#### How `exclude_docs` determines page ownership + +Each sub-site config has an `exclude_docs:` block listing directories +and files that belong to other sites. Some directories are split between +sites at the page level (e.g., `jobs/overview.md` → Reference, +`jobs/actions/` → Guide). When linking, check the target page's +`exclude_docs` status in the config of the site the source page belongs +to. If the target is excluded, use a macro link. + +#### The `render_macros` + `{% raw %}` pattern + +Some pages contain raw Jinja2 code examples (e.g., templating +tutorials with `{{ input.RESTART_MODE }}`). The macros plugin would +try to resolve these as variables, causing errors or empty output. + +The fix: + +1. Leave `render_macros: true` (or omit it — the default is `true`). +2. Wrap raw Jinja code blocks in `{% raw %}…{% endraw %}`. + +**Critical rule:** never set `render_macros: false` on a page that +contains cross-site macro links (`{{ guide_url }}`, etc.). Setting it +to `false` prevents ALL macros from resolving, leaving them as literal +text in the HTML and creating broken links. The only pages that may +use `render_macros: false` are those with no cross-site macro links at +all (e.g., `benchmarks/2018-11-12-comparison.md`). + +#### Link validation + +After building, run the post-build link checker: + +```bash +.venv/bin/python scripts/links/check-links.py +``` + +This scans every `` in the built `site/` directory and verifies +that the target file exists. Exit code 1 means broken links were found. + +Helper scripts in `scripts/links/`: + +- `check-links.py` — post-build internal link checker (the main tool). +- `find-cross-site-links.py` — detect which pages contain cross-site refs. +- `fix-broken-cross-links.py` — repair broken inter-site links. +- `rewrite-cross-site-links.py` — convert hardcoded URLs to macros. +- `urls-to-macros.py` — bulk convert `https://docs.mat3ra.com/guide/…` + to `{{ guide_url }}/…`. + +### Building and Serving Locally + +Use `scripts/serve-all.sh` to build and serve all four sites: + +```bash +# Serve on default port 8000 +./scripts/serve-all.sh + +# Serve on a specific port +PORT=8888 ./scripts/serve-all.sh + +# Build only (no server) +./scripts/serve-all.sh --build +``` + +The script: +1. Creates temporary local config overrides (`.local-mkdocs*.yml`) that + rewrite cross-site URLs to `localhost`. +2. Builds all four sites into `site/`, `site/guide/`, `site/reference/`, + `site/dev/`. +3. Fixes sub-site homepages (copies from `index-/index.html` to + the root of each sub-site). +4. Starts `python -m http.server` on the chosen port. +5. Cleans up temp configs on exit. + +**Do not** use `mkdocs serve` for multi-site work — it only serves one +site at a time. + +### Config Synchronization + +When adding a new CSS or JS file, plugin, or theme setting, it must be +added to **all four** config files: + +- `mkdocs.yml` +- `mkdocs-guide.yml` +- `mkdocs-concepts.yml` +- `mkdocs-dev.yml` + +## Homepage Cards (CSS) + +The top-level `index.md` uses HTML cards inside a `
`. +Styles are in `lang/en/docs/extra/css/general.css`. + +Important CSS notes: + +- **Do not** use the class name `.grid` — MkDocs Material reserves it for + its own grid system and will override the styles. +- MkDocs wraps inline `` tags inside `

` elements. The CSS targets + `.section-cards > p` (margin: 0, display: flex) to make `

` a + transparent grid item, then styles `a.grid-card` with flexbox for + equal-height cards. +- Cards use `display: flex; flex-direction: column; flex: 1` to stretch + to equal height within the CSS Grid row. + +## Writing Style (from `WRITING-STYLE.md`) + +`WRITING-STYLE.md` is authoritative. Key rules: + +- Simple, dry, concise. Drop adorning adjectives ("complete list of all + the many different items" → "the list of items"). +- Third person or passive voice — never "you" or "your". Use "the user" + or "this can be accessed". +- Present tense over future tense. +- Avoid these words: *Simply, Clearly, Obviously, In fact, Furthermore, + Moreover, Complete, In particular, Really, Distinct, Various, + Automatically, Finally*. +- Prefer "click the button" over "click on the button". +- Don't start a sentence with a short interjection like "To" — use + "In order to" instead. The same applies to "By", "From", etc. +- Introduce acronyms on first mention per page + ("Density Functional Theory (DFT)"). Do **not** put acronyms in + headers. +- For external concepts, link to Wikipedia or the upstream source rather + than re-explaining them. +- Follow Object-Oriented Design: encapsulate each topic in its own + section, abstract shared concepts to the parent page, and let specific + pages inherit context from the section overview. + +## Page Structure (from `README.md`) + +- Exactly one H1 (`#`) per page, on the first line. Use H2/H3/H4 for the + rest. +- For long pages, enumerate sections and subsections: + `## 1. Section`, `### 1.1. Subsection`. +- Leave one blank line between paragraphs and after every heading. Leave + 2–3 blank lines when returning from a deeper level to a shallower one. +- No trailing whitespace; one blank line at the end of file. +- Use **relative** paths for all internal links and image references. +- For images, use Markdown syntax `![Alt](path "Title")`; reserve HTML + for clickable maps, `gifffer` GIFs, and YouTube embeds. +- Use admonitions for callouts: + `!!!tip "Title"`, `!!!info "Title"`, `!!!warning "Title"`. +- Inline UI references: `**Run**` for buttons, `*Workflow*` for tab or + section names, `` `MATERIAL` `` for code identifiers or commands. + +## Tutorial Patterns (introduced in PR 357 / commit `21ed5b18`) + +The MatterSim tutorial +(`lang/en/docs/tutorials/ml/run-mlff-python-workflows-mattersim.md`) is +the current reference for tutorial style. Apply the same patterns to +other tutorial pages. + +### Imperative subheadings + +Third-level subheadings name an action the user performs. Use the +imperative form, not the gerund. + +| Avoid | Prefer | +| ---------------------------------- | --------------------------------- | +| `### 1.1. Importing a workflow` | `### 1.1. Import a workflow` | +| `### 4.1. Confirming GPU access` | `### 4.1. Confirm GPU access` | +| `### 4.2. Example Results` | `### 4.2. Example results` | + +Top-level `## N.` titles may stay in gerund form when they label an +approach ("Using a bank workflow", "Creating a new workflow"). Avoid +awkward connectors such as "By creating ...". + +### No list directly under a heading + +Open every section with a prose sentence that orients the reader, then +introduce a list only if it adds value. For short procedural steps, +prefer prose with "First, … Then, …" transitions over a bullet list. + +Avoid: + +```markdown +### 1.1. Import a bank workflow + +- Navigate to the *Workflows Bank* page from the left sidebar. +- Search for `MatterSim` and click **Copy** ... +``` + +Prefer: + +```markdown +### 1.1. Import a bank workflow + +First, navigate to the *Workflows Bank* page from the left sidebar. +Then, search for `MatterSim` and click **Copy** ... +``` + +### Flat lists, flush-left block content + +- Flatten nested bullet lists to a single level. If a sub-list needs + context, lift it out and introduce it with a prose sentence. +- Keep images, code blocks, and follow-on paragraphs flush-left. Do not + nest them inside list items; break the surrounding list into prose + instead. + +### Captions and assets + +- Every image has both alt text and a title attribute. +- Use `` to allow soft word-breaks in long slash-separated terms + (e.g. `flavor/template`). + +## Generating Tutorial Screenshots + +When asked to capture or update screenshots for tutorials, follow this approach: + +We use **Cypress** integration tests (located in the `web-app` repository) to automate the generation of screenshots for tutorials. + +1. **Test Files**: The Cypress feature files/tests are typically stored in the `cypress/e2e/tutorials/` directory within the web application codebase. +2. **Screenshot Capture**: Within these tests, we use the `cy.screenshot('filename')` command to capture specific states of the application UI (e.g., material selection, workflow designer tabs, job submission). +3. **Integration**: The generated images are then placed into the `images/tutorials/` folder of this `documentation` repository and referenced in the markdown files. + +### Workflow for Regenerating Content + +To regenerate the screenshots for a tutorial: +1. Locate the corresponding Cypress test in the `web-app` project. +2. Ensure the test correctly navigates to the state you want to capture. +3. Insert or update `cy.screenshot('desired-image-name')` at the appropriate steps. +4. Run the Cypress test. +5. Copy the newly generated images from Cypress's screenshots directory to the `documentation/images/tutorials/...` directory. +6. Update the markdown file in `documentation/lang/en/docs/tutorials/...` to reference the new images if filenames have changed. + +### Caveats and Troubleshooting + +- **Headless Mode and Incomplete UI Rendering**: When running Cypress in headless mode (e.g., via the default Electron browser in CI), complex UI widgets like `ag-grid`, dropdown menus, and workflow designer canvases may fail to render fully before the screenshot is taken. This results in empty or incorrect images. **Workaround**: Run Cypress in **headed mode** for screenshot generation, or ensure you have robust assertions (e.g., waiting for specific network requests to complete or using `cy.wait()`) prior to calling `cy.screenshot()`. +- **Uncaught Exceptions Breaking Tests**: Sometimes, the application may throw benign console errors (e.g., `ResizeObserver loop limit exceeded`) that cause Cypress to fail the test prematurely before taking the screenshot. **Workaround**: These exceptions can be suppressed in `cypress/support/e2e.ts` by intercepting the `uncaught:exception` event and returning `false`. + + +## Working with the Repo + +- Make the smallest diff that satisfies the request. Don't touch files + the user didn't ask about. +- Don't edit translated pages under non-`en` languages unless asked — + they are regenerated by `translate.py`. +- Never stage or commit unless the user explicitly asks. +- When renaming a tutorial page, update in the same change: + 1. the `.md` file, + 2. the sibling `.json` metadata file (if present), + 3. the entry in `mkdocs.yml`. +- New images go under `images/

/` as `.webp`, hyphen-case, under + 1 MB. +- Use `tmp/` for throwaway test scripts (Playwright, etc.). This + directory is git-ignored. + +## GitHub Source Stats + +The MkDocs Material theme shows repository stars, forks, and latest +tag in the header via its built-in `source` component. This relies on +client-side JavaScript that fetches from `api.github.com`. When +rate-limited (common on localhost), the stats silently disappear. This +is expected behavior — they work in production. Do **not** add custom +JavaScript workarounds for this; the native mechanism is sufficient. + +## Pre-Submit Checklist + +- [ ] One H1; sub-headers in sentence case; no acronyms in headers. +- [ ] No list starts directly under a heading. +- [ ] Lists are flat; images and code blocks are flush-left. +- [ ] Third person / passive voice; no "you" or "your". +- [ ] None of the forbidden words from `WRITING-STYLE.md`. +- [ ] Acronyms are introduced on first use. +- [ ] Same-site links and image paths use relative paths. +- [ ] Cross-site links use `{{ guide_url }}`, `{{ reference_url }}`, or + `{{ dev_url }}` macros — not hardcoded URLs. +- [ ] Pages with raw Jinja code use `{% raw %}` blocks — not + `render_macros: false` — if they also contain cross-site macros. +- [ ] `mkdocs.yml` is updated if pages were added, renamed, or moved. +- [ ] Changes to CSS/JS/plugins are reflected in **all four** config files. +- [ ] Post-build link check passes: `.venv/bin/python scripts/links/check-links.py`. +- [ ] Only the files the user asked about were modified. diff --git a/INTERNAL.md b/INTERNAL.md index 2c7a3a1aa..a5967a8b2 100644 --- a/INTERNAL.md +++ b/INTERNAL.md @@ -20,6 +20,14 @@ Follow the below instructions to upload/update a tutorial video: ``` whereby `PATH_TO_SAVE_AUDIO` and `PATH_TO_SAVE_NEW_VIDEO` should have the file extension `.mp3` and `.mp4`, respectively. + Voiceover audio alone (without an accompanying video file) can be generated + by omitting the `--file` and `--output` options. + + The Google Cloud Text-to-Speech API has a limit of about 4 minutes of audio + per request. Audio longer than this must be split into multiple requests + using the `--skip` and `--until` options. The exact end time of a segment + should be used as the `skip` and/or `until` value. + 5. Retry step 4 with adjusted `youTubeCaptions` data until the optimal outcome is achieved. 6. Before uploading, make sure that the timings of the `youTubeCaptions` sentences in the metadata file match exactly the duration of their pronunciations in the voiceover. This ensures that the subtitles will be synced correctly to the voice in the final online video version. diff --git a/README.md b/README.md index 119c33b26..78942a776 100644 --- a/README.md +++ b/README.md @@ -11,15 +11,15 @@ For a quick installation: 2. Clone this repository: ```bash - git clone https://github.com/Exabyte-io/documentation.git + git clone https://github.com/mat3ra/documentation.git ``` 3. Setup virtual environment ```bash cd documentation - virtualenv venv - source venv/bin/activate + virtualenv .venv + source .venv/bin/activate pip install --no-deps -r requirements.txt ``` @@ -41,7 +41,137 @@ For a quick installation: mkdocs serve ``` -You should have the documentation up and running at `http://localhost:8000` +This starts the legacy full site at `http://localhost:8000`. For the +multi-site setup (Guide / Concepts / Dev), see the next section. + +### Multi-Site Build (Guide / Concepts / Dev) + +The documentation is split into three focused sites, each with its own MkDocs +configuration. The original `mkdocs.yml` remains available for the full +monolithic build. + +| Config file | Site | URL | Dev port | +|-------------|------|-----|----------| +| `mkdocs.yml` | Full (legacy) | `docs.mat3ra.com` | 8000 | +| `mkdocs-guide.yml` | Platform Guide | `docs.mat3ra.com/guide/` | 8001 | +| `mkdocs-concepts.yml` | Concepts & Reference | `docs.mat3ra.com/reference/` | 8002 | +| `mkdocs-dev.yml` | Developer Guide | `docs.mat3ra.com/dev/` | 8003 | + +#### Serve a single site (quick editing) + +```bash +source .venv/bin/activate +mkdocs serve -f mkdocs-guide.yml # localhost:8001 +mkdocs serve -f mkdocs-concepts.yml # localhost:8002 +mkdocs serve -f mkdocs-dev.yml # localhost:8003 +``` + +Pages within the site work normally with live reload. +Cross-site links navigate to `docs.mat3ra.com` (production). + +#### Build & serve all sites locally (full testing) + +```bash +./scripts/serve-all.sh +``` + +This builds the legacy site plus all three subsites into `site/` and starts a +local server on `http://localhost:8000`: + +- `http://localhost:8000/` — legacy full site +- `http://localhost:8000/guide/` — Platform Guide +- `http://localhost:8000/reference/` — Concepts & Reference +- `http://localhost:8000/dev/` — Developer Guide + +Cross-site links in Markdown use `{{ guide_url }}`, `{{ reference_url }}`, and +`{{ dev_url }}` variables (resolved by the macros plugin at build time). +The `serve-all.sh` script automatically overrides these to point to +`http://localhost:8000/…`, so cross-site navigation works locally without any +extra setup. + +#### Build only (CI / deploy) + +```bash +mkdocs build -f mkdocs.yml # legacy at / +mkdocs build -f mkdocs-guide.yml -d site/guide # /guide/ +mkdocs build -f mkdocs-concepts.yml -d site/reference # /reference/ +mkdocs build -f mkdocs-dev.yml -d site/dev # /dev/ +``` + +#### Validate internal links + +After building, run the post-build link checker to catch broken internal +links across all four sites: + +```bash +.venv/bin/python scripts/links/check-links.py +``` + +This scans every `` in the built `site/` directory and verifies +that the target file exists. Exit code 1 means broken links were found. +Additional helper scripts live in `scripts/links/`. + +### Cross-Site Linking Convention + +Because each sub-site only contains a subset of pages, links between +sites cannot use relative paths — the target file doesn't exist in the +same build. The convention is: + +| Link target is… | Use this form | +| ----------------------------- | ------------------------------------------------------ | +| In the **same** sub-site | Relative path: `[text](../path/to/page.md)` | +| In a **different** sub-site | Macro link: `[text]({{ reference_url }}/path/to/page/)` | + +The macro variables (`guide_url`, `reference_url`, `dev_url`) are defined +in the `extra:` section of each config file and resolved at build time by +the `mkdocs-macros-plugin`. + +#### Which page belongs to which site? + +Each sub-site config has an `exclude_docs:` block listing directories and +files that belong to other sites. If a page is excluded from a sub-site, +any link **to** it from within that sub-site must use the appropriate +macro instead of a relative path. + +| Top-level directory | Site | +| ---------------------------- | ---------------------------- | +| `tutorials/`, `ui/`, `jobs-designer/`, `workflow-designer/`, `software-directory/`, `cli/`, `jobs-cli/`, `getting-started/`, `pricing/`, `jupyterlite/`, `remote-connection/`, `materials-designer/` | **Guide** (`guide_url`) | +| `models/`, `models-directory/`, `methods/`, `methods-directory/`, `properties-directory/`, `software/`, `benchmarks/`, `data/`, `data-structured/`, `security/`, `site-policy/` | **Reference** (`reference_url`) | +| `infrastructure/`, `data-on-disk/`, `rest-api/` | **Dev** (`dev_url`) | +| `accounts/`, `entities-general/`, `jobs/`, `materials/`, `properties/`, `workflows/`, `collaboration/`, `data-in-objectstorage/` | **Shared** (split by page — check `exclude_docs`) | + +For shared directories, individual pages are assigned to specific sites +via the `exclude_docs` lists. For example, `jobs/overview.md` is in +Reference, while `jobs/actions/` is in Guide. + +#### Pages with raw Jinja syntax + +Some pages (e.g., templating tutorials) contain raw Jinja2 code examples +like `{{ input.RESTART_MODE }}` that would be consumed by the macros +plugin. These pages use `{% raw %}…{% endraw %}` blocks around code +examples to prevent the macros plugin from interpreting them: + +````markdown +--- +render_macros: true +--- +# Templating Example + +The [Jinja engine]({{ reference_url }}/workflows/templating/jinja/) renders variables. + +{% raw %} +```jinja +{{ input.NAT }} +``` +{% endraw %} +```` + +The key rule: **never** set `render_macros: false` on a page that also +contains cross-site macro links (`{{ guide_url }}`, etc.), because those +macros will be left as literal text in the HTML output, producing broken +links. Instead, set `render_macros: true` (or omit the front-matter key +entirely) and wrap only the raw Jinja code blocks in `{% raw %}`. + ## Development @@ -327,18 +457,18 @@ Including a clickable image map is done as follows. Note that absolute paths to Including resolved JSON schemas and associated examples should be done within dedicated `data.md` pages for each concept being explained. -The [markdown_include](https://github.com/Exabyte-io/markdown-include) package is used to include JSON content into markdown documents, by putting direct links to pages inside the [ESSE repository](https://github.com/Exabyte-io/exabyte-esse) instead of copying their contents in the main documentation. +The [markdown_include](https://github.com/mat3ra/markdown-include) package is used to include JSON content into markdown documents, by putting direct links to pages inside the [ESSE repository](https://github.com/mat3ra/exabyte-esse) instead of copying their contents in the main documentation. ```text === "Schema" - ``` json + ```json --8<-- "data/esse/schema/material.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/material.json" ``` ``` diff --git a/REVIEW.md b/REVIEW.md new file mode 100644 index 000000000..4aae18ee0 --- /dev/null +++ b/REVIEW.md @@ -0,0 +1,271 @@ +# Documentation Review Guide + +This file defines a repeatable review process for evaluating and improving +the Mat3ra documentation. It is designed for AI coding agents but can also +be used by human reviewers. + +Read [`WRITING-STYLE.md`](WRITING-STYLE.md) and [`AGENTS.md`](AGENTS.md) +first — they are the canonical references for prose style and agent +guidance respectively. This file builds on them. + +--- + +## Review Panel + +The review simulates a panel of three personas. Each brings a different +lens to the documentation: + +| ID | Persona | Focus | +|----|---------|-------| +| R1 | Experienced computational materials scientist (5–10 yr) | Technical accuracy, depth, correctness of methods and parameters | +| R2 | First-year postdoc in comp chem / AI for materials | Cross-linking, discoverability, ML workflow clarity | +| R3 | Last-year PhD student in comp. mat. sci. | Clarity for newcomers, step-by-step completeness, visual aids | + +When scoring, consider how each persona would rate the page independently, +then average. + +--- + +## Evaluation Criteria + +Score each page on a 0–10 scale across five criteria: + +### C1: Structural Consistency + +| Score | Description | +|-------|-------------| +| 9–10 | Numbered sections (`## 1.`, `### 1.1.`), imperative subheadings, no list directly under heading, proper H1/H2/H3 hierarchy | +| 7–8 | Numbered sections but inconsistent subheading style, or one heading-level violation | +| 5–6 | Unnumbered sections, gerund subheadings, lists under headings | +| 0–4 | No structure, flat document, missing H1 | + +### C2: Voice & Style + +| Score | Description | +|-------|-------------| +| 9–10 | Third-person/passive throughout, no forbidden words, no "you/your/we/our", acronyms introduced on first use | +| 7–8 | 1–2 isolated voice violations, otherwise clean | +| 5–6 | Frequent "we"/"you" usage, some forbidden words | +| 0–4 | Pervasive second-person, marketing tone | + +**Forbidden words** (from `WRITING-STYLE.md`): *Simply, Clearly, +Obviously, In fact, Furthermore, Moreover, Complete, In particular, +Really, Distinct, Various, Automatically, Finally*. + +### C3: Technical Depth + +| Score | Description | +|-------|-------------| +| 9–10 | Method explained with references, key parameters documented, expected results stated, comparison to experiment/literature where applicable | +| 7–8 | Method referenced but not explained, parameters listed without rationale | +| 5–6 | Procedural steps only, no "why" | +| 0–4 | Incomplete procedure, missing steps | + +### C4: Navigability & Cross-Linking + +| Score | Description | +|-------|-------------| +| 9–10 | All related tutorials cross-linked, prerequisite tutorials referenced, same-site relative links, cross-site macro links | +| 7–8 | Most links present, one or two missing cross-references | +| 5–6 | Minimal linking, isolated page | +| 0–4 | Broken links or no links at all | + +### C5: Media & Visuals + +| Score | Description | +|-------|-------------| +| 9–10 | All images have alt text + title, `.webp` format, video embeds present, screenshots current | +| 7–8 | Images present with alt text but PNG format, or one missing caption | +| 5–6 | Some images without alt/title, outdated screenshots | +| 0–4 | No images or broken image links | + +--- + +## How to Run a Review + +### Quick Prompt (paste into chat) + +``` +Review the documentation under `lang/en/docs/tutorials/` following the +process defined in REVIEW.md. Score each page on the 5 criteria (C1–C5), +produce a scorecard table, then refactor the lowest-scoring pages to bring +the average above 9/10. Work in rounds of 5–8 files, updating the +scorecard after each round. +``` + +### Full Prompt (for thorough multi-round review) + +``` +You are a review panel consisting of: + +(1) An experienced computational materials scientist with 5–10 years of + experience +(2) A first-year postdoc in comp chem / AI for materials +(3) A last-year PhD student in comp. mat. sci. + +Read REVIEW.md, WRITING-STYLE.md, and AGENTS.md. Then: + +1. Score every tutorial page under `lang/en/docs/tutorials/` on the 5 + criteria defined in REVIEW.md (C1–C5, 0–10 scale). +2. Produce a scorecard table grouped by section. +3. Identify the lowest-scoring pages and refactor them in rounds of 5–8 + files per round. +4. After each round, re-score the refactored pages and update the + scorecard. +5. Continue until the mean score across all pages is ≥ 9/10. +6. Produce a final scorecard and a walkthrough of all changes made. +``` + +### Scoping a Partial Review + +To review a specific section only: + +``` +Review only the files under `lang/en/docs/tutorials/dft/vibrational/` +following REVIEW.md. Score, refactor, and re-score. +``` + +--- + +## Style Checklist (Quick Reference) + +This distills the most common issues found during reviews. Check every +page against this list: + +- [ ] One H1 (`#`) on line 1; sub-headers use sentence case +- [ ] Sections numbered: `## 1.`, `### 1.1.` +- [ ] Subheadings are imperative ("Import the workflow", not "Importing + the workflow") +- [ ] No list starts directly under a heading — open with prose first +- [ ] Lists are flat (single level); images/code blocks are flush-left +- [ ] Third person / passive voice throughout; no "you", "your", "we", + "our" +- [ ] None of the forbidden words from `WRITING-STYLE.md` +- [ ] No acronyms in headings; acronyms introduced on first use in body +- [ ] Same-site links use relative paths +- [ ] Cross-site links use `{{ guide_url }}`, `{{ reference_url }}`, or + `{{ dev_url }}` macros +- [ ] All images have alt text and title: `![alt](path "title")` +- [ ] Prefer `.webp` images; each file < 1 MB +- [ ] Video embeds use the standard `
` pattern +- [ ] Version notes include "and later" (e.g., "5.2.1, 5.4.0, 6.0.0, + 6.3, and later") +- [ ] `mkdocs.yml` updated if pages were added, renamed, or moved + +--- + +## Baseline Scores (June 2025) + +These scores reflect the state after 12 rounds of review. Use them as a +starting point — re-score before making changes to account for any +subsequent edits. + +| Section | Pages | Mean Score | Status | +|---------|-------|------------|--------| +| DFT Electronic | 16 | 9.2 | ✅ Refactored | +| DFT Vibrational | 4 | 9.0 | ✅ Refactored | +| DFT Thermodynamic | 1 | 9.2 | ✅ Refactored | +| DFT Chemical | 2 | 9.2 | ✅ Refactored | +| DFT Optical | 1 | 9.2 | ✅ Refactored | +| DFT Addons | 2 | 9.2 | ✅ Refactored | +| Python ML | 5 | 9.1 | ✅ Refactored | +| ML (legacy + DeePMD) | 4 | 9.0 | ✅ Refactored | +| Reference / Overview | 4 | 8.4 | ✅ Refactored | +| **Tutorials overall** | **39** | **9.1** | | +| Templating | 2 | ~6.0 | ⬜ Not yet reviewed | +| General Functionality | 2 | ~5.5 | ⬜ Not yet reviewed | +| Materials | ~12 | ~6.5 | ⬜ Not yet reviewed | +| Materials (specific) | ~20 | ~6.0 | ⬜ Not yet reviewed | + +--- + +## Common Refactoring Patterns + +These patterns were applied repeatedly during the 12-round review. +Future agents should follow the same approach: + +### Voice Fixes + +```diff +-We will now calculate the band structure. ++The band structure is calculated as follows. + +-In this tutorial, we demonstrate how to... ++This tutorial demonstrates how to... + +-You should click the button. ++Click the button. / The button should be clicked. + +-our platform ++the platform +``` + +### Section Numbering + +```diff +-## Create Job ++## 1. Create the job + +-## Choose Workflow ++## 2. Select the workflow + +-### Examine Input Files ++### 2.1. Examine the input files +``` + +### Heading Style + +```diff +-### 1.1. Importing a workflow ++### 1.1. Import a workflow + +-### 4.2. Example Results ++### 4.2. Example results +``` + +### No List Under Heading + +```diff + ### 1.1. Import a bank workflow + +- - Navigate to the Workflows Bank page. +- - Search for the workflow. ++First, navigate to the Workflows Bank page. ++Then, search for the workflow. +``` + +### Version Notes + +```diff +- The present tutorial is written for Quantum ESPRESSO at versions +- 5.2.1, 5.4.0, 6.0.0 or 6.3. ++ This tutorial applies to Quantum ESPRESSO versions 5.2.1, 5.4.0, ++ 6.0.0, 6.3, and later. +``` + +### Verbose Workflow Details → Collapsible + +When a tutorial has extensive workflow/parameter documentation that +interrupts the procedural flow, move it into a collapsible block: + +```markdown +
+ Expand to view input parameter details + + ... detailed parameter documentation ... + +
+``` + +--- + +## Extending This Guide + +When adding new evaluation criteria or refactoring patterns: + +1. Add the criterion to the "Evaluation Criteria" section with score + descriptions. +2. Add a corresponding checklist item to "Style Checklist". +3. If a new refactoring pattern emerges, add a diff example to "Common + Refactoring Patterns". +4. Update the baseline scores table after each review cycle. diff --git a/WRITING-STYLE.md b/WRITING-STYLE.md index 50bceb442..453e369a5 100644 --- a/WRITING-STYLE.md +++ b/WRITING-STYLE.md @@ -38,6 +38,22 @@ The following list of words should be avoided: - Automatically - Finally +## Multi-Site Link Conventions + +The documentation is split into Guide, Reference, and Dev sub-sites. +Links within the same sub-site use relative paths. Links to a page in a +different sub-site use macro variables: + +- `{{ guide_url }}` — Platform Guide (tutorials, UI, how-tos) +- `{{ reference_url }}` — Concepts & Reference (models, methods, + properties) +- `{{ dev_url }}` — Developer Guide (REST API, infrastructure, storage) + +Pages that contain raw Jinja2 code examples (e.g., `{{ input.NAT }}`) +must wrap those blocks in `{% raw %}…{% endraw %}` so the macros plugin +does not consume them. Do not set `render_macros: false` if the page +also contains cross-site macro links. + ## Extra Styles and Sources The default [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) theme is extended, with additional css and javascript inside [extra](extra) folder. Any new files shall go into the same folder and shall be added to the corresponding section of [mkdocs.yml](mkdocs.yml). diff --git a/data/example-json/machine-learning-predict.json b/data/example-json/machine-learning-predict.json index 9c739e1ba..bf5d9f66b 100644 --- a/data/example-json/machine-learning-predict.json +++ b/data/example-json/machine-learning-predict.json @@ -8,7 +8,7 @@ }, "owner": { "_id": "5b143a4ecd313f405b314224", - "slug": "exabyte-io", + "slug": "mat3ra", "cls": "Account" }, "schemaVersion": "0.2.0", @@ -219,7 +219,7 @@ "CONTAINER": "production-20160630-cluster-001", "PROVIDER": "aws", "REGION": "us-east-1", - "NAME": "/cluster-001-share/groups/exabyte-io/exabyte-io-2021-ml-work/checking-ml-file-property-ec8ToqKwpWDGiyNCS/.job_context/target.pkl" + "NAME": "/cluster-001-share/groups/mat3ra/mat3ra-2021-ml-work/checking-ml-file-property-ec8ToqKwpWDGiyNCS/.job_context/target.pkl" } }, { @@ -230,7 +230,7 @@ "CONTAINER": "production-20160630-cluster-001", "PROVIDER": "aws", "REGION": "us-east-1", - "NAME": "/cluster-001-share/groups/exabyte-io/exabyte-io-2021-ml-work/checking-ml-file-property-ec8ToqKwpWDGiyNCS/.job_context/workflow_context_file_mapping" + "NAME": "/cluster-001-share/groups/mat3ra/mat3ra-2021-ml-work/checking-ml-file-property-ec8ToqKwpWDGiyNCS/.job_context/workflow_context_file_mapping" } }, { @@ -241,7 +241,7 @@ "CONTAINER": "production-20160630-cluster-001", "PROVIDER": "aws", "REGION": "us-east-1", - "NAME": "/cluster-001-share/groups/exabyte-io/exabyte-io-2021-ml-work/checking-ml-file-property-ec8ToqKwpWDGiyNCS/.job_context/descriptors.pkl" + "NAME": "/cluster-001-share/groups/mat3ra/mat3ra-2021-ml-work/checking-ml-file-property-ec8ToqKwpWDGiyNCS/.job_context/descriptors.pkl" } }, { @@ -252,7 +252,7 @@ "CONTAINER": "production-20160630-cluster-001", "PROVIDER": "aws", "REGION": "us-east-1", - "NAME": "/cluster-001-share/groups/exabyte-io/exabyte-io-2021-ml-work/checking-ml-file-property-ec8ToqKwpWDGiyNCS/.job_context/target_scaler.pkl" + "NAME": "/cluster-001-share/groups/mat3ra/mat3ra-2021-ml-work/checking-ml-file-property-ec8ToqKwpWDGiyNCS/.job_context/target_scaler.pkl" } }, { @@ -263,7 +263,7 @@ "CONTAINER": "production-20160630-cluster-001", "PROVIDER": "aws", "REGION": "us-east-1", - "NAME": "/cluster-001-share/groups/exabyte-io/exabyte-io-2021-ml-work/checking-ml-file-property-ec8ToqKwpWDGiyNCS/.job_context/descriptor_scaler.pkl" + "NAME": "/cluster-001-share/groups/mat3ra/mat3ra-2021-ml-work/checking-ml-file-property-ec8ToqKwpWDGiyNCS/.job_context/descriptor_scaler.pkl" } }, { @@ -274,7 +274,7 @@ "CONTAINER": "production-20160630-cluster-001", "PROVIDER": "aws", "REGION": "us-east-1", - "NAME": "/cluster-001-share/groups/exabyte-io/exabyte-io-2021-ml-work/checking-ml-file-property-ec8ToqKwpWDGiyNCS/.job_context/sklearn_mlp.pkl" + "NAME": "/cluster-001-share/groups/mat3ra/mat3ra-2021-ml-work/checking-ml-file-property-ec8ToqKwpWDGiyNCS/.job_context/sklearn_mlp.pkl" } }, { @@ -285,7 +285,7 @@ "CONTAINER": "production-20160630-cluster-001", "PROVIDER": "aws", "REGION": "us-east-1", - "NAME": "/cluster-001-share/groups/exabyte-io/exabyte-io-2021-ml-work/checking-ml-file-property-ec8ToqKwpWDGiyNCS/.job_context/predictions.pkl" + "NAME": "/cluster-001-share/groups/mat3ra/mat3ra-2021-ml-work/checking-ml-file-property-ec8ToqKwpWDGiyNCS/.job_context/predictions.pkl" } }, { @@ -296,7 +296,7 @@ "CONTAINER": "production-20160630-cluster-001", "PROVIDER": "aws", "REGION": "us-east-1", - "NAME": "/cluster-001-share/groups/exabyte-io/exabyte-io-2021-ml-work/checking-ml-file-property-ec8ToqKwpWDGiyNCS/.job_context/RMSE.pkl" + "NAME": "/cluster-001-share/groups/mat3ra/mat3ra-2021-ml-work/checking-ml-file-property-ec8ToqKwpWDGiyNCS/.job_context/RMSE.pkl" } } ], diff --git a/data/example-json/machine-learning-train.json b/data/example-json/machine-learning-train.json index c5bd24ba4..1555b4d0d 100644 --- a/data/example-json/machine-learning-train.json +++ b/data/example-json/machine-learning-train.json @@ -714,7 +714,7 @@ "hash": "c0c97c1dffb00371a5aec012306d9b4b", "owner": { "_id": "5b143a4ecd313f405b314224", - "slug": "exabyte-io", + "slug": "mat3ra", "cls": "Account" }, "creator": { diff --git a/extra/css/docs-agent.css b/extra/css/docs-agent.css new file mode 100644 index 000000000..233bd0c88 --- /dev/null +++ b/extra/css/docs-agent.css @@ -0,0 +1,244 @@ +/* Ask AI widget. + * + * Scoped under .docs-agent so nothing here can reach the documentation page, + * and sized in relative units so the panel stays usable at phone widths. + */ + +.docs-agent-launcher { + position: fixed; + right: 1.25rem; + bottom: 1.25rem; + z-index: 30; + padding: 0.65rem 1.15rem; + border: none; + border-radius: 2rem; + background: var(--md-primary-fg-color, #2094f3); + color: #fff; + font-size: 0.8rem; + font-weight: 600; + cursor: pointer; + box-shadow: 0 2px 10px rgba(0, 0, 0, 0.25); +} + +.docs-agent-launcher:hover { + filter: brightness(1.08); +} + +.docs-agent-panel { + position: fixed; + right: 1.25rem; + bottom: 5rem; + z-index: 31; + display: flex; + flex-direction: column; + width: min(26rem, calc(100vw - 2.5rem)); + max-height: min(34rem, calc(100vh - 8rem)); + border: 1px solid var(--md-default-fg-color--lightest, #e0e0e0); + border-radius: 0.5rem; + background: var(--md-default-bg-color, #fff); + box-shadow: 0 4px 24px rgba(0, 0, 0, 0.2); + overflow: hidden; +} + +.docs-agent-panel[hidden] { + display: none; +} + +.docs-agent-panel > header { + display: flex; + align-items: center; + justify-content: space-between; + padding: 0.6rem 0.9rem; + border-bottom: 1px solid var(--md-default-fg-color--lightest, #e0e0e0); +} + +.docs-agent-panel > header h2 { + margin: 0; + font-size: 0.85rem; + font-weight: 700; +} + +.docs-agent-close { + border: none; + background: none; + font-size: 1.2rem; + line-height: 1; + cursor: pointer; + color: var(--md-default-fg-color--light, #666); +} + +.docs-agent-log { + flex: 1; + overflow-y: auto; + padding: 0.75rem 0.9rem; + font-size: 0.75rem; + line-height: 1.6; +} + +.docs-agent-message { + margin-bottom: 0.9rem; +} + +.docs-agent-message p { + margin: 0 0 0.5rem; +} + +.docs-agent-message ul, +.docs-agent-message ol { + margin: 0 0 0.5rem; + padding-left: 1.15rem; +} + +.docs-agent-message pre { + margin: 0 0 0.5rem; + padding: 0.5rem 0.6rem; + border-radius: 0.25rem; + background: var(--md-code-bg-color, #f5f5f5); + /* Long commands scroll inside the block rather than widening the panel. */ + overflow-x: auto; +} + +.docs-agent-message code { + font-size: 0.9em; +} + +.docs-agent-user { + padding: 0.4rem 0.6rem; + border-radius: 0.35rem; + background: var(--md-code-bg-color, #f5f5f5); + font-weight: 600; +} + +.docs-agent-status { + color: var(--md-default-fg-color--light, #666); + font-style: italic; +} + +.docs-agent-sources { + margin-top: 0.5rem; + padding-top: 0.5rem; + border-top: 1px solid var(--md-default-fg-color--lightest, #e0e0e0); +} + +.docs-agent-sources p { + margin: 0 0 0.25rem; + font-weight: 600; + font-size: 0.7rem; + text-transform: uppercase; + letter-spacing: 0.03em; + color: var(--md-default-fg-color--light, #666); +} + +.docs-agent-sources ul { + margin: 0; + padding-left: 1.15rem; + word-break: break-word; +} + +.docs-agent-form { + display: flex; + gap: 0.4rem; + padding: 0.6rem 0.9rem; + border-top: 1px solid var(--md-default-fg-color--lightest, #e0e0e0); +} + +.docs-agent-form input { + flex: 1; + min-width: 0; + padding: 0.4rem 0.55rem; + border: 1px solid var(--md-default-fg-color--lighter, #ccc); + border-radius: 0.25rem; + background: var(--md-default-bg-color, #fff); + color: inherit; + font-size: 0.75rem; +} + +.docs-agent-form button { + padding: 0.4rem 0.8rem; + border: none; + border-radius: 0.25rem; + background: var(--md-primary-fg-color, #2094f3); + color: #fff; + font-size: 0.75rem; + font-weight: 600; + cursor: pointer; +} + +.docs-agent-form button:disabled { + opacity: 0.6; + cursor: default; +} + +.docs-agent-footer { + margin: 0; + padding: 0 0.9rem 0.6rem; + font-size: 0.62rem; + line-height: 1.4; + color: var(--md-default-fg-color--light, #666); +} + +@media screen and (max-width: 30rem) { + .docs-agent-panel { + right: 0.75rem; + left: 0.75rem; + bottom: 4.5rem; + width: auto; + } +} + +/* The Mat3ra mark next to the "Ask AI" label, in both the launcher and the + * panel header. Drawn in currentColor, so it inherits whatever it sits on. */ +.docs-agent-mark { + display: inline-flex; + align-items: center; + margin-right: 0.4rem; + vertical-align: -0.1em; +} + +.docs-agent-launcher .docs-agent-mark svg { + width: 0.85rem; + height: 0.85rem; +} + +.docs-agent-panel > header h2 { + display: flex; + align-items: center; +} + +/* Anything clickable reads as a link: the documentation's own link colour where + * the theme defines one, and a conventional blue anywhere else the widget is + * embedded. Source URLs are long, so they wrap rather than widen the panel. */ +.docs-agent-message a, +.docs-agent-term { + color: var(--md-typeset-a-color, #1a73e8); + text-decoration: none; + word-break: break-word; +} + +.docs-agent-message a:hover, +.docs-agent-message a:focus, +.docs-agent-term:hover, +.docs-agent-term:focus { + text-decoration: underline; +} + +/* Header controls: ending a conversation and closing the panel. */ +.docs-agent-controls { + display: flex; + align-items: center; + gap: 0.5rem; +} + +.docs-agent-clear { + border: none; + background: none; + padding: 0; + font-size: 0.68rem; + cursor: pointer; + color: var(--md-default-fg-color--light, #666); +} + +.docs-agent-clear:hover, +.docs-agent-clear:focus { + text-decoration: underline; +} diff --git a/extra/css/general.css b/extra/css/general.css index 37e8fc1b5..fc823c8d8 100644 --- a/extra/css/general.css +++ b/extra/css/general.css @@ -133,3 +133,69 @@ footer { color: grey; padding-top: 0.6em; } + +/* Hide line numbers in code blocks with only one line */ +.highlight:not(:has(.linenodiv .normal ~ .normal)) .linenos { + display: none; +} + +/* --------------------------------------------------------- * + * HOMEPAGE SECTION CARDS + * --------------------------------------------------------- */ +.section-cards { + display: grid; + grid-template-columns: repeat(3, 1fr); + gap: 1rem; + margin: 1.5rem 0; +} + +/* MkDocs wraps inside

— make

a transparent grid item */ +.section-cards > p { + margin: 0; + display: flex; +} + +.section-cards a.grid-card { + display: flex; + flex-direction: column; + flex: 1; + border: 1px solid var(--md-default-fg-color--lightest); + border-radius: 0.4rem; + padding: 1.2rem 1.4rem; + text-decoration: none; + color: var(--md-default-fg-color); + cursor: pointer; + transition: box-shadow 0.2s, border-color 0.2s, transform 0.15s; +} + +.section-cards a.grid-card:visited { + color: var(--md-default-fg-color); +} + +.section-cards a.grid-card:hover { + border-color: var(--md-primary-fg-color); + box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1); + transform: translateY(-2px); +} + +.section-cards a.grid-card strong { + display: block; + font-size: 1.15rem; + margin-bottom: 0.6rem; + padding-bottom: 0.6rem; + border-bottom: 1px solid var(--md-default-fg-color--lightest); +} + +.section-cards a.grid-card span { + display: block; + flex: 1; + font-size: 0.85rem; + color: var(--md-default-fg-color--light); + line-height: 1.5; +} + +@media (max-width: 900px) { + .section-cards { grid-template-columns: 1fr; } +} + + diff --git a/extra/css/tables.css b/extra/css/tables.css index 7ec4ba9f7..ce6dc4af1 100644 --- a/extra/css/tables.css +++ b/extra/css/tables.css @@ -1,3 +1,12 @@ .md-typeset .md-typeset__table { padding: 0 0.5rem; } + +/* Clickable row hover feedback */ +.md-typeset table tbody tr[style*="cursor"] { + transition: background-color 0.15s ease; +} + +.md-typeset table tbody tr[style*="cursor"]:hover { + background-color: var(--md-accent-fg-color--transparent); +} diff --git a/extra/js/clickable-rows.js b/extra/js/clickable-rows.js new file mode 100644 index 000000000..e5a4d06ff --- /dev/null +++ b/extra/js/clickable-rows.js @@ -0,0 +1,17 @@ +/** + * Make table rows clickable — when a row contains a single link, + * clicking anywhere on the row navigates to that link. + */ +document.addEventListener("DOMContentLoaded", function () { + document.querySelectorAll(".md-typeset table tbody tr").forEach(function (row) { + var links = row.querySelectorAll("a:not(.footnote-ref)"); + if (links.length === 1) { + row.style.cursor = "pointer"; + row.addEventListener("click", function (e) { + if (e.target.tagName !== "A") { + links[0].click(); + } + }); + } + }); +}); diff --git a/extra/js/docs-agent.js b/extra/js/docs-agent.js new file mode 100644 index 000000000..086177d19 --- /dev/null +++ b/extra/js/docs-agent.js @@ -0,0 +1,657 @@ +/** + * Ask AI — the documentation assistant widget. + * + * Written as a framework-free module so the platform application can mount the + * same code inside its own shell: + * + * DocsAgent.mount(element, { endpoint, tokenProvider }); + * + * On the documentation site it mounts itself into the page (see the bottom of + * this file). It never assumes MkDocs. + * + * Model output is rendered by building DOM nodes and setting textContent — + * `innerHTML` is never used for anything the model or the corpus produced. That + * makes injection structurally impossible rather than filtered, which is why + * this file carries a small Markdown renderer instead of pulling in a Markdown + * parser plus a sanitiser. + */ +(function (global) { + "use strict"; + + // Beta runs on the default Cloud Run hostname; a mat3ra.com subdomain + // replaces this before general availability. + var DEFAULT_ENDPOINT = "https://docs-agent-mmrcocqy3a-uc.a.run.app"; + var SESSION_KEY = "docsAgentSession"; + // Following a source link is a normal part of reading an answer, and the + // page reloads when it happens. The conversation therefore has to outlive + // the page, or every citation would end the exchange that produced it. + var SESSION_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; + var SESSION_MAX_MESSAGES = 20; // matches the service's own conversation cap + var SESSION_MAX_CHARS = 40000; + var ENDPOINT_OVERRIDE_KEY = "docsAgentEndpoint"; // localStorage, for local development + var MAX_QUESTION_CHARS = 4000; + + // ---------------------------------------------------------------- markdown + + // Bare URLs are matched too: the model lists its sources as plain URLs, and + // a source you cannot click is not much of a citation. + var INLINE_PATTERN = + /(`[^`]+`)|(\*\*[^*]+\*\*)|(\[[^\]]+\]\([^)\s]+\))|(https:\/\/[^\s)\],<>"']+)/; + + // Product term -> documentation page, fetched from the service. Built from + // the index there, so it can only ever name a page that exists. + var glossary = {}; + + var CANONICAL_DOCS_ORIGIN = "https://docs.mat3ra.com"; + // When the widget runs on a documentation build that is not production — a + // deploy preview, or a local server — citations should stay on the build + // being read. The corpus stores canonical production URLs, so following one + // otherwise leaves the preview entirely, which loses the conversation with + // it: storage is per-origin. Set only where the widget mounts itself onto a + // documentation site; the platform shell serves no documentation and must + // keep sending readers to the real thing. + var docsOrigin = ""; + + /** Append inline Markdown (code, bold, links, bare URLs) to a parent node. */ + function renderInline(parent, text) { + while (text) { + var match = INLINE_PATTERN.exec(text); + if (!match) { + parent.appendChild(document.createTextNode(text)); + return; + } + if (match.index > 0) { + parent.appendChild(document.createTextNode(text.slice(0, match.index))); + } + var token = match[0]; + if (token.charAt(0) === "`") { + var code = document.createElement("code"); + code.textContent = token.slice(1, -1); + parent.appendChild(code); + } else if (token.charAt(0) === "*") { + parent.appendChild(renderEmphasis(token.slice(2, -2))); + } else if (token.charAt(0) === "[") { + var split = token.indexOf("]("); + parent.appendChild(safeLink(token.slice(split + 2, -1), token.slice(1, split))); + } else { + // A bare URL. Trailing sentence punctuation is not part of it. + var url = token.replace(/[.,;:]+$/, ""); + parent.appendChild(safeLink(url, url)); + text = text.slice(match.index + url.length); + continue; + } + text = text.slice(match.index + token.length); + } + } + + /** + * Emphasised text, linked to the page that defines it when the glossary + * knows the term. + * + * Answers name platform features in bold — Materials Bank, Materials + * Designer — and those are exactly the things a reader wants to open. The + * mapping comes from the service's index rather than from the model, so a + * link here can never point at a page that does not exist. + */ + function renderEmphasis(label) { + var href = glossary[label.trim().toLowerCase()]; + if (!href) { + var strong = document.createElement("strong"); + strong.textContent = label; + return strong; + } + var link = safeLink(href, label); + if (link.tagName !== "A") return link; + link.className = "docs-agent-term"; + link.title = "Open the documentation for " + label; + var bold = document.createElement("strong"); + bold.appendChild(link); + return bold; + } + + /** Point a canonical documentation URL at the build currently being read. */ + function localDocsUrl(href) { + if (!docsOrigin || docsOrigin === CANONICAL_DOCS_ORIGIN) return href; + if (href.indexOf(CANONICAL_DOCS_ORIGIN + "/") !== 0) return href; + return docsOrigin + href.slice(CANONICAL_DOCS_ORIGIN.length); + } + + /** + * A link the model asked for. Only https targets become anchors; anything + * else (javascript:, data:, a relative path) is rendered as plain text, so + * a poisoned URL in the corpus cannot become a clickable trap. + */ + function safeLink(href, label) { + if (!/^https:\/\//i.test(href)) { + return document.createTextNode(label + " (" + href + ")"); + } + var anchor = document.createElement("a"); + anchor.href = localDocsUrl(href); + anchor.textContent = label; + // Navigate in place: a documentation link is the continuation of the + // answer, not a detour, and opening tabs behind the reader is a habit + // the documentation itself does not have. The conversation survives the + // navigation because it is stored — see the session functions below. + return anchor; + } + + /** Render the Markdown subset the agent produces into `target`. */ + function renderMarkdown(target, markdown) { + target.textContent = ""; + var lines = markdown.split("\n"); + var index = 0; + var list = null; + + function closeList() { + list = null; + } + + while (index < lines.length) { + var line = lines[index]; + + if (/^```/.test(line)) { + closeList(); + var buffer = []; + index += 1; + while (index < lines.length && !/^```/.test(lines[index])) { + buffer.push(lines[index]); + index += 1; + } + index += 1; + var pre = document.createElement("pre"); + var codeBlock = document.createElement("code"); + codeBlock.textContent = buffer.join("\n"); + pre.appendChild(codeBlock); + target.appendChild(pre); + continue; + } + + var heading = /^(#{1,6})\s+(.*)$/.exec(line); + if (heading) { + closeList(); + var level = Math.min(heading[1].length + 2, 6); // never outrank the page's own h1/h2 + var headingNode = document.createElement("h" + level); + renderInline(headingNode, heading[2]); + target.appendChild(headingNode); + index += 1; + continue; + } + + var bullet = /^\s*[-*]\s+(.*)$/.exec(line); + var numbered = /^\s*\d+\.\s+(.*)$/.exec(line); + if (bullet || numbered) { + var wanted = bullet ? "UL" : "OL"; + if (!list || list.tagName !== wanted) { + list = document.createElement(bullet ? "ul" : "ol"); + target.appendChild(list); + } + var item = document.createElement("li"); + renderInline(item, (bullet || numbered)[1]); + list.appendChild(item); + index += 1; + continue; + } + + if (!line.trim()) { + closeList(); + index += 1; + continue; + } + + closeList(); + var paragraph = document.createElement("p"); + renderInline(paragraph, line); + target.appendChild(paragraph); + index += 1; + } + } + + // --------------------------------------------------------------- streaming + + /** Read an SSE body, calling onEvent(name, data) per event. */ + function readEvents(response, onEvent) { + var reader = response.body.getReader(); + var decoder = new TextDecoder(); + var buffer = ""; + + function pump() { + return reader.read().then(function (result) { + if (result.done) return; + buffer += decoder.decode(result.value, { stream: true }); + var blocks = buffer.split("\n\n"); + buffer = blocks.pop(); + blocks.forEach(function (block) { + var name = ""; + var payload = ""; + block.split("\n").forEach(function (line) { + if (line.indexOf("event: ") === 0) name = line.slice(7); + else if (line.indexOf("data: ") === 0) payload += line.slice(6); + }); + if (!name) return; + var data = {}; + try { + data = payload ? JSON.parse(payload) : {}; + } catch (error) { + return; + } + onEvent(name, data); + }); + return pump(); + }); + } + return pump(); + } + + // ---------------------------------------------------------------- branding + + // The Mat3ra mark, inlined and drawn in currentColor so it works on the + // purple launcher and on the panel header without shipping two assets or + // depending on a path that only exists on the documentation site. + var LOGO = + '"; + + /** A label preceded by the mark. Built as nodes; the SVG is our own markup. */ + function brandedLabel(text) { + var fragment = document.createDocumentFragment(); + var holder = document.createElement("span"); + holder.className = "docs-agent-mark"; + holder.innerHTML = LOGO; // trusted constant above, never model output + fragment.appendChild(holder); + fragment.appendChild(document.createTextNode(text)); + return fragment; + } + + // ------------------------------------------------------------------ widget + + function DocsAgentWidget(root, options) { + this.endpoint = (options && options.endpoint) || resolveEndpoint(); + this.tokenProvider = (options && options.tokenProvider) || null; + if (options && options.docsOrigin) docsOrigin = options.docsOrigin; + this.messages = []; // conversation, in memory only + this.busy = false; + this.build(root); + } + + DocsAgentWidget.prototype.build = function (root) { + var self = this; + + var panel = document.createElement("section"); + panel.className = "docs-agent-panel"; + panel.setAttribute("role", "dialog"); + panel.setAttribute("aria-label", "Ask the documentation assistant"); + panel.hidden = true; + + var header = document.createElement("header"); + var title = document.createElement("h2"); + title.appendChild(brandedLabel("Ask AI")); + // A conversation that survives navigation also has to be endable. + var clear = document.createElement("button"); + clear.type = "button"; + clear.className = "docs-agent-clear"; + clear.textContent = "New chat"; + var close = document.createElement("button"); + close.type = "button"; + close.className = "docs-agent-close"; + close.setAttribute("aria-label", "Close"); + close.textContent = "×"; + var controls = document.createElement("div"); + controls.className = "docs-agent-controls"; + controls.appendChild(clear); + controls.appendChild(close); + header.appendChild(title); + header.appendChild(controls); + + var log = document.createElement("div"); + log.className = "docs-agent-log"; + log.setAttribute("aria-live", "polite"); + + var form = document.createElement("form"); + form.className = "docs-agent-form"; + var input = document.createElement("input"); + input.type = "text"; + input.placeholder = "Ask about the Mat3ra platform…"; + input.setAttribute("aria-label", "Your question"); + input.maxLength = MAX_QUESTION_CHARS; + var send = document.createElement("button"); + send.type = "submit"; + send.textContent = "Ask"; + form.appendChild(input); + form.appendChild(send); + + var footer = document.createElement("p"); + footer.className = "docs-agent-footer"; + footer.textContent = + "Answers are generated from the documentation and can be wrong. Questions are " + + "logged to improve the assistant, and this conversation is kept in your browser " + + "until you start a new chat."; + + panel.appendChild(header); + panel.appendChild(log); + panel.appendChild(form); + panel.appendChild(footer); + + var launcher = document.createElement("button"); + launcher.type = "button"; + launcher.className = "docs-agent-launcher"; + launcher.appendChild(brandedLabel("Ask AI")); + launcher.setAttribute("aria-expanded", "false"); + + root.appendChild(launcher); + root.appendChild(panel); + + this.panel = panel; + this.log = log; + this.input = input; + this.send = send; + this.launcher = launcher; + + launcher.addEventListener("click", function () { + self.toggle(panel.hidden); + }); + close.addEventListener("click", function () { + self.toggle(false); + }); + form.addEventListener("submit", function (event) { + event.preventDefault(); + var question = input.value.trim(); + if (question && !self.busy) { + input.value = ""; + self.ask(question); + } + }); + panel.addEventListener("keydown", function (event) { + if (event.key === "Escape") self.toggle(false); + }); + clear.addEventListener("click", function () { + self.clearSession(); + self.log.textContent = ""; + self.greet(); + self.saveSession(); + self.input.focus(); + }); + + // Redraw the stored conversation once the glossary is available, so + // restored answers get the same links a fresh one would. + this.loadGlossary().then(function () { + self.restoreSession(); + }); + }; + + /** Fetch the term-to-page map once. Answers render fine without it. */ + DocsAgentWidget.prototype.loadGlossary = function () { + return fetch(this.endpoint + "/glossary") + .then(function (response) { + return response.ok ? response.json() : null; + }) + .then(function (data) { + if (data && data.terms) glossary = data.terms; + }) + .catch(function () { + /* Terms simply stay unlinked. */ + }); + }; + + // ------------------------------------------------------------------ session + + /** + * The conversation, kept in the browser so it survives navigation. + * + * Answers cite documentation pages and those links now open in place, so + * without this every citation would discard the exchange that produced it. + * Nothing is sent anywhere by storing it: this is the same text the page + * already displays, on the reader's own machine, and the panel offers a way + * to clear it. + */ + DocsAgentWidget.prototype.saveSession = function () { + try { + var messages = this.messages.slice(-SESSION_MAX_MESSAGES); + while ( + messages.length && + messages.reduce(function (total, m) { + return total + m.content.length; + }, 0) > SESSION_MAX_CHARS + ) { + messages.shift(); + } + global.localStorage.setItem( + SESSION_KEY, + JSON.stringify({ + version: 1, + updated: Date.now(), + open: !this.panel.hidden, + messages: messages, + }) + ); + } catch (error) { + /* Storage full or disabled: the widget still works for this page. */ + } + }; + + DocsAgentWidget.prototype.readSession = function () { + try { + var stored = JSON.parse(global.localStorage.getItem(SESSION_KEY) || "null"); + if (!stored || stored.version !== 1 || !Array.isArray(stored.messages)) return null; + if (Date.now() - (stored.updated || 0) > SESSION_MAX_AGE_MS) { + this.clearSession(); + return null; + } + return stored; + } catch (error) { + return null; + } + }; + + DocsAgentWidget.prototype.clearSession = function () { + this.messages = []; + try { + global.localStorage.removeItem(SESSION_KEY); + } catch (error) { + /* Nothing to clear. */ + } + }; + + /** Redraw a stored conversation and reopen the panel if it was open. */ + DocsAgentWidget.prototype.restoreSession = function () { + var stored = this.readSession(); + if (!stored || !stored.messages.length) { + this.greet(); + return; + } + this.messages = stored.messages; + var self = this; + stored.messages.forEach(function (message) { + if (message.role === "user") { + self.bubble("user", message.content); + } else { + renderMarkdown(self.bubble("assistant", ""), message.content); + } + }); + this.scroll(); + if (stored.open) this.toggle(true); + }; + + DocsAgentWidget.prototype.toggle = function (open) { + this.panel.hidden = !open; + this.launcher.setAttribute("aria-expanded", String(open)); + if (open) this.input.focus(); + else this.launcher.focus(); + // Remember whether it was open, so following a link does not close it. + this.saveSession(); + }; + + DocsAgentWidget.prototype.greet = function () { + var intro = document.createElement("div"); + intro.className = "docs-agent-message docs-agent-assistant"; + renderMarkdown( + intro, + "Ask a question about the Mat3ra platform. Answers come from this documentation, with links to the pages used." + ); + this.log.appendChild(intro); + }; + + DocsAgentWidget.prototype.bubble = function (role, text) { + var node = document.createElement("div"); + node.className = "docs-agent-message docs-agent-" + role; + if (text) node.textContent = text; + this.log.appendChild(node); + this.scroll(); + return node; + }; + + DocsAgentWidget.prototype.scroll = function () { + this.log.scrollTop = this.log.scrollHeight; + }; + + DocsAgentWidget.prototype.ask = function (question) { + var self = this; + this.busy = true; + this.send.disabled = true; + this.bubble("user", question); + this.messages.push({ role: "user", content: question }); + this.saveSession(); + + var answerNode = this.bubble("assistant", ""); + var statusNode = document.createElement("p"); + statusNode.className = "docs-agent-status"; + statusNode.textContent = "Searching the documentation…"; + answerNode.appendChild(statusNode); + + var answer = ""; + var pending = null; + + function draw() { + pending = null; + renderMarkdown(answerNode, answer); + self.scroll(); + } + + Promise.resolve(this.tokenProvider ? this.tokenProvider() : null) + .then(function (token) { + var headers = { "Content-Type": "application/json" }; + if (token) headers.Authorization = "Bearer " + token; + return fetch(self.endpoint + "/chat", { + method: "POST", + headers: headers, + body: JSON.stringify({ messages: self.messages }), + }); + }) + .then(function (response) { + if (!response.ok || !response.body) { + throw new Error("http " + response.status); + } + return readEvents(response, function (name, data) { + if (name === "status") { + statusNode.textContent = data.query + ? "Searching the documentation: " + data.query + : "Searching the documentation…"; + } else if (name === "text") { + if (statusNode.parentNode) statusNode.remove(); + answer += data.text || ""; + if (!pending) pending = requestAnimationFrame(draw); + } else if (name === "sources") { + if (pending) cancelAnimationFrame(pending); + draw(); + self.renderSources(answerNode, data.urls || [], answer); + } else if (name === "error") { + if (statusNode.parentNode) statusNode.remove(); + answer += "\n\n" + (data.message || "Something went wrong."); + draw(); + } + }); + }) + .catch(function () { + if (statusNode.parentNode) statusNode.remove(); + answer += + "\n\nThe assistant is unavailable right now. The documentation search box above still works."; + draw(); + }) + .then(function () { + if (answer) self.messages.push({ role: "assistant", content: answer }); + self.saveSession(); + self.busy = false; + self.send.disabled = false; + self.input.focus(); + }); + }; + + /** + * Show the pages retrieval touched — but only when the answer has not + * already cited its own. + * + * These two lists are not the same thing: the answer cites the pages the + * model *used*, while this event carries everything retrieval *returned*, + * which routinely includes near-misses the model correctly ignored. + * Printing both duplicates the useful list and dresses the near-misses up + * as sources, so the answer's own citations win whenever it has them. + */ + DocsAgentWidget.prototype.renderSources = function (parent, urls, answer) { + if (!urls.length || /(^|\n)\s*(#+\s*)?\**sources\**\s*:?/i.test(answer)) return; + var wrapper = document.createElement("div"); + wrapper.className = "docs-agent-sources"; + var label = document.createElement("p"); + label.textContent = "Pages searched"; + var list = document.createElement("ul"); + urls.forEach(function (url) { + var item = document.createElement("li"); + item.appendChild(safeLink(url, url.replace(/^https:\/\/docs\.mat3ra\.com\//, ""))); + list.appendChild(item); + }); + wrapper.appendChild(label); + wrapper.appendChild(list); + parent.appendChild(wrapper); + this.scroll(); + }; + + // ------------------------------------------------------------------ mounting + + function resolveEndpoint() { + try { + return global.localStorage.getItem(ENDPOINT_OVERRIDE_KEY) || DEFAULT_ENDPOINT; + } catch (error) { + return DEFAULT_ENDPOINT; + } + } + + var DocsAgent = { + mount: function (element, options) { + return new DocsAgentWidget(element, options || {}); + }, + }; + + /** + * Auto-mount on the documentation site, but only once the service answers + * its health check. A documentation page must never show a launcher that + * leads nowhere, and must never break because the assistant is down. + */ + function autoMount() { + var endpoint = resolveEndpoint(); + fetch(endpoint + "/health", { method: "GET" }) + .then(function (response) { + if (!response.ok) throw new Error("unhealthy"); + var host = document.createElement("div"); + host.className = "docs-agent"; + document.body.appendChild(host); + // Self-mounting means this page *is* a documentation build, so + // citations should stay on it rather than jumping to production. + DocsAgent.mount(host, { endpoint: endpoint, docsOrigin: global.location.origin }); + }) + .catch(function () { + /* Service unavailable: leave the page exactly as it was. */ + }); + } + + global.DocsAgent = DocsAgent; + global.DocsAgent._internals = { renderMarkdown: renderMarkdown, safeLink: safeLink }; + + if (typeof document !== "undefined" && !global.DOCS_AGENT_NO_AUTOMOUNT) { + if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", autoMount); + } else { + autoMount(); + } + } +})(typeof window !== "undefined" ? window : this); diff --git a/extra/js/search-hint.js b/extra/js/search-hint.js new file mode 100644 index 000000000..487ca91c8 --- /dev/null +++ b/extra/js/search-hint.js @@ -0,0 +1,77 @@ +/** + * Cross-site search hint for MkDocs Material. + * + * On sub-sites (/guide/, /reference/, /dev/) the built-in search only + * indexes pages belonging to that sub-site. This script adds a small + * hint below the search results telling the user they can search the + * full documentation from the top-level site. + */ +(function () { + "use strict"; + + // Map of sub-site URL prefixes to their display names (from site_name in each mkdocs config) + var subsites = { + "/guide": "Tutorials", + "/interface": "User Interface", + "/reference": "Concepts & Reference", + "/resources": "Platform Resources", + "/developers": "Software Developers", + "/command-line": "Command-Line Interface", + "/standards": "Data Standards", + }; + + // Detect current sub-site + var path = window.location.pathname; + var siteLabel = null; + var prefixes = Object.keys(subsites); + for (var i = 0; i < prefixes.length; i++) { + if (path.startsWith(prefixes[i])) { + siteLabel = subsites[prefixes[i]]; + break; + } + } + if (!siteLabel) return; // On the root site — no hint needed + + // Root URL — works both in production and on localhost + var rootUrl = window.location.origin + "/"; + + // Wait for the search dialog to appear in the DOM. MkDocs Material + // creates it lazily, so we use a MutationObserver. + var hintInjected = false; + + function injectHint(searchOutput) { + if (hintInjected) return; + hintInjected = true; + + var hint = document.createElement("div"); + hint.className = "md-search-result__hint"; + hint.style.cssText = + "padding: 0.8rem 1rem; font-size: 0.7rem; color: var(--md-default-fg-color--light);" + + "border-top: 1px solid var(--md-default-fg-color--lightest); text-align: center;"; + + hint.innerHTML = + "🔍 Search is limited to " + siteLabel + ". " + + '' + + "Search all documentation →"; + + searchOutput.appendChild(hint); + } + + // Observe the document for the search result container + var observer = new MutationObserver(function (mutations) { + var searchOutput = document.querySelector(".md-search-result"); + if (searchOutput) { + injectHint(searchOutput); + observer.disconnect(); + } + }); + + observer.observe(document.body, { childList: true, subtree: true }); + + // Also try immediately in case it's already present + var existing = document.querySelector(".md-search-result"); + if (existing) { + injectHint(existing); + observer.disconnect(); + } +})(); diff --git a/images/accounts/accounts-list.png b/images/accounts/accounts-list.png deleted file mode 100644 index 33ad342cb..000000000 --- a/images/accounts/accounts-list.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:e9b39c5915179ec6cc93ebff7e31a493ca6905813c48ac954eeaa38630a929d1 -size 86540 diff --git a/images/accounts/accounts-list.webp b/images/accounts/accounts-list.webp new file mode 100644 index 000000000..9e917bbf8 --- /dev/null +++ b/images/accounts/accounts-list.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e2f27d62a62834de2cfc3a5443c0700c4ba761afacb601e54fc00ec74877a476 +size 50982 diff --git a/images/getting-started/run-first-simulation-create-job.webp b/images/getting-started/run-first-simulation-create-job.webp new file mode 100644 index 000000000..920134df0 --- /dev/null +++ b/images/getting-started/run-first-simulation-create-job.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e136f7c2d3cd83211c624f552fd0732c728a668ee6b269a8f090e65e2a2a4f84 +size 103876 diff --git a/images/getting-started/run-first-simulation-edit-unit.webp b/images/getting-started/run-first-simulation-edit-unit.webp new file mode 100644 index 000000000..f7d815a1d --- /dev/null +++ b/images/getting-started/run-first-simulation-edit-unit.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:dcadeda73b5699f88dcc57ffb86484cf83d84a5a8f82c53eda1cbe221480e71e +size 46782 diff --git a/images/getting-started/run-first-simulation-import-workflow.gif b/images/getting-started/run-first-simulation-import-workflow.gif old mode 100755 new mode 100644 index 4a4910129..ce9e830e5 --- a/images/getting-started/run-first-simulation-import-workflow.gif +++ b/images/getting-started/run-first-simulation-import-workflow.gif @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:fa9eabac256bd6459d1822944da1d9ebcc286dfcdb8b46c0c6003e49a8bee4a3 -size 642376 +oid sha256:1e1421681a8ce2b8135b6d7ef94e72fe922e61e8afc7d348d0d5402e398e2bd9 +size 1558454 diff --git a/images/getting-started/run-first-simulation-submit-view-output.gif b/images/getting-started/run-first-simulation-submit-view-output.gif deleted file mode 100644 index 9e3729984..000000000 --- a/images/getting-started/run-first-simulation-submit-view-output.gif +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:5a06fc7e0515306d61253accda2a96c3fa88e6eca8a023e56996aca1e2c21ce7 -size 1581803 diff --git a/images/getting-started/run-first-simulation-tab-1-materials.png b/images/getting-started/run-first-simulation-tab-1-materials.png deleted file mode 100644 index 52e9e287f..000000000 --- a/images/getting-started/run-first-simulation-tab-1-materials.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:60bcda17d5e0ddcc02bc5cae6ceca09dca95790f55fabfd0476dcb4aa0759c4e -size 56812 diff --git a/images/getting-started/run-first-simulation-tab-1-materials.webp b/images/getting-started/run-first-simulation-tab-1-materials.webp new file mode 100644 index 000000000..3c7ecde65 --- /dev/null +++ b/images/getting-started/run-first-simulation-tab-1-materials.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:096b4df29d5567df22e0383f5a57ea50267e18f842c6320e50a51e3fca074df8 +size 47634 diff --git a/images/getting-started/run-first-simulation-tab-2-workflow.gif b/images/getting-started/run-first-simulation-tab-2-workflow.gif deleted file mode 100644 index 86dfff5af..000000000 --- a/images/getting-started/run-first-simulation-tab-2-workflow.gif +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:3411367e75411fa98c88eb5bc4487f51072748a2ec2f1829f9052e7fd1bd61e7 -size 2456106 diff --git a/images/getting-started/run-first-simulation-tab-2-workflow.webp b/images/getting-started/run-first-simulation-tab-2-workflow.webp new file mode 100644 index 000000000..df87ece99 --- /dev/null +++ b/images/getting-started/run-first-simulation-tab-2-workflow.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:13336fe354d133f82c161a3ad050aeabb26f82756e00aa1e63675dd753c4ac1f +size 49070 diff --git a/images/getting-started/run-first-simulation-tab-3-compute.png b/images/getting-started/run-first-simulation-tab-3-compute.png deleted file mode 100644 index f1c7cabeb..000000000 --- a/images/getting-started/run-first-simulation-tab-3-compute.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:23c5a3093b6ac0e8c94b2087a08e0dbf5d1cb2ca4fcbf0403df60a1beef69a5d -size 41430 diff --git a/images/getting-started/run-first-simulation-tab-3-compute.webp b/images/getting-started/run-first-simulation-tab-3-compute.webp new file mode 100644 index 000000000..05a0f8bbb --- /dev/null +++ b/images/getting-started/run-first-simulation-tab-3-compute.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:48bca09e03c030ad0eb08075435e8aeb837b90e5fcc4a6545bec26d2f6d3c419 +size 49612 diff --git a/images/getting-started/run-first-simulation-view-bandstructure.png b/images/getting-started/run-first-simulation-view-bandstructure.png deleted file mode 100644 index 64ff7df07..000000000 --- a/images/getting-started/run-first-simulation-view-bandstructure.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:45db7dbe32b756b3156ba6131e04ae44844db5f35bd8461e0239e9eabddea15b -size 105677 diff --git a/images/getting-started/run-first-simulation-view-bandstructure.webp b/images/getting-started/run-first-simulation-view-bandstructure.webp new file mode 100644 index 000000000..0ab29cb13 --- /dev/null +++ b/images/getting-started/run-first-simulation-view-bandstructure.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:50da4b90baa9a605de98f554ae581afa4f4b08d57f36a3ec07e39f910859bfb6 +size 68988 diff --git a/images/getting-started/run-first-simulation-view-results.gif b/images/getting-started/run-first-simulation-view-results.gif deleted file mode 100644 index ceaff30b3..000000000 --- a/images/getting-started/run-first-simulation-view-results.gif +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:ca2165723897af19ea2f8e81667ad4219c24e1c552b977fd76e1fb00cafee009 -size 1350745 diff --git a/images/jobs-designer/header-jobs-designer.png b/images/jobs-designer/header-jobs-designer.png deleted file mode 100644 index 1fd8c92d3..000000000 --- a/images/jobs-designer/header-jobs-designer.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:a40d9b97a40f9bda10c142c8f33313a6a0c2e9d4cdf35f446124f95c168b777b -size 11362 diff --git a/images/jobs-designer/header-jobs-designer.webp b/images/jobs-designer/header-jobs-designer.webp new file mode 100644 index 000000000..d7c62ea7d --- /dev/null +++ b/images/jobs-designer/header-jobs-designer.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a29b5f00bb5796bc5e3482912d6ab24007f49cac5fbca31f6398a1988a75fd8f +size 87750 diff --git a/images/jobs-designer/jobs-designer.png b/images/jobs-designer/jobs-designer.png deleted file mode 100644 index baf76b14f..000000000 --- a/images/jobs-designer/jobs-designer.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:8ba6e9a0c257192630d10e322dd6da9db9dd477784527822c70dec135b1cfc77 -size 136272 diff --git a/images/jobs-designer/jobs-designer.webp b/images/jobs-designer/jobs-designer.webp new file mode 100644 index 000000000..f379440a2 --- /dev/null +++ b/images/jobs-designer/jobs-designer.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c84e6754e2f2ac3338a268029ce7d45094f45e4a313668c6fbf73182e3bb9ecb +size 87310 diff --git a/images/jobs-designer/select-job-dialog.png b/images/jobs-designer/select-job-dialog.png deleted file mode 100644 index ef02f6b38..000000000 --- a/images/jobs-designer/select-job-dialog.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:ac14be12f87c0daa0e878c7df639c69b51ec01884fd1ea7bcdb6c4d7d1bbe645 -size 171351 diff --git a/images/jobs-designer/select-parent-job-dialog.webp b/images/jobs-designer/select-parent-job-dialog.webp new file mode 100644 index 000000000..b5f129f04 --- /dev/null +++ b/images/jobs-designer/select-parent-job-dialog.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:355cf9df2392072316f7008587009d4c39de9c3ab4a43aeebfa273a71a25be61 +size 80030 diff --git a/images/jupyterlite/auth-browser-confirm.webp b/images/jupyterlite/auth-browser-confirm.webp new file mode 100644 index 000000000..a4dfafe46 --- /dev/null +++ b/images/jupyterlite/auth-browser-confirm.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2a390b7f0295df3739922f5dcfc27350b723efd6a483cf5b0533501f6403aed2 +size 20206 diff --git a/images/jupyterlite/auth-browser-signin.webp b/images/jupyterlite/auth-browser-signin.webp new file mode 100644 index 000000000..fb007d8f4 --- /dev/null +++ b/images/jupyterlite/auth-browser-signin.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d71cd4724bf8e60edd01f78e3756301d7c9c5134e8e221dab92dd59eaf1c1553 +size 19148 diff --git a/images/jupyterlite/auth-jupyterlite-notebook.gif b/images/jupyterlite/auth-jupyterlite-notebook.gif new file mode 100644 index 000000000..37c4bbdc2 --- /dev/null +++ b/images/jupyterlite/auth-jupyterlite-notebook.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:21da40f4cb34d051691a0275fe4903675cc78bb0b4d79c4052f11e4de6b4f778 +size 297193 diff --git a/images/jupyterlite/auth-notebook-code.webp b/images/jupyterlite/auth-notebook-code.webp new file mode 100644 index 000000000..976f6f75b --- /dev/null +++ b/images/jupyterlite/auth-notebook-code.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6068db707d536c4a4f49ed62643f4d6c7006e9bf7edc6d2742ae899ad21e36cd +size 16904 diff --git a/images/jupyterlite/auth-success.webp b/images/jupyterlite/auth-success.webp new file mode 100644 index 000000000..c0eeb48ad --- /dev/null +++ b/images/jupyterlite/auth-success.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:26ed4d98490bcc906bd236fb171fd38209a93ae430968469b4c6d410d94d660b +size 10404 diff --git a/images/logo/favicon.ico b/images/logo/favicon.ico deleted file mode 100644 index e8f843742..000000000 Binary files a/images/logo/favicon.ico and /dev/null differ diff --git a/images/logo/favicon.svg b/images/logo/favicon.svg new file mode 100644 index 000000000..1c189c0a9 --- /dev/null +++ b/images/logo/favicon.svg @@ -0,0 +1,19 @@ + + + + + + + + diff --git a/images/properties-directory/bang-gap-energy.png b/images/properties-directory/band-gap-energy.png similarity index 100% rename from images/properties-directory/bang-gap-energy.png rename to images/properties-directory/band-gap-energy.png diff --git a/images/tutorials/defect_formation_energy/defect-formation-energy-result.png b/images/tutorials/defect_formation_energy/defect-formation-energy-result.png new file mode 100644 index 000000000..e356dfe22 --- /dev/null +++ b/images/tutorials/defect_formation_energy/defect-formation-energy-result.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:70180006c89135daef139d72a33407dc87f3450fa31fb0fd3e30a9a4616f8934 +size 206897 diff --git a/images/tutorials/formation_energy/formation-energy-assign-te-source-unit.png b/images/tutorials/formation_energy/formation-energy-assign-te-source-unit.png new file mode 100644 index 000000000..a539e90a4 --- /dev/null +++ b/images/tutorials/formation_energy/formation-energy-assign-te-source-unit.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:09e9109453ee467f34e6f69ea69a5929702dc60fa53d734ad59d4743a1dc4b9c +size 271588 diff --git a/images/tutorials/formation_energy/formation-energy-assign-te-source.png b/images/tutorials/formation_energy/formation-energy-assign-te-source.png new file mode 100644 index 000000000..4b928ff69 --- /dev/null +++ b/images/tutorials/formation_energy/formation-energy-assign-te-source.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3761262e94f707ba82e59d75093861a436bbda0b074fbd8c97156287111c76f9 +size 289851 diff --git a/images/tutorials/formation_energy/formation-energy-compute-tab.png b/images/tutorials/formation_energy/formation-energy-compute-tab.png new file mode 100644 index 000000000..0e821e02a --- /dev/null +++ b/images/tutorials/formation_energy/formation-energy-compute-tab.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:515dff6fb61ed5ebad3a5ad2b384aa7b351a50ba5ef0139480f1ae56e95e8ccc +size 183599 diff --git a/images/tutorials/formation_energy/formation-energy-material-selection.png b/images/tutorials/formation_energy/formation-energy-material-selection.png new file mode 100644 index 000000000..dea4acb73 --- /dev/null +++ b/images/tutorials/formation_energy/formation-energy-material-selection.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4b0293dc7efffd41bc3ea3400ec6db9cb8d8fd85c0d34211917c32b757f3fe81 +size 119936 diff --git a/images/tutorials/formation_energy/formation-energy-parameters.png b/images/tutorials/formation_energy/formation-energy-parameters.png new file mode 100644 index 000000000..8141f7b47 --- /dev/null +++ b/images/tutorials/formation_energy/formation-energy-parameters.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7679e55137b77f54539ba5fdaead77d97afa9647a9f8be1be28c88544d7969f0 +size 168457 diff --git a/images/tutorials/formation_energy/formation-energy-workflow-selection.png b/images/tutorials/formation_energy/formation-energy-workflow-selection.png new file mode 100644 index 000000000..761b0020e --- /dev/null +++ b/images/tutorials/formation_energy/formation-energy-workflow-selection.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e8090b405848f59f721284fd732ea040914b8371e1436ab18fd897751ee27318 +size 133348 diff --git a/images/tutorials/interfacial_energy/interfacial-energy-material-selection.png b/images/tutorials/interfacial_energy/interfacial-energy-material-selection.png new file mode 100644 index 000000000..42ce0612e --- /dev/null +++ b/images/tutorials/interfacial_energy/interfacial-energy-material-selection.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:13f2d44609dbe2c31e5e288334d8657d0db13c2f962569bf300b17cabd8794e2 +size 148498 diff --git a/images/tutorials/interfacial_energy/interfacial-energy-parameters.png b/images/tutorials/interfacial_energy/interfacial-energy-parameters.png new file mode 100644 index 000000000..eb014465b --- /dev/null +++ b/images/tutorials/interfacial_energy/interfacial-energy-parameters.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e29fe0b2e0e27cf73e50b46404380b85b301ce81f0074427d907d358f8bdab6b +size 195597 diff --git a/images/tutorials/interfacial_energy/interfacial-energy-result.png b/images/tutorials/interfacial_energy/interfacial-energy-result.png new file mode 100644 index 000000000..37e25c536 --- /dev/null +++ b/images/tutorials/interfacial_energy/interfacial-energy-result.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8968a07afdb3170e8a676b0105dd417c853e3399d3e4ecc4699fd66f9431e71c +size 223617 diff --git a/images/tutorials/interfacial_energy/interfacial-energy-workflow-selection.png b/images/tutorials/interfacial_energy/interfacial-energy-workflow-selection.png new file mode 100644 index 000000000..7927408d1 --- /dev/null +++ b/images/tutorials/interfacial_energy/interfacial-energy-workflow-selection.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7848e0f3507423fc2e334ef5aa226ec79f466c1ba388f2bf29e721e05112b69f +size 143623 diff --git a/images/tutorials/materials/defects/defect_creation_point_substitution_graphene/4-3d-editor-coordinates.webp b/images/tutorials/materials/defects/defect_creation_point_substitution_graphene/4-3d-editor-coordinates.webp new file mode 100644 index 000000000..30488f002 --- /dev/null +++ b/images/tutorials/materials/defects/defect_creation_point_substitution_graphene/4-3d-editor-coordinates.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c33dd78db8565a405e4611aa52470b9cc320c95cb5e4c7c412d83e05e70cbc88 +size 15420 diff --git a/images/tutorials/materials/defects/defect_creation_point_substitution_graphene/4-threejs-editor-coordinates.webp b/images/tutorials/materials/defects/defect_creation_point_substitution_graphene/4-threejs-editor-coordinates.webp deleted file mode 100644 index 011968021..000000000 --- a/images/tutorials/materials/defects/defect_creation_point_substitution_graphene/4-threejs-editor-coordinates.webp +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:ea3f3d21e176f539fe8bdde11d3c5a2ee296521e844d2ad9a98aaed22bce5e5a -size 153052 diff --git a/images/tutorials/materials/defects/defect_creation_point_substitution_graphene/4-toggle-measure-coordinates.webp b/images/tutorials/materials/defects/defect_creation_point_substitution_graphene/4-toggle-measure-coordinates.webp new file mode 100644 index 000000000..ef38d706e --- /dev/null +++ b/images/tutorials/materials/defects/defect_creation_point_substitution_graphene/4-toggle-measure-coordinates.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:48d8b1d7268b9cc05cfe604c119c7476491fe2ef99aabf2beb06d2b12813eb5a +size 20198 diff --git a/images/tutorials/materials/defects/defect_creation_point_substitution_graphene/band-structure-comparison.webp b/images/tutorials/materials/defects/defect_creation_point_substitution_graphene/band-structure-comparison.webp new file mode 100644 index 000000000..c80a03382 --- /dev/null +++ b/images/tutorials/materials/defects/defect_creation_point_substitution_graphene/band-structure-comparison.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:409de4b79ce7d9eae279d96de98bee7e89da555c8105bdb448513003b06dbe48 +size 35598 diff --git a/images/tutorials/materials/defects/defect_creation_point_substitution_graphene/band-structure-paper-figure.webp b/images/tutorials/materials/defects/defect_creation_point_substitution_graphene/band-structure-paper-figure.webp new file mode 100644 index 000000000..f01739d27 --- /dev/null +++ b/images/tutorials/materials/defects/defect_creation_point_substitution_graphene/band-structure-paper-figure.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fa6a4876a4a6781c7779e314e6305e567d4cdb6840787e68abdfd2aefc8e9e87 +size 34554 diff --git a/images/tutorials/materials/defects/defect_point_pair_gallium_nitride/4-3d-editor-coordinates.webp b/images/tutorials/materials/defects/defect_point_pair_gallium_nitride/4-3d-editor-coordinates.webp new file mode 100644 index 000000000..c6e728362 --- /dev/null +++ b/images/tutorials/materials/defects/defect_point_pair_gallium_nitride/4-3d-editor-coordinates.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c2dd6c7a300f8dedb41a1a2bcf0808fec5046914b497e93c2e23990cdd444109 +size 20612 diff --git a/images/tutorials/materials/defects/defect_point_pair_gallium_nitride/4-threejs-editor-coordinates.webp b/images/tutorials/materials/defects/defect_point_pair_gallium_nitride/4-threejs-editor-coordinates.webp deleted file mode 100644 index 8b19ef50b..000000000 --- a/images/tutorials/materials/defects/defect_point_pair_gallium_nitride/4-threejs-editor-coordinates.webp +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:996813cb8c291f0e1c019893c922f93d99c62bfa29b2512c46a34a298d7eed3f -size 66834 diff --git a/images/tutorials/mattersim/general-py-template.webp b/images/tutorials/mattersim/general-py-template.webp new file mode 100644 index 000000000..2e6fc1595 --- /dev/null +++ b/images/tutorials/mattersim/general-py-template.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3e1a6a12856f22bce22a1e6656742a7463db4e148ac70691d6819e39b6d6b2c8 +size 44854 diff --git a/images/tutorials/mattersim/mattersim-add-unit.webp b/images/tutorials/mattersim/mattersim-add-unit.webp new file mode 100644 index 000000000..d6b3a7bf2 --- /dev/null +++ b/images/tutorials/mattersim/mattersim-add-unit.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:34a2413ccfdb4bcb26b80a063f43d83e6ffbaa509f7719cd8e18d3e1f5058541 +size 64270 diff --git a/images/tutorials/mattersim/mattersim-bank-workflow.webp b/images/tutorials/mattersim/mattersim-bank-workflow.webp new file mode 100644 index 000000000..096a872af --- /dev/null +++ b/images/tutorials/mattersim/mattersim-bank-workflow.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b172931df8e242e52d328806fbc12c98403021493d4e911bce1fa1069a36c2a0 +size 71108 diff --git a/images/tutorials/mattersim/mattersim-edit-unit.webp b/images/tutorials/mattersim/mattersim-edit-unit.webp new file mode 100644 index 000000000..c4832878a --- /dev/null +++ b/images/tutorials/mattersim/mattersim-edit-unit.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5dd2f15e4717c273c04e8669a85d738a535363bf7dae68932960c4e778edb559 +size 100392 diff --git a/images/tutorials/mattersim/mattersim-job.webp b/images/tutorials/mattersim/mattersim-job.webp new file mode 100644 index 000000000..dba18297b --- /dev/null +++ b/images/tutorials/mattersim/mattersim-job.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1aeca37c1b2848ce8105c1baa8f730e581b42da4d9bf70e017da64c9409d3b51 +size 56862 diff --git a/images/tutorials/mattersim/mattersim-results-cell-relaxation.webp b/images/tutorials/mattersim/mattersim-results-cell-relaxation.webp new file mode 100644 index 000000000..df26218f5 --- /dev/null +++ b/images/tutorials/mattersim/mattersim-results-cell-relaxation.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c477c90c69d7ed850f3df841f2c4ea219eb3d4af909c63ded77c82a8e639ba16 +size 79364 diff --git a/images/tutorials/mattersim/mattersim-results-phonon.webp b/images/tutorials/mattersim/mattersim-results-phonon.webp new file mode 100644 index 000000000..ac80a7226 --- /dev/null +++ b/images/tutorials/mattersim/mattersim-results-phonon.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:20f71c7d7c11051f1e05f221705010870115b1dd0dd10d599c3f7c99c8e56b41 +size 74362 diff --git a/images/tutorials/mattersim/mattersim-results-total-energy.webp b/images/tutorials/mattersim/mattersim-results-total-energy.webp new file mode 100644 index 000000000..fee6588ad --- /dev/null +++ b/images/tutorials/mattersim/mattersim-results-total-energy.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e4a4fbba3da5b51ded198994635c81fd2d7632ac4ee9019c9a3312464e49cf40 +size 60980 diff --git a/images/tutorials/mattersim/mattersim-workflow.webp b/images/tutorials/mattersim/mattersim-workflow.webp new file mode 100644 index 000000000..6d8f6e206 --- /dev/null +++ b/images/tutorials/mattersim/mattersim-workflow.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e323ab86a9812d7717b6cb3079e622e371a581363ebe46813176987507ed8a32 +size 83746 diff --git a/images/tutorials/new-application/application-modules-cli.webp b/images/tutorials/new-application/application-modules-cli.webp new file mode 100644 index 000000000..5f05b09df --- /dev/null +++ b/images/tutorials/new-application/application-modules-cli.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c4903a02c3ad4cce9576ee256d0e4cbb723dda76fa8a87e79b39862d1d0ad53e +size 94700 diff --git a/images/tutorials/new-application/application-selection-web-ui.webp b/images/tutorials/new-application/application-selection-web-ui.webp new file mode 100644 index 000000000..2649b2176 --- /dev/null +++ b/images/tutorials/new-application/application-selection-web-ui.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e26c6ae0e46b16aefd13254e73d0cf6956797e55e51fbe4684ba9d6b45eaa1bb +size 90700 diff --git a/images/ui/account-menu.webp b/images/ui/account-menu.webp new file mode 100644 index 000000000..2ad52414c --- /dev/null +++ b/images/ui/account-menu.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5e8fa0426af5f4ec1b6935ed7613b523270440e03c16caae79721501e2f340fb +size 33210 diff --git a/images/ui/account-snapshot.png b/images/ui/account-snapshot.png deleted file mode 100644 index d94055a77..000000000 --- a/images/ui/account-snapshot.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:755022eccbffa90d7aa918145d7a96b938f9ca49788f6d94ca979d3ac081c21d -size 116761 diff --git a/images/ui/chat-widget.webp b/images/ui/chat-widget.webp new file mode 100644 index 000000000..6df405b34 --- /dev/null +++ b/images/ui/chat-widget.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:84c78e97987a3ac515481fa3b73179a0bf70ca077170d87775e618a4bdc585cc +size 30206 diff --git a/images/ui/entry-gateway.png b/images/ui/entry-gateway.png deleted file mode 100644 index bad7109d0..000000000 --- a/images/ui/entry-gateway.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:c5abc5fb87f8a264e1f844c0c86c8bb2474ee28dc0d998fa37823ac61707a911 -size 167882 diff --git a/images/ui/gateway-query.gif b/images/ui/gateway-query.gif deleted file mode 100644 index 9bcd4e037..000000000 --- a/images/ui/gateway-query.gif +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:633483885a6ac312b8d353794f89ee91e7a312fb7e7e2627d5da07ef1c459fdb -size 1812937 diff --git a/images/ui/homepage.webp b/images/ui/homepage.webp new file mode 100644 index 000000000..9fee1e377 --- /dev/null +++ b/images/ui/homepage.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:10dc0752b4b41dd1917a735a1b9271bc0c97300ba09a34c984c8c26e99f65356 +size 114254 diff --git a/images/ui/ui-header.png b/images/ui/ui-header.png deleted file mode 100644 index 44bdff0e7..000000000 --- a/images/ui/ui-header.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:9b2eefecaa3c0c036642ba356ae0cfbd7b5c3aa4217ef05fd47643945723d90d -size 53633 diff --git a/images/ui/ui-header.webp b/images/ui/ui-header.webp new file mode 100644 index 000000000..faae90b3f --- /dev/null +++ b/images/ui/ui-header.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:bc4d053fd5d8d232a007f98d90b2cdfbc65eae5fa6412e438e65bea8d2c0b2c9 +size 34374 diff --git a/images/ui/ui-left-sidebar.png b/images/ui/ui-left-sidebar.png deleted file mode 100644 index fe7b61ff8..000000000 --- a/images/ui/ui-left-sidebar.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:1f0aadb5eac72b3ad6aa9eb9dc25f85134473fa2b73438b756ea6aae7dd92d52 -size 115394 diff --git a/images/ui/ui-left-sidebar.webp b/images/ui/ui-left-sidebar.webp new file mode 100644 index 000000000..a2c96111b --- /dev/null +++ b/images/ui/ui-left-sidebar.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:998047c299b58c4528e354f6346606793d18fb3832021f21b064df7891360f53 +size 49706 diff --git a/images/ui/ui-overview.png b/images/ui/ui-overview.png deleted file mode 100644 index 2bc94f42b..000000000 --- a/images/ui/ui-overview.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:0723e0f9302492a9a04e17e6b16186dc798d10a3601311cd6d56c8c905c54ed8 -size 207608 diff --git a/images/ui/ui-overview.webp b/images/ui/ui-overview.webp new file mode 100644 index 000000000..784e50892 --- /dev/null +++ b/images/ui/ui-overview.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2fc48bafff90fd3b2f5fd3e9e8bcdbabbad193d02af8db3028e651629187fd08 +size 110830 diff --git a/images/ui/ui-right-sidebar.png b/images/ui/ui-right-sidebar.png deleted file mode 100644 index 0c8e4ed22..000000000 --- a/images/ui/ui-right-sidebar.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:c5fe39d88bb3f446f7aea2dc1fdf6c3e1ccd511171c04b47f9c271aa814d4673 -size 169991 diff --git a/images/ui/ui-specific.png b/images/ui/ui-specific.png deleted file mode 100644 index 781f4435c..000000000 --- a/images/ui/ui-specific.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:d4f32bb593ebabdbb1ca988d710bf5a31469cab43a703054a26280410e106f22 -size 154757 diff --git a/images/ui/ui-specific.webp b/images/ui/ui-specific.webp new file mode 100644 index 000000000..1700646cf --- /dev/null +++ b/images/ui/ui-specific.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8e11ef5ad446bd61488186661ab7e30b90ea0fa816ff4ce447c6929ae158ed03 +size 78208 diff --git a/images/ui/user-dashboard.png b/images/ui/user-dashboard.png deleted file mode 100644 index d97d2ac4c..000000000 --- a/images/ui/user-dashboard.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:ce954e2225651457f0d420dcd9a9cef247e0a49b7cb1a87d8ba3ea0fbf58c23f -size 149443 diff --git a/images/ui/user-dashboard.webp b/images/ui/user-dashboard.webp new file mode 100644 index 000000000..728c435ea --- /dev/null +++ b/images/ui/user-dashboard.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9f9f25448df605616c71a32e6e51c6289baeb315d2dc37ae80fb7bebc0c77988 +size 62006 diff --git a/lang/en/docs/accounts/accounting/check-balance-quota.md b/lang/en/docs/accounts/accounting/check-balance-quota.md index 67d2f01fe..5d84af0e3 100644 --- a/lang/en/docs/accounts/accounting/check-balance-quota.md +++ b/lang/en/docs/accounts/accounting/check-balance-quota.md @@ -1,12 +1,12 @@ # Account Balance and Storage Quota -This page explains how users can check the current [Account Balance](../balance.md) and [Storage Quota](../quota.md) associated with the account under consideration. +This page explains how users can check the current [Account Balance]({{ reference_url }}/accounts/balance/) and [Storage Quota]({{ reference_url }}/accounts/quota/) associated with the account under consideration. There are two ways through which both pieces of information can be accessed and viewed simultaneously, listed below. The appearance of the interface components exhibiting the balance and quota information in each of these two cases is displayed in the respective images underneath each item. -## In Right-hand sidebar +## In Account Menu -The information about both balance and quota is present in the [Right-hand sidebar](../../ui/right-sidebar.md) as shown in the visual below. +The information about both balance and quota is present in the [Account Menu]({{ interface_url }}/ui/account-menu/) as shown in the visual below. ![Account Snapshot](../../images/accounts/account-snapshot.png "Account Snapshot") @@ -23,9 +23,8 @@ It can be seen that in both of the above panels, the information about the Balan ## In Dashboard or "Bio" Tab -Furthermore, the current information about the Storage Quota across all the available supercomputing nodes can also be retrieved by itself from the main account [Dashboard](../../ui/specific/dashboard.md), or alternatively from the "[Bio](../ui/bio.md)" tab of the "Account Profile" interface. In both of these cases, the typical appearance of the panel displaying such storage quota information is as shown in the below example: +Furthermore, the current information about the Storage Quota across all the available supercomputing nodes can also be retrieved by itself from the main account [Dashboard]({{ interface_url }}/ui/specific/dashboard/), or alternatively from the "[Bio](../ui/bio.md)" tab of the "Account Profile" interface. In both of these cases, the typical appearance of the panel displaying such storage quota information is as shown in the below example: ![Storage Quota](../../images/accounts/storage-quota.png "Storage Quota") -Two buttons are present at the top-right corner of the above interface widget: the first on the left can be used to [increase the Storage Quota](increase-quota.md), and the second on the right to refresh the displayed information. - +Two buttons are present at the top-right corner of the above interface widget: the first on the left can be used to [increase the Storage Quota](increase-quota.md), and the second on the right to refresh the displayed information. diff --git a/lang/en/docs/accounts/accounting/increase-balance.md b/lang/en/docs/accounts/accounting/increase-balance.md index fd2601b80..8648e515d 100644 --- a/lang/en/docs/accounts/accounting/increase-balance.md +++ b/lang/en/docs/accounts/accounting/increase-balance.md @@ -3,14 +3,14 @@ !!!warning "Warning: content with restricted access" All the information contained under the present documentation page is only relevant for Account Owners or Administrators, since only they have sufficient rights to view the content exposed herein and make the appropriate changes. We remind the reader that a user is always the Owner and full administrator of his own personal Account. -The action of performing a payment in order to add credit to the [Account Balance](../balance.md), using any of the available [Payment Methods](payment-methods.md), can be performed from either the [Service Levels tab](../ui/service-level.md), or from the [right-hand sidebar](../../ui/right-sidebar.md) of the wider User Interface. Under either of these two alternative locations, the account balance can be topped-up with extra credit through their corresponding `Add Credit` (or `Apply Credit`) buttons underneath the current balance indicator, the precise positions of which are encircled in red in the image below: +The action of performing a payment in order to add credit to the [Account Balance]({{ reference_url }}/accounts/balance/), using any of the available [Payment Methods](payment-methods.md), can be performed from either the [Service Levels tab](../ui/service-level.md), or from the [Account Menu]({{ interface_url }}/ui/account-menu/) of the wider User Interface. Under either of these two alternative locations, the account balance can be topped-up with extra credit through their corresponding `Add Credit` (or `Apply Credit`) buttons underneath the current balance indicator, the precise positions of which are encircled in red in the image below: ![Increase Balance](../../images/accounts/increase-balance.png "Increase Balance") ## Increase Balance Dialog -Once either of the above-mentioned `Add Credit` or `Apply Credit` buttons have been clicked upon, the user will be greeted with the following "Add credit" screen asking him to select the desired amount of credit to be added to the account balance from a predefined set of options (500, 5,000 or 50,000 dollars). +Once either of the above-mentioned `Add Credit` or `Apply Credit` buttons have been clicked upon, the user will be greeted with the following "Add credit" screen asking him to select the desired amount of credit to be added to the account balance from a predefined set of options (500, 5,000 or 50,000 dollars). ### Custom Amounts @@ -20,10 +20,10 @@ Alternatively, a custom amount of funds can be entered under the `Other` option ## Finalize the "Add Credit" Operation -Once the user has made the desired choice from the above-mentioned list of options under the "Add credit" screen, the bottom `Add Credit` button should be pressed to confirm and finalize the payment operation. The account balance will consequently be updated once the charge is accepted by our payments provider. The account [service level](../../pricing/service-levels.md) will therefore also be updated correspondingly. +Once the user has made the desired choice from the above-mentioned list of options under the "Add credit" screen, the bottom `Add Credit` button should be pressed to confirm and finalize the payment operation. The account balance will consequently be updated once the charge is accepted by our payments provider. The account [service level]({{ guide_url }}/pricing/service-levels/) will therefore also be updated correspondingly. -Alternatively, to cancel the operation and revert to the previous screen, the neighbouring `Cancel` button (or the `X` button at the top-right corner of the screen) should be clicked upon. +Alternatively, to cancel the operation and revert to the previous screen, the neighbouring `Cancel` button (or the `X` button at the top-right corner of the screen) should be clicked upon. ## Payments and Service Level -Payments are closely linked to the account's [service level](../service-levels.md). Higher payments trigger greater levels of service, with all the associated benefits included as part of the account package. Each service level has a validity period for balances, which can be consulted [here](../../pricing/service-levels.md). Therefore, in order for the current service level to be maintained, we recommend that the necessary credit be added to the account balance before the end of its corresponding validity period. +Payments are closely linked to the account's [service level]({{ reference_url }}/accounts/service-levels/). Higher payments trigger greater levels of service, with all the associated benefits included as part of the account package. Each service level has a validity period for balances, which can be consulted [here]({{ guide_url }}/pricing/service-levels/). Therefore, in order for the current service level to be maintained, we recommend that the necessary credit be added to the account balance before the end of its corresponding validity period. diff --git a/lang/en/docs/accounts/accounting/increase-quota.md b/lang/en/docs/accounts/accounting/increase-quota.md index 4d8c39c16..977e3d3bf 100644 --- a/lang/en/docs/accounts/accounting/increase-quota.md +++ b/lang/en/docs/accounts/accounting/increase-quota.md @@ -3,12 +3,12 @@ !!!warning "Warning: content with restricted access" All the information contained under the present documentation page is only relevant for Account Owners or Administrators, since only they have sufficient rights to view the content exposed herein and make the appropriate changes. We remind the reader that a user is always the Owner and full administrator of his own personal Account. -This page explains how to request an increase to the Account's [Storage Quota](../quota.md) on the available supercomputing clusters, in addition to the storage space already provided under the account's current [service level](../../pricing/service-levels.md). This action can be performed from the following four alternative locations across the platform interface: +This page explains how to request an increase to the Account's [Storage Quota]({{ reference_url }}/accounts/quota/) on the available supercomputing clusters, in addition to the storage space already provided under the account's current [service level]({{ guide_url }}/pricing/service-levels/). This action can be performed from the following four alternative locations across the platform interface: -- [The Right-hand Sidebar](../../ui/right-sidebar.md) +- [The Account Menu]({{ interface_url }}/ui/account-menu/) - [The Service Level Tab](../ui/service-level.md) -- [Dashboard](../../ui/specific/dashboard.md) +- [Dashboard]({{ interface_url }}/ui/specific/dashboard/) - [The "Bio" tab](../ui/bio.md) In the former two cases, the increase in Storage Quota can be executed through either of the corresponding `Add Storage` buttons, located within the broader User Interface as highlighted in red in the image below: @@ -22,11 +22,11 @@ In the latter two cases on the other hand, the same action can be performed thro ## Increase Quota Dialog -Once any of the above-mentioned buttons have been clicked upon, the user will be greeted with the following "Increase Storage Quota" screen asking him to select the desired amount of storage space to be added to the account quota from a predefined set of options (10, 100, 500 GigaBytes, or 1 TeraByte). Next to each entry in this list of options, the associated price that will be charged on a monthly basis to the account balance is indicated. +Once any of the above-mentioned buttons have been clicked upon, the user will be greeted with the following "Increase Storage Quota" screen asking him to select the desired amount of storage space to be added to the account quota from a predefined set of options (10, 100, 500 GigaBytes, or 1 TeraByte). Next to each entry in this list of options, the associated price that will be charged on a monthly basis to the account balance is indicated. ### Custom Amounts -Alternatively, a custom amount of storage space can be entered under the `Other` option of the dialog (in GigaBytes), and the associated monthly price will appear directly underneath. +Alternatively, a custom amount of storage space can be entered under the `Other` option of the dialog (in GigaBytes), and the associated monthly price will appear directly underneath. ![Increase Quota Screen](../../images/accounts/increase-quota-screen.png "Increase Quota Screen") @@ -42,4 +42,4 @@ Alternatively, a custom amount of storage space can be entered under the `Other` Once the user has made the desired choice from the above-mentioned list of options under the "Increase Storage Quota" screen, the bottom `Request Storage` button should be pressed to confirm and finalize the storage increase operation. We will send an email within 24 hours confirming the storage quota upgrade. The user should login again to the corresponding account to [verify the new storage quota](check-balance-quota.md). -Alternatively, to cancel the operation and revert to the previous screen, the neighbouring `Cancel` button (or the `X` button at the top-right corner of the screen) should be clicked upon. +Alternatively, to cancel the operation and revert to the previous screen, the neighbouring `Cancel` button (or the `X` button at the top-right corner of the screen) should be clicked upon. diff --git a/lang/en/docs/accounts/accounting/overview.md b/lang/en/docs/accounts/accounting/overview.md index c097c5e65..5411d0e06 100644 --- a/lang/en/docs/accounts/accounting/overview.md +++ b/lang/en/docs/accounts/accounting/overview.md @@ -1,6 +1,6 @@ # Check Account Balance and Storage Quota -Any user (including those with non-administrative privileges for [organizational accounts](../overview.md)) can check the [balance](../balance.md) and storage [quota](../quota.md) associated with the present account, to verify, for example, that their respective levels of consumption are not approaching their total limiting amounts. We explain how to do so [in this page](check-balance-quota.md). +Any user (including those with non-administrative privileges for [organizational accounts]({{ reference_url }}/accounts/overview/)) can check the [balance]({{ reference_url }}/accounts/balance/) and storage [quota]({{ reference_url }}/accounts/quota/) associated with the present account, to verify, for example, that their respective levels of consumption are not approaching their total limiting amounts. We explain how to do so [in this page](check-balance-quota.md). ## [Increase Balance](increase-balance.md) diff --git a/lang/en/docs/accounts/balance.md b/lang/en/docs/accounts/balance.md index 396e71136..e5920e2d3 100644 --- a/lang/en/docs/accounts/balance.md +++ b/lang/en/docs/accounts/balance.md @@ -4,16 +4,16 @@ The Balance associated with an Account indicates the **total combined** amount o ### Reserved Balance -The "Reserved" aspect of the total balance refers to the amount of money which has been **allocated** for a given set of calculations defined by the User. For example, if 100 jobs have to be executed, each costing 1 dollar, then a Reserved Balance of 100 dollars is allocated. +The "Reserved" aspect of the total balance refers to the amount of money which has been **allocated** for a given set of calculations defined by the User. For example, if 100 jobs have to be executed, each costing 1 dollar, then a Reserved Balance of 100 dollars is allocated. ### Available Balance All the **remaining** money that has not been allocated yet as part of any computational task is then referred to as the "Current", or "Available", Balance. - + ## View Balance -Both the Reserved and Available Balances associated with an Account can be inspected by the User through either the [Service Levels](ui/service-level.md) or the [right-hand sidebar](../ui/right-sidebar.md) components. +Both the Reserved and Available Balances associated with an Account can be inspected by the User through either the [Service Levels]({{ interface_url }}/accounts/ui/service-level/) or the [Account Menu]({{ interface_url }}/ui/account-menu/) components. ## Increase Balance -A description for how the action of increasing the account-related balance can be performed (by the owner of the account or any of the administrators in the case of an Organizational account) is documented in [this page](accounting/increase-balance.md). +A description for how the action of increasing the account-related balance can be performed (by the owner of the account or any of the administrators in the case of an Organizational account) is documented in [this page]({{ interface_url }}/accounts/accounting/increase-balance/). diff --git a/lang/en/docs/accounts/collections.md b/lang/en/docs/accounts/collections.md index 3951733a7..af851ed67 100644 --- a/lang/en/docs/accounts/collections.md +++ b/lang/en/docs/accounts/collections.md @@ -2,7 +2,7 @@ The term "Collection", in the context of our platform, refers to the broad concept of a **database of items**, whereby such items can be of any general type. These collections, comprising all the different items that they contain, are stored in our platform. The concept of a collection can be easily understood by users familiar with MongoDB [^1] database. -The "front-end" of these collections, or in other words the way the users can visualize and interact graphically with such databases as lists of items on our platform, can typically be accessed via the [Explorer](../entities-general/ui/explorer.md) components (or alternatively through the [RESTful API](../rest-api/overview.md)). +The "front-end" of these collections, or in other words the way the users can visualize and interact graphically with such databases as lists of items on our platform, can typically be accessed via the [Explorer]({{ interface_url }}/entities-general/ui/explorer/) components (or alternatively through the [RESTful API]({{ developers_url }}/rest-api/overview/)). ## Entity Collections @@ -14,7 +14,7 @@ As we explain in their [dedicated documentation page](../entities-general/bank.m ## Auxiliary Collections -Due to its wide scope of applicability, the concept of Collections is not restricted to entities only, but rather may be applied to numerous other types of item databases present across the entirety of the Exabyte platform, such as the collection of [Pseudopotentials](../methods-directory/pseudopotential/overview.md) available for computation. +Due to its wide scope of applicability, the concept of Collections is not restricted to entities only, but rather may be applied to numerous other types of item databases present across the entirety of the Exabyte platform, such as the collection of [Pseudopotentials]({{ reference_url }}/methods-directory/pseudopotential/overview/) available for computation. ## Links diff --git a/lang/en/docs/accounts/overview.md b/lang/en/docs/accounts/overview.md index 2bbc351ed..b5d9a1976 100644 --- a/lang/en/docs/accounts/overview.md +++ b/lang/en/docs/accounts/overview.md @@ -1,6 +1,6 @@ # Accounts -The concept of "Account" within the context of our platform broadly refers to the multiple different ways in which a user can engage in **actions** on the [entities](../entities-general/overview.md), such as [creating](../entities-general/actions/create.md) [Materials](../materials/overview.md) or [running](../jobs/actions/run.md) [Jobs](../jobs/overview.md) or collaborating with other users by [sharing](../collaboration/sharing/actions.md) entities with them. +The concept of "Account" within the context of our platform broadly refers to the multiple different ways in which a user can engage in **actions** on the [entities](../entities-general/overview.md), such as [creating]({{ interface_url }}/entities-general/actions/create/) [Materials](../materials/overview.md) or [running]({{ interface_url }}/jobs/actions/run/) [Jobs](../jobs/overview.md) or collaborating with other users by [sharing]({{ interface_url }}/collaboration/sharing/actions/) entities with them. > For the explanation of how the term "User" is compared with the more general concept of "Account", please refer to the [following page](users.md). @@ -8,9 +8,9 @@ The concept of "Account" within the context of our platform broadly refers to th Accounts perform actions on the Entities stored in the corresponding collections as explained in the [corresponding page](collections.md). -## [Types of Accounts](ui/switcher.md) +## [Types of Accounts]({{ interface_url }}/accounts/ui/switcher/) -It is important for the present discussion to draw a distinction between two different types of accounts: **Individual** accounts for users, and collaborative accounts with a membership comprising multiple users, referred to as **Organizational** or **Enterprise** (the two words are used interchangeably). The User can choose which account to use among all the available options through the Account Switcher, described [here](ui/switcher.md). +It is important for the present discussion to draw a distinction between two different types of accounts: **Individual** accounts for users, and collaborative accounts with a membership comprising multiple users, referred to as **Organizational** or **Enterprise** (the two words are used interchangeably). The User can choose which account to use among all the available options through the Account Switcher, described [here]({{ interface_url }}/accounts/ui/switcher/). ### Individual Accounts @@ -28,10 +28,10 @@ The quality of service for the account, including features such as private data, Account [Balance](balance.md) allows to perform actions that require monetary exchange. -## [User Interface](ui/overview.md) +## [User Interface]({{ interface_url }}/accounts/ui/overview/) -Accounts can be manipulated, navigated, and defined according to certain settings or descriptions through the corresponding interface, introduced [here](ui/overview.md). +Accounts can be manipulated, navigated, and defined according to certain settings or descriptions through the corresponding interface, introduced [here]({{ interface_url }}/accounts/ui/overview/). -## [Accounting Actions](accounting/overview.md) +## [Accounting Actions]({{ interface_url }}/accounts/accounting/overview/) -Each User can perform a certain set of Actions in relation to the Account that he/she is currently logged into, and these are narrated starting from [this page](accounting/overview.md). +Each User can perform a certain set of Actions in relation to the Account that he/she is currently logged into, and these are narrated starting from [this page]({{ interface_url }}/accounts/accounting/overview/). diff --git a/lang/en/docs/accounts/payments-charges.md b/lang/en/docs/accounts/payments-charges.md index 7a0d08765..ba019c203 100644 --- a/lang/en/docs/accounts/payments-charges.md +++ b/lang/en/docs/accounts/payments-charges.md @@ -8,22 +8,22 @@ An Account is not billed, or "Charged", until the completion of the correspondin ## View Charges and Payments -Inspection of the complete list of all previously-made payments, and of all incurred charges, associated with an Account is rendered possible through the "Billing & Payments" option under the [right-hand sidebar](../ui/right-sidebar.md) interface component, accessible from anywhere across the platform. This particular aspect of the User Interface is reviewed in the following [dedicated page](ui/charges-payments.md). +Inspection of the complete list of all previously-made payments, and of all incurred charges, associated with an Account is rendered possible through the "Billing & Payments" option under the [Account Menu]({{ interface_url }}/ui/account-menu/) interface component, accessible from anywhere across the platform. This particular aspect of the User Interface is reviewed in the following [dedicated page]({{ interface_url }}/accounts/ui/charges-payments/). ## Payment Methods ### Card-based Payments -Payments can be executed through Credit/Debit Cards, by providing the relevant card information as outlined in the following [procedural instructions](accounting/payment-methods.md). +Payments can be executed through Credit/Debit Cards, by providing the relevant card information as outlined in the following [procedural instructions]({{ interface_url }}/accounts/accounting/payment-methods/). ### Wire-based Payments For the Enterprise Accounts we naturally establish a different payment protocol: - + 1. After receiving a payment from the customer, we make it available as a "Credit" payment method under the customer account. - - 2. We charge the subscription fee to the payment method - + + 2. We charge the subscription fee to the payment method + 3. Account administrators will then be able to use this payment method to pay for compute allocation or any other resource costs - + For repeated payments the process is repeated correspondingly. diff --git a/lang/en/docs/accounts/quota.md b/lang/en/docs/accounts/quota.md index 4d137ddd2..cfb3a6364 100644 --- a/lang/en/docs/accounts/quota.md +++ b/lang/en/docs/accounts/quota.md @@ -4,20 +4,20 @@ The "Quota" associated with an Account indicates the **total combined** amount o ### Consumed Storage Quota -The combined size, in Megabytes (Mb) or Gigabytes (Gb), of all computational data currently stored in the available supercomputing clusters indicated the current level of consumption of the Storage Quota. The total consumption can not exceed the total amount of storage space. If desired, the Owner of the Account may purchase additional space, as explained late in this page. +The combined size, in Megabytes (Mb) or Gigabytes (Gb), of all computational data currently stored in the available supercomputing clusters indicated the current level of consumption of the Storage Quota. The total consumption can not exceed the total amount of storage space. If desired, the Owner of the Account may purchase additional space, as explained late in this page. ### Available Storage Quota -All the available free storage space, that has not been yet occupied by the data generated by the various Account users, constitutes the "Available" storage. It is the responsibility of the Account to ensure that a sufficient amount of available free storage space is present at all times to guarantee the smooth execution of all desired tasks. +All the available free storage space, that has not been yet occupied by the data generated by the various Account users, constitutes the "Available" storage. It is the responsibility of the Account to ensure that a sufficient amount of available free storage space is present at all times to guarantee the smooth execution of all desired tasks. ## View Quota -Both the Consumed and Available storage quotas associated with an Account can be inspected by the user through any of the following user interface components: the [Service Levels](ui/service-level.md) page, the [right-hand sidebar](../ui/right-sidebar.md), the [Bio](ui/bio.md) account interface component, or on the main [Dashboard](../ui/specific/dashboard.md). In the latter three cases, it is possible to visualize such quota information broken down across each individual computing cluster node available to the Account. +Both the Consumed and Available storage quotas associated with an Account can be inspected by the user through any of the following user interface components: the [Service Levels]({{ interface_url }}/accounts/ui/service-level/) page, the [Account Menu]({{ interface_url }}/ui/account-menu/), the [Bio]({{ interface_url }}/accounts/ui/bio/) account interface component, or on the main [Dashboard]({{ interface_url }}/ui/specific/dashboard/). In the latter three cases, it is possible to visualize such quota information broken down across each individual computing cluster node available to the Account. ## Increase Quota -Accounts can increase the limit for the total storage quota according to the instructions in [this page](accounting/increase-balance.md). +Accounts can increase the limit for the total storage quota according to the instructions in [this page]({{ interface_url }}/accounts/accounting/increase-balance/). ## Access Quota Information via Command Line -Information about the consumed and available storage quotas can also be accessed via the Command Line Interface of the platform, as explained in a [separate section of the documentation](../infrastructure/storage.md). +Information about the consumed and available storage quotas can also be accessed via the Command Line Interface of the platform, as explained in a [separate section of the documentation]({{ resources_url }}/infrastructure/storage/). diff --git a/lang/en/docs/accounts/service-levels.md b/lang/en/docs/accounts/service-levels.md index 94506e5e9..b45d095c9 100644 --- a/lang/en/docs/accounts/service-levels.md +++ b/lang/en/docs/accounts/service-levels.md @@ -1,6 +1,6 @@ # Service Levels -Service levels define the types, qualities, and quantities of services provided to the accounts within our platform. The features available on our platform are affected by the opted Service Level. For a detailed comparison of the pricing associated with different Service Levels offered as part of our platform, the user is referred to the [pricing documentation page](../pricing/service-levels.md). +Service levels define the types, qualities, and quantities of services provided to the accounts within our platform. The features available on our platform are affected by the opted Service Level. For a detailed comparison of the pricing associated with different Service Levels offered as part of our platform, the user is referred to the [pricing documentation page]({{ guide_url }}/pricing/service-levels/). ## Comparison @@ -22,7 +22,7 @@ Service levels define the types, qualities, and quantities of services provided [^1]: The total quota of storage space allocated to the account on a monthly basis. -[^2]: The possibility of having private entities inside an account. Otherwise, entities are accessible for other platform users to view. More explanation [here](../collaboration/sharing/access-levels.md). +[^2]: The possibility of having private entities inside an account. Otherwise, entities are accessible for other platform users to view. More explanation [here]({{ interface_url }}/collaboration/sharing/access-levels/). [^3]: The maximum number of users hosted inside an account. @@ -68,7 +68,7 @@ Organizations interested in a managed cloud solution where our software can run ## View/Change Service Level -All the relevant information concerning Service Levels, under the context of the currently selected Account, can be inspected through the corresponding [component of the User Interface](ui/service-level.md). It is important to bear in mind that, when dealing with collaborative accounts, only the Owner or an Administrator of the account is given the right to undergo such operations on behalf of the whole Organization. +All the relevant information concerning Service Levels, under the context of the currently selected Account, can be inspected through the corresponding [component of the User Interface]({{ interface_url }}/accounts/ui/service-level/). It is important to bear in mind that, when dealing with collaborative accounts, only the Owner or an Administrator of the account is given the right to undergo such operations on behalf of the whole Organization. ## Validity Period diff --git a/lang/en/docs/accounts/ui/account-badge.md b/lang/en/docs/accounts/ui/account-badge.md index 975b1c3f0..b63462975 100644 --- a/lang/en/docs/accounts/ui/account-badge.md +++ b/lang/en/docs/accounts/ui/account-badge.md @@ -1,16 +1,16 @@ # Account Badge -The "Account Badge" is always present at the top-right corner of any page under the [header bar](../../ui/header-footer.md) and displays the general information about the Account that the user is currently logged into. +The "Account Badge" is always present at the top-right corner of any page under the [header bar]({{ interface_url }}/ui/header-footer/) and displays the general information about the Account that the user is currently logged into. ## General Information - The general information comprises the Account **name** and **[type](../overview.md)**, between **"Personal"** and **"Enterprise"**. "Enterprise" in this context is a synonym for Organization, and should not be confused with the "Enterprise" [service Level](../service-levels.md). The profile picture of the Account is also displayed here. + The general information comprises the Account **name** and **[type]({{ reference_url }}/accounts/overview/)**, between **"Personal"** and **"Enterprise"**. "Enterprise" in this context is a synonym for Organization, and should not be confused with the "Enterprise" [service Level]({{ reference_url }}/accounts/service-levels/). The profile picture of the Account is also displayed here. The name and profile picture can be modified at any time by the user under the [Profile information section](preferences/profile.md) of the [Account Preferences](preferences-overview.md). ## Example for Personal Account -An example of Badge for an Account of personal type is displayed in its right-hand location within the [header bar](../../ui/header-footer.md) in the image below. In this example, the personal Account belongs to a user called "John Doe". +An example of Badge for an Account of personal type is displayed in its right-hand location within the [header bar]({{ interface_url }}/ui/header-footer/) in the image below. In this example, the personal Account belongs to a user called "John Doe". ![example personal badge](../../images/accounts/example-personal-badge.png "example personal badge") diff --git a/lang/en/docs/accounts/ui/bio.md b/lang/en/docs/accounts/ui/bio.md index 5cb8538d5..799f6247e 100644 --- a/lang/en/docs/accounts/ui/bio.md +++ b/lang/en/docs/accounts/ui/bio.md @@ -1,6 +1,6 @@ # Account Biographical Information -The page under the `Bio` tab button of the general User Interface shows general biographical information about the account's profile, and information about the [organizations](../../collaboration/organizations/overview.md) or [teams](../../collaboration/organizations/teams.md) that the user is member of. This information can be set as [private or public](../../collaboration/sharing/access-levels.md) depending on the account's service level, as explained [here](../service-levels.md). The layout of this "Bio" page is as portrayed in the example image below, with component panels highlighted: +The page under the `Bio` tab button of the general User Interface shows general biographical information about the account's profile, and information about the [organizations]({{ reference_url }}/collaboration/organizations/overview/) or [teams]({{ reference_url }}/collaboration/organizations/teams/) that the user is member of. This information can be set as [private or public]({{ reference_url }}/collaboration/sharing/access-levels/) depending on the account's service level, as explained [here]({{ reference_url }}/accounts/service-levels/). The layout of this "Bio" page is as portrayed in the example image below, with component panels highlighted: ![Bio Panels](../../images/accounts/bio-panels.png "Bio Panels") @@ -24,7 +24,7 @@ In case a personal account is currently employed, the user will see a list of al ### List of Users and Teams -If an [Organizational Account](../../collaboration/organizations/overview.md) is employed, the user will instead see a list of all members of Organization, including information about their [roles](../../collaboration/organizations/roles.md). In a second instance, the user will also be able to view a list of all [Teams](../../collaboration/organizations/teams.md) of the Organization, including information on how many members and projects are present in each of them. +If an [Organizational Account]({{ reference_url }}/collaboration/organizations/overview/) is employed, the user will instead see a list of all members of Organization, including information about their [roles]({{ reference_url }}/collaboration/organizations/roles/). In a second instance, the user will also be able to view a list of all [Teams]({{ reference_url }}/collaboration/organizations/teams/) of the Organization, including information on how many members and projects are present in each of them. Both Lists of Members and Teams are presented in the standard [Explorer-type interface](../../entities-general/ui/explorer.md) commonly encountered across our platform, as demonstrated in the following image example: @@ -32,4 +32,4 @@ Both Lists of Members and Teams are presented in the standard [Explorer-type int ## Storage Quota Information -The information regarding the consumed and available storage space affecting the account under consideration can be inspected in the bottom panel of the "Bio" page. This information is displayed subdivided across each of the available supercomputing nodes. Complete descriptions of the concepts revolving around Storage Quotas can be found [here](../quota.md). +The information regarding the consumed and available storage space affecting the account under consideration can be inspected in the bottom panel of the "Bio" page. This information is displayed subdivided across each of the available supercomputing nodes. Complete descriptions of the concepts revolving around Storage Quotas can be found [here]({{ reference_url }}/accounts/quota/). diff --git a/lang/en/docs/accounts/ui/charges-payments.md b/lang/en/docs/accounts/ui/charges-payments.md index f6bfbee7a..9905f70b9 100644 --- a/lang/en/docs/accounts/ui/charges-payments.md +++ b/lang/en/docs/accounts/ui/charges-payments.md @@ -1,6 +1,6 @@ # Charges, Payments, and Payment Methods -Click `Billing and Payments` in the [right-hand sidebar](../../ui/right-sidebar.md) to review the list of charges incurred by the account, and the payments executed to address them. The possibility to view or add Payment Methods is also offered. +Click `Billing and Payments` in the [Account Menu]({{ interface_url }}/ui/account-menu/) to review the list of charges incurred by the account, and the payments executed to address them. The possibility to view or add Payment Methods is also offered. An example of a "Billing" page is exhibited below. We have highlighted in red the tabs for viewing charges, payments, and payments methods. @@ -8,11 +8,11 @@ An example of a "Billing" page is exhibited below. We have highlighted in red th ## Charges -Under the tab labelled "Charges" the user can review the charges applied to the [Account Balance](../balance.md) while using our platform. +Under the tab labelled "Charges" the user can review the charges applied to the [Account Balance]({{ reference_url }}/accounts/balance/) while using our platform. ## Payments -Under the "Payments" tab , the user can review the money paid so far by crediting the [Account Balance](../balance.md). +Under the "Payments" tab , the user can review the money paid so far by crediting the [Account Balance]({{ reference_url }}/accounts/balance/). ## Actions @@ -22,7 +22,7 @@ Both Charges and Payments sheets are presented under the standard [Explorer-type #### Quick Search -A [Search](../../entities-general/actions/search.md) bar is present at the top of both balance sheets. +A [Search](../../entities-general/actions/search.md) bar is present at the top of both balance sheets. #### Advanced Search @@ -30,20 +30,20 @@ An [Advanced Search](../../entities-general/actions/advanced-search.md) -project-year-month-computation". For example "demo-project-2018-10-bandstructures" | -| type | The type of task being charged, for example "Job" | -| wallDuration | Time duration of the computation | -| charge | Charge amount incurred as part of the computational task | -| username | Name of the user that performed the computation | -| description | Short description of what the charge is for, assigned automatically by the accounting system. For example "charge for whole hour", relevant to the [fast queues](../../infrastructure/resource/queues.md) | -| startTime | Date and time at which the Job was submitted, eg. "12-31-2017 22:33:00" | -| endTime | Date and time of Job termination following its completion in a similar format as the startTime above | +| machine | A [Fully Qualified Domain Name] [^1] of the [cluster]({{ guide_url }}/pricing/service-levels/#clusters-and-premium-hardware) used for the computation, for example: "master-production-20160630-cluster-007.exabyte.io" | +| project | [Slug]({{ data_url }}/entities-general/data/#Slug-Representation), or computer-friendly representation of the name of the project containing the Job, in the format "-project-year-month-computation". For example "demo-project-2018-10-bandstructures" | +| type | The type of task being charged, for example "Job" | +| wallDuration | Time duration of the computation | +| charge | Charge amount incurred as part of the computational task | +| username | Name of the user that performed the computation | +| description | Short description of what the charge is for, assigned automatically by the accounting system. For example "charge for whole hour", relevant to the [fast queues]({{ resources_url }}/infrastructure/resource/queues/) | +| startTime | Date and time at which the Job was submitted, eg. "12-31-2017 22:33:00" | +| endTime | Date and time of Job termination following its completion in a similar format as the startTime above | ## Payment Methods @@ -60,4 +60,4 @@ New Payment Methods (ie. Credit Cards) can be added as it is explained [in this [^1]: [Fully Qualified Domain Names, explanation, Indiana University Website](https://kb.iu.edu/d/aiuv) !!!warning "Restricted access" - The information contained under the present documentation page is relevant to Account [Owners or Administrators](../../collaboration/organizations/roles.md), since only they have sufficient rights to view and modify the content (a user is always the Owner and Administrator of his personal account). + The information contained under the present documentation page is relevant to Account [Owners or Administrators]({{ reference_url }}/collaboration/organizations/roles/), since only they have sufficient rights to view and modify the content (a user is always the Owner and Administrator of his personal account). diff --git a/lang/en/docs/accounts/ui/explorer.md b/lang/en/docs/accounts/ui/explorer.md index 21bf769a4..b235d7009 100644 --- a/lang/en/docs/accounts/ui/explorer.md +++ b/lang/en/docs/accounts/ui/explorer.md @@ -1,10 +1,10 @@ # Accounts Explorer -The list of existing accounts opened in our platform to date is accessible from the [Left-hand Sidebar](../../ui/left-sidebar.md), under the option `Accounts` . The list of accounts is implemented through an [Explorer-type interface](../../entities-general/ui/explorer.md) with its associated layout and actions. +The list of existing accounts opened in our platform to date is accessible from the [Left-hand Sidebar]({{ interface_url }}/ui/left-sidebar/), under the option `Accounts` . The list of accounts is implemented through an [Explorer-type interface](../../entities-general/ui/explorer.md) with its associated layout and actions. ## Viewing Account Information -Clicking on an item in the Accounts Explorer, allows user to inspect the corresponding Account's information, including its [Bio](bio.md), as well as the entities created under that Account which have been accessible to the user account or made [Public](../../collaboration/sharing/access-levels.md). +Clicking on an item in the Accounts Explorer, allows user to inspect the corresponding Account's information, including its [Bio](bio.md), as well as the entities created under that Account which have been accessible to the user account or made [Public]({{ reference_url }}/collaboration/sharing/access-levels/). ## Example diff --git a/lang/en/docs/accounts/ui/overview.md b/lang/en/docs/accounts/ui/overview.md index bd1a9c902..469babd6a 100644 --- a/lang/en/docs/accounts/ui/overview.md +++ b/lang/en/docs/accounts/ui/overview.md @@ -1,6 +1,6 @@ # Accounts-related UI -Multiple User Interface components are available, under the wider general [interface of our platform](../../ui/overview.md), to edit or insert information pertaining to Accounts. Further means are provided, for example, to switch between the accounts the user is a member of, or for navigating the platform-wide list of existing Accounts. +Multiple User Interface components are available, under the wider general [interface of our platform]({{ interface_url }}/ui/overview/), to edit or insert information pertaining to Accounts. Further means are provided, for example, to switch between the accounts the user is a member of, or for navigating the platform-wide list of existing Accounts. Each of these interface components is reviewed below, based on the location they can be accessed from. @@ -10,9 +10,9 @@ The interface elements accessible from the "Profile" page are reviewed [separate ![Account Profile General](../../images/accounts/account-profile-general.png "Account Profile General") -## [Left Sidebar](../../ui/left-sidebar.md) +## [Left Sidebar]({{ interface_url }}/ui/left-sidebar/) -The image below shows components available under the [left sidebar](../../ui/left-sidebar.md). The user should refer to the number labels to access the corresponding sections below. +The image below shows components available under the [left sidebar]({{ interface_url }}/ui/left-sidebar/). The user should refer to the number labels to access the corresponding sections below. ![Account UI left sidebar](../../images/accounts/left-sidebar-accounts.png "Account UI left sidebar") @@ -20,19 +20,19 @@ The image below shows components available under the [left sidebar](../../ui/lef The list of all accounts on our platform can be accessed following [these instructions](explorer.md). -## [Right Sidebar](../../ui/right-sidebar.md) +## [Right Sidebar]({{ interface_url }}/ui/account-menu/) -Similarly, more components are present under the [right-hand sidebar](../../ui/right-sidebar.md). They are highlighted and referenced below. +Similarly, more components are present under the [Account Menu]({{ interface_url }}/ui/account-menu/). They are highlighted and referenced below. ![Account UI right sidebar](../../images/accounts/right-sidebar-accounts.png "Account UI right sidebar") ### 1. [Badge](account-badge.md) -Some information about the currently employed account is displayed in ["Account Badge"](account-badge.md). The latter also acts as the trigger button for the opening of the right-hand sidebar. +Some information about the currently employed account is displayed in ["Account Badge"](account-badge.md). The latter also acts as the trigger button for the opening of the Account Menu. ### 2. [Link to Switcher](switcher.md) -The user can switch between different accounts that he/she is allowed to use under the ["Switcher"](switcher.md). +The user can switch between different accounts that he/she is allowed to use under the ["Switcher"](switcher.md). ### 3. [Link to Charges and Payments](charges-payments.md) diff --git a/lang/en/docs/accounts/ui/preferences-overview.md b/lang/en/docs/accounts/ui/preferences-overview.md index 7894d1450..c19dbba83 100644 --- a/lang/en/docs/accounts/ui/preferences-overview.md +++ b/lang/en/docs/accounts/ui/preferences-overview.md @@ -1,6 +1,6 @@ # Account Preferences -Under the `Preferences` tab of the general "Account Profile" interface, the user can set preferences and settings for the present account that he/she owns or administers. Alternatively, the same Account Preferences can be accessed from the [right-hand sidebar](../../ui/right-sidebar.md) of the general User Interface, under the option labelled "Account Preferences" . +Under the `Preferences` tab of the general "Account Profile" interface, the user can set preferences and settings for the present account that he/she owns or administers. Alternatively, the same Account Preferences can be accessed from the [Account Menu]({{ interface_url }}/ui/account-menu/) of the general User Interface, under the option labelled "Account Preferences" . ## [General Information](preferences/profile.md) @@ -8,7 +8,7 @@ This first aspect of the Account Preferences allows the user to insert account-w ## [User Settings](preferences/settings.md) -Under this section, the user is allowed to enter a suffix which will be appended to each job that is cloned via the jobs explorer page, as explained in detail [here](preferences/settings.md). +Under this section, the user is allowed to enter a suffix which will be appended to each job that is cloned via the jobs explorer page, as explained in detail [here](preferences/settings.md). ## [API Tokens](preferences/api.md) diff --git a/lang/en/docs/accounts/ui/preferences/api.md b/lang/en/docs/accounts/ui/preferences/api.md index 8d5f7cfc8..56048e571 100644 --- a/lang/en/docs/accounts/ui/preferences/api.md +++ b/lang/en/docs/accounts/ui/preferences/api.md @@ -1,6 +1,6 @@ # API Tokens -The concept of API authorization tokens in the context of the Rest-API of our platform are thoroughly explained in a [separate section](../../../rest-api/overview.md) of this documentation manual. For the moment, we will confine ourselves to simply showing how such tokens can be generated or deleted under the Account Preferences. +The concept of API authorization tokens in the context of the Rest-API of our platform are thoroughly explained in a [separate section]({{ developers_url }}/rest-api/overview/) of this documentation manual. For the moment, we will confine ourselves to simply showing how such tokens can be generated or deleted under the Account Preferences. ## Generate New Token diff --git a/lang/en/docs/accounts/ui/preferences/settings.md b/lang/en/docs/accounts/ui/preferences/settings.md index 9a3a7487c..b1e6a2875 100644 --- a/lang/en/docs/accounts/ui/preferences/settings.md +++ b/lang/en/docs/accounts/ui/preferences/settings.md @@ -7,12 +7,12 @@ Here, the user is given the opportunity to enter a suffix which will be appended ## Material Cell Type -Here, user can specify primitive or conventional unit cell representation to be used by default while visualizing materials in [3D Editor](../../../materials-designer/3d-editor/view.md). +Here, user can specify primitive or conventional unit cell representation to be used by default while visualizing materials in [3D Editor]({{ interface_url }}/materials-designer/3d-editor/view/). ## Default Entity Privacy Account's entities are created as public by default which means they are accessible for other platform users to view. -If account's service level allows [Private Data](../../service-levels.md), account's owner or admin can adjust the default behavior here to create private entities instead. +If account's service level allows [Private Data]({{ reference_url }}/accounts/service-levels/), account's owner or admin can adjust the default behavior here to create private entities instead. ## Save Changes diff --git a/lang/en/docs/accounts/ui/preferences/ssh.md b/lang/en/docs/accounts/ui/preferences/ssh.md index 46b99da9d..02c2c2f83 100644 --- a/lang/en/docs/accounts/ui/preferences/ssh.md +++ b/lang/en/docs/accounts/ui/preferences/ssh.md @@ -1,6 +1,6 @@ # SSH Keys -The concept of SSH authorization keys in the context of the Command Line Interface of our platform are thoroughly explained in a [separate section](../../../data-on-disk/security.md). For the moment, we will restrict ourselves to showing how such keys can be added to or deleted from our platform. +The concept of SSH authorization keys in the context of the Command Line Interface of our platform are thoroughly explained in a [separate section]({{ resources_url }}/data-on-disk/security/). For the moment, we will restrict ourselves to showing how such keys can be added to or deleted from our platform. ## Add New Key @@ -25,7 +25,7 @@ Once the new SSH key has been added, the user will be able to see the key as a n ### Connect to Server -Use the guidelines available in [this page](../../../remote-connection/ssh.md#connect-to-server) to establish connection to our login node server via the command-line terminal. +Use the guidelines available in [this page]({{ cli_url }}/remote-connection/ssh/#connect-to-server) to establish connection to our login node server via the command-line terminal. ### Animation diff --git a/lang/en/docs/accounts/ui/profile-page.md b/lang/en/docs/accounts/ui/profile-page.md index 7d29feb88..eba91a7f5 100644 --- a/lang/en/docs/accounts/ui/profile-page.md +++ b/lang/en/docs/accounts/ui/profile-page.md @@ -2,9 +2,9 @@ The "Account Profile" page represents the "command center" of any Account present on our platform. It encompasses all User Interface components which are essential to operate and manage the Account, and the entities that it contains. -This page can be subdivided into several components, related to either [management](overview.md) or [Entities](../../entities-general/overview.md). +This page can be subdivided into several components, related to either [management](overview.md) or [Entities]({{ reference_url }}/entities-general/overview/). -These components are highlighted in the image below. The position of the **"Account Summary"**, displaying information about its name, username and date of creation, is also exhibited. In the case of [Organizational Accounts](../../accounts/overview.md#types-of-accounts), some of these interface components are visible only to the [Owners and Administrators](../../collaboration/organizations/roles.md). +These components are highlighted in the image below. The position of the **"Account Summary"**, displaying information about its name, username and date of creation, is also exhibited. In the case of [Organizational Accounts]({{ reference_url }}/accounts/overview/#types-of-accounts), some of these interface components are visible only to the [Owners and Administrators]({{ reference_url }}/collaboration/organizations/roles/). ![Account UI components](../../images/accounts/account-profile.png "Account UI components") @@ -26,4 +26,4 @@ General Account Preferences and Settings, such as the biographical information a ## Entity Components -The Profile page also allows the Account-owned Entity Collections to be accessed from their associated ["Entity Tabs"](../../ui/specific/tabs-navigator.md), located at the top of the page. Each tab leads to the ["Explorer Interface"](../../entities-general/ui/explorer.md) for the corresponding [entity type](../../entities-general/overview.md). +The Profile page also allows the Account-owned Entity Collections to be accessed from their associated ["Entity Tabs"]({{ interface_url }}/ui/specific/tabs-navigator/), located at the top of the page. Each tab leads to the ["Explorer Interface"](../../entities-general/ui/explorer.md) for the corresponding [entity type]({{ reference_url }}/entities-general/overview/). diff --git a/lang/en/docs/accounts/ui/service-level.md b/lang/en/docs/accounts/ui/service-level.md index 53a347fa5..c5b470ce0 100644 --- a/lang/en/docs/accounts/ui/service-level.md +++ b/lang/en/docs/accounts/ui/service-level.md @@ -1,10 +1,10 @@ # Service Levels -The current data about the [Service Levels](../service-levels.md), can be reviewed for the present Account under the `Service Level` tab button of the Account Profile page. +The current data about the [Service Levels]({{ reference_url }}/accounts/service-levels/), can be reviewed for the present Account under the `Service Level` tab button of the Account Profile page. ## Balance and Storage Quota Indicators -General information about both the available (under "Current") and Reserved [Account Balance](../balance.md) on the left, and general information about the consumed (again under "Current") and the total limit for the [Storage Quota](../quota.md) on the right. +General information about both the available (under "Current") and Reserved [Account Balance]({{ reference_url }}/accounts/balance/) on the left, and general information about the consumed (again under "Current") and the total limit for the [Storage Quota]({{ reference_url }}/accounts/quota/) on the right. > Note: under the present version of our platform, this latter storage quota information refers exclusively to the status of the supercomputing node currently set as the default one, and NOT to the combined storage quota from all available nodes. @@ -20,7 +20,7 @@ The service level that has currently been opted-for is greyed-out and has the la ### Pricing and Service Features -For more information about the services offered under each different level and the associated prices, please consult the [Service Levels Pricing page](../../pricing/service-levels.md). Further explanation about what the various services imply in terms of functionality can be retrieved [here](../service-levels.md). Higher pricing requisites naturally trigger greater levels of service and associated benefits. +For more information about the services offered under each different level and the associated prices, please consult the [Service Levels Pricing page]({{ guide_url }}/pricing/service-levels/). Further explanation about what the various services imply in terms of functionality can be retrieved [here]({{ reference_url }}/accounts/service-levels/). Higher pricing requisites naturally trigger greater levels of service and associated benefits. ### Example Appearance diff --git a/lang/en/docs/accounts/ui/switcher.md b/lang/en/docs/accounts/ui/switcher.md index 88635dbce..e22a292b6 100644 --- a/lang/en/docs/accounts/ui/switcher.md +++ b/lang/en/docs/accounts/ui/switcher.md @@ -1,23 +1,36 @@ # Account Switcher -The possibility to switch between all Accounts available for login to the user is offered at the top of the [right-hand menu sidebar](../../ui/right-sidebar.md), under the label `My Accounts` . +The possibility to switch between all Accounts available for login to the user +is offered at the top of the [right-hand menu sidebar]( +../../ui/account-menu.md), under the label `My Accounts` +. ## Currently Logged-in Account -The name and type of the account that the user is currently logged into is displayed in [header](../../ui/header-footer.md). +The name and type of the account that the user is currently logged into is +displayed in [header]({{ interface_url }}/ui/header-footer/). ## View My Accounts -If the user is a member of, an [organization](../../collaboration/organizations/overview.md), the "My Accounts" list will contain other accounts, besides his/her personal one. This list is presented using an [Explorer-type interface](../../entities-general/ui/explorer.md), with its associated layout and features. +If the user is a member of, an [organization]({{ reference_url }}/collaboration/organizations/overview/), the "My Accounts" list will +contain other accounts, besides his/her personal one. This list is presented +using an [Explorer-type interface](../../entities-general/ui/explorer.md), with +its associated layout and features. -## Switch to Account +## Switch to Account -The user is able to switch between the personal account and organizational accounts by clicking on their corresponding names in the list. When switched, the interface will consequently reflect the change by showing the data related specifically to the organizational account, for example storage quota and balance affecting the wider organization as opposed to the user's personal consumption. +The user is able to switch between the personal account and organizational +accounts by clicking on their corresponding names in the list. When switched, +the interface will consequently reflect the change by showing the data related +specifically to the organizational account, for example storage quota and +balance affecting the wider organization as opposed to the user's personal +consumption. ## Example -In the image below, two accounts are listed in the Account Switcher: a personal account labelled "John Doe", and a wider organizational account called "Exabyte.io". The account under which the user is currently logged in is the personal one. - -![Accounts List](../../images/accounts/accounts-list.png "Accounts List") - +In the image below, three accounts are listed in the Account Switcher: a +personal account labelled "John Doe", and two organizational accounts called +"Seminar Organization" and "Mat3ra Org". The account under which the user is +currently logged in is the "Seminar Organization". +![Accounts List](../../images/accounts/accounts-list.webp "Accounts List") diff --git a/lang/en/docs/accounts/users.md b/lang/en/docs/accounts/users.md index 4668303e8..48df08986 100644 --- a/lang/en/docs/accounts/users.md +++ b/lang/en/docs/accounts/users.md @@ -2,4 +2,4 @@ The notion of a **User** employed throughout the present documentation manual, refers to a human person performing any of the possible actions on the Exabyte platform. This notion should not however be confused with that of [**Accounts**](overview.md#accounts), which may comprise multiple users. -A User has to [switch to](ui/switcher.md) one of (potentially) multiple distinct accounts which are available to him/her in order to perform any actions. +A User has to [switch to]({{ interface_url }}/accounts/ui/switcher/) one of (potentially) multiple distinct accounts which are available to him/her in order to perform any actions. diff --git a/lang/en/docs/benchmarks/2018-11-12-comparison.md b/lang/en/docs/benchmarks/2018-11-12-comparison.md index b94983f53..7c8bc813c 100644 --- a/lang/en/docs/benchmarks/2018-11-12-comparison.md +++ b/lang/en/docs/benchmarks/2018-11-12-comparison.md @@ -1,3 +1,7 @@ +--- +render_macros: false +--- + # 2018-11 Cloud-based Materials Modeling Benchmarks ## Overview diff --git a/lang/en/docs/benchmarks/distributed-memory.md b/lang/en/docs/benchmarks/distributed-memory.md index e09af09a0..85defafce 100644 --- a/lang/en/docs/benchmarks/distributed-memory.md +++ b/lang/en/docs/benchmarks/distributed-memory.md @@ -7,7 +7,7 @@ The purpose of this study was to estimate the extent to which a calculation for a single material can be efficiently scaled. !!! note "Hardware configuration" - Amazon Web Services with the hardware configuration explained [here](../infrastructure/clusters/aws.md) were used for benchmarking. Lowest latency Ethernet network interconnect option was chosen. + Amazon Web Services with the hardware configuration explained [here]({{ resources_url }}/infrastructure/clusters/aws/) were used for benchmarking. Lowest latency Ethernet network interconnect option was chosen. ## Model and Method diff --git a/lang/en/docs/benchmarks/high-throughput-screening.md b/lang/en/docs/benchmarks/high-throughput-screening.md index 686056234..b16572c55 100644 --- a/lang/en/docs/benchmarks/high-throughput-screening.md +++ b/lang/en/docs/benchmarks/high-throughput-screening.md @@ -11,7 +11,7 @@ The team employed quantum mechanical modeling approaches based on density functi The purpose of this study was to estimate the extent to which compute resources can be efficiently scaled while sustaining a constant level of performance. !!! note "Hardware configuration" - Amazon Web Services with the hardware configuration explained [here](../infrastructure/clusters/aws.md) were used for benchmarking + Amazon Web Services with the hardware configuration explained [here]({{ resources_url }}/infrastructure/clusters/aws/) were used for benchmarking ## Model and Method diff --git a/lang/en/docs/benchmarks/hpl-benchmark.md b/lang/en/docs/benchmarks/hpl-benchmark.md index 3c868043c..46477fd70 100644 --- a/lang/en/docs/benchmarks/hpl-benchmark.md +++ b/lang/en/docs/benchmarks/hpl-benchmark.md @@ -1,13 +1,13 @@ # Details -We published a comprehensive comparative benchmarking study for multiple cloud providers: +A comprehensive comparative benchmarking study for multiple cloud providers was published: - + -Original at: [https://arxiv.org/pdf/1702.02968.pdf](https://arxiv.org/pdf/1702.02968.pdf). +Original at: [https://arxiv.org/abs/1702.02968](https://arxiv.org/abs/1702.02968){:target='_blank'}. -## Mentions in press +## Mentions in Press -[^1]: [HPCWire, Website](https://www.hpcwire.com/2017/02/15/hpc-clouds-ready-azure-edges-aws-benchmark-study/) -[^2]: [TheRegister, Website](https://www.theregister.co.uk/2017/02/14/clouds_icani_compete_with_hpc_say_boffins/) -[^3]: [UberCloud, Website](https://www.theubercloud.com/ubercloud-voice-old/) +- [HPCWire](https://www.hpcwire.com/2017/02/15/hpc-clouds-ready-azure-edges-aws-benchmark-study/){:target='_blank'} +- [TheRegister](https://www.theregister.co.uk/2017/02/14/clouds_icani_compete_with_hpc_say_boffins/){:target='_blank'} +- [UberCloud](https://www.theubercloud.com/ubercloud-voice-old/){:target='_blank'} diff --git a/lang/en/docs/benchmarks/overview.md b/lang/en/docs/benchmarks/overview.md index ec2aecd05..522b20675 100644 --- a/lang/en/docs/benchmarks/overview.md +++ b/lang/en/docs/benchmarks/overview.md @@ -1,6 +1,6 @@ # Benchmarks -We have executed a series of benchmark tests to assess the performance of the [high-performance computing nodes](../infrastructure/clusters/overview.md) offered as part of the [general infrastructure](../infrastructure/overview.md) of our platform. The outcomes of such benchmarks are introduced and referenced throughout the remainder of the present page. +We have executed a series of benchmark tests to assess the performance of the [high-performance computing nodes]({{ resources_url }}/infrastructure/clusters/overview/) offered as part of the [general infrastructure]({{ resources_url }}/infrastructure/overview/) of our platform. The outcomes of such benchmarks are introduced and referenced throughout the remainder of the present page. ## [High-Performance Linpack](hpl-benchmark.md) @@ -16,4 +16,4 @@ Example results of a high-throughput screening benchmark are presented [here](hi 2. Additional tests performed around the same time are as explained [here](vendor-comparison.md). -3. 2018 Benchmarks for [VASP](../software-directory/modeling/vasp/overview.md) and [GROMACS](../software-directory/modeling/gromacs.md), are documented [here](2018-11-12-comparison.md). +3. 2018 Benchmarks for [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) and [GROMACS]({{ reference_url }}/software-directory/modeling/gromacs/), are documented [here](2018-11-12-comparison.md). diff --git a/lang/en/docs/cli/accounting.md b/lang/en/docs/cli/accounting.md index d088f71e5..23ba7771f 100644 --- a/lang/en/docs/cli/accounting.md +++ b/lang/en/docs/cli/accounting.md @@ -1,8 +1,8 @@ # Accounting -As explained in detail in the corresponding [part of the documentation](../accounts/overview.md), we implement as system of **Accounts** for managing the user consumption of our computational resources. +As explained in detail in the corresponding [part of the documentation]({{ reference_url }}/accounts/overview/), we implement as system of **Accounts** for managing the user consumption of our computational resources. -These accounts each have a [storage quota](../accounts/quota.md) and a [balance](../accounts/balance.md) for making the necessary [payments](../accounts/payments-charges.md) to our system. These account-related features depend on the choice of the [Service Level](../pricing/service-levels.md). +These accounts each have a [storage quota]({{ reference_url }}/accounts/quota/) and a [balance]({{ reference_url }}/accounts/balance/) for making the necessary [payments]({{ reference_url }}/accounts/payments-charges/) to our system. These account-related features depend on the choice of the [Service Level]({{ guide_url }}/pricing/service-levels/). Information pertaining to accounts can also be retrieved under the [Command Line Interface](overview.md) (CLI) of our platform, as introduced in what follows. diff --git a/lang/en/docs/cli/actions/add-software.md b/lang/en/docs/cli/actions/add-software.md index 4492d08e8..9ce897cdd 100644 --- a/lang/en/docs/cli/actions/add-software.md +++ b/lang/en/docs/cli/actions/add-software.md @@ -1,34 +1,333 @@ -# Add New Software +# Add New Software -The user can compile new software on the [Command Line Interface](../overview.md) (CLI). This is helpful, for example, after introducing some changes or patches to the source code. In order to compile such new software a special permission is required to access the master nodes of our [computational clusters](../../infrastructure/clusters/overview.md), where the compilation shall be performed. This permission can be requested by following [these instructions](../../ui/support.md). +## Overview +Users can compile their own software via the +[Command Line Interface](../overview.md) (CLI). This is helpful if users need +to run a specific version of an application that is not installed "globally". +The globally installed applications are currently distributed as Apptainer[^1] +(Singularity[^2]) containers, bundled with all required dependencies. This +ensures that each application is isolated and avoids dependency conflicts. -We also explain how to add python packages to the environment [in this page](create-python-env.md). +When planning to run an application that is not installed in our cluster, we +encourage packaging code and its dependencies as an Apptainer/Singularity +container. Existing Docker images can be converted into an +Apptainer/Singularity images. -## Example: New Quantum ESPRESSO Version +

+ +
-The user might wish to compile a version of the [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md) simulation package different from the ones offered [through environment modules](modules-actions.md#list-available-modules). This new versions might also include modifications to the source code by the user. +## Using Sandbox mode +Apptainer's sandbox mode is helpful for testing and fine-tuning the build steps +interactively. To start it, first initialize a sandbox with `--sandbox` or `-s` +flag: -We refer to the official documentation [^1] for the instructions on how to compile Quantum ESPRESSO via CLI. Sample routines that allow for the compilation are demonstrated below: +```bash +apptainer build --sandbox gcc_sandbox/ docker://almalinux:9 +``` + +The above command will extract the entire Linux OS tree (`/bin`, `/etc`, `/usr`) +from the AlmaLinux 9 Docker image to a subdirectory named `gcc_sandbox`. + +Now, to install packages and save them to the sandbox folder, we can enter into +the container in shell (interactive) mode with write permission (use +`--writable` or `-w` flag). We will also need `--fakeroot` or `-f` flag to +install software as root inside the container: + +```bash +apptainer shell --writable --fakeroot gcc_sandbox/ +``` + +Once inside the Apptainer shell, we can install packages and run commands +interactively, as we would normally do from the terminal, for example: + +```bash +dnf install gcc +``` + +Once you are happy with the sandbox, have tested the build steps, and installed +everything you need, `exit` from the Apptainer shell mode. + + +## Building containers + +### Build from a Sandbox folder + +We may either package the sandbox directory into a final image: +```bash +apptainer build -f gcc.sif gcc_sandbox/ +``` + +We can verify that our container is working with: +```bash +apptainer exec gcc.sif gcc --version +``` + +After the container is built and saved as an SIF image, we may delete our +sandbox folder. We need to set appropriate permissions to be able to delete: + +```bash +chmod -R u+rwX gcc_sandbox +rm -rf gcc_sandbox +``` + +### Build from a definition file + +Instead of converting the sandbox folder to an SIF image, we may first create an +Apptainer definition with the finalized build steps. Below is an example +Apptainer/Singularity definition to build a Quantum ESPRESSO container +along with its dependencies. + +??? example "Example Apptainer definition (click to expand)" + ```singularity title="espresso.def" + Bootstrap: docker # (1)! + From: almalinux:9 # (2)! + + %labels # (3)! + Maintainer Mat3ra.com + Version QE-7.5-gcc-openmpi-openblas + + %environment # (4)! + export PATH=/usr/lib64/openmpi/bin:/opt/qe-7.5/bin:$PATH + + %post # (5)! + # enable additional repos + dnf install -y epel-release + dnf config-manager --set-enabled crb + + # install dependencies + dnf install -y autoconf \ + gcc \ + gcc-c++ \ + gcc-gfortran \ + git \ + make \ + fftw-devel \ + openblas \ + openblas-devel \ + openmpi-devel \ + scalapack-openmpi-devel \ + wget + + # download QE and compile + VERSION=7.5 + INSTALL_PREFIX="/opt/qe-$VERSION" + BUILD_DIR=~/tmp + mkdir $BUILD_DIR + + cd $BUILD_DIR + wget https://gitlab.com/QEF/q-e/-/archive/qe-${VERSION}/q-e-qe-${VERSION}.tar.gz + tar -xf q-e-qe-${VERSION}.tar.gz + cd q-e-qe-${VERSION} + + export PATH=/usr/lib64/openmpi/bin:$PATH + export FFLAGS="-O2 -fallow-argument-mismatch" + export FCFLAGS="-O2 -fallow-argument-mismatch" + + ./configure --prefix=${INSTALL_PREFIX} MPIF90=mpif90 CC=mpicc F90=gfortran F77=gfortran \ + --with-scalapack=yes \ + BLAS_LIBS="-lopenblas" LAPACK_LIBS="-lopenblas" \ + LDFLAGS="-Wl,-rpath,/usr/lib64/openmpi/lib -Wl,-rpath,/usr/lib64" + + make all -j$(nproc) + make install + + # cleanup + rm -rf $BUILD_DIR + dnf clean all && rm -rf /var/lib/dnf /var/cache/dnf /var/cache/yum + ``` + + 1. Bootstrap from a Docker image + 2. Select base image + 3. Set Metadata such as version, maintainer details, etc. + 4. Set runtime environment variables + 5. Build routine, under the `post` section + +Now we are ready to build the container with: + +```bash +apptainer build espresso.sif espresso.def +``` + +### Build Considerations + +#### Running resource-intensive builds in batch mode + +Prototyping the build is convenient using sandbox mode, but when the routines +are clear and the `.def` file is ready, we suggest that users submit a +[PBS batch script]( ../../jobs-cli/batch-scripts/overview.md) to perform the +build tasks. This ensures that the resource-intensive build process runs on a +compute node rather than the login node itself. As a side "perk", by doing so, +we assert that the compute environment is equivalent to the build environment. + +```bash title="build-qe.pbs" +#!/bin/bash +#PBS -N Build_QE +#PBS -j oe +#PBS -l nodes=1 +#PBS -l ppn=4 +#PBS -l walltime=00:01:00:00 +#PBS -q OR +#PBS -m abe +#PBS -M info@mat3ra.com + +cd $PBS_O_WORKDIR +apptainer build espresso.sif espresso.def +``` + +#### Porting large libraries from the host + +Large libraries such as the Intel OneAPI suite and NVIDIA HPC SDK, which are +several gigabytes in size, can be mapped from the cluster host instead of +bundling together with the application. However, this is not applicable if one +needs a different version of these libraries than the one provided. + +This can be done by using the `--bind` directives and passing the appropriate +library location from the host, e.g., from +`/cluster-001-share/compute/software/libraries` or +`/export/compute/software/libraries/`. + +See the GPU example below for more details. + +#### Building containers with GPU support + +To run applications with GPU acceleration, first, we need to compile the +GPU code with appropriate GPU libraries used, which is done during the container +build phase. Here, we will describe how we can compile our application code +using NVIDIA HPC SDK (which includes CUDA libraries) and package the compiled +code as a containerized application. + +The process works even on systems without GPU devices or drivers, +thanks to the availability of dummy shared objects (e.g., +`libcuda.so`) in recent versions of the NVHPC SDK and CUDA Toolkit. These dummy +libraries allow the linker to complete compilation without requiring an actual +GPU. + +NVIDIA HPC SDK (or CUDA Toolkit) is a large package, +typically several gigabytes in size. Unless a specific version of CUDA is +required, it’s more efficient to map the NVHPC installation available on +the host cluster. Currently, NVHPC 25.3 with CUDA 12.8 is installed in the +Mat3ra clusters. This version matches the NVIDIA driver version on the cluster's +compute nodes. + +We build our GPU containers in two stages: + +1. **Base Image and Compilation Stage**: Install NVHPC and all other +dependencies, and compile the application code. +2. **Slim Production Image**: Create a final production container by copying +only the compiled application and smaller dependencies (if any) into a new base +image, omitting the NVHPC SDK. + +To run such a container, we must `--bind` the NVHPC paths from the host and set +appropriate `PATH` and `LD_LIBRARY_PATH` for apptainer. Specialized software +libraries are installed under `/export/compute/software` in Mat3ra clusters. +Also, to map the NVIDIA GPU drivers from the compute node, we must use the +`--nv` flag. Now, to set `PATH` inside apptainer, we can set +`APPTAINERENV_PREPEND_PATH` (or `APPTAINERENV_APPEND_PATH`) on the host. +However, for other ENV variables, such special Apptainer variables are not +present, so we can use the `APPTAINERENV_` prefix for them. So a typical job +script would look like: + +```bash +export APPTAINERENV_PREPEND_PATH="/export/compute/software/libraries/nvhpc-25.3-cuda-12.8/Linux_x86_64/25.3/comm_libs/12.8/hpcx/hpcx-2.22.1/hcoll/bin:/export/compute/software/libraries/nvhpc-25.3-cuda-12.8/Linux_x86_64/25.3/comm_libs/12.8/hpcx/hpcx-2.22.1/ompi/bin:/export/compute/software/libraries/nvhpc-25.3-cuda-12.8/Linux_x86_64/25.3/comm_libs/12.8/hpcx/hpcx-2.22.1/ucx/mt/bin:/export/compute/software/compilers/gcc/11.2.0/bin" + +export APPTAINERENV_LD_LIBRARY_PATH="/export/compute/software/libraries/nvhpc-25.3-cuda-12.8/Linux_x86_64/25.3/comm_libs/12.8/hpcx/hpcx-2.22.1/hcoll/lib:/export/compute/software/libraries/nvhpc-25.3-cuda-12.8/Linux_x86_64/25.3/comm_libs/12.8/hpcx/hpcx-2.22.1/ompi/lib:/export/compute/software/libraries/nvhpc-25.3-cuda-12.8/Linux_x86_64/25.3/comm_libs/12.8/hpcx/hpcx-2.22.1/nccl_rdma_sharp_plugin/lib:/export/compute/software/libraries/nvhpc-25.3-cuda-12.8/Linux_x86_64/25.3/comm_libs/12.8/hpcx/hpcx-2.22.1/sharp/lib:/export/compute/software/libraries/nvhpc-25.3-cuda-12.8/Linux_x86_64/25.3/comm_libs/12.8/hpcx/hpcx-2.22.1/ucx/mt/lib:/export/compute/software/libraries/nvhpc-25.3-cuda-12.8/Linux_x86_64/25.3/comm_libs/12.8/hpcx/hpcx-2.22.1/ucx/mt/lib/ucx:/export/compute/software/libraries/nvhpc-25.3-cuda-12.8/Linux_x86_64/25.3/comm_libs/12.8/nccl/lib:/export/compute/software/libraries/nvhpc-25.3-cuda-12.8/Linux_x86_64/25.3/compilers/lib:/export/compute/software/libraries/nvhpc-25.3-cuda-12.8/Linux_x86_64/25.3/cuda/12.8/lib64:/export/compute/software/libraries/nvhpc-25.3-cuda-12.8/Linux_x86_64/25.3/math_libs/12.8/lib64:/export/compute/software/compilers/gcc/11.2.0/lib64:\${LD_LIBRARY_PATH}" + +apptainer exec --nv --bind /export,/cluster-001-share pw.x -in pw.in > pw.out +``` + +To understand the details about library paths, one may inspect modulefiles (e.g., +`/cluster-001-share/compute/modulefiles/applications/espresso/7.5-cuda-12.8`) +available in our clusters and [job scripts]( +https://github.com/mat3ra/cli-job-examples/blob/main/espresso/gpu/job.gpu.pbs) +to see how it is implemented. Do not forget to use a GPU-enabled queue, +such as [GOF]({{ resources_url }}/infrastructure/clusters/google/) to submit your GPU jobs. + + +## Run jobs using Apptainer + +Once the container is built, we are ready to run applications packaged in it. A +simple PBS job script would look like: + +```bash title="run-qe.pbs" +#!/bin/bash +#PBS -N Run_QE +#PBS -j oe +#PBS -l nodes=1 +#PBS -l ppn=4 +#PBS -l walltime=00:24:00:00 +#PBS -q OR +#PBS -m abe +#PBS -M info@mat3ra.com + +cd $PBS_O_WORKDIR + +apptainer exec --bind /export,/scratch,/dropbox,/cluster-001-share \ + /path/to/espresso.sif pw.x -in pw.in > pw.out +``` + +Above we `--bind` several host paths to the container so that we can use items +such as pseudopotential files stored under those locations. Submit job with: +```bash +qsub run-qe.pbs +``` + +Monitor job status: +```bash +qstat +``` + +Once the job is completed, all output files will be saved under the directory +from which the job was submitted. Please follow [this documentation page]( +../../jobs-cli/batch-scripts/apptainer.md) to find more about Apptainer +integration. For practical templates, please visit[CLI job examples]( +https://github.com/mat3ra/cli-job-examples). + + +## Transfer external images + +You can build containers on your local machine or use pull pre-built ones from +sources such as [NVIDIA GPU Cloud]( +https://catalog.ngc.nvidia.com/orgs/hpc/containers/quantum_espresso). + +If the container is build locally, you can push the image to a container +registry such as the [GitHub Container Registry]( +https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry). + +```bash +apptainer push espresso.sif oras://ghcr.io///: +``` + +Then, pull the image from the login node:: ```bash -# Create temporary directory -mkdir q-e-compilation && cd q-e-compilation +apptainer pull oras://ghcr.io///: +``` + +!!! tip + - You may use GitHub workflow to build images and push to GHCR. + - When pulling a Docker image, Apptainer will automatically convert and save + it as SIF file. + +Alternatively, you can copy the local image file directly to the cluster +via SCP: + +```bash +scp espresso.sif @login.mat3ra.com:/cluster-001-home// +``` + +## Other Notes -# Download and upack the archive -wget https://github.com/QEF/q-e/archive/qe-6.3MaX.tar.gz -tar -xvzf qe-6.3MaX.tar.gz -cd q-e-qe-6.3MaX/ +### Cleaning Cache -# Load modules -module load mpi/ompi-110 openblas/218-g-540 -./configure -make libfox -make pw -``` +Apptainer can use a significant amount of cache disc space. We can use +`--disable-cache` flag or clean Apptainer cache periodically with: -!!! warning "Compilation routines are given for demonstration only" - The commands below are present to demonstrate the approach only and are limited in applicability. They do not include any consideration of the optimization of parallel performance, for example. +``` +apptainer cache clean --force +``` ## Links -[^1]: [User’s Guide for Quantum ESPRESSO, Document](https://www.quantum-espresso.org/Doc/user_guide.pdf) +[^1]: [Apptainer User Guide](https://apptainer.org/docs/user/latest/) +[^2]: [Singularity User Guide](https://docs.sylabs.io/guides/latest/user-guide/) diff --git a/lang/en/docs/cli/actions/apptainer-tutorial.json b/lang/en/docs/cli/actions/apptainer-tutorial.json new file mode 100644 index 000000000..68935acec --- /dev/null +++ b/lang/en/docs/cli/actions/apptainer-tutorial.json @@ -0,0 +1,221 @@ +{ + "descriptionLinks": [ + "Build containerized applications with GPU support: https://docs.mat3ra.com/cli/actions/add-software/" + ], + "description": "How to build containerized applications with GPU support using Apptainer.", + "tags": [ + { + "...": "../../metadata/general.json#/tags" + }, + "apptainer", + "container", + "containerization", + "gpu", + "nvidia", + "singularity" + ], + "title": "Mat3ra Tutorial: Build containerized applications with GPU support", + "youTubeCaptions": [ + { + "text": "In this tutorial, we will learn, how we can build containerized applications with Apptainer.", + "startTime": "00:00:00.150", + "endTime": "00:00:06.000" + }, + { + "text": "We will also discuss how you can enable GPU support for such containers.", + "startTime": "00:00:06.500", + "endTime": "00:00:15.000" + }, + { + "text": "The detailed steps of this tutorial are available on our documentation site.", + "startTime": "00:00:16.000", + "endTime": "00:00:21.000" + }, + { + "text": "The documentation link can be found in the description below.", + "startTime": "00:00:21.500", + "endTime": "00:00:25.000" + }, + { + "text": "Now, let's head over to platform dot matera dot com and launch the web terminal.", + "startTime": "00:00:25.500", + "endTime": "00:00:30.000" + }, + { + "text": "Alternatively, you can connect to the login node using SSH.", + "startTime": "00:00:30.500", + "endTime": "00:00:34.000" + }, + { + "text": "Let's verify that the Apptainer is installed, and check its version.", + "startTime": "00:00:34.500", + "endTime": "00:00:39.000" + }, + { + "text": "First, we can use the Apptainer sandbox mode to test and fine tune the build steps interactively.", + "startTime": "00:00:39.500", + "endTime": "00:00:45.000" + }, + { + "text": "Once the build steps are finalized, we can package the sandbox folder into a final image.", + "startTime": "00:00:45.500", + "endTime": "00:00:51.000" + }, + { + "text": "Or, we can create a definition file with finalized build steps and build the container from it.", + "startTime": "00:00:51.500", + "endTime": "00:00:55.000" + }, + { + "text": "Let's call our sandbox folder GCC sandbox.", + "startTime": "00:00:55.500", + "endTime": "00:01:00.000" + }, + { + "text": "And initialize the sandbox with Alma Linux 9 base-image from the Docker registry.", + "startTime": "00:01:00.500", + "endTime": "00:01:06.000" + }, + { + "text": "Notice the warning messages, we first need to set appropriate file permissions for the sandbox folder to be able to delete it later.", + "startTime": "00:01:06.500", + "endTime": "00:01:13.000" + }, + { + "text": "Next, we can enter the sandbox container in the shell mode with write permission and as root user.", + "startTime": "00:01:13.500", + "endTime": "00:01:19.000" + }, + { + "text": "Now, we can install packages in the sandbox container as you would normally do.", + "startTime": "00:01:19.500", + "endTime": "00:01:24.000" + }, + { + "text": "Once the installation is complete, we can exit the sandbox container.", + "startTime": "00:01:24.500", + "endTime": "00:01:28.000" + }, + { + "text": "We can package the sandbox folder into a final image with the build command.", + "startTime": "00:01:28.500", + "endTime": "00:01:33.000" + }, + { + "text": "Now, we can verify that the container is working by running the GCC compiler.", + "startTime": "00:01:33.500", + "endTime": "00:01:38.000" + }, + { + "text": "There is a second way to build the container, by creating a definition file with the build steps.", + "startTime": "00:01:38.500", + "endTime": "00:01:45.000" + }, + { + "text": "An example definition file is available in our documentation site, let's copy it to clipboard.", + "startTime": "00:01:45.500", + "endTime": "00:01:51.000" + }, + { + "text": "To transfer the clipboard content from the host machine to the web terminal, we can open the Remote-connection Sidebar by pressing Control Alt Shift in Windows and Linux or Control Option Shift in Mac.", + "startTime": "00:01:51.500", + "endTime": "00:02:03.000" + }, + { + "text": "We can open vim editor, press i to enter insert mode, and right click to paste the clipboard content.", + "startTime": "00:02:03.500", + "endTime": "00:02:08.000" + }, + { + "text": "Press the escape key, and type colon w q to save and exit the file.", + "startTime": "00:02:08.500", + "endTime": "00:02:14.000" + }, + { + "text": "Now, we can run apptainer build command with the image name followed by the definition file name.", + "startTime": "00:02:14.500", + "endTime": "00:02:19.000" + }, + { + "text": "However note that computationally intensive builds should not be directly run on the login node.", + "startTime": "00:02:19.500", + "endTime": "00:02:25.000" + }, + { + "text": "Instead they should be submitted as a job to the batch system as described in our documentation.", + "startTime": "00:02:25.500", + "endTime": "00:02:30.000" + }, + { + "text": "If you need GPU support, please use the dash dash NV flag with apptainer exec command.", + "startTime": "00:02:30.500", + "endTime": "00:02:37.000" + }, + { + "text": "This will map the necessary drivers from the host to the container and set the necessary environment variables.", + "startTime": "00:02:37.500", + "endTime": "00:02:44.000" + }, + { + "text": "Note that it is not necessary to install all dependencies inside the container.", + "startTime": "00:02:44.500", + "endTime": "00:02:49.000" + }, + { + "text": "Especially large libraries like NVIDIA HPC SDK or Intel OneAPI.", + "startTime": "00:02:49.500", + "endTime": "00:02:55.000" + }, + { + "text": "Instead, you can map such libraries from the host to the container using the bind directive.", + "startTime": "00:02:55.500", + "endTime": "00:03:01.000" + }, + { + "text": "Commonly used libraries are available in our clusters under /export or /cluster-share directories.", + "startTime": "00:03:01.500", + "endTime": "00:03:06.000" + }, + { + "text": "You may visit our open source container registry at GitHub to inspect the definition files.", + "startTime": "00:03:06.500", + "endTime": "00:03:11.000" + }, + { + "text": "You are also welcome to contribute to our container registry by submitting a pull request.", + "startTime": "00:03:11.500", + "endTime": "00:03:16.000" + }, + { + "text": "And build containers automatically via GitHub Actions workflow.", + "startTime": "00:03:16.500", + "endTime": "00:03:22.000" + }, + { + "text": "Once the images are built, they are listed under the packages.", + "startTime": "00:03:022.500", + "endTime": "00:03:27.000" + }, + { + "text": "First select the application name, then select appropriate image tag and copy its URL.", + "startTime": "00:03:27.500", + "endTime": "00:03:32.000" + }, + { + "text": "We can go back to the web terminal and download the image using apptainer pull command.", + "startTime": "00:03:32.500", + "endTime": "00:03:38.000" + }, + { + "text": "Now, visit platform dot matera dot com and try building your own containers.", + "startTime": "00:03:38.500", + "endTime": "00:03:44.000" + }, + { + "text": "Thank you for watching this tutorial and using our platform.", + "startTime": "00:03:44.500", + "endTime": "00:03:46.000" + } + ], + "youTubeId": "G1hfW_kS8oY" +} diff --git a/lang/en/docs/cli/actions/balance-quota.md b/lang/en/docs/cli/actions/balance-quota.md index c79b730ca..1e4184009 100644 --- a/lang/en/docs/cli/actions/balance-quota.md +++ b/lang/en/docs/cli/actions/balance-quota.md @@ -1,12 +1,12 @@ # Check Account Quota and Balance -This page explains how to retrieve [accounting information](../../accounts/overview.md) for users logged-in via the [Command Line Interface](../overview.md), including information about any [Organizational Accounts](../../collaboration/organizations/overview.md) that the user may be member of. +This page explains how to retrieve [accounting information]({{ reference_url }}/accounts/overview/) for users logged-in via the [Command Line Interface](../overview.md), including information about any [Organizational Accounts]({{ reference_url }}/collaboration/organizations/overview/) that the user may be member of. Each of the commands outlined in what follows can accept keyword parameters as option flags, as listed by passing the `--help` flag to them. ## Account Balance -Information about the [Account Balance](../../accounts/balance.md) (in US dollars) is accessed using the `balance` command, as demonstrated in the example below. +Information about the [Account Balance]({{ reference_url }}/accounts/balance/) (in US dollars) is accessed using the `balance` command, as demonstrated in the example below. `# > balance` @@ -16,7 +16,7 @@ Id Name Amount Reserved Balance CreditLimit Available 1 steven 1000.00 10.00 990.00 0.00 990.00 ``` -The entries returned by the above command are summarized in the table below, complementing their [general discussion](../../accounts/balance.md). We remind the reader that in order to perform computations on our platform, a positive balance is required. +The entries returned by the above command are summarized in the table below, complementing their [general discussion]({{ reference_url }}/accounts/balance/). We remind the reader that in order to perform computations on our platform, a positive balance is required. | Entry | Description | @@ -30,7 +30,7 @@ The entries returned by the above command are summarized in the table below, com ## Itemized Account Statement -We track the **usage** of our platform, or [balance](../../accounts/balance.md) spent on computations per each [account](../../accounts/overview.md) and each [project](../../jobs/projects.md). The usage statistics of each [cluster](../../infrastructure/clusters/overview.md), in terms of number of CPU hours consumed and charges incurred, is referred to as the **Account Statement**. +We track the **usage** of our platform, or [balance]({{ reference_url }}/accounts/balance/) spent on computations per each [account]({{ reference_url }}/accounts/overview/) and each [project]({{ reference_url }}/jobs/projects/). The usage statistics of each [cluster]({{ resources_url }}/infrastructure/clusters/overview/), in terms of number of CPU hours consumed and charges incurred, is referred to as the **Account Statement**. This statement can be inspected with the `statement` command under CLI, as demonstrated in the example below. @@ -78,11 +78,11 @@ It is often convenient to pass the `-s` (start) and `-e` (end) flags to the `sta ## Detailed List of Jobs -Information about all jobs submitted by the user to date can be retrieved as explained [here](../../jobs-cli/put-link). +Information about all jobs submitted by the user to date can be retrieved as explained [here](../../jobs-cli/overview.md). ## Storage Quota -Information about the [Storage Quota](../../accounts/quota.md) within the available [computing clusters](../../infrastructure/clusters/overview.md) can be retrieved via the `quotas` command. An example of output of this command is shown below. +Information about the [Storage Quota]({{ reference_url }}/accounts/quota/) within the available [computing clusters]({{ resources_url }}/infrastructure/clusters/overview/) can be retrieved via the `quotas` command. An example of output of this command is shown below. ```bash >>> quotas @@ -94,4 +94,4 @@ USED BSOFT BHARD BWARN BGRACE IUSED ISOFT IHARD IWARN This output contains information about the used storage space under the first column. We don't allow for "soft" quotas (under "BSOFT" column) for temporarily exceeding the maximum allowed limit, hence "soft" and "hard" quotas match to the same total limit value, and no "Grace" period is available. The remaining columns starting with "I" concern the compute nodes as opposed to the clusters. !!!warning "Authorization Required to Access Clusters via CLI" - In order to use the `quotas` command, the user needs to first access the clusters via SSH. Please [submit a support request](../../ui/support.md) for gaining the necessary permissions to do this. + In order to use the `quotas` command, the user needs to first access the clusters via SSH. Please [submit a support request]({{ interface_url }}/ui/support/) for gaining the necessary permissions to do this. diff --git a/lang/en/docs/cli/actions/customize.md b/lang/en/docs/cli/actions/customize.md index 2ded7986d..2e802f14d 100644 --- a/lang/en/docs/cli/actions/customize.md +++ b/lang/en/docs/cli/actions/customize.md @@ -12,7 +12,7 @@ change_shell /bin/zsh ## Dot Files -There exist several hidden system configuration files, or "dot-files", within the [Login Home](../../infrastructure/login/directories.md), such as the `.bashrc` and `.bash_profile` files. Caution is advised when modifying such files, since they can significantly affect the functionality of the shell environment. In case of uncertainty, we recommend the reader to consult relevant documentation manuals on the general Linux environment before implementing any change to these files. +There exist several hidden system configuration files, or "dot-files", within the [Login Home]({{ resources_url }}/infrastructure/login/directories/), such as the `.bashrc` and `.bash_profile` files. Caution is advised when modifying such files, since they can significantly affect the functionality of the shell environment. In case of uncertainty, we recommend the reader to consult relevant documentation manuals on the general Linux environment before implementing any change to these files. !!!warning "NEVER remove the system content of the ".ssh" folder" We urge the user not to remove the default content of the files in the ".ssh" folder, since doing so can break the operations of the platform for the user. @@ -124,7 +124,7 @@ It should show a path pointing to your local directory: `~/.local/bin` +Relevant pages include: -## Exabyte Data Convention +- [Data convention]({{ data_url }}/data-structured/overview/) +- [Materials data]({{ data_url }}/materials/data/) +- [Workflows data]({{ data_url }}/workflows/data/overview/) +- [Properties data]({{ data_url }}/properties/data/list/) -We employ a [data convention](../data-structured/overview.md) that supports storing materials, simulations and properties in an organized and easy-to-navigate manner. It is designed with collaborative access to data in mind, and has a flexible permission scheme allowing for complete privacy or wide publicity. +## 5. Account-related Items -We store all data about simulations and materials. Data originated from web application is automatically organized and searchable within the web interface. Data originated on command line is [accessible from within the web application](../data-in-objectstorage/overview.md), and can also be further imported and organized for future search and potential use in advanced analytics / data mining / machine learning applications. We further explain our approach [here](../data/overview.md). +Considerations related to accounts, service levels, and data ownership can be found under the links below: -Find out more under the following pages: +- [Accounts and their types]({{ reference_url }}/accounts/overview/) +- [Service levels and pricing](../pricing/service-levels.md) +- [Entities and permissions]({{ reference_url }}/entities-general/permissions/) +- [Accounts and collaboration]({{ reference_url }}/collaboration/organizations/overview/) +- [Storage quotas]({{ reference_url }}/accounts/quota/) +- [Account balance]({{ reference_url }}/accounts/balance/) -- [data convention](../data-structured/overview.md) -- [materials data](../materials/data.md) -- [workflows data](../workflows/data/overview.md) -- [properties data](../properties/data/list.md) -## Account-related Items +## 6. Developer Resources -Other considerations related to accounts, their service and data ownership/permissions can be found under the links below: +### 6.1. Open-Source Packages -- [accounts and their types](../accounts/overview.md) -- [service levels and pricing](../pricing/service-levels.md) -- [entities and permissions](../entities-general/permissions.md) -- [accounts and collaboration](../collaboration/organizations/overview.md) -- [storage quotas](../accounts/quota.md) -- [account balance](../accounts/balance.md) +Python packages are available on [PyPI](https://pypi.org/search/?q=mat3ra){:target='_blank'}: + +- [mat3ra-made](https://pypi.org/project/mat3ra-made/){:target='_blank'} — Materials Design library for creating and manipulating structures +- [mat3ra-esse](https://pypi.org/project/mat3ra-esse/){:target='_blank'} — Exabyte Source of Schemas and Examples (ESSE) data standard +- [mat3ra-api-examples](https://pypi.org/project/mat3ra-api-examples/){:target='_blank'} — example notebooks for REST API usage +- [mat3ra-parsers](https://pypi.org/project/mat3ra-parsers/){:target='_blank'} — parsers for computational materials science file formats +- [mat3ra-standata](https://pypi.org/project/mat3ra-standata/){:target='_blank'} — standardized material and simulation data + +JavaScript packages are available on [npm](https://www.npmjs.com/search?q=%40mat3ra){:target='_blank'}: + +- [@mat3ra/made](https://www.npmjs.com/package/@mat3ra/made){:target='_blank'} — Materials Design library (JavaScript / TypeScript) + +### 6.2. Open-Source Repositories + +- [Mat3ra GitHub organization](https://github.com/mat3ra/){:target='_blank'} — data structures for materials, workflows, and properties +- [Materials Designer](https://github.com/mat3ra/materials-designer){:target='_blank'} — JavaScript library for web-based materials design +- [API examples](https://github.com/mat3ra/api-examples){:target='_blank'} — Jupyter notebooks demonstrating REST API usage + +### 6.3. Programmatic Access (REST API) + +- [Upload materials](https://github.com/mat3ra/api-examples/blob/main/examples/material/create_material.ipynb){:target='_blank'} +- [Run simulations and extract properties as JSON](https://github.com/mat3ra/api-examples/blob/main/examples/job/run-simulations-and-extract-properties.ipynb){:target='_blank'} +- [All API examples (GitHub)](https://github.com/mat3ra/api-examples){:target='_blank'} + + +## 7. Learning Resources + +### 7.1. Example Tutorials + +- [Create a molecule on a surface]({{ guide_url }}/tutorials/materials/molecule-surface/) +- [NEB chemical reaction profile]({{ guide_url }}/tutorials/dft/chemical/reaction-profile-qe/) +- [Train a machine learning force field]({{ guide_url }}/tutorials/ml/deepmd-mlff-with-espresso-cp-and-lammps/) +- [Run a command-line job]({{ guide_url }}/tutorials/jobs-cli/job-cli-example/) +- [Run a Jupyter notebook connected to REST API]({{ guide_url }}/tutorials/other/jupyter/) + +### 7.2. Mat3ra 2D Webinar Series + +A recurring webinar series on 2D materials design, defect engineering, and DFT simulations. Recordings are available on the [Mat3ra YouTube channel](https://www.youtube.com/@Mat3ra){:target='_blank'}. + +### 7.3. Online Tools + +- [JupyterLite Materials Designer](https://jupyterlite.mat3ra.com){:target='_blank'} — browser-based materials design environment (no installation required) + +### 7.4. Video Resources + +- [Mat3ra YouTube channel](https://www.youtube.com/@Mat3ra){:target='_blank'} — tutorial voiceovers, webinar recordings, and platform walkthroughs diff --git a/lang/en/docs/getting-started/first-steps.md b/lang/en/docs/getting-started/first-steps.md new file mode 100644 index 000000000..fbf9d32e8 --- /dev/null +++ b/lang/en/docs/getting-started/first-steps.md @@ -0,0 +1,42 @@ +# First Steps + +New to Mat3ra? This page outlines the essential steps to begin using the platform. + +!!!tip "Running first simulations" + The fastest way to get started is to follow the [first simulation walkthrough (web interface)](run-first-simulation/web-interface.md) or the [CLI job tutorial](run-first-simulation/cli-job.md). + +## 1. Log In + +The platform is accessed through the [login page](http://platform.mat3ra.com/login){:target='_blank'}. Two connection methods are available: the [web interface]({{ interface_url }}/ui/overview/) and the [command-line interface (CLI)]({{ cli_url }}/cli/overview/). More details are on the [connection options]({{ cli_url }}/remote-connection/overview/) page. + +## 2. Create Materials + +Material structures can be [designed]({{ interface_url }}/materials-designer/overview/) in the browser, [uploaded]({{ interface_url }}/materials/actions/upload/) from files (POSCAR, CIF, XYZ), or [imported]({{ interface_url }}/materials/actions/import/) from third-party databases. For step-by-step instructions, see the [materials design tutorials]({{ guide_url }}/#1-materials-design). + +## 3. Set Up a Workflow + +[Workflows]({{ reference_url }}/workflows/overview/) define the simulation logic — model, method, and software. Pre-built workflows for common properties are available in the [workflows bank]({{ reference_url }}/workflows/bank/). For background on models and methods, see [Key Concepts](concepts.md). + +## 4. Run a Simulation + +Configure [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/) (queue, nodes, time limit) and submit the job. The platform supports multiple [clusters]({{ resources_url }}/infrastructure/clusters/overview/) including AWS and Azure. For a walkthrough, see [Running First Simulations](run-first-simulation/web-interface.md). + +## 5. Analyze Results + +Simulation data is automatically organized and searchable. Results can be viewed in the web interface or accessed programmatically via the [REST API]({{ developers_url }}/). The [data convention]({{ data_url }}/data-structured/overview/) describes how materials, workflows, and properties are stored. + +## Next Steps + +| Goal | Where to go | +|:-----|:------------| +| Documentation overview and useful links | [Content Highlights](content-highlights.md) | +| Understand platform concepts | [Key Concepts](concepts.md) | +| Running first simulation (web) | [Web Interface](run-first-simulation/web-interface.md) | +| Running first simulation (CLI) | [Command Line](run-first-simulation/cli-job.md) | +| Follow step-by-step tutorials | [Tutorials]({{ guide_url }}/) | +| Learn the web interface | [User Interface]({{ interface_url }}/) | +| Understand models and methods | [Concepts & Reference]({{ reference_url }}/) | +| Use the CLI for batch jobs | [Command-Line Interface]({{ cli_url }}/) | +| Access the platform via code | [REST API / Developers]({{ developers_url }}/) | +| Check pricing and service levels | [Pricing](../pricing/service-levels.md) | + diff --git a/lang/en/docs/getting-started/important-concepts.md b/lang/en/docs/getting-started/important-concepts.md deleted file mode 100644 index deaf7cd29..000000000 --- a/lang/en/docs/getting-started/important-concepts.md +++ /dev/null @@ -1,31 +0,0 @@ -# Important Concepts - -In this page we introduce some important concepts explaining the operations of our platform. Links are attached to the keywords below, redirecting the user to the relevant documentation section containing more explanation. - -## Relationship - -Our platform enables the execution of computational **[Workflows](../workflows/overview.md)** applied upon **[Materials](../materials/overview.md)**, in order to extract a set of desired **[Properties](../properties/overview.md)**. We refer to **[Jobs](../jobs/overview.md)** as "containers" of Workflows and Materials information. - -The flowchart diagram below visualizes the general relationship between the above-mentioned entity types. Here, the Properties associated to each entity are labeled with P. Those properties which are computed as output of a Job (also referred to as [Characteristic Properties](../properties/classification/general.md)), are shown in black - P, and consequently have a certain numerical [precision](../methods/data.md) inherited from the Workflow and Job. - -![Entities Relations](../images/getting-started/entities-relations.png "Entities Relations") - -Jobs also refer to the simulation tasks on the Compute platform, as illustrated in the visual below. - -![Simulation Components](../images/getting-started/simulation-components.png "Simulation Components") - -## Main Entities - -The three above-mentioned concepts of Workflows, Materials and Jobs can be grouped together under the same general umbrella term of **[Entities](../entities-general/overview.md)**, due to the many features and user interface components that they share in common. We review the similarities under [Entities and Common Aspects](../entities-general/overview.md) and then explain the details unique to each Entity type separately. - -For example, Jobs have **[Accounting](../accounts/overview.md)** set up for. Workflows and Materials are both **["Bankable" Entities](../entities-general/bank.md)**. Workflows further consist of **[Subworkflows](../workflows/components/subworkflows.md)**, and further of the combination of individual **[Units](../workflows/components/units.md)**, such as portrayed in the example diagram below. - -![Workflow Components](../images/getting-started/workflow-components.png "Workflow Components") - -## Other Items - -Such simulations can be performed with any of the available **[modeling Applications](../software/components.md)**, implementing the supported **[theoretical Models](../models/overview.md)** and corresponding **[computational Methods](../methods/overview.md)**. - -## Data and Infrastructure - -Our platform is designed to store and organize the **[simulation Data](../data/classification.md)** in centralized databases, under the conventions of **[Structured Representation](../data-structured/convention.md)**. A system of **[Queues](../infrastructure/resource/queues.md)** is in place for scheduling and tracking the allocation of **[computational Resources](../infrastructure/resource/overview.md)**, offered by the **[Clusters](../infrastructure/clusters/overview.md)** at the heart of our overall **[Infrastructure](../infrastructure/overview.md)**. diff --git a/lang/en/docs/getting-started/run-first-simulation/cli-job.md b/lang/en/docs/getting-started/run-first-simulation/cli-job.md index 32a611e47..0ad6b392a 100644 --- a/lang/en/docs/getting-started/run-first-simulation/cli-job.md +++ b/lang/en/docs/getting-started/run-first-simulation/cli-job.md @@ -1,69 +1,69 @@ # Jobs via Command-line Interface -The user may want more control over the [workflow execution](../../workflows/overview.md), or run a type of calculation we have yet to implement. For that purpose, we provide access to our platform through [Command Line Interface (CLI)](../../cli/overview.md), were [simulation Jobs](../../jobs/overview.md) can be executed. +The user may want more control over the [workflow execution]({{ reference_url }}/workflows/overview/), or run a type of calculation we have yet to implement. For that purpose, we provide access to our platform through [Command Line Interface (CLI)]({{ cli_url }}/cli/overview/), were [simulation Jobs]({{ reference_url }}/jobs/overview/) can be executed. -Complete instructions on how to operate job submission via CLI can be found [in this section](../../jobs-cli/overview.md). We also provide a [tutorial](../../tutorials/jobs-cli/job-cli-example.md) dedicated to this topic, including on how to [retrieve and inspect](../../tutorials/jobs-cli/job-cli-example.md) the final results of the simulation. +Complete instructions on how to operate job submission via CLI can be found [in this section]({{ cli_url }}/jobs-cli/overview/). We also provide a [tutorial](../../tutorials/jobs-cli/job-cli-example.md) dedicated to this topic, including on how to [retrieve and inspect](../../tutorials/jobs-cli/job-cli-example.md) the final results of the simulation. ## Command-line Interface -We provide an an incorporated [Web Terminal](../../remote-connection/web-terminal.md) to conveniently access the CLI. Alternatively, the user can use the [SSH protocol](../../remote-connection/ssh.md). +We provide an an incorporated [Web Terminal]({{ cli_url }}/remote-connection/web-terminal/) to conveniently access the CLI. Alternatively, the user can use the [SSH protocol]({{ cli_url }}/remote-connection/ssh/). -To use the former Web Terminal interface, open the [right-hand sidebar](../../ui/right-sidebar.md) and click `Terminal`. +To use the former Web Terminal interface, open the [Account Menu]({{ interface_url }}/ui/account-menu/) and click `Terminal`. -The simulations that have been submitted through the main [Web Interface](../../ui/overview.md) are under the `data/` sub-directory under the main [Login Home directory](../../infrastructure/login/directories.md). +The simulations that have been submitted through the main [Web Interface]({{ interface_url }}/ui/overview/) are under the `data/` sub-directory under the main [Login Home directory]({{ resources_url }}/infrastructure/login/directories/). -Our [queuing system](../../infrastructure/resource/queues.md) is controlled through the use of [batch scripts](../../jobs-cli/batch-scripts/overview.md). The reader can find batch script templates under the [job templates directory](../../jobs-cli/batch-scripts/directories.md#job-templates). +Our [queuing system]({{ resources_url }}/infrastructure/resource/queues/) is controlled through the use of [batch scripts]({{ cli_url }}/jobs-cli/batch-scripts/overview/). The reader can find batch script templates under the [job templates directory]({{ cli_url }}/jobs-cli/batch-scripts/directories.md#job-templates). ## Create job ### Prepare subdirectory -To create a job under the CLI, we recommend working inside the aforementioned `~/data/` sub-directory. The user should create a new [working directory](../../jobs-cli/batch-scripts/directories.md#working-directory) under this sub-directory (called `test_job`, for example). +To create a job under the CLI, we recommend working inside the aforementioned `~/data/` sub-directory. The user should create a new [working directory]({{ cli_url }}/jobs-cli/batch-scripts/directories.md#working-directory) under this sub-directory (called `test_job`, for example). ```bash mkdir test_job ``` -A convenient way to get acquainted with our CLI is to start by copying the template [batch script file](../../jobs-cli/batch-scripts/overview.md) from within the `~/job-script-templates` [folder](../../jobs-cli/batch-scripts/directories.md#job-templates), and rename it as `job.script`. These actions can be performed with the following command, for the example case of the [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md) template. +A convenient way to get acquainted with our CLI is to start by copying the template [batch script file]({{ cli_url }}/jobs-cli/batch-scripts/overview/) from within the `~/job-script-templates` [folder]({{ cli_url }}/jobs-cli/batch-scripts/directories.md#job-templates), and rename it as `job.script`. These actions can be performed with the following command, for the example case of the [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) template. ```bash cp ~/job_script_templates/espresso/job.pbs ~/data//test_job/job.script ``` - + Copy any necessary simulation input files or executables into this current working directory as well. ### Edit submission script -The user may need to edit the batch script if he/she wants to use a [simulation software](../../software-directory/overview.md) other the default. Directions on how to set resource manager variables can be found in [the batch script examples](../../jobs-cli/batch-scripts/sample-scripts.md). A comprehensive list of the resource manager options is available [here](../../jobs-cli/batch-scripts/directives.md). +The user may need to edit the batch script if he/she wants to use a [simulation software]({{ reference_url }}/software-directory/overview/) other the default. Directions on how to set resource manager variables can be found in [the batch script examples]({{ cli_url }}/jobs-cli/batch-scripts/sample-scripts/). A comprehensive list of the resource manager options is available [here]({{ cli_url }}/jobs-cli/batch-scripts/directives/). -In addition, if the user would like to alter runtime environment for the calculation, can may consult [modules environment](../../cli/environment.md) section of our documentation. +In addition, if the user would like to alter runtime environment for the calculation, can may consult [modules environment]({{ cli_url }}/cli/environment/) section of our documentation. -Lastly, the options for choosing the queue to submit the job can be found [here](../../infrastructure/resource/queues.md). +Lastly, the options for choosing the queue to submit the job can be found [here]({{ resources_url }}/infrastructure/resource/queues/). !!!tip "Accounting Project Parameter" - In order to specify a [project](../../jobs/projects.md) that the job should belong to and should be [charged upon](../../accounts/payments-charges.md), the instructions contained [in this page](../../jobs-cli/accounting.md) should be followed. + In order to specify a [project]({{ reference_url }}/jobs/projects/) that the job should belong to and should be [charged upon]({{ reference_url }}/accounts/payments-charges/), the instructions contained [in this page]({{ cli_url }}/jobs-cli/accounting/) should be followed. In the present tutorial we will proceed with the default submission script template, without modification. ## Submit job -As a next step, the user can [submit the batch script](../../jobs-cli/actions/submit.md) for job execution using the `qsub` resource manager command: - +As a next step, the user can [submit the batch script]({{ cli_url }}/jobs-cli/actions/submit/) for job execution using the `qsub` resource manager command: + ```bash qsub job.script ``` - + Our resource management system will respond with a message letting know that the job was accepted. ## Monitor job -In order to check on the [current status](../../jobs-cli/actions/check-status.md) of the job, type the following command. +In order to check on the [current status]({{ cli_url }}/jobs-cli/actions/check-status/) of the job, type the following command. ```bash qstat ``` -Once the job starts running, all the output will be placed in the [working directory](../../jobs-cli/batch-scripts/directories.md#working-directory) where the `qsub` command was originally executed from (unless the "directory" line was changed within the batch script file). +Once the job starts running, all the output will be placed in the [working directory]({{ cli_url }}/jobs-cli/batch-scripts/directories.md#working-directory) where the `qsub` command was originally executed from (unless the "directory" line was changed within the batch script file). ## Animation diff --git a/lang/en/docs/getting-started/run-first-simulation/web-interface.md b/lang/en/docs/getting-started/run-first-simulation/web-interface.md index 96ad543ee..77ddfe6b2 100644 --- a/lang/en/docs/getting-started/run-first-simulation/web-interface.md +++ b/lang/en/docs/getting-started/run-first-simulation/web-interface.md @@ -1,80 +1,199 @@ -# Jobs via Web Interface +# Running Jobs via Web Interface + +This page explains how to run a simple [density functional theory calculation]({{ reference_url }}/models-directory/dft/overview/) to obtain [electronic band structure]({{ reference_url }}/properties-directory/non-scalar/bandstructure/) of silicon via our main +[Web Interface]({{ interface_url }}/ui/overview/). + +Before going into the detailed step-by-step instructions, first we present a +short video tutorial to get an overview of the process and look-and-feel of +various UI components of Mat3ra web platform. + +
+ +
+ +Running simulations in Mat3ra web platform involves three main steps: + +1. Specify the material system by creating or importing crystal structure +2. Create or import workflow, which specifies the simulation steps +3. Create and submit job with material(s) of interest, workflow steps and + required compute parameters. + +Each [account]({{ reference_url }}/accounts/overview/) is pre-configured with a default +[material]({{ reference_url }}/materials/overview/) and [workflow]({{ reference_url }}/workflows/overview/). Silicon with standard FCC structure is the default +material, and "Total Energy" calculation with Quantum ESPRESSO is the default +workflow added to each account on creation. However, it is possible to set a +different material and workflow as default during the account creation or later. +We maintain a ["Bank"]({{ reference_url }}/entities-general/bank/) (collection) of materials +and workflows, which includes both Mat3ra-curated and user contributed material +structures and workflows. + + +## 1. Material structure + +There are several ways, we can add new material structures to our account +collection: + +- Import crystal structures from the [Materials Bank]({{ reference_url }}/entities-general/bank/) +- Import crystal structures from a third-party source such as + [Materials Project](https://materialsproject.org/) using [Import]({{ interface_url }}/materials/actions/import/) action +- Upload crystal structures from your local computer such as CIF, POSCAR + formatted files using [Upload]({{ interface_url }}/materials/actions/upload/) action +- Create a new material structure from scratch using [Materials Designer]({{ interface_url }}/materials-designer/overview/). + +To import a material or workflow from the Bank to user's own account collection, +select the "Bank" option in the [left-hand sidebar]({{ interface_url }}/ui/left-sidebar/), +and then select "Materials" or "Workflows" as the user prefers. Then select the +desired material or workflow entry and click "Copy" button in the Actions +column, as explained in more detail [here]({{ interface_url }}/entities-general/actions/copy-bank/). Readers can find additional +details on how to [import]({{ interface_url }}/materials/actions/import/) materials with the +aid of the incorporated Mat3ra Materials Designer tool, as well as further +setting a material as the [default]({{ interface_url }}/entities-general/actions/set-default/) for the account. + + +## 2. Workflow steps + +A workflow can be created from scratch or imported from the Workflows Bank. In +the animation below, we demonstrate how to import the "Band Structure + Density +of States" workflow for [Quantum ESPRESSO]( +{{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) from the +Workflow Bank to our account collection. -This page explains how to run a simple [density functional theory calculation](../../models-directory/dft/overview.md) to obtain an [electronic band structure](../../properties-directory/non-scalar/bandstructure.md) via our main [Web Interface](../../ui/overview.md). + -Each [account](../../accounts/overview.md) is pre-configured with one default [material](../../materials/overview.md) and [workflow](../../workflows/overview.md). For the sake of this tutorial, we will keep the *default* parameters at each step. We will thus study silicon in the standard face-centered cubic structure and use [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md) as the [simulation engine](../../software-directory/overview.md). +The above task involves following steps: -## Prepare Material and Workflow + 1. Navigate to the [Workflows Bank]({{ reference_url }}/workflows/bank/) page by clicking + on the "Bank" option in the [left-hand sidebar]({{ interface_url }}/ui/left-sidebar/) + 2. Search with the text "curators" to filter workflows created by the + Mat3ra "Curators" account + 3. Sort workflows by name, and look for the "Band Structure + Density of + States" workflow for Quantum ESPRESSO and click on the "Copy" button to add it + to our account collection. If the copy button is not visible, please click on + the vertical dots in the Actions column to reveal hidden action items. -Users may also add new materials or workflows into their collection from the application-wise ["Bank" collection](../../entities-general/bank.md) that we maintain. To do so, select the "Bank" option in the [left-hand sidebar](../../ui/left-sidebar.md) of the user interface, and then "Materials" or "Workflows" as the user prefers. To import either workflows and material structures from the Bank, select the desired entry and then click "Copy" in the top-right taskbar of the page, as explained in more detail [here](../../entities-general/actions/copy-bank.md). +Now the workflow is added to the account collection, and can be found under the +Workflows tab. Click on the workflow name to open the workflow details page, +where further adjustments can be made to the workflow such as "Important +Settings" or modify the [input files]({{ interface_url }}/workflow-designer/unit-editor/input-templates/) for individual units. -Silicon FCC is the default material added to each account on creation. In the animation below we demonstrate how to import the "Band Structure" workflow for [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md) from the Bank. +![Edit unit](../../images/getting-started/run-first-simulation-edit-unit.webp "Subworkflow overview in the Workflow Explorer") - - -Readers can also learn how to [create](../../materials-designer/overview.md) or [upload](../../materials/actions/upload.md) / [import](../../materials/actions/import.md) materials with the aid of the incorporated Exabyte Materials Designer tool, as well as further setting them as [default](../../entities-general/actions/set-default.md) elsewhere in this documentation. - -## Open Job Designer -Start by clicking "Create Job" link in the [left-hand sidebar](../../ui/left-sidebar.md) to open the ["Job Designer" page](../../jobs-designer/overview.md), where the user can do the following actions via the relevant Tab for each. +## 3. Job Designer + +Once we have a material structure and workflow in hand, we can either use the +"Create Job" button in the [left-hand sidebar]({{ interface_url }}/ui/left-sidebar/) or +first navigate to the [Jobs Designer page]({{ interface_url }}/jobs-designer/overview/) and +then click on the "Create" job button. + +![Create job button](../../images/getting-started/run-first-simulation-create-job.webp "Create job") + +On the Job creation page, we can: + +- Click on the "Select Job Actions" dropdown menu, and select a [material]({{ interface_url }}/jobs-designer/materials-tab/) or multiple materials from user's + account collection (in this tutorial, we will use the default selection of + Silicon) +- Agiain, click on the "Select Job Actions" dropdown menu, click + "Select Workflow" and choose "Band Structure + Density of States" workflow + that we imported earlier +- Navigate among "Materials", "Workflow" and "Compute" tabs to review and adjust + various parameters if needed. + +![Materials viewer](../../images/getting-started/run-first-simulation-tab-1-materials.webp "Materials viewer") -- Choose a previously created [material](../../jobs-designer/materials-tab.md) -- Choose and adjust a simulation [Workflow](../../jobs-designer/workflow-tab.md) -- Setup [compute parameters](../../jobs-designer/compute-tab.md) - -## 1. Materials Tab -[Materials Tab](../../jobs-designer/materials-tab.md) lets the user choose one or more previously imported [materials](../../materials/overview.md) for use during the calculation. We will proceed with the default structure of Silicon. +### 3.1. Materials Tab -![Materials viewer](../../images/getting-started/run-first-simulation-tab-1-materials.png "Materials viewer") +[Materials Tab]({{ interface_url }}/jobs-designer/materials-tab/) lets the user choose one +or more previously imported [materials]({{ reference_url }}/materials/overview/) for use +in the calculation. We will proceed with the default structure of Silicon for +this demonstration. -## 2. Workflow Tab -Simulations usually have multiple steps that need to be executed in a certain order. This step sequence is called a ["Workflow"](../../workflows/overview.md). +### 3.2. Workflow Tab -Open the dropdown menu of the top-level page header (see animation below), click "Select Workflow" and select "Bandstructure" workflow with "espresso" as modeling engine, after [searching](../../entities-general/actions/search.md) for the corresponding keywords in the resulting "Select Workflow" dialog. We divide a workflow into ["Subworkflows"](../../workflows/components/subworkflows.md), such that each individual Subworkflow can only contain one [modeling engine](../../software/overview.md) and one [theoretical model](../../models/overview.md) (eg. [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md), or "espresso", and [density functional theory](../../models-directory/dft/overview.md) respectively). +Simulations usually have multiple steps that need to be executed in a certain +order. This sequence of steps are defined as a ["Workflow"]({{ reference_url }}/workflows/overview/). -The subworkflow ["Overview" tab](../../workflow-designer/subworkflow-editor/overview-tab.md) contains the basis information about it, including the individual computational building blocks - or ["Units"](../../workflows/components/units.md). Settings that we classify as most important are listed under ["Important Settings"](../../workflow-designer/subworkflow-editor/important-settings.md): [k-point grid](../../models/auxiliary-concepts/reciprocal-space/sampling.md) and [k-point path](../../models/auxiliary-concepts/reciprocal-space/paths.md) within the [reciprocal space](../../models/auxiliary-concepts/reciprocal-space.md) of the crystal are among them for the case of a "Band Structure" calculation considered here. +A workflow consists of one or multiple ["Subworkflows"]({{ reference_url }}/workflows/components/subworkflows/), as such each Subworkflow can only +contain one [modeling engine]({{ reference_url }}/software/overview/) and one +[theoretical model]({{ reference_url }}/models/overview/) (eg. [Quantum ESPRESSO]( +{{ reference_url }}/software-directory/modeling/quantum-espresso/overview/), or "espresso", +and [density functional theory]({{ reference_url }}/models-directory/dft/overview/) +respectively). Therefore, if a simulation involves multiple simulation engines +in the same workflow, e.g, Quantum ESPRESSO for DFT and LAMMPS for molecular +dynamics, then we must create multiple subworkflows. -One can further modify the input files for each individual part of the subworkflow by clicking on the corresponding unit, and [adjusting its input content](../../workflow-designer/unit-editor/input-templates.md) as the animation below demonstrates. +The subworkflow ["Overview" tab]({{ interface_url }}/workflow-designer/subworkflow-editor/overview-tab/) contains individual +computational building blocks or ["Units"]({{ reference_url }}/workflows/components/units/). +Various simulation parameters can be reviewed and adjusted under the +["Important Settings"]({{ interface_url }}/workflow-designer/subworkflow-editor/important-settings/), such as: +[k-point grid]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) and +[k-point path]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/paths/) +in the [reciprocal space]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/), +relevant for a "Band Structure" calculation. Finally, "Save and Exit" +the job designer. - -## 3. Compute Tab +![Workflow Tab](../../images/getting-started/run-first-simulation-tab-2-workflow.webp "Important Settings in Workflow Tab of Job Designer") -The ["Compute" tab](../../jobs-designer/compute-tab.md) lets the user set up the number of processor cores to be used for the computation, its maximum time limit and other relevant [compute parameters](../../infrastructure/compute/parameters.md). We set the maximum time limit for the calculation to properly schedule the allocation of resources. The format is HH:MM:SS, so that `01:00:00` corresponds to up to 1 hour runtime. -One can also choose to be notified of the job status by clicking on his/her name in the ["Notifications" section](../../infrastructure/compute/parameters.md#notifications). +### 3.3. Compute Tab -For the moment, let us leave all parameters at their default values and click "Save". +The ["Compute" tab]({{ interface_url }}/jobs-designer/compute-tab/) lets the user set +various compute parameters, such as cluster, queue, number of nodes and +number of processor cores per node to be used for the simulation, maximum time +limit and other relevant [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/). We set the maximum time limit for +the calculation to properly schedule the allocation of resources. The format is +HH:MM:SS, so that `01:00:00` corresponds to up to 1 hour runtime. One can also +choose to be notified of the job status by clicking on his/her name in the +["Notifications" section]({{ resources_url }}/infrastructure/compute/parameters/#notifications). -![Compute Tab](../../images/getting-started/run-first-simulation-tab-3-compute.png "Compute Tab") +![Compute Tab](../../images/getting-started/run-first-simulation-tab-3-compute.webp "Compute Tab") -!!! Note "Summary" - We have just finished creating our first job. We can now proceed to submit it. -## Run Calculation +## 4. Run Calculation -After saving the job, the user is redirected back to the default ["Project" page](../../jobs/ui/project-page.md). Here, the user can [submit the job](../../jobs/actions/run.md) and track its [status](../../jobs/status.md). +After saving the job, the user is redirected back to the default +["Project" page]({{ interface_url }}/jobs/ui/project-page/). Here, the user can +[submit the job]({{ interface_url }}/jobs/actions/run/) and track its [status]({{ reference_url }}/jobs/status/). -### Submit and Track Progress +### 4.1. Submit and Track Progress -The user can run the job by clicking the three vertical dots to the right of its status label ("pre-submission"), and choosing "Run", as explained in more detail [here](../../jobs/actions/run.md). +The user can run the job by clicking on the "Run" button in the Actions column, +or clicking on the three vertical dots and choosing ["Run"]({{ interface_url }}/jobs/actions/run/) action. -The [status](../../jobs/status.md) will change from "pre-submission" to "submitted". This means that the job is finally submitted to our [computing clusters](../../infrastructure/clusters/overview.md). Depending on the load, it may take some time for it to become "Active" and thus start executing. +The [status]({{ reference_url }}/jobs/status/) will change from "pre-submission" to +"submitted". This means that the job is finally submitted to our +[computing clusters]({{ resources_url }}/infrastructure/clusters/overview/). Depending on +the load, it may take some time for it to become "Active" and thus start +executing. -The user can click on the job name to monitor the progress of the job in real time within the [Job Viewer Interface](../../jobs/ui/viewer.md). +The user can click on the job name to monitor the progress of the job in real +time within the [Job Viewer Interface]({{ interface_url }}/jobs/ui/viewer/). - -### View Results and Access Files +### 4.2. View Results and Access Files -The [Job Viewer screen](../../jobs/ui/viewer.md) tracks the input parameters, output text, and convergence parameters involved in the computation (total energy in this tutorial). It also allows the user to [view the results](../../jobs/ui/results-tab.md) of the calculation, and to [download output files](../../jobs/ui/files-tab.md) when finished. +The [Job Viewer screen]({{ interface_url }}/jobs/ui/viewer/) tracks the input parameters, +output text, and convergence parameters involved in the computation (total +energy in this tutorial). Once the job is completed, user can navigate to the +[Results Tab]({{ interface_url }}/jobs/ui/results-tab/) to [view summary of results]({{ interface_url }}/jobs/ui/results-tab/), and preview or download [output files]({{ interface_url }}/jobs/ui/files-tab/) from the "Files" tab. - -## Done +## 5. Done -We have demonstrated in the present page how a simple electronic band structure calculation can be run using exabyte.io. For a more comprehensive tutorial, readers may refer to the dedicated ["Tutorials" section](../../tutorials/overview.md) of our documentation. +We have demonstrated in the present page how a simple electronic band structure +calculation can be run using Mat3ra web interface. For a more comprehensive +tutorials, readers may refer to the dedicated ["Tutorials" section]( +../../tutorials/overview.md) of our documentation. -![simple electronic band structure calculation](../../images/getting-started/run-first-simulation-view-bandstructure.png "simple electronic band structure calculation") +![simple electronic band structure calculation]( +../../images/getting-started/run-first-simulation-view-bandstructure.webp "simple electronic band structure calculation") diff --git a/lang/en/docs/getting-started/terminology.md b/lang/en/docs/getting-started/terminology.md deleted file mode 100644 index ad4003569..000000000 --- a/lang/en/docs/getting-started/terminology.md +++ /dev/null @@ -1,60 +0,0 @@ -# Terminology - -We summarize here the basic concepts that are used throughout Exabyte.io when referring to simulations. - -## Introduction - -Useful properties of materials can be obtained either via experiments, from a pure analytical standpoint, or via the application of computational techniques, otherwise referred to as **simulations**. This latter case is what we employ at exabyte.io. - -- **Simulation** is an application of a computational model or technique aimed at extracting a specific [property](../properties/overview.md) of [materials](../materials/overview.md). - -There are three main concepts that we deal with: - -- **Materials**: a combination of chemical elements in a particular geometric arrangement, that can be *uniquely* defined by a set of [descriptive properties](../properties/classification/overview.md) (eg. crystal lattice and basis), and has certain [characteristic properties](../properties/classification/overview.md) that can be computed upon it (eg. band gap, formation energy etc.). This includes both `periodic` (repeating units) and `non-periodic` (single unit) structures. - -- **Models**: a [theory](../models/overview.md) that provides scientific insight on how to calculate the characteristic properties of a material; it can be applied via multiple possible **Methods**, or [numerical implementations](../methods/overview.md) of the Model. In practice, methods are enacted on our platform via the creation of **[Workflow Computations](../workflows/overview.md)** to be applied on the material. - -!!!note "Example Model and Method" - **Density Functional Theory (DFT)** is an [example of a model](../models-directory/dft/overview.md), and its **plane-wave pseudopotential formulation** is an [example of method](../methods-directory/pseudopotential/overview.md). Detailed theoretical reviews of such concepts can be found in the references listed [herein](../models-directory/dft/references.md). - -- **Jobs**: an [entity](../jobs/overview.md) that contains information about the computation that makes the application of the Model (and subsequently Method) upon the material under investigation possible. - -More explanation follows for each of the above concepts. - -## Properties - -We introduce the classification schemes of material properties, such as structural, electronic and thermodynamic properties, [in this section of the documentation](../properties/classification/overview.md). - -## Model - -Within our platform, multiple component concepts comprised within a model are employed: - -- [Model](../models/overview.md) -- [Method](../methods/overview.md) -- [Workflow](../workflows/overview.md) -- [Subworkflow](../workflows/components/subworkflows.md) -- [Unit](../workflows/components/units.md) - -### Components - -In order to better understand the difference between Model, Method and Simulation, let us use a travel analogy: - -1. When you set out to travel from San Francisco to New York, you know your destination. Therefore, by analogy, a specific address in New York would be a **characteristic property** that you would like to reach (obtain). - -2. Then, you choose the way you would like to travel between a flight, a train ride, car ride or shipping. By analogy, after choosing the above-mentioned characteristic property of interest (the address), you choose the **model**. - -3. When you board a plane in the airport, or sit into a car, you henceforth choose a specific class of aircraft (jet, propeller, supersonic) or automobile (sedan, SUV, convertible). By analogy, after choosing a model, you would need to choose a specific computational implementation of the model, or the **method**. - -4. The plane could take multiple routes, and reach multiple intermediate destinations along the way. By analogy, a method can be realized through multiple **workflows** that contain specifically arranged **units**. - -Thus, the process of traveling from San Francisco to New York by analogy would be the **simulation** using a model, and a corresponding method contained within it, employed to extract a specific characteristic property. - -> A note on "Simulation Engines". Just like there are multiple airplane manufacturers, there are many **simulation engines** (or [software applications](../software/overview.md)) that implement specific model(s) and method(s). - -## Jobs - -A [simulation Job](../jobs/overview.md) is an [entity](../entities-general/overview.md) that represents the computation employed during the simulation, and the simplest entity that has [accounting](../accounts/overview.md) set up for. Jobs contain the information about the aforementioned Model/Method/Workflow/Units, and can be under any of the following possible [statuses](../jobs/status.md). - -### Projects - -Jobs are organized into [Projects](../jobs/projects.md) for convenience. One can think about projects as collections of jobs, in the same manner as a file system directory is a collection of files. diff --git a/lang/en/docs/getting-started/useful-links.md b/lang/en/docs/getting-started/useful-links.md deleted file mode 100644 index 6b388789d..000000000 --- a/lang/en/docs/getting-started/useful-links.md +++ /dev/null @@ -1,45 +0,0 @@ -# Useful Links - -Some useful information when getting started with the Exabyte.io platform. - - - -
    -
  1. Example tutorials: - -
    2. -
  2. Open-source repositories on Github: - -
    3. -
  3. Example programmatic usage through RESTful-API: - -
    4. -
  4. Example programmatic usage via Jupyter/command-line (CLI): - -
    5. -
  5. Other: -
      -
    1. Webinar Recording: Migrating to Exabyte.io (ie. upload existing input files, scripts)
      2. -
    2. Webinar Recording: Getting Started with Exabyte.io, the Basics
      3. -
    3. Our YouTube channel with Tutorial video voiceovers
      4. -
    4. Community Forum for discussion and Q&A
      5. -
    -
    6. -
- diff --git a/lang/en/docs/index-cli.md b/lang/en/docs/index-cli.md new file mode 100644 index 000000000..4958b3384 --- /dev/null +++ b/lang/en/docs/index-cli.md @@ -0,0 +1,36 @@ +# Command-Line Interface + +This site covers the command-line environment, batch job management, and remote connection methods for the Mat3ra platform. + +!!!tip "Other documentation sites" + For step-by-step tutorials, see the [Tutorials]({{ guide_url }}/). + For web interface documentation, see [User Interface]({{ interface_url }}/). + For explanations of underlying concepts, see [Concepts & Reference]({{ reference_url }}/). + For infrastructure and compute resources, see [Resources / Infrastructure]({{ resources_url }}/). + + +## CLI Environment + +The platform provides a Linux-based [command-line environment](cli/overview.md) with pre-installed simulation software, compilers, and libraries. The environment supports [modules](cli/modules.md) for managing software versions and [Python virtual environments](cli/actions/create-python-env.md) for custom packages. + +- [CLI overview](cli/overview.md) — shell environment, default tools +- [Environment modules](cli/modules.md) — load/unload software packages +- [CLI actions](cli/actions/overview.md) — common operations + + +## Batch Jobs + +Computational jobs are submitted through a [resource manager](jobs-cli/overview.md) using [batch scripts](jobs-cli/batch-scripts/overview.md). The batch system supports PBS/Slurm-style [directives](jobs-cli/batch-scripts/directives.md) for requesting compute resources. + +- [Jobs via CLI overview](jobs-cli/overview.md) — job submission and management +- [Batch script structure](jobs-cli/batch-scripts/general-structure.md) — script layout and conventions +- [Sample scripts](jobs-cli/batch-scripts/sample-scripts.md) — ready-to-use examples + + +## Remote Connection + +The platform supports multiple methods for [remote access](remote-connection/overview.md): [SSH](remote-connection/ssh.md), [Web Terminal](remote-connection/web-terminal.md), and [Remote Desktop](remote-connection/remote-desktop.md). + +- [Remote connection overview](remote-connection/overview.md) — connection methods +- [SSH terminal](remote-connection/ssh.md) — direct SSH access +- [Remote desktop](remote-connection/remote-desktop.md) — graphical environment diff --git a/lang/en/docs/index-concepts.md b/lang/en/docs/index-concepts.md new file mode 100644 index 000000000..0a1c1c3a3 --- /dev/null +++ b/lang/en/docs/index-concepts.md @@ -0,0 +1,83 @@ +# Concepts & Reference + +This site explains the concepts, data models, and scientific methods underlying the Mat3ra platform. It is organized around the platform's core abstractions — entities, models, methods, software, and properties. + +!!!tip "Other documentation sites" + For step-by-step tutorials, tool walkthroughs, CLI usage, and software reference, see the [Platform Guide]({{ guide_url }}/). + For interface walkthroughs and platform actions, see the [User Interface]({{ interface_url }}/). + For infrastructure and compute resources, see [Platform Resources]({{ resources_url }}/). + For REST API documentation, see the [Developers]({{ developers_url }}/) site. + For JSON schemas and data convention, see the [Data Standards]({{ data_url }}/). + + +## Core platform concepts + +The platform organizes work around a set of interconnected entities. Each entity has a defined lifecycle, ownership model, and data schema. + +- [Entities overview](entities-general/overview.md) — lifecycle, ownership, permissions, sets, and bank +- [Accounts](accounts/overview.md) — users, balance, quotas, service levels +- [Collaboration](collaboration/organizations/overview.md) — organizations, roles, teams, access levels + + +## Materials + +- [Overview](materials/overview.md) — what a material is, how it is classified and stored +- [Classification](materials/classification/crystalline.md) — crystalline vs. non-periodic + + +## Workflows + +- [Overview](workflows/overview.md) — structure, bank, defaults +- [Components](workflows/components/overview.md) — subworkflows, units, maps +- [Templating](workflows/templating/overview.md) — Jinja/Swig templates, Exabyte convention +- [Add-ons](workflows/addons/overview.md) — convergence algorithms, structural relaxation + + +## Jobs + +- [Overview](jobs/overview.md) — what a job is, status lifecycle +- [Projects](jobs/projects.md) — organizing jobs into projects + + +## Models & methods + +Physical models and computational methods used for simulations. + +- [Models overview](models/overview.md) — accuracy, data, parameters +- [DFT](models-directory/dft/overview.md) — Density Functional Theory parameters, accuracy, and notes +- [Machine Learning](models-directory/machine-learning/overview.md) — ML model parameters, units, and workflows +- [Methods overview](methods/overview.md) — precision, parameters +- [Pseudopotentials](methods-directory/pseudopotential/overview.md) — plane-wave settings and defaults + + +## Software + +Simulation engines and scripting environments available on the platform. + +- [Software overview](software/overview.md) — components, classification +- [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) +- [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) +- [LAMMPS]({{ reference_url }}/software-directory/modeling/lammps/), [CP2K]({{ reference_url }}/software-directory/modeling/cp2k/), [Gromacs]({{ reference_url }}/software-directory/modeling/gromacs/), [NWChem]({{ reference_url }}/software-directory/modeling/nwchem/) +- [Python]({{ reference_url }}/software-directory/scripting/python/overview/), [Shell]({{ reference_url }}/software-directory/scripting/shell/overview/), [Jupyter Lab]({{ reference_url }}/software-directory/scripting/jupyter-lab/overview/) +- [Python ML]({{ reference_url }}/software-directory/machine-learning/python-ml/overview/), [TensorFlow]({{ reference_url }}/software-directory/machine-learning/tensorflow/) + + +## Properties + +Computed and measured properties extracted from simulations. + +- [Properties overview](properties/overview.md) — lifecycle, extractors, refinement +- [Classification](properties/classification/overview.md) +- [Scalar properties](properties-directory/scalar/total-energy.md) — total energy, fermi energy, surface energy, and more +- [Non-scalar properties](properties-directory/non-scalar/bandstructure.md) — band structure, DOS, phonon dispersions +- [Structural properties](properties-directory/structural/basis.md) — basis, lattice, symmetry, forces + + + + +## Other + +- [Benchmarks](benchmarks/overview.md) — throughput screening, vendor comparisons, HPL +- [Security](security/overview.md) — policies, threat analysis +- [Site policy](site-policy/privacy-statement.md) — privacy, sharing, terms of service +- [Publications](other/publications.md) diff --git a/lang/en/docs/index-dev.md b/lang/en/docs/index-dev.md new file mode 100644 index 000000000..e7ca133fd --- /dev/null +++ b/lang/en/docs/index-dev.md @@ -0,0 +1,39 @@ +# Developer Guide + +This guide covers the technical infrastructure of the Mat3ra platform — REST API access, cluster hardware, and data storage internals. + +!!!tip "Other documentation sites" + For step-by-step tutorials, tool walkthroughs, CLI usage, and software reference, see the [Platform Guide]({{ guide_url }}/). + For explanations of underlying concepts, see [Concepts & Reference]({{ reference_url }}/). + + +## REST API + +Programmatic access to the Mat3ra platform. + +- [Overview](rest-api/overview.md) — capabilities and entry points +- [Authentication](rest-api/authentication.md) — API token setup +- [Query structure](rest-api/query-structure.md) — filters, pagination, projections +- [Endpoints](rest-api/endpoints.md) — available resources +- [API client library](rest-api/api-client.md) +- [API examples](rest-api/api-examples.md) — common usage patterns + + +## Infrastructure + +Cluster hardware, storage systems, and resource management. + +- [Overview](infrastructure/overview.md) — architecture at a glance +- [Storage system](infrastructure/storage.md) +- [Login node](infrastructure/login/overview.md) — directories, access +- **Clusters**: [overview](infrastructure/clusters/overview.md), [hardware](infrastructure/clusters/hardware.md), [Google](infrastructure/clusters/google.md), [AWS](infrastructure/clusters/aws.md), [Azure](infrastructure/clusters/azure.md) +- **Resource management**: [overview](infrastructure/resource/overview.md), [categories](infrastructure/resource/category.md), [queues](infrastructure/resource/queues.md) +- **Compute parameters**: [overview](infrastructure/compute/overview.md), [parameters](infrastructure/compute/parameters.md), [data](infrastructure/compute/data.md) + + +## Data storage + +How data is stored on disk and in object storage. + +- **Data on disk**: [overview](data-on-disk/overview.md), [directory structure](data-on-disk/directories.md), [quotas](data-on-disk/quotas.md), [security](data-on-disk/security.md) +- **Object storage**: [overview](data-in-objectstorage/overview.md), [files](data-in-objectstorage/files.md), [security](data-in-objectstorage/security.md), [dropbox](data-in-objectstorage/dropbox.md) diff --git a/lang/en/docs/index-developers.md b/lang/en/docs/index-developers.md new file mode 100644 index 000000000..257ffce33 --- /dev/null +++ b/lang/en/docs/index-developers.md @@ -0,0 +1,24 @@ +# Developers + +REST API reference and contribution guides for building on the Mat3ra platform. + +!!!tip "Other documentation sites" + For step-by-step tutorials and CLI guides, see the [Platform Guide]({{ guide_url }}/). + For platform infrastructure and compute resources, see [Platform Resources]({{ resources_url }}/). + For JSON schemas and data convention, see the [Data Standards]({{ data_url }}/). + + +## REST API + +Programmatic access to the Mat3ra platform. + +- [Overview](rest-api/overview.md) — capabilities and entry points +- [Authentication](rest-api/authentication.md) — API token setup +- [Query structure](rest-api/query-structure.md) — filters, pagination, projections +- [Endpoints](rest-api/endpoints.md) — available resources +- [API client library](rest-api/api-client.md) +- [API examples](rest-api/api-examples.md) — common usage patterns + +## Miscellaneous + +- [Contribute new applications]({{ guide_url }}/tutorials/contribute-new-application) — How to bring your own applications to the Mat3ra platform diff --git a/lang/en/docs/index-guide.md b/lang/en/docs/index-guide.md new file mode 100644 index 000000000..be5222ea2 --- /dev/null +++ b/lang/en/docs/index-guide.md @@ -0,0 +1,172 @@ +# Tutorials + +Step-by-step tutorials for materials construction, DFT, ML, and simulation workflows on the Mat3ra platform. Each tutorial can also be located through the sidebar navigation. + +!!!tip "Other documentation sites" + For interface walkthroughs and platform actions, see the [User Interface]({{ interface_url }}/). + For explanations of underlying concepts and software reference, see [Concepts & Reference]({{ reference_url }}/). + For infrastructure and compute resources, see [Resources / Infrastructure]({{ resources_url }}/). + For REST API documentation, see the [Developers]({{ developers_url }}/) site. + For CLI environment and batch jobs, see the [Command-Line Interface]({{ cli_url }}/) site. + To get started on the platform, see [Accessing the Platform](tutorials/platform-access.md) and [Restart from Previous Job](tutorials/other/restart-job.md). + + +## 1. Materials Design + +Designing and constructing [material structures]({{ reference_url }}/materials/overview/) for simulations. + +### 1.1. General + +| Topic | Description | Link | +|:------------------------|:---------------------------------------------------------|:-----| +| Import from files | Upload CIF, POSCAR, XYZ and other formats via JupyterLite notebook | [Link](tutorials/materials/import-from-files.md) | +| Combinatorial sets | Generate all unique elemental substitutions in a host structure | [Link](tutorials/materials/combinatorial-screening.md) | +| Interpolated sets | Create intermediate structures between two endpoints | [Link](tutorials/materials/interpolated-sets.md) | +| Molecule on a surface | Place a molecular adsorbate on a crystalline slab | [Link](tutorials/materials/molecule-surface.md) | +| Interface (3D Editor) | Build a slab interface with quick visual setup | [Link](tutorials/materials/slabs-interface.md) | +| Interface (JupyterLite) | Construct a minimal-strain interface via the ZSL algorithm | [Link](tutorials/materials/jupyterlite-zsl.md) | +| VESTA via Remote Desktop| Visualize structures in VESTA through a remote desktop session | [Link](tutorials/materials/vesta-remote-desktop.md) | + +### 1.2. Reproducing Published Structures + +Step-by-step recipes reproducing structures from the literature. The [full overview](tutorials/materials/specific/overview.md) page contains figures and additional context for each entry. + +| Structure Type | Material | Reference | Link | +|:--------------------------|:--------------------|:-------------------------|:-----| +| Substitutional defect | Graphene | Fujimoto et al. (2011) | [Link](tutorials/materials/specific/defect-point-substitution-graphene.md) | +| Substitutional defect (band structure) | Graphene | Fujimoto et al. (2011) | [Link](tutorials/materials/specific/defect-point-substitution-graphene-simulation.md) | +| Vacancy-substitution pair | GaN | Miceli et al. (2016) | [Link](tutorials/materials/specific/defect-point-pair-gallium-nitride.md) | +| Vacancy defect | h-BN | Bertoldo et al. (2022) | [Link](tutorials/materials/specific/defect-point-vacancy-boron-nitride.md) | +| Interstitial defect | SnO | Togo et al. (2006) | [Link](tutorials/materials/specific/defect-point-interstitial-tin-oxide.md) | +| Island surface defect | TiN | Sangiovanni et al. (2018)| [Link](tutorials/materials/specific/defect-surface-island-titanium-nitride.md) | +| Step surface defect | Pt(111) | Šljivančanin et al. (2002)| [Link](tutorials/materials/specific/defect-surface-step-platinum.md) | +| Adatom surface defects | Graphene | Chan et al. (2008) | [Link](tutorials/materials/specific/defect-surface-adatom-graphene.md) | +| Twisted bilayer | h-BN nanoribbons | Xian et al. (2019) | [Link](tutorials/materials/specific/interface-bilayer-twisted-nanoribbons-boron-nitride.md) | +| Twisted bilayer | MoS2 | Liu et al. (2014) | [Link](tutorials/materials/specific/interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide.md) | +| Twisted bilayer (band structure) | MoS2 | Liu et al. (2014) | [Link](tutorials/materials/specific/interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide-simulation.md) | +| 2D–2D interface | Graphene / h-BN | Jung et al. (2015) | [Link](tutorials/materials/specific/interface-2d-2d-graphene-boron-nitride.md) | +| 3D–3D interface | Cu / SiO2 | Shan et al. (2011) | [Link](tutorials/materials/specific/interface-3d-3d-copper-silicon-dioxide.md) | +| 2D–3D interface | Graphene / SiO2 | Kang et al. (2008) | [Link](tutorials/materials/specific/interface-2d-3d-graphene-silicon-dioxide.md) | +| Interface optimization | Graphene / Ni(111) | Dahal et al. (2014) | [Link](tutorials/materials/specific/optimization-interface-film-xy-position-graphene-nickel.md) | +| Adatom island | Pt on MoS2 | Saidi et al. (2015) | [Link](tutorials/materials/specific/defect-point-adatom-island-molybdenum-disulfide-platinum.md) | +| H-passivated nanowire | Si | Aradi et al. (2007) | [Link](tutorials/materials/specific/passivation-edge-nanowire-silicon.md) | +| H-passivated surface | Si(100) | Hansen et al. (1998) | [Link](tutorials/materials/specific/passivation-surface-silicon.md) | +| Nanoclusters | Au | Larsen et al. (2011) | [Link](tutorials/materials/specific/nanocluster-gold.md) | +| Slab | SrTiO3 | Eglitis et al. (2008) | [Link](tutorials/materials/specific/slab-strontium-titanate.md) | +| High-k metal gate stack | Si/SiO2/HfO2/TiN | Muller et al. (1999) | [Link](tutorials/materials/specific/heterostructure-silicon-silicon-dioxide-hafnium-dioxide-titanium-nitride.md) | +| Ripple perturbation | Graphene | Thompson-Flagg et al. (2009) | [Link](tutorials/materials/specific/perturbation-ripples-graphene.md) | +| Grain boundary (3D) | Cu (FCC) | Frolov et al. (2013) | [Link](tutorials/materials/specific/defect-planar-grain-boundary-3d-fcc-metals-copper.md) | +| Grain boundary (2D) | h-BN | Li et al. (2015) | [Link](tutorials/materials/specific/defect-planar-grain-boundary-2d-boron-nitride.md) | + +[^1]: Fujimoto et al., Phys. Rev. B 84, 245446 (2011). [DOI](https://doi.org/10.1103/PhysRevB.84.245446){:target='_blank'} +[^2]: Miceli et al., Phys. Rev. B 93, 165207 (2016). [DOI](https://doi.org/10.1103/PhysRevB.93.165207){:target='_blank'} +[^3]: Bertoldo et al., npj Comput. Mater. 8, 72 (2022). [DOI](https://doi.org/10.1038/s41524-022-00730-w){:target='_blank'} +[^4]: Togo et al., Phys. Rev. B 74, 195128 (2006). [DOI](https://doi.org/10.1103/PhysRevB.74.195128){:target='_blank'} +[^5]: Sangiovanni et al., Phys. Rev. B 97, 035406 (2018). [DOI](https://doi.org/10.1103/PhysRevB.97.035406){:target='_blank'} +[^6]: Šljivančanin et al., Surf. Sci. 515, 235 (2002). [DOI](https://doi.org/10.1016/s0039-6028(02)01908-8){:target='_blank'} +[^7]: Chan et al., Phys. Rev. B 77, 235430 (2008). [DOI](https://doi.org/10.1103/PhysRevB.77.235430){:target='_blank'} +[^8]: Xian et al., Nano Lett. 19, 4934 (2019). [DOI](https://doi.org/10.1021/acs.nanolett.9b00986){:target='_blank'} +[^9]: Liu et al., Nat. Commun. 5, 4966 (2014). [DOI](https://doi.org/10.1038/ncomms5966){:target='_blank'} +[^10]: Jung et al., Nat. Commun. 6, 6308 (2015). [DOI](https://doi.org/10.1038/ncomms7308){:target='_blank'} +[^11]: Shan et al., Phys. Rev. B 83, 115327 (2011). [DOI](https://doi.org/10.1103/PhysRevB.83.115327){:target='_blank'} +[^12]: Kang et al., Phys. Rev. B 78, 115404 (2008). [DOI](https://doi.org/10.1103/PhysRevB.78.115404){:target='_blank'} +[^13]: Dahal et al., Nanoscale 6, 2548 (2014). [DOI](https://doi.org/10.1039/c3nr05279f){:target='_blank'} +[^14]: Saidi et al., Cryst. Growth Des. 15, 642 (2015). [DOI](https://doi.org/10.1021/cg5013395){:target='_blank'} +[^15]: Aradi et al., Phys. Rev. B 76, 035305 (2007). [DOI](https://doi.org/10.1103/PhysRevB.76.035305){:target='_blank'} +[^16]: Hansen et al., Phys. Rev. B 57, 13295 (1998). [DOI](https://doi.org/10.1103/PhysRevB.57.13295){:target='_blank'} +[^17]: Larsen et al., Phys. Rev. B 84, 245429 (2011). [DOI](https://doi.org/10.1103/PhysRevB.84.245429){:target='_blank'} +[^18]: Eglitis et al., Phys. Rev. B 77, 195408 (2008). [DOI](https://doi.org/10.1103/PhysRevB.77.195408){:target='_blank'} +[^19]: Muller et al., Nature 399, 758 (1999). [Reference](https://docs.quantumatk.com/tutorials/hkmg_builder/hkmg_builder.html){:target='_blank'} +[^20]: Thompson-Flagg et al., EPL 85, 46002 (2009). [DOI](https://doi.org/10.1209/0295-5075/85/46002){:target='_blank'} +[^21]: Frolov et al., Nat. Commun. 4, 1899 (2013). [DOI](https://doi.org/10.1038/ncomms2919){:target='_blank'} +[^22]: Li et al., Nano Lett. 15, 6004 (2015). [DOI](https://doi.org/10.1021/acs.nanolett.5b01852){:target='_blank'} + + + +## 2. Simulations + +### 2.1. Density Functional Theory + +[Density Functional Theory]({{ reference_url }}/models-directory/density-functional-theory/overview/) property calculations with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) and [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/). + +| Category | Property | Method / Functional | Software | Link | +|:--------------|:----------------------------|:----------------------|:---------|:-----| +| Electronic | Band structure | DFT (standard) | QE | [Link](tutorials/dft/electronic/band-structure.md) | +| Electronic | Band structure | HSE | QE | [Link](tutorials/dft/electronic/hse-qe-bs.md) | +| Electronic | Band structure | HSE | VASP | [Link](tutorials/dft/electronic/hse-vasp-bg.md) | +| Electronic | Band structure | GW (Full Freq.) | QE | [Link](tutorials/dft/electronic/gw-qe-bs-fullfreq.md) | +| Electronic | Band structure | GW (Plasmon Pole) | QE | [Link](tutorials/dft/electronic/gw-qe-bs-plasmon.md) | +| Electronic | Band gap | DFT (standard) | QE | [Link](tutorials/dft/electronic/band-gap.md) | +| Electronic | Band gap | HSE | QE | [Link](tutorials/dft/electronic/hse-qe-bg.md) | +| Electronic | Band gap | GW | VASP | [Link](tutorials/dft/electronic/gw-vasp-bg.md) | +| Electronic | Density of states | DFT | QE | [Link](tutorials/dft/electronic/density-of-states.md) | +| Electronic | Density mesh | DFT | QE | [Link](tutorials/dft/electronic/electronic-density-mesh.md) | +| Electronic | Fermi surface | DFT | QE | [Link](tutorials/dft/electronic/fermi-surface.md) | +| Electronic | Valence band offset | DFT | QE | [Link](tutorials/dft/electronic/valence-band-offset.md) | +| Electronic | Effective screening medium | ESM | QE | [Link](tutorials/dft/electronic/esm-qe.md) | +| Electronic | Hubbard U correction | DFT+U | QE | [Link](tutorials/dft/electronic/hubbard.md) | +| Electronic | Magnetic properties | Spin-polarized | QE | [Link](tutorials/dft/electronic/spin-magnetic-qe.md) | +| Electronic | Spin-orbit coupling | SOC | QE | [Link](tutorials/dft/electronic/spin-orbit-coupling-qe.md) | +| Optical | Dielectric constant | DFT | QE | [Link](tutorials/dft/optical/epsilon-optimal-basis.md) | +| Vibrational | Zero point energy | DFPT | QE | [Link](tutorials/dft/vibrational/zero-point-energy.md) | +| Vibrational | Phonon dispersion / DOS | DFPT | QE | [Link](tutorials/dft/vibrational/phonon-dispersion-dos.md) | +| Vibrational | Phonons on a grid | DFPT | QE | [Link](tutorials/dft/vibrational/phonons-grid.md) | +| Thermodynamic | Surface energy | DFT | QE | [Link](tutorials/dft/thermodynamic/surface-energy.md) | +| Chemical | Reaction energy profile | NEB | QE | [Link](tutorials/dft/chemical/reaction-profile-qe.md) | +| Chemical | Reaction energy profile | NEB | VASP | [Link](tutorials/dft/chemical/reaction-profile-vasp.md) | +| Workflow | k-point convergence | — | QE | [Link](tutorials/dft/addons/kpt-convergence.md) | +| Workflow | Structural relaxation | — | QE | [Link](tutorials/dft/addons/structural-relaxation.md) | + + + +### 2.2. Machine Learning + +[Machine Learning]({{ reference_url }}/models-directory/machine-learning/overview/) force fields and predictive models. + +| Topic | Description | Link | +|:-------------------------|:----------------------------------------------------------|:-----| +| Train a NN potential | End-to-end workflow: QE CP → DeePMD training → LAMMPS MD | [Link](tutorials/ml/deepmd-mlff-with-espresso-cp-and-lammps.md) | +| Python MLFF (MatterSim) | Run MatterSim force field on a GPU node via Python workflow | [Link](tutorials/ml/run-mlff-python-workflows-mattersim.md) | + + +## 3. Other + +### 3.1. Command-Line Jobs + +Submitting and managing jobs through the [CLI]({{ cli_url }}/jobs-cli/overview/). + +| Topic | Description | Link | +|:----------------------------|:-----------------------------------------------------|:-----| +| Create + run a CLI Job | Submit a job from the command line and monitor output | [Link](tutorials/jobs-cli/job-cli-example.md) | +| Import a CLI Job | Register a CLI-submitted job in the web interface | [Link](tutorials/jobs-cli/cli-job-import.md) | +| QE GPU Job | Run Quantum ESPRESSO on GPU-accelerated compute nodes | [Link](tutorials/jobs-cli/qe-gpu.md) | + +### 3.2. Templating + +Customizing simulation input files with the [template engine]({{ reference_url }}/workflows/templating/overview/). + +| Topic | Description | Link | +|:-------------------------------|:-----------------------------------------------------|:-----| +| Flags by elemental composition | Set boolean flags based on the elements present | [Link](tutorials/templating/set-flag-by-composition.md) | +| Magnetic moment by specie | Assign initial magnetic moments per atomic species | [Link](tutorials/templating/set-magnetic-moment.md) | + +### 3.3. Tools and Environments + +Platform access, notebook environments, and software management. + +| Topic | Description | Link | +|:-------------------|:---------------------------------------------------------|:-----| +| Accessing the platform | Set up an account and access the Mat3ra platform | [Link](tutorials/platform-access.md) | +| Jupyter Notebook | Launch and use a Jupyter notebook on the platform | [Link](tutorials/other/jupyter.md) | +| Restart from previous job | Resume a calculation from the output of a prior job | [Link](tutorials/other/restart-job.md) | +| TensorFlow (GPU) | Run TensorFlow workloads on GPU-enabled compute nodes | [Link](tutorials/general-functionality/tensorflow-gpu.md) | +| Add new software | Install custom packages via the CLI environment | [Link]({{ cli_url }}/cli/actions/add-software/) | +| Contribute new applications | Contribute new applications to the Mat3ra platform | [Link](tutorials/contribute-new-application.md) | + + + diff --git a/lang/en/docs/index-interface.md b/lang/en/docs/index-interface.md new file mode 100644 index 000000000..07a98086e --- /dev/null +++ b/lang/en/docs/index-interface.md @@ -0,0 +1,55 @@ +# User Interface + +Reference documentation for the Mat3ra platform interface: components, entity management, designer tools, and common actions. + +!!!tip "Other documentation sites" + For step-by-step tutorials and how-to guides, see the [Tutorials]({{ guide_url }}/). + For CLI environment and remote connection, see the [Command-Line Interface]({{ cli_url }}/). + For explanations of underlying concepts, see [Concepts & Reference]({{ reference_url }}/). + For infrastructure and compute resources, see [Resources / Infrastructure]({{ resources_url }}/). + For REST API documentation, see the [Developers]({{ developers_url }}/) site. + + +## Interface components + +Common interface elements shared across the platform. + +- [Overview](ui/overview.md) — general layout and navigation +- [Header and footer](ui/header-footer.md), [left-hand sidebar](ui/left-sidebar.md), [account menu](ui/account-menu.md) +- [Dashboard](ui/specific/dashboard.md), [tabs navigation](ui/specific/tabs-navigator.md) + + +## Entity management + +Interface and actions for each entity type. + +- **Materials**: [explorer](materials/ui/explorer.md), [viewer](materials/ui/viewer.md), [actions](materials/actions/overview.md) +- **Workflows**: [explorer](workflows/ui/explorer.md), [viewer](workflows/ui/viewer.md), [actions](workflows/actions/overview.md) +- **Jobs**: [explorer](jobs/ui/explorer.md), [viewer](jobs/ui/viewer.md), [actions](jobs/actions/overview.md) +- **Common actions**: [search](entities-general/actions/search.md), [clone](entities-general/actions/clone.md), [metadata](entities-general/actions/metadata.md), and [more](entities-general/actions/overview.md) + + +## Designer tools + +Detailed walkthroughs for each major platform tool. + +- [Materials Designer](materials-designer/overview.md) — create and edit crystal structures +- [Workflow Designer](workflow-designer/overview.md) — build and configure simulation workflows +- [Jobs Designer](jobs-designer/overview.md) — set up and submit computational jobs + + +## JupyterLite + +In-browser notebook environment for data analysis and materials construction. + +- [JupyterLite overview](jupyterlite/overview.md) — capabilities and architecture +- [Data exchange](jupyterlite/data-exchange.md) — moving data in and out of notebooks +- [Common actions](jupyterlite/common-actions.md) + + +## Account management + +- [Account preferences and settings](accounts/ui/overview.md) +- [Accounting actions (balance, quota, payments)](accounts/accounting/overview.md) +- [Organizations and teams](collaboration/actions/organization/overview.md) +- [Entity sharing](collaboration/sharing/actions.md) diff --git a/lang/en/docs/index-resources.md b/lang/en/docs/index-resources.md new file mode 100644 index 000000000..bb4e37b5d --- /dev/null +++ b/lang/en/docs/index-resources.md @@ -0,0 +1,28 @@ +# Platform Resources + +Compute clusters, storage systems, and resource management for the Mat3ra platform. + +!!!tip "Other documentation sites" + For step-by-step tutorials and CLI guides, see the [Platform Guide]({{ guide_url }}/). + For explanations of underlying concepts, see [Concepts & Reference]({{ reference_url }}/). + For REST API documentation, see the [Developers]({{ developers_url }}/) site. + + +## Infrastructure + +Hardware, clusters, and resource management. + +- [Overview](infrastructure/overview.md) — architecture at a glance +- [Storage system](infrastructure/storage.md) +- [Login node](infrastructure/login/overview.md) — directories, access +- **Clusters**: [overview](infrastructure/clusters/overview.md), [hardware](infrastructure/clusters/hardware.md), [Google](infrastructure/clusters/google.md), [AWS](infrastructure/clusters/aws.md), [Azure](infrastructure/clusters/azure.md) +- **Resource management**: [overview](infrastructure/resource/overview.md), [categories](infrastructure/resource/category.md), [queues](infrastructure/resource/queues.md) +- **Compute parameters**: [overview](infrastructure/compute/overview.md), [parameters](infrastructure/compute/parameters.md), [data](infrastructure/compute/data.md) + + +## Data storage + +How data is stored on disk and in object storage. + +- **Data on disk**: [overview](data-on-disk/overview.md), [directory structure](data-on-disk/directories.md), [quotas](data-on-disk/quotas.md), [security](data-on-disk/security.md) +- **Object storage**: [overview](data-in-objectstorage/overview.md), [files](data-in-objectstorage/files.md), [security](data-in-objectstorage/security.md), [dropbox](data-in-objectstorage/dropbox.md) diff --git a/lang/en/docs/index-standards.md b/lang/en/docs/index-standards.md new file mode 100644 index 000000000..5ed0c4ebc --- /dev/null +++ b/lang/en/docs/index-standards.md @@ -0,0 +1,50 @@ +# Data Standards + +This section documents the data convention, JSON schemas, and structured data representations used across the Mat3ra platform. + +!!!tip "Other documentation sites" + For step-by-step tutorials and platform walkthroughs, see the [Platform Guide]({{ guide_url }}/). + For explanations of underlying concepts, see [Concepts & Reference]({{ reference_url }}/). + For REST API documentation, see the [Developers]({{ developers_url }}/) site. + + +## Overview & Convention + +The [ESSE Data Convention](data-structured/convention.md) defines how structured data is organized and stored in JSON format across the platform. + +- [Structured Data](data-structured/overview.md) — introduction to structured data storage +- [Convention](data-structured/convention.md) — JSON format, schemas, and examples +- [Data Classification](data/classification.md) — how data is categorized +- [Data Lifecycle](data/lifecycle.md) — stages of data from creation to archival + + +## Entity Schemas + +JSON schemas and examples for each platform entity type. + +- [General Entity](entities-general/data.md) — common fields shared by all entities +- [Materials](materials/data.md) — crystal structure representations +- [Jobs](jobs/data.md) — computational job data +- [Workflows](workflows/data/overview.md) — workflow, subworkflow, and unit schemas +- [Models](models/data.md) — model parameter schemas +- [Methods](methods/data.md) — method schemas +- [Software](software/data.md) — application, executable, and flavor schemas + + +## Property Schemas + +Schemas for material and simulation properties. + +- [Overview](properties/data/overview.md) — property data structure +- [Core Types](properties/data/core.md) — primitive and abstract schema types +- [Full List](properties/data/list.md) — all property schemas with examples +- [Periodic Table](properties/data/periodic-table.md) — element-level property data + + +## Entity Directories + +Detailed schemas for specific model, method, and software implementations. + +- **Models**: [DFT](models-directory/dft/data.md), [Machine Learning](models-directory/machine-learning/data.md) +- **Methods**: [Pseudopotential](methods-directory/pseudopotential/data.md), [Linear Regression](methods-directory/linear-regression/data.md) +- **Software**: [VASP](software-directory/modeling/vasp/data.md), [Quantum ESPRESSO](software-directory/modeling/quantum-espresso/data.md), [Python](software-directory/scripting/python/data.md), [Shell](software-directory/scripting/shell/data.md), [JupyterLab](software-directory/scripting/jupyter-lab/data.md) diff --git a/lang/en/docs/index.md b/lang/en/docs/index.md index a3855224f..151c373be 100644 --- a/lang/en/docs/index.md +++ b/lang/en/docs/index.md @@ -1,42 +1,71 @@ -# Mat3ra Documentation +# Documentation -[**Mat3ra**](https://platform.mat3ra.com) is a cloud-native accessible and collaborative platform for materials modeling from the atomic scale. Our platform makes it easier for scientists, engineers, and researchers to **design new materials** and **predict their properties** using *first-principles* approaches and *AI/ML* techniques. +Mat3ra.com is an online platform for digital materials R&D. This documentation explains the main concepts and how to use the platform. -First-principles approach does not require any knowledge of experimental observations, instead solely takes into account the atomistic description of material (e.g., constituent atoms, crystal structure, lattice constant, etc.) to compute desired properties thanks to [Density Functional Theory](https://en.wikipedia.org/wiki/Density_functional_theory){:target='_blank'} and its numerical implementations. When enough data is present, the AI/ML techniques can be applied to discover trends and accelerate predictions. Our platform also helps users collaborate, share and gather obtained knowledge with others. -The present documentation explains how the platform works in detail. +## Browse by Section +
-## Quick start + +Getting Started +New to the platform? Start here for a quick onboarding walkthrough, key concepts, and useful links. + -You can skip straight to our tutorial summarizing [first steps](getting-started/run-first-simulation/web-interface.md). There you will learn how to set up and run [density functional theory](models-directory/dft/overview.md) calculation to obtain [electronic band structure](properties-directory/non-scalar/bandstructure.md) of silicon, a semiconducting material widely used in making electronic chips. + +Tutorials +Step-by-step tutorials for DFT, ML, materials construction, and simulation workflows. + + +User Interface +Interface components, entity management, designer tools, and platform actions reference. + -## Searching + +Command Line +CLI environment, batch jobs, and remote connection methods. + -If you are looking for a specific topic of interest, please use the search box on top to quickly locate relevant pages. + +Concepts & Reference +In-depth explanations of models, methods, properties, software directory, and the science behind the platform. + -The [Links](#links) section below lists resources containing more in-depth explanations about what we are building and why[^1] and example case studies[^2]. + +Resources / Infrastructure +Compute clusters, storage systems, queues, quotas, and resource management. + + +Software Developers +REST API reference, authentication, endpoints, and contribution guides. + -## Contents + +Data Standards +JSON schemas, ESSE data convention, and structured data representations. + -The navigation bar on the left serves as the table of contents for the whole documentation while the table of contents on the right lists content headers under the current page. You may click on any top-level items on the left sidebar to expand the corresponding section. The [content highlights page](getting-started/content-highlights.md) has a brief overview of various features available in Mat3ra platform and links to them. +
+## Quick Links -## Support - -We reply to support requests within 24 hours. Our team can be contacted during working hours Pacific Time through: +- **[Getting Started](getting-started/first-steps.md)** — content highlights, key concepts, terminology +- **[Running First Simulations (Web)](getting-started/run-first-simulation/web-interface.md)** — new-user onboarding via the web interface +- **[Running First Simulations (CLI)](getting-started/run-first-simulation/cli-job.md)** — new-user onboarding via the command line +- **[Pricing](pricing/service-levels.md)** — service levels and storage plans +- **[FAQ](other/faq.md)** — frequently asked questions +- **[Supported Software](software-directory/overview.md)** — Quantum ESPRESSO, VASP, LAMMPS, CP2K, Python, and more +- **[Properties Directory](properties-directory/overview.md)** — band structure, band gaps, phonons, surface energy, and more +- **[REST API](rest-api/overview.md)** — programmatic access to the platform +- **[Community Programs](other/community-programs.md)** — academic and research partnerships -- Email: support@mat3ra.com -- Phone: +1 (510) 473-7770 -- Via web widget: click **Support** button at the bottom of our web application. - -!!! tip "Let us hear your feedback" - In case you find that something is missing or if you still have questions after reading this documentation, please contact us. +## Support -## Links +See [Help & Support](other/support.md) for ways to get assistance. -[^1]: [What is materials discovery cloud, article](https://www.linkedin.com/pulse/how-we-design-world-tomorrow-what-materials-discovery-timur-bazhirov) -[^2]: [Mat3ra: case studies](https://mat3ra.com/case-studies) +!!! tip "Help improve the documentation" + If something is missing or unclear, please open the [Help & Support]( + other/support.md) page and get in touch. diff --git a/lang/en/docs/infrastructure/clusters/aws.md b/lang/en/docs/infrastructure/clusters/aws.md index 0ce6e8ee4..6ef0410fe 100644 --- a/lang/en/docs/infrastructure/clusters/aws.md +++ b/lang/en/docs/infrastructure/clusters/aws.md @@ -4,37 +4,32 @@ This page contains information about clusters hosted on Amazon Web Services[^1] ## Clusters -The following table provides information about available clusters on Amazon Web Services (AWS) cloud computing platform. The latest cluster status can be found on Clusters page in web application. +The following table provides information about available clusters on Amazon Web Services (AWS) cloud computing platform. +The latest cluster status can be found on Clusters +page in web application. -| Name | Master Hostname | Location | -| :---: | :---: | :---: | -| cluster-001 | master-production-20160630-cluster-001.exabyte.io | West US | +| Name | Master Hostname | Location | +|:-------------:|:---------------------------------------------------:|:--------:| +| `cluster-002` | `master-production-20250821-cluster-001.mat3ra.com` | West US | ## Queues -The list of currently enabled queues is given below. Price per core hour is shown in relation to the [relative unit price](../../pricing/service-levels.md#comparison-table) and is subject to change at any time. Total number of nodes can be increased upon [request](../../ui/support.md). - -| Name | Category[^2] | Mode[^3] | Charge Policy[^4] | Price | Max Nodes per Job+ | Max Nodes Total | -| :---: | :---: | :---: | :---: | :---: | :---: | :---: | -| D | debug | debug | core-seconds | 2.251 | 1 | 10 | -| OR | ordinary | regular | core-seconds | 1.000 | 1 | 10 | -| OR4 | ordinary | regular | core-seconds | 1.126 | 1 | 20 | -| OR8 | ordinary | regular | core-seconds | 1.126 | 1 | 20 | -| OR16 | ordinary | regular | core-seconds | 1.126 | 1 | 20 | -| OF | ordinary | fast | core-hours | 1.000 | ≤5 | 100 | -| OFplus| ordinary | fast | core-hours | 0.962 | ≤5 | 10 | -| SR | saving | regular | core-seconds | 0.200 | 1 | 10 | -| SR4 | saving | regular | core-seconds | 0.225 | 1 | 20 | -| SR8 | saving | regular | core-seconds | 0.225 | 1 | 20 | -| SR16 | saving | regular | core-seconds | 0.225 | 1 | 20 | -| SF | saving | fast | core-hours | 0.200 | ≤5 | 100 | -| SFplus| saving | fast | core-hours | 0.379 | ≤5 | 10 | -| GOF | ordinary | fast | core-hours | 8.655 | ≤5 | 10 | -| G4OF | ordinary | fast | core-hours | 8.655 | ≤5 | 10 | -| G8OF | ordinary | fast | core-hours | 8.655 | ≤5 | 10 | -| GSF | saving | fast | core-hours | 3.370 | ≤5 | 10 | -| G4SF | saving | fast | core-hours | 4.158 | ≤5 | 10 | -| G8SF | saving | fast | core-hours | 4.335 | ≤5 | 10 | +The list of currently enabled queues is given below. Price per core hour is shown in relation to +the [relative unit price]({{ guide_url }}/pricing/service-levels/#comparison-table) and is subject to change at any time. Total +number of nodes can be increased upon [request]({{ interface_url }}/ui/support/). + +| Name | Category[^2] | Mode[^3] | Charge Policy[^4] | Price | Max Nodes per Job+ | Max Nodes Total | +|:------:|:------------:|:--------:|:-----------------:|:-----:|:-----------------------------:|:---------------:| +| D | debug | debug | core-seconds | 2.251 | 1 | 10 | +| OR | ordinary | regular | core-seconds | 1.000 | 1 | 10 | +| OF | ordinary | fast | core-hours | 1.000 | 10 | 100 | +| OFplus | ordinary | fast | core-hours | 0.962 | 5 | 10 | +| SR | saving | regular | core-seconds | 0.200 | 1 | 10 | +| SF | saving | fast | core-hours | 0.200 | 10 | 100 | +| SFplus | saving | fast | core-hours | 0.379 | 5 | 10 | +| GOF | ordinary | fast | core-hours | 8.655 | 5 | 10 | +| GSF | saving | fast | core-hours | 1.731 | 5 | 10 | +| G4OF | ordinary | fast | core-hours | 8.655 | 5 | 10 | + please contact support to inquire about attempting a larger node count per job @@ -42,31 +37,22 @@ The list of currently enabled queues is given below. Price per core hour is show The following table contains hardware specifications for the above queues. -| Name | CPU[^5] | Cores per Node | GPU[^6] | GPU per Node | Memory (GB) | Bandwidth (Gbps) | -| :---: | :---: | :---: | :---: | :---: | :---: | :---: | -| D | c-3 | 8 | - | - | 15 | ≤10 | -| OR | c-3 | 36 | - | - | 60 | ≤10 | -| OR4 | c-3 | 4 | - | - | 7.5 | ≤10 | -| OR8 | c-3 | 8 | - | - | 15 | ≤10 | -| OR16 | c-3 | 16 | - | - | 30 | ≤10 | -| OF | c-3 | 36 | - | - | 60 | 10 | -| OFplus| c-5 | 72 | - | - | 144 | 25 | -| SR | c-3 | 36 | - | - | 60 | 10 | -| SR4 | c-3 | 4 | - | - | 7.5 | ≤10 | -| SR8 | c-3 | 8 | - | - | 15 | ≤10 | -| SR16 | c-3 | 16 | - | - | 30 | ≤10 | -| SF | c-3 | 36 | - | - | 60 | 10 | -| SFplus| c-5 | 72 | - | - | 144 | 25 | -| GOF | c-4 | 8 | g-1 | 1 | 61 | 10 | -| G4OF | c-4 | 32 | g-1 | 4 | 244 | 10 | -| G8OF | c-4 | 64 | g-1 | 8 | 488 | 25 | -| GSF | c-4 | 8 | g-1 | 1 | 61 | 10 | -| G4SF | c-4 | 32 | g-1 | 4 | 244 | 10 | -| G8SF | c-4 | 64 | g-1 | 8 | 488 | 25 | - +| Name | CPU[^5] | Cores per Node | GPU[^6] | GPU per Node | Memory (GB) | Bandwidth (Gbps) | Instance Type | +|:------:|:-------:|:--------------:|:-------:|:------------:|:-----------:|:----------------:|:-------------------:| +| D | c-3 | 4 | - | - | 15 | ≤10 | c4.2xlarge | +| OR | c-3 | 36 | - | - | 60 | ≤10 | c4.8xlarge | +| OF | c-3 | 36 | - | - | 60 | 10 | c4.8xlarge | +| OFplus | c-5 | 72 | - | - | 192 | 100 | c5n.18xlarge | +| SR | c-3 | 36 | - | - | 60 | 10 | c4.8xlarge | +| SF | c-3 | 36 | - | - | 60 | 10 | c4.8xlarge | +| SFplus | c-5 | 72 | - | - | 192 | 100 | c5n.18xlarge | +| GOF | c-8 | 8 | g-3 | 8 | 1152 | 400 | p4d.24xlarge | +| GSF | c-8 | 8 | g-3 | 8 | 1152 | 400 | p4d.24xlarge | +| G4OF | c-4 | 32 | g-4 | 1 | 256 | 10 | p5.4xlarge | !!! note "Hyper-threading" - Hyper-threading[^7] is enabled on all AWS compute nodes by default. It is recommended to use half of available cores on each compute node (e.g 18 cores on OF queue) if the application does not benefit from the extra virtual cores. +Hyper-threading[^7] is enabled on all AWS compute nodes by default. It is recommended to use half of available cores on +each compute node (e.g. 18 cores on OF queue) if the application does not benefit from the extra virtual cores. ## Links diff --git a/lang/en/docs/infrastructure/clusters/azure.md b/lang/en/docs/infrastructure/clusters/azure.md index a6ef99162..f540ef87c 100644 --- a/lang/en/docs/infrastructure/clusters/azure.md +++ b/lang/en/docs/infrastructure/clusters/azure.md @@ -4,70 +4,59 @@ This page contains information about clusters hosted on Microsoft Azure[^1] and ## Clusters -The following table provides information about available clusters on Microsoft Azure cloud computing platform. The latest cluster status can be found on Clusters page in web application. +The following table provides information about available clusters on Microsoft Azure cloud computing platform. The +latest cluster status can be found on Clusters page +in web application. -| Name | Hostname | Location | -| :---: | :---: | :---: | -| cluster-007 | master-production-20160630-cluster-007.exabyte.io | East US | +| Name | Hostname | Location | +|:-----------:|:-------------------------------------------------:|:--------:| +| cluster-003 | master-production-20250821-cluster-003.mat3ra.com | East US | ## Queues -The list of currently enabled queues is given below. Price per core hour is shown in relation to the [relative unit price](../../pricing/service-levels.md#comparison-table) and is subject to change at any time. Total number of nodes can be increased upon [request](../../ui/support.md). - -| Name | Category[^2] | Mode[^3] | Charge Policy[^4] | Price | Max Nodes per Job+ | Max Nodes Total | -| :---: | :---: | :---: | :---: | :---: | :---: | :---: | -| D | debug | debug | core-seconds | 4.002 | 1 | 10 | -| OR | ordinary | regular | core-seconds | 1.275 | 1 | 10 | -| OF | ordinary | fast | core-hours | 1.275 | ≤5 | 100 | -| OFplus| ordinary | fast | core-hours | 1.275 | 5 | 10 | -| SR | saving | regular | core-seconds | 0.379 | 1 | 10 | -| SF | saving | fast | core-hours | 0.379 | 1* | 100 | -| SFplus | saving | fast | core-hours | 0.379 | 5 | 10 | -| GPOF | ordinary | fast | core-hours | 6.110 | ≤5 | 10 | -| GP2OF | ordinary | fast | core-hours | 6.110 | ≤5 | 10 | -| GP4OF | ordinary | fast | core-hours | 6.110 | ≤5 | 10 | -| GPSF | saving | fast | core-hours | 1.222 | ≤5 | 10 | -| GP2SF | saving | fast | core-hours | 1.222 | ≤5 | 10 | -| GP4SF | saving | fast | core-hours | 1.222 | ≤5 | 10 | +The list of currently enabled queues is given below. Price per core hour is shown in relation to +the [relative unit price]({{ guide_url }}/pricing/service-levels/#comparison-table) and is subject to change at any time. Total +number of nodes can be increased upon [request]({{ interface_url }}/ui/support/). -+ please contact support to inquire about attempting a larger node count per job - -* presently the infrastructure limitations are not allowing for the multi-node communication in SF queue, so only single-node jobs should be attempted (as of Oct 2022) +| Name | Category[^2] | Mode[^3] | Charge Policy[^4] | Price | Max Nodes per Job+ | Max Nodes Total | +|:------:|:------------:|:--------:|:-----------------:|:-----:|:-----------------------------:|:---------------:| +| D | debug | ordinary | core-seconds | 4.002 | 1 | 10 | +| OR | regular | ordinary | core-seconds | 1.275 | 1 | 10 | +| SR | regular | saving | core-seconds | 0.379 | 1 | 10 | +| OF | fast | ordinary | core-hours | 1.275 | 5 | 100 | +| SF | fast | saving | core-hours | 0.379 | 5 | 100 | +| GPOF | fast | ordinary | core-hours | 6.110 | 5 | 10 | +| GPSF | fast | saving | core-hours | 1.222 | 5 | 10 | ++ please contact support to inquire about attempting a larger node count per job ## Hardware Specifications -The following table contains hardware specifications for the above queues. - -| Name | CPU[^5] | Cores per Node | GPU[^6] | GPU per Node | Memory (GB) | Bandwidth (Gb/sec) | -| :---: | :---: | :---: | :---: | :---: | :---: | :---: | -| D | c-7 | 16 | - | - | 32 | ≤10 | -| OR | c-6 | 44 | - | - | 352 | 100 | -| OF | c-6 | 44 | - | - | 352 | 100 | -| OFplus| c-6 | 44 | - | - | 352 | 100 | -| SR | c-6 | 44 | - | - | 352 | 100 | -| SF | c-6 | 44 | - | - | 352 | 100 | -| SFPlus| c-6 | 44 | - | - | 352 | 100 | -| GPOF | c-2 | 6 | g-2 | 1 | 112 | 10 | -| GP2OF | c-2 | 12 | g-2 | 2 | 224 | 10 | -| GP4OF | c-2 | 24 | g-2 | 4 | 448 | 10 | -| GPSF | c-2 | 6 | g-2 | 1 | 112 | 10 | -| GP2SF | c-2 | 12 | g-2 | 2 | 224 | 10 | -| GP4SF | c-2 | 24 | g-2 | 4 | 448 | 10 | +The following table contains hardware specifications for the above queues. + +| Name | Cores per Node | GPU per Node | Memory (GB) | Bandwidth (Gb/sec) | VM Size | +|:------:|:--------------:|:------------:|:-----------:|:------------------:|:------------------------:| +| D | 8 | - | 2 | ≤10 | Standard_F8s_v2 | +| OR | 44 | - | 352 | 100 | Standard_HC44rs | +| OF | 44 | - | 352 | 100 | Standard_HC44rs | +| SR | 44 | - | 352 | 100 | Standard_HC44rs | +| SF | 44 | - | 352 | 100 | Standard_HC44rs | +| GPOF | 40 | 1 | 320 | 40 | Standard_NC40ads_H100_v5 | +| GPSF | 40 | 1 | 320 | 40 | Standard_NC40ads_H100_v5 | ## Links [^1]: [Microsoft Azure, Website](https://azure.microsoft.com/en-us/) -[^2]: [Queue Cost Categories, Website](../resource/category.md#cost-categories) +[^2]: [Queue Cost Categories, this documentation](../resource/category.md#cost-categories) -[^3]: [Queue Provision Modes, Website](../resource/category.md#provision-modes) +[^3]: [Queue Provision Modes, this documentation](../resource/category.md#provision-modes) -[^4]: [Charge polices, Website](../resource/queues.md#charge-policies) +[^4]: [Charge polices, this documentation](../resource/queues.md#charge-policies) -[^5]: [CPU types, Website](hardware.md#cpu-types) +[^5]: [CPU types, this documentation](hardware.md#cpu-types) -[^6]: [GPU types, Website](hardware.md#gpu-types) +[^6]: [GPU types, this documentation](hardware.md#gpu-types) [^7]: [Azure high performance compute virtual machines, Website](https://docs.microsoft.com/en-us/azure/virtual-machines/linux/sizes-hpc) diff --git a/lang/en/docs/infrastructure/clusters/cluster-101.md b/lang/en/docs/infrastructure/clusters/cluster-101.md new file mode 100644 index 000000000..99f2472c6 --- /dev/null +++ b/lang/en/docs/infrastructure/clusters/cluster-101.md @@ -0,0 +1,40 @@ +# Cluster-101 + +## Overview + +This cluster is hosted on [Microsoft Azure][^1] infrastructure and is intended to provide free compute resources. + +| Name | Hostname | Location | +|:-----------:|:-------------------------------------------------:|:--------:| +| cluster-101 | master-production-20250821-cluster-101.mat3ra.com | East US | + +## Queues + +The list of currently enabled queues is given below. + +The price factor is shown in relation to the [relative unit price]({{ guide_url }}/pricing/service-levels/#comparison-table). + +The price factor if 10E-4 means that the cost of using this queue is 0.0001 times the cost of using the base queue (OR). +This is intended to provide free compute resources and keep the accounting of resource usage. + +| Name | Category[^2] | Mode[^3] | Charge Policy[^4] | Price Factor | Max Nodes per Job+ | Max Nodes Total | +|:----:|:------------:|:--------:|:-----------------:|:------------:|:-----------------------------:|:---------------:| +| D | debug | ordinary | core-seconds | 1.0E-4 | 1 | 1 | +| OR | regular | saving | core-seconds | 1.0E-4 | 1 | 0 | +| SR | regular | saving | core-seconds | 1.0E-4 | 1 | 1 | +| OF | fast | saving | core-hours | 1.0E-4 | 5 | 0 | +| SF | fast | saving | core-hours | 1.0E-4 | 5 | 1 | +| GPOF | fast | saving | core-hours | 1.0E-4 | 5 | 0 | +| GPSF | fast | saving | core-hours | 1.0E-4 | 5 | 1 | + ++ please contact support to inquire about attempting a larger node count per job + +## Hardware Specifications + +See [Azure Queues](azure.md) for more information. + +# Links + +[^1]: [Microsoft Azure, Website](https://azure.microsoft.com/en-us/) + +///FOOTNOTES GO HERE/// diff --git a/lang/en/docs/infrastructure/clusters/directories.md b/lang/en/docs/infrastructure/clusters/directories.md index b0bc2e8d9..3362bb677 100644 --- a/lang/en/docs/infrastructure/clusters/directories.md +++ b/lang/en/docs/infrastructure/clusters/directories.md @@ -6,22 +6,22 @@ The following directories are present under the home folder of each cluster (ref . ├── data ├── dropbox => /dropbox/gmogni -├── exabyte-io => /cluster-001-share/groups/exabyte-io +├── mat3ra => /cluster-001-share/groups/mat3ra └── job_script_templates => /export/compute/job_script_templates ``` -Each important folder is introduced in what follows, complementing the [general discussion](../../data-on-disk/directories.md) on the directory structure within our platform. +Each important folder is introduced in what follows, complementing the [general discussion]({{ reference_url }}/data-on-disk/directories/) on the directory structure within our platform. ## Naming -The home directories on each cluster are mapped under the main [Login Home](../login/directories.md) and serve as "gateways" to the data in each cluster. They can be accessed by [cluster alias](overview.md#cluster-aliases) with their absolute paths of the form `/-home//`, for example `/cluster-001-home/steven/`. These directories contain the hierarchical structure outlined in the remainder of the present page, and are affected by the storage quotas described [here](../../data-on-disk/quotas.md). +The home directories on each cluster are mapped under the main [Login Home](../login/directories.md) and serve as "gateways" to the data in each cluster. They can be accessed by [cluster alias](overview.md#cluster-aliases) with their absolute paths of the form `/-home//`, for example `/cluster-001-home/steven/`. These directories contain the hierarchical structure outlined in the remainder of the present page, and are affected by the storage quotas described [here]({{ reference_url }}/data-on-disk/quotas/). !!! warning "Simulations must be executed after navigating to one of the clusters folders only" - Any [simulation jobs](../../jobs/overview.md) must be executed within the clusters (ie. inside cluster home directories) so that the tasks are sent to the corresponding cluster by our [resource management system](../resource/overview.md) and the associated data is stored therein as well. We explain the procedure for doing so via the [Command Line Interface](../../cli/overview.md) in [this section](../../jobs-cli/overview.md) of the documentation. + Any [simulation jobs]({{ reference_url }}/jobs/overview/) must be executed within the clusters (ie. inside cluster home directories) so that the tasks are sent to the corresponding cluster by our [resource management system](../resource/overview.md) and the associated data is stored therein as well. We explain the procedure for doing so via the [Command Line Interface]({{ cli_url }}/cli/overview/) in [this section]({{ cli_url }}/jobs-cli/overview/) of the documentation. ## Example -In the image below, we highlight two examples of cluster home directories present under the login home, as viewed in a [remote desktop environment](../../remote-connection/remote-desktop.md). The two clusters available in this case are referenced under the aliases "cluster-001" and "cluster-007". +In the image below, we highlight two examples of cluster home directories present under the login home, as viewed in a [remote desktop environment]({{ cli_url }}/remote-connection/remote-desktop/). The two clusters available in this case are referenced under the aliases "cluster-001" and "cluster-007". ![Cluster Homes](../../images/infrastructure/cluster-homes.png "Cluster Homes") @@ -29,13 +29,13 @@ Example contents of the home directory for cluster-001 are displayed in the subs ![Cluster Home Contents](../../images/infrastructure/cluster-home-content.png "Cluster Home Contents") -The "dropbox" and "job_script_templates" folders are present under both Cluster Home and [Login Home](../login/directories.md) and are explained in more detail [in this page](../../data-on-disk/directories.md). +The "dropbox" and "job_script_templates" folders are present under both Cluster Home and [Login Home](../login/directories.md) and are explained in more detail [in this page]({{ reference_url }}/data-on-disk/directories/). ## Shared Folders for Organizations -Simulations data for [Organizations](../../collaboration/organizations/overview.md) (collaborative [accounts](../../accounts/overview.md)) is stored in a dedicated **shared folder** accessible by its **members only**. This shared folder bears the same name as the Organization itself: for example, "exabyte-io" in the visual above. Simulation files present under this data are organized according to the Project/Job based directory naming explained below. +Simulations data for [Organizations]({{ reference_url }}/collaboration/organizations/overview/) (collaborative [accounts]({{ reference_url }}/accounts/overview/)) is stored in a dedicated **shared folder** accessible by its **members only**. This shared folder bears the same name as the Organization itself: for example, "mat3ra" in the visual above. Simulation files present under this data are organized according to the Project/Job based directory naming explained below. -Each organization of which the user is member has its own corresponding shared directory. For example, organization `exabyte-io` has its folder under the path `/share/groups/exabyte-io/`. +Each organization of which the user is member has its own corresponding shared directory. For example, organization `mat3ra` has its folder under the path `/share/groups/mat3ra/`. ## Temporary Data @@ -46,13 +46,13 @@ Personal Accounts can also share data between them, without necessarily belongin ## Personal Account "Data" Folder -The "data" folder present under each cluster home directory contains the **private files** on the cluster accessible to the user only, and generated with his/her [personal account](../../accounts/overview.md). Simulation files present under this data are organized according to the Project/Job based directory naming explained below. +The "data" folder present under each cluster home directory contains the **private files** on the cluster accessible to the user only, and generated with his/her [personal account]({{ reference_url }}/accounts/overview/). Simulation files present under this data are organized according to the Project/Job based directory naming explained below. The absolute path of the data folder for a cluster under the alias "cluster-001" is located at the path location `/cluster-001-home//data`. ## Project/Job based directory naming -Simulation files created through the [Web Interface](../../ui/overview.md) are automatically organized based on the [Project](../../jobs/projects.md) and constituent [Jobs](../../jobs/overview.md) that they are associated with. The subfolders are named according to the [project slug](../../jobs/projects.md#slug) and the job [slug](../../entities-general/data.md#slug), as well as its [ID](../../entities-general/data.md#top-level-keywords). +Simulation files created through the [Web Interface]({{ interface_url }}/ui/overview/) are automatically organized based on the [Project]({{ reference_url }}/jobs/projects/) and constituent [Jobs]({{ reference_url }}/jobs/overview/) that they are associated with. The subfolders are named according to the [project slug]({{ reference_url }}/jobs/projects/#slug) and the job [slug]({{ reference_url }}/entities-general/data/#slug), as well as its [ID]({{ reference_url }}/entities-general/data/#top-level-keywords). This is demonstrated below for an example user with username "steven", project named "Default", and a job named "New Job Nov 11, 2018-20-59 pm", with id "575z5FgGQvtRMBnXg". diff --git a/lang/en/docs/infrastructure/clusters/google.md b/lang/en/docs/infrastructure/clusters/google.md new file mode 100644 index 000000000..a083bde21 --- /dev/null +++ b/lang/en/docs/infrastructure/clusters/google.md @@ -0,0 +1,59 @@ +# Google Cloud Platform + +This page contains information about clusters hosted on Google Cloud Platform[^1] and their hardware specifications. + +## Clusters + +The following table provides information about available clusters on Google Cloud Platform cloud computing platform. The +latest cluster status can be found on Clusters page +in web application. + +| Name | Hostname | Location | +|:-----------:|:-------------------------------------------------:|:----------:| +| cluster-001 | master-production-20250821-cluster-001.mat3ra.com | US-Central | + +## Queues + +The list of currently enabled queues is given below. Price per core hour is shown in relation to +the [relative unit price]({{ guide_url }}/pricing/service-levels/#comparison-table) and is subject to change at any time. Total +number of nodes can be increased upon [request]({{ interface_url }}/ui/support/). + +| Name | Category[^2] | Mode[^3] | Charge Policy[^4] | Price | Max Nodes per Job+ | Max Nodes Total | +|:------:|:------------:|:--------:|:-----------------:|:-----:|:-----------------------------:|:---------------:| +| D | debug | ordinary | core-seconds | 4.002 | 1 | 1 | +| OR | regular | ordinary | core-seconds | 1.275 | 1 | 1 | +| OF | fast | ordinary | core-hours | 1.275 | 5 | 5 | +| OFplus | fast | ordinary | core-hours | 1.275 | 5 | 5 | +| GOF | fast | ordinary | core-hours | 6.110 | 2 | 2 | + ++ please contact support to inquire about attempting a larger node count per job + +## Hardware Specifications + +The following table contains hardware specifications for the above queues. + +| Name | Cores per Node | GPU per Node | Memory (GB) | Bandwidth (Gb/sec) | VM Size | +|:------:|:--------------:|:------------:|:-----------:|:------------------:|:----------------:| +| D | 2 | - | 15 | ≤10 | n1-standard-4 | +| OR | 16 | - | 64 | ≤10 | c2-standard-16 | +| OF | 60 | - | 240 | 10 | c2-standard-60 | +| OFplus | 192 | - | 720 | 10 | h4d-standard-192 | +| GOF | 12 | 1 | 170 | 100 | a2-highgpu-1g | + +## Links + +[^1]: [Google Cloud Platform, Website](https://cloud.google.com/) + +[^2]: [Queue Cost Categories, this documentation](../resource/category.md#cost-categories) + +[^3]: [Queue Provision Modes, this documentation](../resource/category.md#provision-modes) + +[^4]: [Charge polices, this documentation](../resource/queues.md#charge-policies) + +[^5]: [CPU types, this documentation](hardware.md#cpu-types) + +[^6]: [GPU types, this documentation](hardware.md#gpu-types) + +[^7]: [Google Cloud VM instances, Website](https://cloud.google.com/compute/docs/machine-types) + +///FOOTNOTES GO HERE/// diff --git a/lang/en/docs/infrastructure/clusters/hardware.md b/lang/en/docs/infrastructure/clusters/hardware.md index e39154b20..ad48897e6 100644 --- a/lang/en/docs/infrastructure/clusters/hardware.md +++ b/lang/en/docs/infrastructure/clusters/hardware.md @@ -1,6 +1,6 @@ # Hardware Specifications -Our computing resources are hosted by trusted vendors: [Amazon Web Services](aws.md) and [Microsoft Azure](azure.md). +Our computing resources are hosted by trusted vendors: [Amazon Web Services](aws.md) and [Microsoft Azure](azure.md). We support IBM SoftLayer[^1], Rackspace[^2] and Google Cloud[^3] can deploy capacity there on a short notice. The following shows the CPU and GPU hardware specification on aforementioned vendors. @@ -9,34 +9,37 @@ The following shows the CPU and GPU hardware specification on aforementioned ven The following table shows different types of CPUs available in our platform. -| Name | Type | Processor Base Frequency (GHz) | -| :---: | :---: | :---: | -| c-1 | Intel Xeon E5-2667-v3[^4] | 3.20 | -| c-2 | Intel Xeon E5-2690-v4[^5] | 2.60 | -| c-3 | Intel Xeon E5-2666-v3[^6] | 2.90 | -| c-4 | Intel Xeon E5-2686-v4[^7] | 2.30 | -| c-5 | Intel Xeon Platinum[^6a] | 3.00 | -| c-6 | Intel Xeon Platinum 8168[^8] | 2.70 | -| c-7 | Intel Xeon E5-2673-v3[^11] | 2.40 | +| Name | Type | Processor Base Frequency (GHz) | +|:----:|:------------------------------:|:------------------------------:| +| c-1 | Intel Xeon E5-2667-v3[^4] | 3.20 | +| c-2 | Intel Xeon E5-2690-v4[^5] | 2.60 | +| c-3 | Intel Xeon E5-2666-v3[^6] | 2.90 | +| c-4 | Intel Xeon E5-2686-v4[^7] | 2.30 | +| c-5 | Intel Xeon Platinum[^6a] | 3.00 | +| c-6 | Intel Xeon Platinum 8168[^8] | 2.70 | +| c-7 | Intel Xeon E5-2673-v3[^11] | 2.40 | +| c-8 | Intel Xeon Platinum 8275L[^11] | 3.00 | +| c-9 | AMD EPYC 7R13[^12] | 3.60 | ## GPU Types The following table shows different types of GPUs the GPU-enabled compute nodes are provisioned with. -| Name | Type | -| :---: | :---: | -| g-1 | NVIDIA V100[^9] | -| g-2 | NVIDIA P100[^10] | - +| Name | Type | +|:----:|:----------------:| +| g-3 | NVIDIA A100[^9] | +| g-4 | NVIDIA H100[^10] | ## Available Resources -As of Apr, 2018 our major compute and storage systems (per cluster) are as explained below. The total number of cores is administratively limited by our agreements with the cloud vendors, and cen be extended further upon request. Elastically grown file system lets us reach to 8 exabytes (EB) of disk space per single cluster. +As of 2025 our major compute and storage systems (per cluster) are as explained below. +The total number of cores is administratively limited by our agreements with the cloud vendors, and +can be extended further upon request. -| Provider | Total cores | Total Memory (GB) | Total Disk (EB) | -| :--------- | :--------: | :---------------: | :-------------: | -| AWS | 36,000 | 60,000 | 8 | -| Azure | 10,000 | 20,000 | 8 | +| Provider | Total cores | Total Memory (GB) | Total Disk (EB) | +|:---------|:-----------:|:-----------------:|:---------------:| +| AWS | 36,000 | 60,000 | 8 | +| Azure | 10,000 | 20,000 | 8 | ## Links @@ -58,10 +61,14 @@ As of Apr, 2018 our major compute and storage systems (per cluster) are as expla [^8]: [HC-Series, Microsoft Azure documentation](https://docs.microsoft.com/en-us/azure/virtual-machines/hc-series) -[^9]: [NVIDIA Tesla V100, online product documentation](https://www.nvidia.com/en-us/data-center/tesla-v100/) +[^9]: [NVIDIA A100, online product documentation](https://www.nvidia.com/en-us/data-center/a100/) -[^10]: [NVIDIA Tesla P100, online product documentation](https://www.nvidia.com/en-us/data-center/tesla-p100/) +[^10]: [NVIDIA H100, online product documentation](https://www.nvidia.com/en-us/data-center/h100/) [^11]: [F-Series VM Sizes, Azure](https://azure.microsoft.com/en-us/blog/f-series-vm-size/) +[^11]: [p4d.24xlarge VM Sizes, AWS](https://aws.amazon.com/ec2/instance-types/p4/) + +[^12]: [p5.4xlarge VM Sizes, AWS](https://aws.amazon.com/ec2/instance-types/p5/) + ///FOOTNOTES GO HERE/// diff --git a/lang/en/docs/infrastructure/clusters/overview.md b/lang/en/docs/infrastructure/clusters/overview.md index 7973fe190..9d1ee31f3 100644 --- a/lang/en/docs/infrastructure/clusters/overview.md +++ b/lang/en/docs/infrastructure/clusters/overview.md @@ -34,15 +34,15 @@ The architecture of a cluster is explained in the diagram below, comprising a ** ## [Storage](../storage.md) -Clusters also offer a certain amount of **storage space** for [storing](../storage.md) simulation files as [unstructured data](../../data-on-disk/overview.md), subject to certain **quotas** as explained [here](../../data-on-disk/quotas.md). +Clusters also offer a certain amount of **storage space** for [storing](../storage.md) simulation files as [unstructured data]({{ reference_url }}/data-on-disk/overview/), subject to certain **quotas** as explained [here]({{ reference_url }}/data-on-disk/quotas/). ### [Directory Structure](directories.md) We discuss the directory structure which can be found inside the home folder of each cluster [in this section](directories.md) of the documentation. -## [Performance Benchmarks](../../benchmarks/overview.md) +## [Performance Benchmarks]({{ reference_url }}/benchmarks/overview/) -The clusters offered as part of the [infrastructure of our platform](../overview.md) have been subject to an extensive set of **tests and benchmarks**, in order to measure their reliability and performance for different [hardware types](hardware.md) and for the [simulation engines](../../software/components.md) used. They are reviewed and assessed in a [separate section](../../benchmarks/overview.md) of the present documentation. +The clusters offered as part of the [infrastructure of our platform](../overview.md) have been subject to an extensive set of **tests and benchmarks**, in order to measure their reliability and performance for different [hardware types](hardware.md) and for the [simulation engines]({{ reference_url }}/software/components/) used. They are reviewed and assessed in a [separate section]({{ reference_url }}/benchmarks/overview/) of the present documentation. ### Cloud Providers diff --git a/lang/en/docs/infrastructure/compute/data.md b/lang/en/docs/infrastructure/compute/data.md index 088bd9451..91bcb2439 100644 --- a/lang/en/docs/infrastructure/compute/data.md +++ b/lang/en/docs/infrastructure/compute/data.md @@ -25,8 +25,8 @@ Below we show an example JSON structured representation for the compute paramete | Keyword | |:-----------------------------------------------| -| [ppn](parameters.md#nodes-/-ppn) | -| [nodes](parameters.md#nodes-/-ppn) | +| [ppn](parameters.md#nodes-ppn) | +| [nodes](parameters.md#nodes-ppn) | | [queue](parameters.md#queue) | | [timeLimit](parameters.md#time-limit) | | [timeLimitType](parameters.md#time-limit-type) | diff --git a/lang/en/docs/infrastructure/compute/overview.md b/lang/en/docs/infrastructure/compute/overview.md index 7a728a6d7..ea33e67d6 100644 --- a/lang/en/docs/infrastructure/compute/overview.md +++ b/lang/en/docs/infrastructure/compute/overview.md @@ -1,6 +1,6 @@ # Compute Setup -The "Compute" panel, located as a distinct tab under the [Job Designer](../../jobs-designer/overview.md) interface, allows the user to set up the [computational parameters](parameters.md) for the simulation to be executed. +The "Compute" panel, located as a distinct tab under the [Job Designer]({{ interface_url }}/jobs-designer/overview/) interface, allows the user to set up the [computational parameters](parameters.md) for the simulation to be executed. ## Components of the Interface @@ -22,9 +22,9 @@ The user can choose among the available [clusters](../clusters/overview.md) as e The [Queue](../resource/queues.md) of the resource manager can be set [as follows](parameters.md#queue). -## 4. [Nodes/PPN](parameters.md#nodes-/-ppn) +## 4. [Nodes/PPN](parameters.md#nodes-ppn) -The number of computing nodes, and number of Processors per Node (PPN), can be set by the user as described [here](parameters.md#nodes-/-ppn). +The number of computing nodes, and number of Processors per Node (PPN), can be set by the user as described [here](parameters.md#nodes-ppn). ## 5. [Advanced Options](parameters.md#advanced-options) @@ -32,4 +32,4 @@ Further advanced options for the computation are available, and consist in the [ ## 6. [Notifications](parameters.md#notifications) -Notifications on the [job status](../../jobs/status.md) can be triggered as explained [in this section](parameters.md#notifications). +Notifications on the [job status]({{ reference_url }}/jobs/status/) can be triggered as explained [in this section](parameters.md#notifications). diff --git a/lang/en/docs/infrastructure/compute/parameters.md b/lang/en/docs/infrastructure/compute/parameters.md index 8e63daadc..4a0c187b9 100644 --- a/lang/en/docs/infrastructure/compute/parameters.md +++ b/lang/en/docs/infrastructure/compute/parameters.md @@ -18,7 +18,7 @@ Relevant for [Saving Compute Category](../resource/category.md#cost-categories). ### Is restartable -If the job should be restarted upon termination, e.g. due to saving node termination. See "-r" [directive](../../jobs-cli/batch-scripts/directives.md#other-useful-directives) +If the job should be restarted upon termination, e.g. due to saving node termination. See "-r" [directive]({{ cli_url }}/jobs-cli/batch-scripts/directives/#other-useful-directives) ## Cluster choice @@ -26,19 +26,19 @@ A list of [computing clusters](../clusters/overview.md) is available for perform ## Queue -[Queues](../resource/overview.md) are used for managing the submission of [Jobs](../../jobs/overview.md) to the [computing clusters](../clusters/overview.md). +[Queues](../resource/overview.md) are used for managing the submission of [Jobs]({{ reference_url }}/jobs/overview/) to the [computing clusters](../clusters/overview.md). The user is offered the possibility to launch the desired job with a flexible set of [hardware](../clusters/hardware.md) and resource allocation modes per queue. For example, the Debug ("D") queue is especially suited for preliminary tests, "fast" queues (eg. "OF")" are best for high-throughput or multi-node distributed memory runs, and "regular queues" (eg. OR) provide regular access to the scheduler. ## Nodes / PPN -The desired number of computing nodes and the number of cores on each node (PPN = processors per node) can be selected, depending on the expected computational costs and requirements of the calculation under consideration. The necessary payments will have to be made as explained [in this page](../../accounts/balance.md), before the execution of any task can be made possible. +The desired number of computing nodes and the number of cores on each node (PPN = processors per node) can be selected, depending on the expected computational costs and requirements of the calculation under consideration. The necessary payments will have to be made as explained [in this page]({{ reference_url }}/accounts/balance/), before the execution of any task can be made possible. ## Notifications Finally, the user can be notified about the start of the calculation on the supercomputing cluster, about its termination, or about a possible accidental abortion. -The user can click on the button corresponding to each one of these [Job statuses](../../jobs/status.md) within the [user interface](overview.md) to trigger the associated notifications. Alternatively, all three notification types can be activated simultaneously by clicking the user icon. +The user can click on the button corresponding to each one of these [Job statuses]({{ reference_url }}/jobs/status/) within the [user interface](overview.md) to trigger the associated notifications. Alternatively, all three notification types can be activated simultaneously by clicking the user icon. ## Advanced Options @@ -46,4 +46,4 @@ Further advanced options are offered in order to optimize the calculation. These ### Specific Implementation -The user should consult the corresponding [application pages](../../software-directory/overview.md) for more information about the advanced options which pertain to each respective application. +The user should consult the corresponding [application pages]({{ reference_url }}/software-directory/overview/) for more information about the advanced options which pertain to each respective application. diff --git a/lang/en/docs/infrastructure/login/directories.md b/lang/en/docs/infrastructure/login/directories.md index cfff1a86e..8bfcacabd 100644 --- a/lang/en/docs/infrastructure/login/directories.md +++ b/lang/en/docs/infrastructure/login/directories.md @@ -4,7 +4,7 @@ Each user has its own **Login Home** directory mounted on the [login node](overview.md) filesystem, under the path `/home//`, such that user `steven` has `/home/steven/` as a home directory, for example. -The quota limit for data storage under this directory is described [here](../../data-on-disk/quotas.md). +The quota limit for data storage under this directory is described [here]({{ reference_url }}/data-on-disk/quotas/). ## Subdirectories @@ -29,9 +29,9 @@ Upon connecting to the login home, the user is presented with the following **di For the sake of the present discussion, the important folders are the ones labelled with an arrow to their right, indicating that they represent shortcuts pointing to the full path specified to the right of the arrow. -The "dropbox" and "job_script_templates" folders are present under both Cluster Home and [Login Home](../login/directories.md) and are explained in more detail [in this page](../../data-on-disk/directories.md). Each other important folder is introduced in what follows. +The "dropbox" and "job_script_templates" folders are present under both Cluster Home and [Login Home](../login/directories.md) and are explained in more detail [in this page]({{ reference_url }}/data-on-disk/directories/). Each other important folder is introduced in what follows. -The remaining folders conform to the conventions of the [Linux distribution](../../remote-connection/remote-desktop.md#linux-environment) used in our platform. +The remaining folders conform to the conventions of the [Linux distribution]({{ cli_url }}/remote-connection/remote-desktop/#linux-environment) used in our platform. ## Cluster Homes @@ -39,14 +39,14 @@ Login node is meant for storing auxiliary data, such as source code, scripts, no ## Job Script Templates -The Login Home also contains a folder with [Job script](../../jobs-cli/batch-scripts/overview.md) template examples, necessary for [submitting jobs via the Command Line Interface](../../jobs-cli/overview.md). Explained in more details [here](../../data-on-disk/directories.md#job-script-templates). +The Login Home also contains a folder with [Job script]({{ cli_url }}/jobs-cli/batch-scripts/overview/) template examples, necessary for [submitting jobs via the Command Line Interface]({{ cli_url }}/jobs-cli/overview/). Explained in more details [here]({{ reference_url }}/data-on-disk/directories/#job-script-templates). ## Dropbox -Explained in more details [here](../../data-on-disk/directories.md#dropbox). +Explained in more details [here]({{ reference_url }}/data-on-disk/directories/#dropbox). ## Example -The location of the login home folder under the main [remote desktop environment](../../remote-connection/remote-desktop.md) is highlighted in red in the following illustration. +The location of the login home folder under the main [remote desktop environment]({{ cli_url }}/remote-connection/remote-desktop/) is highlighted in red in the following illustration. ![Login Home](../../images/infrastructure/login-home.png "Login Home") diff --git a/lang/en/docs/infrastructure/login/overview.md b/lang/en/docs/infrastructure/login/overview.md index b9d9877ae..ad4dcae74 100644 --- a/lang/en/docs/infrastructure/login/overview.md +++ b/lang/en/docs/infrastructure/login/overview.md @@ -3,11 +3,11 @@ The Login node constitutes the main **access point** to the our infrastructure, and is organized according to the directory structure introduced below. !!!warning "Transit via Login Node" - We can exceptionally concede the ability to connect directly to the [cluster](../clusters/overview.md) for advanced users. A special permission needs to be [requested](../../ui/support.md). + We can exceptionally concede the ability to connect directly to the [cluster](../clusters/overview.md) for advanced users. A special permission needs to be [requested]({{ interface_url }}/ui/support/). -## [Connection Options](../../remote-connection/overview.md) +## [Connection Options]({{ cli_url }}/remote-connection/overview/) -We introduce the different remote connection options separately [here](../../remote-connection/overview.md). +We introduce the different remote connection options separately [here]({{ cli_url }}/remote-connection/overview/). ## [Directory Structure](directories.md) diff --git a/lang/en/docs/infrastructure/overview.md b/lang/en/docs/infrastructure/overview.md index eeb46d624..25ce1b2a8 100644 --- a/lang/en/docs/infrastructure/overview.md +++ b/lang/en/docs/infrastructure/overview.md @@ -2,7 +2,7 @@ Our platform represents a comprehensive **distributed web application**. This section explains the most important components of its **computational infrastructure**. -We additionally support platform-level access via [advanced connection methods](../remote-connection/overview.md), as an alternative to the main Web Interface. Platform-level access methods are intended for expert users and also offer the ability to submit [simulation jobs](../jobs-cli/overview.md) to the [computing clusters](clusters/overview.md), for example. +We additionally support platform-level access via [advanced connection methods]({{ cli_url }}/remote-connection/overview/), as an alternative to the main Web Interface. Platform-level access methods are intended for expert users and also offer the ability to submit [simulation jobs]({{ cli_url }}/jobs-cli/overview/) to the [computing clusters](clusters/overview.md), for example. ## Architecture diagram @@ -12,35 +12,35 @@ The different components forming the underlying architecture of our computationa In the above image, we apply the following conventions for labelling the interconnecting lines. -- Blue lines indicate [remote connection methods](../remote-connection/overview.md) to our platform. -- The orange lines correspond to the transfer of [structured data](../data-structured/overview.md) between the corresponding nodes. +- Blue lines indicate [remote connection methods]({{ cli_url }}/remote-connection/overview/) to our platform. +- The orange lines correspond to the transfer of [structured data]({{ data_url }}/data-structured/overview/) between the corresponding nodes. - Solid red lines are dedicated to data under [object representation](../data-in-objectstorage/overview.md). - Dotted red lines label the Network File System, for accessing files over the infrastructure network. - Finally, green lines mark the [Resource Manager](resource/overview.md) for controlling the computational resources of our platform. -## 1. [Web Interface](../ui/overview.md) +## 1. [Web Interface]({{ interface_url }}/ui/overview/) -The Web Interface of our platform is introduced separately from the rest of the computational infrastructure, [in this page](../ui/overview.md). +The Web Interface of our platform is introduced separately from the rest of the computational infrastructure, [in this page]({{ interface_url }}/ui/overview/). -## 2. [Remote Desktop](../remote-connection/remote-desktop.md) +## 2. [Remote Desktop]({{ cli_url }}/remote-connection/remote-desktop/) -A remote desktop environment is offered for connecting to the platform and accessing the relevant data stored in its different nodes. This is explained in details [here](../remote-connection/remote-desktop.md). +A remote desktop environment is offered for connecting to the platform and accessing the relevant data stored in its different nodes. This is explained in details [here]({{ cli_url }}/remote-connection/remote-desktop/). -## 3. [Rest API](../rest-api/overview.md) +## 3. [Rest API]({{ developers_url }}/rest-api/overview/) -We explain the Rest API access method [in this section](../rest-api/overview.md) of the documentation. +We explain the Rest API access method [in this section]({{ developers_url }}/rest-api/overview/) of the documentation. -## 4. [SSH](../remote-connection/ssh.md) +## 4. [SSH]({{ cli_url }}/remote-connection/ssh/) -The [Command Line Interface](../cli/overview.md) can also be accessed via an external SSH client instead of the Web Terminal. [This page](../remote-connection/ssh.md) outlines the instructions on how to do so. +The [Command Line Interface]({{ cli_url }}/cli/overview/) can also be accessed via an external SSH client instead of the Web Terminal. [This page]({{ cli_url }}/remote-connection/ssh/) outlines the instructions on how to do so. ## 5. [Login Node](login/overview.md) The Login Node provides the main access gateway to the rest of the computational infrastructure, and is the object of a [separate discussion](login/overview.md). -## 6. [Web Terminal](../remote-connection/web-terminal.md) +## 6. [Web Terminal]({{ cli_url }}/remote-connection/web-terminal/) -Alternatively to the aforementioned Remote Desktop connection method, the platform can also be accessed via the Command Line Interface described [here](../cli/overview.md). We provide a [Web Terminal](../remote-connection/web-terminal.md) utility for logging in via Command Line directly from the Web Interface. +Alternatively to the aforementioned Remote Desktop connection method, the platform can also be accessed via the Command Line Interface described [here]({{ cli_url }}/cli/overview/). We provide a [Web Terminal]({{ cli_url }}/remote-connection/web-terminal/) utility for logging in via Command Line directly from the Web Interface. ## 7. [Dropbox](../data-in-objectstorage/dropbox.md) @@ -52,7 +52,7 @@ The computational power of our platform is distributed across different cloud-ba ## 9. [Storage System](storage.md) -The input and output data of simulations can be stored as [unstructured data](../data-on-disk/overview.md) on an appropriate storage system, as explained in its corresponding [documentation page](storage.md). +The input and output data of simulations can be stored as [unstructured data]({{ reference_url }}/data-on-disk/overview/) on an appropriate storage system, as explained in its corresponding [documentation page](storage.md). ## 10. [Resource Management](resource/overview.md) @@ -66,12 +66,12 @@ The simulation files stored on the cluster hard drives can subsequently be store The Master Node constitutes the main entry gateway to each available computing Cluster, and is documented in its respective [section of the documentation](clusters/directories.md). -## 13. [Database](../accounts/collections.md) +## 13. [Database]({{ reference_url }}/accounts/collections/) -The Database contains the various account-owned [collections](../accounts/collections.md) of [entities](../entities-general/overview.md) and their respective [properties](../properties/overview.md), stored in the form of [structured data](../data-structured/overview.md). +The Database contains the various account-owned [collections]({{ reference_url }}/accounts/collections/) of [entities]({{ reference_url }}/entities-general/overview/) and their respective [properties]({{ reference_url }}/properties/overview/), stored in the form of [structured data]({{ data_url }}/data-structured/overview/). ## 14. [Computational Resources](compute/overview.md) -The various settings and parameters affecting the allocation of the computational resources offered on our infrastructure, at the moment of the launching of a [Job simulation](../jobs/overview.md), can be entered from the Web Interface according to the instructions contained [in this page](compute/overview.md). +The various settings and parameters affecting the allocation of the computational resources offered on our infrastructure, at the moment of the launching of a [Job simulation]({{ reference_url }}/jobs/overview/), can be entered from the Web Interface according to the instructions contained [in this page](compute/overview.md). The computational resources available as part of our services are themselves listed for each of the [Azure](clusters/azure.md) and [Amazon Web Service](clusters/aws.md) Cloud Providers. diff --git a/lang/en/docs/infrastructure/resource/queues.md b/lang/en/docs/infrastructure/resource/queues.md index bec783bdc..5164d0ef7 100644 --- a/lang/en/docs/infrastructure/resource/queues.md +++ b/lang/en/docs/infrastructure/resource/queues.md @@ -49,4 +49,4 @@ Detailed [cluster](../clusters/overview.md)-specific lists of queues are availab ## Select Queue -Queues can be selected under the Web Interface according to the instructions found [here](../compute/overview.md). Similarly, the desired queue can be specified in the [Batch Script](../../jobs-cli/batch-scripts/overview.md) for the case of [Job submission via the Command Line Interface](../../jobs-cli/overview.md). +Queues can be selected under the Web Interface according to the instructions found [here](../compute/overview.md). Similarly, the desired queue can be specified in the [Batch Script]({{ cli_url }}/jobs-cli/batch-scripts/overview/) for the case of [Job submission via the Command Line Interface]({{ cli_url }}/jobs-cli/overview/). diff --git a/lang/en/docs/infrastructure/storage.md b/lang/en/docs/infrastructure/storage.md index 9f39f14c2..e1c164419 100644 --- a/lang/en/docs/infrastructure/storage.md +++ b/lang/en/docs/infrastructure/storage.md @@ -1,6 +1,6 @@ # Storage System -We store the raw simulation data on on block storage drives (ie. hard drives) connected to the [computational clusters](clusters/overview.md). The present page explains some of the related conventions. The policies applied to the information in the form of **unstructured data** are explained further [in this section](../data-on-disk/overview.md) of the documentation. +We store the raw simulation data on on block storage drives (ie. hard drives) connected to the [computational clusters](clusters/overview.md). The present page explains some of the related conventions. The policies applied to the information in the form of **unstructured data** are explained further [in this section]({{ reference_url }}/data-on-disk/overview/) of the documentation. ## Storage Diagram @@ -8,10 +8,10 @@ A representative example of an overall storage system, such as implemented on ou ![Storage System](../images/infrastructure/Storage-System.png "Storage System") -The above example includes multiple clusters connected to the same central [Login Node](login/overview.md), each one with its own corresponding main access [Master Node](clusters/directories.md) and associated storage space. Here, we also show (through color labelling) how each [Cluster Home](../data-on-disk/directories.md#cluster-home) directory present under the corresponding Master Node filesystem is **mapped (mounted)** to the [Login Home](../data-on-disk/directories.md#login-home). +The above example includes multiple clusters connected to the same central [Login Node](login/overview.md), each one with its own corresponding main access [Master Node](clusters/directories.md) and associated storage space. Here, we also show (through color labelling) how each [Cluster Home]({{ reference_url }}/data-on-disk/directories/#cluster-home) directory present under the corresponding Master Node filesystem is **mapped (mounted)** to the [Login Home]({{ reference_url }}/data-on-disk/directories/#login-home). -For example, the home folder for "cluster-001" under the path `/home/` on the Master Node is mapped to the directory path `/cluster-001-home/` under the Login Node. A similar pattern is applied for the [Shared Folders for Organizations](../data-on-disk/directories.md#shared-folders-for-organizations). +For example, the home folder for "cluster-001" under the path `/home/` on the Master Node is mapped to the directory path `/cluster-001-home/` under the Login Node. A similar pattern is applied for the [Shared Folders for Organizations]({{ reference_url }}/data-on-disk/directories/#shared-folders-for-organizations). ## Storage Quotas -These storage spaces are subject to certain **quotas**, limiting the size of the data that may be saved in them. These quotas are documented [here](../data-on-disk/quotas.md). +These storage spaces are subject to certain **quotas**, limiting the size of the data that may be saved in them. These quotas are documented [here]({{ reference_url }}/data-on-disk/quotas/). diff --git a/lang/en/docs/jobs-cli/accounting.md b/lang/en/docs/jobs-cli/accounting.md index 45e319942..6a4e730fe 100644 --- a/lang/en/docs/jobs-cli/accounting.md +++ b/lang/en/docs/jobs-cli/accounting.md @@ -1,29 +1,29 @@ # Accounting -We describe here the [accounting](../accounts/overview.md) aspects which are particularly relevant in the context of [Job Submission via CLI](overview.md). +We describe here the [accounting]({{ reference_url }}/accounts/overview/) aspects which are particularly relevant in the context of [Job Submission via CLI](overview.md). ## Job Project Specification -In order to specify a [project](../jobs/projects.md) that the job should belong to and should be [charged upon](../accounts/payments-charges.md), the following [resource management directive](batch-scripts/directives.md) should be used within the job's corresponding [batch script file](batch-scripts/overview.md). +In order to specify a [project]({{ reference_url }}/jobs/projects/) that the job should belong to and should be [charged upon]({{ reference_url }}/accounts/payments-charges/), the following [resource management directive](batch-scripts/directives.md) should be used within the job's corresponding [batch script file](batch-scripts/overview.md). ```bash #PBS -A ``` -Each user has a [default project](../jobs/projects.md#default-project) that jobs are charged on by default, unless this choice is modified with the above directive. +Each user has a [default project]({{ reference_url }}/jobs/projects/#default-project) that jobs are charged on by default, unless this choice is modified with the above directive. -For the case of [Organizational Accounts](../collaboration/organizations/overview.md), if no project is specified within the batch script, then the [personal account](../collaboration/organizations/roles.md#organizations-vs.-personal-accounts) of the user will be charged upon under its default project. +For the case of [Organizational Accounts]({{ reference_url }}/collaboration/organizations/overview/), if no project is specified within the batch script, then the [personal account]({{ reference_url }}/collaboration/organizations/roles/#organizations-vs.-personal-accounts) of the user will be charged upon under its default project. !!! warning "Remember to specify job project for organizational accounts" Please remember to always specify the job project explicitly for organizational accounts. Otherwise the personal account will be charged, and/or (if there is not enough balance) the jobs might be removed from scheduling. ## Registration of Jobs in Web Interface -We explain how jobs submitted via CLI can be transmitted and registered in the [Web Interface](../ui/overview.md) of our platform in a [dedicated Tutorial](../tutorials/jobs-cli/job-cli-example.md). +We explain how jobs submitted via CLI can be transmitted and registered in the [Web Interface]({{ interface_url }}/ui/overview/) of our platform in a [dedicated Tutorial]({{ guide_url }}/tutorials/jobs-cli/job-cli-example/). ## Check Account Balance and Quota -The [balance](../accounts/balance.md) and [storage quota](../accounts/quota.md) for the [Account](../accounts/overview.md) under consideration can be inspected via CLI by following the instructions contained [in this page](../cli/actions/balance-quota.md). +The [balance]({{ reference_url }}/accounts/balance/) and [storage quota]({{ reference_url }}/accounts/quota/) for the [Account]({{ reference_url }}/accounts/overview/) under consideration can be inspected via CLI by following the instructions contained [in this page](../cli/actions/balance-quota.md). ## View List of Jobs and Charges diff --git a/lang/en/docs/jobs-cli/actions/check-status.md b/lang/en/docs/jobs-cli/actions/check-status.md index f0b8bd2de..58f86fea6 100644 --- a/lang/en/docs/jobs-cli/actions/check-status.md +++ b/lang/en/docs/jobs-cli/actions/check-status.md @@ -10,7 +10,7 @@ JOBID USERNAME QUEUE JOBN 815.master-production-20160630-cluster-007.exabyte.io steve OR my_job R 1235kb 00:00:10 00:10:00 1 1 ``` -The complete manual page for this command listing all its possible option flags can be found in the reference containing the information about the Resource Management System [in the corresponding page of the present documentation](../../infrastructure/resource/overview.md#links) (page 364). +The complete manual page for this command listing all its possible option flags can be found in the reference containing the information about the Resource Management System [in the corresponding page of the present documentation]({{ resources_url }}/infrastructure/resource/overview/#links) (page 364). ## Job ID in CLI @@ -28,4 +28,4 @@ The possible job statuses indicated under the "STATE" column of the `qstat` comm - "R": Job is currently **Running**. - "C": Job execution is **Complete**. This can include the possibility of jobs interrupted prematurely because of errors. -Consult the reference containing the information about the Resource Management System [in the corresponding page of the present documentation](../../infrastructure/resource/overview.md#links) for more information. +Consult the reference containing the information about the Resource Management System [in the corresponding page of the present documentation]({{ resources_url }}/infrastructure/resource/overview/#links) for more information. diff --git a/lang/en/docs/jobs-cli/actions/create.md b/lang/en/docs/jobs-cli/actions/create.md index 4374944ac..b34b45672 100644 --- a/lang/en/docs/jobs-cli/actions/create.md +++ b/lang/en/docs/jobs-cli/actions/create.md @@ -1,25 +1,25 @@ # Create New Job -Here, we explain how to assemble the necessary input files for [job submission via the CLI](../overview.md) using some pre-defined examples. The reader is referred to the [dedicated Tutorial](../../tutorials/) on this topic for a more comprehensive description and examples on how such input files can be customized by the user. +Here, we explain how to assemble the necessary input files for [job submission via the CLI](../overview.md) using some pre-defined examples. The reader is referred to the [dedicated Tutorial]({{ guide_url }}/tutorials/overview/) on this topic for a more comprehensive description and examples on how such input files can be customized by the user. ## General Procedure -A new [simulation Job](../../jobs/overview.md) can be created by assembling the necessary **simulation input files**, as well as the **[Batch Script](../batch-scripts/overview.md)** associated with the job, under the same [working folder](../batch-scripts/directories.md). +A new [simulation Job]({{ reference_url }}/jobs/overview/) can be created by assembling the necessary **simulation input files**, as well as the **[Batch Script](../batch-scripts/overview.md)** associated with the job, under the same [working folder](../batch-scripts/directories.md). -By our convention, this working folder must be located under the [cluster home directory](../../infrastructure/clusters/directories.md) of the [computing cluster](../../infrastructure/clusters/overview.md) being considered for job execution. +By our convention, this working folder must be located under the [cluster home directory]({{ resources_url }}/infrastructure/clusters/directories/) of the [computing cluster]({{ resources_url }}/infrastructure/clusters/overview/) being considered for job execution. !!! note "Choose walltime carefully" - The [Walltime](../../infrastructure/compute/parameters.md#time-limit) of the simulation is defined in the [Batch Script](../batch-scripts/overview.md) through its corresponding [directive](../batch-scripts/directives.md), and should be chosen carefully for a number of reasons. + The [Walltime]({{ resources_url }}/infrastructure/compute/parameters/#time-limit) of the simulation is defined in the [Batch Script](../batch-scripts/overview.md) through its corresponding [directive](../batch-scripts/directives.md), and should be chosen carefully for a number of reasons. - 1. Jobs that require long walltime will [reserve the corresponding balance](../../accounts/balance.md#reserved-balance), and thus prevent other jobs from starting. + 1. Jobs that require long walltime will [reserve the corresponding balance]({{ reference_url }}/accounts/balance/#reserved-balance), and thus prevent other jobs from starting. 2. When not enough walltime is allocated, the job may not finish on time, resulting in an erroneous output. - 3. The user is advised to [submit a support ticket](../../ui/support.md) if a walltime adjustment is needed during the course of a long job execution. Our support staff will do their best to accommodate the necessary desired changes, depending on the current computing load and business hours. + 3. The user is advised to [submit a support ticket]({{ interface_url }}/ui/support/) if a walltime adjustment is needed during the course of a long job execution. Our support staff will do their best to accommodate the necessary desired changes, depending on the current computing load and business hours. Users can find our examples of job batch scripts and input files as explained [here](../batch-scripts/sample-scripts.md). ### Example -Below are example commands needed to copy and run one of these template examples with the [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md) modeling application, contained in the `espresso` sub-directory inside `job_script_templates`. +Below are example commands needed to copy and run one of these template examples with the [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) modeling application, contained in the `espresso` sub-directory inside `job_script_templates`. ```bash # make temporary directory @@ -30,4 +30,4 @@ cd job-examples/ && cp -r ~/job_script_templates/espresso . cd espresso && qsub job.pbs ``` -The above case [submits](submit.md) the sample Quantum ESPRESSO job into the [queue](../../infrastructure/resource/queues.md) of the [resource manager](../../infrastructure/resource/overview.md) for scheduling its execution. You can view its status with the `qstat` command described [here](check-status.md). +The above case [submits](submit.md) the sample Quantum ESPRESSO job into the [queue]({{ resources_url }}/infrastructure/resource/queues/) of the [resource manager]({{ resources_url }}/infrastructure/resource/overview/) for scheduling its execution. You can view its status with the `qstat` command described [here](check-status.md). diff --git a/lang/en/docs/jobs-cli/actions/overview.md b/lang/en/docs/jobs-cli/actions/overview.md index cd8b025d6..468b5e070 100644 --- a/lang/en/docs/jobs-cli/actions/overview.md +++ b/lang/en/docs/jobs-cli/actions/overview.md @@ -4,7 +4,7 @@ In the present section of the documentation, we review the most frequently encou ## [Create New Jobs](create.md) -We introduce some simple instructions on how the user can run some pre-defined simulation examples via CLI [in this page](create.md). These instructions are intended to get the user rapidly up to speed with the core functioning and features of our [CLI](../../cli/overview.md). More detailed explanations for understanding the possibility of advanced job customization on our platform can be retrieved under a [dedicated tutorial](../../tutorials/jobs-cli/job-cli-example.md). +We introduce some simple instructions on how the user can run some pre-defined simulation examples via CLI [in this page](create.md). These instructions are intended to get the user rapidly up to speed with the core functioning and features of our [CLI](../../cli/overview.md). More detailed explanations for understanding the possibility of advanced job customization on our platform can be retrieved under a [dedicated tutorial]({{ guide_url }}/tutorials/jobs-cli/job-cli-example/). ## [Submit Job](submit.md) @@ -20,4 +20,4 @@ A Job can be terminated artificially by the user at any time preceding its compl ## [View List of Jobs and Charges](view-job-list.md) -A detailed list of Jobs and associated [Accounting Charges](../../accounts/payments-charges.md) produced to date by the user can be generated under CLI as explained [here](view-job-list.md), for user's reference and convenience. +A detailed list of Jobs and associated [Accounting Charges]({{ reference_url }}/accounts/payments-charges/) produced to date by the user can be generated under CLI as explained [here](view-job-list.md), for user's reference and convenience. diff --git a/lang/en/docs/jobs-cli/actions/submit.md b/lang/en/docs/jobs-cli/actions/submit.md index 527d61aa7..bf28abf99 100644 --- a/lang/en/docs/jobs-cli/actions/submit.md +++ b/lang/en/docs/jobs-cli/actions/submit.md @@ -3,7 +3,7 @@ After a [Batch Script](../batch-scripts/overview.md) is prepared, computation jobs can be **submitted** for execution via CLI. !!! warning "Some things to remember" - Simulation input files have been [gathered together](create.md) under the same [Working Directory](../batch-scripts/directories.md). This Working Directory has to be located within the [Home folder](../../infrastructure/clusters/directories.md) of the cluster on which the user wants to execute the job, so that it is directed to the desired [computing cluster](../../infrastructure/clusters/overview.md). We also recommend the user to first consult the accounting aspects documented [here](../accounting.md), before proceeding with job submission. + Simulation input files have been [gathered together](create.md) under the same [Working Directory](../batch-scripts/directories.md). This Working Directory has to be located within the [Home folder]({{ resources_url }}/infrastructure/clusters/directories/) of the cluster on which the user wants to execute the job, so that it is directed to the desired [computing cluster]({{ resources_url }}/infrastructure/clusters/overview/). We also recommend the user to first consult the accounting aspects documented [here](../accounting.md), before proceeding with job submission. Job submission is performed with the `qsub` command, as demonstrated in the following example, where the Batch Script in this case is called `my_job.pbs`. @@ -12,7 +12,7 @@ Job submission is performed with the `qsub` command, as demonstrated in the foll 814.master-production-20160630-cluster-007.exabyte.io ``` -This command return the Job ID, further explained below. The manual page for this command can be reviewed in the reference containing the information about the Resource Management System [in the corresponding page of the present documentation](../../infrastructure/resource/overview.md#links) (page 373). +This command return the Job ID, further explained below. The manual page for this command can be reviewed in the reference containing the information about the Resource Management System [in the corresponding page of the present documentation]({{ resources_url }}/infrastructure/resource/overview/#links) (page 373). ## Jobs ID diff --git a/lang/en/docs/jobs-cli/actions/terminate.md b/lang/en/docs/jobs-cli/actions/terminate.md index f0969bc74..df1b09b46 100644 --- a/lang/en/docs/jobs-cli/actions/terminate.md +++ b/lang/en/docs/jobs-cli/actions/terminate.md @@ -14,4 +14,4 @@ This explanation concerns the jobs [submitted for execution via CLI](../overview ## More information -The manual page for the `qdel` command, listing the available option flags, can be retrieved the reference containing the information about the Resource Management System [in the corresponding page of the present documentation](../../infrastructure/resource/overview.md#links) (page 337). +The manual page for the `qdel` command, listing the available option flags, can be retrieved the reference containing the information about the Resource Management System [in the corresponding page of the present documentation]({{ resources_url }}/infrastructure/resource/overview/#links) (page 337). diff --git a/lang/en/docs/jobs-cli/actions/view-job-list.md b/lang/en/docs/jobs-cli/actions/view-job-list.md index a5525624e..e9450a896 100644 --- a/lang/en/docs/jobs-cli/actions/view-job-list.md +++ b/lang/en/docs/jobs-cli/actions/view-job-list.md @@ -2,7 +2,7 @@ To get detailed information about all the [jobs](../overview.md) [submitted](../overview.md) **to date** by the user on the [Command Line Interface](../../cli/overview.md) (CLI) of our system, the `lsjob` command should be entered, as displayed in the example below. -This information includes the relevant [compute parameters](../../infrastructure/compute/parameters.md) used as part of the job execution, as well as the [Project](../../jobs/projects.md) container and [Account Charges](../../accounts/payments-charges.md) incurred by each listed Job. Here, the Jobs are referenced by their **"Job IDs"**, as well as by their IDs attributed by the accounting system. +This information includes the relevant [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/) used as part of the job execution, as well as the [Project]({{ reference_url }}/jobs/projects/) container and [Account Charges]({{ reference_url }}/accounts/payments-charges/) incurred by each listed Job. Here, the Jobs are referenced by their **"Job IDs"**, as well as by their IDs attributed by the accounting system. ## Example diff --git a/lang/en/docs/jobs-cli/batch-scripts/apptainer.md b/lang/en/docs/jobs-cli/batch-scripts/apptainer.md new file mode 100644 index 000000000..9cdaafb41 --- /dev/null +++ b/lang/en/docs/jobs-cli/batch-scripts/apptainer.md @@ -0,0 +1,57 @@ +# Apptainer and Environment Modules + +On the new platform, environment modules integrate with Apptainer to provide consistent, containerized runtimes for HPC applications. When you `module load` an application, the module system: + +- Resolves and loads required dependencies (e.g., `gcc`, `mpi`) +- Sets per-application environment variables (e.g., `$EXEC_CMD_VASP`, `$EXEC_CMD_QE`) +- Updates a convenience variable `$EXEC_CMD` to the most recently loaded application's command +- Maintains `$EXEC_CMDS` as a colon-separated list of loaded application exec variables (e.g., `EXEC_CMD_VASP:EXEC_CMD_QE`) + +## Example session + +```bash +>>>> module load espresso/6.3-gcc-openmpi-openblas +The module gcc/11.2.0 is loaded +The module mpi/ompi-4.1.1 is loaded +The module espresso/6.3-gcc-openmpi-openblas is loaded + +Loading espresso/6.3-gcc-openmpi-openblas + Loading requirement: gcc/11.2.0 mpi/ompi-4.1.1 + +>>>> echo $EXEC_CMD +apptainer exec --bind /export,/scratch,/dropbox,/cluster-001-share \ + /export/compute/software/applications/espresso/6.3-gcc-openmpi-openblas/image.sif + +>>>> echo $EXEC_CMDS +EXEC_CMD_QE + +>>>> echo $EXEC_CMD_QE +apptainer exec --bind /export,/scratch,/dropbox,/cluster-001-share \ + /export/compute/software/applications/espresso/6.3-gcc-openmpi-openblas/image.sif + +>>>> module load vasp/5.4.4-gcc-openmpi-openblas-fftw-scalapack +The module vasp/5.4.4-gcc-openmpi-openblas-fftw-scalapack is loaded + +>>>> echo $EXEC_CMDS +EXEC_CMD_VASP:EXEC_CMD_QE + +>>>> echo $EXEC_CMD +apptainer exec --bind /export,/scratch,/dropbox,/cluster-001-share \ + /export/compute/software/applications/vasp/5.4.4-gcc-openmpi-openblas-fftw-scalapack/image.sif + +>>>> echo $EXEC_CMD_VASP +apptainer exec --bind /export,/scratch,/dropbox,/cluster-001-share \ + /export/compute/software/applications/vasp/5.4.4-gcc-openmpi-openblas-fftw-scalapack/image.sif +``` + +Notes: +- The Apptainer command binds common platform directories into the container (e.g., `/export`, `/scratch`, `/dropbox`, and the cluster share such as `/cluster-001-share`). +- `$EXEC_CMD` always points to the last loaded application's container exec command. +- Use per-app variables (e.g., `$EXEC_CMD_VASP`, `$EXEC_CMD_QE`) when you need to be explicit in job scripts. + +## Using in job scripts + +See: +- [Jobs via Command Line](../overview.md) +- [Batch Scripts > General Structure](general-structure.md) +- [Batch Scripts > Sample Scripts](sample-scripts.md) diff --git a/lang/en/docs/jobs-cli/batch-scripts/directives.md b/lang/en/docs/jobs-cli/batch-scripts/directives.md index 2a8d8af48..ed8ff2ea2 100644 --- a/lang/en/docs/jobs-cli/batch-scripts/directives.md +++ b/lang/en/docs/jobs-cli/batch-scripts/directives.md @@ -1,29 +1,29 @@ # Resource Manager Directives -As introduced [here](general-structure.md#3.-directives), the keywords described in the present page may be specified as **PBS Resource Manager Directives** (preceded by the `#PBS` prefix), to be embedded in a [batch script](overview.md). These directives are particularly important for allocating the necessary [computational resources and parameters](../../infrastructure/compute/parameters.md) to the given [simulation Job](../../jobs/overview.md), for its [submission to the CLI](../overview.md). +As introduced [here](general-structure.md#3.-directives), the keywords described in the present page may be specified as **PBS Resource Manager Directives** (preceded by the `#PBS` prefix), to be embedded in a [batch script](overview.md). These directives are particularly important for allocating the necessary [computational resources and parameters]({{ resources_url }}/infrastructure/compute/parameters/) to the given [simulation Job]({{ reference_url }}/jobs/overview/), for its [submission to the CLI](../overview.md). -Full documentation on the resource management software and its directives can be found the reference containing the information about the Resource Management System [in the corresponding page of the present documentation](../../infrastructure/resource/overview.md#links). +Full documentation on the resource management software and its directives can be found the reference containing the information about the Resource Management System [in the corresponding page of the present documentation]({{ resources_url }}/infrastructure/resource/overview/#links). ## Important Directives | Directive | Default | Description | | ------------------|------------------|------------------| -| -l nodes = | 1 node | Number of [compute nodes](../../infrastructure/compute/parameters.md#nodes-/-ppn) assigned to the job | -| -l ppn = | 1 processor per node | Number of [processors per node](../../infrastructure/compute/parameters.md#nodes-/-ppn) (ppn). **Note:** ppn must be less than or equal to the maximum available number of cores on the target compute node | -| -l walltime = | 00:00:05:00 | The maximum authorized [wallclock time](../../infrastructure/compute/parameters.md#time-limit) for the job, after which the job will be automatically terminated | +| -l nodes = | 1 node | Number of [compute nodes]({{ resources_url }}/infrastructure/compute/parameters/#nodes-/-ppn) assigned to the job | +| -l ppn = | 1 processor per node | Number of [processors per node]({{ resources_url }}/infrastructure/compute/parameters/#nodes-/-ppn) (ppn). **Note:** ppn must be less than or equal to the maximum available number of cores on the target compute node | +| -l walltime = | 00:00:05:00 | The maximum authorized [wallclock time]({{ resources_url }}/infrastructure/compute/parameters/#time-limit) for the job, after which the job will be automatically terminated | | -N | No default | The name of the job; up to 15 printable, non-whitespace characters | -| -q | batch | Name of submit [queue](../../infrastructure/resource/queues.md), for example "D" for Debug or "OR16" for Ordinary, Regular, 16 cores per each compute node | +| -q | batch | Name of submit [queue]({{ resources_url }}/infrastructure/resource/queues/), for example "D" for Debug or "OR16" for Ordinary, Regular, 16 cores per each compute node | | -R | y | Register Job in the Web Interface ("y" for yes or "n" for no). This option is further explained [here](../accounting.md#register-jobs-in-web-interface) | -| -A | Default Project | [Charge job](../../accounts/payments-charges.md) to the selected [project](../../jobs/projects.md) | +| -A | Default Project | [Charge job]({{ reference_url }}/accounts/payments-charges/) to the selected [project]({{ reference_url }}/jobs/projects/) | !!!note "Project Name is required for Organizational Accounts" - We recommend to consult the accounting aspects of the Project Name and its effect on the accounting for the organizational [accounts](../../accounts/overview.md) documented [here](../accounting.md#job-project-specification). + We recommend to consult the accounting aspects of the Project Name and its effect on the accounting for the organizational [accounts]({{ reference_url }}/accounts/overview/) documented [here](../accounting.md#job-project-specification). ## Other Useful Directives | Directive | Default | Description | | ------------------|------------------|------------------| -| -r | y | Make the job re-runnable, in the sense that it can be restarted automatically. Select either "y" for yes or "n" for no. This is particularly useful when running Jobs under the [Saving queue category](../../infrastructure/resource/category.md), where the job can be interrupted anytime due to limited resources | +| -r | y | Make the job re-runnable, in the sense that it can be restarted automatically. Select either "y" for yes or "n" for no. This is particularly useful when running Jobs under the [Saving queue category]({{ resources_url }}/infrastructure/resource/category/), where the job can be interrupted anytime due to limited resources | | -e | <job_name>.e<job_id> | Write the standard error message(s) (stderr) encountered during job execution to the selected file name | | -o | <job_name>.o<job_id> | Write the standard output of the simulation (stdout) to the selected file name | | -j | Do not merge | Merge (join) stdout and stderr. Select "oe" for merging to output file, or "eo" for merging to error file instead | @@ -34,7 +34,7 @@ Full documentation on the resource management software and its directives can be The batch system defines many **environment variables**, which are available for use within batch scripts via the `$` reference prefix. The following table list some of the more useful variables. - Further explanation of these Environment Variables can be found under the reference containing the information about the Resource Management System [in the corresponding page of the present documentation](../../infrastructure/resource/overview.md#links) (page 112). + Further explanation of these Environment Variables can be found under the reference containing the information about the Resource Management System [in the corresponding page of the present documentation]({{ resources_url }}/infrastructure/resource/overview/#links) (page 112). !!!warning "Variables modification not recommended" The user is advised not to redefine the value of any of these variables. @@ -45,12 +45,12 @@ The batch system defines many **environment variables**, which are available for | PBS_O_HOME | Home directory of submitting user | | PBS_O_WORKDIR | Working directory in which the job files were defined and then [submitted](../actions/submit.md) | | PBS_JOBID | Unique identifier for this job; important for tracking [job status](../actions/check-status.md) | -| PBS_O_QUEUE | Name of submit [queue](../../infrastructure/resource/queues.md) | -| PBS_QUEUE | Name of execution [queue](../../infrastructure/resource/queues.md) | +| PBS_O_QUEUE | Name of submit [queue]({{ resources_url }}/infrastructure/resource/queues/) | +| PBS_QUEUE | Name of execution [queue]({{ resources_url }}/infrastructure/resource/queues/) | | PBS_O_JOBNAME | Name of the present job | -| PBS_NODEFILE | Name of file containing list of [nodes](../../infrastructure/compute/parameters.md#nodes-/-ppn) assigned to this job | -| PBS_NUM_NODES | Number of [nodes](../../infrastructure/compute/parameters.md#nodes-/-ppn) assigned to this job | -| PBS_NUM_PPN | Value of ["ppn" (processes per node)](../../infrastructure/compute/parameters.md#nodes-/-ppn) for this job | +| PBS_NODEFILE | Name of file containing list of [nodes]({{ resources_url }}/infrastructure/compute/parameters/#nodes-/-ppn) assigned to this job | +| PBS_NUM_NODES | Number of [nodes]({{ resources_url }}/infrastructure/compute/parameters/#nodes-/-ppn) assigned to this job | +| PBS_NUM_PPN | Value of ["ppn" (processes per node)]({{ resources_url }}/infrastructure/compute/parameters/#nodes-/-ppn) for this job | | PBS_NP | Total number of processors, that is the multiplication of the above-mentioned PBS_NUM_NODES with PBS_NUM_PPN | ## Standard Output and Error @@ -63,6 +63,6 @@ After the batch job completes, the above files will be renamed to the correspond ## Notifications -In order to get notified via email about an accidental job termination, resulting for example from computational errors or in case the job was being executed in the [Saving Category](../../infrastructure/resource/category.md) and got interrupted, the above-mentioned `#PBS -m abe` and `#PBS -M < email_address >` directives must be set inside the [Batch Script file](overview.md). +In order to get notified via email about an accidental job termination, resulting for example from computational errors or in case the job was being executed in the [Saving Category]({{ resources_url }}/infrastructure/resource/category/) and got interrupted, the above-mentioned `#PBS -m abe` and `#PBS -M < email_address >` directives must be set inside the [Batch Script file](overview.md). -In addition, for the latter case of Jobs being run in the Saving Category, our scheduling system automatically restarts any unintentionally terminated jobs, and re-submits them into the [regular queue](../../infrastructure/resource/category.md) for their continuation. If the user does not want the job to be restarted in this way, he/she must set the `#PBS -r n` directive inside the [Batch Script](overview.md). In this case, a temporary folder containing the job's intermediate results will be created in the user's home directory. +In addition, for the latter case of Jobs being run in the Saving Category, our scheduling system automatically restarts any unintentionally terminated jobs, and re-submits them into the [regular queue]({{ resources_url }}/infrastructure/resource/category/) for their continuation. If the user does not want the job to be restarted in this way, he/she must set the `#PBS -r n` directive inside the [Batch Script](overview.md). In this case, a temporary folder containing the job's intermediate results will be created in the user's home directory. diff --git a/lang/en/docs/jobs-cli/batch-scripts/directories.md b/lang/en/docs/jobs-cli/batch-scripts/directories.md index cc05b3ef8..6800bc20a 100644 --- a/lang/en/docs/jobs-cli/batch-scripts/directories.md +++ b/lang/en/docs/jobs-cli/batch-scripts/directories.md @@ -5,8 +5,8 @@ Each job defined via the [Command Line Interface](../../cli/overview.md) (CLI) is associated with a user-defined **Working Directory**, referred to under the corresponding [environment variable](directives.md#environment-variables). This directory typically contains the [Batch Script](overview.md) for defining the Job, as well as all of the job's corresponding input and output simulation files generated during the course of its execution. !!!warning "Required location of Working Directory" - A Job can be [submitted](../actions/submit.md) to a [cluster](../../infrastructure/clusters/overview.md) for its execution only if its corresponding working directory is located somewhere within the [cluster's home directory](../../infrastructure/clusters/directories.md), or under any of its sub-directories. + A Job can be [submitted](../actions/submit.md) to a [cluster]({{ resources_url }}/infrastructure/clusters/overview/) for its execution only if its corresponding working directory is located somewhere within the [cluster's home directory]({{ resources_url }}/infrastructure/clusters/directories/), or under any of its sub-directories. ## Job Templates -Users can find examples of job batch scripts and the corresponding input files within the job script templates further explained [here](../../data-on-disk/directories.md#job-script-templates). Users can copy the template inputs contained there into the corresponding job's working directory, and modify it as needed. +Users can find examples of job batch scripts and the corresponding input files within the job script templates further explained [here]({{ resources_url }}/data-on-disk/directories/#job-script-templates). Users can copy the template inputs contained there into the corresponding job's working directory, and modify it as needed. diff --git a/lang/en/docs/jobs-cli/batch-scripts/general-structure.md b/lang/en/docs/jobs-cli/batch-scripts/general-structure.md index 13e7f4df9..f836c86d8 100644 --- a/lang/en/docs/jobs-cli/batch-scripts/general-structure.md +++ b/lang/en/docs/jobs-cli/batch-scripts/general-structure.md @@ -18,11 +18,11 @@ The **shebang** [^1] is a short character sequence at the beginning of the Batch Commentaries (annotations) can be written anywhere within the batch script at the user's discretion, by inserting the "hash" character `#` and a single space ' ' at the start of the corresponding line. -Commentaries may consist in any text string containing any type of character, except for placing an exclamation mark `!` or [resource-manager](../../infrastructure/resource/overview.md)-specific text sequences immediately after the hash. The former character combination is reserved respectively for the above-mentioned shebang. +Commentaries may consist in any text string containing any type of character, except for placing an exclamation mark `!` or [resource-manager]({{ resources_url }}/infrastructure/resource/overview/)-specific text sequences immediately after the hash. The former character combination is reserved respectively for the above-mentioned shebang. ## 3. Directives -As introduced [here](overview.md#implementation), we make use of the **Portable Batch System (PBS)** protocol for organizing job scheduling on our platform. A comprehensive set of **PBS Resource Management Directives** is available for setting the relevant job parameters, such as allocating the necessary [computational resources](../../infrastructure/compute/parameters.md). +As introduced [here](overview.md#implementation), we make use of the **Portable Batch System (PBS)** protocol for organizing job scheduling on our platform. A comprehensive set of **PBS Resource Management Directives** is available for setting the relevant job parameters, such as allocating the necessary [computational resources]({{ resources_url }}/infrastructure/compute/parameters/). These directives are the object of a [dedicated review](directives.md). diff --git a/lang/en/docs/jobs-cli/batch-scripts/overview.md b/lang/en/docs/jobs-cli/batch-scripts/overview.md index 6f5ec0f37..dc3ecb520 100644 --- a/lang/en/docs/jobs-cli/batch-scripts/overview.md +++ b/lang/en/docs/jobs-cli/batch-scripts/overview.md @@ -1,12 +1,12 @@ # Batch Scripts -This page explains the basic framework for the submission of [simulation Jobs](../../jobs/overview.md) via the [Command Line Interface](../../cli/overview.md) (CLI). The corresponding actions for handling the job submission are narrated [separately](../actions/overview.md). +This page explains the basic framework for the submission of [simulation Jobs]({{ reference_url }}/jobs/overview/) via the [Command Line Interface](../../cli/overview.md) (CLI). The corresponding actions for handling the job submission are narrated [separately](../actions/overview.md). ## Batch Mode -Simulation tasks submitted through CLI are expected to be run in **"batch" mode**. Batch jobs are controlled by the so-called **Batch Scripts** (also referred to as **Job Scripts**), which are written by the user and then submitted to the [resource management system](../../infrastructure/resource/overview.md). These scripts specify, at the very least, how many nodes and cores the job will use, how long the job will run, the name of the [application](../../software-directory/overview.md) to be run, and other important [compute parameters](../../infrastructure/compute/parameters.md). +Simulation tasks submitted through CLI are expected to be run in **"batch" mode**. Batch jobs are controlled by the so-called **Batch Scripts** (also referred to as **Job Scripts**), which are written by the user and then submitted to the [resource management system]({{ resources_url }}/infrastructure/resource/overview/). These scripts specify, at the very least, how many nodes and cores the job will use, how long the job will run, the name of the [application]({{ reference_url }}/software-directory/overview/) to be run, and other important [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/). -Interactive parallel jobs are not supported on our platform by design. Users are encouraged to prototype calculations on the [login node](../../infrastructure/login/overview.md) (using 2-8 CPU cores with < 1min walltime per user) instead, and submit larger debug tasks into the [Debug queue](../../infrastructure/resource/category.md) designed specifically for testing purposes. +Interactive parallel jobs are not supported on our platform by design. Users are encouraged to prototype calculations on the [login node]({{ resources_url }}/infrastructure/login/overview/) (using 2-8 CPU cores with < 1min walltime per user) instead, and submit larger debug tasks into the [Debug queue]({{ resources_url }}/infrastructure/resource/category/) designed specifically for testing purposes. ## Implementation @@ -18,7 +18,7 @@ The general layout structure of Batch Scripts is the object of [this discussion] ## [Resource Manager Directives](directives.md) -[This page](directives.md) contains the list of the most important directives for specifying the allocation of [computing resources](../../infrastructure/resource/overview.md), necessary for the execution of the job under consideration. +[This page](directives.md) contains the list of the most important directives for specifying the allocation of [computing resources]({{ resources_url }}/infrastructure/resource/overview/), necessary for the execution of the job under consideration. ## [Working Directory](directories.md) diff --git a/lang/en/docs/jobs-cli/batch-scripts/sample-scripts.md b/lang/en/docs/jobs-cli/batch-scripts/sample-scripts.md index 5db49325c..0dbe3e028 100644 --- a/lang/en/docs/jobs-cli/batch-scripts/sample-scripts.md +++ b/lang/en/docs/jobs-cli/batch-scripts/sample-scripts.md @@ -1,13 +1,13 @@ # Sample Batch Scripts -Examples of batch scripts for a few of the [queue types](../../infrastructure/resource/queues.md) available on our platform are given throughout the present page. The reader is referred to the documentation pages explaining the [Resource Manager Directives](directives.md) and [environment modules](../../cli/modules.md) for the explanation of the batch script contents presented herein. +Examples of batch scripts for a few of the [queue types]({{ resources_url }}/infrastructure/resource/queues/) available on our platform are given throughout the present page. The reader is referred to the documentation pages explaining the [Resource Manager Directives](directives.md) and [environment modules](../../cli/modules.md) for the explanation of the batch script contents presented herein. !!!tip "Template job scripts" - [Job templates](../../data-on-disk/directories.md#job-script-templates) directory that contains template job scripts for different [applications](../../software/components.md). + [Job templates]({{ resources_url }}/data-on-disk/directories/#job-script-templates) directory that contains template job scripts for different [applications]({{ reference_url }}/software/components/). ## Debug queue (D) -This example requests 1 node with 2 processors (cores) for 10 minutes, in the Debug Queue for a sample [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md) run. +This example requests 1 node with 2 processors (cores) for 10 minutes, in the Debug Queue for a sample [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) run. ```bash #!/bin/bash @@ -23,12 +23,13 @@ This example requests 1 node with 2 processors (cores) for 10 minutes, in the De cd $PBS_O_WORKDIR module load espresso -mpirun -np $PBS_NP pw.x -in pw.input +# $EXEC_CMD is set by the environment module +mpirun -np $PBS_NP $EXEC_CMD pw.x -in pw.input ``` ## On-demand regular (OR) -This example requests 1 node and 16 cores for 10 minutes, on the OR [queue](../../infrastructure/resource/queues.md) for a sample [VASP](../../software-directory/modeling/quantum-espresso/overview.md) calculation. +This example requests 1 node and 16 cores for 10 minutes, on the OR [queue]({{ resources_url }}/infrastructure/resource/queues/) for a sample [VASP]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) calculation. ```bash #!/bin/bash @@ -44,5 +45,6 @@ This example requests 1 node and 16 cores for 10 minutes, on the OR [queue](../. cd $PBS_O_WORKDIR module load vasp -mpirun -np $PBS_NP vasp +# $EXEC_CMD is set by the environment module +mpirun -np $PBS_NP $EXEC_CMD vasp ``` diff --git a/lang/en/docs/jobs-cli/overview.md b/lang/en/docs/jobs-cli/overview.md index 00cd9580f..1a2f63ee3 100644 --- a/lang/en/docs/jobs-cli/overview.md +++ b/lang/en/docs/jobs-cli/overview.md @@ -1,6 +1,6 @@ # Jobs via Command Line Interface -The present section of the documentation explains how [simulation Jobs](../jobs/overview.md) can be created and executed via the [Command Line Interface (CLI)](../cli/overview.md) of our platform. +The present section of the documentation explains how [simulation Jobs]({{ reference_url }}/jobs/overview/) can be created and executed via the [Command Line Interface (CLI)](../cli/overview.md) of our platform. ## [Batch script](batch-scripts/overview.md) @@ -8,12 +8,16 @@ We explain how to compose **Batch Scripts** (also known as **Job Scripts**), nec ## [Accounting](accounting.md) -We describe the accounting aspects of Job submission via CLI, such as specifying [Projects](../jobs/projects.md) and inspecting the [Account](../accounts/overview.md) charges and balance, [here](accounting.md). +We describe the accounting aspects of Job submission via CLI, such as specifying [Projects]({{ reference_url }}/jobs/projects/) and inspecting the [Account]({{ reference_url }}/accounts/overview/) charges and balance, [here](accounting.md). ## [Actions](../cli/actions/overview.md) The actions pertaining to Jobs submission and execution under the CLI are reviewed [in this section](actions/overview.md) of the documentation. Other general actions concerning the CLI, such as the loading of modules, the compilation of new applications or the creation of new python environments, are described [separately](../cli/actions/overview.md). -## [Tutorials](../tutorials/jobs-cli/overview.md) +## Apptainer and Environment Modules -We provide tutorials guiding the user through the complete procedure for submitting jobs via CLI, and subsequently retrieving the corresponding results under the [Web Interface](../ui/overview.md) of our platform. These tutorials are introduced [here](../tutorials/jobs-cli/overview.md). +For the new platform, CLI workflows use Apptainer-backed modules that set `$EXEC_CMD` variables for containerized execution. See: [Apptainer and Environment Modules](batch-scripts/apptainer.md) + +## [Tutorials]({{ guide_url }}/tutorials/jobs-cli/overview/) + +We provide tutorials guiding the user through the complete procedure for submitting jobs via CLI, and subsequently retrieving the corresponding results under the [Web Interface]({{ interface_url }}/ui/overview/) of our platform. These tutorials are introduced [here]({{ guide_url }}/tutorials/jobs-cli/overview/). diff --git a/lang/en/docs/jobs-designer/actions-header-menu/select-materials.md b/lang/en/docs/jobs-designer/actions-header-menu/select-materials.md index 01aaaa3ce..11bfe012f 100644 --- a/lang/en/docs/jobs-designer/actions-header-menu/select-materials.md +++ b/lang/en/docs/jobs-designer/actions-header-menu/select-materials.md @@ -1,6 +1,9 @@ +--- +render_macros: true +--- # Select Materials to Jobs -The user may select one or multiple [materials](../../materials/overview.md) present in the account-owned [collection](../../accounts/collections.md) during [Job creation](../overview.md). Within the [header menu](../header-menu.md) of Jobs Designer, the relevant button on the right-hand side should be clicked, and the `Select materials` option chosen from the resulting drop-down menu. +The user may select one or multiple [materials]({{ reference_url }}/materials/overview/) present in the account-owned [collection]({{ reference_url }}/accounts/collections/) during [Job creation](../overview.md). Within the [header menu](../header-menu.md) of Jobs Designer, the relevant button on the right-hand side should be clicked, and the `Select materials` option chosen from the resulting drop-down menu. ## "Select Materials" Dialog @@ -20,7 +23,7 @@ Once the desired material(s) have been selected, they can be selected for the Jo This returns the view to the main Jobs Designer page, where the structures of the imported materials can be inspected within the [Materials Tab](../materials-tab.md). It is worth noticing that the original default material which was present when the Jobs Designer was first opened is replaced with the newly selected material(s). -When multiple materials are selected the [Job Name Field](../header-menu.md#1-job-name) can have a `{{ FORMULA }}` text added to it indicating that one separate job will be created per each selected material appending its formula to the name as explained [here](../header-menu.md#4-save-job). +When multiple materials are selected the [Job Name Field](../header-menu.md#1-job-name) can have a `{% raw %}{{ FORMULA }}{% endraw %}` text added to it indicating that one separate job will be created per each selected material appending its formula to the name as explained [here](../header-menu.md#4-save-job). ## Animation diff --git a/lang/en/docs/jobs-designer/actions-header-menu/select-parent.md b/lang/en/docs/jobs-designer/actions-header-menu/select-parent.md index 1d7474d82..c17b4c6da 100644 --- a/lang/en/docs/jobs-designer/actions-header-menu/select-parent.md +++ b/lang/en/docs/jobs-designer/actions-header-menu/select-parent.md @@ -1,29 +1,53 @@ # Select Parent Job -As introduced in the [header menu page](../header-menu.md#select-parent), a completed "Parent" Job can be selected and added to a Job being [designed](../../jobs/overview.md) from scratch. This new Job can in this way be based upon the Parent, and thus re-utilize its final results for further computation. These results are therefore "recycled", with the aim of optimizing the performance and computational time of the child Job. +As introduced in the [header menu page](../header-menu.md#select-parent), a +completed "Parent" Job can be selected and added to a Job being +[designed]({{ reference_url }}/jobs/overview/) from scratch. This new Job can in +this way be based upon the Parent, and thus re-utilize its final results for +further computation. These results are therefore "recycled", with the aim of +optimizing the performance and computational time of the child Job. -In order to do so, the user should select the `Select Parent` option under the drop-down menu of the main [header bar](../header-menu.md) of Jobs Designer. +In order to do so, the user should select the "Select Parent" option under the +"Select Job Actions" drop-down menu of the main [header bar](../header-menu.md) +of Jobs Designer. -## "Select Job" Dialog +## "Select Parent" Dialog -The "Select Job" dialog is now displayed with the following appearance, which is based on [Jobs Explorer](../../jobs/ui/explorer.md) and thus supporting the corresponding [filter/search](../../entities-general/actions/search.md) functionality. +The "Select Parent" dialog is based on [Jobs Explorer](../../jobs/ui/explorer.md) +and thus supporting the corresponding [filter/search]( +../../entities-general/actions/search.md) functionality. -![Select Job](../../images/jobs-designer/select-job-dialog.png "Select Job") +![Select Parent](../../images/jobs-designer/select-parent-job-dialog.webp "Select Parent") !!! warning "Criteria for Parent Job selection" - Only Jobs that satisfy both of the following criteria are available for selection as "parents". - - - The parent Job must be under either a "Finished" F or "Terminated" T [status](../../jobs/status.md). - - The parent Job must have been executed on a [cluster](../../infrastructure/clusters/overview.md) which is still available for use by the Account under consideration at the moment of the new Job creation. + Only Jobs that satisfy both of the following criteria are available for + selection as "parents". + + - The parent Job must be under either a "Finished" + F or "Terminated" + T + [status]({{ reference_url }}/jobs/status/). + - The parent Job must have been executed on a + [cluster]({{ resources_url }}/infrastructure/clusters/overview/) which is + still available for use by the Account under consideration at the moment of + the new Job creation. ## Add Parent Job -**Only one** Job can be [selected](../../entities-general/actions/select.md) as "Parent". It can be prepended to the Job being currently designed by pressing the "Select Items" button located under the [top-right actions toolbar](../../entities-general/ui/explorer.md#actions-toolbar). +**Only one** Job can be [selected](../../entities-general/actions/select.md) as +"Parent". It can be prepended to the Job being currently designed by pressing +the "Select Items" button +located under the [top-right actions toolbar]( +../../entities-general/ui/explorer.md#actions-toolbar). -This returns the view to the main [Jobs Designer](../overview.md) interface, where the name of the selected parent Job and of its container Project are now indicated directly below the main [header menu](../header-menu.md). +This returns the view to the main [Jobs Designer](../overview.md) interface, +where the name of the selected parent Job and of its container Project are now +indicated directly below the main [header menu](../header-menu.md). ## Animation -Here, we demonstrate how to prepend a parent total energy calculation, performed on the semiconductor GaAs, to a new band structure calculation being designed for the same material. +Here, we demonstrate how to prepend a parent total energy calculation, performed +on the semiconductor GaAs, to a new band structure calculation being designed +for the same material. diff --git a/lang/en/docs/jobs-designer/actions-header-menu/select-workflow.md b/lang/en/docs/jobs-designer/actions-header-menu/select-workflow.md index 240a02ae1..303c4b84c 100644 --- a/lang/en/docs/jobs-designer/actions-header-menu/select-workflow.md +++ b/lang/en/docs/jobs-designer/actions-header-menu/select-workflow.md @@ -1,8 +1,8 @@ # Select Workflow -[Workflows](../../workflows/overview.md) define the computational tasks to be executed and applied to the Material(s) [added](select-materials.md) to the Job being currently [designed](../overview.md). +[Workflows]({{ reference_url }}/workflows/overview/) define the computational tasks to be executed and applied to the Material(s) [added](select-materials.md) to the Job being currently [designed](../overview.md). -After opening the drop-down menu on the right-hand side of the [main header menu](../header-menu.md), the `Select workflow` option should be chosen in order to add Workflows present in the [account-owned collection](../../accounts/collections.md) to the Job being created. +After opening the drop-down menu on the right-hand side of the [main header menu](../header-menu.md), the `Select workflow` option should be chosen in order to add Workflows present in the [account-owned collection]({{ reference_url }}/accounts/collections/) to the Job being created. ## "Select Workflow" Dialog diff --git a/lang/en/docs/jobs-designer/compute-tab.md b/lang/en/docs/jobs-designer/compute-tab.md index ee01fc591..516b02c5b 100644 --- a/lang/en/docs/jobs-designer/compute-tab.md +++ b/lang/en/docs/jobs-designer/compute-tab.md @@ -1,6 +1,6 @@ # Compute Tab -Compute Tab present in [Jobs Designer](overview.md) allows the user to allocate the necessary [computational resources](../infrastructure/resource/overview.md) for the [Job](../jobs/overview.md), in order to ensure its successful and timely execution. +Compute Tab present in [Jobs Designer](overview.md) allows the user to allocate the necessary [computational resources]({{ resources_url }}/infrastructure/resource/overview/) for the [Job]({{ reference_url }}/jobs/overview/), in order to ensure its successful and timely execution. The typical appearance of Compute Tab is exhibited below. @@ -8,4 +8,4 @@ The typical appearance of Compute Tab is exhibited below. ## Link to Instructions -Instructions for understanding and setting the computational parameters can be found in the [corresponding part of the documentation](../infrastructure/compute/overview.md). +Instructions for understanding and setting the computational parameters can be found in the [corresponding part of the documentation]({{ resources_url }}/infrastructure/compute/overview/). diff --git a/lang/en/docs/jobs-designer/header-menu.md b/lang/en/docs/jobs-designer/header-menu.md index 3e8f044a2..f28837117 100644 --- a/lang/en/docs/jobs-designer/header-menu.md +++ b/lang/en/docs/jobs-designer/header-menu.md @@ -1,49 +1,88 @@ # Header Menu -The main header menu at the top of the [Jobs Designer](overview.md) interface is comprised of the following items enumerated below. Please refer to further explanations under the same number labels. +The main header menu at the top of the [Jobs Designer](overview.md) interface is +comprised of the following items enumerated below. Please refer to further +explanations under the same number labels. -![Header Menu](../images/jobs-designer/header-jobs-designer.png "Header Menu") +![Header Menu](../images/jobs-designer/header-jobs-designer.webp "Header Menu") ## 1. Job Name -The name of the Job being created is shown here and can be edited in-place. +The name of the Job being created is shown here and can be edited in-place. ### Project Name -The name of the Project container is also displayed in smaller characters directly underneath it, however unlike Jobs it **cannot** be modified following Project creation. +The name of the Project container is also displayed in smaller characters +directly underneath it, however unlike Jobs it **cannot** be modified following +Project creation. ## 2. Description -A **Description** of the Job is shown and can be edited in-place through the corresponding icon button . The reader is referred to [this page](../entities-general/actions/metadata.md#edit-description) for a full explanation of how to do this. +A **Description** of the Job is shown and can be edited in-place through the +corresponding toggle button. The reader is referred to [this page]( +../entities-general/actions/metadata.md#edit-description) for a full explanation +of how to do this. ## 3. Actions -The second button towards the right of the header menu allows the user primarily to add new entities to the Job being created. The following options are available under the corresponding drop-down menu. +The "Select Job Actions" dropdown list on the header menubar allows the user to +apply actions to the Job being created. The following options are available +under the corresponding dropdown list. ### [Select Materials](actions-header-menu/select-materials.md) -**Multiple** [Materials](../materials/overview.md) can be selected from the account-owned [collection](../accounts/collections.md), and added to the Job under creation. This procedure is described separately [in this page](actions-header-menu/select-materials.md). +**Multiple** [Materials]({{ reference_url }}/materials/overview/) can be +selected from the account-owned +[collection]({{ reference_url }}/accounts/collections/), and added to the Job +under creation. This procedure is described separately [in this page]( +actions-header-menu/select-materials.md). ### [Select Workflow](actions-header-menu/select-workflow.md) -A **single** [Workflow](../workflows/overview.md) can also be selected and added to the Job, for performing computations on **all** materials selected in the above step. If the user wishes to execute multiple computational tasks sequentially, he/she should consider the possibility of creating a sequence of [Subworkflows](../workflow-designer/subworkflow-editor/overview-tab.md) within the same Workflow instead. +A **single** [Workflow]({{ reference_url }}/workflows/overview/) can also be +selected and added to the Job, for performing computations on **all** materials +selected in the above step. If the user wishes to execute multiple computational +tasks sequentially, he/she should consider the possibility of creating a +sequence of [Subworkflows]( +../workflow-designer/subworkflow-editor/overview-tab.md) within the same +Workflow instead. -Instructions on how to select Workflows from the account-owned collection and add them to the Job being designed can be found [here](actions-header-menu/select-workflow.md). +Instructions on how to select Workflows from the account-owned collection and +add them to the Job being designed can be found [here]( +actions-header-menu/select-workflow.md). ### [Select Parent](actions-header-menu/select-parent.md) -This option is convenient when the Job being created is intended to be run on top of the results obtained from a previous "parent" Job. Some examples where such a scenario is plausible include the re-calculation of a property with slight modifications, or obtaining the same results but with a higher precision. In both cases, the same preliminary calculations performed in the preceding parent job can be re-utilized, thus saving computational time. +This option is convenient when the Job being created is intended to be run on +top of the results obtained from a previous "parent" Job. Some examples where +such a scenario is plausible include the re-calculation of a property with +slight modifications, or obtaining the same results but with a higher precision. +In both cases, the same preliminary calculations performed in the preceding +parent job can be re-utilized, thus saving computational time. -The action of selecting a parent job is explained in detail [here](actions-header-menu/select-parent.md). +The action of selecting a parent job is explained in detail [here]( +actions-header-menu/select-parent.md). ### Submit -The `Submit` option is only present for the case of Jobs with a "Pre-submission" [status](../jobs/status.md), which have been opened in Designer directly from [Explorer](../jobs/ui/explorer.md). Pressing `Submit` first saves the Job to the account-owned collection, and then directly [submits](../jobs/actions/run.md) it for execution. +The `Submit` option is only present for the case of Jobs with a "Pre-submission" +[status]({{ reference_url }}/jobs/status/), which have been opened in Designer +directly from [Explorer](../jobs/ui/explorer.md). Pressing `Submit` first saves +the Job to the account-owned collection, and then directly [submits]( +../jobs/actions/run.md) it for execution. ## 4. Save Job -The Job being currently designed can finally be saved, after all appropriate changes have been made, by clicking the "Save" button . +The Job being currently designed can finally be saved, after all appropriate +changes have been made, by clicking the "Save" or "Save & Exit" button. -When multiple materials are selected, by default (unless the workflow is multi-material in nature) a single job will be created per **each** material. The name of the resulting Job will have the material formula appended to it when more than one material is selected during its design phase. +When multiple materials are selected, by default (unless the workflow is +multi-material in nature) a single job will be created per **each** material. +The name of the resulting Job will have the material formula appended to it when +more than one material is selected during its design phase. -Once the new Job has been saved, the view is returned to the corresponding [Project page](../jobs/ui/project-page.md). Here, the new Job is now listed as a top entry under [Jobs Explorer](../jobs/ui/explorer.md) and has a "Pre-submission" [status](../jobs/status.md), indicating its readiness to be [submitted for execution](../jobs/actions/run.md). +Once the new Job has been saved, the view is returned to the corresponding +[Project page](../jobs/ui/project-page.md). Here, the new Job is now listed as a +top entry under [Jobs Explorer](../jobs/ui/explorer.md) and has a +"Pre-submission" [status]({{ reference_url }}/jobs/status/), indicating its +readiness to be [submitted for execution](../jobs/actions/run.md). diff --git a/lang/en/docs/jobs-designer/materials-tab.md b/lang/en/docs/jobs-designer/materials-tab.md index 06ac44860..6b76b3579 100644 --- a/lang/en/docs/jobs-designer/materials-tab.md +++ b/lang/en/docs/jobs-designer/materials-tab.md @@ -1,6 +1,6 @@ # Materials Tab -Opening the Materials Tab within the [Jobs Designer](overview.md) presents the user with the following interface, which can be used to inspect and review the materials [added](actions-header-menu/select-materials.md) to the [Job](../jobs/overview.md) being created. +Opening the Materials Tab within the [Jobs Designer](overview.md) presents the user with the following interface, which can be used to inspect and review the materials [added](actions-header-menu/select-materials.md) to the [Job]({{ reference_url }}/jobs/overview/) being created. ![Materials Tab](../images/jobs-designer/materials-tab.png "Materials Tab") @@ -10,7 +10,7 @@ The interface under Materials Tab largely mirrors the general [Materials Viewer] ![Materials Tab Toolbar](../images/jobs-designer/materials-tab-toolbar.png "Materials Tab Toolbar") -Another important difference of Materials Tab from [Materials Viewer](../materials/ui/viewer.md) is that **no adjustments** are allowed to the [material](../materials/overview.md) being currently inspected. +Another important difference of Materials Tab from [Materials Viewer](../materials/ui/viewer.md) is that **no adjustments** are allowed to the [material]({{ reference_url }}/materials/overview/) being currently inspected. ## 1. Pager for Switching Materials @@ -24,7 +24,7 @@ In the animation shown here, we demonstrate how to cycle through materials by us ## 2. Add / Delete Materials -Pressing the "Plus" icon allows the user to select and add new materials from the account-owned [collection](../accounts/collections.md) into the Job under creation, in an analogous fashion to the action described [here](actions-header-menu/select-materials.md). +Pressing the "Plus" icon allows the user to select and add new materials from the account-owned [collection]({{ reference_url }}/accounts/collections/) into the Job under creation, in an analogous fashion to the action described [here](actions-header-menu/select-materials.md). Conversely, the "Minus" icon initiates for the removal of the material under current inspection. Note that at least one material has to be present at all times in Jobs Designer, which prevents the deletion of the last remaining entry. diff --git a/lang/en/docs/jobs-designer/overview.md b/lang/en/docs/jobs-designer/overview.md index 8a32cdf10..d5caaa360 100644 --- a/lang/en/docs/jobs-designer/overview.md +++ b/lang/en/docs/jobs-designer/overview.md @@ -1,49 +1,72 @@ # What is Jobs Designer? -Our platform provides a convenient interface for conceiving, editing and executing simulation [Jobs](../jobs/overview.md) We refer to this interface as the Jobs Designer, and we reviewed it in detail in this section of documentation. +Our platform provides a convenient interface for conceiving, editing and +executing simulation [Jobs]({{ reference_url }}/jobs/overview/) We refer to this +interface as the Jobs Designer, and we reviewed it in detail in this section of +documentation. ## Navigating to Jobs Designer ### [From project page](../jobs/ui/project-page.md) -The Jobs Designer interface can be opened by [creating a new Job](../jobs/actions/create.md), starting from the [Project Page](../jobs/ui/project-page.md) for the project under which the user wishes to save the new Job. +The Jobs Designer interface can be opened by [creating a new Job]( +../jobs/actions/create.md), starting from the [Project Page]( +../jobs/ui/project-page.md) for the project under which the user wishes to save +the new Job. ### [From left-hand sidebar](../ui/left-sidebar.md) -Alternatively, it can be opened directly from the [left-hand sidebar menu](../ui/left-sidebar.md). In this case the new job will be associated with the [default project](../jobs/projects.md#default-project). One may review [this page](../entities-general/actions/set-default.md) for instructions on how this default choice can be changed in the [Project Explorer](../jobs/ui/projects-explorer.md). +Alternatively, it can be opened directly from the [left-hand sidebar menu]( +../ui/left-sidebar.md). In this case the new job will be associated with the +[default project]({{ reference_url }}/jobs/projects/#default-project). One may +review [this page](../entities-general/actions/set-default.md) for instructions +on how this default choice can be changed in the [Project Explorer]( +../jobs/ui/projects-explorer.md). ### [Open jobs in "pre-submission" status](../jobs/ui/explorer.md) -Any entry listed in [Jobs Explorer](../jobs/ui/explorer.md) which has a "Pre-submission" [status](../jobs/status.md) can be [opened](../entities-general/actions/open-edit.md) in Designer. This is because jobs not submitted for computation yet can be fully modified by the user (thus no limitations on edits such as those imposed by the [Viewer](../jobs/ui/viewer.md#no-adjustments-allowed)). +Any entry listed in [Jobs Explorer](../jobs/ui/explorer.md) which has a +"Pre-submission" [status]({{ reference_url }}/jobs/status/) can be [opened]( +../entities-general/actions/open-edit.md) in Designer. This is because jobs not +submitted for computation yet can be fully modified by the user (thus no +limitations on edits such as those imposed by the [Viewer]( +../jobs/ui/viewer.md#no-adjustments-allowed)). ## Components of the Interface -The creation of new simulation Jobs via Designer proceeds through three main steps, namely the definition of the [Materials](../materials/overview.md) to be investigated (1), the type of simulation [Workflow](../workflows/overview.md) to be applied upon them (2), and finally of the [computational resources](../infrastructure/resource/overview.md) to be allocated for these calculations (3). +The creation of new simulation Jobs via Designer proceeds through three main +steps, namely the definition of the +[Materials]({{ reference_url }}/materials/overview/) to be investigated (1), the +type of simulation [Workflow]({{ reference_url }}/workflows/overview/) to be +applied upon them (2), and finally of the +[computational resources]({{ resources_url }}/infrastructure/resource/overview/) +to be allocated for these calculations (3). -These three steps are each formulated under the corresponding [tab](../ui/specific/tabs-navigator.md), as highlighted in the picture below. This image also shows the location of the [header menu](header-menu.md) located at the top of the page. +These three steps are each formulated under the corresponding [tab]( +../ui/specific/tabs-navigator.md), as highlighted in the picture below. This +image also shows the location of the [header menu](header-menu.md) located at +the top of the page. -Click on each component panel within the image to access the corresponding documentation section, or alternatively refer to the links listed towards the end of the present page. +Click on each component panel within the image to access the corresponding +documentation section, or alternatively refer to the links listed towards the +end of the present page. - - - - - - - - +Jobs Designer ## [Header Menu](header-menu.md) -The components of the header menu are reviewed in [this part of the documentation](header-menu.md). +The components of the header menu are reviewed in +[this part of the documentation](header-menu.md). ## [Materials Tab](materials-tab.md) -The explanation for the Materials Tab is offered [in this page](materials-tab.md). +The explanation for the Materials Tab is offered[in this page]( +materials-tab.md). ## [Workflow Tab](workflow-tab.md) -The Workflow tab is the object of a separate discussion, which can be found [here](workflow-tab.md). +The Workflow tab is the object of a separate discussion, which can be found +[here](workflow-tab.md). ## [Compute Tab](compute-tab.md) diff --git a/lang/en/docs/jobs-designer/workflow-tab.md b/lang/en/docs/jobs-designer/workflow-tab.md index b44326452..fc7f7e5e0 100644 --- a/lang/en/docs/jobs-designer/workflow-tab.md +++ b/lang/en/docs/jobs-designer/workflow-tab.md @@ -1,12 +1,12 @@ # Workflow Tab -Navigating to the Workflow Tab in [Jobs Designer](overview.md) displays the [Workflow](../workflows/overview.md) for the [Job](../jobs/overview.md) being created. The interface is equivalent to that of the [Workflows Designer](../workflow-designer/overview.md), except for a limited set of non-adjustable parameters outlined in what follows. +Navigating to the Workflow Tab in [Jobs Designer](overview.md) displays the [Workflow]({{ reference_url }}/workflows/overview/) for the [Job]({{ reference_url }}/jobs/overview/) being created. The interface is equivalent to that of the [Workflows Designer](../workflow-designer/overview.md), except for a limited set of non-adjustable parameters outlined in what follows. ![Workflow Tab](../images/jobs-designer/workflow-tab.png "Workflow Tab") ## Non-Adjustable Settings -Some Workflow parameters can be edited under Jobs Designer, except for those pertaining to the ["Application"](../software/components.md), ["Model"](../models/overview.md) and ["Method"](../methods/overview.md) being employed as part of the computation. +Some Workflow parameters can be edited under Jobs Designer, except for those pertaining to the ["Application"]({{ reference_url }}/software/components/), ["Model"]({{ reference_url }}/models/overview/) and ["Method"]({{ reference_url }}/methods/overview/) being employed as part of the computation. These non-adjustable settings are present both under the ["Overview Tab"](../workflow-designer/subworkflow-editor/overview-tab.md) of Workflow Designer, and inside the editor of the [subworkflow units](../workflow-designer/unit-editor.md). Hovering the mouse over such settings makes it clear that the editing action is forbidden in these cases, as illustrated below. @@ -20,11 +20,11 @@ The same Workflow settings are attributed simultaneously to all Materials [added ### Single Material -If only one [Material](../materials/overview.md) is present in Jobs Designer, the input parameters for each [computational unit](../workflows/components/units.md) contained in the Workflow can be edited within the [Preview Section of the unit input editor](../workflow-designer/unit-editor/input-templates.md#preview-of-the-input-file). +If only one [Material]({{ reference_url }}/materials/overview/) is present in Jobs Designer, the input parameters for each [computational unit]({{ reference_url }}/workflows/components/units/) contained in the Workflow can be edited within the [Preview Section of the unit input editor](../workflow-designer/unit-editor/input-templates.md#preview-of-the-input-file). ### Multiple Materials -If alternatively multiple [Materials](../materials/overview.md) have been added, then the use of templating logic is recommended for changing the input file parameters simultaneously for all entries. This action should be performed from the [Workflow Designer](../workflow-designer/overview.md) itself, instead of Jobs Designer. We explain the use of templating logic for rendering simulation input files [in this page](../workflows/templating/overview.md). +If alternatively multiple [Materials]({{ reference_url }}/materials/overview/) have been added, then the use of templating logic is recommended for changing the input file parameters simultaneously for all entries. This action should be performed from the [Workflow Designer](../workflow-designer/overview.md) itself, instead of Jobs Designer. We explain the use of templating logic for rendering simulation input files [in this page]({{ reference_url }}/workflows/templating/overview/). ### See Preview for Each Material diff --git a/lang/en/docs/jobs/actions/create-delete-project.md b/lang/en/docs/jobs/actions/create-delete-project.md index a4b32406f..aca47e1bd 100644 --- a/lang/en/docs/jobs/actions/create-delete-project.md +++ b/lang/en/docs/jobs/actions/create-delete-project.md @@ -1,6 +1,6 @@ # Create New Project -New [Projects](../projects.md) can be created under the [Project Explorer](../ui/projects-explorer.md) by clicking the "Create" button accessible under the [actions toolbar](../../entities-general/ui/explorer.md#actions-toolbar). The user is presented with the following "Create New Project" dialog. +New [Projects]({{ reference_url }}/jobs/projects/) can be created under the [Project Explorer](../ui/projects-explorer.md) by clicking the "Create" button accessible under the [actions toolbar](../../entities-general/ui/explorer.md#actions-toolbar). The user is presented with the following "Create New Project" dialog. ![Create New Project](../../images/jobs/create-new-project.png "Create New Project") @@ -14,4 +14,4 @@ Below, we show how to create a new "Example Project". ## Delete Project -The action of deleting a Project cannot be performed by the user. In case of necessity, please send us a [support request](../../ui/support.md). +The action of deleting a Project cannot be performed by the user. In case of necessity, please send us a [support request]({{ interface_url }}/ui/support/). diff --git a/lang/en/docs/jobs/actions/create.md b/lang/en/docs/jobs/actions/create.md index 6d8f310a9..2579a2c2f 100644 --- a/lang/en/docs/jobs/actions/create.md +++ b/lang/en/docs/jobs/actions/create.md @@ -1,19 +1,19 @@ # Create Job -Creating new Jobs follows [the general explanation](../../entities-general/actions/create.md). The important difference is that **the create action has to originate from inside a [**Project**](../projects.md)**, by clicking on the "Create" button there. This is required to properly associate the newly created job with the project. When "Create Job" link is used in [left-hand sidebar](../../ui/left-sidebar.md) the [default project](../projects.md#default-project) +Creating new Jobs follows [the general explanation](../../entities-general/actions/create.md). The important difference is that **the create action has to originate from inside a [**Project**]({{ reference_url }}/jobs/projects/)**, by clicking on the "Create" button there. This is required to properly associate the newly created job with the project. When "Create Job" link is used in [left-hand sidebar]({{ interface_url }}/ui/left-sidebar/) the [default project]({{ reference_url }}/jobs/projects/#default-project) > Attempting to perform the Create action directly from the main [Jobs Explorer](../ui/explorer.md) will result in a warning notice. -This contrasts with other [entity types](../../entities-general/overview.md), for which this action has to originate under the main [Explorer Interface](../../entities-general/ui/explorer.md) of the entity itself. +This contrasts with other [entity types]({{ reference_url }}/entities-general/overview/), for which this action has to originate under the main [Explorer Interface](../../entities-general/ui/explorer.md) of the entity itself. The project from where the Job is created corresponds to where it will also be saved later. ## Opening of Jobs Designer -Clicking "Create" as prescribed above takes the user to the [Job designer page](../../jobs-designer/overview.md), where new simulations can be conceived from start to finish. +Clicking "Create" as prescribed above takes the user to the [Job designer page]({{ interface_url }}/jobs-designer/overview/), where new simulations can be conceived from start to finish. ## Animation -Below, we first navigate to the [Projects Explorer](../ui/projects-explorer.md) starting from [Jobs Explorer](../ui/explorer.md). We then open the first listed project, and from there we create a new Job by opening [Jobs Designer](../../jobs-designer/overview.md) with the "Create" button. +Below, we first navigate to the [Projects Explorer](../ui/projects-explorer.md) starting from [Jobs Explorer](../ui/explorer.md). We then open the first listed project, and from there we create a new Job by opening [Jobs Designer]({{ interface_url }}/jobs-designer/overview/) with the "Create" button. diff --git a/lang/en/docs/jobs/actions/overview.md b/lang/en/docs/jobs/actions/overview.md index fe4c91df5..eeeee4615 100644 --- a/lang/en/docs/jobs/actions/overview.md +++ b/lang/en/docs/jobs/actions/overview.md @@ -12,7 +12,7 @@ We explain what Purge means in the context of Jobs [in this page](purge.md). ## [Run](run.md) -Jobs can be [submitted](../status.md) to the [cluster](../../infrastructure/clusters/overview.md) for execution following [these instructions](run.md). +Jobs can be [submitted]({{ reference_url }}/jobs/status/) to the [cluster]({{ resources_url }}/infrastructure/clusters/overview/) for execution following [these instructions](run.md). ## [Terminate](terminate.md) @@ -20,8 +20,8 @@ Submitted Jobs can be terminated artificially by the user at any moment before t ## [Create / Delete Project](create-delete-project.md) -[This page](create-delete-project.md) describes how the user can create new [Projects](../projects.md). +[This page](create-delete-project.md) describes how the user can create new [Projects]({{ reference_url }}/jobs/projects/). -## [Assign Job to a Project](../projects.md) +## [Assign Job to a Project]({{ reference_url }}/jobs/projects/) -We explain how new Jobs can be assigned to [Projects](../projects.md) [here](../projects.md). +We explain how new Jobs can be assigned to [Projects]({{ reference_url }}/jobs/projects/) [here]({{ reference_url }}/jobs/projects/). diff --git a/lang/en/docs/jobs/actions/purge.md b/lang/en/docs/jobs/actions/purge.md index a19b51681..e098142d4 100644 --- a/lang/en/docs/jobs/actions/purge.md +++ b/lang/en/docs/jobs/actions/purge.md @@ -1,8 +1,8 @@ # Purge Job -After the "Purge" action files present on the [cluster hard drives](../../infrastructure/storage.md) and associated with the Job are removed to free some space against the [quota](../../accounts/quota.md). These files remain, however visible in the web application under the [Files Tab](../ui/files-tab.md) of the [Jobs Viewer](../ui/viewer.md). +After the "Purge" action files present on the [cluster hard drives]({{ resources_url }}/infrastructure/storage/) and associated with the Job are removed to free some space against the [quota]({{ reference_url }}/accounts/quota/). These files remain, however visible in the web application under the [Files Tab](../ui/files-tab.md) of the [Jobs Viewer](../ui/viewer.md). -The purge action is restricted to Jobs with a ["Finished" status](../status.md). +The purge action is restricted to Jobs with a ["Finished" status]({{ reference_url }}/jobs/status/). ## Action @@ -12,6 +12,6 @@ Alternatively, the same action can be performed under the [actions dropdown](../ ## Animation -In the example animation below, we begin by purging a Job. We then copy the command line path of one of the files listed under Jobs Viewer, and under the [Web Terminal](../../remote-connection/web-terminal.md) we finally confirm its deletion from the [cluster disk](../../infrastructure/storage.md) after pasting the file path in it. +In the example animation below, we begin by purging a Job. We then copy the command line path of one of the files listed under Jobs Viewer, and under the [Web Terminal]({{ cli_url }}/remote-connection/web-terminal/) we finally confirm its deletion from the [cluster disk]({{ resources_url }}/infrastructure/storage/) after pasting the file path in it. diff --git a/lang/en/docs/jobs/actions/run.md b/lang/en/docs/jobs/actions/run.md index 79ef9a06e..05592bc41 100644 --- a/lang/en/docs/jobs/actions/run.md +++ b/lang/en/docs/jobs/actions/run.md @@ -1,15 +1,15 @@ # Run Job -A Job listed under the [Jobs Explorer](../ui/explorer.md), which has a ["pre-submission" status](../status.md), can be submitted to the [computational infrastructure](../../infrastructure/overview.md) for execution of its computational tasks. We refer to this action as "Running" the Job. +A Job listed under the [Jobs Explorer](../ui/explorer.md), which has a ["pre-submission" status]({{ reference_url }}/jobs/status/), can be submitted to the [computational infrastructure]({{ resources_url }}/infrastructure/overview/) for execution of its computational tasks. We refer to this action as "Running" the Job. The Run action is accessible from the [actions toolbar](../../entities-general/ui/explorer.md#actions-toolbar) or [actions dropdown](../../entities-general/ui/explorer.md#actions-dropdown), under the button labelled with the "Play" icon . ## Change of Status -Running a Job changes its [status](../status.md) from "Pre-submission" to "Submission", and then eventually to "Active" once the job gets past the waiting time on the [cluster queue](../../infrastructure/resource/queues.md) and enters the execution stage. +Running a Job changes its [status]({{ reference_url }}/jobs/status/) from "Pre-submission" to "Submission", and then eventually to "Active" once the job gets past the waiting time on the [cluster queue]({{ resources_url }}/infrastructure/resource/queues/) and enters the execution stage. ## Animation -In the example below, we demonstrate how the status of a Job changes as described above when it is Run. A delay of some (5-10) seconds is incurred from the moment the Job is submitted to the moment it becomes active. Waiting times depend on the [queue category](../../infrastructure/resource/category.md) being considered. +In the example below, we demonstrate how the status of a Job changes as described above when it is Run. A delay of some (5-10) seconds is incurred from the moment the Job is submitted to the moment it becomes active. Waiting times depend on the [queue category]({{ resources_url }}/infrastructure/resource/category/) being considered. diff --git a/lang/en/docs/jobs/actions/terminate.md b/lang/en/docs/jobs/actions/terminate.md index 83cc99834..3aebff88f 100644 --- a/lang/en/docs/jobs/actions/terminate.md +++ b/lang/en/docs/jobs/actions/terminate.md @@ -1,6 +1,6 @@ # Terminate Job -Any Job which is currently running, and therefore is under the ["Active"](../status.md) status, can be terminated before its completion upon user intervention. This might be necessary in case an error was realized in providing input information to the Job, or in case of excessive consumption of computational resources. +Any Job which is currently running, and therefore is under the ["Active"]({{ reference_url }}/jobs/status/) status, can be terminated before its completion upon user intervention. This might be necessary in case an error was realized in providing input information to the Job, or in case of excessive consumption of computational resources. This preliminary interruption can be performed at any time on an Active Job through the "Stop" button located under either the [actions dropdown](../../entities-general/ui/explorer.md#actions-dropdown) or [actions toolbar](../../entities-general/ui/explorer.md#actions-toolbar) menus. diff --git a/lang/en/docs/jobs/data.md b/lang/en/docs/jobs/data.md index 90fa44f53..6a668f78a 100644 --- a/lang/en/docs/jobs/data.md +++ b/lang/en/docs/jobs/data.md @@ -1,10 +1,10 @@ # Structured Representation of Jobs -In order to organize and store the information about Jobs we employ [Exabyte Data Convention](../data-structured/overview.md), as explained in more detail [elsewhere](../entities-general/data.md) in this documentation. +In order to organize and store the information about Jobs we employ [ESSE Data Convention]({{ data_url }}/data-structured/overview/), as explained in more detail [elsewhere](../entities-general/data.md) in this documentation. ## Example representation -Below is an example JSON structured representation of a Job. It contains a single [Workflow](../workflows/overview.md) and one [Material](../materials/overview.md). +Below is an example JSON structured representation of a Job. It contains a single [Workflow]({{ reference_url }}/workflows/overview/) and one [Material]({{ reference_url }}/materials/overview/). ```json { @@ -37,6 +37,6 @@ Below is an example JSON structured representation of a Job. It contains a singl | :-------- |:----------- | | _material | Link to the identifiers of [material(s)](../materials/data.md) used in this job | | workflow | Content of the [Workflow](../workflows/data/workflows.md) employed in this job | -| compute | Computational parameters as explained in [this page](../infrastructure/compute/data.md). | -| _project | Link to the identifier of the [project](projects.md) containing the job | -| status | Indication of the current [status](status.md) of the job | +| compute | Computational parameters as explained in [this page]({{ resources_url }}/infrastructure/compute/data/). | +| _project | Link to the identifier of the [project]({{ reference_url }}/jobs/projects/) containing the job | +| status | Indication of the current [status]({{ reference_url }}/jobs/status/) of the job | diff --git a/lang/en/docs/jobs/overview.md b/lang/en/docs/jobs/overview.md index 956f0b731..c509d51d7 100644 --- a/lang/en/docs/jobs/overview.md +++ b/lang/en/docs/jobs/overview.md @@ -14,12 +14,12 @@ simplest entity that has accounting set up for, and can have one or more We implement Jobs as another [entity type](../entities-general/overview.md). As such, they have the same user interface components (with some distinct features) -as other entities, as explained [here](../entities-general/ui/overview.md). +as other entities, as explained [here]({{ interface_url }}/entities-general/ui/overview/). -## [Data](data.md) +## [Data]({{ data_url }}/jobs/data/) The data convention applied for Jobs including, for example, their database -representation is explained [in this page](data.md). +representation is explained [in this page]({{ data_url }}/jobs/data/). ## [Status](status.md) @@ -35,28 +35,24 @@ Jobs can collectively be grouped together into [Sets]( ## User Interface -### [Explorer](ui/explorer.md) +### [Explorer]({{ interface_url }}/jobs/ui/explorer/) -Jobs Explorer is another specific implementation of the [Explorer]( -../entities-general/ui/explorer.md) component and is explained [in this page]( -ui/explorer.md). +Jobs Explorer is another specific implementation of the [Explorer]({{ interface_url }}/entities-general/ui/explorer/) component and is explained [in this page]( +{{ interface_url }}/jobs/ui/explorer/). -### [Designer](../jobs-designer/overview.md) +### [Designer]({{ interface_url }}/jobs-designer/overview/) -Jobs Designer is another specific implementation of the [Designer]( -../entities-general/ui/designer.md) component described in more detail [here]( -../jobs-designer/overview.md). +Jobs Designer is another specific implementation of the [Designer]({{ interface_url }}/entities-general/ui/designer/) component described in more detail [here]({{ interface_url }}/jobs-designer/overview/). -### [Viewer](ui/viewer.md) +### [Viewer]({{ interface_url }}/jobs/ui/viewer/) -[This page](ui/viewer.md) explains how the [Viewer]( -../entities-general/ui/viewer.md) differs from Designer component in the context +[This page]({{ interface_url }}/jobs/ui/viewer/) explains how the [Viewer]({{ interface_url }}/entities-general/ui/viewer/) differs from Designer component in the context of Jobs. -## [Actions](actions/overview.md) +## [Actions]({{ interface_url }}/jobs/actions/overview/) Some actions pertain specifically to Jobs, and are introduced [in this page]( -actions/overview.md). +{{ interface_url }}/jobs/actions/overview/). ## Screenshare video @@ -64,5 +60,5 @@ Below we present a short video demonstrating how to create jobs in Mat3ra platform.
- +
diff --git a/lang/en/docs/jobs/projects.md b/lang/en/docs/jobs/projects.md index a58289b5e..59d08cc0e 100644 --- a/lang/en/docs/jobs/projects.md +++ b/lang/en/docs/jobs/projects.md @@ -8,7 +8,7 @@ Projects can only be present at the top-level, with no possibility of creating n > Also referred to as "Accounting Slug". -The [Slug](../entities-general/data.md#Slug-Representation) offers a computer-friendly representation of the name of the Project. This is relevant in the context of [Account Charges](../accounts/ui/charges-payments.md) and is used to identify a project inside each charge entry. +The [Slug]({{ data_url }}/entities-general/data/#Slug-Representation) offers a computer-friendly representation of the name of the Project. This is relevant in the context of [Account Charges]({{ interface_url }}/accounts/ui/charges-payments/) and is used to identify a project inside each charge entry. ## Accounting @@ -20,45 +20,41 @@ There are two ways to track charges on each project, as explained in what follow #### From Charges Page -We describe how to access and navigate the main "Charges and Payments" page [here](../accounts/ui/charges-payments.md). +We describe how to access and navigate the main "Charges and Payments" page [here]({{ interface_url }}/accounts/ui/charges-payments/). #### In Command Line -Alternatively, the charges incurred as part of each Project can be inspected directly on the Command Line Interface, as outlined [in this page](../cli/overview.md). +Alternatively, the charges incurred as part of each Project can be inspected directly on the Command Line Interface, as outlined [in this page]({{ cli_url }}/cli/overview/). ## CLI Path -The path of the Project inside the [cluster infrastructure](../infrastructure/overview.md) is formed utilizing the *slug* field explained above. +The path of the Project inside the [cluster infrastructure]({{ resources_url }}/infrastructure/overview/) is formed utilizing the *slug* field explained above. -Question marks "???" might be present within this path instead of the actual cluster number label (eg. "001" for "cluster-001"), because different [clusters](../infrastructure/clusters/overview.md) are employed for executing the Project's [Jobs](overview.md) with each cluster having a dedicated directory for the project. See explanation in [directory structure](../data-on-disk/directories.md) for more information on this. +Question marks "???" might be present within this path instead of the actual cluster number label (eg. "001" for "cluster-001"), because different [clusters]({{ resources_url }}/infrastructure/clusters/overview/) are employed for executing the Project's [Jobs](overview.md) with each cluster having a dedicated directory for the project. See explanation in [directory structure]({{ resources_url }}/data-on-disk/directories/) for more information on this. ## Status Similarly to the [status](status.md) of individual Jobs, each Project also has a general status assigned to it, according to the following conventions. - Active: at least one job is present with an [Active](status.md#Active) status inside the Project. -- Stand-by: at least one job in the Project is pending execution, but has been submitted to the [queue](../infrastructure/resource/queues.md) already ([Submitted](status.md#Submitted) status). +- Stand-by: at least one job in the Project is pending execution, but has been submitted to the [queue]({{ resources_url }}/infrastructure/resource/queues/) already ([Submitted](status.md#Submitted) status). - Idle: all other possibilities, whereby all jobs contained in the project have statuses other than Active and Submitted. -The Project Status is indicated in [Project Explorer](ui/projects-explorer.md#status), under the corresponding column. +The Project Status is indicated in [Project Explorer]({{ interface_url }}/jobs/ui/projects-explorer/#status), under the corresponding column. ## Default Project -Each new Account is initialized with a default project named "Default". It is initially set to be [shared publicly](../collaboration/sharing/access-levels.md) with all platform users. Higher levels of privacy for this and all [subsequently created Projects](actions/create-delete-project.md) can be set when an appropriate [service level](../pricing/service-levels.md) is attributed to the account. - -## "External" Project - -Jobs created through [External Uploads](../external/overview.md) are placed into the corresponding project. +Each new Account is initialized with a default project named "Default". It is initially set to be [shared publicly]({{ interface_url }}/collaboration/sharing/access-levels/) with all platform users. Higher levels of privacy for this and all [subsequently created Projects]({{ interface_url }}/jobs/actions/create-delete-project/) can be set when an appropriate [service level]({{ guide_url }}/pricing/service-levels/) is attributed to the account. ## Project Page -Each Project has its own dedicated page, listing all the contained Jobs among other properties. We review Projects Pages [here](ui/project-page.md). +Each Project has its own dedicated page, listing all the contained Jobs among other properties. We review Projects Pages [here]({{ interface_url }}/jobs/ui/project-page/). ## Projects Explorer -The list of projects created under an account can be viewed under the [Projects Explorer](ui/projects-explorer.md) interface. +The list of projects created under an account can be viewed under the [Projects Explorer]({{ interface_url }}/jobs/ui/projects-explorer/) interface. ## Create / Delete -The procedure for creating or deleting Projects under [Explorer](ui/projects-explorer.md) is explained [separately](actions/create-delete-project.md). +The procedure for creating or deleting Projects under [Explorer]({{ interface_url }}/jobs/ui/projects-explorer/) is explained [separately]({{ interface_url }}/jobs/actions/create-delete-project/). diff --git a/lang/en/docs/jobs/status.md b/lang/en/docs/jobs/status.md index cf20420b3..c9e99539b 100644 --- a/lang/en/docs/jobs/status.md +++ b/lang/en/docs/jobs/status.md @@ -1,15 +1,15 @@ # Job Status Indicators -Jobs listed under the [Explorer](ui/explorer.md) can be in one of the following possible statuses, appearing under its corresponding letter/color badge. +Jobs listed under the [Explorer]({{ interface_url }}/jobs/ui/explorer/) can be in one of the following possible statuses, appearing under its corresponding letter/color badge. !!!note "Note: explanation of clusters-related terms" - The user is referred to [this page](../infrastructure/compute/overview.md) for instructions on how to operate the computing [clusters](../infrastructure/clusters/overview.md) offered on our platform. The concept of [Queue](../infrastructure/resource/queues.md) on the cluster is also explained in its respective page. + The user is referred to [this page]({{ resources_url }}/infrastructure/compute/overview/) for instructions on how to operate the computing [clusters]({{ resources_url }}/infrastructure/clusters/overview/) offered on our platform. The concept of [Queue]({{ resources_url }}/infrastructure/resource/queues/) on the cluster is also explained in its respective page. ## Pre-submission Badge: P -"Pre-submission" status indicates that the Job has been created as an entry in [Explorer](ui/explorer.md), but it has not been submitted to the [queue](../infrastructure/resource/queues.md) of the cluster yet. It can still be edited by [opening](../entities-general/actions/open-edit.md) it under [Designer](../jobs-designer/overview.md). +"Pre-submission" status indicates that the Job has been created as an entry in [Explorer]({{ interface_url }}/jobs/ui/explorer/), but it has not been submitted to the [queue]({{ resources_url }}/infrastructure/resource/queues/) of the cluster yet. It can still be edited by [opening]({{ interface_url }}/entities-general/actions/open-edit/) it under [Designer]({{ interface_url }}/jobs-designer/overview/). ## Submitted diff --git a/lang/en/docs/jobs/ui/explorer.md b/lang/en/docs/jobs/ui/explorer.md index 1e945d4ce..00f3f4fd5 100644 --- a/lang/en/docs/jobs/ui/explorer.md +++ b/lang/en/docs/jobs/ui/explorer.md @@ -8,7 +8,7 @@ The image below shows how Jobs Explorer appears under typical circumstances. The ## Status Indicators -An important property present in the items list is the [Status indicator](../status.md) of each listed Job, under the "Status" column highlighted in the above image. +An important property present in the items list is the [Status indicator]({{ reference_url }}/jobs/status/) of each listed Job, under the "Status" column highlighted in the above image. ## Other Specific Properties @@ -18,16 +18,16 @@ Additional Job-specific columns that can be listed in Explorer include those tic ### Application -This option displays the [applications](../../software-directory/overview.md) employed within the [workflow](../../workflows/overview.md) used inside the Job, including their version numbers. +This option displays the [applications]({{ reference_url }}/software-directory/overview/) employed within the [workflow]({{ reference_url }}/workflows/overview/) used inside the Job, including their version numbers. ### Cluster - Queue & Cores -These are the [name of the cluster](../../infrastructure/clusters/overview.md) and the compute [queue](../../infrastructure/resource/queues.md) therein where the Job is executed. The number of computational nodes and CPU cores are also indicated. +These are the [name of the cluster]({{ resources_url }}/infrastructure/clusters/overview/) and the compute [queue]({{ resources_url }}/infrastructure/resource/queues/) therein where the Job is executed. The number of computational nodes and CPU cores are also indicated. ### Run & Wait Time -This corresponds to the amount of time that the Job took to finish, and for how long it had to wait in the [queue](../../infrastructure/resource/queues.md) of the cluster before being executed. +This corresponds to the amount of time that the Job took to finish, and for how long it had to wait in the [queue]({{ resources_url }}/infrastructure/resource/queues/) of the cluster before being executed. ### Project -The name of the [Project](../projects.md) containing the Job is displayed under this column. +The name of the [Project]({{ reference_url }}/jobs/projects/) containing the Job is displayed under this column. diff --git a/lang/en/docs/jobs/ui/files-tab.md b/lang/en/docs/jobs/ui/files-tab.md index 763ccaadf..079d72245 100644 --- a/lang/en/docs/jobs/ui/files-tab.md +++ b/lang/en/docs/jobs/ui/files-tab.md @@ -8,6 +8,6 @@ A review of the [actions](../../data-in-objectstorage/actions/overview.md) and [ ## Example Appearance -An example of appearance of the Files tab is portrayed below, for a bandstructure run performed using the [VASP](../../software-directory/modeling/vasp/overview.md) code. The user is referred to the [code-specific documentation](../../software-directory/modeling/vasp/overview.md) for an explanation of the contents of the files displayed in this example. +An example of appearance of the Files tab is portrayed below, for a bandstructure run performed using the [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) code. The user is referred to the [code-specific documentation]({{ reference_url }}/software-directory/modeling/vasp/overview/) for an explanation of the contents of the files displayed in this example. ![Files Tab](../../images/jobs/files-tab.png "Files Tab") diff --git a/lang/en/docs/jobs/ui/project-page.md b/lang/en/docs/jobs/ui/project-page.md index 89597648c..2ea9248c0 100644 --- a/lang/en/docs/jobs/ui/project-page.md +++ b/lang/en/docs/jobs/ui/project-page.md @@ -1,6 +1,6 @@ # Projects Page -The page dedicated to each [Project](../projects.md) contains the information about it and is comprised of two [main tabs](../../ui/specific/tabs-navigator.md), as highlighted below. +The page dedicated to each [Project]({{ reference_url }}/jobs/projects/) contains the information about it and is comprised of two [main tabs]({{ interface_url }}/ui/specific/tabs-navigator/), as highlighted below. ![Projects Page](../../images/jobs/projects-page.png "Projects Page") diff --git a/lang/en/docs/jobs/ui/projects-explorer.md b/lang/en/docs/jobs/ui/projects-explorer.md index fa13067bf..695f9b2be 100644 --- a/lang/en/docs/jobs/ui/projects-explorer.md +++ b/lang/en/docs/jobs/ui/projects-explorer.md @@ -1,6 +1,6 @@ # Projects Explorer -The list of all [Projects](../projects.md) created under the Account is displayed in the dedicated Explorer, which has some distinct features from the [general case](../../entities-general/ui/explorer.md). +The list of all [Projects]({{ reference_url }}/jobs/projects/) created under the Account is displayed in the dedicated Explorer, which has some distinct features from the [general case](../../entities-general/ui/explorer.md). An example of appearance of Projects Explorer is shown below. The highlighted columns in the items list are the Project-specific ones. They are reviewed in turn in what follows. @@ -10,15 +10,15 @@ An example of appearance of Projects Explorer is shown below. The highlighted co ### Number of Jobs -The total number of Jobs contained in each Project entry is indicated under the corresponding column, together with the subset of [active](../status.md) jobs. +The total number of Jobs contained in each Project entry is indicated under the corresponding column, together with the subset of [active]({{ reference_url }}/jobs/status/) jobs. ### Accounting Slug / CLI Path -These project features are reviewed [here](../projects.md#slug). +These project features are reviewed [here]({{ reference_url }}/jobs/projects/#slug). ### Status -The status of the Project can have any of the badges listed [in this section](../projects.md#status). +The status of the Project can have any of the badges listed [in this section]({{ reference_url }}/jobs/projects/#status). ## Open Projects Page diff --git a/lang/en/docs/jobs/ui/results-tab.md b/lang/en/docs/jobs/ui/results-tab.md index 189eafa65..6af81a0cb 100644 --- a/lang/en/docs/jobs/ui/results-tab.md +++ b/lang/en/docs/jobs/ui/results-tab.md @@ -4,11 +4,11 @@ The "Results" tab displays the results of the job's computational tasks. They ar ## Panels -The results for each computational [unit](../../workflow-designer/unit-editor.md) contained across the [workflow](../../workflow-designer/overview.md) operations of the Job are displayed in separate **panels**. +The results for each computational [unit]({{ interface_url }}/workflow-designer/unit-editor/) contained across the [workflow]({{ interface_url }}/workflow-designer/overview/) operations of the Job are displayed in separate **panels**. ### Naming Convention -Panels are named according to the format convention "Subworkflow Name - Unit Name". The name of the [application](../../software-directory/overview.md) implemented in the current unit is also shown directly below. +Panels are named according to the format convention "Subworkflow Name - Unit Name". The name of the [application]({{ reference_url }}/software-directory/overview/) implemented in the current unit is also shown directly below. ### Collapse / Expand @@ -16,7 +16,7 @@ The option to collapse or expand a panel is offered at its top-right corner. ## Materials Properties -The panels contain the results for the computation of the [materials properties](../../properties/overview.md) that were selected at the moment of the [creation of the subworkflow](../../workflow-designer/subworkflow-editor/detailed-view.md), or subsequently adjusted during the [job design](../../jobs-designer/overview.md) stage. +The panels contain the results for the computation of the [materials properties]({{ reference_url }}/properties/overview/) that were selected at the moment of the [creation of the subworkflow]({{ interface_url }}/workflow-designer/subworkflow-editor/detailed-view/), or subsequently adjusted during the [job design]({{ interface_url }}/jobs-designer/overview/) stage. The manner in which these properties are displayed under the corresponding panels is explained in a [separate section](../../properties/ui/viewer.md) of this documentation. diff --git a/lang/en/docs/jobs/ui/viewer.md b/lang/en/docs/jobs/ui/viewer.md index 2a344d0b8..b91323b2b 100644 --- a/lang/en/docs/jobs/ui/viewer.md +++ b/lang/en/docs/jobs/ui/viewer.md @@ -1,13 +1,13 @@ # Jobs Viewer Interface -In order to inspect the content of a Job, the user can [open it](../../entities-general/actions/open-edit.md) from [Jobs Explorer](explorer.md). This action opens the Job under the corresponding Viewer, except for the case of Jobs in the [pre-submitted status](../status.md) where the [Designer](../../jobs-designer/overview.md) is opened instead. +In order to inspect the content of a Job, the user can [open it](../../entities-general/actions/open-edit.md) from [Jobs Explorer](explorer.md). This action opens the Job under the corresponding Viewer, except for the case of Jobs in the [pre-submitted status]({{ reference_url }}/jobs/status/) where the [Designer]({{ interface_url }}/jobs-designer/overview/) is opened instead. -The image below shows how the Viewer contains two extra highlighted tabs, in addition to the three main tabs of [Designer](../../jobs-designer/overview.md). They are labelled [**"Results"**](results-tab.md) and [**"Files"**](files-tab.md), and are reviewed separately in their respective pages. The name of the Job and that of the containing [Project](../projects.md) is also indicated at the top-left corner of the page. +The image below shows how the Viewer contains two extra highlighted tabs, in addition to the three main tabs of [Designer]({{ interface_url }}/jobs-designer/overview/). They are labelled [**"Results"**](results-tab.md) and [**"Files"**](files-tab.md), and are reviewed separately in their respective pages. The name of the Job and that of the containing [Project]({{ reference_url }}/jobs/projects/) is also indicated at the top-left corner of the page. ![Extra Jobs Viewer](../../images/jobs/extra-jobs-viewer.png "Extra Jobs Viewer") ## No Adjustments Allowed -Under Jobs Viewer, it is impossible to make **any** kind of adjustments to either [Materials](../../jobs-designer/materials-tab.md), [Workflow](../../jobs-designer/workflow-tab.md) or [Compute](../../jobs-designer/compute-tab.md) settings contained in their respective tabs. This is in contrast to [Designer](../../jobs-designer/overview.md). +Under Jobs Viewer, it is impossible to make **any** kind of adjustments to either [Materials]({{ interface_url }}/jobs-designer/materials-tab/), [Workflow]({{ interface_url }}/jobs-designer/workflow-tab/) or [Compute]({{ interface_url }}/jobs-designer/compute-tab/) settings contained in their respective tabs. This is in contrast to [Designer]({{ interface_url }}/jobs-designer/overview/). The only change which can be made to the Job under Viewer is the insertion of descriptive [metadata](../../entities-general/actions/metadata.md), under the corresponding button at the top-right corner of the interface. diff --git a/lang/en/docs/jupyterlite/accessing-jupyterlite.md b/lang/en/docs/jupyterlite/accessing-jupyterlite.md index 39c66802c..4e05541ad 100644 --- a/lang/en/docs/jupyterlite/accessing-jupyterlite.md +++ b/lang/en/docs/jupyterlite/accessing-jupyterlite.md @@ -21,7 +21,7 @@ To access JupyterLite directly, navigate to the following URL: https://jupyterlite.mat3ra.com/lab/index.html ``` -To access the Introduction notebook summarizing the functionality available in [mat3ra-made](https://github.com/Exabyte-io/made): +To access the Introduction notebook summarizing the functionality available in [mat3ra-made](https://github.com/mat3ra/made): ``` https://jupyterlite.mat3ra.com/lab/tree?path=made/Introduction.ipynb @@ -33,5 +33,5 @@ In the below tutorial, we present how we can use JupyterLite session in Mat3ra platform to postprocess or analyze data.
- +
diff --git a/lang/en/docs/jupyterlite/authentication.md b/lang/en/docs/jupyterlite/authentication.md new file mode 100644 index 000000000..773a2acba --- /dev/null +++ b/lang/en/docs/jupyterlite/authentication.md @@ -0,0 +1,169 @@ +# Authentication in JupyterLite + +## Overview + +When working with JupyterLite notebooks that interact with the Mat3ra platform API, you need to authenticate to access your account data, materials, and computational resources. The authentication method depends on how you're accessing JupyterLite. + +## Authentication Methods + +### 1. JupyterLite from Platform + +When you launch JupyterLite from the Platform using the JupyterLite Session, authentication happens automatically. The platform passes your credentials through the `data_from_host` variable, which includes: + +- Account ID +- Authentication token +- Organization ID +- Available clusters + +No additional authentication steps are required in this mode. + +### 2. Standalone Notebooks + +When running notebooks outside the Platform (e.g., local IDE, jupyterlite.mat3ra.com), you will be authenticated using the OIDC (OpenID Connect) device flow. + +## OIDC Device Flow Authentication + +### Step-by-Step Authentication Process + +#### Step 1: Run Authentication Code + +In your notebook, import and run the authentication function: + +```python +from utils.auth import authenticate + +await authenticate() +``` + +The process of authentication in JupyterLite notebook: + +Authentication section in JupyterLite notebook + +#### Step 2: View User Code in Notebook + +The notebook will display an "Authentication Required" message with a unique user code: + +![Authentication Code in Notebook](../images/jupyterlite/auth-notebook-code.webp "User code displayed in notebook") + +The code (e.g., "RTJW-LJDN") is displayed prominently. Keep this visible as you'll need to verify it in the browser. + +#### Step 3: Browser Opens Automatically + +A new browser window or tab will open automatically, taking you to the Mat3ra authentication page: + +![Device Confirmation Page](../images/jupyterlite/auth-browser-confirm.webp "Browser confirmation page") + +This page shows: +- The application requesting access ("Mat3ra CLI Device Flow") +- Your account information +- The permissions being requested +- Options to CANCEL or CONFIRM + +#### Step 4: Sign In (If Needed) + +If you're not already signed in, you'll see a sign-in page: + +![Sign In Page](../images/jupyterlite/auth-browser-signin.webp "Sign in confirmation") + +Confirm that you want to sign in to Mat3ra CLI Device Flow with your account. + +#### Step 5: Confirm Device + +Click the **CONFIRM** button to authorize the notebook to access your account. + +#### Step 6: Success Confirmation + +After confirming, you'll see a success message: + +![Authentication Success](../images/jupyterlite/auth-success.webp "Authentication successful") + +You can now close this browser window and return to your notebook. + +#### Step 7: Continue in Notebook + +Back in your notebook, the authentication process completes automatically. Your access tokens are now stored in environment variables, and you can proceed with API calls. + +### Complete Code Example + +Here's a complete example showing authentication and basic API usage: + +```python +# 1. Authenticate +from utils.auth import authenticate +await authenticate() + +# 2. Initialize API client +from mat3ra.api_client import APIClient +client = APIClient.authenticate() + +# 3. Use the API +projects = client.projects.list({"isDefault": True}) +print(f"Found {len(projects)} project(s)") +``` + + +## Troubleshooting + +### Browser Window Doesn't Open + +If the browser window doesn't open automatically: + +1. Check if popup blockers are preventing the window from opening +2. Look for the verification URL in the notebook output +3. Manually copy and paste the URL into your browser + +### "Authorization Pending" Message + +If the notebook keeps showing "authorization pending": + +1. Make sure you clicked CONFIRM in the browser +2. Check that you're signed in to the correct account +3. Verify the user code matches between notebook and browser + + +## Technical Details + +### Token Storage + +Authentication tokens are stored in environment variables: + +- `OIDC_ACCESS_TOKEN`: Used for API requests +- `OIDC_REFRESH_TOKEN`: Used to obtain new access tokens when they expire + +These tokens persist for the duration of your notebook session but are not saved to disk. + +### Security Considerations + +- Tokens are session-specific and expire after a period of inactivity +- Never share your authentication tokens or commit them to version control +- Always authenticate in a secure environment +- The device flow ensures your password is never exposed to the notebook + +### Token Expiration + +Access tokens expire after 30 minutes. In that case, you need to restart the kernel and Run All Cells again (save and use ids for materials, jobs or other entities to avoid losing references). + +Or adjust the `authenticate` function to force re-authentication upon re-running of that cell: + +```python +await authenticate(force=True) +``` + + +### API Client Configuration + +The authentication process automatically configures the API client with: + +- Base URL for the Mat3ra API +- OIDC endpoint URLs +- Client ID and scope +- Token refresh mechanism + + +## Related Documentation + +- [Accessing JupyterLite](accessing-jupyterlite.md) - How to launch JupyterLite +- [Data Exchange](data-exchange.md) - Working with materials data +- [REST API Authentication]({{ developers_url }}/rest-api/authentication/) - Alternative authentication for direct API calls +- [API Client]({{ developers_url }}/rest-api/api-client/) - Using the Python API client + diff --git a/lang/en/docs/jupyterlite/data-exchange.md b/lang/en/docs/jupyterlite/data-exchange.md index 69671138e..eb5c0b3b2 100644 --- a/lang/en/docs/jupyterlite/data-exchange.md +++ b/lang/en/docs/jupyterlite/data-exchange.md @@ -2,7 +2,7 @@ ## Overview -JupyterLite environment can exchange data (1) either directly with the platform or (2) with its sub-parts, such as the [Materials Designer](../materials-designer/overview.md). +JupyterLite environment can exchange data (1) either directly with the platform or (2) with its sub-parts, such as the [Materials Designer]({{ interface_url }}/materials-designer/overview/). ## Get data inside JupyterLite @@ -11,7 +11,7 @@ JupyterLite environment can exchange data (1) either directly with the platform This `data_from_host` variable is updated by JS extension in response to changes in material selection for Materials Designer, or loads API keys when launched from the [Platform top menu](accessing-jupyterlite.md/#2-mat3ra-platform). -For example, to work with materials from [Materials Designer](../materials-designer/overview.md), the user would request to write them into `materials_in` variable using the following code snippet: +For example, to work with materials from [Materials Designer]({{ interface_url }}/materials-designer/overview/), the user would request to write them into `materials_in` variable using the following code snippet: ```python from utils.jupyterlite import get_data diff --git a/lang/en/docs/jupyterlite/dependencies-installation.md b/lang/en/docs/jupyterlite/dependencies-installation.md index ee5cc2360..e2521526c 100644 --- a/lang/en/docs/jupyterlite/dependencies-installation.md +++ b/lang/en/docs/jupyterlite/dependencies-installation.md @@ -4,7 +4,7 @@ The `micropip` package installs dependencies in [Pyodide](./pyodide.md) kernel used in JupyterLite notebooks. -For relative imports to work in provided [api-examples](../rest-api/api-examples.md) notebooks, one needs to install the `mat3ra-api-examples` package in the beginning of the notebook: +For relative imports to work in provided [api-examples]({{ developers_url }}/rest-api/api-examples/) notebooks, one needs to install the `mat3ra-api-examples` package in the beginning of the notebook: ```python import micropip @@ -21,7 +21,7 @@ from utils.jupyterlite import get_materials ## Listing notebook dependencies in `config.yaml` Some of the necessary packages are compiled into pure Python wheels and provided inside the `mat3ra-api-examples` package. In top-level `packages` folder. -The dependencies for each notebook and default ones are listed in the [`config.yml` file]("https://github.com/Exabyte-io/api-examples/blob/5e0109589da981b60fec1c1cfcae1977abbbd8ec/config.yml") on the top-level. +The dependencies for each notebook and default ones are listed in the [`config.yml` file]("https://github.com/mat3ra/api-examples/blob/5e0109589da981b60fec1c1cfcae1977abbbd8ec/config.yml") on the top-level. To install packages required for the notebook, one can use `install_packages` function from `utils.jupyterlite` module and provide the name of the notebook and the relative path to the `config.yml` file: diff --git a/lang/en/docs/jupyterlite/overview.md b/lang/en/docs/jupyterlite/overview.md index 47fa5a6ab..3f2dd72bc 100644 --- a/lang/en/docs/jupyterlite/overview.md +++ b/lang/en/docs/jupyterlite/overview.md @@ -24,6 +24,9 @@ Introduces Pyodide -- kernel used in JupyterLite to run Python code in the brows ## [Accessing JupyterLite](./accessing-jupyterlite.md) Provides a detailed guide on how to access JupyterLite via the **Materials Designer**, **Mat3ra Platform**, or a direct URL, with accompanying visuals. +## [Authentication](./authentication.md) +Explains how to authenticate in Jupyter notebooks, with step-by-step instructions for the browser-based authentication process. + ## [Dependencies Installation and Imports](./dependencies-installation.md) Explains how to install dependencies in Pyodide using the `micropip` package, with code snippets for installing the `numpy` package and the `mat3ra-api-examples` package. @@ -34,9 +37,9 @@ Explains how to transfer data between JupyterLite and Materials Designer, includ ## [File Storage and Synchronization](./file-storage-synchronization.md) Describes how JupyterLite stores files locally in the browser, discusses synchronization limitations across devices, and outlines steps for clearing the local cache when updates are available. -## [Common Actions](./common-actions) +## [Common Actions](./common-actions.md) Covers the available actions in JupyterLite, including how to open, run, upload, and copy notebooks, with instructions on executing these actions. ## Links -- [JupyterLite Documentation](https://jupyterlite.readthedocs.io/en/stable/) \ No newline at end of file +- [JupyterLite Documentation](https://jupyterlite.readthedocs.io/en/stable/) diff --git a/lang/en/docs/materials-designer/3d-editor/editor-actions/adjust-cell-parameters.md b/lang/en/docs/materials-designer/3d-editor/editor-actions/adjust-cell-parameters.md index 568e4062a..373c58b05 100644 --- a/lang/en/docs/materials-designer/3d-editor/editor-actions/adjust-cell-parameters.md +++ b/lang/en/docs/materials-designer/3d-editor/editor-actions/adjust-cell-parameters.md @@ -2,7 +2,7 @@ ## Accessing the Information on the Lattice Vectors -Adjusting the unit cell parameters is achieved by first selecting the "Cell" component entry within the ["Scene" sidebar list](../edit.md#3.-scene) displayed towards the right-hand side of the [3D editor interface](../edit.md). The existing [lattice vectors](../../../properties-directory/structural/lattice.md) describing the geometry of the unit cell under consideration can be inspected under the "Geometry" Tab in the lower panel of the "Scene" sidebar. +Adjusting the unit cell parameters is achieved by first selecting the "Cell" component entry within the ["Scene" sidebar list](../edit.md#3.-scene) displayed towards the right-hand side of the [3D editor interface](../edit.md). The existing [lattice vectors]({{ reference_url }}/properties-directory/structural/lattice/) describing the geometry of the unit cell under consideration can be inspected under the "Geometry" Tab in the lower panel of the "Scene" sidebar. ## Editing Lattice Vectors diff --git a/lang/en/docs/materials-designer/header-menu/advanced/boundary-conditions.md b/lang/en/docs/materials-designer/header-menu/advanced/boundary-conditions.md index 3f5933316..8b6cfadec 100644 --- a/lang/en/docs/materials-designer/header-menu/advanced/boundary-conditions.md +++ b/lang/en/docs/materials-designer/header-menu/advanced/boundary-conditions.md @@ -1,6 +1,6 @@ # Boundary Conditions -Boundary conditions specify how the system under investigation (referred to as "Slab" for the case of interfaces) can interact or is related to its surroundings. Such customization of boundary conditions can be especially resourceful in the case of [Effective Screening Medium](../../../models/auxiliary-concepts/esm.md) calculations. +Boundary conditions specify how the system under investigation (referred to as "Slab" for the case of interfaces) can interact or is related to its surroundings. Such customization of boundary conditions can be especially resourceful in the case of [Effective Screening Medium]({{ reference_url }}/models/auxiliary-concepts/esm/) calculations. ## Set Boundary Conditions Dialog @@ -10,7 +10,7 @@ Open the "Set Boundary Conditions" dialog via the ["Advanced" menu](../advanced. ## Boundary Conditions Types -The dialog features a drop down menu on the left, where the **type** of boundary condition can be chosen and applied perpendicularly to the central slab under consideration. We offer the possibility to choose between the following distinct types, which are also reviewed in Ref. [7] cited [in this page](../../../software-directory/modeling/quantum-espresso/components.md): +The dialog features a drop down menu on the left, where the **type** of boundary condition can be chosen and applied perpendicularly to the central slab under consideration. We offer the possibility to choose between the following distinct types, which are also reviewed in Ref. [7] cited [in this page]({{ reference_url }}/software-directory/modeling/quantum-espresso/components/): - Periodic Boundary Conditions (pbc): the system is completely surrounded by identical replicas of itself in all three dimensions [^1]. - Vacuum-Slab-Vacuum (bc1): immerse the slab between two semi-infinite vacuum regions. diff --git a/lang/en/docs/materials-designer/header-menu/advanced/interpolated-set.md b/lang/en/docs/materials-designer/header-menu/advanced/interpolated-set.md index 69b25f9bc..a75e67831 100644 --- a/lang/en/docs/materials-designer/header-menu/advanced/interpolated-set.md +++ b/lang/en/docs/materials-designer/header-menu/advanced/interpolated-set.md @@ -4,12 +4,12 @@ Interpolated sets allows to represent atomic movements between an **initial** an Multiple intermediate (or "interpolated") structures, referred to as **images**, of the system being considered need to be generated by interpolation in between these initial and final configurations, by varying linearly the one-dimensional **reaction "coordinate"** (e.g. the atomic positions) from its initial to final value. -This set of initial and final structures together with images [ordered](../../../entities-general/sets.md) in a particular manner constitutes the interpolated set for the chemical reaction. +This set of initial and final structures together with images [ordered]({{ reference_url }}/entities-general/sets/) in a particular manner constitutes the interpolated set for the chemical reaction. ## Example Usage -**Interpolated Sets** are used for the calculation of the energy profile and activation barrier for the chemical reactions via the [Nudged Elastic Bands (NEB) method](../../../tutorials/dft/chemical/reaction-profile-qe.md). +**Interpolated Sets** are used for the calculation of the energy profile and activation barrier for the chemical reactions via the [Nudged Elastic Bands (NEB) method]({{ guide_url }}/tutorials/dft/chemical/reaction-profile-qe/). ## Animation diff --git a/lang/en/docs/materials-designer/header-menu/advanced/jupyterlite-dialog.md b/lang/en/docs/materials-designer/header-menu/advanced/jupyterlite-dialog.md index f7b5efeda..9a23dc818 100644 --- a/lang/en/docs/materials-designer/header-menu/advanced/jupyterlite-dialog.md +++ b/lang/en/docs/materials-designer/header-menu/advanced/jupyterlite-dialog.md @@ -30,7 +30,7 @@ To apply a transformation, open the notebook containing the desired transformati ### Access Materials in JupyterLite -Learn how to access materials inside the JupyterLite environment launched from Materials Designer in [Introduction to JupyterLite](../../../jupyterlite/overview.md). +Learn how to access materials inside the JupyterLite environment launched from Materials Designer in [Introduction to JupyterLite]({{ interface_url }}/jupyterlite/overview/). ## Submit Results diff --git a/lang/en/docs/materials-designer/header-menu/edit.md b/lang/en/docs/materials-designer/header-menu/edit.md index eb4984419..55ee2e58c 100644 --- a/lang/en/docs/materials-designer/header-menu/edit.md +++ b/lang/en/docs/materials-designer/header-menu/edit.md @@ -33,4 +33,4 @@ Additionally, the user can also `Clone` GitHub. +1. Standata repository on GitHub. diff --git a/lang/en/docs/materials-designer/source-editor/basis.md b/lang/en/docs/materials-designer/source-editor/basis.md index c983cef89..f35011a0a 100644 --- a/lang/en/docs/materials-designer/source-editor/basis.md +++ b/lang/en/docs/materials-designer/source-editor/basis.md @@ -1,6 +1,6 @@ # Setting the Crystal Basis -The [atomic basis](../../properties-directory/structural/basis.md) of a Material's crystal structure can be edited and set by expanding the "Crystal Basis" section in the central panel of the Materials Designer interface. The appearance of the "Crystal Basis" editor within the wider interface is shown in the figure below: +The [atomic basis]({{ reference_url }}/properties-directory/structural/basis/) of a Material's crystal structure can be edited and set by expanding the "Crystal Basis" section in the central panel of the Materials Designer interface. The appearance of the "Crystal Basis" editor within the wider interface is shown in the figure below: ![Setting the Crystal Basis](../../images/materials-designer/crystal-basis.png "Setting the Crystal Basis") diff --git a/lang/en/docs/materials-designer/source-editor/lattice.md b/lang/en/docs/materials-designer/source-editor/lattice.md index 193521498..a0c5fbec0 100644 --- a/lang/en/docs/materials-designer/source-editor/lattice.md +++ b/lang/en/docs/materials-designer/source-editor/lattice.md @@ -1,6 +1,6 @@ # Crystal Lattice -Every crystal structure has an underlying Bravais lattice. For more theoretical background, please refer to [this page](../../properties-directory/structural/lattice.md). +Every crystal structure has an underlying Bravais lattice. For more theoretical background, please refer to [this page]({{ reference_url }}/properties-directory/structural/lattice/). ## Opening the Crystal Lattice editor diff --git a/lang/en/docs/materials/actions/advanced-search.md b/lang/en/docs/materials/actions/advanced-search.md index 90db5ff57..8229b8926 100644 --- a/lang/en/docs/materials/actions/advanced-search.md +++ b/lang/en/docs/materials/actions/advanced-search.md @@ -12,24 +12,24 @@ The following materials keywords are available. ### Generic Keywords -Generic keywords present for all materials are described below. These can also be referred to as [descriptive properties](../../data-structured/overview.md#by-relation-to-workflow). +Generic keywords present for all materials are described below. These can also be referred to as [descriptive properties]({{ data_url }}/data-structured/overview/#by-relation-to-workflow). | Keyword | Description | | :-------- |:----------- | | name | Name of the Material | | formula | Chemical formula, for example "CaTiO3" | -| latticeType | The [Bravais lattice type](../../materials-designer/source-editor/lattice.md) of the crystal structure under consideration | -| model | The [theoretical model](../../models/overview.md) employed to calculate the materials properties | -| method | The [computational method](../../methods/overview.md) implementing the above model | +| latticeType | The [Bravais lattice type]({{ interface_url }}/materials-designer/source-editor/lattice/) of the crystal structure under consideration | +| model | The [theoretical model]({{ reference_url }}/models/overview/) employed to calculate the materials properties | +| method | The [computational method]({{ reference_url }}/methods/overview/) implementing the above model | | spaceGroupSymbol | The space group symbol describing the symmetry elements present in the crystal structure, e.g. "Fd-3m" | | volume | The volume of the unit cell of the structure, in units of angstrom^3 | | density | The density of the crystal structure, in units of g/cm^3 | -| owner | The Account name which [owns](../../entities-general/ownership.md) the material under consideration | -| tags | Descriptive [metadata](../../entities-general/data.md#Metadata) tags added to the material entry by the user | +| owner | The Account name which [owns]({{ reference_url }}/entities-general/ownership/) the material under consideration | +| tags | Descriptive [metadata]({{ data_url }}/entities-general/data/#Metadata) tags added to the material entry by the user | ### Properties -[Characteristic properties](../../data-structured/overview.md#by-relation-to-workflow) present for materials after the corresponding calculation(s) are done are described below and in the [corresponding page](../../properties/overview.md). +[Characteristic properties]({{ data_url }}/data-structured/overview/#by-relation-to-workflow) present for materials after the corresponding calculation(s) are done are described below and in the [corresponding page]({{ reference_url }}/properties/overview/). | Property | Description | | :-------- |:----------- | diff --git a/lang/en/docs/materials/actions/import.md b/lang/en/docs/materials/actions/import.md index 9e19f4382..a6051335a 100644 --- a/lang/en/docs/materials/actions/import.md +++ b/lang/en/docs/materials/actions/import.md @@ -4,7 +4,7 @@ We support direct import of materials structural data from other online sources. ## Open Import Dialog -Under the [Account Profile](../../accounts/ui/profile-page.md) page, first [navigate](../../ui/specific/tabs-navigator.md) to the "Materials" tab. Then choose import tool in the top right [actions toolbar](../../entities-general/ui/explorer.md#actions-toolbar). +Under the [Account Profile](../../accounts/ui/profile-page.md) page, first [navigate]({{ interface_url }}/ui/specific/tabs-navigator/) to the "Materials" tab. Then choose import tool in the top right [actions toolbar](../../entities-general/ui/explorer.md#actions-toolbar). ## Select Entries diff --git a/lang/en/docs/materials/actions/overview.md b/lang/en/docs/materials/actions/overview.md index 9a5b2073e..486b054b7 100644 --- a/lang/en/docs/materials/actions/overview.md +++ b/lang/en/docs/materials/actions/overview.md @@ -24,4 +24,4 @@ Copying Materials from the Bank is mostly equivalent to the procedure explained ## [Visualize Sets](visualize.md) -[Sets](../../entities-general/sets.md) of materials can be visualized by performing the relevant [action](visualize.md). +[Sets]({{ reference_url }}/entities-general/sets/) of materials can be visualized by performing the relevant [action](visualize.md). diff --git a/lang/en/docs/materials/actions/set-default.md b/lang/en/docs/materials/actions/set-default.md index d3d9c0e2d..8639dfc41 100644 --- a/lang/en/docs/materials/actions/set-default.md +++ b/lang/en/docs/materials/actions/set-default.md @@ -4,4 +4,4 @@ The initial default material for a new Exabyte account is set to FCC Silicon [^1 ## Links -[^1]: [Example Si FCC material, Exabyte Platform Website](https://platform.mat3ra.com/exabyte-io/materials/cMK8Z5hZMo23iDb9Z) +[^1]: [Example Si FCC material, Exabyte Platform Website](https://platform.mat3ra.com/mat3ra/materials/cMK8Z5hZMo23iDb9Z) diff --git a/lang/en/docs/materials/actions/upload.md b/lang/en/docs/materials/actions/upload.md index 9d456a203..72707a295 100644 --- a/lang/en/docs/materials/actions/upload.md +++ b/lang/en/docs/materials/actions/upload.md @@ -2,11 +2,11 @@ We support uploading structural data in the file formats containing the lattice geometry and the ionic positions of the crystal structure under investigation. -At present CIF, POSCAR and XYZ formats are supported [^1], [^2], [^3]. POSCAR format represents a standard way of defining and inputting crystal structure information to [VASP code](../../software-directory/modeling/vasp/overview.md), one of the simulations engines incorporated into our platform. XYZ files are a common format for defining and inputting non-periodic molecular structures into simulation engines, such as NWChem[^4]. +At present CIF, POSCAR and XYZ formats are supported [^1], [^2], [^3]. POSCAR format represents a standard way of defining and inputting crystal structure information to [VASP code]({{ reference_url }}/software-directory/modeling/vasp/overview/), one of the simulations engines incorporated into our platform. XYZ files are a common format for defining and inputting non-periodic molecular structures into simulation engines, such as NWChem[^4]. ## Open Upload Dialog -Open the [Account Profile](../../accounts/ui/profile-page.md) page and [navigate](../../ui/specific/tabs-navigator.md) to "Materials" tab. Then choose upload tool in the top right [actions toolbar](../../entities-general/ui/explorer.md#actions-toolbar). +Open the [Account Profile](../../accounts/ui/profile-page.md) page and [navigate]({{ interface_url }}/ui/specific/tabs-navigator/) to "Materials" tab. Then choose upload tool in the top right [actions toolbar](../../entities-general/ui/explorer.md#actions-toolbar). ## Select Files @@ -59,7 +59,7 @@ Next, the [selected](../../entities-general/actions/select.md) files can be uplo ## View Materials -Once the files have been imported, they are added as entries to the Materials [collection](../../accounts/collections.md). The name of the material is read from the imported file, if possible. Chemical formula is used as a backup option. +Once the files have been imported, they are added as entries to the Materials [collection]({{ reference_url }}/accounts/collections/). The name of the material is read from the imported file, if possible. Chemical formula is used as a backup option. ## Animation diff --git a/lang/en/docs/materials/actions/visualize.md b/lang/en/docs/materials/actions/visualize.md index f1736479a..7c98d2dca 100644 --- a/lang/en/docs/materials/actions/visualize.md +++ b/lang/en/docs/materials/actions/visualize.md @@ -1,11 +1,11 @@ # Visualize Sets -[Sets](../../entities-general/sets.md) of material entries can be visualized by selecting the `Visualize` option under the [actions drop-down menu](../../entities-general/ui/explorer.md#actions-dropdown) to the right of the set's entry within the materials [collection](../../accounts/collections.md), as viewed under the [Explorer Interface](../../entities-general/ui/explorer.md) of our platform. +[Sets]({{ reference_url }}/entities-general/sets/) of material entries can be visualized by selecting the `Visualize` option under the [actions drop-down menu](../../entities-general/ui/explorer.md#actions-dropdown) to the right of the set's entry within the materials [collection]({{ reference_url }}/accounts/collections/), as viewed under the [Explorer Interface](../../entities-general/ui/explorer.md) of our platform. This action allows the user to inspect the entire content of the set within a single instance of the [Materials Viewer interface](../ui/viewer.md). ## Animation -We demonstrate the procedure to visualize an example of [Interpolated Set](../../materials-designer/header-menu/advanced/interpolated-set.md), contained within an [ordered set](../../entities-general/sets.md#change-type) named "NEB set" in this case, in the following animation. We conclude the animation by cycling through the contents of the set, consisting in five different materials structures. +We demonstrate the procedure to visualize an example of [Interpolated Set]({{ interface_url }}/materials-designer/header-menu/advanced/interpolated-set/), contained within an [ordered set]({{ reference_url }}/entities-general/sets/#change-type) named "NEB set" in this case, in the following animation. We conclude the animation by cycling through the contents of the set, consisting in five different materials structures. diff --git a/lang/en/docs/materials/bank.md b/lang/en/docs/materials/bank.md index 11c774e84..9285157d8 100644 --- a/lang/en/docs/materials/bank.md +++ b/lang/en/docs/materials/bank.md @@ -8,11 +8,11 @@ Materials [Mapping Function](../entities-general/bank.md#bank-mapping-function) ## Advanced Search -Advanced search functionality specific to Materials and available also for Materials Bank page are described [here](actions/advanced-search.md). +Advanced search functionality specific to Materials and available also for Materials Bank page are described [here]({{ interface_url }}/materials/actions/advanced-search/). ## Copy from Bank -The procedure of copying (or importing) Bank Materials into Account-owned Materials collection is described [here](actions/copy-bank.md). +The procedure of copying (or importing) Bank Materials into Account-owned Materials collection is described [here]({{ interface_url }}/materials/actions/copy-bank/). ## Links diff --git a/lang/en/docs/materials/classification/crystalline.md b/lang/en/docs/materials/classification/crystalline.md index c1969c3d7..0d372190b 100644 --- a/lang/en/docs/materials/classification/crystalline.md +++ b/lang/en/docs/materials/classification/crystalline.md @@ -1,8 +1,8 @@ # Crystalline Materials -The complete **crystal structure** [^1] of a **crystalline material** is obtained when a [set of atoms](../../properties-directory/structural/basis.md), known as the **basis atoms** or **repeating unit**, are convolved (combined) with each one of the lattice points of the underlying [Bravais lattice](../../properties-directory/structural/lattice.md). +The complete **crystal structure** [^1] of a **crystalline material** is obtained when a [set of atoms]({{ reference_url }}/properties-directory/structural/basis/), known as the **basis atoms** or **repeating unit**, are convolved (combined) with each one of the lattice points of the underlying [Bravais lattice]({{ reference_url }}/properties-directory/structural/lattice/). -This results in a crystal structure with **long-range order**, which gives its corresponding [space group](../../properties-directory/structural/symmetry.md#space-group) symmetry assignment. +This results in a crystal structure with **long-range order**, which gives its corresponding [space group]({{ reference_url }}/properties-directory/structural/symmetry/#space-group) symmetry assignment. ## Visualization diff --git a/lang/en/docs/materials/classification/non-periodic.md b/lang/en/docs/materials/classification/non-periodic.md index b54f9ff56..c9988c611 100644 --- a/lang/en/docs/materials/classification/non-periodic.md +++ b/lang/en/docs/materials/classification/non-periodic.md @@ -1,11 +1,11 @@ # Non-Periodic Materials The complete **structure** of a **non-periodic chemical system** is obtained from a -[set of atoms](../../properties-directory/structural/basis.md), known as the **basis atoms**, that describe +[set of atoms]({{ reference_url }}/properties-directory/structural/basis/), known as the **basis atoms**, that describe a set of non-repeating atoms that are held together by covalent or non-covalent interactions. This results in a structure with a specific geometry which gives it a defined -[point-group](../../properties-directory/structural/symmetry.md#point-group)[^1] symmetry assignment. +[point-group]({{ reference_url }}/properties-directory/structural/symmetry/#point-group)[^1] symmetry assignment. Examples of **non-periodic structures** include **molecules**[^2], like **methane**[^3]. diff --git a/lang/en/docs/materials/data.md b/lang/en/docs/materials/data.md index 6c5dbfacc..26b491a21 100644 --- a/lang/en/docs/materials/data.md +++ b/lang/en/docs/materials/data.md @@ -13,13 +13,13 @@ In the expandable section below, the user can find an example JSON representatio === "Schema" - ``` json + ```json --8<-- "data/esse/schema/material.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/material.json" ``` @@ -29,16 +29,16 @@ In the expandable section below, the user can find an example JSON representatio | Keyword | Short Description | Details | | :-------- |:----------- |:------------- | -| basis | Crystal [basis](../properties-directory/structural/basis.md) with explicit identification per atom | The information about the atomic type and coordinates | -| lattice | Crystal [lattice](../properties-directory/structural/lattice.md) in both Bravais and vector notations | Crystal lattice parameters - lattice constants and angles. Components of the corresponding lattice vectors are also included. | -| derivedProperties | [descriptive properties](../data-structured/overview.md#by-relation-to-workflow) derived from lattice/basis (only one example shown above) | Additional properties of the crystal structure under investigation as explained in the section ensuing the present table. | -| hash | Hash string calculated by the [Bank Mapping Function](bank.md) | Structure-based hash string for the primitive standard representation of this material, calculated when checking this material against existing entries within the Materials Bank | +| basis | Crystal [basis]({{ reference_url }}/properties-directory/structural/basis/) with explicit identification per atom | The information about the atomic type and coordinates | +| lattice | Crystal [lattice]({{ reference_url }}/properties-directory/structural/lattice/) in both Bravais and vector notations | Crystal lattice parameters - lattice constants and angles. Components of the corresponding lattice vectors are also included. | +| derivedProperties | [descriptive properties]({{ data_url }}/data-structured/overview/#by-relation-to-workflow) derived from lattice/basis (only one example shown above) | Additional properties of the crystal structure under investigation as explained in the section ensuing the present table. | +| hash | Hash string calculated by the [Bank Mapping Function]({{ reference_url }}/materials/bank/) | Structure-based hash string for the primitive standard representation of this material, calculated when checking this material against existing entries within the Materials Bank | | scaledHash | As above, but for the lattice axis scaled to 1.0 (i.e. to identify same structures under different uniform pressure) | This hash string is calculated by scaling all the dimensions of the primitive unit cell representation of the material by the $a$ lattice constant | | isNonPeriodic | Boolean value used to describing whether a structure exists in a single unit or repeating units. | The isNonPeriodic Boolean value is assumed to be false by default, indicating that a material is **periodic**. The value of isNonPeriodic, determines which derivedProperties are calculated for a structure. For example: unit cell volume is calculated for periodic, but not non-periodic structures. Conversely, International Chemical Identifier (InChI)[^1] are calculated for non-periodic, but not periodic structures. ## Derived Properties -As seen above, we use the crystal **lattice** and **basis** JSON objects as the main [identifying properties](../data-structured/overview.md#by-relation-to-uniqueness). Based upon them, we calculate the **derivedProperties**, that may include such information as: +As seen above, we use the crystal **lattice** and **basis** JSON objects as the main [identifying properties]({{ data_url }}/data-structured/overview/#by-relation-to-uniqueness). Based upon them, we calculate the **derivedProperties**, that may include such information as: - the unit cell volume, - density, diff --git a/lang/en/docs/materials/default.md b/lang/en/docs/materials/default.md index 1387d66b3..60c955160 100644 --- a/lang/en/docs/materials/default.md +++ b/lang/en/docs/materials/default.md @@ -1,3 +1,3 @@ # Default Material -When a new Exabyte account is created, its default material is set to [FCC Silicon](data.md#example-representation) and can later be adjusted by the account member(s) according to [these instructions](actions/set-default.md). +When a new Exabyte account is created, its default material is set to [FCC Silicon]({{ data_url }}/materials/data/#example-representation) and can later be adjusted by the account member(s) according to [these instructions]({{ interface_url }}/materials/actions/set-default/). diff --git a/lang/en/docs/materials/overview.md b/lang/en/docs/materials/overview.md index 4b2739235..409ee1e3a 100644 --- a/lang/en/docs/materials/overview.md +++ b/lang/en/docs/materials/overview.md @@ -4,25 +4,25 @@ This section contains information about how we define, organize, store and inter ## User Interface -### [Materials Explorer](ui/explorer.md) +### [Materials Explorer]({{ interface_url }}/materials/ui/explorer/) -The implementation of the [Explorer Interface](../entities-general/ui/explorer.md) for Materials is explained [here](ui/explorer.md). +The implementation of the [Explorer Interface]({{ interface_url }}/entities-general/ui/explorer/) for Materials is explained [here]({{ interface_url }}/materials/ui/explorer/). -### [Materials Designer](../materials-designer/overview.md) +### [Materials Designer]({{ interface_url }}/materials-designer/overview/) -**Materials Designer** is introduced [here](../materials-designer/overview.md), +**Materials Designer** is introduced [here]({{ interface_url }}/materials-designer/overview/), -### [Materials Viewer](ui/viewer.md) +### [Materials Viewer]({{ interface_url }}/materials/ui/viewer/) -The **Viewer** interface and its differences from Designer are highlighted [separately](ui/viewer.md). +The **Viewer** interface and its differences from Designer are highlighted [separately]({{ interface_url }}/materials/ui/viewer/). -## [Actions](actions/overview.md) +## [Actions]({{ interface_url }}/materials/actions/overview/) -The Actions section explains and provides visual examples of actions that users can perform on materials. These actions are introduced [in the following page](actions/overview.md). +The Actions section explains and provides visual examples of actions that users can perform on materials. These actions are introduced [in the following page]({{ interface_url }}/materials/actions/overview/). -## [Data](data.md) +## [Data]({{ data_url }}/materials/data/) -The [Data](data.md) section contains an example of JSON representation of a material, with its detailed explanation. +The [Data]({{ data_url }}/materials/data/) section contains an example of JSON representation of a material, with its detailed explanation. ## [Bank](bank.md) diff --git a/lang/en/docs/materials/ui/explorer.md b/lang/en/docs/materials/ui/explorer.md index 042950283..5121218ee 100644 --- a/lang/en/docs/materials/ui/explorer.md +++ b/lang/en/docs/materials/ui/explorer.md @@ -6,4 +6,4 @@ Materials Explorer is mostly similar to the general [Explorer](../../entities-ge ## Materials Properties -In the above image, the properties exclusive to materials have been ticked under the [Columns Selector](../../entities-general/ui/explorer.md#columns-selector) drop-down. These properties are reviewed in more detail in a [dedicated page](../../properties/overview.md). +In the above image, the properties exclusive to materials have been ticked under the [Columns Selector](../../entities-general/ui/explorer.md#columns-selector) drop-down. These properties are reviewed in more detail in a [dedicated page]({{ reference_url }}/properties/overview/). diff --git a/lang/en/docs/materials/ui/viewer.md b/lang/en/docs/materials/ui/viewer.md index c5f974a9c..27461c73a 100644 --- a/lang/en/docs/materials/ui/viewer.md +++ b/lang/en/docs/materials/ui/viewer.md @@ -4,11 +4,11 @@ The user can [open](../../entities-general/actions/open-edit.md) entities listed ## Viewer vs. Designer -As explained in the [general introduction](../../entities-general/ui/viewer.md), we reuse the [Designer](../../materials-designer/overview.md) component as Viewer throughout the platform, with some adjustments and limitations on editing. For example, the ["Edit" functionality of the 3D crystal viewer](../../materials-designer/3d-editor/edit.md) is missing from Viewer, due to the inapplicability of its structure-changing actions under the "viewing" circumstances. +As explained in the [general introduction](../../entities-general/ui/viewer.md), we reuse the [Designer]({{ interface_url }}/materials-designer/overview/) component as Viewer throughout the platform, with some adjustments and limitations on editing. For example, the ["Edit" functionality of the 3D crystal viewer]({{ interface_url }}/materials-designer/3d-editor/edit/) is missing from Viewer, due to the inapplicability of its structure-changing actions under the "viewing" circumstances. ## Allowed Adjustments -Some minor adjustments, not related to the crystal structure (as an [identifying descriptive property](../../data-structured/overview.md#by-relation-to-uniqueness)) , might still be performed under the Materials Viewer. These can primarily be performed under the *header* and *footer* of Viewer, both highlighted in red in the image below. +Some minor adjustments, not related to the crystal structure (as an [identifying descriptive property]({{ data_url }}/data-structured/overview/#by-relation-to-uniqueness)) , might still be performed under the Materials Viewer. These can primarily be performed under the *header* and *footer* of Viewer, both highlighted in red in the image below. ![Materials Viewer](../../images/materials/materials-viewer.png "Materials Viewer") @@ -18,12 +18,12 @@ One such permitted action is the changing of the Material's name, as it appears ### Edit Metadata -[Metadata](../../entities-general/data.md#metadata) can also be added or modified for the material entry currently being inspected. For example, a general description can be written under the "Info" button present towards the right-hand side of the header. Tags can inserted/edited in the footer, following the [these instructions](../../entities-general/actions/metadata.md). +[Metadata]({{ data_url }}/entities-general/data/#metadata) can also be added or modified for the material entry currently being inspected. For example, a general description can be written under the "Info" button present towards the right-hand side of the header. Tags can inserted/edited in the footer, following the [these instructions](../../entities-general/actions/metadata.md). ### Toggle Privacy -Accounts with the appropriate [Service Level](../../pricing/service-levels.md) can choose between making the current material private to the members of the Account only, or publicly accessible to all users of the platform. The difference between these two privacy levels is explained in more detail [here](../../collaboration/sharing/access-levels.md). This choice can be made via the relevant toggle slider present in the footer as explained above. +Accounts with the appropriate [Service Level]({{ guide_url }}/pricing/service-levels/) can choose between making the current material private to the members of the Account only, or publicly accessible to all users of the platform. The difference between these two privacy levels is explained in more detail [here]({{ reference_url }}/collaboration/sharing/access-levels/). This choice can be made via the relevant toggle slider present in the footer as explained above. ## Properties Explorer -The list of calculated [properties](../../properties/overview.md) for the material under consideration, is displayed below the footer as explained [here](../../properties/ui/explorer.md). +The list of calculated [properties]({{ reference_url }}/properties/overview/) for the material under consideration, is displayed below the footer as explained [here](../../properties/ui/explorer.md). diff --git a/lang/en/docs/metadata/general.json b/lang/en/docs/metadata/general.json index 118243d5f..5eaa783a1 100644 --- a/lang/en/docs/metadata/general.json +++ b/lang/en/docs/metadata/general.json @@ -3,7 +3,7 @@ "chemistry", "cloud computing", "exabyte", - "exabyte-io", + "mat3ra", "high-performance computing", "HPC", "industry", diff --git a/lang/en/docs/methods-directory/linear-regression/data.md b/lang/en/docs/methods-directory/linear-regression/data.md index dc772d6ce..3f8ea6f75 100644 --- a/lang/en/docs/methods-directory/linear-regression/data.md +++ b/lang/en/docs/methods-directory/linear-regression/data.md @@ -1,15 +1,15 @@ # Structured Data for Linear Regression Method -Below, the user can find an example [JSON structured representation](../../data-structured/overview.md) for the [Linear Regression Method](overview.md). +Below, the user can find an example [JSON structured representation](../../data-structured/overview.md) for the [Linear Regression Method]({{ reference_url }}/methods-directory/linear-regression/overview/). === "Schema" - ``` json - --8<-- "data/esse/schema/methods_directory/regression.json" + ```json + --8<-- "data/esse/schema/methods_directory/legacy/regression.json" ``` === "Example" - ``` json - --8<-- "data/esse/example/methods_directory/regression.json" + ```json + --8<-- "data/esse/example/methods_directory/legacy/regression.json" ``` diff --git a/lang/en/docs/methods-directory/linear-regression/overview.md b/lang/en/docs/methods-directory/linear-regression/overview.md index cdd66e60f..5176a90af 100644 --- a/lang/en/docs/methods-directory/linear-regression/overview.md +++ b/lang/en/docs/methods-directory/linear-regression/overview.md @@ -8,6 +8,6 @@ This method is widely used as an effective algorithmic implementation of the [Ma [This page](parameters.md) contains a list of the fundamental computational parameters involved in the Linear Regression Method. -## [Structured Representation](data.md) +## [Structured Representation]({{ data_url }}/methods-directory/linear-regression/data/) -[This page](data.md) contains an example [structured representation](../../data-structured/overview.md) for the method. +[This page]({{ data_url }}/methods-directory/linear-regression/data/) contains an example [structured representation]({{ data_url }}/data-structured/overview/) for the method. diff --git a/lang/en/docs/methods-directory/pseudopotential/actions.md b/lang/en/docs/methods-directory/pseudopotential/actions.md index b4fb86744..86c7376d5 100644 --- a/lang/en/docs/methods-directory/pseudopotential/actions.md +++ b/lang/en/docs/methods-directory/pseudopotential/actions.md @@ -1,10 +1,10 @@ # Upload Custom Pseudopotential Files -Pseudopotential files can be uploaded directly to the [Subworkflow Editor Interface](../../workflow-designer/subworkflow-editor/overview.md), in order to expand the default set. This can be achieved following the procedure outlined below. +Pseudopotential files can be uploaded directly to the [Subworkflow Editor Interface]({{ interface_url }}/workflow-designer/subworkflow-editor/overview/), in order to expand the default set. This can be achieved following the procedure outlined below. ## Expand Pseudopotential panel -The user can initiate the upload of a custom pseudopotential file by first expanding the subsection labelled "Pseudopotentials" within the ["Overview" tab](../../workflow-designer/subworkflow-editor/overview-tab.md) of the interface (with the help of the "plus' button to its left). The `Upload` button on the right-hand side then needs to be clicked. +The user can initiate the upload of a custom pseudopotential file by first expanding the subsection labelled "Pseudopotentials" within the ["Overview" tab]({{ interface_url }}/workflow-designer/subworkflow-editor/overview-tab/) of the interface (with the help of the "plus' button to its left). The `Upload` button on the right-hand side then needs to be clicked. ## Set Information Fields diff --git a/lang/en/docs/methods-directory/pseudopotential/data.md b/lang/en/docs/methods-directory/pseudopotential/data.md index a430d2a13..96896450b 100644 --- a/lang/en/docs/methods-directory/pseudopotential/data.md +++ b/lang/en/docs/methods-directory/pseudopotential/data.md @@ -1,15 +1,15 @@ # Structured Data for Plane-Wave Pseudopotential Method -Below, the user can find an example [JSON structured representation](../../data-structured/overview.md) for the [Plane-wave Pseudopotential Method](overview.md). +Below, the user can find an example [JSON structured representation](../../data-structured/overview.md) for the [Plane-wave Pseudopotential Method]({{ reference_url }}/methods-directory/pseudopotential/overview/). === "Schema" - ``` json - --8<-- "data/esse/schema/methods_directory/pseudopotential.json" + ```json + --8<-- "data/esse/schema/methods_directory/legacy/pseudopotential.json" ``` === "Example" - ``` json - --8<-- "data/esse/example/methods_directory/pseudopotential.json" + ```json + --8<-- "data/esse/example/methods_directory/legacy/pseudopotential.json" ``` diff --git a/lang/en/docs/methods-directory/pseudopotential/default.md b/lang/en/docs/methods-directory/pseudopotential/default.md index a162836df..2209dfa66 100644 --- a/lang/en/docs/methods-directory/pseudopotential/default.md +++ b/lang/en/docs/methods-directory/pseudopotential/default.md @@ -13,7 +13,7 @@ We make use of the "pseudo-dojo" repository of norm-conserving pseudopotentials ### VASP -For [VASP](../../software-directory/modeling/vasp/overview.md) we provide the sets of `paw` pseudopotential for each supported version. +For [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) we provide the sets of `paw` pseudopotential for each supported version. ## Other Sources diff --git a/lang/en/docs/methods-directory/pseudopotential/important-settings.md b/lang/en/docs/methods-directory/pseudopotential/important-settings.md index 2ac10345e..2467e3ee7 100644 --- a/lang/en/docs/methods-directory/pseudopotential/important-settings.md +++ b/lang/en/docs/methods-directory/pseudopotential/important-settings.md @@ -1,6 +1,6 @@ # Important Settings -An example of appearance of the "Important Settings" tab within the [Subworkflow Editor Interface](../../workflow-designer/subworkflow-editor/overview.md) of [Workflow Designer](../../workflow-designer/overview.md), for the case of a basic ground-state total energy subworkflow calculation performed with [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md) (comprising a single Unit of type "pw-scf"), is illustrated in the image below. +An example of appearance of the "Important Settings" tab within the [Subworkflow Editor Interface]({{ interface_url }}/workflow-designer/subworkflow-editor/overview/) of [Workflow Designer]({{ interface_url }}/workflow-designer/overview/), for the case of a basic ground-state total energy subworkflow calculation performed with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) (comprising a single Unit of type "pw-scf"), is illustrated in the image below. ![Important Settings](../../images/workflow-designer/important-settings-tab.png "Important Settings") @@ -8,9 +8,9 @@ In this image, the two most common types of [input parameters](parameters.md) en ## Cutoff -The initial section of the "Important Settings" tab titled "cutoffs" contains settings which are always global to all units in the current subworkflow. In particular, under the label "wavefunction", the user can enter the plane-wave cutoff parameter for expanding the electronic wavefunction of the crystal. It is expressed in the corresponding default energy units for the current [application](../../software/components.md) of choice. For example, Rydbergs for [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md), and electronVolts (eV) for the [VASP](../../software-directory/modeling/vasp/overview.md) code. +The initial section of the "Important Settings" tab titled "cutoffs" contains settings which are always global to all units in the current subworkflow. In particular, under the label "wavefunction", the user can enter the plane-wave cutoff parameter for expanding the electronic wavefunction of the crystal. It is expressed in the corresponding default energy units for the current [application](../../software/components.md) of choice. For example, Rydbergs for [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/), and electronVolts (eV) for the [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) code. -This cutoff parameter is of crucial importance for establishing the overall [precision](../../methods/precision.md) of the DFT calculation, and a judicious choice will usually depend on the conduction of a preliminary [convergence test](../../workflows/addons/convergence-algorithms.md) to ensure that the desired precision in the total energy is reached. For instructions on how to add a preliminary convergence subworkflow add-on to the current workflow, see [this page](../../workflow-designer/subworkflow-editor/actions-menu.md). +This cutoff parameter is of crucial importance for establishing the overall [precision](../../methods/precision.md) of the DFT calculation, and a judicious choice will usually depend on the conduction of a preliminary [convergence test](../../workflows/addons/convergence-algorithms.md) to ensure that the desired precision in the total energy is reached. For instructions on how to add a preliminary convergence subworkflow add-on to the current workflow, see [this page]({{ interface_url }}/workflow-designer/subworkflow-editor/actions-menu/). In the text field directly to the right, under the label "density", the user can then also set the cutoff for the electronic charge density and potential (in the same application-dependent units as the previously-described plane-waves cutoff). For norm-conserving or PAW pseudopotentials [subtypes](parameters.md#pseudopotential), a value of four times the aforementioned wavefunction cutoff parameter is recommended, whereas for Ultra-Soft pseudopotentials a higher value between eight and twelve times the wavefunction cutoff is typically more suitable. diff --git a/lang/en/docs/methods-directory/pseudopotential/overview.md b/lang/en/docs/methods-directory/pseudopotential/overview.md index 452fbfb83..bc434434d 100644 --- a/lang/en/docs/methods-directory/pseudopotential/overview.md +++ b/lang/en/docs/methods-directory/pseudopotential/overview.md @@ -15,19 +15,19 @@ This method is widely used as an effective algorithmic recipe for the computatio ## [Actions](actions.md) -We introduce [here](actions.md) the action for uploading a custom Pseudopotential file to our platform via the [Subworkflow Editor Interface](../../workflow-designer/subworkflow-editor/overview.md). +We introduce [here](actions.md) the action for uploading a custom Pseudopotential file to our platform via the [Subworkflow Editor Interface]({{ interface_url }}/workflow-designer/subworkflow-editor/overview/). ## [Precision](precision.md) We discuss the parameters that limit the [numerical precision](../../methods/precision.md) of the plane-wave pseudopotential method [here](precision.md). -## [Structured Representation](data.md) +## [Structured Representation]({{ data_url }}/methods-directory/pseudopotential/data/) -[This page](data.md) contains an example [structured representation](../../data-structured/overview.md) for the method. +[This page]({{ data_url }}/methods-directory/pseudopotential/data/) contains an example [structured representation]({{ data_url }}/data-structured/overview/) for the method. ## [Important Settings](important-settings.md) -We explain [under this page](important-settings.md) how important settings concerning the method can be set under the [Subworkflow Editor Interface](../../workflow-designer/subworkflow-editor/overview.md) of [Workflow Designer](../../workflow-designer/overview.md). +We explain [under this page](important-settings.md) how important settings concerning the method can be set under the [Subworkflow Editor Interface]({{ interface_url }}/workflow-designer/subworkflow-editor/overview/) of [Workflow Designer]({{ interface_url }}/workflow-designer/overview/). ## Links diff --git a/lang/en/docs/methods-directory/pseudopotential/precision.md b/lang/en/docs/methods-directory/pseudopotential/precision.md index 649205553..e406ad34e 100644 --- a/lang/en/docs/methods-directory/pseudopotential/precision.md +++ b/lang/en/docs/methods-directory/pseudopotential/precision.md @@ -1,6 +1,6 @@ # Precision of Plane-Wave Pseudopotential Method -At present, we limit the estimation of the [numerical precision](../../methods/precision.md) of plane-wave pseudopotential computations to the following list of parameters, as contained within the [data structure](../../methods/data.md) for methods. +At present, we limit the estimation of the [numerical precision](../../methods/precision.md) of plane-wave pseudopotential computations to the following list of parameters, as contained within the [data structure]({{ data_url }}/methods/data/) for methods. ## Plane-wave diff --git a/lang/en/docs/methods/data.md b/lang/en/docs/methods/data.md index 7813d3f76..a3a2ee953 100644 --- a/lang/en/docs/methods/data.md +++ b/lang/en/docs/methods/data.md @@ -1,17 +1,17 @@ # Structured Representation of Methods -In order to organize and store the information about [Methods](overview.md) on our platform, we employ the **Exabyte Data Convention**, as explained [elsewhere](../data-structured/overview.md) in the documentation. +In order to organize and store the information about [Methods]({{ reference_url }}/methods/overview/) on our platform, we employ the **ESSE Data Convention**, as explained [elsewhere](../data-structured/overview.md) in the documentation. -Below, the user can find an example JSON structured representation of a [Method](overview.md). +Below, the user can find an example JSON structured representation of a [Method]({{ reference_url }}/methods/overview/). === "Schema" - ``` json + ```json --8<-- "data/esse/schema/method.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/method.json" ``` diff --git a/lang/en/docs/methods/overview.md b/lang/en/docs/methods/overview.md index 8f283a0ea..641dd7025 100644 --- a/lang/en/docs/methods/overview.md +++ b/lang/en/docs/methods/overview.md @@ -1,13 +1,13 @@ # Method -A theoretical [model](../models/overview.md) may have multiple **Methods**, or computational implementations. Since a method is a numerical property, it always has a certain precision. A method is implemented inside a **simulation engine** (or [application](../software-directory/overview.md)), and each application can itself implement one or more methods. +A theoretical [model](../models/overview.md) may have multiple **Methods**, or computational implementations. Since a method is a numerical property, it always has a certain precision. A method is implemented inside a **simulation engine** (or [application]({{ reference_url }}/software-directory/overview/)), and each application can itself implement one or more methods. !!! note "Example Model & Method" If we use Newtonian mechanics as Model, then the Method would be the algorithmic implementation of calculating the multiple between m and a in the `F = ma` equation. -## [Structured Representation](data.md) +## [Structured Representation]({{ data_url }}/methods/data/) -We explain structured representation of a method [here](data.md). +We explain structured representation of a method [here]({{ data_url }}/methods/data/). ## [Parameters](parameters.md) diff --git a/lang/en/docs/methods/parameters.md b/lang/en/docs/methods/parameters.md index a59459949..89b2e93b1 100644 --- a/lang/en/docs/methods/parameters.md +++ b/lang/en/docs/methods/parameters.md @@ -1,6 +1,6 @@ # Method Parameters -Our platform supports the following method parameters, which can be edited by the user within the "Overview" tab of the [Subworkflow Editor Interface](../workflow-designer/subworkflow-editor/overview-tab.md). +Our platform supports the following method parameters, which can be edited by the user within the "Overview" tab of the [Subworkflow Editor Interface]({{ interface_url }}/workflow-designer/subworkflow-editor/overview-tab/). ## Type diff --git a/lang/en/docs/models-directory/dft/data.md b/lang/en/docs/models-directory/dft/data.md index c8bc6e3c3..262f68c11 100644 --- a/lang/en/docs/models-directory/dft/data.md +++ b/lang/en/docs/models-directory/dft/data.md @@ -1,15 +1,15 @@ # Structured Data for Density Functional Theory Model -Below, the user can find an example [JSON structured representation](../../data-structured/overview.md) for the [Density Functional Theory Model](overview.md). +Below, the user can find an example [JSON structured representation](../../data-structured/overview.md) for the [Density Functional Theory Model]({{ reference_url }}/models-directory/dft/overview/). === "Schema" - ``` json - --8<-- "data/esse/schema/models_directory/pb/qm/dft/ksdft.json" + ```json + --8<-- "data/esse/schema/models_category/pb/qm/dft/ksdft.json" ``` === "Example" - ``` json - --8<-- "data/esse/example/models_directory/pb/qm/dft/ksdft.json" + ```json + --8<-- "data/esse/example/models_category/pb/qm/dft/ksdft.json" ``` diff --git a/lang/en/docs/models-directory/dft/notes.md b/lang/en/docs/models-directory/dft/notes.md index daa4db362..dc8ad1dd9 100644 --- a/lang/en/docs/models-directory/dft/notes.md +++ b/lang/en/docs/models-directory/dft/notes.md @@ -6,7 +6,7 @@ We list in the present page some special notices concerning the [parameters](par ### Electronic Band Gap -When computations of the [Electronic Band Gap](../../properties-directory/non-scalar/band-gaps.md) are executed through [Density Functional Theory](../../models-directory/dft/overview.md), operated in conjunction with the [Generalized Gradient Approximation](parameters.md#subtype) (GGA), a systematic **under-estimation of the band gap** is to be expected. This is a well-known shortcoming of the GGA technique, and should be taken into account when following the [procedure](../../tutorials/dft/electronic/band-gap.md) for calculating the band-gap of semiconducting materials. +When computations of the [Electronic Band Gap](../../properties-directory/non-scalar/band-gaps.md) are executed through [Density Functional Theory](../../models-directory/dft/overview.md), operated in conjunction with the [Generalized Gradient Approximation](parameters.md#subtype) (GGA), a systematic **under-estimation of the band gap** is to be expected. This is a well-known shortcoming of the GGA technique, and should be taken into account when following the [procedure]({{ guide_url }}/tutorials/dft/electronic/band-gap/) for calculating the band-gap of semiconducting materials. Further modifications to the input files and settings to correctly predict the band gap are possible, but lie beyond the scope of the present discussion. @@ -16,7 +16,7 @@ Hybrid functionals [^1] are a class of approximations to the exchange–correlat This approach typically results in improved [precision](../../methods/precision.md) in the estimation of the values of numerous [material properties](../../properties/overview.md) of interest, as demonstrated in the scientific literature [^3]. -A demonstration of the effectiveness of the HSE Hybrid Functional in predicting the [electronic band gap](../../properties-directory/non-scalar/band-gaps.md) of semiconducting materials is offered in the [relevant tutorial page](../../tutorials/dft/electronic/hse-vasp-bg.md). +A demonstration of the effectiveness of the HSE Hybrid Functional in predicting the [electronic band gap](../../properties-directory/non-scalar/band-gaps.md) of semiconducting materials is offered in the [relevant tutorial page]({{ guide_url }}/tutorials/dft/electronic/hse-vasp-bg/). ## The GW Approximation diff --git a/lang/en/docs/models-directory/dft/overview.md b/lang/en/docs/models-directory/dft/overview.md index 0d14f6e70..9d6d80168 100644 --- a/lang/en/docs/models-directory/dft/overview.md +++ b/lang/en/docs/models-directory/dft/overview.md @@ -1,23 +1,54 @@ # Density Functional Theory Model -We introduce here the theoretical framework of **Density Functional Theory (DFT)**. +**Density Functional Theory (DFT)** is a quantum mechanical modeling method used to investigate the electronic structure of many-body systems, primarily atoms, molecules, and condensed matter. DFT reformulates the many-electron Schrödinger equation in terms of the electron density rather than the many-body wave function, reducing the problem from 3N to 3 spatial variables [^1]. + +## Theoretical Foundations + +The method rests on two theorems by Hohenberg and Kohn [^2]: + +1. The ground-state energy of a many-electron system is a unique functional of the electron density. +2. The electron density that minimizes the energy functional is the exact ground-state density. + +In practice, the Kohn–Sham formulation [^3] maps the interacting many-electron system onto a set of non-interacting single-particle equations with an effective potential, making the problem computationally tractable. + +### Exchange-Correlation Functionals + +The exchange-correlation (XC) functional captures the quantum mechanical effects of electron exchange and correlation. Common approximations include: + +- **Local Density Approximation (LDA)** — depends only on the local electron density; tends to overbind. +- **Generalized Gradient Approximation (GGA)** — includes density gradients; the PBE functional [^4] is the most widely used. GGA is the default on the Mat3ra platform. +- **Hybrid Functionals** — mix a fraction of exact (Hartree–Fock) exchange with GGA; HSE06 [^5] is supported for more accurate band gaps. See the [HSE tutorials]({{ guide_url }}/tutorials/dft/electronic/hse-vasp-bg/). +- **GW Approximation** — a many-body perturbation theory approach for quasiparticle energies; supported through [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) and [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/). See the [GW tutorial]({{ guide_url }}/tutorials/dft/electronic/gw-vasp-bg/). + +!!!info "Known limitation: band gap underestimation" + Standard GGA-DFT systematically underestimates electronic band gaps due to the self-interaction error and the derivative discontinuity of the XC functional. Hybrid functionals and the GW approximation provide improved accuracy at higher computational cost. + ## [Parameters](parameters.md) -The list of parameters affecting DFT is presented [in this page](parameters.md). +The list of parameters affecting DFT calculations is presented [in this page](parameters.md), including the choice of XC functional, plane-wave cutoff energy, and k-point sampling. ## [Accuracy](accuracy.md) -We discuss the factors limiting the [accuracy](../../models/accuracy.md) of DFT [here](accuracy.md). +Factors limiting the [accuracy](../../models/accuracy.md) of DFT are discussed [here](accuracy.md), covering basis-set convergence, pseudopotential quality, and XC functional limitations. ## [References](references.md) -A comprehensive list of references reviewing the theoretical background underlying DFT is outlined [in this page](references.md), to be referred to at the reader's discretion. +A comprehensive list of references reviewing the theoretical background underlying DFT is outlined [in this page](references.md). -## [Structured Representation](data.md) +## [Structured Representation]({{ data_url }}/models-directory/dft/data/) -[This page](data.md) contains an example [structured representation](../../data-structured/overview.md) for the DFT model. +[This page]({{ data_url }}/models-directory/dft/data/) contains an example [structured representation]({{ data_url }}/data-structured/overview/) for the DFT model. ## [Special Notes](notes.md) -We have collected [in this page](notes.md) some special notes on special precautions that need to be taken when considering the different [parameters](parameters.md) of DFT. +Special precautions that need to be taken when considering the different [parameters](parameters.md) of DFT are collected [in this page](notes.md). + + +## Links + +[^1]: [Wikipedia Density Functional Theory](https://en.wikipedia.org/wiki/Density_functional_theory) +[^2]: P. Hohenberg and W. Kohn, "Inhomogeneous Electron Gas," Phys. Rev. 136, B864 (1964). [DOI](https://doi.org/10.1103/PhysRev.136.B864) +[^3]: W. Kohn and L. J. Sham, "Self-Consistent Equations Including Exchange and Correlation Effects," Phys. Rev. 140, A1133 (1965). [DOI](https://doi.org/10.1103/PhysRev.140.A1133) +[^4]: J. P. Perdew, K. Burke, and M. Ernzerhof, "Generalized Gradient Approximation Made Simple," Phys. Rev. Lett. 77, 3865 (1996). [DOI](https://doi.org/10.1103/PhysRevLett.77.3865) +[^5]: J. Heyd, G. E. Scuseria, and M. Ernzerhof, "Hybrid functionals based on a screened Coulomb potential," J. Chem. Phys. 118, 8207 (2003). [DOI](https://doi.org/10.1063/1.1564060) diff --git a/lang/en/docs/models-directory/machine-learning/actions.md b/lang/en/docs/models-directory/machine-learning/actions.md index e94ecdc11..2eb335ca6 100644 --- a/lang/en/docs/models-directory/machine-learning/actions.md +++ b/lang/en/docs/models-directory/machine-learning/actions.md @@ -1,11 +1,11 @@ # Define Training Data Set -Assembling a **training data set** for [Machine Learning](overview.md) applications can be done through the [addition](../../jobs-designer/actions-header-menu/select-materials.md) of [materials](../../materials/overview.md) to the relevant training [Job](../../jobs/overview.md) and selection of targets and features, as thoroughly explained in [this tutorial page](../../tutorials/ml/train-ml-model.md). +Assembling a **training data set** for [Machine Learning](overview.md) applications can be done through the [addition]({{ interface_url }}/jobs-designer/actions-header-menu/select-materials/) of [materials](../../materials/overview.md) to the relevant training [Job](../../jobs/overview.md) and selection of targets and features, as thoroughly explained in [this tutorial page]({{ guide_url }}/tutorials/ml/train-ml-model/). +To be eligible for the Limited Free Compute program, users must meet the following criteria: -## Limited Free Access for Academic Users +- Be a registered user of the platform. +- Have a valid academic affiliation (eg. student, faculty, researcher) or be a private party interested in exploring the + platform capabilities. +- If affiliated with an academic institution, use an email address associated with the institution (ie. hosted on a " + .edu" domain) during the registration. +- (Optional) Provide information about the nature of the anticipated work (eg. research topic, educational purpose, + etc.) +- Agree to the conditions outlined below. -!!!note "The Free Access Program completed in May of 2020." - The last Free Access Program completed as of 2020/05. Users are still welcome to submit their information for any future similar programs. +### 1.2. Applying for Free Compute. -For users with current academic affiliation we can provide computational resources free of charge on a case-by-case basis. +As of now, no separate application is needed. If you meet the eligibility criteria above, you can start using the +platform and its resources right away. -### Applying for Limited Free Access +We will review the user base periodically and reach out to the users who meet the eligibility criteria to inform them +about the program and its benefits. -As below: +And consequently, we will screen out the users who do not meet the criteria. + + +### 1.3. Free Compute Conditions. + +Free access is limited to certain compute resources and is subject to the following limitations. -1. Fill in this online form -2. For new users - submit a registration request using an email address associated with your academic institution include the information requested in **3**. -3. For existing users - if you use a personal email address during the registration, send an email to "support@exabyte.io" from the email address associated with your academic institution (ie. hosted on a ".edu" domain) with a subject containing "Free Access for Academic Users" - -we will review and enable access as appropriate. We will prioritize applications providing detailed information about the applicants (ie. Google Scholar, ResearchGate profile(s), links to prior publications) and the nature of the anticipated work. - -### Conditions +#### 1.3.1. Limitations -Free access is limited to certain compute resources only and is subject to other limitations as below. We will consider adjusting the limitations according to the user feedback received. Contact "support@exabyte.io" for this. - -#### Limitations +As below: + +| Feature | Explanation | +|:-----------------------:|:------------------:| +| Max nodes per job | 1 | +| Max cores per job | Per Queue Policy | +| Max job walltime | Per Queue Policy | +| Max job queued per user | 10 | +| Available Queues | "D" only | +| Available Resources | "cluster-101" only | +| Default Disk Quota | 10 Gb | -| Feature | Explanation | -| :------: | :----------: | -| Max nodes per job | 1 | -| Max cores per job | 4 | -| Max job walltime | 24 hours | -| Max job queued per user | 4 | -| Available Queues | "D" only | -| Available Resources | "cluster-009" only | -| Included Disk Quota | 10 Gb | +For more information, please see [cluster-101]({{ resources_url }}/infrastructure/clusters/cluster-101/). -#### Acknowledgements +## 2. Acknowledgements -Any/all published work derived from the Limited Free Access program must include the following Acknowledgement text and citation below. +Any/all published work derived from any of the Community Programs listed here must include the following acknowledgement +and citation. -**Acknowledgement text** +**Acknowledgment text** ```text -The authors performed this work partially or in full using the Exabyte.io -platform, a web-based computational ecosystem for the development of new -materials and chemicals [REFERENCE TO THE BELOW CITATION]. +The authors performed this work partially or in full using the Mat3ra.com +platform [REFERENCE TO THE BELOW CITATION]. ``` **Citation** ```text -Timur Bazhirov, "Data-centric online ecosystem for digital materials science", -arxiv.org preprint, 2019, https://arxiv.org/abs/1902.10838 +Vsevolod Biryukov, Kamal Choudhary, Timur Bazhirov, "AI-ready design of realistic 2D materials and interfaces with Mat3ra-2D.", +arxiv.org preprint, 2026, https://arxiv.org/abs/2603.27886 ``` -In Bibtex format: +In BibTeX format: ```bibtex -@article{Exabyte.io-Platform-Reference, - title={Data-centric online ecosystem for digital materials science}, - author={Bazhirov, Timur}, - journal={arxiv.org/abs/1902.10838}, - year={2019}, +@article{2026-mat3ra-2d, + title={AI-ready design of realistic 2D materials and interfaces with Mat3ra-2D}, + author={Biryukov, Vsevolod, and Choudhary, Kamal, and Bazhirov, Timur}, + journal={arxiv.org/abs/2603.27886}, + year={2026}, } ``` -#### Publicity +## 3. Publicity. + +We plan to select some of the work performed under the Free Compute Tier to be highlighted in the online +publication sources, similar to the following: + +- [Enabling new Science through Accessible Cloud HPC](https://www.mat3ra.com/news-and-blog-posts/enabling-new-science-through-accessible-modeling-and-simulations) +- [Scientific Computing on Cloud Infrastructure](https://blogs.oracle.com/cloud-infrastructure/post/exabyteio-for-scientific-computing-on-oracle-cloud-infrastructure-hpc) -We plan to select some of the work performed under the Limited Free Access program to be highlighted in the online publication sources together with the cloud provider(s) enabling the computational infrastructure. +We will contact select users in advance to request permission for this. If you are interested in having your work +highlighted, please let us know by sending an email to `support@mat3ra.com`. - -## Reach out to us +## 4. Feedback. -We are friendly people like you, why not reach out to us with your suggestions and ideas? You may contact us at info@exabyte.io. If you are interested in joining our team, write to hi@exabyte.io with your resume and cover letter. +We welcome feedback from the users of the Community Programs listed here. Please send your feedback, suggestions, and +any issues you encounter to `support@mat3ra.com`. diff --git a/lang/en/docs/other/faq.md b/lang/en/docs/other/faq.md index edf9fd657..141952950 100644 --- a/lang/en/docs/other/faq.md +++ b/lang/en/docs/other/faq.md @@ -19,12 +19,6 @@ Mat3ra is a comprehensive platform for materials design and discovery through mo We believe that focusing on core science is the most effective way to speed things up. We merge together in a single environment: rigorous models, vast compute power, intuitive user interface and data management tools, in order to make your work on materials design highly efficient. -### I don't get it - what is it really? - -OK, the animation below might help demonstrate our vision: - - - ### Where does your name come from? Mat3ra is the era of digital materials engineering and R&D. Hence the digit in the name. @@ -75,7 +69,7 @@ At current we fully support AWS and Azure in production. We paused using Rackspa ### As far as I understand this project allows one to use supercomputing facilities by paying money. But I cannot find any information about prices? -For pricing, please see [the service levels pricing section](../pricing/service-levels.md), and the [service levels features explanation](../accounts/service-levels.md). The pricing is quite comprehensive and can be **as low as 2 cents per core hour** for [saving-category](../infrastructure/compute/overview.md) resources. +For pricing, please see [the service levels pricing section]({{ guide_url }}/pricing/service-levels/), and the [service levels features explanation]({{ reference_url }}/accounts/service-levels/). The pricing is quite comprehensive and can be **as low as 2 cents per core hour** for [saving-category]({{ resources_url }}/infrastructure/compute/overview/) resources. ### How much computational resources do you have? How much of them user can use for one job? @@ -90,20 +84,20 @@ We are covering this exact topic, and other similar ones in the webinar series. ### Which software codes can we use? Only those installed on your machines? -Here's the [list of installed software](../software-directory/overview.md), with many packages/versions accessible via command-line interface through [modules environment](../cli/modules.md). Users can also [install new software](../cli/actions/add-software.md) using the runtime libraries provided (or install them as well), and [set up a python environment](../cli/actions/create-python-env.md), for example. We can help install new packages globally too, of course. +Here's the [list of installed software]({{ reference_url }}/software-directory/overview/), with many packages/versions accessible via command-line interface through [modules environment]({{ cli_url }}/cli/modules/). Users can also [install new software]({{ cli_url }}/cli/actions/add-software/) using the runtime libraries provided (or install them as well), and [set up a python environment]({{ cli_url }}/cli/actions/create-python-env/), for example. We can help install new packages globally too, of course. ### Can I use our own script or software to connect via ssh to your system and submit jobs? > For example simultaneous submition of 200 jobs at a time (each job is 16 CPU for 2 hours). Then after these 2 hours resubmit another 200 jobs and so on. -Absolutely. This is exactly what our [case study](../benchmarks/high-throughput-screening.md) speaks about here. +Absolutely. This is exactly what our [case study]({{ reference_url }}/benchmarks/high-throughput-screening/) speaks about here. ### Will there be a queue for these (200) calculations (from above)? -The beauty of the cloud is that it is elastic, so we can start all 200 jobs at once. Our system is dynamic and we run it well below the maximum capacity, so extra 200 jobs should take 5-15 min total to start as the computational nodes are provisioned and added to the system in parallel. This [benchmark](../benchmarks/high-throughput-screening.md) demonstrates it really well. The ability to "burst" - quickly run through a large number of jobs with little wait, is a nice value proposition of our system, compared to the shared use academic/gov supercomputers, for example. +The beauty of the cloud is that it is elastic, so we can start all 200 jobs at once. Our system is dynamic and we run it well below the maximum capacity, so extra 200 jobs should take 5-15 min total to start as the computational nodes are provisioned and added to the system in parallel. This [benchmark]({{ reference_url }}/benchmarks/high-throughput-screening/) demonstrates it really well. The ability to "burst" - quickly run through a large number of jobs with little wait, is a nice value proposition of our system, compared to the shared use academic/gov supercomputers, for example. ### Another example: I have heavy QE calculations, which require disk space of about 100-300 GB, and runs continuously during at least a week. Is it possible to do that? Yes, indeed - a job running for a week writing 100-300 Gb during that period is perfectly fine. We do not presently enforce maximum wall time, beyond what the account balance can accommodate. If you have 200 jobs like that running in parallel, we can accommodate with additional preparations. -We enforce [quotas](../data-on-disk/quotas.md) on the accounts to avoid clashing, the exact amounts we can [set per account](../pricing/storage-quota.md) as desired. +We enforce [quotas]({{ resources_url }}/data-on-disk/quotas/) on the accounts to avoid clashing, the exact amounts we can [set per account]({{ guide_url }}/pricing/storage-quota/) as desired. diff --git a/lang/en/docs/other/registration.md b/lang/en/docs/other/registration.md deleted file mode 100644 index 606a09b22..000000000 --- a/lang/en/docs/other/registration.md +++ /dev/null @@ -1,37 +0,0 @@ -This page explains the details of registration process. - -# Filling in the initial registration form - -In order to deliver the best service possible, we currently review all registration requests before accepting. Thus we require certain details from applicants, all the fields are required. See descriptions of each field in the table shown underneath the below screenshot. - -!!! tip "Privacy note" - We guarantee that the information you submit is private to our organization only, and do **not** share any of your information with any third parties. - -| Field | Description || -| ------------- |:------------- | -----: -| Email | A valid email | required -| Username | Alphanumeric and lowercase from 5 to 10 symbols | required -| Affiliation | Organisational affiliation | required -| Phone Number | With country code (+1 for example) | required -| Privacy | Please read and accept | required - - -# How quickly are registrations approved? - -We try to respond to each request with 24 hours. In some cases we may need to request further information before approving the registration request the account. We put specific attention to your use case, thus explaining what made you interested in our product and how you see yourself using it may significantly speed up the approval. - -# How your data is used to approve a registration? - -We vet all applications based on the information you provide, and what is available publicly. We will decide the application based on this combined information. We may need to request more information and will respond as quickly as possible in order to process the activation quickly. - -# Other conditions to be accepted upon registration - -Before creating a registration request we require users to accept certain other conditions of use of Exabyte.io: - -+ **Non-disclosure agreement**: Exabyte.io is a unique platform, we require our new users to accept conditions to keep the features and functionality of the platform in the strictest confidence in order to be able to continue to create new and exciting features. - -+ **Feedback** - We ask that new users agree to give regular feedback in order to continue providing the best service we can, and consistently improve our product. - -# Already have an account? - -If you already have an account, use the link at the footer of the document to jump to the login form. If you have an account but have forgotten your password, use the "Password" link. diff --git a/lang/en/docs/other/support.md b/lang/en/docs/other/support.md index fb1b08f64..e719ed3ad 100644 --- a/lang/en/docs/other/support.md +++ b/lang/en/docs/other/support.md @@ -1,15 +1,13 @@ # How to Get Support -We encourage you to ask questions. There are many ways to do that. - Our support team can be contacted by phone, email, or the web during working hours Pacific Time. -Technical questions, computer operations, passwords, and account support +Technical questions, computer operations, passwords, and account support: -- email: support@exabyte.io +- email: support@mat3ra.com - phone: 1.510.473.7770 -- web: https://platform.mat3ra.com/ +- web: https://platform.mat3ra.com/ > "Contact Support" (bottom of left sidebar menu) # Web widget -You may also submit a support ticket using our support-widget: click "Contact Support" in the bottom of left sidebar menu of any web application screen and fill in the form. +Submit a support ticket using our support-widget: click "Contact Support" in the bottom of left sidebar menu of any web application screen and fill in the form. diff --git a/lang/en/docs/pricing/service-levels.md b/lang/en/docs/pricing/service-levels.md index bac2368fd..fec07dbab 100644 --- a/lang/en/docs/pricing/service-levels.md +++ b/lang/en/docs/pricing/service-levels.md @@ -1,8 +1,6 @@ # Pricing -> Updated pricing scheme as of July 2019. For the information about the legacy pricing scheme please contact our support team. - -The pricing is dependent on the [Service Level](../accounts/service-levels.md). We aim to have a flexible scheme where customers always pay on-demand for the value they extract. +The pricing is dependent on the [Service Level]({{ reference_url }}/accounts/service-levels/). We aim to have a flexible scheme where customers always pay on-demand for the value they extract. ## Cost structure @@ -10,7 +8,7 @@ The cost of using our platform is comprised of the following components, added t ### Subscription Fee -The cost of accessing the platform. Charged on a monthly or yearly basis. [Free](../accounts/service-levels.md#free-service-level) tier is available. +The cost of accessing the platform. Charged on a monthly or yearly basis. [Free]({{ reference_url }}/accounts/service-levels/#free-service-level) tier is available. ### Computing Cost @@ -22,29 +20,26 @@ The cost of other resources, such as disk storage or account members. ## Comparison Table -Below is a quick comparison of our pricing for different [Service Levels](../accounts/service-levels.md). -Readers are referred to [Service Levels](../accounts/service-levels.md) page for detailed information about available features. +Below is a quick comparison of our pricing for different [Service Levels]({{ reference_url }}/accounts/service-levels/). +Readers are referred to [Service Levels]({{ reference_url }}/accounts/service-levels/) page for detailed information about available features. -| Fees | Free | Pro | Team | Enterprise | -| :------------- | :----------- | :------------- | :------------- | :------------- | -| Monthly Subscription Fee | - | $10 | $30 | - | -| Yearly Subscription Fee | - | $100 | $300 | $1,000 | -| Minimum Compute Allocation[^1] | - | - | $700 | $1,000 | -| Total Minimum Commitment | - | - | $1000 | Contact Us | -| Additional Account Members - Member/Month | - | - | $20 | $20 | -| Additional Account Members - Member/Year | - | - | $200 | $200 | -| Additional Disk Space - GB/Month | - | $0.2 | $0.2 | $0.2 | -| Additional Dropbox Space - GB/Month | - | $0.2 | $0.2 | $0.2 | -| Ordinary Compute Price - Core-Hour | - | $0.12 | $0.12 | $0.12 | +| Fees | Free | Pro | Enterprise | +| :------------- | :----------- | :------------- | :------------- | +| Yearly Subscription Fee | - | $360 | $3,600 | +| Additional Account Members - Member/Month | - | - | $20 | +| Additional Account Members - Member/Year | - | - | $200 | +| Additional Disk Space - GB/Month | - | $0.2 | $0.2 | +| Additional Dropbox Space - GB/Month | - | $0.2 | $0.2 | +| Ordinary Compute Price - Core-Hour | - | $0.12 | $0.12 | -[^1]: Only for organizational accounts that opt for [wire-based electronic payments](../accounts/payments-charges.md#wire-based-payments). +[^1]: For organizational accounts that opt for [wire-based electronic payments]({{ reference_url }}/accounts/payments-charges/#wire-based-payments). !!! note "Contact us for detailed pricing" - For detailed pricing or a quotation please contact us at sales@exabyte.io. + For detailed pricing or a quotation please contact us at sales@mat3ra.com. ## Category-based pricing -The compute price above refers to the **Ordinary** [cost category](../infrastructure/resource/category.md#cost-categories) for each service level. One can further control the price by varying the category type. When using submission queues with "Saving" cost category, for example, the relative unit price can be as low as 1/5th of the Ordinary. +The compute price above refers to the **Ordinary** [cost category]({{ resources_url }}/infrastructure/resource/category/#cost-categories) for each service level. One can further control the price by varying the category type. When using submission queues with "Saving" cost category, for example, the relative unit price can be as low as 1/5th of the Ordinary. |Cost Category| Charge factor |:--------- |:------------ @@ -54,9 +49,9 @@ The compute price above refers to the **Ordinary** [cost category](../infrastruc ## Queue- and Cluster-dependent pricing -As the type of hardware and scheduling policies vary for different submission queues, the pricing is also different. For, example, GPU-enabled nodes are available within a certain subset of queues and are generally priced higher. +As the type of hardware and scheduling policies vary for different submission queues, the pricing is also different. For example, GPU-enabled nodes are available within a certain subset of queues and are generally priced higher. -Detailed description of submission queues is available [here](../infrastructure/resource/queues.md). Clusters and associated hardware and pricing are explained in [this section](../infrastructure/clusters/overview.md) +Detailed description of submission queues is available [here]({{ resources_url }}/infrastructure/resource/queues/). Clusters and associated hardware and pricing are explained in [this section]({{ resources_url }}/infrastructure/clusters/overview/) !!! tip "Least expensive pricing options" - The options explained above can be combined in order to achieve the least expensive pricing. For example, when "Enterprise" service level is used in combination with submission queues that belong to the "Saving" cost category, the resulting price per core hour can be as low as $0.024. When we take into account the performance per core [benchmarks](../benchmarks/2018-11-12-comparison.md#performance-per-core) this presents a unique performance per price option. + The options explained above can be combined in order to achieve the least expensive pricing. For example, when "Enterprise" service level is used in combination with submission queues that belong to the "Saving" cost category, the resulting price per core hour can be as low as $0.024. diff --git a/lang/en/docs/properties-directory/elemental/atomic-radius.md b/lang/en/docs/properties-directory/elemental/atomic-radius.md index 9c50dd923..041e0cc5b 100644 --- a/lang/en/docs/properties-directory/elemental/atomic-radius.md +++ b/lang/en/docs/properties-directory/elemental/atomic-radius.md @@ -4,11 +4,11 @@ Atomic radius of a chemical element is a measure of the size of its atoms, and gives a typical indication of the distance from the center of the nucleus to the boundary of the surrounding cloud of electrons [^1]. -The atomic radii can be found tabulated for elements across the [Periodic Table](../../properties/data/periodic-table.md). +The atomic radii can be found tabulated for elements across the [Periodic Table]({{ data_url }}/properties/data/periodic-table/). ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#atomic-radius). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#atomic-radius). ## Links diff --git a/lang/en/docs/properties-directory/elemental/electronegativity.md b/lang/en/docs/properties-directory/elemental/electronegativity.md index f374b1615..b6471caa1 100644 --- a/lang/en/docs/properties-directory/elemental/electronegativity.md +++ b/lang/en/docs/properties-directory/elemental/electronegativity.md @@ -6,11 +6,11 @@ Electronegativity of an element is a chemical property that describes the tenden The most common way of quantifying the Electronegativity is that due to Pauling. This gives a dimensionless quantity, on a relative scale running from around 0.7 to 3.98 (hydrogen = 2.20). This is known as an electronegativity in Pauling units, which is what we use. -Values for the Pauling Electronegativity can be found tabulated for all elements in the [Periodic Table](../../properties/data/periodic-table.md). +Values for the Pauling Electronegativity can be found tabulated for all elements in the [Periodic Table]({{ data_url }}/properties/data/periodic-table/). ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#electronegativity). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#electronegativity). ## Links diff --git a/lang/en/docs/properties-directory/elemental/ionization-potential.md b/lang/en/docs/properties-directory/elemental/ionization-potential.md index e22d33fe9..1027c214b 100644 --- a/lang/en/docs/properties-directory/elemental/ionization-potential.md +++ b/lang/en/docs/properties-directory/elemental/ionization-potential.md @@ -4,11 +4,11 @@ The ionization energy (or potential) is defined as the minimum amount of energy required to remove the most loosely-bound valence electron of an isolated atom of an element [^1]. -Values for the ionization energies can be found tabulated for elements across the [Periodic Table](../../properties/data/periodic-table.md). +Values for the ionization energies can be found tabulated for elements across the [Periodic Table]({{ data_url }}/properties/data/periodic-table/). ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#ionization-potential). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#ionization-potential). ## Links diff --git a/lang/en/docs/properties-directory/non-scalar/band-gaps.md b/lang/en/docs/properties-directory/non-scalar/band-gaps.md index 31263e758..1d2dfa453 100644 --- a/lang/en/docs/properties-directory/non-scalar/band-gaps.md +++ b/lang/en/docs/properties-directory/non-scalar/band-gaps.md @@ -2,30 +2,49 @@ Non-Scalar Electronic -The Bang Gap measures the finite energy difference between the highest occupied and lowest unoccupied energy levels in, respectively, the valence and conduction bands of a semiconducting or insulating material [^1]. +The Band Gap measures the finite energy difference between the highest occupied and lowest unoccupied energy levels in the valence and conduction bands, respectively, of a semiconducting or insulating material [^1]. It is one of the most fundamental electronic properties, governing optical absorption, electrical conductivity, and thermoelectric performance. + ## Direct and Indirect Band Gaps -Two types of band gap are possible: **direct** and **indirect** [^2]. The latter is always computed on our platform, and is equivalent to the former for the direct gap semiconductors. +Two types of band gap are possible: **direct** and **indirect** [^2]. The platform computes both types whenever possible. + +When the gap is direct, the minimum energy difference between occupied and unoccupied states occurs at the same [k-point in reciprocal space](../../models/auxiliary-concepts/reciprocal-space.md). For indirect band gaps, this minimum energy difference involves states at different k-points, and the transition requires a change in crystal momentum (typically assisted by a phonon). + +The indirect band gap can be smaller than the direct gap. Classic examples include silicon (indirect gap ~1.1 eV, direct gap ~3.4 eV) and germanium. + + +## Methods for Computing the Band Gap + +The band gap can be obtained from several levels of theory, each with different accuracy-cost tradeoffs: + +| Method | Typical Accuracy | Tutorial | +|--------|-----------------|----------| +| GGA-DFT (PBE) | Underestimates by 30–50% | [Band gap tutorial]({{ guide_url }}/tutorials/dft/electronic/band-gap/) | +| HSE hybrid functional | Within ~0.2 eV of experiment | [HSE (VASP)]({{ guide_url }}/tutorials/dft/electronic/hse-vasp-bg/), [HSE (QE)]({{ guide_url }}/tutorials/dft/electronic/hse-qe-bg/) | +| GW approximation | Typically within ~0.1 eV | [GW (VASP)]({{ guide_url }}/tutorials/dft/electronic/gw-vasp-bg/) | +| ML force fields | Depends on training data | [MatterSim]({{ guide_url }}/tutorials/ml/run-mlff-python-workflows-mattersim/) | + +!!!warning "GGA band gap underestimation" + Standard DFT with the Generalized Gradient Approximation systematically underestimates band gaps due to the self-interaction error and missing derivative discontinuity in the exchange-correlation functional. For quantitative band gap predictions, hybrid functionals (HSE) or the GW approximation are recommended. -When the gap is direct, the minimum change in energy between occupied and unoccupied states occurs at the same [k-point in reciprocal space](../../models/auxiliary-concepts/reciprocal-space.md), whereas for the case of indirect band-gaps this change is instead located at different k-points. -The indirect band gap can be smaller than the direct one in some cases. - ## Example -Both types of band gaps are returned under the [Results Tab](../../jobs/ui/results-tab.md) as portrayed in the following image, immediately below the main [bandstructure dispersion](bandstructure.md) plot. +Both types of band gaps are returned under the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/), immediately below the main [band structure dispersion](bandstructure.md) plot. -In case the material is of indirect-gap nature, the pair of k-vectors linking the corresponding minimal energy difference is indicated. Otherwise, for direct-gap semiconductors, the two types of gap are presented as being equivalent and being both located across the Gamma point. +For indirect-gap materials, the pair of k-vectors linking the corresponding minimal energy difference is indicated. For direct-gap semiconductors, the two gap types are presented as equivalent and both located at the Gamma point. + +![Band Gap Energy](../../images/properties-directory/band-gap-energy.png "Band Gap Energy") -![Band Gap Energy](../../images/properties-directory//bang-gap-energy.png "Band Gap Energy") ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#band-gaps). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#band-gaps). + ## Links -[^1]: [Wikipedia Bang Gap, Website](https://en.wikipedia.org/wiki/Band_gap) +[^1]: [Wikipedia Band Gap](https://en.wikipedia.org/wiki/Band_gap) -[^2]: [Wikipedia Direct and indirect band gaps, Website](https://en.wikipedia.org/wiki/Direct_and_indirect_band_gaps) +[^2]: [Wikipedia Direct and indirect band gaps](https://en.wikipedia.org/wiki/Direct_and_indirect_band_gaps) diff --git a/lang/en/docs/properties-directory/non-scalar/bandstructure.md b/lang/en/docs/properties-directory/non-scalar/bandstructure.md index e52ead00a..5c88f993f 100644 --- a/lang/en/docs/properties-directory/non-scalar/bandstructure.md +++ b/lang/en/docs/properties-directory/non-scalar/bandstructure.md @@ -6,17 +6,17 @@ The electronic bandstructure of a material describes the range of energies that ## Example -Electronic bandstructure calculations can be performed with an appropriate [Workflow](../../workflows/overview.md). The results are portrayed in the [Results Tab](../../jobs/ui/results-tab.md) of [Job Viewer](../../jobs/ui/viewer.md) in the form of a **dispersion curve**, as illustrated in the graphic below. The visual contains the bandstructure calculated on the path "Г-X-W-K-Г-L-U-W-L-U-X" with indirect band gap realized between k-points at [0.0,0.0,0.0] and [0.4,0.0,0.4] with the value of 0.601. Similarly, the direct gap of 2.422 is found at the gamma point. +Electronic bandstructure calculations can be performed with an appropriate [Workflow](../../workflows/overview.md). The results are portrayed in the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) in the form of a **dispersion curve**, as illustrated in the graphic below. The visual contains the bandstructure calculated on the path "Г-X-W-K-Г-L-U-W-L-U-X" with indirect band gap realized between k-points at [0.0,0.0,0.0] and [0.4,0.0,0.4] with the value of 0.601. Similarly, the direct gap of 2.422 is found at the gamma point. ![Bandstructure](../../images/properties-directory//bandstructure.png "Bandstructure") ### Path in the reciprocal space -This dispersion plot covers the [desired path](../../workflow-designer/subworkflow-editor/important-settings.md) in the reciprocal space of the Brillouin Zone, with its corresponding Greek letter labels indicating special symmetry points. The energy along the vertical axis is scaled relative to the [Fermi energy](../scalar/fermi-energy.md) of the material (red dashed line), marking the highest occupied energy level. +This dispersion plot covers the [desired path]({{ interface_url }}/workflow-designer/subworkflow-editor/important-settings/) in the reciprocal space of the Brillouin Zone, with its corresponding Greek letter labels indicating special symmetry points. The energy along the vertical axis is scaled relative to the [Fermi energy](../scalar/fermi-energy.md) of the material (red dashed line), marking the highest occupied energy level. ### Export as Image -The possibility to export the graph is offered as mentioned [here](../../properties/ui/viewer.md#export-as-images). +The possibility to export the graph is offered as mentioned [here]({{ interface_url }}/properties/ui/viewer/#export-as-images). ## Energy Eigenvalues @@ -24,7 +24,7 @@ The list of energy eigenvalue solutions, corresponding to each k-point in the re ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#bandstructure). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#bandstructure). ## Links diff --git a/lang/en/docs/properties-directory/non-scalar/electronic-dos.md b/lang/en/docs/properties-directory/non-scalar/electronic-dos.md index 4edb2bea5..3d7b0ade9 100644 --- a/lang/en/docs/properties-directory/non-scalar/electronic-dos.md +++ b/lang/en/docs/properties-directory/non-scalar/electronic-dos.md @@ -6,7 +6,7 @@ The Density of States of the material describes the number of states per an inte ## Example -Example results for the computed electronic Density of States are also presented graphically in the [Results Tab](../../jobs/ui/results-tab.md) of [Job Viewer](../../jobs/ui/viewer.md). +Example results for the computed electronic Density of States are also presented graphically in the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). The typical appearance of such a Density of States plot for electronic bandstructures is shown below. @@ -18,11 +18,11 @@ In this graph, the total density of states is marked by the black line. Individu ### Export as Image -The possibility to export the graph is offered as mentioned [here](../../properties/ui/viewer.md#export-as-images). +The possibility to export the graph is offered as mentioned [here]({{ interface_url }}/properties/ui/viewer/#export-as-images). ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#density-of-states). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#density-of-states). ## Links diff --git a/lang/en/docs/properties-directory/non-scalar/file-content.md b/lang/en/docs/properties-directory/non-scalar/file-content.md index 0d351d282..64d8cde56 100644 --- a/lang/en/docs/properties-directory/non-scalar/file-content.md +++ b/lang/en/docs/properties-directory/non-scalar/file-content.md @@ -14,7 +14,7 @@ Below, this can be observed in the results tab of the job. ## Schema -The JSON schema and an example implementation can be found [here](../../properties/data/list.md#file-content) +The JSON schema and an example implementation can be found [here]({{ data_url }}/properties/data/list/#file-content) ## Links diff --git a/lang/en/docs/properties-directory/non-scalar/phonon-dispersions.md b/lang/en/docs/properties-directory/non-scalar/phonon-dispersions.md index cc2254de9..aca81c642 100644 --- a/lang/en/docs/properties-directory/non-scalar/phonon-dispersions.md +++ b/lang/en/docs/properties-directory/non-scalar/phonon-dispersions.md @@ -6,17 +6,17 @@ The results of phonon lattice vibration calculations [^1] are presented in a sim ## Example -An example of such a phonon dispersion plot, as presented under the [Results Tab](../../jobs/ui/results-tab.md) of [Job Viewer](../../jobs/ui/viewer.md), is shown below. +An example of such a phonon dispersion plot, as presented under the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/), is shown below. ![Phonons](../../images/properties-directory//phonons.png "Phonons") ### Export as Image -The possibility to export the graph is offered as mentioned [here](../../properties/ui/viewer.md#export-as-images). +The possibility to export the graph is offered as mentioned [here]({{ interface_url }}/properties/ui/viewer/#export-as-images). ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#phonon-dispersions). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#phonon-dispersions). ## Links diff --git a/lang/en/docs/properties-directory/non-scalar/phonon-dos.md b/lang/en/docs/properties-directory/non-scalar/phonon-dos.md index 68062c4c5..4fa2b51ae 100644 --- a/lang/en/docs/properties-directory/non-scalar/phonon-dos.md +++ b/lang/en/docs/properties-directory/non-scalar/phonon-dos.md @@ -6,7 +6,7 @@ The Density of States for the case of lattice vibrations [^1] describes the numb ## Example -The final results for the computed phonon Density of States are also presented graphically in the [Results Tab](../../jobs/ui/results-tab.md) of [Job Viewer](../../jobs/ui/viewer.md). +The final results for the computed phonon Density of States are also presented graphically in the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). An example of such a Density of States plot is shown below. @@ -14,11 +14,11 @@ An example of such a Density of States plot is shown below. ### Export as Image -The possibility to export the graph is offered as mentioned [here](../../properties/ui/viewer.md#export-as-images). +The possibility to export the graph is offered as mentioned [here]({{ interface_url }}/properties/ui/viewer/#export-as-images). ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#phonon-density-of-states). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#phonon-density-of-states). ## Links diff --git a/lang/en/docs/properties-directory/non-scalar/reaction-energy-profile.md b/lang/en/docs/properties-directory/non-scalar/reaction-energy-profile.md index 395d4eb2c..66cc54d56 100644 --- a/lang/en/docs/properties-directory/non-scalar/reaction-energy-profile.md +++ b/lang/en/docs/properties-directory/non-scalar/reaction-energy-profile.md @@ -8,15 +8,15 @@ The purpose of energy profiles is to provide a qualitative representation of how ## Example -Reaction Energy Profile calculations can be performed with an appropriate [Workflow](../../workflows/overview.md), based on the [**Nudged Elastic Bands** method](../../models/auxiliary-concepts/nudged-elastic-band.md) such as [implemented](../../tutorials/dft/chemical/reaction-profile-qe.md) by the [Quantum ESPRESSO modeling application](../../software-directory/modeling/quantum-espresso/overview.md). +Reaction Energy Profile calculations can be performed with an appropriate [Workflow](../../workflows/overview.md), based on the [**Nudged Elastic Bands** method](../../models/auxiliary-concepts/nudged-elastic-band.md) such as [implemented]({{ guide_url }}/tutorials/dft/chemical/reaction-profile-qe/) by the [Quantum ESPRESSO modeling application]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/). -The final results are portrayed in the [Results Tab](../../jobs/ui/results-tab.md) of [Job Viewer](../../jobs/ui/viewer.md) in the form of a **profile curve**, as illustrated in the graphic below. The visual contains the reaction energy profile for a chemical reaction with [activation energy barrier](../scalar/reaction-energy-barrier.md) of approximately 0.2 eV. +The final results are portrayed in the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) in the form of a **profile curve**, as illustrated in the graphic below. The visual contains the reaction energy profile for a chemical reaction with [activation energy barrier](../scalar/reaction-energy-barrier.md) of approximately 0.2 eV. ![Reaction Profile](../../images/properties-directory/reaction-profile.png "Reaction Profile") ### Export as Image -The possibility to export the graph is offered as mentioned [here](../../properties/ui/viewer.md#export-as-images). +The possibility to export the graph is offered as mentioned [here]({{ interface_url }}/properties/ui/viewer/#export-as-images). ## Transition State @@ -26,7 +26,7 @@ The highest potential energy molecular configuration across a reaction energy pr ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#reaction-energy-profile). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#reaction-energy-profile). ## Links diff --git a/lang/en/docs/properties-directory/non-scalar/stress-tensor.md b/lang/en/docs/properties-directory/non-scalar/stress-tensor.md index 18ef54e8b..a049575b2 100644 --- a/lang/en/docs/properties-directory/non-scalar/stress-tensor.md +++ b/lang/en/docs/properties-directory/non-scalar/stress-tensor.md @@ -1,12 +1,17 @@ +--- +render_macros: true +--- # Stress Tensor Non-Scalar Mechanical -The stress tensor ${\boldsymbol {\sigma }}$ [^1] is a [Physical](../../properties/classification/general.md) property. It is a second-rank **tensor**, representable as a **Matrix**, which consists of nine components $\sigma _{ij}$ that completely define the state of stress at a point inside a deformed material. +The stress tensor ${ oldsymbol {\sigma }}$ [^1] is a [Physical](../../properties/classification/general.md) property. It is a second-rank **tensor**, representable as a **Matrix**, which consists of nine components $\sigma _{ij}$ that completely define the state of stress at a point inside a deformed material. +{% raw %} $$ -{\boldsymbol {\sigma }}=\left[{{\begin{matrix}\sigma _{{xx}}&\sigma _{{xy}}&\sigma _{{xz}}\\\sigma _{{yx}}&\sigma _{{yy}}&\sigma _{{yz}}\\\sigma _{{zx}}&\sigma _{{zy}}&\sigma _{{zz}}\\\end{matrix}}}\right] +{ oldsymbol {\sigma }}=\left[{{ egin{matrix}\sigma _{{xx}}&\sigma _{{xy}}&\sigma _{{xz}}\\sigma _{{yx}}&\sigma _{{yy}}&\sigma _{{yz}}\\sigma _{{zx}}&\sigma _{{zy}}&\sigma _{{zz}}\ nd{matrix}}}ight] $$ +{% endraw %} The image below offers an explanation of the directions in which each shear and normal stress component expressed above acts upon, relative to a Cartesian coordinate system. @@ -14,13 +19,13 @@ The image below offers an explanation of the directions in which each shear and ## Example -Under the [Results Tab](../../jobs/ui/results-tab.md) of [Job Viewer](../../jobs/ui/viewer.md), the components of the stress tensor are presented as follows, expressed in units of kilobars (kbar). +Under the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/), the components of the stress tensor are presented as follows, expressed in units of kilobars (kbar). ![Stress Tensor](../../images/properties-directory//stress-tensor.png "Stress Tensor") ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#stress-tensor). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#stress-tensor). ## Links diff --git a/lang/en/docs/properties-directory/non-scalar/workflow.md b/lang/en/docs/properties-directory/non-scalar/workflow.md index 038b23c5a..654b5db90 100644 --- a/lang/en/docs/properties-directory/non-scalar/workflow.md +++ b/lang/en/docs/properties-directory/non-scalar/workflow.md @@ -8,7 +8,7 @@ workflow being generated and placed in the user's account. ## Creation during ML Jobs If any unit in the workflow has the `workflow:pyml_predict` property, -[Express will be called](https://github.com/Exabyte-io/express/blob/dev/express/properties/workflow.py) to construct +[Express will be called](https://github.com/mat3ra/express/blob/dev/express/properties/workflow.py) to construct the new predict workflow. The following process is performed to convert a workflow from "Train" to "Predict" mode: - The `IS_WORKFLOW_RUNNING_TO_PREDICT` flag is set to `True` @@ -28,4 +28,4 @@ which has generated a workflow named `workflow:pyml_predict`. ## Schema -The JSON schema and an example implementation can be found [here](../../properties/data/list.md#workflow) +The JSON schema and an example implementation can be found [here]({{ data_url }}/properties/data/list/#workflow) diff --git a/lang/en/docs/properties-directory/overview.md b/lang/en/docs/properties-directory/overview.md index d12fc4d54..e83d21b47 100644 --- a/lang/en/docs/properties-directory/overview.md +++ b/lang/en/docs/properties-directory/overview.md @@ -2,11 +2,11 @@ In this section of the documentation, we review in detail the physical relevance and description of each [property](../properties/overview.md) available for computation. -In each case, we also explain how such results are presented to the user under the interface of the [Results Tab](../jobs/ui/results-tab.md) within [Jobs Viewer](../jobs/ui/viewer.md), when results are extracted from the output of simulations. +In each case, we also explain how such results are presented to the user under the interface of the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) within [Jobs Viewer]({{ interface_url }}/jobs/ui/viewer/), when results are extracted from the output of simulations. -Illustrations of the [JSON schemas](../properties/data/overview.md) and associated examples for each property discussed in the present section are contained [in this page](../properties/data/list.md), and referenced at the end of each property's dedicated description. +Illustrations of the [JSON schemas]({{ data_url }}/properties/data/overview/) and associated examples for each property discussed in the present section are contained [in this page]({{ data_url }}/properties/data/list/), and referenced at the end of each property's dedicated description. -At the top of each property's page, we include colored badges referring to the [property classification](../properties/classification/overview.md), distinguishing between [scalar and non-scalar](../properties/classification#by-data-type) types and between the different types of [Materials Properties](../properties/classification/materials.md). +At the top of each property's page, we include colored badges referring to the [property classification](../properties/classification/overview.md), distinguishing between [scalar and non-scalar](../properties/classification/general.md#by-data-type) types and between the different types of [Materials Properties](../properties/classification/materials.md). ## Materials Properties diff --git a/lang/en/docs/properties-directory/scalar/fermi-energy.md b/lang/en/docs/properties-directory/scalar/fermi-energy.md index 214d3024d..4220af7d1 100644 --- a/lang/en/docs/properties-directory/scalar/fermi-energy.md +++ b/lang/en/docs/properties-directory/scalar/fermi-energy.md @@ -6,7 +6,7 @@ The Fermi Energy marks the highest occupied energy level in the [electronic band ## Example -Its value can be estimated with any [bandstructure](../non-scalar/bandstructure.md) [Workflow](../../workflows/overview.md), and it is returned under the [Results Tab](../../jobs/ui/results-tab.md) interface with the following appearance (in eV). +Its value can be estimated with any [bandstructure](../non-scalar/bandstructure.md) [Workflow](../../workflows/overview.md), and it is returned under the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) interface with the following appearance (in eV).
@@ -20,7 +20,7 @@ Its value can be estimated with any [bandstructure](../non-scalar/bandstructure. ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#fermi-energy). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#fermi-energy). ## Links diff --git a/lang/en/docs/properties-directory/scalar/formation-energy.md b/lang/en/docs/properties-directory/scalar/formation-energy.md index 174eaf192..6142438fc 100644 --- a/lang/en/docs/properties-directory/scalar/formation-energy.md +++ b/lang/en/docs/properties-directory/scalar/formation-energy.md @@ -11,6 +11,7 @@ $$ $$ `E_fmt` and `E_tot`, `E_zpe` are the formation energy, total energy and zero point energy for the compound and lowest energy elemental structures, correspondingly. - - !!!note "Note: feature under development" - The calculation of Formation energies is not yet available as a Workflow computation on our platform. + +## Tutorials + +- [Calculate Formation Energy]({{ reference_url }}/tutorials/dft/thermodynamic/formation-energy/) diff --git a/lang/en/docs/properties-directory/scalar/pressure.md b/lang/en/docs/properties-directory/scalar/pressure.md index d7892824d..ef8642981 100644 --- a/lang/en/docs/properties-directory/scalar/pressure.md +++ b/lang/en/docs/properties-directory/scalar/pressure.md @@ -2,7 +2,7 @@ Scalar Thermodynamic -We define the **Average Pressure** $p_{avg}$ of a Material as a **[Scalar and Physical](../../data-structured/overview.md) property** obtained from the following conventional formula. +We define the **Average Pressure** $p_{avg}$ of a Material as a **[Scalar and Physical]({{ data_url }}/data-structured/overview/) property** obtained from the following conventional formula. $$ p_{avg}=-\frac{1}{3} \mathrm{Tr} \hspace{1pt} {\boldsymbol{\sigma}} @@ -14,7 +14,7 @@ where ${\boldsymbol{\sigma}}$ is the [internal stress tensor](../non-scalar/stre The average pressure can be computed as part of any [Workflow](../../workflows/overview.md) involving at least one basic "self-consistent field" (scf) total energy calculation in [DFT](../../models-directory/dft/overview.md). -It is then presented to the user, as part of the output of a [Job](../../jobs/overview.md), with the following appearance under the interface of the [Results Tab](../../jobs/ui/results-tab.md) of [Job Viewer](../../jobs/ui/viewer.md). Its final value is expressed in units of kilobars (kbar). +It is then presented to the user, as part of the output of a [Job](../../jobs/overview.md), with the following appearance under the interface of the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). Its final value is expressed in units of kilobars (kbar).
@@ -28,7 +28,7 @@ It is then presented to the user, as part of the output of a [Job](../../jobs/ov ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#pressure). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#pressure). ## Links diff --git a/lang/en/docs/properties-directory/scalar/reaction-energy-barrier.md b/lang/en/docs/properties-directory/scalar/reaction-energy-barrier.md index ed27d24e4..38d5f26f0 100644 --- a/lang/en/docs/properties-directory/scalar/reaction-energy-barrier.md +++ b/lang/en/docs/properties-directory/scalar/reaction-energy-barrier.md @@ -6,7 +6,7 @@ The Reaction Energy Barrier (also known as Activation Barrier) marks the highest ## Example -Its value can be estimated with any [Nudged Elastic Band](../../tutorials/dft/chemical/reaction-profile-qe.md) (NEB) [Workflow](../../workflows/overview.md), and it is returned under the [Results Tab](../../jobs/ui/results-tab.md) interface with the following appearance (in eV). +Its value can be estimated with any [Nudged Elastic Band]({{ guide_url }}/tutorials/dft/chemical/reaction-profile-qe/) (NEB) [Workflow](../../workflows/overview.md), and it is returned under the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) interface with the following appearance (in eV).
@@ -20,7 +20,7 @@ Its value can be estimated with any [Nudged Elastic Band](../../tutorials/dft/ch ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#reaction-energy-barrier). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#reaction-energy-barrier). ## Links diff --git a/lang/en/docs/properties-directory/scalar/surface-energy.md b/lang/en/docs/properties-directory/scalar/surface-energy.md index fbdcdb105..d0b8a9072 100644 --- a/lang/en/docs/properties-directory/scalar/surface-energy.md +++ b/lang/en/docs/properties-directory/scalar/surface-energy.md @@ -14,7 +14,7 @@ where $N$ is the number of atoms in the slab and $A$ is the surface area, with $ The surface energy can be calculated by an appropriate [Workflow](../../workflows/overview.md) using, for example [Density Functional Theory](../../models-directory/dft/overview.md). -It is presented to the user with the appearance displayed below, under the interface of the [Results Tab](../../jobs/ui/results-tab.md) of [Job Viewer](../../jobs/ui/viewer.md). Its final value is expressed in units of eV/Angstrom^2. +It is presented to the user with the appearance displayed below, under the interface of the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). Its final value is expressed in units of eV/Angstrom^2.
@@ -28,7 +28,7 @@ It is presented to the user with the appearance displayed below, under the inter ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#surface-energy). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#surface-energy). ## Links diff --git a/lang/en/docs/properties-directory/scalar/total-energy.md b/lang/en/docs/properties-directory/scalar/total-energy.md index a640d173b..2bfe3de16 100644 --- a/lang/en/docs/properties-directory/scalar/total-energy.md +++ b/lang/en/docs/properties-directory/scalar/total-energy.md @@ -8,7 +8,7 @@ The "Total Energy" refers to the total electronic ground state energy of a mater The total energy can be calculated by a corresponding workflow. For [DFT](../../models-directory/dft/overview.md) calculations, for example, any [Workflow](../../workflows/overview.md) containing a unit with a "self-consistent field" (scf) type can extract total energy. -It is presented to the user, as part of the output of a [Job](../../jobs/overview.md), with the appearance displayed below, under the interface of the [Results Tab](../../jobs/ui/results-tab.md) of the [Job Viewer](../../jobs/ui/viewer.md). Its final value is expressed in units of electronVolt (eV). +It is presented to the user, as part of the output of a [Job](../../jobs/overview.md), with the appearance displayed below, under the interface of the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) of the [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). Its final value is expressed in units of electronVolt (eV).
@@ -32,7 +32,7 @@ The reader is referred to the links presented at the bottom of the page for a th #### Generic Applications -The following contributions, displayed in the image below, are computed and returned to the user under the [Results Tab](../../jobs/ui/results-tab.md) of [Job Viewer](../../jobs/ui/viewer.md), for the cases of both [VASP](../../software-directory/modeling/vasp/overview.md) and [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md) calculations. In all instances, the results are returned in units of eV. +The following contributions, displayed in the image below, are computed and returned to the user under the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/), for the cases of both [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) and [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) calculations. In all instances, the results are returned in units of eV. ![Common Contributions](../../images/properties-directory/common-contributions.png "Common Contributions") @@ -42,7 +42,7 @@ Two additional energy contributions can be evaluated with Quantum ESPRESSO-based ## Schema -The JSON schema and an example representation for the total energy can be found [here](../../properties/data/list.md#total-energy), whereas that for its contributions [here](../../properties/data/list.md#total-energy-contributions). +The JSON schema and an example representation for the total energy can be found [here]({{ data_url }}/properties/data/list/#total-energy), whereas that for its contributions [here]({{ data_url }}/properties/data/list/#total-energy-contributions). ## Links diff --git a/lang/en/docs/properties-directory/scalar/total-force.md b/lang/en/docs/properties-directory/scalar/total-force.md index 656db6e23..da88ff3ea 100644 --- a/lang/en/docs/properties-directory/scalar/total-force.md +++ b/lang/en/docs/properties-directory/scalar/total-force.md @@ -6,7 +6,7 @@ Similarly to the [average pressure](pressure.md), the **Total Force** is also tr ## Example -This material property is displayed under the [Results Tab](../../jobs/ui/results-tab.md) of [Job Viewer](../../jobs/ui/viewer.md) as follows, in units of eV/Angstroms. It it also routinely computed as part of any total energy self-consistent field (scf) calculation using [DFT](../../models-directory/dft/overview.md). +This material property is displayed under the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) as follows, in units of eV/Angstroms. It it also routinely computed as part of any total energy self-consistent field (scf) calculation using [DFT](../../models-directory/dft/overview.md).
@@ -20,4 +20,4 @@ This material property is displayed under the [Results Tab](../../jobs/ui/result ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#total-force). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#total-force). diff --git a/lang/en/docs/properties-directory/scalar/valence-band-offset.md b/lang/en/docs/properties-directory/scalar/valence-band-offset.md index 0a06642d8..7e69a4903 100644 --- a/lang/en/docs/properties-directory/scalar/valence-band-offset.md +++ b/lang/en/docs/properties-directory/scalar/valence-band-offset.md @@ -11,11 +11,11 @@ Regarding conduction band edges $\varepsilon_{c}$ there exists an equivalent pro The VBO plays an important role for the transport properties of charge carriers in heterojunction devices (e.g. hole injection efficiency). Using first principles calculations, the VBO can be determined through the potential lineup method [^1][^2][^3] or via the local density of states (LDOS) [^3]. For more details -regarding the potential lineup method, see also the [valence band offset tutorial](../../tutorials/dft/electronic/valence-band-offset.md) +regarding the potential lineup method, see also the [valence band offset tutorial]({{ guide_url }}/tutorials/dft/electronic/valence-band-offset/) ## Example -Its value can be estimated using the valence band offset [workflow](../../workflows/overview.md), and it is returned under the [Results Tab](../../jobs/ui/results-tab.md) interface with the following appearance (in eV). +Its value can be estimated using the valence band offset [workflow](../../workflows/overview.md), and it is returned under the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) interface with the following appearance (in eV).
@@ -28,7 +28,7 @@ Its value can be estimated using the valence band offset [workflow](../../workfl ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#valence-band-offset). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#valence-band-offset). ## Links diff --git a/lang/en/docs/properties-directory/scalar/zero-point-energy.md b/lang/en/docs/properties-directory/scalar/zero-point-energy.md index 7d478fb91..f3d96e767 100644 --- a/lang/en/docs/properties-directory/scalar/zero-point-energy.md +++ b/lang/en/docs/properties-directory/scalar/zero-point-energy.md @@ -8,7 +8,7 @@ A further contribution to the internal energy of a material structure originates The Zero-point Energy has to be computed by performing a [Phonon calculation](../non-scalar/phonon-dispersions.md) on the material under investigation using an appropriate [Workflow](../../workflows/overview.md). -It is displayed under the [Results Tab](../../jobs/ui/results-tab.md) of the corresponding [Job](../../jobs/overview.md) in the following manner, also in units of eV. +It is displayed under the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) of the corresponding [Job](../../jobs/overview.md) in the following manner, also in units of eV.
@@ -22,7 +22,7 @@ It is displayed under the [Results Tab](../../jobs/ui/results-tab.md) of the cor ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#zero-point-energy). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#zero-point-energy). ## Links diff --git a/lang/en/docs/properties-directory/structural/atomic-forces.md b/lang/en/docs/properties-directory/structural/atomic-forces.md index 5903c6f6f..cbb2173c2 100644 --- a/lang/en/docs/properties-directory/structural/atomic-forces.md +++ b/lang/en/docs/properties-directory/structural/atomic-forces.md @@ -10,13 +10,13 @@ They are expressed as a set of vectors, one for each atom in the material, descr Atomic forces can be computed as part of any [Workflow](../../workflows/overview.md) executing a total energy self-consistent field calculation. -Under the [Results Tab](../../jobs/ui/results-tab.md) within [Jobs Viewer](../../jobs/ui/viewer.md), the atomic forces are returned to the user as displayed in the example image below (exhibiting an ideal equilibrium situation with zero force components), expressed in units of eV/Angstroms. +Under the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) within [Jobs Viewer]({{ interface_url }}/jobs/ui/viewer/), the atomic forces are returned to the user as displayed in the example image below (exhibiting an ideal equilibrium situation with zero force components), expressed in units of eV/Angstroms. ![Atomic forces](../../images/properties-directory//atomic_forces.png "Atomic forces") ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#atomic-forces). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#atomic-forces). ## Links diff --git a/lang/en/docs/properties-directory/structural/basis.md b/lang/en/docs/properties-directory/structural/basis.md index 1d25fc2c5..5ea51088f 100644 --- a/lang/en/docs/properties-directory/structural/basis.md +++ b/lang/en/docs/properties-directory/structural/basis.md @@ -14,7 +14,7 @@ A typical example of an atomic arrangement within a material is given by the cub ## Atomic Positions -The atomic positions, defining the atom's geometric arrangement within the structure, can be defined and entered in the [basis editor](../../materials-designer/source-editor/basis.md) of [Materials Designer](../../materials-designer/overview.md), as separate three-dimensional vectors. Each vector labels the position of the corresponding atom within the unit cell of the crystal, expressed under either a fractional or Cartesian coordinate system. +The atomic positions, defining the atom's geometric arrangement within the structure, can be defined and entered in the [basis editor]({{ interface_url }}/materials-designer/source-editor/basis/) of [Materials Designer]({{ interface_url }}/materials-designer/overview/), as separate three-dimensional vectors. Each vector labels the position of the corresponding atom within the unit cell of the crystal, expressed under either a fractional or Cartesian coordinate system. Depending on these atomic coordinates, finite [inter-atomic forces](atomic-forces.md) might arise. @@ -24,11 +24,11 @@ The ratio of an element in a compound or alloy describes the fraction of all ato ## Atomic Constraints -The Atomic Constraints or Selective Dynamics, specifying the constraints on the movement of atoms, can be set in the [basis editor](../../materials-designer/source-editor/basis.md) of [Materials Designer](../../materials-designer/overview.md), as three-dimensional boolean vector appending to the atom position. For example, "Si 0.25 0.25 0.25 1 0 1" freezes the movement of "Si" along the "Y" direction. +The Atomic Constraints or Selective Dynamics, specifying the constraints on the movement of atoms, can be set in the [basis editor]({{ interface_url }}/materials-designer/source-editor/basis/) of [Materials Designer]({{ interface_url }}/materials-designer/overview/), as three-dimensional boolean vector appending to the atom position. For example, "Si 0.25 0.25 0.25 1 0 1" freezes the movement of "Si" along the "Y" direction. ## Schema -The JSON schema and an example representation for the properties described in this page can be found for each of the [basis](../../properties/data/list.md#basis), [atomic elements](../../properties/data/list.md#atomic-elements), [atomic positions](../../properties/data/list.md#atomic-coordinates) and [elemental ratio](../../properties/data/list.md#elemental-ratio). +The JSON schema and an example representation for the properties described in this page can be found for each of the [basis]({{ data_url }}/properties/data/list/#basis), [atomic elements]({{ data_url }}/properties/data/list/#atomic-elements), [atomic positions]({{ data_url }}/properties/data/list/#atomic-coordinates) and [elemental ratio]({{ data_url }}/properties/data/list/#elemental-ratio). ## Links diff --git a/lang/en/docs/properties-directory/structural/final-structure.md b/lang/en/docs/properties-directory/structural/final-structure.md index cfc78b8f5..6a6bd1cea 100644 --- a/lang/en/docs/properties-directory/structural/final-structure.md +++ b/lang/en/docs/properties-directory/structural/final-structure.md @@ -4,15 +4,15 @@ The final structure represents the [crystal structure](../../materials/classific ## Relevance for Structural Relaxations -The visualization of the final structure is especially resourceful in the context of simulation runs that include a preliminary [structural relaxation](../../workflows/addons/structural-relaxation.md) step. In this case, it becomes important to understand how the material [originally defined](../../jobs-designer/materials-tab.md) during [Job creation](../../jobs-designer/overview.md) was structurally altered by the relaxation algorithms. +The visualization of the final structure is especially resourceful in the context of simulation runs that include a preliminary [structural relaxation](../../workflows/addons/structural-relaxation.md) step. In this case, it becomes important to understand how the material [originally defined]({{ interface_url }}/jobs-designer/materials-tab/) during [Job creation]({{ interface_url }}/jobs-designer/overview/) was structurally altered by the relaxation algorithms. ## Example -The final structure can be inspected under an instance of the [Materials Viewer interface](../../materials/ui/viewer.md) within the [Results Tab](../../jobs/ui/results-tab.md) of the corresponding [Job Viewer](../../jobs/ui/viewer.md). +The final structure can be inspected under an instance of the [Materials Viewer interface]({{ interface_url }}/materials/ui/viewer/) within the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) of the corresponding [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). We refer to this interface as the "Final Structure Viewer" in this particular context. -Below we show an example of a material structure as it appears under the Final Structure Viewer (demarcated in red), following a relaxation run performed on it using [VASP](../../software-directory/modeling/vasp/overview.md). +Below we show an example of a material structure as it appears under the Final Structure Viewer (demarcated in red), following a relaxation run performed on it using [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/). The viewer is shown in the general context of the other relevant computed material [properties](../overview.md), displayed together in their own panel. diff --git a/lang/en/docs/properties-directory/structural/inchi-key.md b/lang/en/docs/properties-directory/structural/inchi-key.md index 0d6854d81..ac4000ee9 100644 --- a/lang/en/docs/properties-directory/structural/inchi-key.md +++ b/lang/en/docs/properties-directory/structural/inchi-key.md @@ -32,7 +32,7 @@ H -0.7493682 0.0000000 0.4424329 ```` ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#InChIKey). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#InChIKey). ## Links diff --git a/lang/en/docs/properties-directory/structural/inchi.md b/lang/en/docs/properties-directory/structural/inchi.md index 4468231da..fd6aabcab 100644 --- a/lang/en/docs/properties-directory/structural/inchi.md +++ b/lang/en/docs/properties-directory/structural/inchi.md @@ -25,7 +25,7 @@ H -0.7493682 0.0000000 0.4424329 ```` ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#InChI). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#InChI). ## Links diff --git a/lang/en/docs/properties-directory/structural/lattice.md b/lang/en/docs/properties-directory/structural/lattice.md index 2086c66f6..9ab4902a6 100644 --- a/lang/en/docs/properties-directory/structural/lattice.md +++ b/lang/en/docs/properties-directory/structural/lattice.md @@ -10,7 +10,7 @@ $$ where $n_i$ are any integers, and $a_i$ are known as the **lattice vectors** spanning the lattice in three-dimensional space. The defining characteristic of a Bravais lattice is that, for any choice of position vector $R$, the lattice has to look exactly the same when viewed from any equivalent lattice point. -Information about the Bravais Lattice can be entered within the [lattice editor](../../materials-designer/source-editor/lattice.md) of [Materials Designer](../../materials-designer/overview.md), when a new material is being created. +Information about the Bravais Lattice can be entered within the [lattice editor]({{ interface_url }}/materials-designer/source-editor/lattice/) of [Materials Designer]({{ interface_url }}/materials-designer/overview/), when a new material is being created. ## Lattice types @@ -34,7 +34,7 @@ $$ ## Schema -The JSON schema and an example representation for the properties described in this page can be found for each of the [Bravais Lattice](../../properties/data/list.md#bravais-lattice), [lattice vectors](../../properties/data/list.md#lattice-vectors), [volume](../../properties/data/list.md#volume) and [density](../../properties/data/list.md#density). +The JSON schema and an example representation for the properties described in this page can be found for each of the [Bravais Lattice]({{ data_url }}/properties/data/list/#bravais-lattice), [lattice vectors]({{ data_url }}/properties/data/list/#lattice-vectors), [volume]({{ data_url }}/properties/data/list/#volume) and [density]({{ data_url }}/properties/data/list/#density). ## Links diff --git a/lang/en/docs/properties-directory/structural/magnetic-moment.md b/lang/en/docs/properties-directory/structural/magnetic-moment.md index 8b27d5deb..f51de2d8b 100644 --- a/lang/en/docs/properties-directory/structural/magnetic-moment.md +++ b/lang/en/docs/properties-directory/structural/magnetic-moment.md @@ -8,15 +8,15 @@ The Magnetic Moment is a **[Vector and Physical](../../properties/classification ## Example -The magnetic moment can be computed by inserting the corresponding [Workflow Modifier](../../workflow-designer/subworkflow-editor/overview-tab.md). +The magnetic moment can be computed by inserting the corresponding [Workflow Modifier]({{ interface_url }}/workflow-designer/subworkflow-editor/overview-tab/). -It is returned to the user as a set of vectors (one for each atom present in the material), as portrayed below, under the interface of the [Results Tab](../../jobs/ui/results-tab.md) of [Job Viewer](../../jobs/ui/viewer.md). Its final value is expressed in units of bohr magnetons. +It is returned to the user as a set of vectors (one for each atom present in the material), as portrayed below, under the interface of the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). Its final value is expressed in units of bohr magnetons. ![Magnetic Moment](../../images/properties-directory//magnetic-moment.png "Magnetic Moment") ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#magnetic-moments). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#magnetic-moments). ## Links diff --git a/lang/en/docs/properties-directory/structural/molecular-weight.md b/lang/en/docs/properties-directory/structural/molecular-weight.md index f3bbd0274..4c7f0d292 100644 --- a/lang/en/docs/properties-directory/structural/molecular-weight.md +++ b/lang/en/docs/properties-directory/structural/molecular-weight.md @@ -15,7 +15,7 @@ MW H2O = 15.999 g/mol + 1.001 g/mol 1.001 g/mol = 18.001 g/mol. ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#molecular-weight). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#molecular-weight). ## Links diff --git a/lang/en/docs/properties-directory/structural/symmetry.md b/lang/en/docs/properties-directory/structural/symmetry.md index 99740a5a8..06718543b 100644 --- a/lang/en/docs/properties-directory/structural/symmetry.md +++ b/lang/en/docs/properties-directory/structural/symmetry.md @@ -45,7 +45,7 @@ share in common, is labelled by the symbol "Fd-3m". ## Schema -The JSON schema and an example representation for this property can be found [here](../../properties/data/list.md#symmetry). +The JSON schema and an example representation for this property can be found [here]({{ data_url }}/properties/data/list/#symmetry). ## Links diff --git a/lang/en/docs/properties/classification/general.md b/lang/en/docs/properties/classification/general.md index 59f57cd31..289b3df3c 100644 --- a/lang/en/docs/properties/classification/general.md +++ b/lang/en/docs/properties/classification/general.md @@ -2,7 +2,7 @@ ## Summary -[Properties](../overview.md) are classified according to the below. We explain the terms contained in the table throughout the remainder of the present documentation page. These classification criteria complement the more general ones introduced [here](../../data/classification.md). +[Properties](../overview.md) are classified according to the below. We explain the terms contained in the table throughout the remainder of the present documentation page. These classification criteria complement the more general ones introduced [here]({{ data_url }}/data/classification/). | By refinement status | By data type | By relation to Workflow | By Uniqueness | By Physical Meaning | |:--------:|:-------------:|:------------------------:|:---------------:|:------------------------:| @@ -27,7 +27,7 @@ We can subdivide properties based on how they are presented to the user into the - **Scalar**: can be expressed as a single numerical value with an associated measurement unit. - **Non-Scalar**: cannot be expressed as above. -We review the scalar and non-scalar classes of Materials properties in [this documentation section](../../properties-directory/overview.md). +We review the scalar and non-scalar classes of Materials properties in [this documentation section]({{ reference_url }}/properties-directory/overview/). > NOTE: non-scalar properties may be further subdivided into other groups like 1-dimensional arrays or matrices, for example. @@ -46,7 +46,7 @@ For atomistic simulations, a descriptive property can be for example the initial ## By Relation to Uniqueness -An effective way of organizing the data consists in identifying the materials themselves, rather than their properties. We do so by considering **Identifiers**, a special subset of *Descriptive* properties that helps associating each material with its ["exabyteId" keyword](../../entities-general/data.md). +An effective way of organizing the data consists in identifying the materials themselves, rather than their properties. We do so by considering **Identifiers**, a special subset of *Descriptive* properties that helps associating each material with its ["exabyteId" keyword]({{ data_url }}/entities-general/data/). ### Example @@ -69,4 +69,4 @@ In the context of data obtained by simulations, it could happen that the value o ### Example -For atomistic simulations done using the [plane-wave pseudopotential method](../../methods-directory/pseudopotential/overview.md) we can extract the Fermi energy. However, there is no physical meaning to its numerical value, as it is heavily dependent on the pseudization scheme. Conversely the electronic band gap, or the difference between electronic energies below the Fermi level and above it, has physical meaning and can be directly compared with experimental measurements. +For atomistic simulations done using the [plane-wave pseudopotential method]({{ reference_url }}/methods-directory/pseudopotential/overview/) we can extract the Fermi energy. However, there is no physical meaning to its numerical value, as it is heavily dependent on the pseudization scheme. Conversely the electronic band gap, or the difference between electronic energies below the Fermi level and above it, has physical meaning and can be directly compared with experimental measurements. diff --git a/lang/en/docs/properties/classification/machine-learning.md b/lang/en/docs/properties/classification/machine-learning.md index 99b1f8e90..9c67df51f 100644 --- a/lang/en/docs/properties/classification/machine-learning.md +++ b/lang/en/docs/properties/classification/machine-learning.md @@ -1,6 +1,6 @@ # Classification for Machine Learning purposes -The classification criteria explained in this page complement the more general ones introduced [here](../../data/classification.md). +The classification criteria explained in this page complement the more general ones introduced [here]({{ data_url }}/data/classification/). ## Motivation diff --git a/lang/en/docs/properties/classification/materials.md b/lang/en/docs/properties/classification/materials.md index 76f284baf..720e5557e 100644 --- a/lang/en/docs/properties/classification/materials.md +++ b/lang/en/docs/properties/classification/materials.md @@ -1,6 +1,6 @@ # Materials Properties Classification -The classification explained below complements the more general one introduced [here](../../data/classification.md). We further classify the Properties of [Materials](../../materials/overview.md) according to the conventions below. +The classification explained below complements the more general one introduced [here]({{ data_url }}/data/classification/). We further classify the Properties of [Materials](../../materials/overview.md) according to the conventions below. | By origin | By domain | |:------------------------------:|:------------------------------:| @@ -17,7 +17,7 @@ The classification explained below complements the more general one introduced [ ## By origin -We further make the following sub-categorization for Materials Properties, following the Exabyte Data Convention. +We further make the following sub-categorization for Materials Properties, following the ESSE Data Convention. - **elemental**: entirely defined by pure elements and inherited by compounds without modification (eg. electronegativity, atomic weight). - **primary**: directly available properties specific to material (can be of all types, for example [characteristic or descriptive](general.md)). diff --git a/lang/en/docs/properties/data/core.md b/lang/en/docs/properties/data/core.md index acf040579..7cb7ee7e5 100644 --- a/lang/en/docs/properties/data/core.md +++ b/lang/en/docs/properties/data/core.md @@ -11,12 +11,12 @@ The primitive schemas are derived from the default JSON primitives and do not ha Series is an array of arrays containing numbers or strings. It is used to store data === "Schema" - ``` json + ```json --8<-- "data/esse/schema/core/primitive/1d_data_series.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/core/primitive/1d_data_series.json" ``` @@ -26,12 +26,12 @@ Holds the information about the three-dimensional periodic lattice specified thr === "Schema" - ``` json + ```json --8<-- "data/esse/schema/core/primitive/3d_lattice.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/core/primitive/3d_lattice.json" ``` @@ -40,12 +40,12 @@ Holds the information about the three-dimensional periodic lattice specified thr Used for plotting. It has a label to describe the type of data on the axis and units to describe the units of the data. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/core/primitive/axis.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/core/primitive/axis.json" ``` @@ -59,12 +59,12 @@ Data prepared for a two-dimensional plot. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/core/abstract/2d_data.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/core/abstract/2d_data.json" ``` @@ -73,12 +73,12 @@ Data prepared for a two-dimensional plot. Two-dimensional data object, defined in conjunction with two axes. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/core/abstract/2d_plot.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/core/abstract/2d_plot.json" ``` @@ -87,12 +87,12 @@ Two-dimensional data object, defined in conjunction with two axes. A tensor which can be represented as a 3x3 matrix (for example the stress tensor). === "Schema" - ``` json + ```json --8<-- "data/esse/schema/core/abstract/3d_tensor.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/core/abstract/3d_tensor.json" ``` @@ -101,7 +101,7 @@ A tensor which can be represented as a 3x3 matrix (for example the stress tensor Three non-collinear vectors in three-dimensional space that form a basis set. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/core/abstract/3d_vector_basis.json" ``` @@ -115,12 +115,12 @@ Three non-collinear vectors in three-dimensional space that form a basis set. Point is a generic data type that is expected to be used by many different aspects of the database. It is an array holding three numbers. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/core/abstract/point.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/core/abstract/point.json" ``` @@ -129,11 +129,11 @@ Point is a generic data type that is expected to be used by many different aspec Vector is a generic data type that is expected to be used by many different aspects of the database. It is an array holding three numbers. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/core/abstract/vector.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/core/abstract/vector.json" ``` diff --git a/lang/en/docs/properties/data/list.md b/lang/en/docs/properties/data/list.md index a0a46cd29..7bf4b7284 100644 --- a/lang/en/docs/properties/data/list.md +++ b/lang/en/docs/properties/data/list.md @@ -1,528 +1,528 @@ # Schemas for Material Properties -We present throughout this page a list of JSON schemas and example representations concerning [properties](../../properties-directory/overview.md). The reader is referred to their respective documentation pages, accessible by clicking the headers below, for a review of their underlying physical significance. +We present throughout this page a list of JSON schemas and example representations concerning [properties]({{ reference_url }}/properties-directory/overview/). The reader is referred to their respective documentation pages, accessible by clicking the headers below, for a review of their underlying physical significance. ## Scalar Properties -### [Total Energy](../../properties-directory/scalar/total-energy.md) +### [Total Energy]({{ reference_url }}/properties-directory/scalar/total-energy/) Total energy contains the total energy of the unit cell. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/scalar/total_energy.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/scalar/total_energy.json" ``` -### [Zero Point Energy](../../properties-directory/scalar/zero-point-energy.md) +### [Zero Point Energy]({{ reference_url }}/properties-directory/scalar/zero-point-energy/) Some residual thermal vibrational energy is left at zero temperature due to quantum effects, and is referred to as Zero Point Energy. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/scalar/zero_point_energy.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/scalar/zero_point_energy.json" ``` -### [Fermi Energy](../../properties-directory/scalar/fermi-energy.md) +### [Fermi Energy]({{ reference_url }}/properties-directory/scalar/fermi-energy/) The Fermi energy marks the highest occupied energy level in a solid. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/scalar/fermi_energy.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/scalar/fermi_energy.json" ``` -### [Total Energy Contributions](../../properties-directory/scalar/total-energy.md#total-energy-contributions) +### [Total Energy Contributions]({{ reference_url }}/properties-directory/scalar/total-energy/#total-energy-contributions) Total energy contributions contains information about the components in the total energy of the unit cell. The contributions available will depend on the type of method and software used. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/non-scalar/total_energy_contributions.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/non-scalar/total_energy_contributions.json" ``` -### [Formation Energy](../../properties-directory/scalar/formation-energy.md) +### [Formation Energy]({{ reference_url }}/properties-directory/scalar/formation-energy/) The Formation energy represents the energy required to create a defect in an otherwise perfect solid structure. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/scalar/formation_energy.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/scalar/formation_energy.json" ``` -### [Surface Energy](../../properties-directory/scalar/surface-energy.md) +### [Surface Energy]({{ reference_url }}/properties-directory/scalar/surface-energy/) The energy of a surface can also be computed. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/scalar/surface_energy.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/scalar/surface_energy.json" ``` -### [Pressure](../../properties-directory/scalar/pressure.md) +### [Pressure]({{ reference_url }}/properties-directory/scalar/pressure/) Pressure contains the average internal pressure of the unit cell. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/scalar/pressure.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/scalar/pressure.json" ``` -### [Total Force](../../properties-directory/scalar/total-force.md) +### [Total Force]({{ reference_url }}/properties-directory/scalar/total-force/) This is the total average force present within the crystal structure. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/scalar/total_force.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/scalar/total_force.json" ``` -### [Valence Band Offset](../../properties-directory/scalar/valence-band-offset.md) +### [Valence Band Offset]({{ reference_url }}/properties-directory/scalar/valence-band-offset/) The valence band offset represents the energy difference of valence bands across a heterostructure interface. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/scalar/valence_band_offset.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/scalar/valence_band_offset.json" ``` ## Non-Scalar Properties -### [Bandstructure](../../properties-directory/non-scalar/bandstructure.md) +### [Bandstructure]({{ reference_url }}/properties-directory/non-scalar/bandstructure/) Band structure shows the energy of electronic states (bands) as a function of k-point position throughout the cell. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/non-scalar/band_structure.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/non-scalar/band_structure.json" ``` -### [Band Gaps](../../properties-directory/non-scalar/band-gaps.md) +### [Band Gaps]({{ reference_url }}/properties-directory/non-scalar/band-gaps/) Band gap is the difference in energy from the highest occupied electronic state (Fermi energy at 0K) to the lowest unoccupied state. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/non-scalar/band_gaps.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/non-scalar/band_gaps.json" ``` -### [Electronic Density of States](../../properties-directory/non-scalar/electronic-dos.md) +### [Electronic Density of States]({{ reference_url }}/properties-directory/non-scalar/electronic-dos/) Density of states contains information on the number of electronic states as a function of energy. It may include the atom resolved partial density of states and electron states in some cases. In addition it may also contain information about each atom’s spin state as well. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/non-scalar/density_of_states.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/non-scalar/density_of_states.json" ``` -### [File Content](../../properties-directory/non-scalar/file-content.md) +### [File Content]({{ reference_url }}/properties-directory/non-scalar/file-content/) Tags a file for display on the results tab of the web-app. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/non-scalar/file_content.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/non-scalar/file_content.json" ``` -### [Reaction Energy Profile](../../properties-directory/non-scalar/reaction-energy-profile.md) +### [Reaction Energy Profile]({{ reference_url }}/properties-directory/non-scalar/reaction-energy-profile/) The energy profile of a chemical reaction is a representation of its energetic pathway, followed by the reactants as they are transformed into products. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/non-scalar/reaction_energy_profile.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/non-scalar/reaction_energy_profile.json" ``` -### [Reaction Energy Barrier](../../properties-directory/scalar/reaction-energy-barrier.md) +### [Reaction Energy Barrier]({{ reference_url }}/properties-directory/scalar/reaction-energy-barrier/) The Reaction Energy Barrier marks the highest energy state encountered during the course of the progress of a chemical reaction. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/scalar/reaction_energy_barrier.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/scalar/reaction_energy_barrier.json" ``` -### [Phonon Dispersions](../../properties-directory/non-scalar/phonon-dispersions.md) +### [Phonon Dispersions]({{ reference_url }}/properties-directory/non-scalar/phonon-dispersions/) Lattice vibrations can be plotted in the form of phonon frequency dispersion plots across the reciprocal k-space of the crystal structure. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/non-scalar/phonon_dispersions.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/non-scalar/phonon_dispersions.json" ``` -### [Phonon Density of States](../../properties-directory/non-scalar/phonon-dos.md) +### [Phonon Density of States]({{ reference_url }}/properties-directory/non-scalar/phonon-dos/) The Density of States for phonons can also be computed. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/non-scalar/phonon_dos.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/non-scalar/phonon_dos.json" ``` -### [Stress Tensor](../../properties-directory/non-scalar/stress-tensor.md) +### [Stress Tensor]({{ reference_url }}/properties-directory/non-scalar/stress-tensor/) Stress tensor contains a 3x3 matrix of the stress components of the unit cell. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/non-scalar/stress_tensor.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/non-scalar/stress_tensor.json" ``` -### [Workflow](../../properties-directory/non-scalar/workflow.md) +### [Workflow]({{ reference_url }}/properties-directory/non-scalar/workflow/) Some jobs can result in the generation of new workflows, which will be placed in the user's account. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/workflow.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/workflow.json" ``` ## Elemental Properties -### [Atomic Radius](../../properties-directory/elemental/atomic-radius.md) +### [Atomic Radius]({{ reference_url }}/properties-directory/elemental/atomic-radius/) The atomic radius represents the average distance between the nucleus of an atom and the edges of its surrounding electron cloud. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/elemental/atomic_radius.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/elemental/atomic_radius.json" ``` -### [Electronegativity](../../properties-directory/elemental/electronegativity.md) +### [Electronegativity]({{ reference_url }}/properties-directory/elemental/electronegativity/) The electronegativity describes the capacity of an atom to attract the electrons involved in chemical bonding. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/elemental/electronegativity.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/elemental/electronegativity.json" ``` -### [Ionization Potential](../../properties-directory/elemental/ionization-potential.md) +### [Ionization Potential]({{ reference_url }}/properties-directory/elemental/ionization-potential/) The ionization energy (or potential) measures the energy required to strip an atom from its most loosely bound valence electron. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/elemental/ionization_potential.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/elemental/ionization_potential.json" ``` ## Structural Properties -### [Atomic Forces](../../properties-directory/structural/atomic-forces.md) +### [Atomic Forces]({{ reference_url }}/properties-directory/structural/atomic-forces/) Forces may exist between atoms in a crystal structure if they are displaced away from their equilibrium configuration. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/structural/atomic_forces.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/structural/atomic_forces.json" ``` -### [Atomic Coordinates](../../properties-directory/structural/basis.md) +### [Atomic Coordinates]({{ reference_url }}/properties-directory/structural/basis/) Contains information about the coordinates of atoms within the unit cell by id. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/structural/basis/atomic_coordinates.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/structural/basis/atomic_coordinates.json" ``` -### [Atomic Elements](../../properties-directory/structural/basis.md) +### [Atomic Elements]({{ reference_url }}/properties-directory/structural/basis/) Contains an array of the elements in the unit cell and the atom id’s association with each atom. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/structural/basis/atomic_element.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/structural/basis/atomic_element.json" ``` -### [Atomic Constraints](../../properties-directory/structural/basis.md) +### [Atomic Constraints]({{ reference_url }}/properties-directory/structural/basis/) Contains information about the spatial constraints on the movement of atoms. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/structural/basis/atomic_constraints.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/structural/basis/atomic_constraints.json" ``` -### [Basis](../../properties-directory/structural/basis.md) +### [Basis]({{ reference_url }}/properties-directory/structural/basis/) Basis defines elemental and geometrical constitution of the unit cell. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/structural/basis.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/structural/basis.json" ``` -### [Bravais Lattice](../../properties-directory/structural/lattice.md) +### [Bravais Lattice]({{ reference_url }}/properties-directory/structural/lattice/) Lattice Bravais holds information about the three-dimensional periodic structure specified implicitly through lengths and angles between lattice vectors, and their units. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/structural/lattice/lattice_bravais.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/structural/lattice/lattice_bravais.json" ``` -### [Lattice Vectors](../../properties-directory/structural/lattice.md) +### [Lattice Vectors]({{ reference_url }}/properties-directory/structural/lattice/) Lattice vectors holds information about the three-dimensional periodic structure explicitly, by specifying the three lattice vectors and their units. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/structural/lattice/lattice_vectors.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/structural/lattice/lattice_vectors.json" ``` -### [Density](../../properties-directory/structural/lattice.md#volume-and-density) +### [Density]({{ reference_url }}/properties-directory/structural/lattice/#volume-and-density) The Density of the material is defined by the sum of the atomic masses within the unit cell, divided by its volume. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/structural/density.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/structural/density.json" ``` -### [Elemental Ratio](../../properties-directory/structural/basis.md#elemental-ratio) +### [Elemental Ratio]({{ reference_url }}/properties-directory/structural/basis/#elemental-ratio) The elemental ratio is given by the fraction of all atoms in a crystal which are composed of a certain element. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/structural/elemental_ratio.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/structural/elemental_ratio.json" ``` -### [InChI](../../properties-directory/structural/inchi.md) +### [InChI]({{ reference_url }}/properties-directory/structural/inchi/) The International Chemical Identifier[^1] used to identify molecules. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/structural/inchi.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/structural/inchi.json" ``` -### [InChIKey](../../properties-directory/structural/inchi-key.md) +### [InChIKey]({{ reference_url }}/properties-directory/structural/inchi-key/) The fixed-length non-human readable string derived from an **InChI**. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/structural/inchi_key.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/structural/inchi_key.json" ``` -### [Magnetic Moments](../../properties-directory/structural/magnetic-moment.md) +### [Magnetic Moments]({{ reference_url }}/properties-directory/structural/magnetic-moment/) The magnetic moment of ferromagnetic materials can also be computed. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/structural/magnetic_moments.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/structural/magnetic_moments.json" ``` -### [P Norm](../../properties-directory/structural/lattice.md) +### [P Norm]({{ reference_url }}/properties-directory/structural/lattice/) The P norm measures how homogeneous a material is in terms of its chemical composition. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/structural/p-norm.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/structural/p-norm.json" ``` -### [Symmetry](../../properties-directory/structural/symmetry.md) +### [Symmetry]({{ reference_url }}/properties-directory/structural/symmetry/) The symmetry of the structure, indicating the point group and space group. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/structural/symmetry.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/structural/symmetry.json" ``` -### [Volume](../../properties-directory/structural/lattice.md) +### [Volume]({{ reference_url }}/properties-directory/structural/lattice/) The volume of the unit cell is given by the scalar triple product of the lattice vectors. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/structural/volume.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/structural/volume.json" ``` diff --git a/lang/en/docs/properties/data/overview.md b/lang/en/docs/properties/data/overview.md index 34a97b146..7ef4bbcb0 100644 --- a/lang/en/docs/properties/data/overview.md +++ b/lang/en/docs/properties/data/overview.md @@ -1,12 +1,12 @@ # Properties Data -We make use of the data convention, introduced [in this page](../../data-structured/convention.md), to organize the information related to properties. +We make use of the data convention, introduced [in this page]({{ data_url }}/data-structured/convention/), to organize the information related to properties. -## [JSON Schemas and Examples](../../data-structured/convention.md) +## [JSON Schemas and Examples]({{ data_url }}/data-structured/convention/) -We provide below an example of a [**JSON schema**](../../data-structured/convention.md) for a material property. The reader is referred to the JSON external documentation [^1] [^2] for the explanation of the primitive types and schema keywords. +We provide below an example of a [**JSON schema**]({{ data_url }}/data-structured/convention/) for a material property. The reader is referred to the JSON external documentation [^1] [^2] for the explanation of the primitive types and schema keywords. -Also listed below, is an example of a JSON representation of the [total energy](../../properties-directory/scalar/total-energy.md), which can validated by the schema. It consists in a scalar numerical **value**, which is expressed in **units** of electronVolts (eV). +Also listed below, is an example of a JSON representation of the [total energy]({{ reference_url }}/properties-directory/scalar/total-energy/), which can validated by the schema. It consists in a scalar numerical **value**, which is expressed in **units** of electronVolts (eV).
@@ -14,12 +14,12 @@ Also listed below, is an example of a JSON representation of the [total energy]( === "Schema" - ``` json + ```json --8<-- "data/esse/schema/properties_directory/scalar/total_energy.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/properties_directory/scalar/total_energy.json" ``` diff --git a/lang/en/docs/properties/data/periodic-table.md b/lang/en/docs/properties/data/periodic-table.md index c28bf27ae..14f3fa562 100644 --- a/lang/en/docs/properties/data/periodic-table.md +++ b/lang/en/docs/properties/data/periodic-table.md @@ -1,9 +1,9 @@ # Periodic Table Data -We store the **elemental information** associated with each element in the Periodic Table on our database. This information is retrieved, for example, at the moment of the [Workflow Creation](../../workflow-designer/overview.md) to populate elements-specific data (eg. atomic mass). +We store the **elemental information** associated with each element in the Periodic Table on our database. This information is retrieved, for example, at the moment of the [Workflow Creation]({{ interface_url }}/workflow-designer/overview/) to populate elements-specific data (eg. atomic mass). We assembled the data using the open-source Ref. [^1] below. ## Links -[^1]: [Exabyte.io Periodic Table Data, JSON, Github Repository](https://github.com/Exabyte-io/periodic-table) +[^1]: [Exabyte.io Periodic Table Data, JSON, Github Repository](https://github.com/mat3ra/periodic-table) diff --git a/lang/en/docs/properties/lifecycle/extractor.md b/lang/en/docs/properties/lifecycle/extractor.md index efb7cb2db..93427435e 100644 --- a/lang/en/docs/properties/lifecycle/extractor.md +++ b/lang/en/docs/properties/lifecycle/extractor.md @@ -1,18 +1,18 @@ # Extraction of Properties -The extraction of raw data from simulations computations consists in processing the [output files](../../data-on-disk/overview.md) of [modeling engines](../../software/components.md) with the help of post-processing software. This is typically done in order to identify the desired properties, and store them in a database for future reference. +The extraction of raw data from simulations computations consists in processing the [output files]({{ resources_url }}/data-on-disk/overview/) of [modeling engines]({{ reference_url }}/software/components/) with the help of post-processing software. This is typically done in order to identify the desired properties, and store them in a database for future reference. ## Extractor Scripts -Computational scientists are usually familiar with this concept, and often have a set of **scripts** for extracting such raw numerical data from simulation outputs. We refer to such scripts as **"Extractors"**. Our platform follows exactly the same approach, and forms [structured data](../../data-structured/overview.md) according to the [Data Convention](../../data-structured/convention.md) to subsequently store Materials properties in the database. +Computational scientists are usually familiar with this concept, and often have a set of **scripts** for extracting such raw numerical data from simulation outputs. We refer to such scripts as **"Extractors"**. Our platform follows exactly the same approach, and forms [structured data]({{ data_url }}/data-structured/overview/) according to the [Data Convention]({{ data_url }}/data-structured/convention/) to subsequently store Materials properties in the database. Such raw extracted data typically needs to be further **refined** for a better comprehension of its physical relevance and accuracy. We describe how this issue is confronted on our platform [in a separate documentation page](refinement.md). ## Example -For example, the retrieval of the [total energy](../../properties-directory/scalar/total-energy.md) in a [Quantum Espresso](../../software-directory/modeling/quantum-espresso/overview.md) output file can be done by looking for the "!" character, and extracting the ensuing content of the same line. Alternatively, a corresponding XML file can be parsed. +For example, the retrieval of the [total energy]({{ reference_url }}/properties-directory/scalar/total-energy/) in a [Quantum Espresso]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) output file can be done by looking for the "!" character, and extracting the ensuing content of the same line. Alternatively, a corresponding XML file can be parsed. -Below we show an excerpt of a Quantum ESPRESSO standard output file, that can serve as input for the extractor explained above. The line containing the total energy is displayed at the center with its preceding exclamation mark. This input text is then parsed by the **Extractor**, and the resulting [structured](../data/overview.md) data is generated and further stored in database. +Below we show an excerpt of a Quantum ESPRESSO standard output file, that can serve as input for the extractor explained above. The line containing the total energy is displayed at the center with its preceding exclamation mark. This input text is then parsed by the **Extractor**, and the resulting [structured]({{ data_url }}/properties/data/overview/) data is generated and further stored in database. ```json tab="Extractor Input" ... diff --git a/lang/en/docs/properties/lifecycle/refinement.md b/lang/en/docs/properties/lifecycle/refinement.md index 54681b8d3..2ed1b905b 100644 --- a/lang/en/docs/properties/lifecycle/refinement.md +++ b/lang/en/docs/properties/lifecycle/refinement.md @@ -18,20 +18,20 @@ We categorize the various degrees of refinement of extracted Materials propertie ### Non-Refinable Property Example -For the case of the [pseudopotential DFT model](../../models-directory/dft/overview.md) the **[Fermi Energy](../../properties-directory/scalar/total-energy.md)**, for example, is excluded from being classed as Refined, and therefore remains treated as Raw. This is due to the fact that its absolute value makes no physical meaning, but rather depends heavily on the choice of the pseudopotential, on the Exchange-correlation functional approximation, and on other computational [methods](../../methods/overview.md) being employed. +For the case of the [pseudopotential DFT model]({{ reference_url }}/models-directory/dft/overview/) the **[Fermi Energy]({{ reference_url }}/properties-directory/scalar/total-energy/)**, for example, is excluded from being classed as Refined, and therefore remains treated as Raw. This is due to the fact that its absolute value makes no physical meaning, but rather depends heavily on the choice of the pseudopotential, on the Exchange-correlation functional approximation, and on other computational [methods]({{ reference_url }}/methods/overview/) being employed. ### Refined Property Example -The [band gap](../../properties-directory/non-scalar/bandstructure.md) is instead considered a refined property, since it is a relative energy difference between the highest electron-occupied and lowest unoccupied levels in the bandstructure of the material. Therefore its computed value can be compared directly with experiments, with a reliability limited only by its numerical precision. +The [band gap]({{ reference_url }}/properties-directory/non-scalar/bandstructure/) is instead considered a refined property, since it is a relative energy difference between the highest electron-occupied and lowest unoccupied levels in the bandstructure of the material. Therefore its computed value can be compared directly with experiments, with a reliability limited only by its numerical precision. -> **NOTE**: exception for "Total Energy". We class the [Total Energy](../../properties-directory/scalar/total-energy.md) of the material as refined property, despite its absolute value computed with DFT also being of no physical relevance. This is done due to its importance in formulating the Equation of State of the Material, where it is normally compared relative to its ground-state value under equilibrium conditions. +> **NOTE**: exception for "Total Energy". We class the [Total Energy]({{ reference_url }}/properties-directory/scalar/total-energy/) of the material as refined property, despite its absolute value computed with DFT also being of no physical relevance. This is done due to its importance in formulating the Equation of State of the Material, where it is normally compared relative to its ground-state value under equilibrium conditions. ## Best Properties The property classified as "Best" is defined as the computation of a given refined material property which has achieved the best **numerical precision**. The comparison is made with all other computations for that particular property performed across the Exabyte platform per user and by all users combined. -A description of how we estimate the precision of properties can be found [in this page](../../methods/data.md). +A description of how we estimate the precision of properties can be found [in this page]({{ data_url }}/methods/data/). ## Appearance in User Interface -Both Refined and Best properties can be displayed in [Materials Explorer](../../materials/ui/explorer.md), for convenient consultation by the user, after having been suitably selected through the [columns selector](../../entities-general/ui/explorer.md#columns-selector). +Both Refined and Best properties can be displayed in [Materials Explorer]({{ interface_url }}/materials/ui/explorer/), for convenient consultation by the user, after having been suitably selected through the [columns selector]({{ interface_url }}/entities-general/ui/explorer/#columns-selector). diff --git a/lang/en/docs/properties/lifecycle/retrieval.md b/lang/en/docs/properties/lifecycle/retrieval.md index d9b04494f..25424669c 100644 --- a/lang/en/docs/properties/lifecycle/retrieval.md +++ b/lang/en/docs/properties/lifecycle/retrieval.md @@ -4,12 +4,12 @@ Properties can be retrieved for inspection through any of the following means. ## Web Application -Properties can be retrieved as the output of [Jobs](../../jobs/overview.md), or by inspecting the entries listed in the account-owned collection of [Materials](../../materials/overview.md). The former option can be accessed under the [Results Tab](../../jobs/ui/results-tab.md) of [Jobs Viewer](../../jobs/ui/viewer.md), whereas the latter is available under the [Properties Explorer](../ui/explorer.md) interface. +Properties can be retrieved as the output of [Jobs](../../jobs/overview.md), or by inspecting the entries listed in the account-owned collection of [Materials](../../materials/overview.md). The former option can be accessed under the [Results Tab]({{ interface_url }}/jobs/ui/results-tab/) of [Jobs Viewer]({{ interface_url }}/jobs/ui/viewer/), whereas the latter is available under the [Properties Explorer]({{ interface_url }}/properties/ui/explorer/) interface. ## REST API -We explain how to retrieve properties programmatically via the REST API in a [separate documentation section](../../rest-api/overview.md). +We explain how to retrieve properties programmatically via the REST API in a [separate documentation section]({{ developers_url }}/rest-api/overview/). ## Data on Disk -Properties can also be retrieved directly from the simulation data files stored on the [compute cluster disks](../../infrastructure/clusters/overview.md), as explained [here](../../data-on-disk/overview.md). +Properties can also be retrieved directly from the simulation data files stored on the [compute cluster disks]({{ resources_url }}/infrastructure/clusters/overview/), as explained [here]({{ resources_url }}/data-on-disk/overview/). diff --git a/lang/en/docs/properties/overview.md b/lang/en/docs/properties/overview.md index 9ed395159..9555cd42f 100644 --- a/lang/en/docs/properties/overview.md +++ b/lang/en/docs/properties/overview.md @@ -4,28 +4,28 @@ The present section of the documentation explains our approach to organizing, st ## Definition -**"Property"** is any measurable quantity which provides information about the entity under consideration. Properties can hold information about [Materials](../materials/overview.md) and [Workflows](../workflows/overview.md) as demonstrated [here](../getting-started/important-concepts.md) +**"Property"** is any measurable quantity which provides information about the entity under consideration. Properties can hold information about [Materials](../materials/overview.md) and [Workflows](../workflows/overview.md) as demonstrated [here]({{ guide_url }}/getting-started/concepts/) -Exact set of properties that have to be supplied to, and can be extracted as a result of, a [Job](../jobs/overview.md) computation, can vary depending on the Workflow type and on the [models](../models/overview.md)/[methods](../methods/overview.md) included therein. +Exact set of properties that have to be supplied to, and can be extracted as a result of, a [Job](../jobs/overview.md) computation, can vary depending on the Workflow type and on the [models]({{ reference_url }}/models/overview/)/[methods]({{ reference_url }}/methods/overview/) included therein. -## [List of Properties](../properties-directory/overview.md) +## [List of Properties]({{ reference_url }}/properties-directory/overview/) -We have listed and described the properties available for computation on our platform [in this section](../properties-directory/overview.md). +We have listed and described the properties available for computation on our platform [in this section]({{ reference_url }}/properties-directory/overview/). ## [Classification](classification/overview.md) We explain how properties can be classified into different categories [here](classification/overview.md). -## [Data](data/overview.md) +## [Data]({{ data_url }}/properties/data/overview/) -For an example of a JSON structure-based representation of properties, and of the associated validating/descriptive schema, please consult the [Data section](data/overview.md). +For an example of a JSON structure-based representation of properties, and of the associated validating/descriptive schema, please consult the [Data section]({{ data_url }}/properties/data/overview/). ## [Lifecycle](lifecycle/overview.md) We describe the lifecycle that properties go through in order to be extracted from simulation output, and then subsequently refined and retrieved, [in this section](lifecycle/overview.md). -## [User Interface](ui/explorer.md) +## [User Interface]({{ interface_url }}/properties/ui/explorer/) -Properties are presented in special panels within the user interface of the [Job Viewer](../jobs/ui/viewer.md), as introduced [here](ui/viewer.md). +Properties are presented in special panels within the user interface of the [Job Viewer]({{ interface_url }}/jobs/ui/viewer/), as introduced [here]({{ interface_url }}/properties/ui/viewer/). -These properties can also be reviewed under a dedicated [Explorer-type interface](../entities-general/ui/explorer.md) for each Material stored in the account-owned [collection](../accounts/collections.md). We explain how to retrieve and inspect the contents of this Properties Explorer [in this page](ui/explorer.md). +These properties can also be reviewed under a dedicated [Explorer-type interface]({{ interface_url }}/entities-general/ui/explorer/) for each Material stored in the account-owned [collection](../accounts/collections.md). We explain how to retrieve and inspect the contents of this Properties Explorer [in this page]({{ interface_url }}/properties/ui/explorer/). diff --git a/lang/en/docs/properties/ui/explorer.md b/lang/en/docs/properties/ui/explorer.md index 67dfc63aa..c2cc8213c 100644 --- a/lang/en/docs/properties/ui/explorer.md +++ b/lang/en/docs/properties/ui/explorer.md @@ -1,6 +1,6 @@ # Properties Explorer -The list of calculated Material [properties](../../properties-directory/overview.md), associated with any entry listed under [Materials Explorer](../../materials/ui/explorer.md), is displayed below the footer of the corresponding [Viewer](../../materials/ui/viewer.md) page. It is presented to the user in a separate [Explorer-type Interface](../../entities-general/ui/explorer.md), which we refer to as the "Properties Explorer". +The list of calculated Material [properties]({{ reference_url }}/properties-directory/overview/), associated with any entry listed under [Materials Explorer](../../materials/ui/explorer.md), is displayed below the footer of the corresponding [Viewer](../../materials/ui/viewer.md) page. It is presented to the user in a separate [Explorer-type Interface](../../entities-general/ui/explorer.md), which we refer to as the "Properties Explorer". ## Example Appearance @@ -14,6 +14,6 @@ Specific features of this Explorer consist in the nature of the information disp The different aspects of this property-specific information can be selected from the appropriate [columns selector](../../entities-general/ui/explorer.md#columns-selector) as shown in the image below, where only the property-specific options have been left ticked. -Such specific options include information on the [simulation engine](../../software/components.md), [model](../../models/overview.md), [method](../../methods/overview.md) and [precision](../../methods/data.md) pertaining to the corresponding computed property. The numerical value of the property is also displayed here, when it is applicable in the case of [scalar quantities](../classification/general.md). +Such specific options include information on the [simulation engine]({{ reference_url }}/software/components/), [model]({{ reference_url }}/models/overview/), [method]({{ reference_url }}/methods/overview/) and [precision]({{ data_url }}/methods/data/) pertaining to the corresponding computed property. The numerical value of the property is also displayed here, when it is applicable in the case of [scalar quantities]({{ reference_url }}/properties/classification/general/). ![Property Specific Columns](../../images/properties/property-specific-columns.png "Property Specific Columns") diff --git a/lang/en/docs/properties/ui/viewer.md b/lang/en/docs/properties/ui/viewer.md index 5b2e6337b..18dedd19b 100644 --- a/lang/en/docs/properties/ui/viewer.md +++ b/lang/en/docs/properties/ui/viewer.md @@ -1,10 +1,10 @@ # Properties Viewer -The final results of [properties](../overview.md) can be inspected by the user under the interface of the [Results Tab](../../jobs/ui/results-tab.md) within [Jobs Viewer](../../jobs/ui/viewer.md), after the results have been extracted from the output of simulations. +The final results of [properties]({{ reference_url }}/properties/overview/) can be inspected by the user under the interface of the [Results Tab](../../jobs/ui/results-tab.md) within [Jobs Viewer](../../jobs/ui/viewer.md), after the results have been extracted from the output of simulations. ## Property Examples -We explain how each property is presented under such an interface in their dedicated documentation pages, introduced [in this part of the documentation](../../properties-directory/overview.md). +We explain how each property is presented under such an interface in their dedicated documentation pages, introduced [in this part of the documentation]({{ reference_url }}/properties-directory/overview/). ## Export as Images diff --git a/lang/en/docs/remote-connection/actions-rd/browse.md b/lang/en/docs/remote-connection/actions-rd/browse.md index abeae8f48..8a0f1806a 100644 --- a/lang/en/docs/remote-connection/actions-rd/browse.md +++ b/lang/en/docs/remote-connection/actions-rd/browse.md @@ -1,10 +1,10 @@ # Directory Browsing in Remote Desktop -Directories can be browsed in [Remote Desktop](../remote-desktop.md) under a [standard Linux files explorer interface](../remote-desktop.md#linux-environment). A general review of the directory structure encountered under this environment can be found [here](../../data-on-disk/directories.md). +Directories can be browsed in [Remote Desktop](../remote-desktop.md) under a [standard Linux files explorer interface](../remote-desktop.md#linux-environment). A general review of the directory structure encountered under this environment can be found [here]({{ resources_url }}/data-on-disk/directories/). ## Animation -In the following animation, we demonstrate how to navigate in and out of some directories present under the Remote Desktop interface, starting from the main [Home Folder](../../infrastructure/login/directories.md). +In the following animation, we demonstrate how to navigate in and out of some directories present under the Remote Desktop interface, starting from the main [Home Folder]({{ resources_url }}/infrastructure/login/directories/). diff --git a/lang/en/docs/remote-connection/actions-rd/open-app.md b/lang/en/docs/remote-connection/actions-rd/open-app.md index de5c31a63..3939d15fc 100644 --- a/lang/en/docs/remote-connection/actions-rd/open-app.md +++ b/lang/en/docs/remote-connection/actions-rd/open-app.md @@ -1,11 +1,11 @@ # Open Applications in Remote Desktop -Useful graphical analysis and visualization [software](../../software-directory/overview.md) is available under the [Remote Desktop](../remote-desktop.md) interface of our platform, accessible via the `Other` category under the top-left `Applications` menu of the interface (except for the [VMD](../../software-directory/analysis/vmd.md) application, which is listed under the `Graphics` category instead of `Other`). +Useful graphical analysis and visualization [software]({{ reference_url }}/software-directory/overview/) is available under the [Remote Desktop](../remote-desktop.md) interface of our platform, accessible via the `Other` category under the top-left `Applications` menu of the interface (except for the [VMD]({{ reference_url }}/software-directory/analysis/vmd/) application, which is listed under the `Graphics` category instead of `Other`). -This set of software is particularly useful for graphically visualizing the crystal structures of the [materials](../../materials/overview.md) involved in simulations. +This set of software is particularly useful for graphically visualizing the crystal structures of the [materials]({{ reference_url }}/materials/overview/) involved in simulations. ## Animation: Open Example Application - "VESTA" -Here, we show how to open the [VESTA](../../software-directory/analysis/vesta.md) visualization software under Remote Desktop, by way of an example. +Here, we show how to open the [VESTA]({{ reference_url }}/software-directory/analysis/vesta/) visualization software under Remote Desktop, by way of an example. diff --git a/lang/en/docs/remote-connection/actions-rd/overview.md b/lang/en/docs/remote-connection/actions-rd/overview.md index ea5cbad97..a282037f2 100644 --- a/lang/en/docs/remote-connection/actions-rd/overview.md +++ b/lang/en/docs/remote-connection/actions-rd/overview.md @@ -8,4 +8,4 @@ We offer some examples on how directories can be browsed in Remote Desktop [here ## [Open Applications](open-app.md) -The graphical analysis and visualization [software](../../software-directory/overview.md) available within our platform can be accessed under Remote Desktop, as documented in the example contained [in this page](open-app.md). +The graphical analysis and visualization [software]({{ reference_url }}/software-directory/overview/) available within our platform can be accessed under Remote Desktop, as documented in the example contained [in this page](open-app.md). diff --git a/lang/en/docs/remote-connection/actions/access-data.md b/lang/en/docs/remote-connection/actions/access-data.md index 1320e3b7b..08e21f1a4 100644 --- a/lang/en/docs/remote-connection/actions/access-data.md +++ b/lang/en/docs/remote-connection/actions/access-data.md @@ -1,9 +1,9 @@ # Access Data in Web Interface with Dropbox -Among its other functions, the [Dropbox](../../data-in-objectstorage/dropbox.md) folder allows the user to exchange data back and forth between the [Remote Desktop](../remote-desktop.md) or [Web Terminal](../web-terminal.md) remote connection methods, and the main [Web Interface](../../ui/overview.md) of our platform. +Among its other functions, the [Dropbox]({{ resources_url }}/data-in-objectstorage/dropbox/) folder allows the user to exchange data back and forth between the [Remote Desktop](../remote-desktop.md) or [Web Terminal](../web-terminal.md) remote connection methods, and the main [Web Interface]({{ interface_url }}/ui/overview/) of our platform. ## Animation -In the animation below, we show how to transfer (copy) files to Dropbox within the Remote Desktop, and later retrieve them inside the Web Interface under the [Dropbox dedicated page](../../data-in-objectstorage/ui/dropbox-page.md). +In the animation below, we show how to transfer (copy) files to Dropbox within the Remote Desktop, and later retrieve them inside the Web Interface under the [Dropbox dedicated page]({{ interface_url }}/data-in-objectstorage/ui/dropbox-page/). diff --git a/lang/en/docs/remote-connection/actions/copy-paste.md b/lang/en/docs/remote-connection/actions/copy-paste.md index a0b00bcbe..fba76ae6b 100644 --- a/lang/en/docs/remote-connection/actions/copy-paste.md +++ b/lang/en/docs/remote-connection/actions/copy-paste.md @@ -4,9 +4,9 @@ The Copy/Pasting of text to/from the [Remote Desktop](../remote-desktop.md) or [ ## Paste Text into Remote Interface -In the following animation, we show how to copy and paste the path of a simulation output file listed under [Files Explorer](../../data-in-objectstorage/ui/explorer.md) to the Web Terminal (the same considerations apply also to the case of Remote Desktop). +In the following animation, we show how to copy and paste the path of a simulation output file listed under [Files Explorer]({{ interface_url }}/data-in-objectstorage/ui/explorer/) to the Web Terminal (the same considerations apply also to the case of Remote Desktop). -We first copy its path into the clipboard by performing the corresponding [action](../../data-in-objectstorage/actions/copy-path.md) under Files Explorer. We then [open the Remote-connection Sidebar](sidebar.md) under Web Terminal and paste the file path in it. This in turn makes the file path available under the Web Terminal interface through a right-mouse click, which allows us for example to open the file with a command line text editor (like nano) and to inspect its contents (something which cannot be done under the Web Interface). +We first copy its path into the clipboard by performing the corresponding [action]({{ interface_url }}/data-in-objectstorage/actions/copy-path/) under Files Explorer. We then [open the Remote-connection Sidebar](sidebar.md) under Web Terminal and paste the file path in it. This in turn makes the file path available under the Web Terminal interface through a right-mouse click, which allows us for example to open the file with a command line text editor (like nano) and to inspect its contents (something which cannot be done under the Web Interface). diff --git a/lang/en/docs/remote-connection/actions/download.md b/lang/en/docs/remote-connection/actions/download.md index 13173aaa3..a10271258 100644 --- a/lang/en/docs/remote-connection/actions/download.md +++ b/lang/en/docs/remote-connection/actions/download.md @@ -2,11 +2,11 @@ ## Instructions for Remote Desktop -Starting from [Remote Desktop](../remote-desktop.md), the user can download files (of limited size) by putting them in the [Dropbox](../../data-in-objectstorage/dropbox.md) folder first, which has an overall capacity of 1 Gb. Such files can later be downloaded from the [Web Interface](../../ui/overview.md) by clicking their corresponding entries listed under the [Files Explorer](../../data-in-objectstorage/ui/explorer.md) interface of the [Dropbox Page](../../data-in-objectstorage/ui/dropbox-page.md), as explained [here](../../data-in-objectstorage/actions/download.md). +Starting from [Remote Desktop](../remote-desktop.md), the user can download files (of limited size) by putting them in the [Dropbox]({{ resources_url }}/data-in-objectstorage/dropbox/) folder first, which has an overall capacity of 1 Gb. Such files can later be downloaded from the [Web Interface]({{ interface_url }}/ui/overview/) by clicking their corresponding entries listed under the [Files Explorer]({{ interface_url }}/data-in-objectstorage/ui/explorer/) interface of the [Dropbox Page]({{ interface_url }}/data-in-objectstorage/ui/dropbox-page/), as explained [here]({{ interface_url }}/data-in-objectstorage/actions/download/). ## Animation -We demonstrate how to download a file called "remote-connection.yaml", present under the [Login Home](../../infrastructure/login/directories.md) directory, starting from the Remote Desktop interface. After copying the file to the Dropbox folder, we then retrieve it under the Web Interface. +We demonstrate how to download a file called "remote-connection.yaml", present under the [Login Home]({{ resources_url }}/infrastructure/login/directories/) directory, starting from the Remote Desktop interface. After copying the file to the Dropbox folder, we then retrieve it under the Web Interface. @@ -18,7 +18,7 @@ From the [Web Terminal](../web-terminal.md) on the other hand, the user can down exadownload ``` -Typing this command under the [Command Line Interface](../../cli/overview.md) downloads the file directly to the default location for saving Downloaded content set by the web browser being employed. +Typing this command under the [Command Line Interface]({{ cli_url }}/cli/overview/) downloads the file directly to the default location for saving Downloaded content set by the web browser being employed. ## Animation diff --git a/lang/en/docs/remote-connection/actions/open-desktop.md b/lang/en/docs/remote-connection/actions/open-desktop.md index 004e61bc6..d2c97ea68 100644 --- a/lang/en/docs/remote-connection/actions/open-desktop.md +++ b/lang/en/docs/remote-connection/actions/open-desktop.md @@ -1,8 +1,8 @@ # Open / Close Remote Desktop -The [Remote Desktop](../remote-desktop.md) connection method for accessing our platform is accessible under the corresponding `Remote Desktop` option available in the [right-hand sidebar menu](../../ui/right-sidebar.md) of the [Web Interface](../../ui/overview.md). +The [Remote Desktop](../remote-desktop.md) connection method for accessing our platform is accessible under the corresponding `Remote Desktop` option available in the [Account Menu menu]({{ interface_url }}/ui/account-menu/) of the [Web Interface]({{ interface_url }}/ui/overview/). -The Remote Desktop can subsequently be closed by clicking the ✕ button at its top-right corner, which reverts the entire screen to its previous appearance. +The Remote Desktop can subsequently be closed by clicking the ✕ button at its top-right corner, which reverts the entire screen to its previous appearance. ## Animation diff --git a/lang/en/docs/remote-connection/actions/open-terminal.md b/lang/en/docs/remote-connection/actions/open-terminal.md index fe8429533..3c1b50e2c 100644 --- a/lang/en/docs/remote-connection/actions/open-terminal.md +++ b/lang/en/docs/remote-connection/actions/open-terminal.md @@ -1,6 +1,6 @@ # Open / Close Web Terminal -The [Web Terminal](../web-terminal.md) remote connection method for accessing the [Command Line Interface](../../cli/overview.md) of our platform is accessible under the corresponding `Terminal` option included in the [right-hand sidebar menu](../../ui/right-sidebar.md) of the [Web Interface](../../ui/overview.md). +The [Web Terminal](../web-terminal.md) remote connection method for accessing the [Command Line Interface]({{ cli_url }}/cli/overview/) of our platform is accessible under the corresponding `Terminal` option included in the [right-hand sidebar menu]({{ interface_url }}/ui/account-menu/) of the [Web Interface]({{ interface_url }}/ui/overview/). The Web Terminal can subsequently be closed by clicking the ✕ button at its top-right corner, which reverts the entire screen to its previous appearance. diff --git a/lang/en/docs/remote-connection/actions/overview.md b/lang/en/docs/remote-connection/actions/overview.md index 54dc9c2b4..00041420f 100644 --- a/lang/en/docs/remote-connection/actions/overview.md +++ b/lang/en/docs/remote-connection/actions/overview.md @@ -33,6 +33,6 @@ We explain how to perform file transfers via the [SCP protocol](../../remote-con Finally, we provide [these instructions](copy-paste.md) on how text can be copied and pasted into the remote connection interfaces, with the help of the above-mentioned [Sidebar](sidebar.md). -## [Access data in Web Platform](../../ui/overview.md) +## [Access data in Web Platform]({{ interface_url }}/ui/overview/) -Finally, we review the procedure for exchanging data back and forth between the remote connection interfaces and the [Web Interface](../../ui/overview.md) of our platform, through the use of [Dropbox](../../data-in-objectstorage/dropbox.md). +Finally, we review the procedure for exchanging data back and forth between the remote connection interfaces and the [Web Interface]({{ interface_url }}/ui/overview/) of our platform, through the use of [Dropbox]({{ resources_url }}/data-in-objectstorage/dropbox/). diff --git a/lang/en/docs/remote-connection/actions/transfer-files-scp.md b/lang/en/docs/remote-connection/actions/transfer-files-scp.md index 6fc93c51a..51dfb996b 100644 --- a/lang/en/docs/remote-connection/actions/transfer-files-scp.md +++ b/lang/en/docs/remote-connection/actions/transfer-files-scp.md @@ -22,7 +22,7 @@ scp -i @login.mat3ra.com: + + +## Features + +The Explorer interface provides several features for each endpoint: + +- **Request parameters** — view required and optional parameters with their types and descriptions +- **Response examples** — inspect the structure of a successful response before making a request +- **Response schema** — examine the full data model returned by each endpoint +- **Try it** — execute a live request against the API and view the response in real time + + +## API Versions + +The following API versions are currently supported: + +- [2018-10-01](https://platform.mat3ra.com/api/2018-10-01/swagger.json) + + +## Links + +[^1]: [Swagger UI, GitHub](https://github.com/swagger-api/swagger-ui/tree/v2.2.10) + +///FOOTNOTES GO HERE/// diff --git a/lang/en/docs/rest-api/authentication.md b/lang/en/docs/rest-api/authentication.md index fb56a8674..3198e5010 100644 --- a/lang/en/docs/rest-api/authentication.md +++ b/lang/en/docs/rest-api/authentication.md @@ -1,6 +1,6 @@ # Authentication -There are 2 ways to generate the authentication parameters: either through the Login endpoint of by using the account preferences as explained [elsewhere](../accounts/ui/preferences/api.md). We recommend using the second option. +There are 2 ways to generate the authentication parameters: either through the Login endpoint of by using the account preferences as explained [elsewhere]({{ interface_url }}/accounts/ui/preferences/api/). We recommend using the second option. ## Login diff --git a/lang/en/docs/rest-api/endpoints.md b/lang/en/docs/rest-api/endpoints.md index 5776c5dcb..2294a0b26 100644 --- a/lang/en/docs/rest-api/endpoints.md +++ b/lang/en/docs/rest-api/endpoints.md @@ -2,14 +2,14 @@ ## Definition -An Endpoint is one end of a communication channel, the API end of it. It has a unique URL and a set of parameters associated with it. Sending a request with a specific HTTP[^1] method to an Endpoint triggers a certain function. +An Endpoint is one end of a communication channel, the API end of it. It has a unique URL and a set of parameters associated with it. Sending a request with a specific HTTP [^1] method to an Endpoint triggers a certain function. !!! example - Contacting materials endpoint with a PUT HTTP method and the corresponding data about a material will lead to the creation of the corresponding [Material](../materials/overview.md) inside the database and return the result. + Contacting materials endpoint with a PUT HTTP method and the corresponding data about a material will lead to the creation of the corresponding [Material]({{ reference_url }}/materials/overview/) inside the database and return the result. ## List of Endpoints -Below is the list of currently supported endpoints with links to the detailed documentation for each: +Below is the list of currently supported endpoints with links to the detailed documentation in the [API Explorer](api-explorer.md): - [Material](https://api-explorer.mat3ra.com/?url=https://platform.mat3ra.com/api/2018-10-01/swagger.json/#!/Material/get_materials) - [Workflow](https://api-explorer.mat3ra.com/?url=https://platform.mat3ra.com/api/2018-10-01/swagger.json/#!/Workflow/get_workflows) @@ -23,38 +23,9 @@ Below is the list of currently supported endpoints with links to the detailed do - [Login](https://api-explorer.mat3ra.com/?url=https://platform.mat3ra.com/api/2018-10-01/swagger.json/#!/API/post_login) - [Logout](https://api-explorer.mat3ra.com/?url=https://platform.mat3ra.com/api/2018-10-01/swagger.json/#!/API/get_logout) -## Endpoint Documentation - -In order to explain the data formats and allow users to try the endpoints we use Swagger UI[^2], a software framework to design, build, document, and try API services. In the example below, we demonstrate how to use the REST API Explorer page to list the materials an account has access to. It is assumed that the reader has already generated the authentication parameters explained in [here](authentication.md). - -1. Open [REST API Explorer](https://api-explorer.mat3ra.com/) page. - -2. Set `X-ACCOUNT-ID` and `X-AUTH-TOKEN` authentication parameters. - -3. Navigate to `Materials` endpoint, set up [query](./query-structure.md#query) (`{"formula": "Si"}`) and [projection](./query-structure.md#projection) (`{"limit": 5}`) parameters. - -4. Click on `RESPONSE EXAMPLE` and `RESPONSE SCHEMA` on the right panel to see an example response and its structure (schema). - -5. Click on `Try` to connect to the RESTful API and retrieve the materials. - -6. A list of materials filtered by the given query and projection parameters will be returned. - -The aforementioned steps are demonstrated in the animation below. - - - - -## API Versions - -Below you can find the currently supported API versions. - -- [2018-10-01](https://platform.mat3ra.com/api/2018-10-01/swagger.json) - ## Links [^1]: [Wikipedia Hypertext Transfer Protocol (HTTP), Website](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol) -[^2]: [Swagger UI, GitHub](https://github.com/swagger-api/swagger-ui/tree/v2.2.10) - ///FOOTNOTES GO HERE/// diff --git a/lang/en/docs/rest-api/overview.md b/lang/en/docs/rest-api/overview.md index 3337d5912..485e6219b 100644 --- a/lang/en/docs/rest-api/overview.md +++ b/lang/en/docs/rest-api/overview.md @@ -2,7 +2,7 @@ ## Definition -RESTful[^1] API (or REST-API, or Representational State Transfer Application Programming Interface) is a layer allows to access and manipulate textual representation of the web resources (eg. [Entities](../entities-general/overview.md)) by using a uniform and predefined set of stateless operations. +RESTful[^1] API (or REST-API, or Representational State Transfer Application Programming Interface) is a layer allows to access and manipulate textual representation of the web resources (eg. [Entities]({{ reference_url }}/entities-general/overview/)) by using a uniform and predefined set of stateless operations. In other words, REST-API provides **programmatic** access to data and functionality for data scientists and engineers, and anyone else who prefers coding to the user interface. diff --git a/lang/en/docs/site-policy/privacy-statement.md b/lang/en/docs/site-policy/privacy-statement.md index ac9ec5a2a..bcd3398df 100644 --- a/lang/en/docs/site-policy/privacy-statement.md +++ b/lang/en/docs/site-policy/privacy-statement.md @@ -136,7 +136,7 @@ Exabyte.io may disclose personally-identifying information or other information In complying with court orders and similar legal processes, Exabyte.io strives for transparency. When permitted, we will make a reasonable effort to notify users of any disclosure of their information, unless we are prohibited by law or court order from doing so, or in rare, exigent circumstances. -For more information, see our [Guidelines for Legal Requests of User Data](../articles/guidelines-for-legal-requests-of-user-data/). +For more information, see the Guidelines for Legal Requests of User Data. ## How you can access and control the information we collect diff --git a/lang/en/docs/site-policy/sharing-policy.md b/lang/en/docs/site-policy/sharing-policy.md index 6392a46ba..fa8f02879 100644 --- a/lang/en/docs/site-policy/sharing-policy.md +++ b/lang/en/docs/site-policy/sharing-policy.md @@ -67,7 +67,7 @@ In the user interface the system-wide sharing status for the entities is be show ## Service levels and private data -As the page explaining the [service levels](../pricing/service-levels.md) has it, the ability to create entities that are private to an account is a premium feature and requires an elevated service level type. For the newly created accounts that use promotional credits to try our platform all created entities are public. +As the page explaining the [service levels]({{ guide_url }}/pricing/service-levels/) has it, the ability to create entities that are private to an account is a premium feature and requires an elevated service level type. For the newly created accounts that use promotional credits to try our platform all created entities are public. ### Other notes diff --git a/lang/en/docs/software-directory/development/compilers.md b/lang/en/docs/software-directory/development/compilers.md index e354f4f55..cd56fd855 100644 --- a/lang/en/docs/software-directory/development/compilers.md +++ b/lang/en/docs/software-directory/development/compilers.md @@ -7,7 +7,7 @@ We support both the GNU Compiler Collection (GCC) [^1], as well as the Intel pro | GCC | 11.2.0, 5.4.0 | | Intel | 14.0.3.174, i-174 | -These compilers are accessible under the [Command Line Interface environment](../../cli/environment.md) of our platform, via the loading of the corresponding [modules](../../cli/modules.md). +These compilers are accessible under the [Command Line Interface environment]({{ cli_url }}/cli/environment/) of our platform, via the loading of the corresponding [modules]({{ cli_url }}/cli/modules/). ## Links diff --git a/lang/en/docs/software-directory/development/libraries.md b/lang/en/docs/software-directory/development/libraries.md index 080087e91..7bf8991c3 100644 --- a/lang/en/docs/software-directory/development/libraries.md +++ b/lang/en/docs/software-directory/development/libraries.md @@ -1,6 +1,6 @@ # Libraries -We provide the following development libraries, accessible within the [Command Line Interface environment](../../cli/environment.md) of our platform through the loading of the corresponding [modules](../../cli/modules.md). +We provide the following development libraries, accessible within the [Command Line Interface environment]({{ cli_url }}/cli/environment/) of our platform through the loading of the corresponding [modules]({{ cli_url }}/cli/modules/). | Name | Version(s) | | :-------- | ----------- | diff --git a/lang/en/docs/software-directory/development/text-editors.md b/lang/en/docs/software-directory/development/text-editors.md index 829e84876..54e7e7e15 100644 --- a/lang/en/docs/software-directory/development/text-editors.md +++ b/lang/en/docs/software-directory/development/text-editors.md @@ -1,6 +1,6 @@ # Text Editors -Under the [Command Line Interface Environment](../../cli/overview.md) of our platform, we have included two widely-used advanced command line text editors: **vim** [^1] and **emacs** [^2]. These can conveniently be employed for editing [programming scripts](../../software/classification/scripting.md), or for inspecting [simulation data files](../../data-on-disk/overview.md). +Under the [Command Line Interface Environment]({{ cli_url }}/cli/overview/) of our platform, we have included two widely-used advanced command line text editors: **vim** [^1] and **emacs** [^2]. These can conveniently be employed for editing [programming scripts]({{ reference_url }}/software/classification/scripting/), or for inspecting [simulation data files]({{ resources_url }}/data-on-disk/overview/). Other basic text editors found by default in UNIX-based operating systems are also available [^3]. diff --git a/lang/en/docs/software-directory/machine-learning/exabyte/data.md b/lang/en/docs/software-directory/machine-learning/exabyte/data.md deleted file mode 100644 index bd73b7c21..000000000 --- a/lang/en/docs/software-directory/machine-learning/exabyte/data.md +++ /dev/null @@ -1,13 +0,0 @@ -# Exabyte Machine Learning: Structured Representation - -We present in what follows the [structured representation](../../../data-structured/overview.md) for the [Exabyte Machine Learning](overview.md). - -=== "Schema" - ``` json - --8<-- "data/esse/schema/software_directory/ml/exabyteml.json" - ``` - -=== "Example" - ``` json - --8<-- "data/esse/example/software_directory/ml/exabyteml.json" - ``` diff --git a/lang/en/docs/software-directory/machine-learning/exabyte/overview.md b/lang/en/docs/software-directory/machine-learning/exabyte/overview.md deleted file mode 100644 index 513a4027d..000000000 --- a/lang/en/docs/software-directory/machine-learning/exabyte/overview.md +++ /dev/null @@ -1,10 +0,0 @@ -# Exabyte Machine Learning Engine - -We provide a proof-of-concept support for [Machine Learning](../../../models-directory/machine-learning/overview.md) through the **Exabyte Machine Learning (Exabyte-ML) engine**, which is based upon the [Linear Regression](../../../methods-directory/linear-regression/overview.md) computational and statistical method. - -The currently implemented version of this engine is 0.2.0. - -## Accessibility - -Exabyte-ML is accessible via the [subworkflow editor interface](../../../workflow-designer/subworkflow-editor/overview.md). Pre-assembled ML workflows can be imported directly from the [Workflows Bank](../../../workflows/bank.md). - diff --git a/lang/en/docs/software-directory/machine-learning/python-ml/components.md b/lang/en/docs/software-directory/machine-learning/python-ml/components.md index ae4d06a9e..e17f199f7 100644 --- a/lang/en/docs/software-directory/machine-learning/python-ml/components.md +++ b/lang/en/docs/software-directory/machine-learning/python-ml/components.md @@ -1,19 +1,19 @@ # Components -We present in this page the different [components](../../../software/components.md) (executables and flavors) +We present in this page the different [components]({{ reference_url }}/software/components/) (executables and flavors) comprised within our [Python-based](overview.md) machine learning implementation. Only those components implemented on our platform to date are mentioned here, as can be inspected from the lists of available executables and flavors under the -[Unit Editor Interface](../../../workflow-designer/unit-editor.md#application). +[Unit Editor Interface]({{ interface_url }}/workflow-designer/unit-editor/#application). !!!warning "Implementation on our platform" The user who wishes for additional functionality to be added to our platform in future should express so via - a [support request](../../../ui/support.md). + a [support request]({{ interface_url }}/ui/support/). ## Executable -PythonML is based on the `python` [executable](../../../software/components.md#executables), and through this executable +PythonML is based on the `python` [executable]({{ reference_url }}/software/components/#executables), and through this executable the implemented ML calculations can be performed. ## Training and Prediction diff --git a/lang/en/docs/software-directory/machine-learning/python-ml/data.md b/lang/en/docs/software-directory/machine-learning/python-ml/data.md index db859cf25..b74c9cf8a 100644 --- a/lang/en/docs/software-directory/machine-learning/python-ml/data.md +++ b/lang/en/docs/software-directory/machine-learning/python-ml/data.md @@ -1,15 +1,14 @@ # Data -This implementation of Machine Learning uses [Python](../../scripting/python/overview.md) under-the-hood. Hence, its -workflow units adopt the [schema](../../../data-structured/overview.md) used -by [Python Units](../../scripting/python/data.md). +This implementation of Machine Learning uses [Python]({{ reference_url }}/software-directory/scripting/python/overview/) under-the-hood. Hence, its +workflow units adopt the schema used by [Python Units]({{ data_url }}/software-directory/scripting/python/data/). === "Schema" - ``` json + ```json --8<-- "data/esse/schema/software_directory/scripting/python.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/software_directory/scripting/python.json" ``` diff --git a/lang/en/docs/software-directory/machine-learning/python-ml/overview.md b/lang/en/docs/software-directory/machine-learning/python-ml/overview.md index e674dafc7..3f874e954 100644 --- a/lang/en/docs/software-directory/machine-learning/python-ml/overview.md +++ b/lang/en/docs/software-directory/machine-learning/python-ml/overview.md @@ -1,13 +1,13 @@ # Python-Based Machine Learning -We provide a proof-of-concept support for [Machine Learning](../../../models-directory/machine-learning/overview.md) +We provide a proof-of-concept support for [Machine Learning]({{ reference_url }}/models-directory/machine-learning/overview/) based in [Python](../../scripting/python/overview.md) and Scikit-Learn [^1]. ## Accessibility This machine learning implementation is accessible via the -[subworkflow editor interface](../../../workflow-designer/subworkflow-editor/overview.md). -Pre-assembled ML workflows can be imported directly from the [Workflows Bank](../../../workflows/bank.md). +[subworkflow editor interface]({{ interface_url }}/workflow-designer/subworkflow-editor/overview/). +Pre-assembled ML workflows can be imported directly from the [Workflows Bank]({{ reference_url }}/workflows/bank/). ## Workflow Structure diff --git a/lang/en/docs/software-directory/machine-learning/python-ml/workflow-structure.md b/lang/en/docs/software-directory/machine-learning/python-ml/workflow-structure.md index a0e8203bc..c1dcbbb15 100644 --- a/lang/en/docs/software-directory/machine-learning/python-ml/workflow-structure.md +++ b/lang/en/docs/software-directory/machine-learning/python-ml/workflow-structure.md @@ -15,7 +15,7 @@ A diagram of an example workflow can be found below, based on the bank workflow This subworkflow facilitates setting up the PythonML job. Users should not need to edit this workflow. The configuration of this workflow is handled automatically on the -when [the predict workflow is generated](../../../properties-directory/non-scalar/workflow.md). +when [the predict workflow is generated]({{ reference_url }}/properties-directory/non-scalar/workflow/). ### Subworkflow: Machine Learning diff --git a/lang/en/docs/software-directory/machine-learning/tensorflow.md b/lang/en/docs/software-directory/machine-learning/tensorflow.md index 46aa3a17d..2ea43ebb7 100644 --- a/lang/en/docs/software-directory/machine-learning/tensorflow.md +++ b/lang/en/docs/software-directory/machine-learning/tensorflow.md @@ -1,7 +1,7 @@ # TensorFlow [TensorFlow](https://www.tensorflow.org/) is a powerful open-source machine learning platform geared towards neural networks. -Currently, our support for TensorFlow is primarily through the [command-line interface](../../cli/overview.md), +Currently, our support for TensorFlow is primarily through the [command-line interface]({{ cli_url }}/cli/overview/), although we note that a custom [PythoML](python-ml/overview.md) workflow could be used to run TensorFlow workflows through our web app (e.g. for hyperparameter tuning). diff --git a/lang/en/docs/software-directory/modeling/nwchem.md b/lang/en/docs/software-directory/modeling/nwchem.md index 8efd9623f..3d3345062 100644 --- a/lang/en/docs/software-directory/modeling/nwchem.md +++ b/lang/en/docs/software-directory/modeling/nwchem.md @@ -6,4 +6,4 @@ More information about NWChem can be retrieved under its official website [^1]. ## Links -[^1]: [NWChem, Official Website](http://www.nwchem-sw.org/index.php/Main_Page) +[^1]: [NWChem, Official Website](https://nwchemgit.github.io) diff --git a/lang/en/docs/software-directory/modeling/quantum-espresso/components.md b/lang/en/docs/software-directory/modeling/quantum-espresso/components.md index f3ec66893..eb2108e04 100644 --- a/lang/en/docs/software-directory/modeling/quantum-espresso/components.md +++ b/lang/en/docs/software-directory/modeling/quantum-espresso/components.md @@ -1,17 +1,17 @@ # Components -We present in this page the different [components](../../../software/components.md) (executables and flavors) comprised within the [Quantum ESPRESSO](overview.md) distribution package. +We present in this page the different [components]({{ reference_url }}/software/components/) (executables and flavors) comprised within the [Quantum ESPRESSO](overview.md) distribution package. -Only those components implemented on our platform to date are mentioned here, as can be inspected from the lists of available executables and flavors under the [Unit Editor Interface](../../../workflow-designer/unit-editor.md#application). +Only those components implemented on our platform to date are mentioned here, as can be inspected from the lists of available executables and flavors under the [Unit Editor Interface]({{ interface_url }}/workflow-designer/unit-editor/#application). !!!warning "Implementation on our platform" - The user who wishes for additional functionality to be added to our platform in future should express so via a [support request](../../../ui/support.md). + The user who wishes for additional functionality to be added to our platform in future should express so via a [support request]({{ interface_url }}/ui/support/). ## Executables -The core plane wave DFT functions of QE are provided by the PWscf (Plane-Wave Self-Consistent Field) component, further referred to under the name of its [executable](../../../software/components.md#executables) `pw.x`. Further components are included in the distribution package, such as the `ph.x` executable for performing phonon calculations via the density functional perturbation theory and linear response theoretical formalisms [^6]. +The core plane wave DFT functions of QE are provided by the PWscf (Plane-Wave Self-Consistent Field) component, further referred to under the name of its [executable]({{ reference_url }}/software/components/#executables) `pw.x`. Further components are included in the distribution package, such as the `ph.x` executable for performing phonon calculations via the density functional perturbation theory and linear response theoretical formalisms [^6]. -Complete documentation about the software package can be found in its corresponding website. The input file description for `pw.x` can be found in Ref. [^1]. The package-specific documentation [^2] contains links to input descriptions for other [executables](../../../software/components.md#executables) as well. +Complete documentation about the software package can be found in its corresponding website. The input file description for `pw.x` can be found in Ref. [^1]. The package-specific documentation [^2] contains links to input descriptions for other [executables]({{ reference_url }}/software/components/#executables) as well. The following executables have been implemented on our platform so far. @@ -24,17 +24,17 @@ The following executables have been implemented on our platform so far. - `pp.x`: data analysis and plotting. - `dos.x`: calculates the Density of States (DOS). - `bands.x`: re-orders the bands in the band-structure of the material, and computes band-related properties. -- `neb.x` [^3] [^4]: performs calculations of the energy profile of chemical reactions via the [Nudged Elastic Band](../../../tutorials/dft/chemical/reaction-profile-qe.md) method. +- `neb.x` [^3] [^4]: performs calculations of the energy profile of chemical reactions via the [Nudged Elastic Band]({{ guide_url }}/tutorials/dft/chemical/reaction-profile-qe/) method. ## Flavors -The `pw.x` executable for the Quantum ESPRESSO modeling application, for example, allows for the execution of the following different types of calculation [flavors](../../../software/components.md#flavors) [^5]. +The `pw.x` executable for the Quantum ESPRESSO modeling application, for example, allows for the execution of the following different types of calculation [flavors]({{ reference_url }}/software/components/#flavors) [^5]. -- `scf`: "self-consistent field" [total ground-state energy](../../../properties-directory/scalar/total-energy.md) calculation. +- `scf`: "self-consistent field" [total ground-state energy]({{ reference_url }}/properties-directory/scalar/total-energy/) calculation. - `nscf`: for further processing of the results of non-scf calculations (for instance, in DOS calculations). -- `bands`: [electronic band structure](../../../properties-directory/non-scalar/bandstructure.md) calculation. +- `bands`: [electronic band structure]({{ reference_url }}/properties-directory/non-scalar/bandstructure/) calculation. - `relax`: optimization of the atomic positions to relax the inter-atomic forces. -- `vc-relax`: "variable-cell" [structural relaxation and optimization](../../../workflows/addons/structural-relaxation.md). +- `vc-relax`: "variable-cell" [structural relaxation and optimization]({{ reference_url }}/workflows/addons/structural-relaxation/). ## Links diff --git a/lang/en/docs/software-directory/modeling/quantum-espresso/compute-parameters.md b/lang/en/docs/software-directory/modeling/quantum-espresso/compute-parameters.md index df6e53e30..4ab1b733a 100644 --- a/lang/en/docs/software-directory/modeling/quantum-espresso/compute-parameters.md +++ b/lang/en/docs/software-directory/modeling/quantum-espresso/compute-parameters.md @@ -1,6 +1,6 @@ # Quantum Espresso: Specific Compute Parameters -The [compute parameters](../../../infrastructure/compute/parameters.md) which are specific to Quantum ESPRESSO consist in the **[Advanced Options](../../../infrastructure/compute/parameters.md#advanced-options)**, which can be set from within the relevant [user interface](../../../infrastructure/compute/overview.md). +The [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/) which are specific to Quantum ESPRESSO consist in the **[Advanced Options]({{ resources_url }}/infrastructure/compute/parameters/#advanced-options)**, which can be set from within the relevant [user interface]({{ resources_url }}/infrastructure/compute/overview/). These specific parameters allow for the **parallelization** of Quantum ESPRESSO computations, as explained in what follows. Detailed explanations on how to best set the values of such parallelization parameters can be found under Ref. [^1]. @@ -10,7 +10,7 @@ Processors can in general be divided into different **"images"**, each correspon ### k-point pools -Each image can be subpartitioned into **"pools"**, each taking care of a group of [k-points](../../../models/auxiliary-concepts/reciprocal-space/sampling.md). +Each image can be subpartitioned into **"pools"**, each taking care of a group of [k-points]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/). ### band pools diff --git a/lang/en/docs/software-directory/modeling/quantum-espresso/data.md b/lang/en/docs/software-directory/modeling/quantum-espresso/data.md index e99417f2b..342cf275c 100644 --- a/lang/en/docs/software-directory/modeling/quantum-espresso/data.md +++ b/lang/en/docs/software-directory/modeling/quantum-espresso/data.md @@ -1,27 +1,27 @@ # Quantum ESPRESSO: Structured Data -We present in this page the [structured representations](../../../data-structured/overview.md) for the [Quantum ESPRESSO modeling application](overview.md), and for its [specific compute parameters](compute-parameters.md). +We present in this page the [structured representations]({{ data_url }}/data-structured/overview/) for the [Quantum ESPRESSO modeling application]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/), and for its [specific compute parameters]({{ reference_url }}/software-directory/modeling/quantum-espresso/compute-parameters/). ## Application === "Schema" - ``` json + ```json --8<-- "data/esse/schema/software_directory/modeling/espresso.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/software_directory/modeling/espresso.json" ``` ## Compute Parameters === "Schema" - ``` json + ```json --8<-- "data/esse/schema/software_directory/modeling/espresso/arguments.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/software_directory/modeling/espresso/arguments.json" ``` diff --git a/lang/en/docs/software-directory/modeling/quantum-espresso/overview.md b/lang/en/docs/software-directory/modeling/quantum-espresso/overview.md index 8ba3633fb..f6e1f017b 100644 --- a/lang/en/docs/software-directory/modeling/quantum-espresso/overview.md +++ b/lang/en/docs/software-directory/modeling/quantum-espresso/overview.md @@ -4,8 +4,8 @@ Quantum ESPRESSO (QE, also referred to as "espresso" in our platform) [^1] [^2] is a software suite for ab-initio quantum methods performing general electronic-structure calculations and materials modeling. It is distributed for free under the GNU General Public License. Quantum ESPRESSO is based on -[Density Functional Theory](../../../models-directory/dft/overview.md), -[plane wave basis sets and pseudopotentials](../../../methods-directory/pseudopotential/overview.md) +[Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/), +[plane wave basis sets and pseudopotentials]({{ reference_url }}/methods-directory/pseudopotential/overview/) (both norm-conserving and ultrasoft). ## Supported Versions @@ -15,19 +15,19 @@ We support `5.2.1`, `5.4.0`, `6.0.0`, `6.3.0`, `6.4.1`, `6.5.0`, `6.6.0`, ## [Components](components.md) -We introduce the different [components](../../../software/components.md) which +We introduce the different [components]({{ reference_url }}/software/components/) which are part of the Quantum ESPRESSO software distribution [in this page](components.md). ## [Compute Parameters](compute-parameters.md) -We explain which [compute parameters](../../../infrastructure/compute/parameters.md) +We explain which [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/) are specific to Quantum ESPRESSO [here](compute-parameters.md). -## [Data](data.md) +## [Data]({{ data_url }}/software-directory/modeling/quantum-espresso/data/) -The [structured representation](../../../data-structured/overview.md) for +The [structured representation]({{ reference_url }}/data-structured/overview/) for Quantum ESPRESSO, and for its specific compute parameters, is explained -[in this page](data.md). +[in this page]({{ data_url }}/software-directory/modeling/quantum-espresso/data/). ## Links diff --git a/lang/en/docs/software-directory/modeling/turbomole.md b/lang/en/docs/software-directory/modeling/turbomole.md index 8f7749893..f1f4165bb 100644 --- a/lang/en/docs/software-directory/modeling/turbomole.md +++ b/lang/en/docs/software-directory/modeling/turbomole.md @@ -5,7 +5,7 @@ TURBOMOLE is an ab-initio computational chemistry program that implements variou Full instructions on how TURBOMOLE can be operated and adapted to different research contexts can be consulted in its official website [^1]. !!!note "Demo version" - The "Demo" version of TURBOMOLE is accessible via [Remote Desktop Environment](../../remote-connection/remote-desktop.md). + The "Demo" version of TURBOMOLE is accessible via [Remote Desktop Environment]({{ cli_url }}/remote-connection/remote-desktop/). ## Links diff --git a/lang/en/docs/software-directory/modeling/vasp/components.md b/lang/en/docs/software-directory/modeling/vasp/components.md index 6884a09e4..9ddfd4198 100644 --- a/lang/en/docs/software-directory/modeling/vasp/components.md +++ b/lang/en/docs/software-directory/modeling/vasp/components.md @@ -1,28 +1,28 @@ # Components -We present in this page the different [components](../../../software/components.md) (executables and flavors) comprised within the [VASP](overview.md) distribution package. +We present in this page the different [components]({{ reference_url }}/software/components/) (executables and flavors) comprised within the [VASP](overview.md) distribution package. -Only those components implemented on our platform to date are mentioned here, as can be inspected from the lists of available executables and flavors under the [Unit Editor Interface](../../../workflow-designer/unit-editor.md#application). +Only those components implemented on our platform to date are mentioned here, as can be inspected from the lists of available executables and flavors under the [Unit Editor Interface]({{ interface_url }}/workflow-designer/unit-editor/#application). !!!warning "Implementation on our platform" - The user who wishes for additional functionality to be added to our platform in future should express so via a [support request](../../../ui/support.md). + The user who wishes for additional functionality to be added to our platform in future should express so via a [support request]({{ interface_url }}/ui/support/). ## Executables -the VASP package is composed of one main `vasp` [executable](../../../software/components.md#executables) only, through which all calculation [flavors](../../../software/components.md#flavors) explained in what follows can be performed. +the VASP package is composed of one main `vasp` [executable]({{ reference_url }}/software/components/#executables) only, through which all calculation [flavors]({{ reference_url }}/software/components/#flavors) explained in what follows can be performed. ## Flavors -The following computation [flavors](../../../software/components.md#flavors) are available within VASP. +The following computation [flavors]({{ reference_url }}/software/components/#flavors) are available within VASP. -- `vasp`: "self-consistent field" [total ground-state energy](../../../properties-directory/scalar/total-energy.md) calculation. +- `vasp`: "self-consistent field" [total ground-state energy]({{ reference_url }}/properties-directory/scalar/total-energy/) calculation. - `vasp_vc_relax_conv`: - `vasp_nscf`: for further processing of the results of non-scf calculations (for instance, in DOS calculations). -- `vasp_zpe`: for [Zero Point Energy](../../../properties-directory/scalar/zero-point-energy.md) calculations. -- `vasp_kpt_conv`: for performing a [k-points convergence study](../../../models/auxiliary-concepts/reciprocal-space/convergence.md). +- `vasp_zpe`: for [Zero Point Energy]({{ reference_url }}/properties-directory/scalar/zero-point-energy/) calculations. +- `vasp_kpt_conv`: for performing a [k-points convergence study]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/convergence/). - `vasp_relax`: optimization of the atomic positions to relax the inter-atomic forces. -- `vasp_vc_relax`: "variable-cell" [structural relaxation and optimization](../../../workflows/addons/structural-relaxation.md). -- `vasp_bands`: [electronic band structure](../../../properties-directory/non-scalar/bandstructure.md) calculation. +- `vasp_vc_relax`: "variable-cell" [structural relaxation and optimization]({{ reference_url }}/workflows/addons/structural-relaxation/). +- `vasp_bands`: [electronic band structure]({{ reference_url }}/properties-directory/non-scalar/bandstructure/) calculation. - `vasp_hse`: for performing calculations using the HSE hybrid exchange-correlation functional. -- `vasp_bands_hse`: [electronic band structure](../../../properties-directory/non-scalar/bandstructure.md) calculations using HSE. +- `vasp_bands_hse`: [electronic band structure]({{ reference_url }}/properties-directory/non-scalar/bandstructure/) calculations using HSE. - `vasp_nscf_hse`: for further processing of the results of non-scf HSE calculations. diff --git a/lang/en/docs/software-directory/modeling/vasp/compute-parameters.md b/lang/en/docs/software-directory/modeling/vasp/compute-parameters.md index dec9b1a32..2b7453a59 100644 --- a/lang/en/docs/software-directory/modeling/vasp/compute-parameters.md +++ b/lang/en/docs/software-directory/modeling/vasp/compute-parameters.md @@ -1,5 +1,5 @@ # VASP: Specific Compute Parameters -The [compute parameters](../../../infrastructure/compute/parameters.md) which are specific to VASP at present contain no **[Advanced Options](../../../infrastructure/compute/parameters.md#advanced-options)** within our [user interface](../../../infrastructure/compute/overview.md). +The [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/) which are specific to VASP at present contain no **[Advanced Options]({{ resources_url }}/infrastructure/compute/parameters/#advanced-options)** within our [user interface]({{ resources_url }}/infrastructure/compute/overview/). -Input keywords for the **parallelization** of VASP computations can still be set in the [unit](../../../workflows/components/units.md) input file(s), and they include `NCORE`/`NPAR`, `KPAR`, and other flags. Users can find detailed explanations in the references available in the [overview](overview.md#links) page. +Input keywords for the **parallelization** of VASP computations can still be set in the [unit]({{ reference_url }}/workflows/components/units/) input file(s), and they include `NCORE`/`NPAR`, `KPAR`, and other flags. Users can find detailed explanations in the references available in the [overview](overview.md#links) page. diff --git a/lang/en/docs/software-directory/modeling/vasp/data.md b/lang/en/docs/software-directory/modeling/vasp/data.md index a156deff8..363d78757 100644 --- a/lang/en/docs/software-directory/modeling/vasp/data.md +++ b/lang/en/docs/software-directory/modeling/vasp/data.md @@ -1,13 +1,13 @@ # Structured Representation for VASP -We present below the [structured data](../../../data-structured/overview.md) for the [VASP](overview.md) modeling application. +We present below the [structured data]({{ data_url }}/data-structured/overview/) for the [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) modeling application. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/software_directory/modeling/vasp.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/software_directory/modeling/vasp.json" ``` diff --git a/lang/en/docs/software-directory/modeling/vasp/overview.md b/lang/en/docs/software-directory/modeling/vasp/overview.md index 024b56b88..b2fa76d40 100644 --- a/lang/en/docs/software-directory/modeling/vasp/overview.md +++ b/lang/en/docs/software-directory/modeling/vasp/overview.md @@ -2,31 +2,31 @@ The Vienna Ab initio Simulation Package, better known as VASP, is a package for performing ab-initio electronic structure calculations and molecular dynamics, using either Vanderbilt ultra-soft pseudopotentials or the projector-augmented wave (PAW) method, together with a plane wave basis set. -The underlying [theoretical model](../../../models/overview.md) is [Density Functional Theory (DFT)](../../../models-directory/dft/overview.md), but the code also allows for the use of post-DFT corrections, such as hybrid functionals mixing DFT and Hartree–Fock exchange, many-body perturbation theory (the GW method), and dynamical electronic correlations within the Random Phase Approximation (RPA). +The underlying [theoretical model]({{ reference_url }}/models/overview/) is [Density Functional Theory (DFT)]({{ reference_url }}/models-directory/dft/overview/), but the code also allows for the use of post-DFT corrections, such as hybrid functionals mixing DFT and Hartree–Fock exchange, many-body perturbation theory (the GW method), and dynamical electronic correlations within the Random Phase Approximation (RPA). Complete information and documentation about the VASP code can be found in its corresponding website [^1], [^2], [^3]. !!!warning "License Requirements" - VASP is a proprietary software, and as such it requires a license in order to be operated. All users who would like to use this code are advised to send us a [support request](../../../ui/support.md) so that we can check their existing licenses. Contact us about an on-demand license option for interested parties. + VASP is a proprietary software, and as such it requires a license in order to be operated. All users who would like to use this code are advised to send us a [support request]({{ interface_url }}/ui/support/) so that we can check their existing licenses. Contact us about an on-demand license option for interested parties. ## Supported Versions We provide support and implementations for both the 5.3.5 and 5.4.4 versions of VASP. !!! note "Default Pseudopotentials" - As mentioned in the [dedicated section](../../../methods-directory/pseudopotential/default.md), the list of default pseudopotentials follows the versions of the VASP software itself (versions 5.2 and 5.4). + As mentioned in the [dedicated section]({{ reference_url }}/methods-directory/pseudopotential/default/), the list of default pseudopotentials follows the versions of the VASP software itself (versions 5.2 and 5.4). ## [Components](components.md) -We introduce the different [components](../../../software/components.md) which are part of the VASP software distribution [in this page](components.md). +We introduce the different [components]({{ reference_url }}/software/components/) which are part of the VASP software distribution [in this page](components.md). ## [Compute Parameters](compute-parameters.md) -We explain the specific aspects of [compute parameters](../../../infrastructure/compute/parameters.md) [here](compute-parameters.md). +We explain the specific aspects of [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/) [here](compute-parameters.md). -## [Data](data.md) +## [Data]({{ data_url }}/software-directory/modeling/vasp/data/) -The [structured representation](../../../data-structured/overview.md) for VASP is explained [in this page](data.md). +The [structured representation]({{ data_url }}/data-structured/overview/) for VASP is explained [in this page]({{ data_url }}/software-directory/modeling/vasp/data/). ## Links diff --git a/lang/en/docs/software-directory/overview.md b/lang/en/docs/software-directory/overview.md index 7734c4cce..3ceaacefe 100644 --- a/lang/en/docs/software-directory/overview.md +++ b/lang/en/docs/software-directory/overview.md @@ -1,19 +1,19 @@ # List of Available Software -We list on the present page the [software](../software/overview.md) available on our platform, accessible via the appropriate [connection method](../remote-connection/overview.md). The reader is referred to the introductory pages dedicated to each of the packages listed here by clicking the links contained below. Dedicated pages contain references to the relevant documentation explaining the operations of the corresponding software in detail. +We list on the present page the [software]({{ reference_url }}/software/overview/) available on our platform, accessible via the appropriate [connection method]({{ cli_url }}/remote-connection/overview/). The reader is referred to the introductory pages dedicated to each of the packages listed here by clicking the links contained below. Dedicated pages contain references to the relevant documentation explaining the operations of the corresponding software in detail. ## Access Scenarios Tools can be accessed through one or more of the following methods: - 1. The main user interface (in the [subworkflow editor](../workflow-designer/subworkflow-editor/overview.md)), - 2. Remote Desktop (we provide an example for [VESTA](analysis/vesta.md)) in [this page](../remote-connection/actions-rd/open-app.md), - 3. [Environment Modules](../cli/modules.md) in [command line interface](../cli/overview.md). + 1. The main user interface (in the [subworkflow editor]({{ interface_url }}/workflow-designer/subworkflow-editor/overview/)), + 2. Remote Desktop (we provide an example for [VESTA](analysis/vesta.md)) in [this page]({{ cli_url }}/remote-connection/actions-rd/open-app/), + 3. [Environment Modules]({{ cli_url }}/cli/modules/) in [command line interface]({{ cli_url }}/cli/overview/). ## Modeling Applications -The platform currently offers the choice between the following software engines for modeling, otherwise known as **[applications](../software/components.md)**. +The platform currently offers the choice between the following software engines for modeling, otherwise known as **[applications]({{ reference_url }}/software/components/)**. | Name | Version(s) | Access Scenarios (see previous section) | | :-------- | ----------- | -------------| @@ -21,20 +21,21 @@ The platform currently offers the choice between the following software engines | [VASP](modeling/vasp/overview.md) | 5.3.5-5.4.4 | 1, 3 | | [LAMMPS](modeling/lammps.md) | 11-2016, 12-2018, 1-2022 | 3 | | [NWChem](modeling/nwchem.md) | 6.6, 7.0.2 | 3 | + + ## Machine Learning -We have a proof-of-concept support for [machine learning](../models-directory/machine-learning/overview.md) through [Exabyte-ML](machine-learning/exabyte/overview.md). This application is accessible via the [subworkflow editor interface](../workflow-designer/subworkflow-editor/overview.md) only. +We have a proof-of-concept support for [machine learning]({{ reference_url }}/models-directory/machine-learning/overview/). This application is accessible via the [subworkflow editor interface]({{ interface_url }}/workflow-designer/subworkflow-editor/overview/) only. ## Analysis Tools -We support the following structural analysis and visualization tools through a [remote desktop connection](../remote-connection/remote-desktop.md). The reader may click each entry listed below to be redirected to the software's corresponding documentation introduction. +We support the following structural analysis and visualization tools through a [remote desktop connection]({{ cli_url }}/remote-connection/remote-desktop/). The reader may click each entry listed below to be redirected to the software's corresponding documentation introduction. | Name | Version(s) | Access Scenarios (see previous section) | | :-------- | ----------- | ------------- | @@ -44,14 +45,14 @@ We support the following structural analysis and visualization tools through a [ | [P4VASP](analysis/p4vasp.md) | 0.3.30 | 2, 3 | !!!info "Opening graphical software in remote desktop." - An example of how to open a graphical structural visualization tool in our remote desktop environment is provided [under this page](../remote-connection/actions-rd/open-app.md). + An example of how to open a graphical structural visualization tool in our remote desktop environment is provided [under this page]({{ cli_url }}/remote-connection/actions-rd/open-app/). ## Scripting Applications Our platform includes support for two widely-used scripting languages, [shell scripting](scripting/shell/overview.md) and [python](scripting/python/overview.md), which are introduced in their respective documentation pages. -For command line users, we provide a system-default Python installation and recommend users employ virtual environments for controlling the versions of Python packages in [Command Line Interface](../cli/overview.md), as explained [in this page](../cli/actions/create-python-env.md). +For command line users, we provide a system-default Python installation and recommend users employ virtual environments for controlling the versions of Python packages in [Command Line Interface]({{ cli_url }}/cli/overview/), as explained [in this page]({{ cli_url }}/cli/actions/create-python-env/). ## Development Tools -Users of our [Command Line Interface](../cli/overview.md) have at their disposal a comprehensive set of development [compilers](development/compilers.md) and [libraries](development/libraries.md), as well as of [text editors](development/text-editors.md) for inspecting or editing the relevant scripts and simulation files. +Users of our [Command Line Interface]({{ cli_url }}/cli/overview/) have at their disposal a comprehensive set of development [compilers](development/compilers.md) and [libraries](development/libraries.md), as well as of [text editors](development/text-editors.md) for inspecting or editing the relevant scripts and simulation files. diff --git a/lang/en/docs/software-directory/scripting/jupyter-lab/data.md b/lang/en/docs/software-directory/scripting/jupyter-lab/data.md index 62b32bd80..946d7b38e 100644 --- a/lang/en/docs/software-directory/scripting/jupyter-lab/data.md +++ b/lang/en/docs/software-directory/scripting/jupyter-lab/data.md @@ -2,24 +2,24 @@ ## Structured Representation -We present in what follows the [structured representation](../../../data-structured/overview.md) for the [Jupyter Lab Application](overview.md). +We present in what follows the [structured representation]({{ data_url }}/data-structured/overview/) for the [Jupyter Lab Application]({{ reference_url }}/software-directory/scripting/jupyter-lab/overview/). === "Schema" - ``` json + ```json --8<-- "data/esse/schema/software_directory/scripting/jupyter-lab.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/software_directory/scripting/jupyter-lab.json" ``` ## Files/Storage Convention -1. Initially, the root of the Dropbox folder is passed to the application on the start, so the files at the root of the [Dropbox](../../../data-in-objectstorage/dropbox.md) directory can be accessed -2. Upon each "Save and Checkpoint" action invoked inside the notebook, the ipynb file is overwritten. A new version is stored in the file system, and a checkpoint is saved to the job inside its directory both in the [command-line](../../../jobs-cli/batch-scripts/directories.md#working-directory) and on the [web interface](../../../data-in-objectstorage/files.md). -3. All notebooks have access to the filesystem accessible to the user on the corresponding computational node, namely the [home](../../../infrastructure/clusters/directories.md) and [share](../../../infrastructure/clusters/directories.md) directories. For example, the following command will list the shared directory for the account "exabyte-io", when invoked inside the Jupyter Notebook running on "cluster-007": +1. Initially, the root of the Dropbox folder is passed to the application on the start, so the files at the root of the [Dropbox]({{ resources_url }}/data-in-objectstorage/dropbox/) directory can be accessed +2. Upon each "Save and Checkpoint" action invoked inside the notebook, the ipynb file is overwritten. A new version is stored in the file system, and a checkpoint is saved to the job inside its directory both in the [command-line]({{ cli_url }}/jobs-cli/batch-scripts/directories/#working-directory) and on the [web interface]({{ resources_url }}/data-in-objectstorage/files/). +3. All notebooks have access to the filesystem accessible to the user on the corresponding computational node, namely the [home]({{ resources_url }}/infrastructure/clusters/directories/) and [share]({{ resources_url }}/infrastructure/clusters/directories/) directories. For example, the following command will list the shared directory for the account "mat3ra", when invoked inside the Jupyter Notebook running on "cluster-007": ```bash - ls -lhta /cluster-007-share/groups/exabyte-io + ls -lhta /cluster-007-share/groups/mat3ra ``` diff --git a/lang/en/docs/software-directory/scripting/jupyter-lab/overview.md b/lang/en/docs/software-directory/scripting/jupyter-lab/overview.md index 39f748573..ff682cc6b 100644 --- a/lang/en/docs/software-directory/scripting/jupyter-lab/overview.md +++ b/lang/en/docs/software-directory/scripting/jupyter-lab/overview.md @@ -6,7 +6,7 @@ We include support for **Jupyter Lab** versions 3.0.3 and 0.33.12 within our pla ## Data -We introduce the [structured representation](../../../data-structured/overview.md) for Jupyter Lab application [here](data.md). +We introduce the [structured representation]({{ data_url }}/data-structured/overview/) for Jupyter Lab application [here]({{ data_url }}/software-directory/scripting/jupyter-lab/data/). ## Links diff --git a/lang/en/docs/software-directory/scripting/python/data.md b/lang/en/docs/software-directory/scripting/python/data.md index 4c323777a..6eac92991 100644 --- a/lang/en/docs/software-directory/scripting/python/data.md +++ b/lang/en/docs/software-directory/scripting/python/data.md @@ -1,13 +1,13 @@ # Python: Structured Representation -We present in what follows the [structured representation](../../../data-structured/overview.md) for the [Python scripting language](overview.md). +We present in what follows the [structured representation]({{ data_url }}/data-structured/overview/) for the [Python scripting language]({{ reference_url }}/software-directory/scripting/python/overview/). === "Schema" - ``` json + ```json --8<-- "data/esse/schema/software_directory/scripting/python.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/software_directory/scripting/python.json" ``` diff --git a/lang/en/docs/software-directory/scripting/python/overview.md b/lang/en/docs/software-directory/scripting/python/overview.md index 77360a626..b4d3accd3 100644 --- a/lang/en/docs/software-directory/scripting/python/overview.md +++ b/lang/en/docs/software-directory/scripting/python/overview.md @@ -1,12 +1,12 @@ # Python Scripting -We include support for **python scripting** [^1] within our platform, using version 2.7.5 of the Python programming language interpreter by default, but supporting several other versions as options. For more information on Python versions, see [the Command Line Environment documentation's section on Python](../../../cli/environment.md#default-python-environment). +We include support for **python scripting** [^1] within our platform, using version 2.7.5 of the Python programming language interpreter by default, but supporting several other versions as options. For more information on Python versions, see [the Command Line Environment documentation's section on Python]({{ cli_url }}/cli/environment/#default-python-environment). -Python scripting can be inserted directly via the [Command Line Interface](../../../cli/overview.md), or alternatively within the [editor for the unit input templates](../../../workflow-designer/unit-editor/input-templates.md) inside [Workflow Designer](../../../workflow-designer/overview.md). +Python scripting can be inserted directly via the [Command Line Interface]({{ cli_url }}/cli/overview/), or alternatively within the [editor for the unit input templates]({{ interface_url }}/workflow-designer/unit-editor/input-templates/) inside [Workflow Designer]({{ interface_url }}/workflow-designer/overview/). ## Data -We introduce the [structured representation](../../../data-structured/overview.md) for python scripting [here](data.md). +We introduce the [structured representation]({{ data_url }}/data-structured/overview/) for python scripting [here]({{ data_url }}/software-directory/scripting/python/data/). ## Links diff --git a/lang/en/docs/software-directory/scripting/shell/data.md b/lang/en/docs/software-directory/scripting/shell/data.md index 77ab0511d..43701b697 100644 --- a/lang/en/docs/software-directory/scripting/shell/data.md +++ b/lang/en/docs/software-directory/scripting/shell/data.md @@ -1,13 +1,13 @@ # Shell Scripting: Structured Representation -We present in what follows the [structured representation](../../../data-structured/overview.md) for the [shell scripting language](overview.md). +We present in what follows the [structured representation]({{ data_url }}/data-structured/overview/) for the [shell scripting language]({{ reference_url }}/software-directory/scripting/shell/overview/). === "Schema" - ``` json + ```json --8<-- "data/esse/schema/software_directory/scripting/shell.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/software_directory/scripting/shell.json" ``` diff --git a/lang/en/docs/software-directory/scripting/shell/overview.md b/lang/en/docs/software-directory/scripting/shell/overview.md index 4e70a9ac6..a09dca424 100644 --- a/lang/en/docs/software-directory/scripting/shell/overview.md +++ b/lang/en/docs/software-directory/scripting/shell/overview.md @@ -1,8 +1,8 @@ # Shell Scripting -Our platform includes full support for **shell scripting** [^1], that is the execution of UNIX commands inside a program to be run by the [Unix shell](../../../cli/environment.md#shell-type) as command line interpreter. +Our platform includes full support for **shell scripting** [^1], that is the execution of UNIX commands inside a program to be run by the [Unix shell]({{ cli_url }}/cli/environment/#shell-type) as command line interpreter. -Shell scripts can be edited directly via the [Command Line Interface](../../../cli/overview.md), or alternatively entered within the [editor for the unit input templates](../../../workflow-designer/unit-editor/input-templates.md) inside [Workflow Designer](../../../workflow-designer/overview.md). +Shell scripts can be edited directly via the [Command Line Interface]({{ cli_url }}/cli/overview/), or alternatively entered within the [editor for the unit input templates]({{ interface_url }}/workflow-designer/unit-editor/input-templates/) inside [Workflow Designer]({{ interface_url }}/workflow-designer/overview/). ## Versions @@ -10,11 +10,11 @@ The version of bash supported on our platform is 4.2.46. ## Example -An example for running a [Quantum ESPRESSO](../../modeling/quantum-espresso/overview.md) job through a shell script executed via [Command Line Interface](../../../jobs-cli/overview.md) can be found inside [this tutorial page](../../../tutorials/jobs-cli/job-cli-example.md#4.-combined-input-script). +An example for running a [Quantum ESPRESSO](../../modeling/quantum-espresso/overview.md) job through a shell script executed via [Command Line Interface]({{ cli_url }}/jobs-cli/overview/) can be found inside [this tutorial page]({{ guide_url }}/tutorials/jobs-cli/job-cli-example/#4.-combined-input-script). ## Data -We introduce the [structured representation](../../../data-structured/overview.md) for shell scripting [here](data.md). +We introduce the [structured representation]({{ data_url }}/data-structured/overview/) for shell scripting [here]({{ data_url }}/software-directory/scripting/shell/data/). ## Links diff --git a/lang/en/docs/software/classification/analysis.md b/lang/en/docs/software/classification/analysis.md index 8df2f1d20..b18554f14 100644 --- a/lang/en/docs/software/classification/analysis.md +++ b/lang/en/docs/software/classification/analysis.md @@ -4,4 +4,4 @@ Materials can be analyzed with the help of specialized computer software assisti ## Implementation -We enable support for several analysis (and visualization) tools. which are accessible primarily via our [Remote Desktop Environment](../../remote-connection/remote-desktop.md) or [Command Line Interface](../../remote-connection/overview.md). The tools are introduced [in this section](../../software-directory/overview.md) of the documentation. +We enable support for several analysis (and visualization) tools. which are accessible primarily via our [Remote Desktop Environment]({{ cli_url }}/remote-connection/remote-desktop/) or [Command Line Interface]({{ cli_url }}/remote-connection/overview/). The tools are introduced [in this section]({{ reference_url }}/software-directory/overview/) of the documentation. diff --git a/lang/en/docs/software/classification/development.md b/lang/en/docs/software/classification/development.md index f8ba4aeac..9af0a74d8 100644 --- a/lang/en/docs/software/classification/development.md +++ b/lang/en/docs/software/classification/development.md @@ -4,4 +4,4 @@ Development tools are comprised of **compilers** and **libraries**, necessary in ## Implementation -We provide support for several development libraries and compilers on our platform, which are introduced [in this section](../../software-directory/overview.md) of the documentation. +We provide support for several development libraries and compilers on our platform, which are introduced [in this section]({{ reference_url }}/software-directory/overview/) of the documentation. diff --git a/lang/en/docs/software/classification/machine-learning.md b/lang/en/docs/software/classification/machine-learning.md index a0b1d8039..160b839fc 100644 --- a/lang/en/docs/software/classification/machine-learning.md +++ b/lang/en/docs/software/classification/machine-learning.md @@ -4,4 +4,4 @@ ## Implementation -We have a proof-of-concept support for Machine Learning within our platform as a way to do predictive modeling of materials, as mentioned [in this section](../../software-directory/overview.md#machine-learning) of the documentation. +We have a proof-of-concept support for Machine Learning within our platform as a way to do predictive modeling of materials, as mentioned [in this section]({{ reference_url }}/software-directory/overview/#machine-learning) of the documentation. diff --git a/lang/en/docs/software/classification/modeling.md b/lang/en/docs/software/classification/modeling.md index 283e410e9..4a7396895 100644 --- a/lang/en/docs/software/classification/modeling.md +++ b/lang/en/docs/software/classification/modeling.md @@ -6,7 +6,7 @@ These engines may be based on such [theoretical models](../../models/overview.md ## Implementation -The modeling engines which are implemented on our platform are introduced [in this section](../../software-directory/overview.md) of the documentation. +The modeling engines which are implemented on our platform are introduced [in this section]({{ reference_url }}/software-directory/overview/) of the documentation. ## Links diff --git a/lang/en/docs/software/classification/scripting.md b/lang/en/docs/software/classification/scripting.md index 0b321c179..f92091480 100644 --- a/lang/en/docs/software/classification/scripting.md +++ b/lang/en/docs/software/classification/scripting.md @@ -4,7 +4,7 @@ A scripting language [^1] is a programming language that supports **scripts**, o ## Implementation -We provide support for several scripting languages on our platform, which are introduced [in this section](../../software-directory/overview.md) of the documentation. +We provide support for several scripting languages on our platform, which are introduced [in this section]({{ reference_url }}/software-directory/overview/) of the documentation. ## Links diff --git a/lang/en/docs/software/components.md b/lang/en/docs/software/components.md index 6271b2242..195a33675 100644 --- a/lang/en/docs/software/components.md +++ b/lang/en/docs/software/components.md @@ -2,7 +2,7 @@ The concept of **"Software Application"** is related to the main **modeling engine** and associated software tools employed by the user for the design, execution and postprocessing of a [simulation Job](../jobs/overview.md), through the implementation of any of the available [computational methods](../methods/overview.md). -Each application may be comprised of one or multiple **Executables**, implementing in turn different possible computation **Flavors**. These settings can be entered within the [unit editor interface](../workflow-designer/unit-editor.md#application) of [Workflow Designer](../workflow-designer/overview.md). +Each application may be comprised of one or multiple **Executables**, implementing in turn different possible computation **Flavors**. These settings can be entered within the [unit editor interface]({{ interface_url }}/workflow-designer/unit-editor/#application) of [Workflow Designer]({{ interface_url }}/workflow-designer/overview/). ## Executables @@ -10,9 +10,9 @@ Applications are typically run via the launching of their respective executable ### Example -The [Quantum ESPRESSO](../software-directory/modeling/quantum-espresso/overview.md) modeling application for example is comprised of several main input executables, included as part of its distribution package, such as `pw.x`, `ph.x`, `bands.x` etc. +The [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) modeling application for example is comprised of several main input executables, included as part of its distribution package, such as `pw.x`, `ph.x`, `bands.x` etc. -Other applications such as [VASP](../software-directory/modeling/vasp/overview.md) on the other hand contain just a single main executable, through which all of its supported computation features can be performed. +Other applications such as [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) on the other hand contain just a single main executable, through which all of its supported computation features can be performed. ## Flavors diff --git a/lang/en/docs/software/data.md b/lang/en/docs/software/data.md index 013d76511..3f89c2d95 100644 --- a/lang/en/docs/software/data.md +++ b/lang/en/docs/software/data.md @@ -1,42 +1,42 @@ # Structured Representations -We provide below examples of JSON-based structured representation for an application, and for each of its possible [components](overview.md#applications) (executables and flavors) and [classification categories](classification/overview.md). This structured representation is based upon the [Exabyte Data Convention](../data-structured/overview.md) implemented throughout our platform. +We provide below examples of JSON-based structured representation for an application, and for each of its possible [components]({{ reference_url }}/software/overview/#applications) (executables and flavors) and [classification categories]({{ reference_url }}/software/classification/overview/). This structured representation is based upon the [ESSE Data Convention](../data-structured/overview.md) implemented throughout our platform. !!! note "Work in progress" - Some applications are yet to be fully integrated into our platform to have a structured representation. These are only available via [Command Line Interface](../cli/overview.md). + Some applications are yet to be fully integrated into our platform to have a structured representation. These are only available via [Command Line Interface]({{ cli_url }}/cli/overview/). -## [Application](components.md) +## [Application]({{ reference_url }}/software/components/) === "Schema" - ``` json + ```json --8<-- "data/esse/schema/software/application.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/software/application.json" ``` -## [Executable](components.md#executables) +## [Executable]({{ reference_url }}/software/components/#executables) === "Schema" - ``` json + ```json --8<-- "data/esse/schema/software/executable.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/software/executable.json" ``` -## [Flavor](components.md#flavors) +## [Flavor]({{ reference_url }}/software/components/#flavors) === "Schema" - ``` json + ```json --8<-- "data/esse/schema/software/flavor.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/software/flavor.json" ``` diff --git a/lang/en/docs/software/overview.md b/lang/en/docs/software/overview.md index f3a9d107d..89276ab8f 100644 --- a/lang/en/docs/software/overview.md +++ b/lang/en/docs/software/overview.md @@ -2,9 +2,9 @@ We review in the present section of the documentation the most important general concepts underlying the **Software** comprised within the scope of our platform. This software is necessary for performing such tasks as executing materials modeling simulations, or for analyzing and visualizing their corresponding output. -## [List of Available Software](../software-directory/overview.md) +## [List of Available Software]({{ reference_url }}/software-directory/overview/) -The reader is referred to [another section](../software-directory/overview.md) of the documentation for a complete list and review of the specific software packages available for use on our platform. +The reader is referred to [another section]({{ reference_url }}/software-directory/overview/) of the documentation for a complete list and review of the specific software packages available for use on our platform. ## [Components](components.md) @@ -14,6 +14,6 @@ We introduce the concepts of an [application](components.md), and of its constit We classify software into a set of distinct categories, as narrated [in this section](classification/overview.md) of the documentation. -## [Data](data.md) +## [Data]({{ data_url }}/software/data/) -We provide a list of [JSON-based structured representations](../data-structured/overview.md) for applications, and for each of their components, [in this page](data.md). +We provide a list of [JSON-based structured representations]({{ data_url }}/data-structured/overview/) for applications, and for each of their components, [in this page]({{ data_url }}/software/data/). diff --git a/lang/en/docs/tutorials/contribute-new-application.md b/lang/en/docs/tutorials/contribute-new-application.md new file mode 100644 index 000000000..37fb4bdb7 --- /dev/null +++ b/lang/en/docs/tutorials/contribute-new-application.md @@ -0,0 +1,418 @@ +# Contribute New Applications to Mat3ra + +!!!abstract "TL;DR" + Bringing your own application to the Mat3ra platform is a two-step process: + + 1. **Build the Image:** Package your application into an Apptainer + container. Create a PR to the [application-containers-public]( + https://github.com/mat3ra/application-containers-public) repository + with the Apptainer `.def` file and register it in `manifest.yml`. Merge this + PR first so the container image is built and published to the GitHub + Container Registry (GHCR). + + 2. **Update the Metadata:** Add the application's YAML metadata, templates, + and executables, ensuring your image tag matches Step 1 exactly. Create a PR + to the [standata](https://github.com/mat3ra/standata) repository. Once + merged and deployed, the application will be available on both the + web-interface and the CLI. + +This page explains how developers and advanced users can contribute new +application to the Mat3ra platform so that it becomes a first-class option in +both the web-interface and the [Command Line Interface (CLI)](/cli/overview). + +This task involves adding necessary configurations to two repositories via pull +requests. A basic understanding of container technologies (such as Apptainer, +Singularity, or Docker), a GitHub account, [Node.js](https://nodejs.org) +installed in local development machine, and a working Apptainer `.def` file are +required before proceeding. If you need help with preparing Apptainer +definition, please consult the [Add Software](/cli/actions/add-software) page +first. + + +![Application Selection in Web-Interface](../../../../images/tutorials/new-application/application-selection-web-ui.webp "Application Selection in Web-Interface") + + +## 1. Overview + +### 1.1. Understand the two-repository architecture + +Contributing a new application involves creating Pull Requests (PRs) to two +repositories: + +[**application-containers-public**]( +https://github.com/mat3ra/application-containers-public) holds the Apptainer +definition files and a `manifest.yml` that drives a GitHub Actions (GHA) +workflow. On merge, GHA builds each image and pushes it to the GitHub Container +Registry (GHCR). + +[**standata**](https://github.com/mat3ra/standata) holds the platform +metadata, including application name, version, build flavor, the GHCR image tag +to pull, and the runtime environment variables. The platform reads this +repository to populate the application dropdown in the web-interface. Necessary +modulefiles are also generated based on these metadata for CLI use. + +The two repositories are coupled by `imageName` and `imageTag`: the value +provided to `standata` must exactly match the value registered in +`application-containers-public`. As a result, the container pull request must be +merged and the image published before the `standata` pull request can be merged. + +```mermaid +flowchart TB + Dev[Developer machine] + + subgraph containers["application-containers-public"] + AppRepo[manifest.yml + .def files] + GHA[GitHub Actions] + GHCR[GHCR images] + AppRepo --> GHA --> GHCR + end + + subgraph standata["standata"] + Meta[applications YAML\n+ executables + templates] + end + + Platform[Mat3ra platform] + + Dev -->|"PR: .def + manifest.yml"| AppRepo + Dev -->|"PR: apps YAML + executables + templates"| Meta + GHCR -->|"imageName + imageTag"| Meta + Meta --> Platform +``` + + +## 2. `application-containers-public` repository + +### 2.1. Fork and clone the repository + +First, fork [github.com/mat3ra/application-containers-public]( +https://github.com/mat3ra/application-containers-public) on GitHub, then +clone the fork locally. The top-level layout is: + +``` +application-containers-public/ +├── base/ +├── espresso/ +├── lammps/ +├── nwchem/ +├── manifest.yml +├── inheritance-tree.png +└── .github/workflows/cicd.yml +``` + +Under `base/` are foundational images: AlmaLinux base, GNU toolchain variant, +Intel OneAPI variant, NVIDIA HPC SDK variant, and so on. Each application has +its own subdirectory containing one `.def` file per build variant. + +### 2.2. Add the `.def` file + +Add the Apptainer definition file under the appropriate application directory, +e.g. `espresso/espresso-7.5-gnu.def`. Two conventions must be followed. + +First, bootstrap from an existing base image using `Bootstrap: oras` wherever +possible: + +```singularity +Bootstrap: oras +From: ghcr.io/mat3ra/application-containers-public/almalinux-apptainer-gnu:9.7-2 +``` + +This reuses tested toolchains and keeps build times short. + +Second, source the parent environment file at the top of `%post`: + +```singularity +%post + if [ -f /.singularity.d/env/91-environment.sh ]; then + . /.singularity.d/env/91-environment.sh + fi +``` + +This picks up environment variables (e.g. OpenMPI `PATH` and `LD_LIBRARY_PATH`) +set by the parent base image. Application-specific runtime variables belong in +the `%environment` section. + +!!!tip "Multi-stage builds" + In order to keep image size small, use a first stage that compiles against + the large toolchain, then copy only the compiled executables into a + lightweight final stage. The Mat3ra platform bind-mounts the required + runtime libraries from the host compute node at job execution time. + +!!!warning "Do not bake large toolchains into the image" + Libraries such as NVIDIA HPC SDK and Intel OneAPI are pre-installed on the + clusters and available via NFS. Embedding them would produce images tens of + GB in size. Declare them instead as `environmentVariables` in `standata` + (see [Section 3.2](#32-add-the-application-version-block)). + +### 2.3. Register the image in `manifest.yml` + +Open `manifest.yml` at the repository root and add an entry for the new +application: + +```yaml +- name: espresso + path: espresso/espresso-7.5-gnu.def + tag: 7.5-gnu-1 +``` + +The three fields are: + +- `name` → the image name in the registry. +- `path` → location of the `.def` file relative to the repository root. +- `tag` → follows the convention `--` where `N` is a + build iteration starting from `0`. Bump `N` whenever the recipe changes + without a version change for the application; the CI treats tags as immutable + and skips a build if the tag already exists. + +### 2.4. Open the pull request and verify the build + +Open a pull request against the `main` branch of +`application-containers-public`. The CI workflow iterates over `manifest.yml`, +checks whether each tag already exists in GHCR, and if not, runs +`apptainer build` and `oras push`. On pull requests the push step is skipped +(dry run); the image is published only after the PR is merged. + +After merge, the image is available at: + +```bash +apptainer pull oras://ghcr.io/mat3ra/application-containers-public/espresso:7.5-gnu-1 +``` + +The image name, and tag are needed in the next section. + +### 2.5. Example Pull Requests +- [GNU build of Quantum ESPRESSO 7.5](https://github.com/mat3ra/application-containers-public/pull/7/changes) +- [Intel build of LAMMPS](https://github.com/mat3ra/application-containers-public/pull/9/changes) + + +## 3. `standata` repository + +!!!info + Although the `standata` repository contains JavaScript code, the only + changes required to add new application are in the YAML files. YAML is a + human-readable data serialization format, containing key-value pairs, lists, + and nested structures, very similar to JSON or dictionaries in Python and + other programming languages. + +### 3.1. Fork and clone the repository + +Fork [github.com/mat3ra/standata](https://github.com/mat3ra/standata) +and clone locally. The relevant subtree is: + +``` +assets/applications/ +├── applications/ +│ ├── application_data.yml +│ ├── espresso.yml +│ ├── lammps.yml +│ └── ... +├── executables/ +└── templates/ +``` + +Each application has its own YAML file under `applications/`, and +`application_data.yml` is the index that the build process reads. + +### 3.2. Add application version block + +Create or extend the YAML file for the new application, e.g. +`assets/applications/applications/espresso.yml`. Each version block follows this +structure: + +```yaml +- version: '7.5' + isDefault: true + build: GNU + hasAdvancedComputeOptions: true + buildConfig: + moduleName: '7.5-gnu' + imageName: 'espresso' + imageTag: '7.5-gnu-1' + bio: 'Quantum ESPRESSO 7.5 (GCC 11.5.0, OpenMPI 4.1.1 and OpenBLAS)' + dependencies: + - 'mpi/ompi-4.1.1' + environmentVariables: {} +``` + +The `imageName` and `imageTag` fields must exactly match what was registered in +`manifest.yml` in the container repository. This is the link between the two +repositories. + +For applications that require mapping host-side toolchains (e.g. NVIDIA HPC SDK +or Intel OneAPI), declare the Apptainer environment forwarding variables under +`environmentVariables`. The prefix `APPTAINERENV_` instructs Apptainer to inject +the variable into the container at runtime: + +```yaml +environmentVariables: + APPTAINERENV_PREPEND_PATH: '${SOFTWARE_LIBRARIES_PATH}/nvidia/hpc-sdk/bin' + APPTAINERENV_LD_LIBRARY_PATH: '${SOFTWARE_LIBRARIES_PATH}/nvidia/hpc-sdk/lib' +``` + +`SOFTWARE_LIBRARIES_PATH` is a platform-native variable that resolves to the +correct host directory for the cluster the job lands on. Consult an existing +CUDA or Intel entry in `espresso.yml` as a template when the exact paths are +unknown. + +The remaining fields are: + +- `isDefault: true` → marks the version selected by default in the UI. +- `hasAdvancedComputeOptions: true` → exposes the advanced compute settings + panel. +- `build` → the flavor label shown in the version submenu (e.g. `GNU`, + `Intel`, `CUDA`). + +### 3.3. Register in `application_data.yml` + +Add a single `!include` statement to +`assets/applications/applications/application_data.yml`: + +```yaml +espresso: !include 'applications/espresso.yml' +``` + +In order to expose executables in the UI or provide starter input templates, +also populate `assets/applications/executables//` and +`assets/applications/templates//` respectively. + +### 3.4. Add an executable + +The executable YAML describes the command that the platform runs, the input +files it expects, and the results and monitors it produces. Create +`assets/applications/executables/myapp/myapp.yml` following the LAMMPS +pattern: + +```yaml +isDefault: true +monitors: + - standard_output +results: [] +flavors: + myrun: + isDefault: true + input: + - name: flavor.in + results: [] + monitors: + - standard_output + applicationName: myapp + executableName: myexec +``` + +Each key in `flavors` corresponds to one flavor visible in the workflow designer +unit editor. The `input` list names the input files the template system will +render. `monitors` controls which output streams the platform captures in real +time (at minimum `standard_output`). + +Then register the executable in `assets/applications/executables/tree.yml`: + +```yaml +myapp: + myapp: !include 'executables/myapp/myapp.yml' +``` + +### 3.5. Add an input file template and flavor + +The template system connects the executable flavor to a rendered input file. +This is what the user sees and edits inside the workflow designer unit editor. + +**Step 1: Write the raw input file.** Create the actual input content under +`assets/applications/input_files_templates/myapp/flavor.in`. This is the +default input script that a user starts from. It may be a static file or +contain [Jinja](https://jinja.palletsprojects.com/) template variables if the +platform should substitute material-specific values at runtime. + +**Step 2: Write the flavor YAML.** Create +`assets/applications/templates/myapp/flavor.yml`: + +```yaml +- content: !readFile 'input_files_templates/myapp/flavor.in' + name: flavor.in + contextProviders: [] + applicationName: myapp + executableName: myexec +``` + +The `!readFile` tag inlines the raw input file at build time. `contextProviders` +is an optional list of platform context plugins that inject material or job +properties into the template at render time; leave it empty for a static +template. + +**Step 3: Register the flavor in `templates.yml`.** Add a line to +`assets/applications/templates/templates.yml`: + +```yaml +# myapp +- !include 'templates/myapp/flavor.yml' +``` + +After these three steps, the `flavor` appears in the unit editor when a user +selects `myapp` as the application and `myexec` as the executable. + +### 3.6. Build and validate locally + +Run the following commands in the `standata` checkout to verify that the YAML +parses correctly and the generated data looks as expected: + +```bash +npm install +npm run build:applications +npm run build # to build all assets +npm run test # to run the tests +``` + +`build:applications` generates per-application JSON under `data/applications/`. +Inspect the diffs to confirm the version block is present, the `imageTag` +matches the container repository, the executable flavor appears, and the +template content renders correctly. + +### 3.7. Open the pull request + +Open a pull request against `standata` only after the container pull request +has been merged and the image is live in GHCR. Commit the generated files under +`data/` and `dist/` produced by the build step above. + +### 3.8. Example Pull Requests +- [Quantum ESPRESSO 7.5](https://github.com/mat3ra/standata/pull/109/changes) +- [LAMMPS](https://github.com/mat3ra/standata/pull/91/changes) + +One may ignore the auto-generated files under `data/`, `dist/`, and `src/` +directories while reviewing the PR changes. + + +## 4. Merge order and checklist + +Merge order is mandatory: the container pull request must be merged first so +that the image tag referenced in `standata` is valid when that PR is reviewed. + +### 4.1. `application-containers-public` PR Checklist + ✅ `.def` file added under the correct application directory
+ ✅ `manifest.yml` entry with correct name, path, and tag
+ ✅ CI passes (dry-run build succeeds)
+ ✅ Merged first + +### 4.2. `standata` PR Checklist + ✅ `applications/myapp.yml` with matching `imageName` and `imageTag`
+ ✅ `!include` added to `application_data.yml`
+ ✅ `executables/myapp/myapp.yml` with at least one flavor
+ ✅ `myapp` entry added to `executables/tree.yml`
+ ✅ `input_files_templates/myapp/flavor.in` created
+ ✅ `templates/myapp/flavor.yml` created
+ ✅ `!include` added to `templates/templates.yml`
+ ✅ `npm run build` outputs committed
+ ✅ Merged after the container PR is merged + +Once both PRs are merged and the next platform release ships, the application +appears in the application dropdown for every user. The container image is +pulled from GHCR on first use, the version block drives the runtime environment, +and the flavor/template pair appears in the workflow designer unit editor. The +application is also available via modulefile for CLI use. + +![Load application with modulefile](../../../../images/tutorials/new-application/application-modules-cli.webp "Load application with modulefile") + + +## 5. References + +- Apptainer Definition and container building: [Adding New Software](/cli/actions/add-software) +- Container repository: [github.com/mat3ra/application-containers-public](https://github.com/mat3ra/application-containers-public) +- Metadata repository: [github.com/mat3ra/standata](https://github.com/mat3ra/standata) +- Published images: [Mat3ra packages on GHCR](https://github.com/orgs/mat3ra/packages?repo_name=application-containers-public) diff --git a/lang/en/docs/tutorials/dft/addons/kpt-convergence.md b/lang/en/docs/tutorials/dft/addons/kpt-convergence.md index b1b99c0f3..eaac5829d 100644 --- a/lang/en/docs/tutorials/dft/addons/kpt-convergence.md +++ b/lang/en/docs/tutorials/dft/addons/kpt-convergence.md @@ -1,55 +1,66 @@ -# Study Convergence of the Reciprocal Space Grid +--- +render_macros: true +--- +# Reciprocal Space Grid Convergence Study -The present tutorial page explains how to run a [convergence study](../../../models/auxiliary-concepts/reciprocal-space/convergence.md) of the size of the [grid of k-points](../../../models/auxiliary-concepts/reciprocal-space/sampling.md), necessary for sampling the Brillouin Zone of the crystal structure under investigation, using [density functional theory](../../../models-directory/dft/overview.md). +This tutorial explains how to run a [convergence study]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/convergence/) of the [k-point grid]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) size using [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT). -K-point convergence can be run either as a stand-alone [workflow](../../../workflows/overview.md), or prepended as a [Workflow Add-on](../../../workflows/addons/overview.md) to another [property calculation](../../../properties/overview.md). +K-point convergence can be run either as a stand-alone [workflow]({{ reference_url }}/workflows/overview/) or prepended as a [Workflow Add-on]({{ reference_url }}/workflows/addons/overview/) to another [property calculation]({{ reference_url }}/properties/overview/). -In the present tutorial, we will study the issue of k-point convergence for the case of crystalline silicon under its equilibrium cubic-diamond crystal structure, by making use of [VASP](../../../software-directory/modeling/vasp/overview.md) as the main simulation engine. We will investigate k-point convergence in the context of a [Total Energy](../../../properties-directory/scalar/total-energy.md) calculation. +The example system is crystalline silicon in its cubic-diamond crystal structure, using [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) as the simulation engine in the context of a [Total Energy]({{ reference_url }}/properties-directory/scalar/total-energy/) calculation. -!!!note "VASP version considered in this tutorial" - The present tutorial is written for VASP at versions 5.3.5 or 5.4.4. +!!!note "VASP version" + This tutorial applies to VASP versions 5.3.5, 5.4.4, and later. -## Create Job -Silicon in its cubic-diamond crystal structure is the [default material](../../../materials/default.md) that is shown on [new job creation](../../../jobs-designer/overview.md), unless this default was [changed](../../../entities-general/actions/set-default.md) by the user following [account](../../../accounts/overview.md) creation. If silicon is still the default choice, it will be automatically loaded at the moment of the [opening](../../../jobs/actions/create.md) of [Job Designer](../../../jobs-designer/overview.md). +## 1. Create the job -## Choose workflow +Silicon in its cubic-diamond crystal structure is the [default material]({{ reference_url }}/materials/default/) loaded on [new job creation]({{ interface_url }}/jobs-designer/overview/), unless the default was [changed]({{ interface_url }}/entities-general/actions/set-default/) after [account]({{ reference_url }}/accounts/overview/) creation. -[Workflows](../../../workflows/overview.md) for calculating the Total Energy through [VASP](../../../software-directory/modeling/vasp/overview.md) can readily be [imported](../../../workflows/actions/copy-bank.md) from the [Workflows Bank](../../../workflows/bank.md) into the account-owned [collection](../../../accounts/collections.md). This workflow can later be [selected](../../../jobs-designer/actions-header-menu/select-workflow.md) and added to the [Job being created](../../../jobs-designer/workflow-tab.md). -Thereafter, in order to add k-point convergence as an [Add-on](../../../workflows/addons/overview.md) to the total energy calculation workflow, the user should [click the appropriate button](../../../workflow-designer/subworkflow-editor/actions-menu.md#insert-add-ons) within the [Subworkflow Editor Interface](../../../workflow-designer/subworkflow-editor/overview.md) of [Workflow Designer](../../../workflow-designer/overview.md). The corresponding "Convergence" option should thus be chosen. The parameters contained in the resulting "Convergence" dialog should be set according to the instructions outlined [in this page](../../../models/auxiliary-concepts/reciprocal-space/convergence.md). For the moment, we shall just accept the default contents of such dialog, and proceed with no further modifications by clicking the bottom `Apply` button. +## 2. Select the workflow and add the convergence add-on -At the end of the insertion of the k-point convergence Add-on to the Total Energy Workflow, the user can scroll down to view the extra [units](../../../workflows/components/units.md) which have been added for convergence purposes, which are primarily of [Logical type](../../../workflows/components/units.md#unit-types). The objective of such units is to set up the parameters necessary to progressively increase [k-point density](../../../models/auxiliary-concepts/reciprocal-space/sampling.md), and consequently check the corresponding evolution of the total energy difference throughout the study to ensure a sufficiently accurate final convergence. +[Workflows]({{ reference_url }}/workflows/overview/) for calculating the Total Energy through [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/). The workflow can then be [selected]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) and added to the [job being created]({{ interface_url }}/jobs-designer/workflow-tab/). -## Examine Input Files +In order to add k-point convergence as an [Add-on]({{ reference_url }}/workflows/addons/overview/), [click the appropriate button]({{ interface_url }}/workflow-designer/subworkflow-editor/actions-menu/#insert-add-ons) within the [Subworkflow Editor]({{ interface_url }}/workflow-designer/subworkflow-editor/overview/) and select "Convergence". The parameters in the resulting dialog can be set according to the instructions in [this page]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/convergence/). Accepting the default settings and clicking **Apply** is sufficient for this tutorial. -Readers can open the main [Execution Unit](../../../workflows/components/units.md#execution) "vasp" by clicking it. The contents of the input files used for the convergence study within the VASP calculation can in this way be inspected, towards the bottom of the [unit editor interface](../../../workflow-designer/unit-editor.md#unit-input-templates). +After insertion, scrolling down reveals the extra [units]({{ reference_url }}/workflows/components/units/) added for convergence purposes, primarily of [Logical type]({{ reference_url }}/workflows/components/units/#unit-types). These units progressively increase [k-point density]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) and check the total energy difference at each step. -Users should be able to notice some differences in the formatting of the KPOINTS file, compared to the more conventional cases. This file should not normally be edited, or should be edited with caution, since the text is modified to contain [templating expressions](../../../workflows/templating/overview.md) (eg. `{{PARAMETER}}`) that are necessary for the workflow to function correctly. -## Submit Job +## 3. Examine the input files -Before [submitting](../../../jobs/actions/run.md) the [Job](../../../jobs/overview.md), the user should click on the ["Compute" tab](../../../jobs-designer/compute-tab.md) of [Job Designer](../../../jobs-designer/overview.md) and inspect the [compute parameters](../../../infrastructure/compute/parameters.md) included therein. Silicon is a small structure, so four cores and a few minutes of calculation runtime should be sufficient. +The main [Execution Unit]({{ reference_url }}/workflows/components/units/#execution) "vasp" can be opened by clicking it. The input files are visible towards the bottom of the [unit editor]({{ interface_url }}/workflow-designer/unit-editor/#unit-input-templates). -## Examine Results +!!!warning "Templating in KPOINTS" + The KPOINTS file contains [templating expressions]({{ reference_url }}/workflows/templating/overview/) (e.g. {% raw %}`{{PARAMETER}}`{% endraw %}) required for workflow operation. This file should not be edited, or edited with caution. -Once the Job execution is finished, switching to the [Results tab](../../../jobs/ui/results-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md) will show the results of the computation, including the final converged value of the total energy as well as additional information about each execution unit. -## Converged k-point Density +## 4. Submit the job -Finally, the user can also browse the output and input files under the [Files tab](../../../jobs/ui/files-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md). In order to determine the k-point density at which convergence was reached, the KPOINTS file should be [downloaded and inspected](../../../data-in-objectstorage/actions/download.md). +Before [submitting]({{ interface_url }}/jobs/actions/run/) the [job]({{ reference_url }}/jobs/overview/), review the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) of [Job Designer]({{ interface_url }}/jobs-designer/overview/) to verify the [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/). Silicon is a small structure, so 4 CPUs and a few minutes of runtime are sufficient. -### Convergence plot -The convergence plot can be retrieved upon Job completion under the "Charts" tab accessible by opening the main "vasp" Execution Unit. The relevant convergence plot is the one labelled "Ionic Energy". In order for this plot to appear among the calculation results, the "convergence_ionic" option should be selected under the ["Detailed View" tab](../../../workflow-designer/subworkflow-editor/detailed-view.md) of the Total Energy [Subworkflow Editor Interface](../../../workflow-designer/subworkflow-editor/overview.md) at the moment of initial Job designing. +## 5. Examine the results -An example appearance of the "Ionic Energy" energy convergence chart as a function of [k-grid size](../../../models/auxiliary-concepts/reciprocal-space/sampling.md#kgrid) is given in the image below. In this case, after a sharp initial shift in energy, the desired convergence precision threshold has been reached for a k-grid size of 13 X 13 X 13. The threshold corresponds to the relative energy change between two subsequent steps in the k-grid size progression shown on the x-axis. +Once the job completes, the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) displays the final converged total energy and additional information about each execution unit. + + +## 6. Determine the converged k-point density + +The output and input files are available under the [Files tab]({{ interface_url }}/jobs/ui/files-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). The KPOINTS file can be [downloaded and inspected]({{ interface_url }}/data-in-objectstorage/actions/download/) to determine the k-point density at which convergence was reached. + +### 6.1. View the convergence plot + +The convergence plot is available under the "Charts" tab of the main "vasp" Execution Unit. The relevant plot is labelled "Ionic Energy". For this plot to appear, the "convergence_ionic" option must be selected under the [Detailed View tab]({{ interface_url }}/workflow-designer/subworkflow-editor/detailed-view/) of the Total Energy [Subworkflow Editor]({{ interface_url }}/workflow-designer/subworkflow-editor/overview/) at job design time. + +An example convergence chart is shown below. After a sharp initial shift in energy, the desired convergence precision threshold is reached at a k-grid of 13 × 13 × 13. ![Convergence Plot](../../../images/tutorials/kpoint-convergence-chart.png "Convergence Plot") -## Animation -We demonstrate the above-mentioned steps involved in the creation and execution of a k-points convergence study using silicon and [Total Energy](../../../properties-directory/scalar/total-energy.md) workflow in the video below. +## 7. Video walkthrough + +The animation below demonstrates the creation and execution of a k-point convergence study using silicon and a [Total Energy]({{ reference_url }}/properties-directory/scalar/total-energy/) workflow.
diff --git a/lang/en/docs/tutorials/dft/addons/structural-relaxation.md b/lang/en/docs/tutorials/dft/addons/structural-relaxation.md index cd9dfc5b7..70b23411f 100644 --- a/lang/en/docs/tutorials/dft/addons/structural-relaxation.md +++ b/lang/en/docs/tutorials/dft/addons/structural-relaxation.md @@ -1,63 +1,66 @@ -# Perform Structural Relaxation +# Perform Structural Relaxation -This tutorial explains how to run a [structural relaxation](../../../workflows/addons/structural-relaxation.md) using [Density Functional Theory](../../../models-directory/dft/overview.md). Variable-cell relaxation consist in simultaneously minimizing the inter-atomic forces, whilst also optimizing the overall lattice geometry by minimizing its corresponding potential energy together with the components of its internal [stress tensor](../../../properties-directory/non-scalar/stress-tensor.md). +This tutorial explains how to run a [structural relaxation]({{ reference_url }}/workflows/addons/structural-relaxation/) using [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT). Variable-cell relaxation simultaneously minimizes inter-atomic forces while optimizing the lattice geometry by minimizing its potential energy and [stress tensor]({{ reference_url }}/properties-directory/non-scalar/stress-tensor/) components. -## Accessing the Functionality +Relaxation can be run either as a stand-alone [workflow]({{ reference_url }}/workflows/overview/) or prepended as a [Workflow Add-on]({{ reference_url }}/workflows/addons/overview/) to another [property calculation]({{ reference_url }}/properties/overview/). -Relaxation can be run either as a stand-alone [workflow](../../../workflows/overview.md), or prepended as a [Workflow Add-on](../../../workflows/addons/overview.md) to another [property calculation](../../../properties/overview.md). +The example system is crystalline silicon distorted from its equilibrium cubic-diamond crystal structure, using [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) as the simulation engine for a [Total Energy]({{ reference_url }}/properties-directory/scalar/total-energy/) computation. Relaxation prior to a property calculation is a critical step for ensuring accurate final results. -## Summary +!!!info "General applicability" + Despite referencing [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/), the instructions here apply to all [modeling engines]({{ reference_url }}/software-directory/overview/#modeling-applications) supported on the platform. -In the present tutorial, we study the crystalline silicon distorted from its equilibrium cubic-diamond crystal structure and make use of the [VASP](../../../software-directory/modeling/vasp/overview.md) simulation engine. We will investigate how to optimize the crystal structure geometry and atomic positions in the context of a [Total Energy](../../../properties-directory/scalar/total-energy.md) computation. Relaxation prior to a property calculation is generally-speaking a critical precaution to take in order to ensure an accurate final result in the material property being sought. +!!!note "VASP version" + This tutorial applies to VASP versions 5.3.5, 5.4.4, and later. -!!!info "Generality of tutorial instructions" - Despite making explicit references to [VASP](../../../software-directory/modeling/vasp/overview.md), the instructions presented herein are of general applicability to all [modeling engines](../../../software-directory/overview.md#modeling-applications) supported on our platform. - -!!!note "VASP version considered in this tutorial" - The present tutorial is written for VASP at versions 5.3.5 or 5.4.4. -## Create Job +## 1. Create the job -Silicon in its cubic-diamond crystal structure is the [default material](../../../materials/default.md) shown on [new job creation](../../../jobs-designer/overview.md), unless this default was [changed](../../../entities-general/actions/set-default.md) by the user following [account](../../../accounts/overview.md) creation. If silicon is still the default choice, it will be automatically loaded at the moment of the [opening](../../../jobs/actions/create.md) of [Job Designer](../../../jobs-designer/overview.md). +Silicon in its cubic-diamond crystal structure is the [default material]({{ reference_url }}/materials/default/) loaded on [new job creation]({{ interface_url }}/jobs-designer/overview/), unless the default was [changed]({{ interface_url }}/entities-general/actions/set-default/) after [account]({{ reference_url }}/accounts/overview/) creation. -## Choose Workflow -[Workflows](../../../workflows/overview.md) for calculating the Total Energy can be [imported](../../../workflows/actions/copy-bank.md) from the [Workflows Bank](../../../workflows/bank.md) into the account-owned [collection](../../../accounts/collections.md). This workflow can later be [selected](../../../jobs-designer/actions-header-menu/select-workflow.md) and added to the [Job being created](../../../jobs-designer/workflow-tab.md). +## 2. Select the workflow and add the relaxation add-on -Thereafter, in order to add structural relaxation as an [Add-on](../../../workflows/addons/overview.md) to the total energy calculation workflow, the user should [click the appropriate button](../../../workflow-designer/header-menu.md#inserting-add-ons) within the [Header Menu](../../../workflow-designer/header-menu.md) of [Workflow Designer](../../../workflow-designer/overview.md). The corresponding "Relaxation" option under this button should thus be chosen. +[Workflows]({{ reference_url }}/workflows/overview/) for the Total Energy calculation can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/). The workflow can then be [selected]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) and added to the [job being created]({{ interface_url }}/jobs-designer/workflow-tab/). -At the end of the insertion of the relaxation Add-on to the Total Energy Workflow, the user will notice that an additional "Variable-cell Relaxation" [Subworkflow](../../../workflows/components/subworkflows.md) has been prepended to the overall [computation order flowchart](../../../workflow-designer/sidebar.md) exhibited on the left-hand side of the [Workflow Designer Interface](../../../workflow-designer/overview.md). +In order to add structural relaxation as an [Add-on]({{ reference_url }}/workflows/addons/overview/), [click the appropriate button]({{ interface_url }}/workflow-designer/header-menu/#inserting-add-ons) within the [Header Menu]({{ interface_url }}/workflow-designer/header-menu/) of [Workflow Designer]({{ interface_url }}/workflow-designer/overview/) and select "Relaxation". -## Examine Unit Input Files +After insertion, an additional "Variable-cell Relaxation" [Subworkflow]({{ reference_url }}/workflows/components/subworkflows/) is prepended to the [computation order flowchart]({{ interface_url }}/workflow-designer/sidebar/) on the left side of the [Workflow Designer]({{ interface_url }}/workflow-designer/overview/). -The user can now try to open the main "vc-relax" [Execution Unit](../../../workflows/components/units.md) within the "Variable-cell Relaxation" [Subworkflow](../../../workflows/components/subworkflows.md) by clicking it. The contents of the input files used for the structural relaxation study can in this way be inspected, towards the bottom of the [unit editor interface](../../../workflow-designer/unit-editor.md#unit-input-templates). -The type of relaxation calculation performed is always by default a variable-cell including the relaxation of the [atomic positions](../../../properties-directory/structural/basis.md) as well as of the [unit cell shape and size](../../../properties-directory/structural/lattice.md). +## 3. Examine the unit input files -Please note that the second total energy subworkflow reads the structural information output by the preliminary relaxation, instead of the parameters in its own input. - -!!!note "Specific example for VASP" - The POSCAR file employed in the ensuing Total Energy subworkflow computation is just a placeholder, and during the course of its execution will be overwritten by a CONTCAR file obtained from the results of the relaxation. This behavior is triggered by the "prepare_restart" post-processor. +Open the main "vc-relax" [Execution Unit]({{ reference_url }}/workflows/components/units/) within the "Variable-cell Relaxation" [Subworkflow]({{ reference_url }}/workflows/components/subworkflows/) by clicking it. The input files can be inspected towards the bottom of the [unit editor]({{ interface_url }}/workflow-designer/unit-editor/#unit-input-templates). -## Submit Job +The relaxation type is variable-cell by default, including both [atomic positions]({{ reference_url }}/properties-directory/structural/basis/) and [unit cell shape and size]({{ reference_url }}/properties-directory/structural/lattice/). -Before [submitting](../../../jobs/actions/run.md) the [Job](../../../jobs/overview.md), the user should click the ["Compute" tab](../../../jobs-designer/compute-tab.md) of [Job Designer](../../../jobs-designer/overview.md) and inspect the [compute parameters](../../../infrastructure/compute/parameters.md) included therein. Silicon is a small structure, so four CPU cores and one minute of calculation runtime should be sufficient. +The second total energy subworkflow reads the structural information output by the preliminary relaxation, rather than the parameters in its own input. -## Examine Results +!!!note "VASP-specific behavior" + The POSCAR file in the ensuing Total Energy subworkflow is a placeholder that is overwritten during execution by the CONTCAR file from the relaxation results. This behavior is triggered by the "prepare_restart" post-processor. -Once the Job execution is finished, switching to the [Results tab](../../../jobs/ui/results-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md) will show the results of the computation, including the final optimized value of the total energy as well as additional information about each execution unit. -## Optimized Structural Parameters +## 4. Submit the job -Finally, the user can also browse the actual output and input files that are part of the calculation under the [Files tab](../../../jobs/ui/files-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md). In order to determine the structure geometry for which relaxation was achieved in the end, the POSCAR file can be [downloaded and inspected](../../../data-in-objectstorage/actions/download.md). +Before [submitting]({{ interface_url }}/jobs/actions/run/) the [job]({{ reference_url }}/jobs/overview/), review the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) of [Job Designer]({{ interface_url }}/jobs-designer/overview/) to verify the [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/). Silicon is a small structure, so 4 CPUs and 1 minute of runtime are sufficient. -The structural data contained in this file can readily be visualized graphically under the [Materials Viewer](../../../materials/ui/viewer.md) instance contained within the [Results tab](../../../jobs/ui/results-tab.md). -## Animation +## 5. Examine the results -We demonstrate the above-mentioned steps involved in the creation and execution of a [structural relaxation](../../../workflows/addons/structural-relaxation.md) study on a [Total Energy](../../../properties-directory/scalar/total-energy.md) workflow computation under the following animation, where we make use of the [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) simulation engine. The starting point is a crystal structure of silicon which has been slightly distorted from its equilibrium cubic-diamond lattice parameters and atomic positions. +Once the job completes, the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) displays the optimized total energy and additional information about each execution unit. -As expected, the components of both the atomic forces and [stress tensor](../../../properties-directory/non-scalar/stress-tensor.md) shown at the end of the structural relaxation computation, under the interface of [Results tab](../../../jobs/ui/results-tab.md), have low values in proximity to zero, signalling successful relaxation and geometry optimization. + +## 6. Inspect the optimized structure + +The output and input files are available under the [Files tab]({{ interface_url }}/jobs/ui/files-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). The POSCAR file can be [downloaded and inspected]({{ interface_url }}/data-in-objectstorage/actions/download/) to determine the relaxed geometry. + +The structural data can also be visualized graphically in the [Materials Viewer]({{ interface_url }}/materials/ui/viewer/) within the [Results tab]({{ interface_url }}/jobs/ui/results-tab/). + + +## 7. Video walkthrough + +The animation below demonstrates the creation and execution of a [structural relaxation]({{ reference_url }}/workflows/addons/structural-relaxation/) study on a [Total Energy]({{ reference_url }}/properties-directory/scalar/total-energy/) workflow using [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/). The starting point is a silicon crystal slightly distorted from its equilibrium lattice parameters and atomic positions. + +As expected, the force and [stress tensor]({{ reference_url }}/properties-directory/non-scalar/stress-tensor/) components shown at the end of the relaxation approach zero, indicating successful geometry optimization.
diff --git a/lang/en/docs/tutorials/dft/chemical/reaction-profile-qe.md b/lang/en/docs/tutorials/dft/chemical/reaction-profile-qe.md index 2995dab55..ab43eb880 100644 --- a/lang/en/docs/tutorials/dft/chemical/reaction-profile-qe.md +++ b/lang/en/docs/tutorials/dft/chemical/reaction-profile-qe.md @@ -1,108 +1,91 @@ -# Calculate Reaction Energy Profile Using Nudged Elastic Band (NEB) method +# Reaction Energy Profile with NEB (Quantum ESPRESSO) -This tutorial page explains how to calculate the [energy reaction profile](../../../properties-directory/non-scalar/reaction-energy-profile.md) and [activation barrier](../../../properties-directory/scalar/reaction-energy-barrier.md) for the multi-dimensional energy space of chemical reactions via the [**Nudged Elastic Bands (NEB) method**](../../../models/auxiliary-concepts/nudged-elastic-band.md), by making use of the [interpolated sets](../../../materials-designer/header-menu/advanced/interpolated-set.md) introduced in a [separate tutorial](../../materials/interpolated-sets.md). +This tutorial explains how to calculate the [energy reaction profile]({{ reference_url }}/properties-directory/non-scalar/reaction-energy-profile/) and [activation barrier]({{ reference_url }}/properties-directory/scalar/reaction-energy-barrier/) via the [Nudged Elastic Band (NEB) method]({{ reference_url }}/models/auxiliary-concepts/nudged-elastic-band/), using [interpolated sets]({{ interface_url }}/materials-designer/header-menu/advanced/interpolated-set/) of intermediate image structures (see the [interpolated sets tutorial](../../materials/interpolated-sets.md)). -We consider the example of a one-dimensional, three-atom molecule of Hydrogen (H3) throughout the present tutorial, and shall be making use of [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) as the main simulation engine, via the implementation of its `PWneb` [flavor](../../../software-directory/modeling/quantum-espresso/components.md#flavors). - -!!!note "Quantum ESPRESSO version considered in this tutorial" - The present tutorial is written for Quantum ESPRESSO at versions 5.2.1, 5.4.0, 6.0.0 or 6.3. - -This example considers a simple activated reaction, consisting in the **collinear proton transfer reaction**: +The example system is a one-dimensional, three-atom hydrogen (H3) molecule undergoing a **collinear proton transfer reaction**: ```text H2 + H <==> H + H2 ``` -In this triatomic reaction, the middle H atom breaks the bond with first atom and forms a molecule with third atom. We will thus calculate the energy activation barrier of this reaction. This same example is also offered as part of the Quantum ESPRESSO online documentation [^1]. +In this reaction, the middle H atom breaks the bond with the first atom and forms a molecule with the third atom. This example is also available in the Quantum ESPRESSO documentation [^1]. -## Workflow Structure +!!!note "Quantum ESPRESSO version" + This tutorial applies to Quantum ESPRESSO versions 5.2.1, 5.4.0, 6.0.0, 6.3, and later. -
- - Expand to view ... - -We outline here some important aspects of the [Workflow](../../../workflows/overview.md) used for executing NEB calculations on our platform via [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md), which is composed of a single main [unit](../../../workflows/components/units.md). +## 1. Understand the NEB workflow -### Main Executable +
+ Expand to view input parameter details -NEB calculations are performed through the ["neb.x" Quantum ESPRESSO Executable](../../../software-directory/modeling/quantum-espresso/components.md#executables). The input parameters for this executable are described in Ref. 4 of [this page](../../../software-directory/modeling/quantum-espresso/components.md), and can be customized by the user via the [unit input template editor](../../../workflow-designer/unit-editor.md#unit-input-templates) within the [Workflow Designer Interface](../../../workflow-designer/overview.md). +The [workflow]({{ reference_url }}/workflows/overview/) for NEB calculations with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) contains a single [unit]({{ reference_url }}/workflows/components/units/). -### Broyden Algorithm +**Executable:** NEB calculations use the ["neb.x" executable]({{ reference_url }}/software-directory/modeling/quantum-espresso/components/#executables). Input parameters are described in Ref. 4 of [this page]({{ reference_url }}/software-directory/modeling/quantum-espresso/components/) and can be customized via the [unit input template editor]({{ interface_url }}/workflow-designer/unit-editor/#unit-input-templates). -Within the neb.x input script, we note in particular the need for the [Broyden algorithm](../../../methods/auxiliary-concepts/optimization-algorithms.md) instead of the default one, for numerically solving iterative minimization and optimization problems such as the [structural relaxations](../../../workflows/addons/structural-relaxation.md) performed on the interpolated set images during the course of the NEB computation. This helps to remove the problem of ”oscillations” in the calculated activation energies. If these oscillations persist, and the user cannot afford more images, he/she should focus on smaller problems by decomposing the original one into pieces. +**Broyden algorithm:** The [Broyden algorithm]({{ reference_url }}/methods/auxiliary-concepts/optimization-algorithms/) is used instead of the default optimizer to remove oscillations in activation energies. -### Number of Images +**Number of images:** The `num_of_images` parameter defines the number of image points discretizing the reaction path (must be > 3 including initial/final). This can be set under the "neb" section of [Important Settings]({{ interface_url }}/workflow-designer/subworkflow-editor/important-settings/) for automatic generation by Quantum ESPRESSO. -The number of image points used to discretize the reaction path, as defined by the [interpolated set](../../../materials-designer/header-menu/advanced/interpolated-set.md) of images to be considered for the NEB calculation, is defined by the `num_of_images` input parameter, and must be larger than 3 (including the initial and final images). +**Convergence threshold:** The simulation stops when the force orthogonal to the path is below `path_thr` (in eV/Å). -The number of intermediate NEB images should be set under the "neb" section of the ["Important Settings" Tab](../../../workflow-designer/subworkflow-editor/important-settings.md) within the [Workflow Designer Interface](../../../workflow-designer/overview.md), for their automatic generation by Quantum ESPRESSO (without consequently the need to import an interpolated set manually, as described later in this page). +**Image structures:** Atomic positions for all images are specified within `BEGIN_POSITIONS / END_POSITIONS` delimiters, with each `ATOMIC_POSITIONS` card prefixed by `FIRST_IMAGE`, `INTERMEDIATE_IMAGE`, or `LAST_IMAGE`. -### Convergence Threshold +
-The NEB simulation stops when the error (the norm of the force orthogonal to the path in eV/A) is less than the `path_thr` input parameter. -### Structure of Images +## 2. Create the job -Atomic positions for all the images are specified within the `BEGIN_POSITIONS / END_POSITIONS` delimiters, where each instance of `ATOMIC_POSITIONS` card is prefixed either by `FIRST_IMAGE`, `INTERMEDIATE_IMAGE`, or `LAST_IMAGE` keywords, depending on its position within the overall order of the interpolated set under consideration. +Open the [Job Designer]({{ interface_url }}/jobs-designer/overview/) to create a new [job]({{ reference_url }}/jobs/overview/). -
-## Create Job +## 3. Import the interpolated set -We start with [opening](../../../jobs/actions/create.md) an instance of the [Job Designer Interface](../../../jobs-designer/overview.md) for creating and designing new computational [Jobs](../../../jobs/overview.md) on our platform. - -## Import Interpolated Set +The **Interpolated Set** generated in the [interpolated sets tutorial](../../materials/interpolated-sets.md) under the name "NEB CONSTRAINED SET" should be [selected and imported]({{ interface_url }}/jobs-designer/actions-header-menu/select-materials/) into the [Materials tab]({{ interface_url }}/jobs-designer/materials-tab/) by [selecting]({{ interface_url }}/entities-general/actions/select/) all images in the set. -The **Interpolated Set** generated in [this other tutorial](../../materials/interpolated-sets.md) under the name "NEB CONSTRAINED SET", containing the initial, final and a total of 3 intermediate images of the H3 molecule under investigation (including atomic constraints along the single dimension of the molecule), should then be [selected and imported](../../../jobs-designer/actions-header-menu/select-materials.md) into the ["Materials Viewer" Tab](../../../jobs-designer/materials-tab.md) of the NEB job being [designed](../../../jobs-designer/overview.md). This is done by [selecting](../../../entities-general/actions/select.md) all images contained in the set at the moment of import. -## Choose Workflow +## 4. Select the workflow -[Workflows](../../../workflows/overview.md) for calculating the reaction energy profile of chemical molecules via NEB with [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) can readily be [imported](../../../workflows/actions/copy-bank.md) from the [Workflows Bank](../../../workflows/bank.md) into the account-owned [collection](../../../accounts/collections.md). This workflow can later be [selected](../../../jobs-designer/actions-header-menu/select-workflow.md) and added to the [Job being created](../../../jobs-designer/workflow-tab.md). +[Workflows]({{ reference_url }}/workflows/overview/) for NEB calculations with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/). The workflow can then be [selected]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) and added to the job. -!!!warning "Size of grid of k-points" - The user should take care to set the size of the [grid of reciprocal k-points (kgrid)](../../../models/auxiliary-concepts/reciprocal-space/sampling.md) to 1 x 1 x 1 under the ["Important Settings" Tab](../../../workflow-designer/subworkflow-editor/important-settings.md) of the [Workflow Designer Interface](../../../workflow-designer/overview.md), since we are presently dealing with single molecules as opposed to periodic crystalline structures. +!!!warning "K-point grid for molecules" + The [k-point grid]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) should be set to 1 × 1 × 1 under [Important Settings]({{ interface_url }}/workflow-designer/subworkflow-editor/important-settings/), since the system is a molecule rather than a periodic crystal. -## Submit Job -Before [submitting](../../../jobs/actions/run.md) the [job](../../../jobs/overview.md), the user should click on the ["Compute" tab](../../../jobs-designer/compute-tab.md) of [Job Designer](../../../jobs-designer/overview.md) and examine the [compute parameters](../../../infrastructure/compute/parameters.md) included therein. The H3 molecules being considered in the present tutorial are relatively small structures, hence 4 CPUs and a few minutes of calculation runtime should be sufficient. +## 5. Submit the job -## Examine Final Results +Before [submitting]({{ interface_url }}/jobs/actions/run/), review the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) to verify the [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/). H3 is a small system — 4 CPUs and a few minutes of runtime are sufficient. -When the NEB computation is complete at the end of Job execution, switching to the [Results tab](../../../jobs/ui/results-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md) will show the **Reaction Energy Profile** for the H3 molecules under investigation, plotted in the form of an energy curve as a function of the one-dimensional reaction coordinate that is varied from the initial to final configuration. -An example of such a reaction energy profile is shown in the image below, in which the intermediate activation energy barrier between reactants and products is clearly visible. +## 6. Examine the results -![Reaction Energy Profile](../../../images/tutorials/reaction-profile.png "Reaction Energy Profile") +The [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) displays the **Reaction Energy Profile** as an energy curve versus the reaction coordinate. -## Retrieve Final Optimized Images +![Reaction Energy Profile](../../../images/tutorials/reaction-profile.png "Reaction Energy Profile") -The final optimized image structures can be retrieved at the end of Job execution according to the instructions contained [in this page](../../../workflows/addons/structural-relaxation.md#initial/final-structures-set). +The final optimized image structures can be retrieved according to the instructions in [this page]({{ reference_url }}/workflows/addons/structural-relaxation/#initial/final-structures-set). -## Animation -### NEB with Manually-Generated Images +## 7. Video walkthrough -We demonstrate the above-mentioned steps involved in the creation and execution of an NEB-based reaction energy profile computation on H3 molecules using the [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) simulation engine in the following animation. +### 7.1. NEB with manually generated images -Here, we have made use of the constrained interpolated set containing 3 intermediate images generated manually in a [separate tutorial](../../materials/interpolated-sets.md). It can be deduced from the final result for the energy reaction profile that the size of the activation barrier in this case is of 0.2 eV. This result is in good agreement with those published in the literature for the same collinear proton transfer chemical reaction (see for example page 26 in Ref. [^2]). +The animation below uses the constrained interpolated set containing 3 intermediate images generated in the [interpolated sets tutorial](../../materials/interpolated-sets.md). The activation barrier of ~0.2 eV is in good agreement with published results (see page 26 in Ref. [^2]).
-### NEB with Automatically Generated Images - -We can repeat the same reaction profile calculation for H3 molecules as above, but this time taking advantage of the Quantum ESPRESSO feature for the automatic generation of intermediate images mentioned previously. This effectively makes it redundant to import manually an interpolated set, such as was done in the previous video. +### 7.2. NEB with automatically generated images -This feature can be enabled by selecting an appropriate number of intermediate images to be generated under the ["Important Settings" Tab](../../../workflow-designer/subworkflow-editor/important-settings.md) of the [Workflow Designer Interface](../../../workflow-designer/overview.md), as demonstrated in the following animation, where we select to generate a total of 5 intermediate images. In this case, only the initial and final images need to be imported manually into Job Designer. +The same calculation can be performed with automatic intermediate image generation by Quantum ESPRESSO, eliminating the need to import an interpolated set manually. Set the number of intermediate images under [Important Settings]({{ interface_url }}/workflow-designer/subworkflow-editor/important-settings/) — only the initial and final images need to be imported.
-## Links -[^1]: [Quantum ESPRESSO NEB Example, Official GitHub Repository](https://github.com/maxhutch/quantum-espresso/tree/master/NEB/examples/example01) +## 8. Links +[^1]: [Quantum ESPRESSO NEB Example, Official GitHub Repository](https://github.com/maxhutch/quantum-espresso/tree/master/NEB/examples/example01) [^2]: [Guido Fratesi: "Low Temperature methane-to-methanol conversion on transition metal surfaces", Ph.D Thesis](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.378.7331&rep=rep1&type=pdf) diff --git a/lang/en/docs/tutorials/dft/chemical/reaction-profile-vasp.md b/lang/en/docs/tutorials/dft/chemical/reaction-profile-vasp.md index 61a8ba3ed..ad0a449bc 100644 --- a/lang/en/docs/tutorials/dft/chemical/reaction-profile-vasp.md +++ b/lang/en/docs/tutorials/dft/chemical/reaction-profile-vasp.md @@ -1,54 +1,46 @@ -# Calculate Reaction Energy Profile Using Nudged Elastic Band (NEB) method +# Reaction Energy Profile with NEB (VASP) -This tutorial page explains how to calculate the energy reaction profile and activation barrier for the multi-dimensional energy space of chemical reactions via the **Nudged Elastic Bands (NEB) method**, by making use of the [interpolated sets](../../../materials-designer/header-menu/advanced/interpolated-set.md) of intermediate image structures introduced in a [separate tutorial](../../materials/interpolated-sets.md). +This tutorial explains how to calculate the energy reaction profile and activation barrier via the **Nudged Elastic Band (NEB) method** using [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) and [interpolated sets]({{ interface_url }}/materials-designer/header-menu/advanced/interpolated-set/) of intermediate image structures (see the [interpolated sets tutorial](../../materials/interpolated-sets.md)). -We consider the example of a one-dimensional, three-atom molecule of Hydrogen (H3) throughout the present tutorial, and shall be making use of [VASP](../../../software-directory/modeling/vasp/overview.md) as the main simulation engine. +The example system is the same collinear proton transfer reaction of H3 studied in the [Quantum ESPRESSO NEB tutorial](reaction-profile-qe.md). Only VASP-specific aspects are covered here. -Only the aspects of NEB calculations which are specific to VASP will be reviewed here. For a more general introduction to how such calculations are performed and defined on our platform, the reader is referred to [this alternative tutorial page](reaction-profile-qe.md). The same collinear proton transfer chemical reaction of the H3 molecule as in this latter tutorial will be investigated here. +!!!note "VASP version" + This tutorial applies to VASP versions 5.3.5, 5.4.4, and later. -!!!note "VASP version considered in this tutorial" - The present tutorial is written for VASP at versions 5.3.5 or 5.4.4. -## Workflow Structure +## 1. Understand the VASP NEB workflow -General instructions on how NEB is implemented under VASP can be found in Ref. [^1]. An example demonstration of VASP NEB capabilities, for calculating the energy barrier in the case of the self-diffusion of a Pt-adatom on Pt (001), is offered in Ref. [^2]. +General VASP NEB instructions are available in Ref. [^1], and an example for Pt-adatom self-diffusion on Pt (001) is provided in Ref. [^2]. -Most importantly, VASP expects there to be a group of pre-existing [set folders](../../../entities-general/sets.md), within the account-owned [collection](../../../accounts/collections.md) of materials, named "00" (initial) to "0N" (final), each containing the POSCAR structure file for each of the N images constituting the interpolated set under consideration. All output files (OUTCAR, CONTCAR, OSZICAR etc...) of the NEB-steps run are written to these same directories. These sets are generated automatically on our platform, as explained in what follows. - -We describe now the overall structure of the [Workflow](../../../workflows/overview.md) used for executing NEB calculations on our platform via [VASP](../../../software-directory/modeling/vasp/overview.md), which is composed of three main [subworkflow](../../../workflows/components/subworkflows.md) operations. +VASP requires pre-existing [set folders]({{ reference_url }}/entities-general/sets/) named "00" (initial) through "0N" (final), each containing a POSCAR file for the corresponding image. These are generated automatically by the workflow. -!!!warning "Restrictions on number of computing cores" - The number of cores on which VASP is run for NEB purposes has to be an integer multiple of the total number of *intermediate* images. Hence, if the user is working with 2 intermediate images, the number of cores selected should be 2, 4, 6, or all other even numbers. +The workflow contains three main [subworkflows]({{ reference_url }}/workflows/components/subworkflows/): -### 1. Calculate Initial/Final Total Energies +!!!warning "Restrictions on computing cores" + The number of cores must be an integer multiple of the number of *intermediate* images. For example, 2 intermediate images require 2, 4, 6, or another even number of cores. -One important point about the VASP NEB workflow is that VASP does not run the calculation for initial and final image structures within the interpolated set. +### 1.1. Calculate initial/final total energies -Consequently, the first subworkflow step consists in executing a pair of self-consistent field (SCF) ground-state energy computations, in order to extract the [total energy](../../../properties-directory/scalar/total-energy.md) for both the initial and final images. +VASP does not compute energies for the initial and final images during NEB. A pair of SCF calculations extracts the [total energy]({{ reference_url }}/properties-directory/scalar/total-energy/) for both endpoints. -This first subworkflow has a separate compute configuration, independent from the rest of the workflow, that can be adjusted by the user under its ["Compute" Tab](../../../workflow-designer/subworkflow-editor/compute.md). The reason is that if there are 10 images, at least 10 cores are needed, as mentioned before, but such a large number of cores is not necessarily required for the initial/final total energy SCF calculations performed in the present step. +This subworkflow has an independent compute configuration under its [Compute Tab]({{ interface_url }}/workflow-designer/subworkflow-editor/compute/), since the larger core count needed for NEB is not required for these SCF calculations. -We also remind the reader that the size of the [grid of reciprocal k-points (kgrid)](../../../models/auxiliary-concepts/reciprocal-space/sampling.md) should be set to 1 x 1 x 1 for the case of chemical molecules, such as those considered in the present tutorial. This option can be set under the ["Important Settings" Tab](../../../workflow-designer/subworkflow-editor/important-settings.md) of the [Workflow Designer Interface](../../../workflow-designer/overview.md). +The [k-point grid]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) should be set to 1 × 1 × 1 under [Important Settings]({{ interface_url }}/workflow-designer/subworkflow-editor/important-settings/) for molecular systems. -### 2. Prepare Directories +### 1.2. Prepare directories -The second subworkflow runs a [shell script](../../../software-directory/scripting/shell/overview.md) which prepares the aforementioned directories necessary to run a VASP NEB calculation. This script first puts the initial POSCAR structure file into a set directory named "00", the final one into "0N", and the remaining intermediate images in "01" to "0(N-1)". +A [shell script]({{ reference_url }}/software-directory/scripting/shell/overview/) creates the required directory structure: initial POSCAR → "00", final POSCAR → "0N", intermediate images → "01" through "0(N-1)". The SCF outputs from the previous step are copied into directories "00" and "0N". -The outputs of the previous subworkflow on the SCF calculations applied to the initial and final images are here copied into the initial (00) and final (0N) directories respectively. +### 1.3. NEB calculation -### 3. Nudged Elastic Band (NEB) Calculation +The NEB computation is executed through VASP. Key INCAR parameters: -The third and final subworkflow executes the NEB computation itself through VASP. We note the following important input parameters within the VASP "INCAR" input script: +- `IMAGES` — number of intermediate image geometries [^3] +- `SPRING` — spring constant (eV/Ų); negative values enable nudging +- `MAGMOM` — ensures protons have opposite spins (required for correct barrier) +- `EDIFFG` — break condition for ionic relaxation; negative values specify a force threshold -- "IMAGES" defines the number of interpolated image geometries between the initial and final states within the interpolated set under investigation. This tag is documented in detail in Ref. [^3]. - -- "SPRING" defines the spring constant, in eV/Ang^2, between the images. A negative value turns on nudging. - -- "MAGMOM" ensures that the protons have opposite spins. This parameter has to be explicitly set in order to obtain the correct activation barrier, since the VASP NEB routine does not by itself relax the spins. - -- "EDIFFG" is important to get the properly relaxed intermediate states, since the default parameters might not be enough. More specifically, this parameter defines the break condition for the ionic relaxation loop. If EDIFFG is negative, such as in our case, the relaxation will stop if all forces are smaller than the absolute value set for this parameter. - -An example of INCAR input script for an NEB calculation with VASP is shown below: +An example INCAR is shown below: ```text ISTART = 0 @@ -63,39 +55,41 @@ MAGMOM = 1 -1 1 IMAGES = 1 ``` -Additional information on further possible input parameters available for VASP NEB calculations can be retrieved in Ref. [^4]. +Additional NEB input parameters are documented in Ref. [^4]. + +!!!note "Automatic image generation" + The "number of intermediate images" option under Important Settings is not currently used for VASP. Automatic image generation support will be added in a future platform release. + + +## 2. Import the interpolated set -!!!note "Redundant "number of intermediate images" option" - The number of intermediate images under "Important Settings" is not used at present for VASP. It will be enabled when support will be added for generating images automatically on our platform. - -## Import Interpolated Set +The constrained **Interpolated Set** from the [interpolated sets tutorial](../../materials/interpolated-sets.md) should be [selected and imported]({{ interface_url }}/jobs-designer/actions-header-menu/select-materials/) into the [Materials tab]({{ interface_url }}/jobs-designer/materials-tab/) by [selecting]({{ interface_url }}/entities-general/actions/select/) all images in the set. -The constrained **Interpolated Set** generated in [this other tutorial](../../materials/interpolated-sets.md) under the name "NEB CONSTRAINED SET", containing the initial, final and a total of 3 intermediate images of the H3 molecule under investigation, should then be [selected and imported](../../../jobs-designer/actions-header-menu/select-materials.md) into the ["Materials Viewer" Tab](../../../jobs-designer/materials-tab.md) of the NEB VASP job being [designed](../../../jobs-designer/overview.md). This is done by [selecting](../../../entities-general/actions/select.md) all images contained in the set at the moment of import. -## Create and Submit Job +## 3. Create and submit the job -The same set of instructions as in the [alternative NEB tutorial](reaction-profile-qe.md#create-job-and-choose-workflow) should now be followed for [importing](../../../workflows/actions/copy-bank.md) the relevant VASP NEB [workflow](../../../workflows/overview.md) from the [bank](../../../workflows/bank.md) into the account-owned [collection](../../../accounts/collections.md), and for later [selecting and adding it](../../../jobs-designer/actions-header-menu/select-workflow.md) into the new [Job](../../../jobs/overview.md) being [designed](../../../jobs-designer/overview.md). +Follow the same instructions as in the [Quantum ESPRESSO NEB tutorial](reaction-profile-qe.md#4-select-the-workflow) for [importing]({{ interface_url }}/workflows/actions/copy-bank/) the VASP NEB [workflow]({{ reference_url }}/workflows/overview/) from the [bank]({{ reference_url }}/workflows/bank/) and adding it to the new [job]({{ reference_url }}/jobs/overview/). -## Retrieve Final Optimized Images -The final optimized image structures can be retrieved at the end of Job execution according to the instructions contained [in this page](../../../workflows/addons/structural-relaxation.md#initial/final-structures-set). +## 4. Examine the results -## Animation +The final optimized image structures can be retrieved following the instructions in [this page]({{ reference_url }}/workflows/addons/structural-relaxation/#initial/final-structures-set). -We demonstrate the above-mentioned steps involved in the creation and execution of an NEB-based reaction energy profile computation on H3 molecules, using the [VASP](../../../software-directory/modeling/vasp/overview.md) simulation engine, in the following animation. Because we are working with 3 intermediate images, we run the NEB [Job](../../../jobs/overview.md) on a total of 6 cores, which is a multiple of 3 as required. +The [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) displays the energy reaction profile with an activation barrier of ~0.2 eV, in agreement with the [Quantum ESPRESSO NEB tutorial](reaction-profile-qe.md). -It can be deduced from the final results for the energy reaction profile, available under the [Results tab](../../../jobs/ui/results-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md), that the size of the activation energy barrier in this case is of about 0.2 eV, in agreement with the outcome of the [other NEB Tutorial](reaction-profile-qe.md). + +## 5. Video walkthrough + +The animation below demonstrates the NEB calculation on H3 using VASP with 3 intermediate images on 6 cores (a multiple of 3, as required).
-## Links -[^1]: [TS search using the NEB Method, Official VASP Documentation](https://cms.mpi.univie.ac.at/wiki/index.php/TS_search_using_the_NEB_Method) +## 6. Links +[^1]: [TS search using the NEB Method, Official VASP Documentation](https://cms.mpi.univie.ac.at/wiki/index.php/TS_search_using_the_NEB_Method) [^2]: [Collective jumps of a Pt adatom on fcc-Pt (001): Nudged Elastic Band Calculation, Official VASP Documentation](https://cms.mpi.univie.ac.at/wiki/index.php/Collective_jumps_of_a_Pt_adatom_on_fcc-Pt_(001):_Nudged_Elastic_Band_Calculation) - [^3]: [Instructions on how to generate Images, Official VASP Documentation](https://cms.mpi.univie.ac.at/wiki/index.php/IMAGES) - -[^4]: [Transition State Theory: Nudged Elastic Band with VASP, University of Texas Website](http://theory.cm.utexas.edu/vtsttools/neb.html) +[^4]: [Transition State Theory: Nudged Elastic Band with VASP, University of Texas](http://theory.cm.utexas.edu/vtsttools/neb.html) diff --git a/lang/en/docs/tutorials/dft/electronic/band-gap.md b/lang/en/docs/tutorials/dft/electronic/band-gap.md index cd10e22a2..ce24a58d1 100644 --- a/lang/en/docs/tutorials/dft/electronic/band-gap.md +++ b/lang/en/docs/tutorials/dft/electronic/band-gap.md @@ -1,55 +1,58 @@ # Calculate Electronic Band Gap -This tutorial page explains how to calculate an [electronic band gap](../../../properties-directory/non-scalar/band-gaps.md) based on [Density Functional Theory](../../../models-directory/dft/overview.md). We consider crystalline silicon in its standard equilibrium cubic-diamond crystal structure, and use [VASP](../../../software-directory/modeling/vasp/overview.md) as our main simulation engine during this tutorial. +This tutorial explains how to calculate the [electronic band gap]({{ reference_url }}/properties-directory/non-scalar/band-gaps/) of crystalline silicon in its standard equilibrium cubic-diamond crystal structure, based on [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT). [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) is used as the main simulation engine. -!!!note simulation engines considered in this tutorial" - The present tutorial is originally designed for [VASP](../../../software-directory/modeling/vasp/overview.md) (ver. 5.3.5 or 5.4.4), however, the steps demonstrated below are identical for other similar software, such as [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) (ver. 5.4 to 6.3), for example. +!!!note "Simulation engines considered in this tutorial" + This tutorial is designed for [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) (ver. 5.3.5 or 5.4.4), however the steps are identical for other engines such as [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) (ver. 5.4 to 6.3 and later). -## Definitions +## 1. Understand the band gap -### Band Gap +The [electronic band gap]({{ reference_url }}/properties-directory/non-scalar/band-gaps/) is the **energy difference** between the **highest occupied electronic state** and the **lowest unoccupied state** within the [electronic band structure]({{ reference_url }}/properties-directory/non-scalar/bandstructure/) of a material. -The [electronic band gap](../../../properties-directory/non-scalar/band-gaps.md) defines the **energy difference** between the **highest occupied electronic state** and the **lowest unoccupied state** within the [electronic band-structure](../../../properties-directory/non-scalar/bandstructure.md) of the material under investigation. +!!!info "Direct vs indirect gaps" + The platform extracts both **direct** and **indirect** band gaps. The difference between the two types is explained in the [band gaps reference]({{ reference_url }}/properties-directory/non-scalar/band-gaps/#direct-and-indirect-band-gaps). -!!!info "Direct vs Indirect Gaps" - We support the extraction of both the **direct** and **indirect** band gaps. The difference between the two types is explained [in this page](../../../properties-directory/non-scalar/band-gaps.md#direct-and-indirect-band-gaps). -## Create job +## 2. Create a job -Silicon in its cubic-diamond crystal structure is the [default material](../../../materials/default.md) that is shown on [new job creation](../../../jobs-designer/overview.md), unless this default was [changed](../../../entities-general/actions/set-default.md) by the user following [account](../../../accounts/overview.md) creation. If silicon is still the default choice, it will as such be automatically loaded at the moment of the [opening](../../../jobs/actions/create.md) of [Job Designer](../../../jobs-designer/overview.md). +Silicon in its cubic-diamond crystal structure is the [default material]({{ reference_url }}/materials/default/) loaded on [new job creation]({{ interface_url }}/jobs-designer/overview/), unless the default was [changed]({{ interface_url }}/entities-general/actions/set-default/) after [account]({{ reference_url }}/accounts/overview/) creation. If silicon is still the default, it is automatically loaded when the [Job Designer]({{ interface_url }}/jobs-designer/overview/) is [opened]({{ interface_url }}/jobs/actions/create/). -## Choose Workflow -[Workflows](../../../workflows/overview.md) for calculating the band gap can be [imported](../../../workflows/actions/copy-bank.md) from the [Workflows Bank](../../../workflows/bank.md) into the account-owned [collection](../../../accounts/collections.md). This workflow can later be [selected](../../../jobs-designer/actions-header-menu/select-workflow.md) and added to the [Job being created](../../../jobs-designer/workflow-tab.md). +## 3. Select the workflow -## Set Sampling in Reciprocal Space +[Workflows]({{ reference_url }}/workflows/overview/) for calculating the band gap can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/). The workflow can then be [selected]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) and added to the [job being created]({{ interface_url }}/jobs-designer/workflow-tab/). -It is critical to have a high [k-point density](../../../models/auxiliary-concepts/reciprocal-space/sampling.md) in order to calculate the band gap with sufficient accuracy. -For the case of [VASP](../../../software-directory/modeling/vasp/overview.md), the band gap workflow is composed of two [units](../../../workflows/components/units.md). The first unit specifies the settings for the self-consistent calculation of the energy eigenvalues and wave functions. The second unit calculation is a non self-consistent calculation using the wave functions and charge density of the previous calculation. +## 4. Set sampling in reciprocal space -We set the size of the grid of k-points to 18 x 18 x 18 in the first workflow unit. The validity of this choice of k-grid size for yielding accurate results of order meV in the final energy can be verified by performing the relevant [convergence study](../../../models/auxiliary-concepts/reciprocal-space/convergence.md). +A high [k-point density]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) is critical for calculating the band gap with sufficient accuracy. -## Submit Job +For [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/), the band gap workflow is composed of two [units]({{ reference_url }}/workflows/components/units/). The first unit performs a self-consistent field (SCF) calculation of the energy eigenvalues and wave functions. The second unit performs a non-self-consistent calculation using the wave functions and charge density from the first step. -Before [submitting](../../../jobs/actions/run.md) the [job](../../../jobs/overview.md), the user should click on the ["Compute" tab](../../../jobs-designer/compute-tab.md) of [Job Designer](../../../jobs-designer/overview.md) and inspect the [compute parameters](../../../infrastructure/compute/parameters.md) included therein. Silicon is a small structure, so four CPUs and one minute of calculation runtime should be sufficient. +The k-point grid is set to 18 × 18 × 18 in the first workflow unit. The validity of this grid size for yielding meV-level accuracy can be verified by performing a [convergence study]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/convergence/). -## Examine results -When both [unit](../../../workflows/components/units.md) computations are complete at the end of Job execution, switching to the [Results tab](../../../jobs/ui/results-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md) will show the results of the simulation, including the indirect band gap found for Si (~0.6 eV). +## 5. Submit the job -!!!note "Silicon as Indirect Gap Semiconductor" - The user will notice that we identify both the direct band gap and the indirect band gap. This calculation is done during the first, self-consistent step of the calculation on the dense k-point mesh. It can be deduced that the indirect band gap is significantly smaller than the smallest direct band gap, which is the reason why silicon is classed as an **indirect gap semiconductor**. +Before [submitting]({{ interface_url }}/jobs/actions/run/) the [job]({{ reference_url }}/jobs/overview/), the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) of [Job Designer]({{ interface_url }}/jobs-designer/overview/) should be reviewed to verify the [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/). Silicon is a small structure, so four CPUs and one minute of calculation runtime are sufficient. -### Comparison with Experimental Value -The calculated value of ~0.6 eV for the indirect band gap is significantly below the tabulated experimental value for the band gap of Silicon of ~1.1 eV, however as discussed [elsewhere](../../../models-directory/dft/notes.md#accuracy-limits-of-the-generalized-gradient-approximation) this underestimation is expected given our adoption of the [Generalized Gradient Approximation](../../../models-directory/dft/parameters.md#subtype). The use of more accurate techniques, such as Hybrid Screened Exchange (HSE), for example, allows to significantly improve the comparison. See the [corresponding tutorial](hse-vasp-bg.md) for more details. +## 6. Examine the results -## Animation +Once both [unit]({{ reference_url }}/workflows/components/units/) computations complete, the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) displays the simulation results, including the indirect band gap of Si (~0.6 eV). -We demonstrate the above-mentioned steps involved in the creation and execution of a Band Gap computation workflow on silicon using the simulation engine in the following animation. +!!!note "Silicon as indirect gap semiconductor" + Both the direct and indirect band gaps are identified. The calculation is performed during the first, self-consistent step on the dense k-point mesh. The indirect band gap is significantly smaller than the smallest direct band gap, which is why silicon is classified as an **indirect gap semiconductor**. + +### 6.1. Compare with experiment + +The calculated value of ~0.6 eV for the indirect band gap is below the tabulated experimental value of ~1.1 eV. As discussed in the [DFT accuracy notes]({{ reference_url }}/models-directory/dft/notes/#accuracy-limits-of-the-generalized-gradient-approximation), this underestimation is expected when using the [Generalized Gradient Approximation]({{ reference_url }}/models-directory/dft/parameters/#subtype). More accurate techniques, such as Hybrid Screened Exchange (HSE), significantly improve the comparison. See the [HSE band gap tutorial](hse-vasp-bg.md) for details. + + +## 7. Video walkthrough + +The animation below demonstrates the steps involved in the creation and execution of a band gap computation on silicon.
- diff --git a/lang/en/docs/tutorials/dft/electronic/band-structure.md b/lang/en/docs/tutorials/dft/electronic/band-structure.md index 1936c01c6..361435b49 100644 --- a/lang/en/docs/tutorials/dft/electronic/band-structure.md +++ b/lang/en/docs/tutorials/dft/electronic/band-structure.md @@ -1,42 +1,48 @@ # Electronic Band Structure Calculation -This tutorial page explains how to calculate the [electronic band structure](../../../properties-directory/non-scalar/bandstructure.md) based on [Density Functional Theory](../../../models-directory/dft/overview.md). We will be studying crystalline Silicon in the standard cubic-diamond crystal structure, and we will use [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) as our simulation engine. +This tutorial explains how to calculate the [electronic band structure]({{ reference_url }}/properties-directory/non-scalar/bandstructure/) of crystalline silicon in the standard cubic-diamond crystal structure, based on [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT). [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) is used as the simulation engine. -!!!note "Quantum ESPRESSO version considered in this tutorial" - The present tutorial is written for Quantum ESPRESSO at versions 5.2.1, 5.4.0, 6.0.0 or 6.3. +!!!note "Quantum ESPRESSO version" + This tutorial applies to Quantum ESPRESSO versions 5.2.1, 5.4.0, 6.0.0, 6.3, and later. -!!! Note "Accuracy of the results" - Please note that this calculation is performed using standard [Density Functional Theory](../../../models-directory/dft/overview.md), and therefore an underestimation of the energy of unoccupied electronic states is expected. Further modifications to the input files and settings to correctly predict the band gap are possible, and will be explored later. +!!!warning "Accuracy of the results" + This calculation uses standard DFT, which is known to underestimate the energy of unoccupied electronic states. More accurate methods such as [HSE](hse-qe-bs.md) and [GW](gw-qe-bs-fullfreq.md) are covered in separate tutorials. -## Create Job -Silicon in its cubic-diamond crystal structure is the [default material](../../../materials/default.md) that is shown on [new job creation](../../../jobs-designer/overview.md), unless this default was [changed](../../../entities-general/actions/set-default.md) by the user following [account](../../../accounts/overview.md) creation. If silicon is still the default choice, it will as such be automatically loaded at the moment of the [opening](../../../jobs/actions/create.md) of [Job Designer](../../../jobs-designer/overview.md). +## 1. Create a job -## Choose Workflow +Silicon in its cubic-diamond crystal structure is the [default material]({{ reference_url }}/materials/default/) loaded on [new job creation]({{ interface_url }}/jobs-designer/overview/), unless the default was [changed]({{ interface_url }}/entities-general/actions/set-default/) after [account]({{ reference_url }}/accounts/overview/) creation. If silicon is still the default, it is automatically loaded when the [Job Designer]({{ interface_url }}/jobs-designer/overview/) is [opened]({{ interface_url }}/jobs/actions/create/). -[Workflows](../../../workflows/overview.md) for calculating the [band structure](../../../properties-directory/non-scalar/bandstructure.md) of [materials](../../../materials/overview.md) with [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) can readily be [imported](../../../workflows/actions/copy-bank.md) from the [Workflows Bank](../../../workflows/bank.md) into the account-owned [collection](../../../accounts/collections.md). This workflow can later be [selected](../../../jobs-designer/actions-header-menu/select-workflow.md) and added to the [Job being created](../../../jobs-designer/workflow-tab.md). -## Set Sampling in Reciprocal Space +## 2. Select the workflow -It is critical to have a high [k-point density](../../../models/auxiliary-concepts/reciprocal-space/sampling.md) in order to resolve enough details for the band structure plot. +[Workflows]({{ reference_url }}/workflows/overview/) for calculating the [band structure]({{ reference_url }}/properties-directory/non-scalar/bandstructure/) with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/). The workflow can then be [selected]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) and added to the [job being created]({{ interface_url }}/jobs-designer/workflow-tab/). -The band structure workflow is composed of two [units](../../../workflows/components/units.md). The first unit specifies the settings for the self-consistent calculation of the energy eigenvalues and wave functions. The second unit calculation is a non self-consistent calculation using the wave functions and charge density of the previous calculation. -We set the size of the grid of k-points to 18 x 18 x 18 in the first workflow unit. This provides a dense enough k-point sampling in order to resolve the fine features present within the output of the band structure computation. The validity of this choice of k-grid size for yielding accurate results of order meV in the final energy can be verified by performing the relevant [convergence study](../../../models/auxiliary-concepts/reciprocal-space/convergence.md). +## 3. Set sampling in reciprocal space -In addition, we also apply the recommended [k-point path](../../../models/auxiliary-concepts/reciprocal-space/paths.md) to effectively sample the electronic states throughout the Brillouin Zone of the crystal, based on the crystal symmetry. +A high [k-point density]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) is critical for resolving the fine features of the band structure plot. -## Submit Job +The band structure workflow is composed of two [units]({{ reference_url }}/workflows/components/units/). The first unit performs a self-consistent field (SCF) calculation of the energy eigenvalues and wave functions. The second unit performs a non-self-consistent calculation using the wave functions and charge density from the first step. -Before [submitting](../../../jobs/actions/run.md) the [job](../../../jobs/overview.md), the user should click on the ["Compute" tab](../../../jobs-designer/compute-tab.md) of [Job Designer](../../../jobs-designer/overview.md) and examine the [compute parameters](../../../infrastructure/compute/parameters.md) included therein. Silicon is a small structure, so 4 CPUs and 1 minute of calculation runtime should be sufficient. +The k-point grid is set to 18 × 18 × 18 in the first workflow unit. This provides dense enough sampling to resolve the features in the band structure output. The validity of this grid size for yielding meV-level accuracy can be verified by performing a [convergence study]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/convergence/). -## Examine Final Results +In addition, the recommended [k-point path]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/paths/) is applied to sample the electronic states throughout the Brillouin Zone, based on the crystal symmetry. -When both [unit](../../../workflows/components/units.md) computations are complete at the end of Job execution, switching to the [Results tab](../../../jobs/ui/results-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md) will show the [band structure](../../../properties-directory/non-scalar/bandstructure.md) of silicon, plotted as a dispersion curve as a function of the special [k-point paths](../../../models/auxiliary-concepts/reciprocal-space/paths.md) chosen. -## Animation +## 4. Submit the job -We demonstrate the above-mentioned steps involved in the creation and execution of a band structure computation on silicon using the [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) simulation engine in the following animation. +Before [submitting]({{ interface_url }}/jobs/actions/run/) the [job]({{ reference_url }}/jobs/overview/), the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) of [Job Designer]({{ interface_url }}/jobs-designer/overview/) should be reviewed to verify the [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/). Silicon is a small structure, so 4 CPUs and 1 minute of calculation runtime are sufficient. + + +## 5. Examine the results + +Once both [unit]({{ reference_url }}/workflows/components/units/) computations complete, the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) displays the [band structure]({{ reference_url }}/properties-directory/non-scalar/bandstructure/) of silicon, plotted as a dispersion curve along the selected [k-point path]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/paths/). + + +## 6. Video walkthrough + +The animation below demonstrates the steps involved in the creation and execution of a band structure computation on silicon using Quantum ESPRESSO.
diff --git a/lang/en/docs/tutorials/dft/electronic/density-of-states.md b/lang/en/docs/tutorials/dft/electronic/density-of-states.md index 58b4984f9..ae7e1bd2f 100644 --- a/lang/en/docs/tutorials/dft/electronic/density-of-states.md +++ b/lang/en/docs/tutorials/dft/electronic/density-of-states.md @@ -1,45 +1,51 @@ # Calculate Electronic Density of States -This tutorial page explains how to calculate the [electronic density of states](../../../properties-directory/non-scalar/electronic-dos.md) using [Density Functional Theory](../../../models-directory/dft/overview.md). We study crystalline silicon in its standard equilibrium cubic-diamond crystal structure, and use [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) as our main simulation engine during the present tutorial. +This tutorial explains how to calculate the [electronic density of states]({{ reference_url }}/properties-directory/non-scalar/electronic-dos/) (DOS) of crystalline silicon in its standard equilibrium cubic-diamond crystal structure, based on [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT). [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) is used as the simulation engine. -!!!note "Quantum ESPRESSO version considered in this tutorial" - The present tutorial is written for Quantum ESPRESSO at versions 5.2.1, 5.4.0, 6.0.0 or 6.3. +!!!note "Quantum ESPRESSO version" + This tutorial applies to Quantum ESPRESSO versions 5.2.1, 5.4.0, 6.0.0, 6.3, and later. !!!warning "Accuracy of the results" - Please note that this calculation is performed using [Density Functional Theory](../../../models-directory/dft/overview.md) and the [Generalized Gradient Approximation](../../../models-directory/dft/parameters.md#subtype), which is known to under-estimate the energy of unoccupied electronic states. + This calculation uses DFT with the [Generalized Gradient Approximation]({{ reference_url }}/models-directory/dft/parameters/#subtype), which is known to underestimate the energy of unoccupied electronic states. -## Create job -Silicon in its cubic-diamond crystal structure is the [default material](../../../materials/default.md) that is shown on [new job creation](../../../jobs-designer/overview.md), unless this default was [changed](../../../entities-general/actions/set-default.md) by the user following [account](../../../accounts/overview.md) creation. If silicon is still the default choice, it will as such be automatically loaded at the moment of the [opening](../../../jobs/actions/create.md) of [Job Designer](../../../jobs-designer/overview.md). +## 1. Create a job -## Choose Workflow +Silicon in its cubic-diamond crystal structure is the [default material]({{ reference_url }}/materials/default/) loaded on [new job creation]({{ interface_url }}/jobs-designer/overview/), unless the default was [changed]({{ interface_url }}/entities-general/actions/set-default/) after [account]({{ reference_url }}/accounts/overview/) creation. If silicon is still the default, it is automatically loaded when the [Job Designer]({{ interface_url }}/jobs-designer/overview/) is [opened]({{ interface_url }}/jobs/actions/create/). -The Density of States in typically calculated in conjunction with the [electronic band structure](../../../properties-directory/non-scalar/bandstructure.md) of the material under investigation, whose computation is the object of a [separate tutorial](band-structure.md). -[Workflows](../../../workflows/overview.md) for calculating the band structure together with the Density of States through [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) can readily be [imported](../../../workflows/actions/copy-bank.md) from the [Workflows Bank](../../../workflows/bank.md) into the account-owned [collection](../../../accounts/collections.md). This workflow can later be [selected](../../../jobs-designer/actions-header-menu/select-workflow.md) and added to the [Job being created](../../../jobs-designer/workflow-tab.md). +## 2. Select the workflow -## Set Sampling in Reciprocal Space +The DOS is typically calculated together with the [electronic band structure]({{ reference_url }}/properties-directory/non-scalar/bandstructure/), whose computation is covered in a [separate tutorial](band-structure.md). -It is critical to have a high [k-point density](../../../models/auxiliary-concepts/reciprocal-space/sampling.md) in order to calculate the density of states with sufficient accuracy. The method for treating [partial electronic occupancies](../../../models/auxiliary-concepts/reciprocal-space/electronic-occupations.md) is also important in establishing the quality of the computation: the **tetrahedron method**, for example, is more precise for Density of States calculations. +[Workflows]({{ reference_url }}/workflows/overview/) for calculating the band structure together with the DOS through [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/). The workflow can then be [selected]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) and added to the [job being created]({{ interface_url }}/jobs-designer/workflow-tab/). -In [Quantum Espresso](../../../software-directory/modeling/quantum-espresso/overview.md), the band structure + Density of States [workflow](../../../workflows/overview.md) has five [units](../../../workflows/components/units.md) in total. The first unit specifies the settings for the self-consistent calculation of the eigenvalues and wave functions. The second unit calculation is a non self-consitent calculation using the wave functions and charge density of the previous calculation. Subsequent units calculate the density of states, and also the projection of those states for partial density of states analysis. -We set the size of the grid of k-points to 18 x 18 x 18 in the first workflow unit. This provides a dense enough k-point sampling in order to resolve the fine features present within the output of the Density of States computation. The validity of this choice of k-grid size for yielding accurate results of order meV in the final energy can be verified by performing the relevant [convergence study](../../../models/auxiliary-concepts/reciprocal-space/convergence.md). +## 3. Set sampling in reciprocal space -## Submit job +A high [k-point density]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) is critical for calculating the DOS with sufficient accuracy. The method for treating [partial electronic occupancies]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/electronic-occupations/) also affects the quality of the computation — the **tetrahedron method**, for example, is more precise for DOS calculations. -Before [submitting](../../../jobs/actions/run.md) the [job](../../../jobs/overview.md), the user should click on the ["Compute" tab](../../../jobs-designer/compute-tab.md) of [Job Designer](../../../jobs-designer/overview.md) and examine the [compute parameters](../../../infrastructure/compute/parameters.md) included therein. Silicon is a small structure, so four CPUs and one minute of calculation runtime should be sufficient. +In [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/), the band structure + DOS [workflow]({{ reference_url }}/workflows/overview/) has five [units]({{ reference_url }}/workflows/components/units/) in total. The first unit performs a self-consistent field (SCF) calculation of the eigenvalues and wave functions. The second unit performs a non-self-consistent calculation using the wave functions and charge density from the first step. Subsequent units calculate the total DOS and partial DOS (projected onto individual atoms and orbital characters). -## Examine results +The k-point grid is set to 18 × 18 × 18 in the first workflow unit. This provides dense enough sampling to resolve the fine features of the DOS. The validity of this grid size for yielding meV-level accuracy can be verified by performing a [convergence study]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/convergence/). -When all five [unit](../../../workflows/components/units.md) computations are complete at the end of Job execution, switching to the [Results tab](../../../jobs/ui/results-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md) will show the density of states for the silicon sample under investigation, together with the partial density of states due to each atom in the structure as well as their s and p electron-like character. Moving the mouse cursor along each data series will highlight the atom's electronic character that the data series corresponds to. + +## 4. Submit the job + +Before [submitting]({{ interface_url }}/jobs/actions/run/) the [job]({{ reference_url }}/jobs/overview/), the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) of [Job Designer]({{ interface_url }}/jobs-designer/overview/) should be reviewed to verify the [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/). Silicon is a small structure, so four CPUs and one minute of calculation runtime are sufficient. + + +## 5. Examine the results + +Once all five [unit]({{ reference_url }}/workflows/components/units/) computations complete, the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) displays the DOS for the silicon sample, together with the partial DOS due to each atom and their s- and p-electron-like character. Moving the mouse cursor along each data series highlights the atom and orbital character that the series corresponds to. !!!note "Partial contributions" - The numbers represent the order of the current orbital as included inside the pseudopotential, and **not** the principal quantum number. - -## Animation + The numbers in the partial DOS legend represent the order of the current orbital as included inside the pseudopotential, **not** the principal quantum number. + + +## 6. Video walkthrough -We demonstrate the above-mentioned steps involved in the creation and execution of a Density of States computation on silicon using the [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) simulation engine in the following animation. +The animation below demonstrates the steps involved in the creation and execution of a DOS computation on silicon using Quantum ESPRESSO.
diff --git a/lang/en/docs/tutorials/dft/electronic/electronic-density-mesh.md b/lang/en/docs/tutorials/dft/electronic/electronic-density-mesh.md index 68650706c..da7fe3e20 100644 --- a/lang/en/docs/tutorials/dft/electronic/electronic-density-mesh.md +++ b/lang/en/docs/tutorials/dft/electronic/electronic-density-mesh.md @@ -1,67 +1,62 @@ # Electronic Charge Density Mesh Calculation -This tutorial page explains how to calculate and visualize the electronic charge density mesh based on [Density Functional Theory](../../../models-directory/dft/overview.md). We consider crystalline silicon in its standard equilibrium cubic-diamond crystal structure, and use [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) as our main simulation engine during this tutorial. +This tutorial explains how to calculate and visualize the electronic charge density mesh of crystalline silicon in its standard equilibrium cubic-diamond crystal structure, based on [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT). [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) is used as the simulation engine. -!!!note "Quantum ESPRESSO version considered in this tutorial" - The present tutorial is written for Quantum ESPRESSO at versions 5.2.1, 5.4.0, 6.0.0 or 6.3. +!!!note "Quantum ESPRESSO version" + This tutorial applies to Quantum ESPRESSO versions 5.2.1, 5.4.0, 6.0.0, 6.3, and later. -## Create job -Silicon in its cubic-diamond crystal structure is the [default material](../../../materials/default.md) that is shown on [new job creation](../../../jobs-designer/overview.md), unless this default was [changed](../../../entities-general/actions/set-default.md) by the user following [account](../../../accounts/overview.md) creation. If silicon is still the default choice, it will as such be automatically loaded at the moment of the [opening](../../../jobs/actions/create.md) of [Job Designer](../../../jobs-designer/overview.md). +## 1. Create a job -## Choose Workflow +Silicon in its cubic-diamond crystal structure is the [default material]({{ reference_url }}/materials/default/) loaded on [new job creation]({{ interface_url }}/jobs-designer/overview/), unless the default was [changed]({{ interface_url }}/entities-general/actions/set-default/) after [account]({{ reference_url }}/accounts/overview/) creation. If silicon is still the default, it is automatically loaded when the [Job Designer]({{ interface_url }}/jobs-designer/overview/) is [opened]({{ interface_url }}/jobs/actions/create/). -[Workflows](../../../workflows/overview.md) for calculating the electronic density mesh through [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) can readily be [imported](../../../workflows/actions/copy-bank.md) from the [Workflows Bank](../../../workflows/bank.md) into the account-owned [collection](../../../accounts/collections.md). This workflow can later be [selected](../../../jobs-designer/actions-header-menu/select-workflow.md) and added to the [Job being created](../../../jobs-designer/workflow-tab.md). -## Set Sampling in Reciprocal Space +## 2. Select the workflow -It is critical to have a high [k-point density](../../../models/auxiliary-concepts/reciprocal-space/sampling.md) in order to calculate the electronic density with sufficient accuracy and to properly visualize the resulting charge density iso-surfaces. +[Workflows]({{ reference_url }}/workflows/overview/) for calculating the electronic density mesh through [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/). The workflow can then be [selected]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) and added to the [job being created]({{ interface_url }}/jobs-designer/workflow-tab/). -For Quantum ESPRESSO, the workflow for "Electronic Density Mesh" contains only one [unit](../../../workflows/components/units.md) that produces an output file called **density.xsf**. -We set the size of the grid of k-points to 18 x 18 x 18 in the first workflow unit. This provides a dense enough k-point sampling in order to resolve the fine features present within the electron charge density mesh. The validity of this choice of k-grid size for yielding accurate results of order meV in the final energy can be verified by performing the relevant [convergence study](../../../models/auxiliary-concepts/reciprocal-space/convergence.md). +## 3. Set sampling in reciprocal space -## Submit Job +A high [k-point density]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) is critical for computing the electronic density with sufficient accuracy and for properly visualizing the resulting charge density iso-surfaces. -Before [submitting](../../../jobs/actions/run.md) the [job](../../../jobs/overview.md), the user should click on the ["Compute" tab](../../../jobs-designer/compute-tab.md) of [Job Designer](../../../jobs-designer/overview.md) and inspect the [compute parameters](../../../infrastructure/compute/parameters.md) included therein. Silicon is a small structure, so 4 CPUs and 1 minute of calculation runtime should be sufficient. +For Quantum ESPRESSO, the "Electronic Density Mesh" workflow contains a single [unit]({{ reference_url }}/workflows/components/units/) that produces an output file called **density.xsf**. -## Examine Results +The k-point grid is set to 18 × 18 × 18. The validity of this grid size for yielding meV-level accuracy can be verified by performing a [convergence study]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/convergence/). -Once the computation is complete at the end of Job execution, switching to the [Files tab](../../../jobs/ui/files-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md) will show a listing of the files and directories on the system associated with the electronic density job under consideration. - -The file that is of interest to us in this case is the aforementioned "density.xsf" output file, containing the results for the electronic charge density computation. -## Preparing for Visualization +## 4. Submit the job -### Open remote Desktop +Before [submitting]({{ interface_url }}/jobs/actions/run/) the [job]({{ reference_url }}/jobs/overview/), the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) of [Job Designer]({{ interface_url }}/jobs-designer/overview/) should be reviewed to verify the [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/). Silicon is a small structure, so 4 CPUs and 1 minute of calculation runtime are sufficient. -Following Job execution, we are now ready to visualize graphically the electron density mesh. The next step is to open a [Remote Desktop Connection](../../../remote-connection/remote-desktop.md) so that graphical interface programs for [visualization](../../../software-directory/overview.md#analysis-tools) purposes can be run. Instructions on how to open the [Remote Desktop Interface](../../../remote-connection/remote-desktop.md) starting from our [Web Interface](../../../ui/overview.md) can be found [here](../../../remote-connection/actions/open-desktop.md). -### Open visualization software +## 5. Examine the results -The next steps depend on the [analysis and visualization software](../../../software-directory/overview.md#analysis-tools) preferred by the user. We provide below two examples supported on our platform, for the cases of [XCrysden](../../../software-directory/analysis/xcrysden.md) and [VESTA](../../../software-directory/analysis/vesta.md) respectively. Instructions on how to open Applications in the Remote Desktop Environment can be retrieved [in this page](../../../remote-connection/actions-rd/open-app.md). +Once the computation completes, the [Files tab]({{ interface_url }}/jobs/ui/files-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) shows the files and directories associated with the job. The file of interest is "density.xsf", which contains the electronic charge density. -> If the [default project](../../../jobs/projects.md) was used for the electron charge density calculation, then the location of the "density.xsf" output file referenced in what follows will be: `/home//data///`. Otherwise, the full path to the file is shown underneath the filename among the list of entries in the [Files tab](../../../jobs/ui/files-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md). -## Visualize Charge Density with XCrysden +## 6. Open the Remote Desktop -The user should first open the [XCrysden](../../../software-directory/analysis/xcrysden.md) analysis and visualization software suite. +In order to visualize the electron density mesh graphically, a [Remote Desktop Connection]({{ cli_url }}/remote-connection/remote-desktop/) should be opened so that graphical [visualization tools]({{ reference_url }}/software-directory/overview/#analysis-tools) can be run. Instructions for opening the [Remote Desktop Interface]({{ cli_url }}/remote-connection/remote-desktop/) are available [here]({{ cli_url }}/remote-connection/actions/open-desktop/). -Within XCrysden, the user should first go to "File" > "Open", and then navigate to the [directory](../../../data-on-disk/directories.md) where the "density.xsf" electron density file was saved by the previously-executed Job. This opens the file for a visualization of the electron density. +> If the [default project]({{ reference_url }}/jobs/projects/) was used, the "density.xsf" file is located at: `/home//data///`. The full path is also shown in the [Files tab]({{ interface_url }}/jobs/ui/files-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). -At this stage, the user can adjust the value of charge density to be shown, and toggle the isosurface buttons to display the corresponding data. -## Visualize Charge Density with Vesta +## 7. Visualize charge density with XCrySDen -The user can alternatively open the [VESTA](../../../software-directory/analysis/vesta.md) analysis and visualization software package, for achieving the same objective and purpose as with [XCrysden](../../../software-directory/analysis/xcrysden.md) described above. +Open the [XCrySDen]({{ reference_url }}/software-directory/analysis/xcrysden/) application. Navigate to `File` → `Open`, and browse to the [directory]({{ resources_url }}/data-on-disk/directories/) where "density.xsf" was saved. The charge density is then displayed. Adjust the iso-surface value and toggle the iso-surface buttons to explore the data. -Within VESTA, first go to file->Open and then browse to the directory where the electron density file (density.xsf) is located. This file should be opened in order to visualize the electron density of the material under investigation. -## Animation +## 8. Visualize charge density with VESTA -We demonstrate the above-mentioned steps involved in the creation and execution of an electronic charge density mesh computation workflow on silicon, using the [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) simulation engine, in the following animation. +Alternatively, open the [VESTA]({{ reference_url }}/software-directory/analysis/vesta/) application. Navigate to `File` → `Open` and browse to the directory containing "density.xsf". The electron density is displayed in the VESTA interface. -In this particular example, we consider the usage of [VESTA](../../../software-directory/analysis/vesta.md) for visualizing the output contents of the electron charge density file. In the final part of the animation, we adjust the iso-surface value to have the electronic density more visible as yellow iso-surfaces, demonstrating how the electron density within the dimensions of the unit cell is highly concentrated around the second atom in the two-atom [basis](../../../properties-directory/structural/basis.md) of crystalline silicon. The electron densities around the other atoms do not fully show up in this visualization, since their iso-surfaces are truncated by the sides of the unit cell (this truncation shows up as blue planes on the edges of the unit cell). + +## 9. Video walkthrough + +The animation below demonstrates the steps involved in creating, executing, and visualizing an electronic charge density mesh computation on silicon using Quantum ESPRESSO and [VESTA]({{ reference_url }}/software-directory/analysis/vesta/). + +In the final part of the animation, the iso-surface value is adjusted to make the electronic density visible as yellow iso-surfaces, showing how the electron density is concentrated around the second atom in the two-atom [basis]({{ reference_url }}/properties-directory/structural/basis/) of crystalline silicon. The electron densities around other atoms are truncated by the sides of the unit cell (appearing as blue planes on the edges).
diff --git a/lang/en/docs/tutorials/dft/electronic/esm-qe.md b/lang/en/docs/tutorials/dft/electronic/esm-qe.md index 4fc22492d..571e34583 100644 --- a/lang/en/docs/tutorials/dft/electronic/esm-qe.md +++ b/lang/en/docs/tutorials/dft/electronic/esm-qe.md @@ -1,130 +1,98 @@ # Effective Screening Medium (ESM) Calculation -In this tutorial, we demonstrate how to create a [Job](../../../jobs/overview.md) in order to extract the **potential/charge profiles** via the [Effective Screening Medium (ESM)](../../../models/auxiliary-concepts/esm.md) approach for simulating **surfaces** and **interfaces**, based on [Density Functional Theory](../../../models-directory/dft/overview.md). +This tutorial demonstrates how to extract **potential/charge profiles** via the [Effective Screening Medium (ESM)]({{ reference_url }}/models/auxiliary-concepts/esm/) approach for simulating **surfaces** and **interfaces**, based on [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT). The example system is a water (H₂O) molecule, and [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) is used as the simulation engine. -We consider a water (H2O) molecule in the present example, and use [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) as our main simulation engine. +!!!note "Quantum ESPRESSO version" + This tutorial applies to Quantum ESPRESSO versions 5.2.1, 5.4.0, 6.0.0, 6.3, and later. -!!!note "Quantum ESPRESSO version considered in this tutorial" - The present tutorial is written for Quantum ESPRESSO at versions 5.2.1, 5.4.0, 6.0.0 or 6.3. - -## Workflow (Quantum ESPRESSO) -
- Expand to view ... - -The [Workflow](../../../workflows/overview.md) implementing ESM calculations on our platform through [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) is composed of a single main computational [unit](../../../workflows/components/units.md). - -Examples on how ESM is enabled and supported in Quantum ESPRESSO are offered in Ref. [^1]. Here, we will offer a brief review of the most important input keywords, that are required to be included in Quantum ESPRESSO input scripts in the context of ESM calculations. - -### Quantum ESPRESSO ESM Input Parameters - -#### assume_isolated = 'esm' - -This parameter is used to perform the calculation assuming the system to be isolated, such as in the cases of a molecule or a cluster, as opposed to regular periodic boundary conditions. +## 1. Understand the ESM workflow -For polarized or charged slab calculation, the 'esm' option embeds the simulation cell within an effective semi- -infinite medium in the perpendicular direction (along z). Embedding regions can be vacuum or semi-infinite metal electrodes.If between two electrodes, an optional electric field may be applied via the 'esm_efield' keyword described in what follows. - -This requires a simulation cell with the $c$ lattice vector along z, normal to the xy plane, with the slab centered around z=0. +
+ Expand to view input parameter details -#### esm_bc +The [workflow]({{ reference_url }}/workflows/overview/) for ESM calculations with Quantum ESPRESSO contains a single main computational [unit]({{ reference_url }}/workflows/components/units/). Examples of ESM in Quantum ESPRESSO are available in Ref. [^1]. The key input parameters are: -This option determines the boundary conditions used for either side of the slab. The available possibilities are listed in [this page](../../../materials-designer/header-menu/advanced/boundary-conditions.md). +**`assume_isolated = 'esm'`** — treats the system as isolated (molecule or cluster). For polarized or charged slab calculations, this embeds the simulation cell within an effective semi-infinite medium along z. Embedding regions can be vacuum or semi-infinite metal electrodes. An optional electric field can be applied via `esm_efield`. The simulation cell must have the $c$ lattice vector along z, with the slab centered around z=0. -#### esm_w +**`esm_bc`** — determines the [boundary conditions]({{ interface_url }}/materials-designer/header-menu/advanced/boundary-conditions/) used for either side of the slab. -This keyword determines the [position offset](../../../materials-designer/header-menu/advanced/boundary-conditions.md#offset) of the start of the effective screening region, measured relative to the edge of the simulation cell (of total vertical thickness $L_z$). The ESM region begins at (assuming the slab to be centered around z=0): +**`esm_w`** — the [position offset]({{ interface_url }}/materials-designer/header-menu/advanced/boundary-conditions/#offset) of the start of the effective screening region, measured relative to the cell edge: $$ - z = +/- [L_z/2 + esm_w] +z = \pm [L_z/2 + \text{esm\_w}] $$ -#### esm_efield - -This other option gives the magnitude of the electric field to be applied between semi-infinite ESM electrodes (metals). It is applicable only in the case of the metal-slab-metal (bc2) [boundary condition](../../../materials-designer/header-menu/advanced/boundary-conditions.md). - -#### lfcpopt +**`esm_efield`** — magnitude of the electric field applied between semi-infinite ESM electrodes. Applicable only with the metal-slab-metal (bc2) [boundary condition]({{ interface_url }}/materials-designer/header-menu/advanced/boundary-conditions/). -If the `lfcpopt` option is set to ".TRUE.", it performs a constant bias potential (constant-mu) calculation [^2] for a static system with ESM method. This option is subject to the following two conditions: +**`lfcpopt`** — if set to `.TRUE.`, performs a constant bias potential (constant-μ) calculation [^2]. Requires `calculation = 'relax'` and bc2 or bc3 boundary conditions. -- calculation must be of type 'relax'. -- [Boundary conditions](../../../materials-designer/header-menu/advanced/boundary-conditions.md) can be of type "bc2" or "bc3" only. +**`fcp_mu`** — target Fermi energy when `lfcpopt = .TRUE.`. -Using the constant-mu method, one can control the Fermi energy, that is the applied bias, during a simulation. - -#### fcp_mu - -Finally, the `fcp_mu` tag in the Quantum ESPRESSO input script sets the target Fermi energy for the simulation, if the aforementioned `lfcpopt` input parameter has been set to ".TRUE.". - -### SCF vs Relax ESM Calculations - -Two different flavors of ESM workflow calculations are offered on our platform, the first one performing a basic ground state energy self-consistent field (SCF) calculation, whereas the second affording also for the [relaxation](../../../workflows/addons/structural-relaxation.md) of the inter-atomic forces, within the structure under consideration, during the course of the ESM computation. The latter option is enabled via the `calculation = 'relax'` Quantum ESPRESSO input tag. +Two workflow flavors are available: a basic ground-state SCF calculation and a variant that includes [structural relaxation]({{ reference_url }}/workflows/addons/structural-relaxation/) during the ESM computation (enabled via `calculation = 'relax'`).
-## Prepare Water Molecule -The structure of a water molecule (H2O) can readily be [imported](../../../materials/actions/copy-bank.md) from the [Materials Bank](../../../materials/bank.md) into the account-owned [collection](../../../accounts/collections.md) of materials, if it is not already present there. +## 2. Prepare the water molecule -This water structure should then be [imported](../../../materials-designer/header-menu/input-output/import.md) into the [Materials Designer](../../../materials-designer/overview.md) interface, in order to edit its [boundary conditions](../../../materials-designer/header-menu/advanced/boundary-conditions.md) via the corresponding option in the ["Advanced" menu](../../../materials-designer/header-menu/advanced.md). +The H₂O structure can be [imported]({{ interface_url }}/materials/actions/copy-bank/) from the [Materials Bank]({{ reference_url }}/materials/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/). -In the present example, we shall opt for the "Vacuum-Slab-Vacuum" (bc1) boundary condition option. The vacuum boundaries should be shifted by half of the lattice $c$ constant, by leaving the "Offset" option of the ["Set Boundary Conditions" dialog](../../../materials-designer/header-menu/advanced/boundary-conditions.md) to its default zero value. +The structure should then be [imported]({{ interface_url }}/materials-designer/header-menu/input-output/import/) into the [Materials Designer]({{ interface_url }}/materials-designer/overview/) to edit its [boundary conditions]({{ interface_url }}/materials-designer/header-menu/advanced/boundary-conditions/) via the [Advanced menu]({{ interface_url }}/materials-designer/header-menu/advanced/). -After finishing setting up the boundary conditions for our water molecule structure, the user should [Save](../../../materials-designer/header-menu/input-output/save.md) the changes to the structure into the account-owned materials collection, and then exit Materials Designer. +For this example, select the "Vacuum-Slab-Vacuum" (bc1) boundary condition. Leave the "Offset" to its default zero value, which shifts the vacuum boundaries by half the lattice $c$ constant. -## Create Job +After setting the boundary conditions, [save]({{ interface_url }}/materials-designer/header-menu/input-output/save/) the structure and exit the Materials Designer. -The user should then open an instance of the [Job Designer interface](../../../jobs-designer/overview.md) in order to create a new simulation [Job](../../../jobs/overview.md), via the corresponding option in the main [left-hand sidebar](../../../ui/left-sidebar.md#create-job) of our [Web interface](../../../ui/overview.md). -## Import Water Molecule in Job Designer +## 3. Create the job and import the material -The previously-created water structure should now be [selected and imported](../../../jobs-designer/actions-header-menu/select-materials.md) via the ["Materials" tab](../../../jobs-designer/materials-tab.md) of [Job Designer](../../../jobs-designer/overview.md), in order to be made the main simulation system under consideration. +Open the [Job Designer]({{ interface_url }}/jobs-designer/overview/) to create a new [Job]({{ reference_url }}/jobs/overview/). The water structure should be [selected and imported]({{ interface_url }}/jobs-designer/actions-header-menu/select-materials/) via the [Materials tab]({{ interface_url }}/jobs-designer/materials-tab/). -## Copy ESM Workflow from Bank -[Workflows](../../../workflows/overview.md) for performing [Effective Screening Medium (ESM)](../../../models/auxiliary-concepts/esm.md) computations with [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) can readily be [imported](../../../workflows/actions/copy-bank.md) from the [Workflows Bank](../../../workflows/bank.md) into the account-owned [collection](../../../accounts/collections.md). The user should search for the "ESM" keyword whilst performing a [search](../../../entities-general/actions/search.md) within the Bank. +## 4. Import the ESM workflow from the bank -This workflow can later be [selected](../../../jobs-designer/actions-header-menu/select-workflow.md) and added to the [Job being created](../../../jobs-designer/overview.md). +[Workflows]({{ reference_url }}/workflows/overview/) for ESM calculations with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/). Search for the "ESM" keyword in the bank. The workflow can then be [selected]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) and added to the job. -## Change Important Settings -Opening ["Important Settings"](../../../workflow-designer/subworkflow-editor/important-settings.md) within the [Workflow Tab](../../../jobs-designer/workflow-tab.md) of Job Designer allows the user to customize the following Boundary Conditions-related settings: +## 5. Configure the important settings -- Type of [boundary conditions](../../../materials-designer/header-menu/advanced/boundary-conditions.md) +Open [Important Settings]({{ interface_url }}/workflow-designer/subworkflow-editor/important-settings/) within the [Workflow Tab]({{ interface_url }}/jobs-designer/workflow-tab/) to configure the following boundary condition parameters: + +- Type of [boundary conditions]({{ interface_url }}/materials-designer/header-menu/advanced/boundary-conditions/) - Offset - Electric Field -- Target Fermi Energy +- Target Fermi Energy + +For this example, keep the bc1 boundary conditions and leave the remaining options at their default zero values. Set the [k-point]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) grid to 1 × 1 × 1, since the system is a molecule rather than a periodic crystal. -In the present example, we shall keep the previously-defined 'bc1' boundary conditions, and leave the remaining three options to their default zero values. -In addition, the user should set the size of the grid of [k-points](../../../models/auxiliary-concepts/reciprocal-space/sampling.md) to 1x1x1 in this case, also under "Important Settings", since we are dealing with a water molecule as opposed to a periodic crystal. +## 6. Submit the job -## Submit Job +Before [submitting]({{ interface_url }}/jobs/actions/run/) the [job]({{ reference_url }}/jobs/overview/), review the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) of [Job Designer]({{ interface_url }}/jobs-designer/overview/) to verify the [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/). Water is a small structure, so 4 CPUs and a few minutes of runtime are sufficient. -Before [submitting](../../../jobs/actions/run.md) the [job](../../../jobs/overview.md), the user should click on the ["Compute" tab](../../../jobs-designer/compute-tab.md) of [Job Designer](../../../jobs-designer/overview.md) and examine the [compute parameters](../../../infrastructure/compute/parameters.md) included therein. Water is a small structure, so 4 CPUs and a few minutes of calculation runtime should be sufficient. -## Examine Final Results +## 7. Examine the results -### Potential Energy Profile +### 7.1. Potential energy profile -When the ESM computation is complete at the end of Job execution, switching to the [Results tab](../../../jobs/ui/results-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md) will show the **Potential Energy profile** of our water-vacuum system, plotted as an energy curve (in eV) as a function of the distance along the vertical perpendicular direction (the "z" coordinate), away from the central water slab. The "local" and "Hartree" contributions to the Potential energy are also given separately. +The [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) displays the **potential energy profile** of the water-vacuum system, plotted as energy (eV) versus distance along the z-coordinate, away from the central water slab. The local and Hartree contributions to the potential energy are shown separately. -### Charge Density Profile +### 7.2. Charge density profile -Similarly, the Charge Density profile is also displayed under the [Results tab](../../../jobs/ui/results-tab.md), showing the evolution of the charge density (in electron charge units/Angstrom) as a function of the same vertical "z" coordinate mentioned previously. +The **charge density profile** is also displayed, showing the charge density (in electron charge units/Å) as a function of the z-coordinate. The 2D (xy-plane) average charge density and electrostatic potentials are printed to the file with the `.esm1` extension, accessible via the [Files tab]({{ interface_url }}/jobs/ui/files-tab/). -The two dimensional (xy-plane) average charge density and electrostatic potentials are printed out into the file with the '.esm1' extension, accessible via the ["Files" tab](../../../jobs/ui/files-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md). -## Animation +## 8. Video walkthrough -We demonstrate the above-mentioned steps involved in the creation and execution of an ESM computation on a water molecule, using the [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) simulation engine, in the following animation. Here, we shall make use of the "Relax" variant of the Quantum ESPRESSO ESM workflow. +The animation below demonstrates the creation and execution of an ESM computation on a water molecule using the "Relax" variant of the Quantum ESPRESSO ESM workflow.
-## Links -[^1]: [Quantum ESPRESSO ESM Examples, Official GitHub repository](https://github.com/QEF/q-e/tree/master/PW/examples/ESM_example) +## 9. Links +[^1]: [Quantum ESPRESSO ESM Examples, Official GitHub repository](https://github.com/QEF/q-e/tree/master/PW/examples/ESM_example) [^2]: [N. Bonnet, T. Morishita, O. Sugino, and M. Otani: "First-Principles Molecular Dynamics at a Constant Electrode Potential", Phys. Rev. Lett. 109, 266101 (2012)](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.109.266101) diff --git a/lang/en/docs/tutorials/dft/electronic/fermi-surface.md b/lang/en/docs/tutorials/dft/electronic/fermi-surface.md index 22ef67ee7..17e91695c 100644 --- a/lang/en/docs/tutorials/dft/electronic/fermi-surface.md +++ b/lang/en/docs/tutorials/dft/electronic/fermi-surface.md @@ -1,41 +1,47 @@ # Fermi Surface Calculation -This page explains how to calculate the [Fermi surface](../../../properties-directory/scalar/fermi-energy.md) for metallic copper (Cu) lying in its equilibrium face-centred cubic (fcc) [Bravais Lattice](../../../properties-directory/structural/lattice.md), through the use of [Density Functional Theory](../../../models-directory/dft/overview.md). We will use [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) as our simulation engine for this tutorial. +This tutorial explains how to calculate and visualize the [Fermi surface]({{ reference_url }}/properties-directory/scalar/fermi-energy/) for metallic copper (Cu) in its equilibrium face-centred cubic (fcc) [Bravais Lattice]({{ reference_url }}/properties-directory/structural/lattice/), based on [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT). [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) is used as the simulation engine. -!!!note "Quantum ESPRESSO version considered in this tutorial" - The present tutorial is written for Quantum ESPRESSO at versions 5.2.1, 5.4.0, 6.0.0 or 6.3. +!!!note "Quantum ESPRESSO version" + This tutorial applies to Quantum ESPRESSO versions 5.2.1, 5.4.0, 6.0.0, 6.3, and later. -## Create Job and Select Material -The user should start by creating a new [Job](../../../jobs/overview.md), through [opening](../../../jobs/actions/create.md) the [Job Designer Interface](../../../jobs-designer/overview.md). The fcc crystal structure of copper should then be [selected and added](../../../jobs-designer/actions-header-menu/select-materials.md) to the new Job being designed, assuming that this structure is already present among the entries listed in the account-owned [collection](../../../accounts/collections.md) of materials. +## 1. Create a job and select the material -## Choose Workflow +Start by creating a new [Job]({{ reference_url }}/jobs/overview/) through [opening]({{ interface_url }}/jobs/actions/create/) the [Job Designer Interface]({{ interface_url }}/jobs-designer/overview/). The fcc crystal structure of copper should then be [selected and added]({{ interface_url }}/jobs-designer/actions-header-menu/select-materials/) to the new job, assuming the structure is already present in the account-owned [collection]({{ reference_url }}/accounts/collections/) of materials. -[Workflows](../../../workflows/overview.md) for calculating the [band structure](../../../properties-directory/non-scalar/bandstructure.md) of [materials](../../../materials/overview.md) with [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) can readily be [imported](../../../workflows/actions/copy-bank.md) from the [Workflows Bank](../../../workflows/bank.md) into the account-owned [collection](../../../accounts/collections.md). This workflow can later be [selected](../../../jobs-designer/actions-header-menu/select-workflow.md) and added to the [Job being created](../../../jobs-designer/workflow-tab.md). -## Set Sampling in Reciprocal Space +## 2. Select the workflow -It is critical to have a high [k-point density](../../../models/auxiliary-concepts/reciprocal-space/sampling.md) in order to resolve enough details for the Fermi surface plot. +[Workflows]({{ reference_url }}/workflows/overview/) for calculating the [band structure]({{ reference_url }}/properties-directory/non-scalar/bandstructure/) with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/). The workflow can then be [selected]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) and added to the [job being created]({{ interface_url }}/jobs-designer/workflow-tab/). -The band structure workflow is composed of two [units](../../../workflows/components/units.md). The first unit specifies the settings for the self-consistent calculation of the energy eigenvalues and wave functions. The second unit calculation is a non self-consistent calculation using the wave functions and charge density of the previous calculation. -We set the size of the grid of k-points to 18 x 18 x 18 in the first workflow unit. This provides a dense enough k-point sampling in order to resolve the fine features present within the output of the band structure computation. The validity of this choice of k-grid size for yielding accurate results of order meV in the final energy can be verified by performing the relevant [convergence study](../../../models/auxiliary-concepts/reciprocal-space/convergence.md). +## 3. Set sampling in reciprocal space -## Submit Job +A high [k-point density]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) is critical for resolving the details of the Fermi surface plot. -Before [submitting](../../../jobs/actions/run.md) the [job](../../../jobs/overview.md), the user should click on the ["Compute" tab](../../../jobs-designer/compute-tab.md) of [Job Designer](../../../jobs-designer/overview.md) and examine the [compute parameters](../../../infrastructure/compute/parameters.md) included therein. Copper is a small structure, so 4 CPUs and 1 minute of calculation runtime should be sufficient. +The band structure workflow is composed of two [units]({{ reference_url }}/workflows/components/units/). The first unit performs a self-consistent field (SCF) calculation of the energy eigenvalues and wave functions. The second unit performs a non-self-consistent calculation using the wave functions and charge density from the first step. -## Examine Final Results +The k-point grid is set to 18 × 18 × 18 in the first workflow unit. The validity of this grid size for yielding meV-level accuracy can be verified by performing a [convergence study]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/convergence/). -When both [unit](../../../workflows/components/units.md) computations are complete at the end of Job execution, switching to the [Results tab](../../../jobs/ui/results-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md) will show the final [total energy](../../../properties-directory/scalar/total-energy.md), the [Fermi energy](../../../properties-directory/scalar/fermi-energy.md), and more information about each execution unit. -The user can also browse the actual input and output files that are part of the calculation under the [Files Tab](../../../jobs/ui/files-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md). +## 4. Submit the job -## Generate File with Fermi Surface Information +Before [submitting]({{ interface_url }}/jobs/actions/run/) the [job]({{ reference_url }}/jobs/overview/), the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) of [Job Designer]({{ interface_url }}/jobs-designer/overview/) should be reviewed to verify the [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/). Copper is a small structure, so 4 CPUs and 1 minute of calculation runtime are sufficient. -Once the simulation is complete, the user should [open](../../../remote-connection/actions/open-terminal.md) a [Web Terminal session](../../../remote-connection/web-terminal.md) in order to create a file that is essential for visualizing the Fermi surface. The calculation of Fermi surface can in general be performed using the `fs.x` code, part of the [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) distribution. The resulting file in `.bxsf` format can then be read and plotted using the [XCrySDen](../../../software-directory/analysis/xcrysden.md) analysis and visualization software. -In order to generate the post-processing bxsf file, the user should first navigate from within the [Command Line Interface](../../../cli/overview.md) into the [working directory](../../../jobs-cli/batch-scripts/directories.md) containing the simulation input and output files. Once in this directory, a new input file with the following contents should be written using any [command-line text editor](../../../software-directory/development/text-editors.md) (for example `nano`). This new file should be given the name `fs.in` at the moment of saving: +## 5. Examine the results + +Once both [unit]({{ reference_url }}/workflows/components/units/) computations complete, the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) displays the final [total energy]({{ reference_url }}/properties-directory/scalar/total-energy/), the [Fermi energy]({{ reference_url }}/properties-directory/scalar/fermi-energy/), and additional information about each execution unit. + +The actual input and output files can also be browsed under the [Files Tab]({{ interface_url }}/jobs/ui/files-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). + + +## 6. Generate the Fermi surface file + +Once the simulation is complete, a [Web Terminal session]({{ cli_url }}/remote-connection/web-terminal/) should be [opened]({{ cli_url }}/remote-connection/actions/open-terminal/) to create the file needed for Fermi surface visualization. The `fs.x` code, part of the [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) distribution, generates a `.bxsf` file that can be plotted using [XCrySDen]({{ reference_url }}/software-directory/analysis/xcrysden/). + +First, navigate within the [Command Line Interface]({{ cli_url }}/cli/overview/) into the [working directory]({{ cli_url }}/jobs-cli/batch-scripts/directories/) containing the simulation files. Then, create a new input file named `fs.in` using any [command-line text editor]({{ reference_url }}/software-directory/development/text-editors/) (e.g. `nano`) with the following contents: ```bash &fermi @@ -44,30 +50,30 @@ In order to generate the post-processing bxsf file, the user should first naviga / ``` -Afterwards, the following commands should be entered, first for [loading](../../../cli/actions/modules-actions.md#load-desired-module) the appropriate Quantum ESPRESSO [module](../../../cli/modules.md) under the Command Line Interface [environment](../../../cli/environment.md), and then for running the `fs.x` executable on the previously-created `fs.in` file: +Next, load the appropriate Quantum ESPRESSO [module]({{ cli_url }}/cli/modules/) and run the `fs.x` executable: ```bash module load espresso/540-i-174-impi-044 fs.x < fs.in -``` +``` -After the end of the execution of the above commands, the user will notice a new file that has been created in the current working directory called `__prefix__fs.bxsf`. We shall use this file for the ensuing visualization of the Fermi surface with XCrySDen. +After execution, a new file called `__prefix__fs.bxsf` appears in the current working directory. -Finally, the user should close the Web Terminal session to return to the original [Web Interface](../../../ui/overview.md) of our platform. +Close the Web Terminal session to return to the [Web Interface]({{ interface_url }}/ui/overview/). -## Visualize Fermi Surface -The next step is to [open](../../../remote-connection/actions/open-desktop.md) a [Remote Desktop Connection](../../../remote-connection/remote-desktop.md), so that graphical interface programs for [visualization purposes](../../../software-directory/overview.md#analysis-tools) can be run. +## 7. Visualize the Fermi surface -The user should now find and [open](../../../remote-connection/actions-rd/open-app.md) the [XCrySDen](../../../software-directory/analysis/xcrysden.md) application. +Open a [Remote Desktop Connection]({{ cli_url }}/remote-connection/remote-desktop/) to run graphical visualization software. Instructions for opening the Remote Desktop are available [here]({{ cli_url }}/remote-connection/actions/open-desktop/). -Within XCrysden, the user should go to `File` -> `Open Structure` -> `Open BXSF`, and then navigate to the directory where the aforementioned `__prefix__fs.bxsf` file was created. This opens a graphical visualization of the Fermi surface, as portrayed in the example screenshot below. +Find and [open]({{ cli_url }}/remote-connection/actions-rd/open-app/) the [XCrySDen]({{ reference_url }}/software-directory/analysis/xcrysden/) application. Within XCrySDen, navigate to `File` → `Open Structure` → `Open BXSF`, then browse to the directory where `__prefix__fs.bxsf` was created. ![Fermi Surface Copper](../../../images/tutorials/fermi-surface-copper.png "Fermi Surface Copper") -## Animation -We demonstrate the above-mentioned steps involved in the creation, execution and visualization of a Fermi Surface calculation on crystalline copper, using the [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) simulation engine, in the following animation. +## 8. Video walkthrough + +The animation below demonstrates the creation, execution, and visualization of a Fermi surface calculation on crystalline copper using Quantum ESPRESSO.
diff --git a/lang/en/docs/tutorials/dft/electronic/gw-qe-bs-fullfreq.md b/lang/en/docs/tutorials/dft/electronic/gw-qe-bs-fullfreq.md index 16a599d19..874e44c3e 100644 --- a/lang/en/docs/tutorials/dft/electronic/gw-qe-bs-fullfreq.md +++ b/lang/en/docs/tutorials/dft/electronic/gw-qe-bs-fullfreq.md @@ -1,116 +1,101 @@ -# Calculate Electronic Band Structure with GW Approximation and Full-frequency Integration +# Calculate Electronic Band Structure with GW Approximation and Full-Frequency Integration -This tutorial page explains how to calculate the [electronic band structure](../../../properties-directory/non-scalar/bandstructure.md) of a semiconducting material based on [Density Functional Theory](../../../models-directory/dft/overview.md). We consider crystalline silicon in its standard equilibrium cubic-diamond crystal structure, and use [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) as our main simulation engine during this tutorial. +This tutorial explains how to calculate the [electronic band structure]({{ reference_url }}/properties-directory/non-scalar/bandstructure/) of crystalline silicon in its cubic-diamond crystal structure using the [GW Approximation]({{ reference_url }}/models-directory/dft/notes/#the-gw-approximation) with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) and **full-frequency integration** along the imaginary axis. -!!!note "Quantum ESPRESSO version considered in this tutorial" - The present tutorial is written for Quantum ESPRESSO at version(s) 6.3. +!!!note "Quantum ESPRESSO version" + This tutorial applies to Quantum ESPRESSO version 6.3 and later. -## GW Approximation +The GW Approximation produces more accurate electronic band structures than standard DFT, at significantly higher computational cost. The aim is to calculate the band structure of silicon along the Γ–X–W–K directions. For an alternative approach using the plasmon-pole approximation, see the [plasmon-pole tutorial](gw-qe-bs-plasmon.md). More information on GW results for a sample set of materials can be found in Ref. 1 of [this page](gw-vasp-bg.md). -What sets the present tutorial apart from the [GGA DFT band-structure tutorial](band-structure.md) is the employment of the [GW Approximation](../../../models-directory/dft/notes.md#the-gw-approximation). This method is significantly more computationally intensive than the conventional approach for computing electronic band structures. It yields more accurate electronic results closer to experimental value. More information about this approximation, together with a demonstration of its application and results on a sample set of materials, can be found in Ref. 1 in [this page](gw-vasp-bg.md). -The aim of the present tutorial is to calculate the electronic band structure of silicon along the Gamma-X-W-K directions. In this example, we use **full-frequency integration** along the imaginary axis. For an alternative approach to GW band calculation using the Plasmon pole approximation the user can review [another tutorial](gw-qe-bs-plasmon.md). +## 1. Understand the SternheimerGW code -## The SternheimerGW Code +The GW Approximation is enabled via **SternheimerGW** [^1] [^2], an add-on package for Quantum ESPRESSO. SternheimerGW uses time-dependent density-functional perturbation theory to evaluate GW quasiparticle band structures and spectral functions. Both the Green's function G and the screened Coulomb interaction W are obtained by solving linear Sternheimer equations, avoiding summation over unoccupied states. The code performs a full-frequency integration for accurate spectral properties, and the linear response approach allows evaluation at arbitrary electron wavevectors — particularly useful for indirect band gap semiconductors. -The GW Approximation is enabled on our platform via **SternheimerGW** [^1] [^2], an add-on software package for Quantum ESPRESSO. - -SternheimerGW uses time-dependent density-functional perturbation theory to evaluate GW quasiparticle band structures and spectral functions for solids. Both the Green's function G and the screened Coulomb interaction W are obtained by solving linear Sternheimer equations, thus overcoming the need for a summation over unoccupied states. The code targets the calculation of accurate spectral properties by convoluting G and W using a full frequency integration. The linear response approach allows users to evaluate the spectral function at arbitrary electron wavevectors, which is particularly useful for indirect band gap semiconductors and for simulations of angle-resolved photoelectron spectra. - -Further information and examples on how the GW method is supported by the SternheimerGW code can be retrieved in Ref. [^3]. +Further information is available in Ref. [^3]. !!!warning "Norm-conserving pseudopotentials required" - Steinheimer GW needs to be operated in conjunction with norm-conserving pseudopotentials (default options provided by our platform are explained [here](../../../methods-directory/pseudopotential/default.md)). - -## Workflow Structure - -
- Expand to view + SternheimerGW requires norm-conserving pseudopotentials (default options are described [here]({{ reference_url }}/methods-directory/pseudopotential/default/)). -We shall now describe the computational implementation of the GW Approximation for computing the electronic band structure on our platform, illustrating the various steps constituting the overall [Workflow](../../../workflows/overview.md). -Workflows performing GW calculations, based upon the [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) modeling engine and the full-frequency integration approach, are composed of two main compute [units](../../../workflows/components/units.md): +## 2. Understand the workflow structure -1 - A first ground-state energy self-consistent field (SCF) calculation, to obtain the energy eigenvalues and wave functions. -2 - GW calculation to obtain quasiparticle energies, using SternheimerGW, using the wave functions and charge density of the previous preliminary calculation. +
+ Expand to view detailed input parameters -Let us consider the individual parts of the input file for the latter second step. +The workflow contains two main compute [units]({{ reference_url }}/workflows/components/units/): -### GW Unit +1. A ground-state SCF calculation to obtain energy eigenvalues and wave functions. +2. A GW calculation using SternheimerGW, reading the wave functions and charge density from step 1. -#### Configuration of the scf run +The SternheimerGW input file contains the following key sections: -The variables `prefix` and `outdir` should be set to the same values as in the SCF calculation, so that SternheimerGW can read the results of that preliminary calculation. +**SCF configuration:** The `prefix` and `outdir` variables must match the SCF calculation so SternheimerGW can read its results. -#### Grid used for the linear response +**Linear response grids:** The `kpt_grid` controls the density response for the dielectric function. The `qpt_grid` is used to convolute the Green's function and screened Coulomb interaction. -With the variables `kpt_grid` and `qpt_grid`, we control the integration over the Brillouin zone. The `kpt_grid` is used to calculate the density response required to evaluate the dielectric function. The `qpt_grid` is instead used to convolute the Green's function and the Screened Coulomb interaction. +**Number of bands:** The `num_band` variable controls how many bands receive the GW correction. This value must exceed the number of occupied states for an accurate Fermi energy. -#### Number of bands for which the GW correction is calculated +**W convolution:** The `max_freq_coul` and `num_freq_coul` variables set the maximum value and number of points for the frequency integration. -With the variable `num_band`, we control the for how many bands the GW correction is calculated. In order to determine an accurate Fermi energy, this value must be larger than the number of occupied states. +**Self-energy cutoffs:** The `ecut_corr` and `ecut_exch` variables define the FFT grid for the correlation and exchange contributions to the self-energy. -#### W in the convolution +**Frequencies:** The `FREQUENCIES` section defines the coarse complex frequency mesh for evaluating the screened Coulomb interaction. A mesh along the imaginary frequency axis is typical. -We convolute the Green's function and the Screened Coulomb interaction in the frequency domain. The variables `max_freq_coul` and `num_freq_coul` determine the maximum value and the number of points used in this integration. +**K-points:** The `K_points` section specifies the k-point coordinates (in $2 \pi / a$ units) where the exchange and correlation self-energy are evaluated. -#### Exchange and correlation self energy +
-The variables `ecut_corr` and `ecut_exch` define the Fast Fourier Transform grid that is used to evaluate correlation and exchange contribution to the self energy. -#### Frequencies +## 3. Create the job -The first line in the `FREQUENCIES` section of the SternheimerGW input script gives the number of frequencies followed by number of frequency lines that specify the coarse complex frequency mesh on which the Screened Coulomb interaction is evaluated. From this mesh, we obtain the denser mesh used in the convolution by numerical analytical continuation. Typically, a mesh along the imaginary frequency axis is chosen. +Silicon in its cubic-diamond crystal structure is the [default material]({{ reference_url }}/materials/default/) loaded on [new job creation]({{ interface_url }}/jobs-designer/overview/), unless the default was [changed]({{ interface_url }}/entities-general/actions/set-default/) after [account]({{ reference_url }}/accounts/overview/) creation. -#### K-points -The first line of the final `K_points` section gives the number of k-points, followed by lines specifying the k-point coordinates in $2 \pi / a$ units. The code evaluates the exchange and correlation self energy at these k points. +## 4. Select the workflow -
+[Workflows]({{ reference_url }}/workflows/overview/) for the GW band structure calculation via full-frequency integration can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/). The workflow can then be [selected]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) and added to the [job being created]({{ interface_url }}/jobs-designer/workflow-tab/). -## Create Job -Silicon in its cubic-diamond crystal structure is the [default material](../../../materials/default.md) that is shown on [new job creation](../../../jobs-designer/overview.md), unless this default was [changed](../../../entities-general/actions/set-default.md) by the user following [account](../../../accounts/overview.md) creation. If silicon is still the default choice, it will as such be automatically loaded at the moment of the [opening](../../../jobs/actions/create.md) of [Job Designer](../../../jobs-designer/overview.md). +## 5. Set sampling in reciprocal space -## Choose Workflow +Set the [k-point and q-point grids]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) to 4 × 4 × 4 for the GW unit (8 × 8 × 8 for the SCF unit) via [Important Settings]({{ interface_url }}/workflow-designer/subworkflow-editor/important-settings/). Reduce the plane-wave cutoff to 20 Ry and the charge density cutoff to 80 Ry — sufficient for silicon with a norm-conserving pseudopotential. -[Workflows](../../../workflows/overview.md) for calculating the [band structure](../../../properties-directory/non-scalar/bandstructure.md) of [materials](../../../materials/overview.md) with [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md), operated in conjunction with the SternheimerGW code for enabling the GW Approximation via the full-frequency integration approach, can readily be [imported](../../../workflows/actions/copy-bank.md) from the [Workflows Bank](../../../workflows/bank.md) into the account-owned [collection](../../../accounts/collections.md). This workflow can later be [selected](../../../jobs-designer/actions-header-menu/select-workflow.md) and added to the [Job being created](../../../jobs-designer/workflow-tab.md). +Also modify the [k-point path]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/paths/) (at the bottom of Important Settings) to sample the Γ–X–W–K region of the Brillouin Zone. -## Set Sampling in Reciprocal Space -We set the size of the [grids of k-points and q-points](../../../models/auxiliary-concepts/reciprocal-space/sampling.md) to 4 x 4 x 4 for the second GW workflow unit (8 x 8 x 8 kgrid in the first SCF unit), via the ["Important Settings" section](../../../workflow-designer/subworkflow-editor/important-settings.md) under the [Workflow Tab](../../../jobs-designer/workflow-tab.md) of [Job Designer](../../../jobs-designer/overview.md). We also take care to reduce the plane-wave cutoff from their default values to 20 Ry, and the charge density cutoff to 80 Ry, which for the case of silicon modeled with a norm conserving pseudopotential provide sufficient precision. +## 6. Submit the job -In addition, we also modify the [k-point path](../../../models/auxiliary-concepts/reciprocal-space/paths.md), accessible towards the bottom of "Important Settings", to sample only the region of the Brillouin Zone of the crystal between the central Gamma point and the X, W and K special symmetry points. +Before [submitting]({{ interface_url }}/jobs/actions/run/) the [job]({{ reference_url }}/jobs/overview/), review the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) of [Job Designer]({{ interface_url }}/jobs-designer/overview/). -## Submit Job +!!!warning "Computational cost" + GW calculations are significantly more expensive than standard [GGA-DFT]({{ reference_url }}/models-directory/dft/parameters/#subtype). More [CPU cores and/or walltime]({{ resources_url }}/infrastructure/compute/parameters/) should be allocated as appropriate. -Before [submitting](../../../jobs/actions/run.md) the [job](../../../jobs/overview.md), the user should click on the ["Compute" tab](../../../jobs-designer/compute-tab.md) of [Job Designer](../../../jobs-designer/overview.md) and examine the [compute parameters](../../../infrastructure/compute/parameters.md) included therein. +!!!info "Parallelization for SternheimerGW" + In order to run SternheimerGW in parallel, the `k-point pools` value under [Advanced Options]({{ resources_url }}/infrastructure/compute/parameters/#advanced-options) must be set equal to the number of cores. G-vector parallelization is not implemented — only pool and image parallelization are available. -!!!warning "Computational Cost" - The computational cost of GW calculations is significantly higher than for more basic methods in [DFT](../../../models-directory/dft/overview.md) such as the [Generalized Gradient Approximation](../../../models-directory/dft/parameters.md#subtype). We thus recommend to allow for more [CPU cores and/or walltime](../../../infrastructure/compute/parameters.md) as appropriate for the material system under investigation. -In order to run the SternheimerGW code in parallel (more than 1 core), the user should set the `k-point pools` value under the ["Advanced Options"](../../../infrastructure/compute/parameters.md#advanced-options) of the "Compute" tab equal to the number of cores, otherwise, the calculation fails with a "G-vectors mismatch" error message. This is a result of the fact that G-vector parallelization is not implemented for SternheimerGW, and the only available parallelization levels are pools and images. +## 7. Examine the results -## Examine Final Results +Once both [units]({{ reference_url }}/workflows/components/units/) complete, the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) displays the [band structure]({{ reference_url }}/properties-directory/non-scalar/bandstructure/) of silicon along the Γ–X–W–K path. -When both [unit](../../../workflows/components/units.md) computations are complete at the end of Job execution, switching to the [Results tab](../../../jobs/ui/results-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md) will show the [band structure](../../../properties-directory/non-scalar/bandstructure.md) of silicon, plotted as a dispersion curve as a function of the special [k-point paths](../../../models/auxiliary-concepts/reciprocal-space/paths.md) chosen (the Gamma-X-W-K directions in our case). +The indirect band gap of ~1.05 eV is in good agreement with experiment. -We also note that the final result for the indirect band gap of silicon of 1.05 eV is in good agreement with the reported experimental value. +!!!note "Band gap measurement" + In this case, the band gap is calculated on the chosen Γ–X–W–K reciprocal path, not on the overall grid. -!!!note "Band gap result" - In this case, the band gap is calculated on the chosen Gamma-X-W-K reciprocal path, and not on the overall grid. -## Animation +## 8. Video walkthrough -We demonstrate the above-mentioned steps involved in the creation and execution of a GW band structure computation on crystalline silicon, using the [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) simulation engine together with the SternheimerGW code for enacting the full-frequency integration along the imaginary axis, in the following animation. +The animation below demonstrates the full workflow.
-## Links -[^1]: [SternheimerGW, Official Website](http://www.sternheimergw.org/) +## 9. Links +[^1]: [SternheimerGW, Official Website](http://www.sternheimergw.org/) [^2]: [M. Schlipf, H. Lambert, N. Zibouche, F. Giustino: "SternheimerGW: a program for calculating GW quasiparticle band structures and spectral functions without unoccupied states"; arXiv:1812.03717](https://arxiv.org/pdf/1812.03717.pdf) [^3]: [SternheimerGW, Official GitHub Repository](https://github.com/QEF/SternheimerGW) diff --git a/lang/en/docs/tutorials/dft/electronic/gw-qe-bs-plasmon.md b/lang/en/docs/tutorials/dft/electronic/gw-qe-bs-plasmon.md index f179c9d1a..40e57d65b 100644 --- a/lang/en/docs/tutorials/dft/electronic/gw-qe-bs-plasmon.md +++ b/lang/en/docs/tutorials/dft/electronic/gw-qe-bs-plasmon.md @@ -1,63 +1,58 @@ -# Calculate Electronic Band Structure with GW Approximation and Plasmon-pole Approach +# Calculate Electronic Band Structure with GW Approximation and Plasmon-Pole Approach -This page explains how to calculate the [electronic band structure](../../../properties-directory/non-scalar/bandstructure.md) based on [Density Functional Theory](../../../models-directory/dft/overview.md) and [GW Approximation](../../../models-directory/dft/notes.md#the-gw-approximation). We consider a hexagonal Boron Nitride (BN) monolayer [^1] as our sample material, and use [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md). +This tutorial explains how to calculate the [electronic band structure]({{ reference_url }}/properties-directory/non-scalar/bandstructure/) of a hexagonal boron nitride (BN) monolayer [^1] using the [GW Approximation]({{ reference_url }}/models-directory/dft/notes/#the-gw-approximation) with the **Godby–Needs plasmon-pole model** and [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/). -!!!note "Quantum ESPRESSO version considered in this tutorial" - The present tutorial is written for Quantum ESPRESSO at version(s) 6.3. +!!!note "Quantum ESPRESSO version" + This tutorial applies to Quantum ESPRESSO version 6.3 and later. -## Plasmon-pole Approximation +The plasmon-pole approach [^2] samples only at zero frequency and uses the Godby–Needs model along the imaginary axis. The method is enabled via the [SternheimerGW](gw-qe-bs-fullfreq.md#1-understand-the-sternheimergw-code) code. The [full-frequency integration tutorial](gw-qe-bs-fullfreq.md) provides a more complete introduction to GW workflows. Only plasmon-pole-specific aspects are covered below. -Here we employ of the **Plasmon pole** approach [^2] and only sample at zero frequency. We use a **Godby-Needs plasmon-pole model** along the imaginary axis. The plasmon-pole method is enabled within Quantum ESPRESSO via the [SternheimerGW](gw-qe-bs-fullfreq.md#the-sternheimergw-code) code. The user is referred to this latter link more more instructions on Quantum ESPRESSO-based GW Workflows in our platform. Only plasmon-pole-specific aspects of GW computations shall be explained in this page. -## Workflow Structure +## 1. Understand the plasmon-pole workflow
- Expand to view + Expand to view detailed input parameters -We shall now review the plasmon-pole-specific components of the input file for the second compute [unit](../../../workflows/components/units.md) (based on SternheimerGW), within the larger [Workflow](../../../workflows/overview.md) based upon the [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) modeling engine. +The plasmon-pole-specific components of the SternheimerGW input file include: -### Truncation +**Truncation:** For isotropic systems, a spherical truncation is used by default. For films and other anisotropic systems (such as the BN monolayer), "2d" truncation is recommended. The Wigner-Seitz (ws) truncation is more general but computationally expensive for larger systems. -If we do not specify a particular truncation (for both correlation and exchange) used to overcome the divergence of the Coulomb potential for small G vectors, a spherical truncation is employed. This relies on the system being somewhat isotropic. For films or other systems with strong anisotropy, the use of a spherical truncation is no longer appropriate. +**Linear solver configuration:** The `thres_coul` and `thres_green` values control solver accuracy. The `max_iter_coul` and `max_iter_green` values set iteration limits — if exceeded, a different solver is tried automatically. -For films, such as the example being presently considered, using a "2d" truncation is recommended. Even more general is the Wigner-Seitz (ws) truncation, limiting the Coulomb interaction to the actual simulation box. Note that the initial setup of the ws truncation is not parallelized, so it might be quite computationally expensive for larger systems. +**Plasmon-pole frequencies:** When using the Godby–Needs model, exactly two frequencies must be specified: -### Configuration of the Coulomb and Green solver +$$ +\omega_1 = 0 \qquad \omega_2 = \text{i} \omega_\text{p} +$$ -Using the values `thres_coul` and `thres_green`, the user can tweak the accuracy of the linear solver to optimize it for the system under investigation. `max_iter_coul` and `max_iter_green` allow the user to specify a maximum number of iterations, that the linear solver should try to converge upon. If this maximum is exceeded, the code will try a different linear solver. +These are used to construct an approximation of the screened Coulomb interaction. -### Configuration of W in the convolution +
-For comparison with other GW codes, SternheimerGW offers the possibility to evaluate the GW correction in the plasmon-pole (PP) model. When using the Godby-Needs PP model, the user must specify exactly the following two frequencies: -$$ -\omega_1 = 0 \qquad \omega_2 = \text{i} \omega_\text{p} -​​$$ +## 2. Create and submit the job -These two frequencies are then used to construct an approximation for the screened Coulomb interaction. +Follow the instructions in the [full-frequency GW tutorial](gw-qe-bs-fullfreq.md#3-create-the-job) for creating and executing the GW workflow job and inspecting results. -
+For this 2D material, the z-dimension of the k-grids and q-grid is set to 1. The recommended settings are: plane-wave cutoff of 80 Ry, k-grid of 8 × 8 × 1, and q-grid of 4 × 4 × 1. -## Create and Submit Job -The user should, at this point, follow the instructions included in the [alternative GW tutorial](gw-qe-bs-fullfreq.md#create-job) for explanations on how to create and execute a GW Workflow computational [Job](../../../jobs/overview.md), and on how to retrieve and inspect its corresponding results. +## 3. Examine the results -## Animation +The indirect band gap of the BN monolayer is ~6.460 eV, between the Γ and M Brillouin Zone special points. This result is in good agreement with other first-principles calculations [^3]. -We demonstrate the steps involved in the creation and execution of a GW band structure computation on a BN monolayer (in its hexagonal form), using the [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) simulation engine in the following animation. -Here, we set the size along the z dimension of the k-grids and q-grid to 1, since we are considering a 2D material. In summary, we use a plane-wave cutoff of 80 Ry, k-grids size of 8 x 8 x 1 and q-grid size of 4 x 4 x 1. +## 4. Video walkthrough -The final result for the indirect band gap of the BN monolayer of 6.460 eV, between the Gamma and M Brillouin Zone special points, is in good agreement with other first-principles calculations [^3]. +The animation below demonstrates the creation and execution of a GW band structure computation on a BN monolayer using Quantum ESPRESSO with the plasmon-pole model.
-## Links -[^1]: [Wikipedia Boron nitride nanosheet, Website](https://en.wikipedia.org/wiki/Boron_nitride_nanosheet) +## 5. Links +[^1]: [Wikipedia Boron nitride nanosheet](https://en.wikipedia.org/wiki/Boron_nitride_nanosheet) [^2]: [J. Lischner, S. Sharifzadeh, J. Deslippe, J.B. Neaton, and S.G. Louie: "Effects of self-consistency and plasmon-pole models on GW calculations for closed-shell molecules"; Phys. Rev. B 90, 115130 (2014)](https://arxiv.org/pdf/1409.2901.pdf) - [^3]: [D. Wickramaratne, L. Weston, and C.G. Van de Walle: "Monolayer to Bulk Properties of Hexagonal Boron Nitride"; J. Phys. Chem. C, 2018, 122 (44), pp 25524–25529](https://pubs.acs.org/doi/abs/10.1021/acs.jpcc.8b09087?journalCode=jpccck&) diff --git a/lang/en/docs/tutorials/dft/electronic/gw-vasp-bg.md b/lang/en/docs/tutorials/dft/electronic/gw-vasp-bg.md index 8a594705a..0c148c67f 100644 --- a/lang/en/docs/tutorials/dft/electronic/gw-vasp-bg.md +++ b/lang/en/docs/tutorials/dft/electronic/gw-vasp-bg.md @@ -1,68 +1,66 @@ # Calculate Electronic Band Gap with GW Approximation -This tutorial page explains how to calculate the [electronic band gap](../../../properties-directory/non-scalar/band-gaps.md) of a semiconducting material based on [Density Functional Theory](../../../models-directory/dft/overview.md). We consider crystalline silicon in its standard equilibrium cubic-diamond crystal structure, and use [VASP](../../../software-directory/modeling/vasp/overview.md) as our main simulation engine during this tutorial. +This tutorial explains how to calculate the [electronic band gap]({{ reference_url }}/properties-directory/non-scalar/band-gaps/) of crystalline silicon in its cubic-diamond crystal structure using the [GW Approximation]({{ reference_url }}/models-directory/dft/notes/#the-gw-approximation) with [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/). -!!!note "VASP version considered in this tutorial" - The present tutorial is written for VASP at versions 5.3.5 or 5.4.4. +!!!note "VASP version" + This tutorial applies to VASP versions 5.3.5, 5.4.4, and later. -What sets the present tutorial apart from the [other tutorial](band-gap.md) on band gap calculations is the employment of the **"GW Approximation"**, which is reviewed in [this part of the documentation](../../../models-directory/dft/notes.md#the-gw-approximation). This method is significantly slower than the conventional approach for computing electronic band gaps, however similarly to the [HSE method](hse-vasp-bg.md) it yields more accurate electronic band structure results which are closer to experimental values, thus rectifying the tendency of the [GGA to underestimate the size of the band gap](../../../models-directory/dft/notes.md#accuracy-limits-of-the-generalized-gradient-approximation). More information on this approximation, together with a demonstration of its application and results on a sample set of materials, can be found in Ref. [^1]. +The GW Approximation is significantly slower than standard DFT but yields more accurate band structures, rectifying the tendency of the [GGA to underestimate band gaps]({{ reference_url }}/models-directory/dft/notes/#accuracy-limits-of-the-generalized-gradient-approximation). Similarly to the [HSE method](hse-vasp-bg.md), the GW approach produces results much closer to experimental values. A demonstration of GW results on a sample set of materials is available in Ref. [^1]. -## Workflow Structure -We shall now describe the computational implementation of the GW Approximation for computing electronic band gaps on our platform, illustrating the various steps constituting the overall [Workflow](../../../workflows/overview.md). For the present explanation, we consider the example case of the [VASP](../../../software-directory/modeling/vasp/overview.md) modeling engine. Further information on how the GW method is supported by VASP can be retrieved in Refs. [^2] and [^3]. +## 1. Understand the GW workflow -Workflows performing GW calculations follow a three-step procedure: +The [workflow]({{ reference_url }}/workflows/overview/) for GW band gap calculations with [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) follows a three-step procedure [^2] [^3]: -### 1. Preliminary Ground State SCF Calculation +### 1.1. Preliminary ground-state SCF calculation -The first [subworkflow step](../../../workflows/components/subworkflows.md) in the overall GW Workflow is a standard self-consistent field (scf) total ground state energy calculation, providing the ensuing steps of the workflow with the wavefunctions of the material structure under investigation (GW calculations always require a one-electron basis set). +The first [subworkflow]({{ reference_url }}/workflows/components/subworkflows/) step is a standard self-consistent field (SCF) total ground-state energy calculation, providing the wavefunctions needed by subsequent steps. The [k-point grid]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) is set to 10 × 10 × 10 under [Important Settings]({{ interface_url }}/workflow-designer/subworkflow-editor/important-settings/). -For the sake of the present example, we can set the [grid of special k-points](../../../models/auxiliary-concepts/reciprocal-space/sampling.md) to 10 x 10 x 10, under [Important Settings](../../../workflow-designer/subworkflow-editor/important-settings.md). +### 1.2. Many-bands SCF calculation -### 2. Many Bands SCF Calculation +GW calculations require a significant number of empty bands. This is performed as a separate subworkflow: the `NBANDS` VASP tag is set to a large value to include many unoccupied orbitals. -A significant number of empty bands is required for GW calculations, such that it is typically better to perform the calculations in two steps, as two separate subworkflows: first the above-mentioned standard ground-state SCF calculation with only a few unoccupied orbitals, and secondly a calculation over a large number of unoccupied orbitals (bands), by setting the `NBANDS` VASP tag to a large value. +### 1.3. GW step -### 3. GW Step +The actual GW calculation is done in the final subworkflow. Different GW flavors are selected via the `ALGO` VASP tag. -The actual GW calculation is done in this final subworkflow step. Here different GW flavors are possible and are selected with the `ALGO` VASP tag. +The "Single Shot" quasi-particle energy method, commonly referred to as **G0W0**, is the simplest and most computationally efficient GW calculation. It computes quasi-particle energies from a single GW iteration by neglecting off-diagonal self-energy matrix elements and using a Taylor expansion around the DFT energies. -The "Single Shot" quasi-particle energies method, often referred to as **G0W0**, is the simplest GW calculation, and computationally the most efficient one. A single-shot calculation calculates the quasi-particle energies from a single GW iteration by neglecting all off-diagonal matrix elements of the self-energy, and employing a Taylor expansion of the self-energy around the DFT energies. +After a successful G0W0 run, VASP writes the quasi-particle energies into the main "OUTCAR" output file for every k-point in the Brillouin zone. -After a successful G0W0 run, VASP will write the quasi-particle energies into the main "OUTCAR" output file for every k-point in the Brillouin zone of the crystal structure under investigation. +!!!note "Grid-based approach" + In this example, quasi-particle energies are calculated on the k-point grid. Points on the grid may not fall exactly onto the band extrema, but this approach is robust and provides a reasonable approximation. Intelligent interpolation can be used to extract band dispersions along symmetry paths. -In the present example we calculate quasi-particle energies on the grid of k-points. This might not be the most accurate approach, as points on the grid might not fall exactly onto the band extrema for conduction and valence band, however, it is robust and can provide a very reasonable approximation. An intelligent interpolation technique might be used to further extract band dispersions along symmetry paths. -## Creating and Executing Job +## 2. Import the GW workflow from the bank -GW-based band gap calculation [workflows](../../../workflows/overview.md) can readily be [imported](../../../workflows/actions/copy-bank.md) into the account-owned [collection](../../../accounts/collections.md) from the [Workflows Bank](../../../workflows/bank.md), for example under the name "D1-GW0-BG". +GW band gap [workflows]({{ reference_url }}/workflows/overview/) can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/), for example under the name "D1-GW0-BG". !!!info "Workflow naming convention" - The "D1-GW0-BG" name for the GW workflow contains the following information: "D" refers to the difficulty level (see table II in Ref. [^1]), "GW0" represents the method, and "BG" is an abbreviation for the band gap. - -Apart from this, the same procedural instructions as in the [other band gap calculation tutorial](band-gap.md) should be followed for [creating and launching](../../../jobs-designer/overview.md) the corresponding GW-based electronic band gap [Job](../../../jobs/overview.md) through our [Web Interface](../../../ui/overview.md), and for inspecting the associated results. + The "D1-GW0-BG" name contains the following information: "D" refers to the difficulty level (see table II in Ref. [^1]), "GW0" represents the method, and "BG" is an abbreviation for band gap. -## Animation +The same procedural instructions as in the [band gap tutorial](band-gap.md) apply for creating and launching the job. -In the video animation below, we outline the procedure for creating and executing an electronic band gap calculation job via the GW Approximation, considering crystalline silicon as our example material and employing [VASP](../../../software-directory/modeling/vasp/overview.md) as the main simulation engine. We conclude by inspecting the corresponding results displayed under the [Results Tab](../../../jobs/ui/results-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md). -!!!tip "Computational cost of GW calculations" - GW calculations are in general quite computationally demanding. We therefore recommend the employment of at least 8 computing cores. For larger calculations, [OF queues](../../../infrastructure/resource/queues.md) will have faster turnaround than the OR queues considered in the video. +## 3. Video walkthrough + +The animation below demonstrates the procedure for creating and executing a GW band gap calculation on crystalline silicon using VASP. + +!!!tip "Computational cost" + GW calculations are computationally demanding. At least 8 computing cores are recommended. For larger calculations, [OF queues]({{ resources_url }}/infrastructure/resource/queues/) offer faster turnaround than OR queues.
-## Comparison with Experimental Value -The calculated value of 1.094 eV for the indirect band gap of silicon is in better agreement with the experimental value for this material (1.17 eV [^1]) than the alternative case of standard band gap calculations performed with the [Generalized Gradient Approximation](../../../models-directory/dft/notes.md#accuracy-limits-of-the-generalized-gradient-approximation) (GGA), whose shortcomings are assessed in [another tutorial page](band-gap.md). +## 4. Compare with experiment -This provides an example of how the GW Approximation can result in improved precision in the estimation of important material properties than more traditional approaches within [DFT](../../../models-directory/dft/overview.md). +The calculated value of ~1.094 eV for the indirect band gap of silicon is in better agreement with the experimental value of 1.17 eV [^1] than standard [GGA calculations](band-gap.md). This demonstrates how the GW Approximation provides improved accuracy for electronic structure predictions compared to traditional DFT approaches. -## Links -[^1]: [P. Das, M. Mohammadi, T. Bazhirov: "Accessible computational materials design with high fidelity and high throughput"; arXiv:1807.05623, 15 Jul 2018](https://arxiv.org/pdf/1807.05623.pdf) +## 5. Links +[^1]: [P. Das, M. Mohammadi, T. Bazhirov: "Accessible computational materials design with high fidelity and high throughput"; arXiv:1807.05623, 15 Jul 2018](https://arxiv.org/pdf/1807.05623.pdf) [^2]: [GW calculations, Official VASP Documentation](https://cms.mpi.univie.ac.at/wiki/index.php/GW_calculations) - [^3]: [Bandgap of Si in GW, Official VASP Documentation](https://cms.mpi.univie.ac.at/wiki/index.php/Bandgap_of_Si_in_GW) diff --git a/lang/en/docs/tutorials/dft/electronic/hse-qe-bg.md b/lang/en/docs/tutorials/dft/electronic/hse-qe-bg.md index 34103d859..b071168ca 100644 --- a/lang/en/docs/tutorials/dft/electronic/hse-qe-bg.md +++ b/lang/en/docs/tutorials/dft/electronic/hse-qe-bg.md @@ -1,58 +1,49 @@ # Band Gap and Density of States with Quantum ESPRESSO (HSE) -This tutorial page explains how to calculate the [electronic band gap](../../../properties-directory/non-scalar/band-gaps.md) and [Density of States](../../../properties-directory/non-scalar/electronic-dos.md) (DoS) of semiconducting [materials](../../../materials/overview.md) based on [Density Functional Theory](../../../models-directory/dft/overview.md). We consider crystalline silicon in its standard equilibrium cubic-diamond crystal structure, and use [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) as our main simulation engine during this tutorial. +This tutorial explains how to calculate the [electronic band gap]({{ reference_url }}/properties-directory/non-scalar/band-gaps/) and [Density of States]({{ reference_url }}/properties-directory/non-scalar/electronic-dos/) (DOS) of crystalline silicon in its cubic-diamond crystal structure using the **HSE (Heyd–Scuseria–Ernzerhof)** [hybrid functional]({{ reference_url }}/models-directory/dft/parameters/#hybrid-functionals) with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/). -!!!note "Quantum ESPRESSO version considered in this tutorial" - The present tutorial is written for Quantum ESPRESSO at versions 5.2.1, 5.4.0, 6.0.0 or 6.3. +!!!note "Quantum ESPRESSO version" + This tutorial applies to Quantum ESPRESSO versions 5.2.1, 5.4.0, 6.0.0, 6.3, and later. -We discuss in the present tutorial those aspects of the band gap and DoS calculation which are specific to the implementation of the **HSE (Heyd-Scuseria-Ernzerhof)** [exchange-correlation functional](../../../models-directory/dft/parameters.md#functional), a special class of [Hybrid Functionals](../../../models-directory/dft/parameters.md#hybrid-functionals). The increased [precision](../../../methods/precision.md) of Hybdrid Functionals in predicting [material properties](../../../properties/overview.md) of interest such as band gaps will hence be demonstrated. - -The instructions presented herein complement the general discussion introduced in a [separate tutorial](band-gap.md). The reader is referred to this latter page for an outline of the general procedure for band gap computations using DFT, whereas only HSE-specific aspects will be reviewed throughout the remainder of the present page. The reader is also invited to consult [this other tutorial](hse-qe-bs.md) for a more general review and introduction to HSE-based computations of electronic band structures using Quantum ESPRESSO. +The instructions here complement the general [band gap tutorial](band-gap.md) and the [HSE band structure tutorial](hse-qe-bs.md). Only HSE-specific aspects of the band gap and DOS calculation are covered below. -## Workflow for HSE Band Gap and DoS Calculation with Quantum ESPRESSO -Contrary to the case of [Quantum ESPRESSO-based HSE computations of the band structure](hse-qe-bs.md), in which the list of electronic k-points had to be extracted and then inserted manually within the main input script, in the present case where we limit ourselves to the computation of the band gap and DoS only, the [grid of special k-points](../../../models/auxiliary-concepts/reciprocal-space/sampling.md) can be defined automatically as customarily done in self-consistent field (scf) total ground-state energy computations. +## 1. Understand the HSE band gap workflow -Apart from this, the structure of the main Quantum ESPRESSO input script is essentially the same as for a general HSE-based band structure computation. The HSE-specific aspects and parameters of the scf calculation can be triggered by including the HSE [Refiner](../../../models-directory/dft/parameters.md#refiners), as set under the [Subworkflow Editor Interface](../../../workflow-designer/subworkflow-editor/overview-tab.md#refiners). +Unlike the [HSE band structure computation](hse-qe-bs.md), where k-points must be extracted and inserted manually, the band gap and DOS calculation uses a [k-point grid]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) defined automatically, as in a standard SCF calculation. -For band-gap computations, it is also essential to ensure that the corresponding "band_gaps" [property](../../../properties/overview.md) calculation option, available under the ["Detailed View" tab](../../../workflow-designer/subworkflow-editor/detailed-view.md) of the [Subworkflow Editor Interface](../../../workflow-designer/subworkflow-editor/overview-tab.md#refiners), gets ticked for selection before the beginning of Job execution. +The HSE-specific parameters are triggered by including the HSE [Refiner]({{ reference_url }}/models-directory/dft/parameters/#refiners), set under the [Subworkflow Editor Interface]({{ interface_url }}/workflow-designer/subworkflow-editor/overview-tab/#refiners). -### Main HSE Computation Unit +For band-gap computations, the "band_gaps" [property]({{ reference_url }}/properties/overview/) calculation option must be enabled under the [Detailed View tab]({{ interface_url }}/workflow-designer/subworkflow-editor/detailed-view/) of the Subworkflow Editor before job execution. -The [Workflow](../../../workflows/overview.md) for executing the HSE band gap and DoS calculation is contained within a single [Subworkflow](../../../workflows/components/subworkflows.md), itself comprising two [units](../../../workflows/components/units.md), the first one for executing the main HSE computation and the second one for extracting the DoS via the `projwfc.x` [Quantum ESPRESSO executable](../../../software-directory/modeling/quantum-espresso/components.md#executables). Except for the automatic generation of k-points, the Quantum ESPRESSO input script defined within the former unit conforms to the same general conventions of a HSE-based band structure computation such as outlined [in this other tutorial](hse-qe-bs.md). +### 1.1. Workflow units -### Size of the q-grid +The [workflow]({{ reference_url }}/workflows/overview/) contains a single [subworkflow]({{ reference_url }}/workflows/components/subworkflows/) with two [units]({{ reference_url }}/workflows/components/units/): the main HSE computation and the DOS extraction via the `projwfc.x` [executable]({{ reference_url }}/software-directory/modeling/quantum-espresso/components/#executables). -It is nevertheless crucial, in order to obtain an accurate numerical estimate of the band gap size, to have a sufficiently large three-dimensional mesh for the q (k1-k2) sampling of the Fock operator, as defined through the "nqx1, nqx2, nqx3" input keywords within the Quantum ESPRESSO input script. This "q-grid" size has to be a divisor of the k-grid size, and for the sake of the present tutorial we recommend setting the k-grid dimensions to 8x8x8 and the q-grid to 4x4x4 for example, as can be set under the ["Important Settings" tab](../../../workflow-designer/subworkflow-editor/important-settings.md) of the [Subworkflow Editor interface](../../../workflow-designer/subworkflow-editor/overview.md). +### 1.2. Configure the q-grid -#### Restrictions on kgrid size +An accurate band gap estimate requires a sufficiently large q-grid (k1-k2 mesh for the Fock operator), defined via the `nqx1`, `nqx2`, `nqx3` input keywords. The q-grid must be a divisor of the k-grid. For this tutorial, the recommended setting is a k-grid of 8 × 8 × 8 with a q-grid of 4 × 4 × 4, configurable under the [Important Settings tab]({{ interface_url }}/workflow-designer/subworkflow-editor/important-settings/) of the Subworkflow Editor. -The user is advised that the default settings in the HSE band gap computation workflow are such that **the q-grid is set to be half the size of the kgrid** entered by the user. Hence an **even kgrid size** is always required, for example 8x8x8 yielding a q-grid of dimensions 4x4x4. - - Should the user enter an odd number for the kgrid dimensions by mistake, this size will automatically be increased by one in the workflow to make it even: for example, a 5x5x5 kgrid size entered by the user is increased to 6x6x6 by the workflow operations, thus resulting in a 3x3x3 q-grid. - - In order to change this default behaviour, the user is invited to manually edit the Quantum ESPRESSO input script for the main HSE calculation directly through the corresponding [unit editor interface](../../../workflow-designer/unit-editor.md), within its [input script template](../../../workflow-designer/unit-editor/input-templates.md). +!!!info "Even k-grid sizes required" + The default HSE workflow sets the q-grid to half the k-grid size, so an **even k-grid size** is always required. If an odd number is entered, it is automatically increased by one (e.g. 5 × 5 × 5 → 6 × 6 × 6, yielding a 3 × 3 × 3 q-grid). This behavior can be overridden by editing the input script directly through the [unit editor]({{ interface_url }}/workflow-designer/unit-editor/). -### Estimated Computational Cost -The user is welcome to explore how the precision of the final band gap result depends on the choice of such grid size parameters, within the limits of the computational resources at his disposal. +## 2. Import the HSE workflow from the bank -The aforementioned recommended choice of grid dimensions however already constitutes a significant computational cost, requiring an estimated execution time of about 20-30 minutes on 16 CPU cores, but presents the advantage of yielding an appreciably accurate final result for the size of the silicon band gap, as explained later in the present tutorial. +[Workflows]({{ reference_url }}/workflows/overview/) for the HSE band gap and DOS calculation with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/). The workflow can then be [selected]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) and added to the [job being created]({{ interface_url }}/jobs-designer/overview/). -## Copy HSE Workflow from Bank +!!!warning "Computational cost" + The recommended grid dimensions require approximately 20–30 minutes on 16 CPU cores. HSE calculations are significantly more expensive than standard [GGA-DFT]({{ reference_url }}/models-directory/dft/parameters/#subtype). More [CPU cores and/or walltime]({{ resources_url }}/infrastructure/compute/parameters/) should be allocated as appropriate. -[Workflows](../../../workflows/overview.md) for calculating the [electronic band gap](../../../properties-directory/non-scalar/band-gaps.md) and [Density of States](../../../properties-directory/non-scalar/electronic-dos.md) of semiconducting [materials](../../../materials/overview.md) with [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) via the HSE approach being presently considered can readily be [imported](../../../workflows/actions/copy-bank.md) from the [Workflows Bank](../../../workflows/bank.md) into the account-owned [collection](../../../accounts/collections.md). -This workflow can later be [selected](../../../jobs-designer/actions-header-menu/select-workflow.md) and added to the [Job being created](../../../jobs-designer/overview.md). The same procedure as in the [general band-gap computation tutorial](band-gap.md) can otherwise be followed. +## 3. Examine the results -!!!warning "Computational Cost" - The computational cost of HSE calculations is significantly higher than for more basic methods in [DFT](../../../models-directory/dft/overview.md) such as the [Generalized Gradient Approximation](../../../models-directory/dft/parameters.md#subtype). We thus recommend to allow for more [CPU cores and/or walltime](../../../infrastructure/compute/parameters.md) as appropriate for the material system under investigation. - -## Animation +The final result of ~1.193 eV for the indirect band gap of silicon is in excellent agreement with the experimental zero-temperature value of 1.17 eV. HSE provides a marked improvement in band gap accuracy compared to the [Generalized Gradient Approximation]({{ reference_url }}/models-directory/dft/notes/#accuracy-limits-of-the-generalized-gradient-approximation), which significantly underestimates band gaps. -We demonstrate the steps involved in the creation and execution of a HSE Band Gap and DoS computation workflow on silicon, using the [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) simulation engine, in the following animation. We conclude by inspecting the final numerical result for the size of the indirect band gap of silicon under the ["Results" Tab](../../../jobs/ui/results-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md). -The final result of 1.193 eV is in excellent agreement with the value at zero temperature quoted in the literature of 1.17 eV. Thus, HSE provides a marked improvement in the accuracy of band gap estimations compared to more traditional approaches in DFT such as the [Generalized Gradient Approximation](../../../models-directory/dft/parameters.md#subtype), which is known on the other hand to significantly underestimate the size of band gaps as discussed [elsewhere](../../../models-directory/dft/notes.md#accuracy-limits-of-the-generalized-gradient-approximation). +## 4. Video walkthrough + +The animation below demonstrates the creation and execution of the HSE band gap and DOS workflow on silicon using Quantum ESPRESSO, concluding with the numerical result in the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/).
diff --git a/lang/en/docs/tutorials/dft/electronic/hse-qe-bs.md b/lang/en/docs/tutorials/dft/electronic/hse-qe-bs.md index a307c6321..0dfffa35f 100644 --- a/lang/en/docs/tutorials/dft/electronic/hse-qe-bs.md +++ b/lang/en/docs/tutorials/dft/electronic/hse-qe-bs.md @@ -1,76 +1,62 @@ # Band Structure with Quantum ESPRESSO (HSE) -This tutorial page explains how to calculate the [electronic band structure](../../../properties-directory/non-scalar/bandstructure.md) based on [Density Functional Theory](../../../models-directory/dft/overview.md). We will be studying crystalline Silicon in the standard cubic-diamond crystal structure, and we will use [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) as our simulation engine. +This tutorial explains how to calculate the [electronic band structure]({{ reference_url }}/properties-directory/non-scalar/bandstructure/) of crystalline silicon in its cubic-diamond crystal structure using the **HSE (Heyd–Scuseria–Ernzerhof)** [hybrid functional]({{ reference_url }}/models-directory/dft/parameters/#hybrid-functionals) with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/). -!!!note "Quantum ESPRESSO version considered in this tutorial" - The present tutorial is written for Quantum ESPRESSO at versions 5.2.1, 5.4.0, 6.0.0 or 6.3. +!!!note "Quantum ESPRESSO version" + This tutorial applies to Quantum ESPRESSO versions 5.2.1, 5.4.0, 6.0.0, 6.3, and later. -We discuss in the present tutorial those aspects of the band structure calculation which are specific to the implementation of the **HSE (Heyd-Scuseria-Ernzerhof)** [exchange-correlation functional](../../../models-directory/dft/parameters.md#functional), a special class of [Hybrid Functionals](../../../models-directory/dft/parameters.md#hybrid-functionals). - -The instructions presented herein complement the general discussion introduced in a [separate tutorial](band-structure.md). The reader is referred to this latter page for an outline of the general procedure for band structure computations using DFT as performed on our platform, whereas only HSE-specific aspects will be reviewed throughout the remainder of the present page. +The instructions here complement the general [band structure tutorial](band-structure.md). Only HSE-specific aspects are covered below. -## Workflow for HSE Calculation with Quantum ESPRESSO -A Quantum ESPRESSO [Workflow](../../../workflows/overview.md) to compute the band structure of [materials](../../../materials/overview.md) using HSE is composed of the following [subworkflow](../../../workflows/components/subworkflows.md) steps. +## 1. Understand the HSE workflow -### 1. Preliminary SCF Calculation +A Quantum ESPRESSO [workflow]({{ reference_url }}/workflows/overview/) for computing the band structure with HSE is composed of three [subworkflow]({{ reference_url }}/workflows/components/subworkflows/) steps: -The first subworkflow step involves a standard self-consistent field (scf) calculation of the ground-state energy eigenvalues and wave functions. This is necessary for defining the [grid of k-points](../../../models/auxiliary-concepts/reciprocal-space/sampling.md), which will later be extracted manually in the subsequent step. +### 1.1. Preliminary SCF calculation -### 2. Manual Extraction of k-points +The first step is a standard self-consistent field (SCF) calculation of the ground-state energy eigenvalues and wave functions. This provides the [k-point grid]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) that is manually extracted in the next step. -The traditional approach for computing the band structure in Quantum ESPRESSO, outlined in [this separate tutorial](band-structure.md), would have proceeded via a non self-consistent calculation using the wave functions and charge density of the previous scf calculation. However, within the HSE approach towards achieving the same objective, in order to get the Fock operator [^1] [^2] at a certain k-point, one requires the wavefunctions on a grid that is commensurate with it, and this can only be done self-consistently. +### 1.2. Extract k-points -A way around this problem is to manually extract the k-points generated automatically in the preceding step, together with their respective weights, and insert them individually as an explicit list inside the input script for the final HSE calculation described next. +Unlike the standard [band structure calculation](band-structure.md), which proceeds via a non-self-consistent calculation, the HSE approach requires self-consistent evaluation of the Fock operator [^1] [^2] at each k-point on a commensurate grid. -The procedure to manually extract the k-points from the output of the previous scf calculation is performed automatically in the present subworkflow step via a [Python script](../../../software-directory/scripting/python/overview.md). This script extracts the list of k-points with their corresponding weights within the list under consideration, with the help of [Regular Expressions](../../../methods-directory/pseudopotential/actions.md#regular-expressions) (commonly referred to as "regex"). The resulting output is finally printed out as a JSON file. +The k-points generated in the SCF step are automatically extracted via a [Python script]({{ reference_url }}/software-directory/scripting/python/overview/) that uses [Regular Expressions]({{ reference_url }}/methods-directory/pseudopotential/actions/#regular-expressions) to parse the output. The resulting list is saved as a JSON file for use in the next step. -### 3. HSE Calculation +### 1.3. HSE calculation -The final subworkflow step in the HSE band structure computation workflow is composed of two units. The main HSE calculation is performed in the first one of these units. Apart from the specific elements described in what follows, the remainder of the main HSE input script conforms to the general standard conventions of an scf ground-state total energy calculation performed with Quantum ESPRESSO via its ["pw_scf" flavor](../../../software-directory/modeling/quantum-espresso/components.md#flavors), as implemented on our platform. The HSE-specific aspects and parameters of the scf calculation described below can be triggered by including the HSE [Refiner](../../../models-directory/dft/parameters.md#refiners), as set under the [Subworkflow Editor Interface](../../../workflow-designer/subworkflow-editor/overview-tab.md#refiners). +The final step contains two units. The main HSE calculation is performed in the first unit. HSE-specific parameters are triggered by including the HSE [Refiner]({{ reference_url }}/models-directory/dft/parameters/#refiners), set under the [Subworkflow Editor]({{ interface_url }}/workflow-designer/subworkflow-editor/overview-tab/#refiners). -#### Selecting the HSE Exchange-correlation Functional +Key aspects of the HSE input configuration: -The HSE method is activated via the addition of the `input_dft = 'hse'` input parameter within the main Quantum ESPRESSO input script, for explicitly selecting the HSE Exchange-correlation functional. - -#### Defining the q-sampling of the Fock Operator - -A second set of important input parameters in the context of HSE consists in the "nqx1, nqx2, nqx3" keywords. These parameters define the three-dimensional mesh for the q (k1-k2) sampling of the Fock operator. For basic bandstructure calculations such as those being considered in the present tutorial, these three mesh parameters can all be left to a size of one. However for an accurate estimate of the size of the band gap, such as narrated in a [separate tutorial](hse-qe-bg.md), a higher value for this q-mesh size should be considered and tested, which drastically improves the precision of the band structure computation at the price of a significantly higher computational cost. +- **Exchange-correlation functional:** Activated via `input_dft = 'hse'` in the Quantum ESPRESSO input script. +- **q-grid for the Fock operator:** Defined via `nqx1`, `nqx2`, `nqx3`. For basic band structure calculations, a size of 1 is sufficient. For accurate band gap estimates, see the [HSE band gap tutorial](hse-qe-bg.md). +- **k-point list:** Imported from the extracted JSON rather than auto-generated. +- **k-path:** A second list of k-points defining the [path]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/paths/) for the band structure dispersion curve, customizable under [Important Settings]({{ interface_url }}/workflow-designer/subworkflow-editor/important-settings/). -#### Inserting the List of k-points +!!!note "Weight of k-path points" + The k-path points are assigned very small weights (<1e-7) so they do not interfere with the HSE electronic structure computation — they are only needed for plotting the dispersion curve. The weights are not exactly zero because Quantum ESPRESSO requires non-zero values. -Another aspect of the main HSE calculation unit worth noticing is how the grid of special [k-points](../../../models/auxiliary-concepts/reciprocal-space/sampling.md) is not generated automatically, as customarily done in ground state scf computations, but rather is defined manually in crystal coordinates by importing the list of k-points extracted in the preceding subworkflow. - -#### Specifying the k-path +The final band structure is computed via the [bands.x executable]({{ reference_url }}/software-directory/modeling/quantum-espresso/components/#executables). -In addition to this list of k-points for sampling the Brillouin Zone of the crystal over a regular grid, a second list of k-points needs to be provided and inserted manually at the bottom of the Quantum ESPRESSO input script, consisting in the [path of k-points](../../../models/auxiliary-concepts/reciprocal-space/paths.md) to be followed across the Brillouin Zone for plotting the final band structure dispersion curves. This k-path can be customized by the user under the ["Important Settings" tab](../../../workflow-designer/subworkflow-editor/important-settings.md) of the [Subworkflow Editor interface](../../../workflow-designer/subworkflow-editor/overview.md). -!!!note "Weight of the k-path points" - It should be noticed that the reciprocal coordinates of these k-points along the path under consideration are inserted with a **very small weight** (less than 1e-7), as opposed to the k-grid points which are instead entered with their normal weights. This is done to ensure that the k-path points do not interfere with the HSE electronic structure computation itself, since they are only needed for defining and plotting the final band structure dispersion curve. Such weights are not set to exactly zero in order for them to be applied correctly by Quantum ESPRESSO. +## 2. Import the HSE workflow from the bank -#### Calculating the Final Band Structure +[Workflows]({{ reference_url }}/workflows/overview/) for the HSE band structure calculation with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/). The workflow can then be [selected]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) and added to the [job being created]({{ interface_url }}/jobs-designer/overview/). -The final band structure calculation based upon the results of the preceding steps is performed through the customary ["bands.x" executable](../../../software-directory/modeling/quantum-espresso/components.md#executables), a component of the Quantum ESPRESSO package distribution. +!!!warning "Computational cost" + HSE calculations are significantly more expensive than standard [GGA-DFT]({{ reference_url }}/models-directory/dft/parameters/#subtype). More [CPU cores and/or walltime]({{ resources_url }}/infrastructure/compute/parameters/) should be allocated as appropriate. -## Copy HSE Workflow from Bank -[Workflows](../../../workflows/overview.md) for calculating the [band structure](../../../properties-directory/non-scalar/bandstructure.md) of [materials](../../../materials/overview.md) with [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) via the HSE approach being presently described can readily be [imported](../../../workflows/actions/copy-bank.md) from the [Workflows Bank](../../../workflows/bank.md) into the account-owned [collection](../../../accounts/collections.md). +## 3. Video walkthrough -This workflow can later be [selected](../../../jobs-designer/actions-header-menu/select-workflow.md) and added to the [Job being created](../../../jobs-designer/overview.md). The same procedure as in the [general band-structure computation tutorial](band-structure.md) based on Quantum ESPRESSO can otherwise be followed. - -!!!warning "Computational Cost" - The computational cost of HSE calculations is significantly higher than for more basic methods in [DFT](../../../models-directory/dft/overview.md) such as the [Generalized Gradient Approximation](../../../models-directory/dft/parameters.md#subtype). We thus recommend to allow for more [CPU cores and/or walltime](../../../infrastructure/compute/parameters.md) as appropriate for the material system under investigation. - -## Animation - -We demonstrate the steps involved in the creation and execution of a HSE Band Structure computation workflow on silicon, using the [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) simulation engine, in the following animation. We conclude by inspecting the final band structure dispersion plot under the ["Results" Tab](../../../jobs/ui/results-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md). +The animation below demonstrates the creation and execution of an HSE band structure computation on silicon using Quantum ESPRESSO, concluding with the dispersion plot in the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/).
-## Links -[^1]: [Wikipedia Hartree-Fock method, Website](https://en.wikipedia.org/wiki/Hartree%E2%80%93Fock_method) +## 4. Links -[^2]: [Wikipedia Fock matrix, Website](https://en.wikipedia.org/wiki/Fock_matrix) +[^1]: [Wikipedia Hartree-Fock method](https://en.wikipedia.org/wiki/Hartree%E2%80%93Fock_method) +[^2]: [Wikipedia Fock matrix](https://en.wikipedia.org/wiki/Fock_matrix) diff --git a/lang/en/docs/tutorials/dft/electronic/hse-vasp-bg.md b/lang/en/docs/tutorials/dft/electronic/hse-vasp-bg.md index 44ef1459b..f4204ae6b 100644 --- a/lang/en/docs/tutorials/dft/electronic/hse-vasp-bg.md +++ b/lang/en/docs/tutorials/dft/electronic/hse-vasp-bg.md @@ -1,61 +1,57 @@ # Band Gap with VASP (HSE) -We discuss in the present tutorial those aspects of the calculation of [electronic structure properties](overview.md) which are specific to the implementation of the **HSE (Heyd-Scuseria-Ernzerhof)** [exchange-correlation functional](../../../models-directory/dft/parameters.md#functional), a special class of [Hybrid Functionals](../../../models-directory/dft/parameters.md#hybrid-functionals). +This tutorial covers the calculation of the [electronic band gap]({{ reference_url }}/properties-directory/non-scalar/band-gaps/) of crystalline silicon using the **HSE (Heyd–Scuseria–Ernzerhof)** [hybrid functional]({{ reference_url }}/models-directory/dft/parameters/#hybrid-functionals), as implemented in [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/). HSE provides significantly improved band gap accuracy compared to standard [DFT]({{ reference_url }}/models-directory/dft/overview/) calculations. -## Band Gap Calculations +!!!note "VASP version" + This tutorial applies to VASP versions 5.3.5, 5.4.4, and later. -Here, we will explain how to compute the [electronic band gap](../../../properties-directory/non-scalar/band-gaps.md) of crystalline silicon using the [VASP](../../../software-directory/modeling/vasp/overview.md) modeling engine. The increased [precision](../../../methods/precision.md) of Hybdrid Functionals in predicting [material properties](../../../properties/overview.md) of interest such as band gaps will hence be demonstrated. +The instructions presented here complement the general [band gap tutorial](band-gap.md). Only HSE-specific aspects are covered on this page. -!!!note "VASP version considered in this tutorial" - The present tutorial is written for VASP at versions 5.3.5 or 5.4.4. - -The instructions presented herein complement the general discussion introduced in a [separate tutorial](band-gap.md). The reader is referred to this latter page for an outline of the general procedure for band-gap computations using DFT, whereas only HSE-specific aspects will be reviewed throughout the remainder of the present page. -## Workflow for HSE Calculation with VASP +## 1. Understand the HSE workflow -Advanced instructions on how to perform an HSE band structure calculation using [VASP](../../../software-directory/modeling/vasp/overview.md) can be retrieved under Refs. [^1],[^2]. +The VASP [workflow]({{ reference_url }}/workflows/overview/) for computing the band gap with HSE is composed of the following [subworkflow]({{ reference_url }}/workflows/components/subworkflows/) steps: -For the sake of this brief introduction, it suffices to know that a VASP [Workflow](../../../workflows/overview.md) to compute the band-gap of semiconducting materials using HSE is composed of the following [subworkflow](../../../workflows/components/subworkflows.md) steps. +1. Standard self-consistent field (SCF) calculation of energy eigenvalues and wave functions, with the HSE [Refiner]({{ reference_url }}/models-directory/dft/parameters/#refiners) enabled under the [Subworkflow Editor]({{ interface_url }}/workflow-designer/subworkflow-editor/overview-tab/#refiners). +2. Self-consistent Hartree–Fock/HSE calculation, again with the HSE [Refiner]({{ reference_url }}/models-directory/dft/parameters/#refiners) activated. +3. Extraction of the [k-points]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) in the symmetry-irreducible wedge of the Brillouin Zone (IBZ). +4. Final HSE band structure computation, using the wave functions and charge density from the previous steps. -1. Standard self-consistent field (scf) calculation of the energy eigenvalues and wave functions, which includes the HSE [Refiner](../../../models-directory/dft/parameters.md#refiners) as set under the [Subworkflow Editor Interface](../../../workflow-designer/subworkflow-editor/overview-tab.md#refiners). +Advanced instructions for HSE band structure calculations with VASP are available in Refs. [^1] and [^2]. -2. Self-consistent Hartree-Fock/HSE calculation, again with the HSE [Refiner](../../../models-directory/dft/parameters.md#refiners) activated. -3. Extraction of the [k-points](../../../models/auxiliary-concepts/reciprocal-space/sampling.md) in the Symmetry-irreducible wedge of the Brillouin Zone (IBZ) in [reciprocal space](../../../models/auxiliary-concepts/reciprocal-space.md). +## 2. Import the HSE workflow from the bank -4. Final HSE band structure computation, using the wave functions and charge density calculated in the previous steps. - -## Copy HSE Workflow from Bank - -[Workflows](../../../workflows/overview.md) for calculating the [band gap](../../../properties-directory/non-scalar/band-gaps.md) through HSE, as implemented under [VASP](../../../software-directory/modeling/vasp/overview.md), can readily be [imported](../../../workflows/actions/copy-bank.md) from the [Workflows Bank](../../../workflows/bank.md) into the account-owned [collection](../../../accounts/collections.md). The user should [search](../../../entities-general/actions/search.md) for the string "D7-HSR-BS-BG-DOS" under the Workflows Bank dialog when looking for the relevant HSE-based band-gap workflow. +[Workflows]({{ reference_url }}/workflows/overview/) for calculating the [band gap]({{ reference_url }}/properties-directory/non-scalar/band-gaps/) through HSE with [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/). Search for the string "D7-HSR-BS-BG-DOS" when looking for the relevant workflow. !!!info "Workflow naming convention" - The "D7-HSR-BS-BG-DOS" name for the HSE workflow contains the following information: "D" refers to the difficulty level (see table II in Ref. 1 cited [in this page](gw-vasp-bg.md)), "HSR" represents the method, and "BS", "BG" and "DOS" are abbreviations for band structure, band gap, and density of states respectively. + The "D7-HSR-BS-BG-DOS" name contains the following information: "D" refers to the difficulty level (see table II in Ref. 1 cited [in this page](gw-vasp-bg.md)), "HSR" represents the method, and "BS", "BG", and "DOS" are abbreviations for band structure, band gap, and density of states respectively. -This workflow can later be [selected](../../../jobs-designer/actions-header-menu/select-workflow.md) and added to the [Job being created](../../../jobs-designer/overview.md). The same procedure as in the [general band-gap computation tutorial](band-gap.md) can otherwise be followed. +The workflow can then be [selected]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) and added to the [job being created]({{ interface_url }}/jobs-designer/overview/). The same general procedure as in the [band gap tutorial](band-gap.md) applies. -!!!warning "Computational Cost" - The computational cost of HSE calculations is significantly higher than for more basic methods in [DFT](../../../models-directory/dft/overview.md) such as the [Generalized Gradient Approximation](../../../models-directory/dft/parameters.md#subtype). We thus recommend to allow for more [CPU cores and/or walltime](../../../infrastructure/compute/parameters.md) as appropriate for the system under investigation. +!!!warning "Computational cost" + HSE calculations are significantly more expensive than standard [GGA-DFT]({{ reference_url }}/models-directory/dft/parameters/#subtype). More [CPU cores and/or walltime]({{ resources_url }}/infrastructure/compute/parameters/) should be allocated as appropriate. -## Examine results -When the computation is complete at the end of Job execution, switching to the [Results tab](../../../jobs/ui/results-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md) will show the results of the simulation, including the indirect band gap found for silicon of around 1.14 eV. +## 3. Examine the results -### Comparison with Experimental Value +Once the computation completes, the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) displays the simulation results, including the indirect band gap of silicon (~1.14 eV). -The calculated value of 1.14 eV for the indirect band gap of silicon is in much better agreement with the experimental value for this material (1.17 eV [^3]) than the alternative case of the [Generalized Gradient Approximation](../../../models-directory/dft/notes.md#accuracy-limits-of-the-generalized-gradient-approximation) (GGA), whose shortcomings are assessed in the [other tutorial page](band-gap.md). +### 3.1. Compare with experiment -This provides an example of how HSE can result in improved precision in the estimation of important material properties than more traditional approaches within [DFT](../../../models-directory/dft/overview.md). +The calculated HSE value of ~1.14 eV is in excellent agreement with the experimental value of 1.17 eV [^3], a significant improvement over the GGA result of ~0.6 eV (see the [standard band gap tutorial](band-gap.md)). This demonstrates how hybrid functionals can yield more accurate electronic structure predictions. -## Animation -We demonstrate the steps involved in the creation and execution of a HSE Band Gap computation workflow on silicon, using the [VASP](../../../software-directory/modeling/vasp/overview.md) simulation engine, in the following animation. +## 4. Video walkthrough + +The animation below demonstrates the steps involved in the creation and execution of an HSE band gap computation on silicon using VASP.
-## Links + +## 5. Links [^1]: [Hartree-Fock (HF) type and hybrid functional calculations, Official VASP Manual](https://cms.mpi.univie.ac.at/vasp/vasp/Hartree_Fock_HF_type_hybrid_functional_calculations.html) [^2]: [Si HSE bandstructure, VASP Wiki Tutorial](https://cms.mpi.univie.ac.at/wiki/index.php/Si_HSE_bandstructure) diff --git a/lang/en/docs/tutorials/dft/electronic/hubbard.md b/lang/en/docs/tutorials/dft/electronic/hubbard.md index bb6763c18..932329de2 100644 --- a/lang/en/docs/tutorials/dft/electronic/hubbard.md +++ b/lang/en/docs/tutorials/dft/electronic/hubbard.md @@ -1,108 +1,79 @@ -# DFT+U and Hubbard parameter calculation in Quantum Espresso +# DFT+U and Hubbard Parameter Calculation in Quantum ESPRESSO -In this tutorial, we demonstrate how to perform DFT+U calculation, followed by -calculation of Hubbard parameters using Quantum Espresso on our web platform. +This tutorial demonstrates how to perform a DFT+U calculation followed by the computation of Hubbard parameters from first principles, using Quantum ESPRESSO on the Mat3ra platform. -## Create DFT+U workflow -First, we need to create PWscf workflow with DFT+U enabled. +## 1. Create the DFT+U workflow -### Add pw.x unit +A self-consistent DFT+U calculation (using `pw.x`) is a prerequisite for the Hubbard parameter calculation (using `hp.x`). -A PWscf calculation -(using `pw.x`) is a prerequisite for the Hubbard parameter (using `hp.x`) calculation. +### 1.1. Add the pw.x unit -- Navigate to the workflows page from the sidebar and create a new workflow. Expand -details section and select Quantum Espresso version `7.2` from the drop-down. +Navigate to the workflows page from the sidebar and create a new workflow. Expand the details section and select Quantum ESPRESSO version `7.2` from the drop-down. ![Navigation sidebar](../../../images/tutorials/hubbard/hubbard-01-navigation-sidebar.webp "Navigation sidebar") ![Select application version and build](../../../images/tutorials/hubbard/hubbard-02-select-ver-build.webp "Select application version and build") -- Click **Edit** button on the default **pw_scf** workflow unit. Expand the details -pane in the unit modal, and select **pw_scf_dft_u** flavor/ template. Close the -unit modal. +Click the **Edit** button on the default **pw_scf** workflow unit. Expand the details pane in the unit modal and select the **pw_scf_dft_u** flavor/template. Close the unit modal. ![Select executable and flavor](../../../images/tutorials/hubbard/hubbard-03-select-executable-flavor.webp "Select executable and flavor") -!!!warning - Here we follow the latest DFT+U syntax and method introduced in Quantum - Espresso version `7.1`. The new template (syntax) **pw_scf_dft_u** is only - available to Quantum Espresso version `7.1` or above. If the user would like - to use old syntax, please select Quantum Espresso version `7.0` or below - and use **pw_scf_dft_u_legacy**. +!!!warning "DFT+U syntax versions" + This tutorial follows the DFT+U syntax and method introduced in Quantum ESPRESSO version `7.1`. The **pw_scf_dft_u** template is only available in version `7.1` or above. For the legacy syntax, select Quantum ESPRESSO version `7.0` or below and use **pw_scf_dft_u_legacy**. +### 1.2. Add the hp.x unit -### Add hp.x unit to the workflow +Hubbard parameters can be obtained from first principles using the `hp.x` implementation of Linear Response theory [^1]. -Hubbard parameters can be obtained from the *first principles*. We will use -Quantum Espresso `hp.x` implementation of Linear Response theorem[^1]. - -We can add the `hp.x` workflow to the previous PWscf (DFT+U) workflow by adding a new -execution unit. Click the edit unit button on the second unit, and select `hp.x` -executable. The `q`-grid for `hp.x` can be modified in the important settings -tab. +Add a new execution unit to the workflow by clicking the edit unit button on the second unit and selecting the `hp.x` executable. The `q`-grid for `hp.x` can be modified in the *Important Settings* tab. ![Add new unit](../../../images/tutorials/hubbard/hubbard-04-add-new-unit.webp "Add new unit") -!!!tip - We have a bank workflow **Hubbard U - HP** incorporating above two steps. - Navigate to Bank Workflows page via left sidebar and search for - *Hubbard U - HP* workflow, and copy/clone it to your account. Then you may - further modify (as necessary) and use it. +!!!tip "Bank workflow available" + A pre-built **Hubbard U - HP** bank workflow incorporating both steps above is available. Navigate to the *Bank Workflows* page via the left sidebar, search for *Hubbard U - HP*, and copy it to the account. -## Create and submit job +## 2. Create and submit the job -After the above: +Navigate to the jobs page via the sidebar menu and create a new job. Then: -- Navigate to the jobs page via the sidebar menu and create a new job. -- Select material. Here, we have selected FeO. You can import new material from -banks or upload structure files. -- Select workflow, here, we select the Hubbard workflow that we just created. +- Select the material (FeO in this example — new materials can be imported from banks or uploaded as structure files). +- Select the Hubbard workflow created in the previous step. ![Select material and workflow](../../../images/tutorials/hubbard/hubbard-05-select-mat-workflow.webp "Select material and workflow") -- Navigate to **Important Settings** tab, and scroll down to **hubbard** -section. Here we are able to specify the Hubbard U values specific to atomic -species and orbital (Hubbard manifold). You can add new or delete a row in the -Hubbard card. +### 2.1. Configure the Hubbard card + +Navigate to the *Important Settings* tab under the workflow and scroll down to the **hubbard** section. Hubbard U values specific to atomic species and orbital (Hubbard manifold) can be specified here. Rows can be added or deleted as needed. ![Important settings](../../../images/tutorials/hubbard/hubbard-06-imp-settings.webp "Important settings") ![Edit Hubbard card](../../../images/tutorials/hubbard/hubbard-07-card-values.webp "Edit Hubbard card") -- Go to **Compute** tab, and select the number of processors and other compute -parameters. +### 2.2. Set compute parameters -![Set compute parameters](../../../images/tutorials/hubbard/hubbard-08-compute-parameters.webp "Set compute parameters") +Navigate to the *Compute* tab and select the number of processors and other compute parameters. -!!!warning - As of 20/Dec/2023, there is a bug in our platform that prevents running MPI - jobs in a single processor when the Intel (default) build of Quantum - ESPRESSO is used. Please select at least two processors/ cores when using - Intel build as a workaround. Alternatively, you may use the GNU build of - Quantum ESPRESSO. +![Set compute parameters](../../../images/tutorials/hubbard/hubbard-08-compute-parameters.webp "Set compute parameters") - **Update (18-Feb-2024):** The above MPI bug is resolved in platform version - `2024.2.15`. Now user may run MPI jobs on a single processor when using - Intel build of Quantum ESPRESSO. -- Now, we are ready to submit the job for running the calculation. +## 3. Examine the results ![Results](../../../images/tutorials/hubbard/hubbard-09-result.webp "Results") -Once the job is finished, the Hubbard U values are shown in the **Results** tab. +Once the job completes, the calculated Hubbard U values are displayed in the *Results* tab. + -## Step-by-step screenshare video +## 4. Video walkthrough -In the below animation, we go through an example calculation. +The animation below demonstrates the full calculation workflow.
- +
-## References +## 5. References [^1]: [HP – A code for the calculation of Hubbard parameters using density-functional perturbation theory, I. Timrov, N. Marzari, M. Cococcioni, Computer Physics Communications, **279**, 108455 (2022)](https://doi.org/10.1016/j.cpc.2022.108455). diff --git a/lang/en/docs/tutorials/dft/electronic/overview.md b/lang/en/docs/tutorials/dft/electronic/overview.md index 6cc680293..418218dbb 100644 --- a/lang/en/docs/tutorials/dft/electronic/overview.md +++ b/lang/en/docs/tutorials/dft/electronic/overview.md @@ -1,55 +1,39 @@ # Electronic Properties Tutorials -In the present section, we introduce the most common operations supported on our platform for performing **electronic structure** computations on materials, implemented through the [Density Functional Theory model](../../../models-directory/dft/overview.md). +This section covers electronic structure calculations on the Mat3ra platform, implemented through [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT). The tutorials demonstrate how to compute band structures, band gaps, density of states, and related properties using [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) and [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/). -## [Band Structure](band-structure.md) -We review the procedure for computing the [electronic band structure](../../../properties-directory/non-scalar/bandstructure.md) of crystalline samples [in this tutorial](band-structure.md). +## Standard DFT Calculations -## [Band Gap](band-gap.md) +| Tutorial | Property | Software | +|----------|----------|----------| +| [Band structure](band-structure.md) | [Electronic band structure]({{ reference_url }}/properties-directory/non-scalar/bandstructure/) | QE | +| [Band gap](band-gap.md) | [Band gap]({{ reference_url }}/properties-directory/non-scalar/band-gaps/) | VASP | +| [Density of states](density-of-states.md) | [Electronic DOS]({{ reference_url }}/properties-directory/non-scalar/electronic-dos/) | QE | +| [Charge density mesh](electronic-density-mesh.md) | Charge density | QE | +| [Fermi surface](fermi-surface.md) | [Fermi surface]({{ reference_url }}/properties-directory/scalar/fermi-energy/) | QE | +| [Valence band offset](valence-band-offset.md) | [Valence band offset]({{ reference_url }}/properties-directory/scalar/valence-band-offset/) | QE | +| [Effective screening medium](esm-qe.md) | ESM potential/charge profiles | QE | -The calculation of the [band gap](../../../properties-directory/non-scalar/band-gaps.md) is explained [here](band-gap.md). -## [Density of States](density-of-states.md) +## Beyond Standard DFT -We also offer instructions on how to evaluate the [electronic Density of States](../../../properties-directory/non-scalar/electronic-dos.md) under [this other tutorial page](density-of-states.md). +These tutorials use advanced functionals or many-body methods for improved accuracy, particularly for band gap predictions. -## [Charge Density Mesh](electronic-density-mesh.md) +| Tutorial | Method | Software | +|----------|--------|----------| +| [HSE band gap (VASP)](hse-vasp-bg.md) | Hybrid HSE functional | VASP | +| [HSE band gap (QE)](hse-qe-bg.md) | Hybrid HSE functional | QE | +| [HSE band structure (QE)](hse-qe-bs.md) | Hybrid HSE functional | QE | +| [GW band gap (VASP)](gw-vasp-bg.md) | [GW approximation]({{ reference_url }}/models-directory/dft/notes/#the-gw-approximation) | VASP | +| [GW band structure, full freq. (QE)](gw-qe-bs-fullfreq.md) | GW full frequency | QE | +| [GW band structure, plasmon pole (QE)](gw-qe-bs-plasmon.md) | GW plasmon pole | QE | -Finally, we conclude our review of the electronic properties of materials by covering [a tutorial page](electronic-density-mesh.md) dedicated to the computation of the Electronic Charge Density Mesh. -## [Fermi Surface](fermi-surface.md) +## Spin and Magnetic Properties -We review the steps involved in the calculation and visualization of the [Fermi Surface](../../../properties-directory/scalar/fermi-energy.md) of metallic crystalline samples such as copper [under this page](fermi-surface.md). - -## [HSE Calculations](hse-vasp-bg.md) - -[In other tutorial](hse-vasp-bg.md), we demonstrate how the use of the hybrid HSE functional can yield more accurate results for the example case of a band-gap computation with [VASP](../../../software-directory/modeling/vasp/overview.md). - -A similar Band Gap calculation with Quantum ESPRESSO is [available here](hse-qe-bg.md). And for the Band Structure - in [this tutorial](hse-qe-bs.md). - -## GW Calculations - -This [tutorial](gw-vasp-bg.md) illustrates how the results for the Band Gap can be more accurate through the use of the [GW Approximation](../../../models-directory/dft/notes.md#the-gw-approximation). - -## Valence Band Offset - -We show how to calculate the [valence band offset](../../../properties-directory/scalar/valence-band-offset.md) for a -heterostructure using the potential lineup method in [this tutorial](valence-band-offset.md). - -## DFT+U calculation and Hubbard Parameters - -In [this tutorial](hubbard.md) we show how to perform DFT+U calculation in -Quantum Espresso. We also show calculation of Hubbard parameters from the -*first principles*. - -## Spin-magnetic bandstructure calculation - -[This tutorial](spin-magnetic-qe.md) describes spin-magnetic bandstructure -calculation of nickel using Quantum Espresso. - -## Spin-orbit coupling calculation using QE - -In [this tutorial](spin-orbit-coupling-qe.md), we present bandstructure -calculation of topological insulating Bi2Se3 with -incorporating spin-orbit coupling effect using Quantum ESPRESSO. +| Tutorial | Method | Software | +|----------|--------|----------| +| [Hubbard U correction](hubbard.md) | DFT+U | QE | +| [Spin-magnetic band structure](spin-magnetic-qe.md) | Spin-polarized DFT | QE | +| [Spin-orbit coupling](spin-orbit-coupling-qe.md) | SOC | QE | diff --git a/lang/en/docs/tutorials/dft/electronic/spin-magnetic-qe.md b/lang/en/docs/tutorials/dft/electronic/spin-magnetic-qe.md index 9cc9c5db6..e1781a9c2 100644 --- a/lang/en/docs/tutorials/dft/electronic/spin-magnetic-qe.md +++ b/lang/en/docs/tutorials/dft/electronic/spin-magnetic-qe.md @@ -1,108 +1,81 @@ -# Spin-magnetic calculation in Quantum ESPRESSO +# Spin-Magnetic Band Structure Calculation in Quantum ESPRESSO -In this tutorial, we walk you through the steps of spin magnetic bandstructure -calculation using Quantum Espresso on our web platform. +This tutorial demonstrates how to perform a spin-polarized band structure calculation using Quantum ESPRESSO on the Mat3ra platform. -## 1. Specify material structure -First of all, to perform material simulation, we need to specify the -material structure. We can create a new material on our platform using -**Materials Designer**. Alternatively, we can upload structure files (e.g., CIF, -or VASP POTCAR format), or import materials from the **Materials bank** in -Mat3ra platform. +## 1. Specify the material structure + +In order to perform a spin-magnetic calculation, the material structure must first be defined. A new material can be created using the **Materials Designer**, or structure files (e.g. CIF or VASP POSCAR format) can be uploaded. Materials may also be imported from the **Materials Bank**. ![materials designer with atomic labels](../../../images/tutorials/spin-magnetic/spin-materials-designer.webp "materials designer with atomic labels") -Notice, that if we want to assign different spin states (i.e., up or down) to -the same atomic species, we must add numeric labels to the atomic symbols. In -this case, the unit cell has two Fe atoms, we added `Fe1` and `Fe2` labels. +If different spin states (up or down) need to be assigned to the same atomic species, numeric labels must be added to the atomic symbols. In this example, the unit cell contains two Fe atoms labeled `Fe1` and `Fe2`. + -## 2. Create workflow +## 2. Create the workflow -Below we will show how to create a workflow for spin magnetic bandstructure -calculation. Alternatively, you may find the desired workflow in the workflow -bank on our platform, and you can import it to your library/account. Our example -calculation involves three steps: +The workflow for spin-magnetic band structure calculation consists of three steps: -1. Perform self-consistent field (SCF) calculation -2. Perform bands (NSCF) calculation along specific k-path -3. Post-processing of bands calculation +1. Self-consistent field (SCF) calculation +2. Bands (NSCF) calculation along a specific k-path +3. Post-processing of the bands calculation ![Various workflow units for spin magnetic bandstructure calculation](../../../images/tutorials/spin-magnetic/spin-full-workflow.webp "Various workflow units for spin magnetic bandstructure calculation") -### 2.1. SCF workflow unit +!!!tip "Bank workflow available" + The desired workflow can also be imported from the workflow bank. + +### 2.1. Configure the SCF unit -There are several templates for spin magnetic calculation. Here we choose -**pw_scf_magn**. If you like to perform **DFT+U**, **DFT+U+V**, or **DFT+U+J** -in conjunction with spin-polarization, please select the respective template. +Several templates are available for spin-magnetic calculations. Select **pw_scf_magn** for a standard spin-polarized SCF. Templates for **DFT+U**, **DFT+U+V**, and **DFT+U+J** in conjunction with spin-polarization are also available. ![Various spin magnetic flavors available](../../../images/tutorials/spin-magnetic/spin-flavors.webp "Various spin magnetic flavors available") -### 2.2. Bands calculation +### 2.2. Configure the bands calculation unit -In the next step, we add a unit for bands calculation and select -**pw_bands_magn** template. This performs `nscf` calculation along the specified -k-path. We can set the desired k-path via the **Important Settings** tab. +Add a unit for bands calculation and select the **pw_bands_magn** template. This performs an NSCF calculation along the specified k-path. The desired k-path can be set via the *Important Settings* tab. ![Specify k-path for bands calculation](../../../images/tutorials/spin-magnetic/spin-k-path.webp "Specify k-path for bands calculation") -### 2.3. Bands.x postprocessing +### 2.3. Configure bands.x post-processing ![bands.x settings](../../../images/tutorials/spin-magnetic/spin-bands-x.webp "bands.x settings") -In the final step, we add `bands.x` calculation. This step is optional, and -used for further postprocessing of already calculated bandstructure data in the -above steps. We are interested in processing one type of spin (i.e., up or down) -state. We can do that by specifying `spin_component = 1` for **up** spin, or -`spin_component = 2` for **down** spin. So we add two units, one to process only -**up** and another to process **down** spin only. We update the `filbands` -filenames so that the outputs are written to different files for up/down spins. -It is recommended to give each unit a distinct name, otherwise, some of the -generated files might be overwritten. - -## 3. Job designer - -Finally, navigate to the jobs page and click create new job. Import the material -and workflow. Then navigate to the **Important Settings** tab under workflow. -Here we can set the `starting_magnetization`. Since we want to perform -antiferromagnetic calculation, we specify `starting_magnetization` for Fe1 site -to -1, and that of Fe2 site to +1. - -Scroll, down to the bands calculation unit. Here we can modify the k-path for -the bands calculation. We will set the `starting_magnetization` the same as the -above step. However, note that `starting_magnetization` may not be used in case -`nscf`/`bands` calculations. Please consult Quantum ESPRESSO [documentation]( -https://www.quantum-espresso.org/Doc/INPUT_PW.html) for more clarity. It is safe -to set the `starting_magnetization` the same as `scf` step. +This optional step processes the calculated band structure data. In order to process a single spin channel, set `spin_component = 1` for **up** spin or `spin_component = 2` for **down** spin. Two units are added — one for up and one for down. The `filbands` filenames should be set to different values so that outputs are not overwritten. Each unit should be given a distinct name. + + +## 3. Configure the job + +Navigate to the jobs page and create a new job. Import the material and workflow, then navigate to the *Important Settings* tab under the workflow. + +Set the `starting_magnetization` values. For an antiferromagnetic calculation, specify `starting_magnetization` for the Fe1 site as -1 and for the Fe2 site as +1. ![set starting magnetization](../../../images/tutorials/spin-magnetic/spin-context-provider.webp "set starting magnetization") -Instead of specifying the `starting_magnetization`, we could alternatively -specify the `total_magnetization` if wanted. +Scroll down to the bands calculation unit. The `starting_magnetization` should be set to the same values as the SCF step. + +!!!note "Magnetization in NSCF calculations" + The `starting_magnetization` may not be used in NSCF/bands calculations. Consult the Quantum ESPRESSO [documentation](https://www.quantum-espresso.org/Doc/INPUT_PW.html) for details. Setting it to the same value as the SCF step is a safe default. + +Alternatively, `total_magnetization` can be specified instead. The compute parameters can be adjusted in the *Compute* tab. The job is then ready for submission. -If necessary, we can adjust the compute parameters in the **compute** tab. -Finally, we are ready for job submission. -## 4. Results +## 4. Examine the results ![Bandstructure plots](../../../images/tutorials/spin-magnetic/spin-bandstructure-plots.webp "Bandstructure plots") -Once the job is completed, the bandstructure plots are shown in the **Results** -tab. All input and output files can be found in the **Files** tab and can be -used for further analysis. +Once the job completes, the band structure plots are displayed in the *Results* tab. All input and output files can be found in the *Files* tab. -**Updated in platform version 2024.8.22:** Both spin components (if present) are -now shown in the same plot with different colors. Following plot shows the spin -resolved bandstructure of nickel, where blue and orange colors represent up and -down spin components, respectively. +!!!info "Spin-resolved plot (platform version 2024.8.22+)" + Both spin components are shown in the same plot with different colors. The plot below shows the spin-resolved band structure of nickel, where blue and orange represent up and down spin components, respectively. ![Spin resolved bandstructure of Ni](../../../images/tutorials/spin-magnetic/ni-spin-resolved-bandstructure.webp "Spin resolved bandstructure of Ni") -## Step-by-step screenshare video +## 5. Video walkthrough -In the below video, we go through an example calculation. +The animation below demonstrates the full calculation workflow.
- +
diff --git a/lang/en/docs/tutorials/dft/electronic/spin-orbit-coupling-qe.md b/lang/en/docs/tutorials/dft/electronic/spin-orbit-coupling-qe.md index e6a069d16..4e572a816 100644 --- a/lang/en/docs/tutorials/dft/electronic/spin-orbit-coupling-qe.md +++ b/lang/en/docs/tutorials/dft/electronic/spin-orbit-coupling-qe.md @@ -1,106 +1,83 @@ -# How to incorporate spin-orbit coupling effect in Quantum ESPRESSO - -In this tutorial, we walk you through the steps of incorporating spin-orbit -coupling effect in bandstructure calculation using Quantum ESPRESSO. We want to -calculate the electronic bandstructure of Bi2Se3, a -prototypical topological insulating material, featuring an insulating bulk and -conducting surface states. The spin-orbit coupling effect of heavy bismuth atoms -and presence of surface is necessary for the occurrence of Topological Dirac -surface states. - -## 1. Creating slab structure -We will need to create a slab structure for this calculation. Density Functional -Theory calculation can only be performed on periodic systems. To obtain a -surface by adding sufficient vacuum between the layers. - -Navigate to the materials designer from the left sidebar, and click -**Create New** material. Set the lattice type (hexagonal in case of -Bi2Se3), original lattice constants, and atomic positions. -Then select **Preserve Interatomic Distance** and increase to lattice vector -**c** to add vacuum to the ab-plane. +# Spin-Orbit Coupling Band Structure in Quantum ESPRESSO + +This tutorial demonstrates how to incorporate the spin-orbit coupling (SOC) effect in a band structure calculation using Quantum ESPRESSO. The example system is Bi2Se3, a prototypical topological insulating material featuring an insulating bulk and conducting surface states. The spin-orbit coupling of heavy bismuth atoms and the presence of a surface are necessary for the occurrence of topological Dirac surface states. + + +## 1. Create the slab structure + +A slab structure is required for this calculation. DFT calculations operate on periodic systems, so a surface is modeled by adding sufficient vacuum between the layers. + +Navigate to the Materials Designer from the left sidebar and click **Create New** material. Set the lattice type (hexagonal for Bi2Se3), the original lattice constants, and the atomic positions. Then select **Preserve Interatomic Distance** and increase the lattice vector **c** to add vacuum to the ab-plane. ![Bi2Se3 slab structure](../../../images/tutorials/soc/bi2se3-slab.webp "Bi2Se3 slab structure") -## 2. Create workflow -We need to specify the workflow following workflow steps to obtain the -bandstructure with the spin-orbit coupling effect: +## 2. Create the workflow + +The workflow for band structure with SOC consists of three steps: -1. Perform self-consistent field (SCF) calculation -2. Perform bands (NSCF) calculation along specific k-path -3. Post-processing of bands calculation +1. Self-consistent field (SCF) calculation +2. Bands (NSCF) calculation along a specific k-path +3. Post-processing of the bands calculation -Note that for SOC calculation, we need to select fully relativistic -pseudopotential. +!!!warning "Pseudopotential requirement" + SOC calculations require fully relativistic pseudopotentials. ![Relativistic pseudopotential](../../../images/tutorials/soc/relativistic-pseudo.webp "Relativistic pseudopotential") -### 2.1. Self-consistent field calculation -Add an execution unit, and select **pw_scf_soc** template, there are few other -SOC templates that you may explore, for example, SOC in conjunction with the -Hubbard U calculation. +### 2.1. Configure the SCF unit + +Add an execution unit and select the **pw_scf_soc** template. Several other SOC templates are available, including SOC in conjunction with the Hubbard U calculation. ![SOC templates](../../../images/tutorials/soc/spin-orbit-coupling-flavors.webp "SOC templates") -### 2.2. PW Bands calculation -Add the next execution unit for PW *bands* calculation. Here we select -**pw_bands_soc** template. The K-path and number of points between the K points -can be specified in the **Important Settings** tab. +### 2.2. Configure the PW bands unit -### 2.3. Bands.x postprocessing -Finally, we add another unit for postprocessing of our bands data. This is an -optional step for the post-processing of the bandstructure data. +Add the next execution unit for PW bands calculation and select the **pw_bands_soc** template. The k-path and number of points between k-points can be specified in the *Important Settings* tab. + +### 2.3. Configure bands.x post-processing + +Add another unit for post-processing of the bands data. This is an optional step for further analysis of the band structure output. ![Bandstructure with SOC workflow](../../../images/tutorials/soc/spin-orbit-coupling-workflow.webp "Bandstructure with SOC workflow") -## 3. Job designer -Navigate to the jobs designer page from the left sidebar and click -**Create New** job. Select material and workflow. +## 3. Configure and submit the job + +Navigate to the Jobs Designer from the left sidebar and click **Create New** job. Select the material and workflow. ![Select material and workflow](../../../images/tutorials/soc/select-material-and-workflow.webp "Select material and workflow") -We can further edit the workflow units, and set various parameters under the -**Important Settings** tab. Here we can set the k-grid density, starting -magnetization, K-path, etc. SOC calculations are slower to converge, it is -possible to start a SOC calculation from a previously converged SCF charge -density that was performed without SOC, which takes shorter time than starting -calculation without any starting charge density. +The workflow units can be further edited under the *Important Settings* tab to set the k-grid density, starting magnetization, k-path, and other parameters. + +!!!tip "Faster convergence from pre-converged density" + SOC calculations are slower to converge. It is possible to start a SOC calculation from a previously converged SCF charge density that was performed without SOC. This is faster than starting without any initial charge density. ![Important settings](../../../images/tutorials/soc/important-settings.webp "Important settings") -Navigate to the **Compute** and set various computer parameters, such as, time -limit for a given calculation, queue, number of nodes, and number of processor -cores per node. +Navigate to the *Compute* tab to set the time limit, queue, number of nodes, and processor cores per node. ![Compute parameters](../../../images/tutorials/soc/compute-parameters.webp "Compute parameters") -Save and exit job designer, now hover over the job, and click the run button to -submit job. +Save and exit the Job Designer, then hover over the job and click the **Run** button to submit. + +## 4. Examine the results -## 4. Results -Once the job is finished, navigate to the **Results** tab for a quick view of -the summary of various results including the bandstructure plot. With sufficient -convergence criterion (k-grid density, cutoff energies, convergence threshold, -etc.), we should see conducting Dirac surface states for slab calculation. We -can repeat the calculation for bulk, and identify the surface states by -comparing the. For bulk-only calculation, there should be a bandgap. All output -files are available under the **Files** tab. One may use Jupyter notebook -session in our platform, or download the files to the local computer for further -analysis. +Once the job completes, navigate to the *Results* tab for a summary including the band structure plot. With sufficient convergence parameters (k-grid density, cutoff energies, convergence threshold), conducting Dirac surface states should be visible in the slab calculation. Repeating the calculation for the bulk and comparing the results allows identification of the surface states — the bulk-only calculation should show a band gap. ![Spin-orbit coupling results](../../../images/tutorials/soc/spin-orbit-coupling-results.webp "Spin-orbit coupling results") -Note that above bandstructure plot in the result tab is obtained using coarse -convergence criterion. We need more stringent convergence parameters to see the -topological Dirac states clearly. +!!!note "Convergence required for topological states" + The band structure plot shown above was obtained using coarse convergence parameters. More stringent convergence is needed to resolve the topological Dirac states clearly. + +All output files are available under the *Files* tab. Jupyter notebook sessions on the platform or local downloads can be used for further analysis. -## Step-by-step screenshare video +## 5. Video walkthrough -In the below video, we go through an example calculation. +The animation below demonstrates the full calculation workflow.
- +
diff --git a/lang/en/docs/tutorials/dft/electronic/valence-band-offset.md b/lang/en/docs/tutorials/dft/electronic/valence-band-offset.md index a02fda689..423daebc3 100644 --- a/lang/en/docs/tutorials/dft/electronic/valence-band-offset.md +++ b/lang/en/docs/tutorials/dft/electronic/valence-band-offset.md @@ -1,121 +1,99 @@ # Calculate Valence Band Offset -This tutorial page explains how to calculate the [valence band offset](../../../properties-directory/scalar/valence-band-offset.md) (VBO) -based on the potential lineup method[^1][^2][^3] using [Density Functional Theory](../../../models-directory/dft/overview.md). -For this tutorial, we consider a 2D material interface MoS2/WS2 and use -[Quantum Espresso](../../../software-directory/modeling/quantum-espresso/overview.md) as our main simulation engine. -The content of this tutorial was also part of our 2021 webinar *2D Materials and their Electronic Properties*[^4] +This tutorial explains how to calculate the [valence band offset]({{ reference_url }}/properties-directory/scalar/valence-band-offset/) (VBO) +based on the potential lineup method [^1] [^2] [^3] using [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT). +The example system is a 2D material interface MoS2/WS2, and [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) is used as the simulation engine. +The content of this tutorial was also presented in the 2021 webinar *2D Materials and their Electronic Properties* [^4]. -!!!note "Simulation engines considered in this tutorial" - The workflow presented in this tutorial is currently only available for - [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md). +!!!note "Simulation engine" + The VBO workflow is currently only available for [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/). -## Definitions -### Valence Band Offset +## 1. Understand the method -The [valence band offset](../../../properties-directory/scalar/valence-band-offset.md) is defined by the relative position -of the valence band on both sides of the interface. This property is relevant to study the charge transport across -interfaces such as semiconductor heterojunctions. Other properties related to the band profile at the interface are -the *conduction band offset* and *Schottky barrier* (metal-semiconductor interface). +### 1.1. Valence band offset -### Potential Lineup Method -This tutorial employs the potential lineup method in order to determine the valence band offset, which requires the -calculation of the macroscopically averaged electrostatic potential and valence band maximum of the two materials. -The valence band offset for an A/B interface can then be determined via: +The [valence band offset]({{ reference_url }}/properties-directory/scalar/valence-band-offset/) is defined by the relative position of the valence band on both sides of an interface. This property is relevant for studying charge transport across interfaces such as semiconductor heterojunctions. Related properties include the *conduction band offset* and the *Schottky barrier* (metal-semiconductor interface). + +### 1.2. Potential lineup method + +This tutorial employs the potential lineup method to determine the VBO, which requires the macroscopically averaged electrostatic potential and valence band maximum of the two materials. The VBO for an A/B interface is: $$ \Delta E_{\mathrm{VBO}} = \Delta E_{v} + \Delta \overline{V} $$ -The first term, $\Delta E_{v}$, is usually referred to as the *band structure term* and defined as the difference -of the two valence band maxima $\varepsilon_{v}$ referenced to the macroscopically averaged electrostatic potential $\overline{V}$ -in each material: +The first term, $\Delta E_{v}$, is the *band structure term* — the difference of the two valence band maxima $\varepsilon_{v}$ referenced to the macroscopically averaged electrostatic potential $\overline{V}$ in each material: $$ \Delta E_{v} = (\varepsilon_{v}^{A} - \overline{V}^{A}) - (\varepsilon_{v}^{B} - \overline{V}^{B}) $$ -![Referencing the valence band edge](../../../images/tutorials/valence-band-maximum-with-reference.png){: style="width:600px"} -The second term, $\Delta \overline{V}$, is determined from the lineup of the macroscopically averaged electrostatic potential in -the interface heterostructure. -![Lineup of the macroscopically averaged electrostatic potential](../../../images//tutorials/macroscopically-averaged-potential-lineup.png){: style="width:600px"} +![Referencing the valence band edge](../../../images/tutorials/valence-band-maximum-with-reference.png "Referencing the valence band edge"){: style="width:600px"} + +The second term, $\Delta \overline{V}$, is determined from the lineup of the macroscopically averaged electrostatic potential in the interface heterostructure. + +![Lineup of the macroscopically averaged electrostatic potential](../../../images/tutorials/macroscopically-averaged-potential-lineup.png "Lineup of the macroscopically averaged electrostatic potential"){: style="width:600px"} + + +## 2. Select the materials + +Three materials are required, corresponding to the MoS2/WS2 interface and the isolated monolayers of both MoS2 and WS2. Each structure should be relaxed beforehand. +The initial interface structure was taken from [materialsproject.org](https://materialsproject.org/materials/mp-1023954) and optimized via variable-cell relaxation of the x- and y-components. The monolayer structures were extracted from the interface and optimized in the same way. The final structures are available on the Mat3ra platform: -## Choose Materials +- [MoS2/WS2 heterostructure](https://platform.mat3ra.com/mat3ra/materials/cxgeoQwPJQJbgA2aD) +- [WS2 monolayer](https://platform.mat3ra.com/mat3ra/materials/5JcsfbBPKFWjxGXkX) +- [MoS2 monolayer](https://platform.mat3ra.com/mat3ra/materials/Cyr7Y6sefZsmZo6bH) -When creating the job, the user needs to select **three materials** corresponding to the MoS2/WS2 interface -and the isolated monolayers of both MoS2 and WS2. Each of the structures is expected to be relaxed. -The initial interface structure was taken from [materialsproject](https://materialsproject.org/materials/mp-1023954) and -optimized via a variable-cell relaxation of the x- and y-components. The monolayer structures were extracted from the interface -and optimized in the same way. The final structures are available on the Mat3ra platform: +!!!warning "Material order" + The VBO workflow assumes the interface structure corresponds to the first material. The interface structure must be loaded first. - - [MoS2/WS2 heterostructure](https://platform.mat3ra.com/exabyte-io/materials/cxgeoQwPJQJbgA2aD) - - [WS2 monolayer](https://platform.mat3ra.com/exabyte-io/materials/5JcsfbBPKFWjxGXkX) - - [MoS2 monolayer](https://platform.mat3ra.com/exabyte-io/materials/Cyr7Y6sefZsmZo6bH) -!!!note "Order of Materials" - The VBO workflow assumes the interface structure to correspond to the first material, i.e. please be sure to load the interface - structure first. +## 3. Select the workflow -## Choose Workflow +The [workflow]({{ reference_url }}/workflows/overview/) for calculating the VBO can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/). The workflow can then be [selected]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) and added to the [job being created]({{ interface_url }}/jobs-designer/workflow-tab/). -The [workflow](../../../workflows/overview.md) for calculating the valence band offset can be -[imported](../../../workflows/actions/copy-bank.md) from the [Workflows Bank](../../../workflows/bank.md) into the account-owned -[collection](../../../accounts/collections.md). -This workflow can later be [selected](../../../jobs-designer/actions-header-menu/select-workflow.md) and added to the -[Job being created](../../../jobs-designer/workflow-tab.md). -A [representation of this workflow](https://github.com/Exabyte-io/wode.js/blob/2022.11.16-0/assets/workflows/espresso/valence_band_offset.yml) -is also available as part of the Mat3ra workflow definitions repository ([wode.js](https://github.com/Exabyte-io/wode.js)). +A [representation of this workflow](https://github.com/mat3ra/wode.js/blob/2022.11.16-0/assets/workflows/espresso/valence_band_offset.yml) is also available in the Mat3ra workflow definitions repository ([wode.js](https://github.com/mat3ra/wode.js)). -[![Valence Band Offset Workflow](../../../images/tutorials/valence-band-offset-workflow.png)](../../../images/tutorials/valence-band-offset-workflow.png) +[![Valence Band Offset Workflow](../../../images/tutorials/valence-band-offset-workflow.png "Valence Band Offset Workflow")](../../../images/tutorials/valence-band-offset-workflow.png) -The workflow contains two subworkflows per material calculating the valence band maximum (via band structure), -macroscopically averaged electrostatic potential, and its minima. -As the system in this tutorial is a heterostructure built of monolayers, determining the value of the macroscopically -averaged electrostatic potential in the region of the monolayer corresponds to finding the minima of $\overline{V}$. -For multilayered heterostructures the problem becomes equivalent of finding plateaus of $\overline{V}$. -The final subworkflow collects all the intermediate results and determines the value of the valence band offset. +The workflow contains two subworkflows per material that calculate the valence band maximum (via band structure), the macroscopically averaged electrostatic potential, and its minima. For monolayer heterostructures, determining $\overline{V}$ in the monolayer region corresponds to finding the minima. For multilayered heterostructures, the problem becomes equivalent to finding plateaus of $\overline{V}$. The final subworkflow collects all intermediate results and determines the VBO. -### Workflow Settings -For the purpose of this tutorial, we set the size of the grid of k-points to 6 x 6 x 1 for each of the three PW-SCF units -and adjust the k-path to reflect the reduced dimensionality (Γ-M-K-Γ). In addition, one should also adjust the size of the window -for macroscopic averaging. For the present system we set this size to the distance between the sulfur atoms in both -monolayers (ca. 5.7 bohr). +### 3.1. Configure workflow settings -## Submit Job +Set the k-point grid to 6 × 6 × 1 for each of the three PW-SCF units and adjust the k-path to reflect the reduced dimensionality (Γ–M–K–Γ). Also adjust the macroscopic averaging window size — for this system, set it to the distance between the sulfur atoms in both monolayers (~5.7 bohr). -Before [submitting](../../../jobs/actions/run.md) the [job](../../../jobs/overview.md), the user should click on the -["Compute" tab](../../../jobs-designer/compute-tab.md) of [Job Designer](../../../jobs-designer/overview.md) and inspect -the [compute parameters](../../../infrastructure/compute/parameters.md) included therein. -## Examine results +## 4. Submit the job -When all [unit](../../../workflows/components/units.md) computations are complete at the end of Job execution, switching -to the [Results tab](../../../jobs/ui/results-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md) will show the results -of the simulation, including the valence band offset as well as the plots of the planar and macroscopic average of -the electrostatic potentials. +Before [submitting]({{ interface_url }}/jobs/actions/run/) the [job]({{ reference_url }}/jobs/overview/), the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) of [Job Designer]({{ interface_url }}/jobs-designer/overview/) should be reviewed to verify the [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/). -### Comparison with Experimental Value -The calculated value of ~0.27 eV for the valence band offset is below the experimental[^5] value of 0.55 eV, -but agrees with previous theoretical results[^6] of 0.32 eV and 0.22 eV, respectively. +## 5. Examine the results -## Animation +Once all [unit]({{ reference_url }}/workflows/components/units/) computations complete, the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) displays the VBO as well as the plots of the planar and macroscopic average of the electrostatic potentials. -We demonstrate the above-mentioned steps involved in the creation and execution of a Valence Band Offset workflow in the following animation. +### 5.1. Compare with experiment + +The calculated value of ~0.27 eV is below the experimental value of 0.55 eV [^5], but agrees with previous theoretical results of 0.32 eV and 0.22 eV [^6]. + + +## 6. Video walkthrough + +The animation below demonstrates the steps involved in creating and executing a VBO workflow.
-## Links + +## 7. Links [^1]: A. Baldereschi, S. Baroni, R. Resta, *Phys. Rev. Lett.* **61**, 734 (1988); DOI: [10.1103/PhysRevLett.61.734](https://www.doi.org/10.1103/PhysRevLett.61.734) [^2]: L. Colombo, R. Resta, S. Baroni, *Phys. Rev. B* **44**, 5572 (1991); DOI: [10.1103/physrevb.44.5572](https://www.doi.org/10.1103/physrevb.44.5572) [^3]: M. Peressi, N. Binggeli, A. Baldereschi, *J. Phys. D: Appl. Phys.* **31**, 1273-1299 (1998); DOI: [10.1088/0022-3727/31/11/002](https://www.doi.org/10.1088/0022-3727/31/11/002) [^4]: [2D Materials and their Electronic Properties (Mat3ra YouTube)](https://youtu.be/5T9JMoj62P4) -[^5]: C. Lu, *et. al*, *Phys. Status Solidi A*, 1900544 (2009); DOI: [10.1002/pssa.201900544](https://www.doi.org/10.1002/pssa.201900544) +[^5]: C. Lu, *et al.*, *Phys. Status Solidi A*, 1900544 (2009); DOI: [10.1002/pssa.201900544](https://www.doi.org/10.1002/pssa.201900544) [^6]: E. Torun, H.P.C. Miranda, A. Molina-Sánchez, L. Wirtz, *Phys. Rev. B* **97**, 245427 (2018); DOI: [10.1103/PhysRevB.97.245427](https://www.doi.org/10.1103/PhysRevB.97.245427) - diff --git a/lang/en/docs/tutorials/dft/optical/epsilon-optimal-basis.md b/lang/en/docs/tutorials/dft/optical/epsilon-optimal-basis.md index b3fbe9615..f69de131d 100644 --- a/lang/en/docs/tutorials/dft/optical/epsilon-optimal-basis.md +++ b/lang/en/docs/tutorials/dft/optical/epsilon-optimal-basis.md @@ -1,131 +1,77 @@ -# Optical property with optimal basis +# Optical Properties with Optimal Basis Functions -In this tutorial we will go through the details of optical property calculation -with optimal basis function. We will use Quantum ESPRESSO SIMPLE.X program to -calculate dielectric function of silicon. Please refer to the original paper: -[SIMPLE code: Optical properties with optimal basis functions, Prandini, G., -Galante, M., Marzari, N., & Umari, P., Computer Physics Communications, **240**, -106 (2019)](https://doi.org/10.1016/j.cpc.2019.02.016) for the detailed physics -behind this calculation. +This tutorial demonstrates how to calculate the dielectric function of silicon using the SIMPLE.x program in Quantum ESPRESSO, which employs optimal basis functions for optical property calculations. The detailed physics behind this method is described in: [SIMPLE code: Optical properties with optimal basis functions, Prandini, G., Galante, M., Marzari, N., & Umari, P., Computer Physics Communications, **240**, 106 (2019)](https://doi.org/10.1016/j.cpc.2019.02.016). -Below we will replicate the [example 5 from Quantum ESPRESSO GWW directory]( -https://gitlab.com/QEF/q-e/-/tree/qe-7.3/GWW/examples/). Alternatively, input -and reference output files are available in our [CLI-job-examples]( -https://github.com/Exabyte-io/cli-job-examples/tree/main/espresso/simple.x) -repository. +The workflow below replicates [example 5 from the Quantum ESPRESSO GWW directory](https://gitlab.com/QEF/q-e/-/tree/qe-7.3/GWW/examples/). Input and reference output files are also available in the [CLI-job-examples repository](https://github.com/mat3ra/cli-job-examples/tree/main/espresso/simple.x). -## 1. Create workflow +## 1. Create the workflow -Dielectric constant calculation workflow using SIMPLE method involves following -steps. +The dielectric constant calculation using the SIMPLE method involves the following steps. +### 1.1. PW SCF calculation -### 1.1 PW SCF calculation +Navigate to the workflows page, and create a new workflow. The Quantum ESPRESSO version and build can be changed by expanding the details pane and selecting from the drop-down menus. -First step is to perform self consistent field calculation. Navigate to -workflows page in our web platform, and click create new workflow. Quantum -ESPRESSO version and build can be changed by expanding the details pane, and -selecting the options from respective drop-down menu. - -Currently, SIMPLE code only supports norm-conserving pseudopotential. Please -choose norm-conserving pseudopotential after applying appropriate method -filters. +!!!warning "Pseudopotential requirement" + The SIMPLE code only supports norm-conserving pseudopotentials. Select a norm-conserving pseudopotential after applying the appropriate method filters. ![Select norm-conserving pseudopotential](../../../images/tutorials/simple.x/simple-select-ncpp.webp "Select norm-conserving pseudopotential") -We will provide, lattice parameters via `ibrav` and `celldm` instead of -`CELL_PARAMETERS` card. Click edit on the **pw_scf** unit, and directly modify -desired parameters on the template. We can set energy and charge density cutoffs -as well as k-gird parameters on the **Important Settings** tab. - - -### 1.2 HEAD calculation - -Add next unit (execution unit) and select **head.x** executable, adjust -parameters on the `head` template as necessary. - +Lattice parameters are provided via `ibrav` and `celldm` instead of the `CELL_PARAMETERS` card. Click **Edit** on the **pw_scf** unit and modify the desired parameters in the template. Energy and charge density cutoffs, as well as the k-grid, can be set in the *Important Settings* tab. -### 1.3 NSCF calculation (Gamma-only) +### 1.2. HEAD calculation -Next step is to perform a non-self consistent field calculation for $\Gamma$ -point only. Add an execution unit, click edit unit, select `pw_nscf` flavor. -Edit the `ibrav` and other parameters as we did in the PW SCF step. Note that we -have set `nbnd` as well. Finally, set the k-grid only for gamma point -calculation. +Add an execution unit and select the **head.x** executable. Adjust parameters in the `head` template as needed. +### 1.3. NSCF calculation (Gamma-only) -### 1.4 pw4gww.x +Add an execution unit, click **Edit**, and select the `pw_nscf` flavor. Set `ibrav` and other parameters as in the SCF step. Set `nbnd` and configure the k-grid for Gamma-point-only calculation. -We need to prepare input files for GWW calculation. Similarly, add a unit with -**pw4gww.x** executable. Take note of various input parameters, and modify on -the template as necessary. +### 1.4. pw4gww.x preparation +Add a unit with the **pw4gww.x** executable to prepare input files for the GWW calculation. Modify template parameters as necessary. -### 1.5 GWW calculation +### 1.5. GWW calculation -Add unit with **gww.x** executable, and adjust various input parameters in the -template via edit unit. +Add a unit with the **gww.x** executable and adjust input parameters in the template. +### 1.6. NSCF calculation with k-grid -### 1.6 NSCF calculation with k-grid - -Next we need to perform non-self consistent field calculation for finite k-grid. -We also need to set no symmetry and no inversion for our `nscf` runs so that -Quantum ESPRESSO does not reduce the number of k-points based on symmetry. In -our platform, it can be done via an assignment unit. Click and add unit, and -select assignment unit from the drop-down. Later assign a variable: -`NO_SYMMETRY_NO_INVERSION` and set the value to `true`. +Perform a non-self-consistent calculation on a finite k-grid. Symmetry must be disabled so that Quantum ESPRESSO does not reduce k-points. This is achieved by adding an assignment unit (select "assignment" from the unit type drop-down) with the variable `NO_SYMMETRY_NO_INVERSION` set to `true`. ![Select unit type](../../../images/tutorials/simple.x/simple-unit-type.webp "Select unit type") ![Set no symmetry](../../../images/tutorials/simple.x/simple-set-no-sym.webp "Set no symmetry") -Add an execution unit for `nscf` calculation. Here we update the number of bands -(`nbnd`) to 40. The k-grid is set to 2×2×2 via the **Important Settings** tab. -Remember to give the unit a unique name, as we already have a unit with name -`pw_nscf`, otherwise some of the generated file names may create conflicts. - +Add an execution unit for `nscf` calculation with `nbnd` set to 40 and a 2 × 2 × 2 k-grid via *Important Settings*. A unique unit name is required to avoid file name conflicts with the earlier `pw_nscf` unit. -### 1.7 SIMPLE calculation +### 1.7. SIMPLE calculation -Now, we are ready the calculate the optimal basis set using **simple.x**. Here, -we will choose the `calc_mode=0` for BSE method. One can set `calc_mode=1` for -Independent Particle (IP) method. Specify number of valence band to 16, and -conduction band to 24. +Add a unit with **simple.x** to calculate the optimal basis set. Set `calc_mode=0` for the BSE method (or `calc_mode=1` for Independent Particle). Specify 16 valence bands and 24 conduction bands. ![Simple.x input template](../../../images/tutorials/simple.x/simple-template.webp "Simple.x input template") +### 1.8. SIMPLE BSE calculation -### 1.8 SIMPLE BSE calculation - -Add next unit for the dielectric function calculation using **simple_bse.x** -program. Alternatively, user can select **simple_ip.x** method instead. - +Add a unit for the dielectric function calculation using **simple_bse.x**. Alternatively, **simple_ip.x** can be used. -### 1.9 Post processing +### 1.9. Post-processing -The the above step calculates the $\alpha$ and $\beta$ coefficients of Haydock -series, which can be transformed into dielectric constant using -**abcoeff_to_eps.x** post processing utility. +The previous step calculates the $\alpha$ and $\beta$ coefficients of the Haydock series. These are transformed into the dielectric constant using the **abcoeff_to_eps.x** post-processing utility. ![Simple.x full workflow steps](../../../images/tutorials/simple.x/simple-full-workflow.webp "Simple.x full workflow steps") -## 2. Run Job +## 2. Run the job -Once workflow is ready, navigate to jobs page and create new job. Select the -workflow, adjust compute parameters as desired. Submit the job for execution. -Once the job is completed, navigate to the **Files** tab. Here the epsilon -output files can be found. User may launch a Jupyter notebook session in our -platform to quickly plot epsilon or download the output files and use any -plotting program for visualization. +Once the workflow is ready, navigate to the jobs page and create a new job. Select the workflow, adjust compute parameters, and submit for execution. After completion, the epsilon output files are available under the *Files* tab. A Jupyter notebook session on the platform or local downloads can be used for plotting. -## 3. Step by step screenshare video +## 3. Video walkthrough -In the below tutorial, we go through the whole process. +The animation below demonstrates the full process.
- +
diff --git a/lang/en/docs/tutorials/dft/thermodynamic/defect-formation-energy.md b/lang/en/docs/tutorials/dft/thermodynamic/defect-formation-energy.md new file mode 100644 index 000000000..64b25f3dd --- /dev/null +++ b/lang/en/docs/tutorials/dft/thermodynamic/defect-formation-energy.md @@ -0,0 +1,89 @@ +# Calculate Defect Formation Energy + +This tutorial explains how to calculate the [defect formation energy]({{ reference_url }}/properties-directory/scalar/formation-energy/) of a defective material using [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT) with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/). + +## 1. Prerequisites + +The defect formation energy is calculated with respect to the pristine material and its constituent elements in their standard states. For the workflow to succeed, the **elemental total energies must already exist** on the platform. + +Before running the defect formation energy workflow for a defective compound (e.g., Nitrogen vacancy in GaN), you must first calculate the [Total Energy]({{ reference_url }}/properties-directory/scalar/total-energy/) for each of its constituent elements that are added or removed to create the defect: +1. **Get Elemental Materials**: Navigate to your Materials collection and import the relevant elemental reference materials from Standata, saving them to your account. +2. **Calculate Total Energy**: For each elemental material, run a standard SCF [Total Energy]({{ reference_url }}/properties-directory/scalar/total-energy/) job on it. + - **Crucial**: The precision settings (e.g., KPPRA, kinetic energy cutoffs) used for the elements must exactly match the settings you will use for the defective material's calculation. + - **Crucial**: Ensure you note the property **Group** (e.g., `qe:dft:gga:pbe`) under which the elemental Total Energies were calculated, as you will need to specify this group in the Defect Formation Energy workflow. + +## 2. Create the materials + +1. Create the pristine bulk material structure using the [Materials Designer]({{ interface_url }}/materials-designer/overview/). +2. Create the defective structure. You can follow tutorials on creating defects, such as [Create Point Defect Pair in GaN](../../materials/specific/defect-point-pair-gallium-nitride.md). +3. Ensure that the total energy for the pristine material has been calculated with the same precision parameters that you plan to use for the defect calculation. + +## 3. Understand the workflow structure + +
+ Expand to view unit details + +The defect formation energy [workflow]({{ reference_url }}/workflows/overview/) is composed of several [subworkflows]({{ reference_url }}/workflows/components/subworkflows/) that load the materials, fetch their pre-calculated total energies, and compute the final energy. + +### 1. Load Defective Material +- Loads the defective material into the workflow. + +### 2. Compute Total Energy for Defective Material +- **pw_scf**: Performs an SCF calculation on the defective structure. + +### 3. Load Pristine Material +- Loads the standalone pristine bulk material into the workflow. + +### 4. Fetch Total Energy for Pristine Material +- Queries the platform for the total energy of the pristine material and extracts it using `io-bulk-te-job` and `io-te-bulk`. + +### 5. Resolve Elemental Materials +- Resolves the Standata elemental reference materials for every element present in either the defective or the pristine structure. + +### 6. Resolve Total Energies for Elemental Materials +- **assign-source-of-te-for-an-element** / **assign-group-for-material** set which elemental reference records to search for (see [step 5](#5-set-group-and-source-of-properties) below). +- Contains a loop (`init-element-index` / `check-te-for-elemental-materials-loop` / `assign-current-element`) that iterates over elements. +- **io-te-for-an-element** retrieves the pre-calculated `total_energy` property for the current element's standard state reference material, filtered by that Group and Source. + +### 7. Compute Defect Formation Energy +- **assign-defect-formation-energy**: Uses [Python]({{ reference_url }}/software-directory/scripting/python/overview/) to compute the defect formation energy by finding the difference in total energy between the defective and pristine materials, adjusted for the chemical potentials (elemental reference energies) of any atoms added or removed. + +
+ +## 4. Select the workflow and create the job + +This is a **multi-material** workflow: the job must be submitted with exactly two materials, in this order: + +1. **Defective supercell** (position 0) — its total energy is computed by the job itself. +2. **Pristine supercell** (position 1) — its total energy is fetched from that material's own most recently finished Total Energy job, so it must already exist on the platform (see [step 2](#2-create-the-materials)). + +To set this up: + +1. Open the [Job Designer]({{ interface_url }}/jobs-designer/overview/) and add the defective material first, then the pristine material, so they occupy positions 0 and 1 respectively. +2. [Workflows]({{ reference_url }}/workflows/overview/) for defect formation energy calculations with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/). +3. Once imported, [select]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) the Defect Formation Energy workflow and add it to your job. + +## 5. Set Group and Source of Properties + +This step only applies to the **elemental reference** lookup — the pristine material's total energy (fetched in the **Fetch Total Energy for Pristine Material** subworkflow) is read directly from that material's own most recent finished Total Energy job and does not use a Group or Source setting. + +Inside the **Resolve Total Energies for Elemental Materials** subworkflow, switch to the **Detailed view** tab and check two assignment units: + +- **assign-source-of-te-for-an-element**: who owns the elemental Total Energy record to search for — `'public'` by default, or `'my_account'`/`'curators'` if you calculated the elemental references yourself or want curated results only. +- **assign-group-for-material**: the property group (e.g., `qe:dft:gga:pbe`) to filter the elemental Total Energy results by computational method. This must match the property group of the individual elemental total energies you calculated previously. + +This is the same **Resolve Total Energies for Elemental Materials** subworkflow used by the Formation Energy workflow: + +![Job Designer source assignment for Defect Formation Energy](/images/tutorials/formation_energy/formation-energy-assign-te-source-unit.png) + +![Unit settings for assign-source-of-te-for-an-element](/images/tutorials/formation_energy/formation-energy-assign-te-source.png) + +## 6. Submit the job + +Before [submitting]({{ interface_url }}/jobs/actions/run/) the [job]({{ reference_url }}/jobs/overview/), review the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) to verify the compute parameters. Ensure that the K-point grid and cutoffs match those used for the pristine material and elemental reference calculations. + +## 7. Examine the results + +Once the job completes, navigate to the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of the [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). The **Defect Formation Energy** property will be displayed. + +![Job Viewer results for Defect Formation Energy](/images/tutorials/defect_formation_energy/defect-formation-energy-result.png) diff --git a/lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md b/lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md new file mode 100644 index 000000000..7d5741fe3 --- /dev/null +++ b/lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md @@ -0,0 +1,84 @@ +# Calculate Formation Energy + +This tutorial explains how to calculate the [formation energy]({{ reference_url }}/properties-directory/scalar/formation-energy/) of a compound material using [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT) with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/). + +!!!note "Quantum ESPRESSO version" + This tutorial applies to Quantum ESPRESSO versions 5.2.1, 5.4.0, 6.0.0, 6.3, and later. + +## Prerequisites + +The formation energy of a compound is calculated with respect to its constituent elements in their standard states. For the workflow to succeed, the **elemental total energies must already exist** on the platform. + +Before running the formation energy workflow for a compound (e.g., Silicon Carbide, SiC), you must first calculate the [Total Energy]({{ reference_url }}/properties-directory/scalar/total-energy/) for each of its constituent elements: +1. **Get Elemental Materials**: Navigate to your Materials collection and import the relevant elemental reference materials from Standata, saving them to your account. +2. **Calculate Total Energy**: For each elemental material, run a standard SCF [Total Energy]({{ reference_url }}/properties-directory/scalar/total-energy/) job on it. + - **Crucial**: The precision settings (e.g., KPPRA, kinetic energy cutoffs) used for the elements must exactly match the settings you will use for the compound material's calculation. + - **Crucial**: Ensure you note the property **Group** (e.g., `qe:dft:gga:pbe`) under which the elemental Total Energies were calculated, as you will need to specify this group in the Formation Energy workflow. + +## 1. Create a job + +Open the [Job Designer]({{ interface_url }}/jobs-designer/overview/) to create a new job. + +Under the *Choose A Material* section, select the compound material for which you want to calculate the formation energy. You can import materials from external databases or upload them directly. + +![Job Designer material selection for Formation Energy](/images/tutorials/formation_energy/formation-energy-material-selection.png) + +## 2. Understand the workflow structure + +
+ Expand to view unit details + +The [workflow]({{ reference_url }}/workflows/overview/) is composed of the following key [units]({{ reference_url }}/workflows/components/units/): + +**pw_scf** (in the **Compute Total Energy** subworkflow) — Performs a self-consistent field (SCF) calculation to determine the total energy of the compound material. + +**assign-source-of-te-for-an-element** / **assign-group-for-material** (in the **Resolve Total Energies for Elemental Materials** subworkflow) — Set which elemental reference records to search for: the **Source** is the record's owner (`public` by default, `my_account`, or `curators`), and the **Group** is the computational-method slug (e.g., `qe:dft:gga:pbe`) the elemental Total Energies were calculated under. + +**init-element-index** / **check-te-for-elemental-materials-loop** / **assign-current-element** — A loop construct that iterates over each unique element present in the compound. + +**io-te-for-an-element** — An [I/O unit]({{ reference_url }}/workflows/components/units/#i/o) that queries the platform's REST API to retrieve the pre-calculated `total_energy` property for the current element's standard state reference material, filtered by the Group and Source set above, and sorts by precision to find the most appropriate reference value. + +**assign-formation-energy** (in the **Calculate Formation Energy** subworkflow) — Uses [Python]({{ reference_url }}/software-directory/scripting/python/overview/) logic to subtract the sum of the elemental reference energies (scaled by stoichiometry) from the compound's total energy, yielding the final formation energy. + +
+ +## 3. Select the workflow + +[Workflows]({{ reference_url }}/workflows/overview/) for calculating formation energy with Quantum ESPRESSO can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into your account-owned [collection]({{ reference_url }}/accounts/collections/). + +In the Job Designer, [select]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) the Formation Energy workflow and add it to the job. + +![Job Designer workflow selection for Formation Energy](/images/tutorials/formation_energy/formation-energy-workflow-selection.png) + +## 4. Set Group and Source of Properties + +Inside the **Resolve Total Energies for Elemental Materials** subworkflow (not the earlier **Get Elemental Materials** subworkflow, which only resolves the elemental reference *materials* — not their total energies), switch to the **Detailed view** tab. There are two critical [assignment units]({{ reference_url }}/workflows/components/units/#assignment) that must be configured correctly: + +**assign-source-of-te-for-an-element**: This unit sets who owns the elemental Total Energy record to search for — `'public'` by default, or `'my_account'`/`'curators'` if you calculated the elemental references yourself or want curated results only. This is unrelated to Standata: Standata is only where the elemental reference *materials* (structures) come from; the Source setting is about who calculated the *total energy property* on those materials. + +![Job Designer source assignment for Formation Energy](/images/tutorials/formation_energy/formation-energy-assign-te-source-unit.png) + +![Unit settings for assign-source-of-te-for-an-element](/images/tutorials/formation_energy/formation-energy-assign-te-source.png) + +**assign-group-for-material**: This unit sets the property group (e.g., `qe:dft:gga:pbe`) to filter the elemental Total Energy results by computational method. The group selected here must match the property group of the elemental total energies you calculated previously. + +## 5. Set parameters + +In the workflow unit settings, ensure the [k-point grid]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) is sufficiently dense for your desired accuracy. A high KPPRA (k-points per reciprocal atom) is typically required for accurate formation energies. + +!!!important "Precision Consistency" + The precision settings (e.g., KPPRA, kinetic energy cutoff) used for the compound material's SCF calculation must match the precision settings used to calculate the elemental reference energies. The `io-te-for-an-element` unit does not verify this for you — it simply picks the highest-precision matching reference it finds, so a mismatch will silently produce an incorrect formation energy. + +![Job Designer parameter configuration for Formation Energy](/images/tutorials/formation_energy/formation-energy-parameters.png) + +## 6. Submit the job + +Once all parameters are set, navigate to the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) to verify the compute resource allocation, then [submit]({{ interface_url }}/jobs/actions/run/) the job. + +![Job Designer compute tab for Formation Energy](/images/tutorials/formation_energy/formation-energy-compute-tab.png) + +## 7. Examine the results + +Once the job completes, navigate to the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of the [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). The **Formation Energy** property will be displayed. More negative values indicate greater thermodynamic stability relative to the elemental standard states. + + diff --git a/lang/en/docs/tutorials/dft/thermodynamic/interfacial-energy.md b/lang/en/docs/tutorials/dft/thermodynamic/interfacial-energy.md new file mode 100644 index 000000000..9f96aa02d --- /dev/null +++ b/lang/en/docs/tutorials/dft/thermodynamic/interfacial-energy.md @@ -0,0 +1,67 @@ +# Calculate Interfacial Energy + +This tutorial explains how to calculate the interfacial energy between a substrate material and a film material using [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT) with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/). + +## 1. Create the materials + +To calculate interfacial energy, you need an interface structure that combines both the substrate and the film, as well as the individual substrate and film materials in their bulk forms. + +1. Create the substrate and film structures using the [Materials Designer]({{ interface_url }}/materials-designer/overview/). +2. Create the combined interface structure using the [Interface Builder]({{ interface_url }}/materials-designer/header-menu/advanced/interface/). +3. Ensure that the total energy for both the standalone substrate and the standalone film has been calculated with the same precision parameters (e.g., KPPRA, kinetic energy cutoffs) that you plan to use for the interface calculation. + +## 2. Understand the workflow structure + +
+ Expand to view unit details + +The interfacial energy [workflow]({{ reference_url }}/workflows/overview/) is composed of several [subworkflows]({{ reference_url }}/workflows/components/subworkflows/) that load the materials, fetch their pre-calculated total energies, and compute the interface energy. + +### 1. Load Interface Material +- Loads the combined interface material into the workflow using `set-material-index` and `io-material`. + +### 2. Load Substrate Material +- Loads the standalone substrate material into the workflow to be used as a reference. + +### 3. Fetch Total Energy for Substrate Material +- Looks up the substrate material's own most recently finished Total Energy job and extracts its highest-precision `total_energy` property using `io-bulk-te-job` and `io-te-bulk`. Unlike the Formation Energy and Defect Formation Energy workflows, there is no Group or Source assignment unit to configure here — the lookup is tied directly to the substrate material you submitted, not to a property group or an owner filter. + +### 4. Load Film Material +- Loads the standalone film material into the workflow. + +### 5. Fetch Total Energy for Film Material +- Same lookup as above, applied to the film material. + +### 6. Compute Interfacial Energy +- **pw_scf**: Performs a self-consistent field (SCF) calculation to determine the total energy of the combined interface structure. +- **assign-interfacial-energy**: Uses [Python]({{ reference_url }}/software-directory/scripting/python/overview/) to compute the interfacial energy by subtracting the substrate and film reference energies from the total energy of the interface, normalized by the interface area. + +
+ +## 3. Select the workflow and create the job + +This is a **multi-material** workflow: the job must be submitted with exactly three materials, in this order: + +1. **Interface** (position 0) — its total energy is computed by the job itself. +2. **Substrate** (position 1) — its total energy is fetched from that material's own most recently finished Total Energy job. +3. **Film** (position 2) — same as the substrate. + +Both the substrate's and film's Total Energy jobs must already exist on the platform before you submit this job (see [step 1](#1-create-the-materials)). + +1. Open the [Job Designer]({{ interface_url }}/jobs-designer/overview/) and add the interface material first, then the substrate, then the film, so they occupy positions 0, 1, and 2 respectively. +![Material Selection](/images/tutorials/interfacial_energy/interfacial-energy-material-selection.png) +2. [Workflows]({{ reference_url }}/workflows/overview/) for interfacial energy calculations with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/). +3. Once imported, [select]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) the Interfacial Energy workflow and add it to your job. +![Workflow Selection](/images/tutorials/interfacial_energy/interfacial-energy-workflow-selection.png) + +## 4. Submit the job + +Before [submitting]({{ interface_url }}/jobs/actions/run/) the [job]({{ reference_url }}/jobs/overview/), review the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) to verify the compute parameters. Ensure that the K-point grid and cutoffs match those used for the substrate and film reference calculations. + +![Job Designer compute tab for Interfacial Energy](/images/tutorials/interfacial_energy/interfacial-energy-parameters.png) + +## 5. Examine the results + +Once the job completes, navigate to the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of the [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). The **Interfacial Energy** property will be displayed. + +![Job Viewer results for Interfacial Energy](/images/tutorials/interfacial_energy/interfacial-energy-result.png) diff --git a/lang/en/docs/tutorials/dft/thermodynamic/surface-energy.md b/lang/en/docs/tutorials/dft/thermodynamic/surface-energy.md index f6f25acf0..f6130ee50 100644 --- a/lang/en/docs/tutorials/dft/thermodynamic/surface-energy.md +++ b/lang/en/docs/tutorials/dft/thermodynamic/surface-energy.md @@ -1,99 +1,84 @@ # Calculate Surface Energy -This tutorial page explains how to calculate the [surface energy](../../../properties-directory/scalar/surface-energy.md) of [materials](../../../materials/overview.md) based on [Density Functional Theory](../../../models-directory/dft/overview.md). We consider crystalline gold in its standard equilibrium face-centred cubic (fcc) crystal structure, and use [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) as our main simulation engine during this tutorial. +This tutorial explains how to calculate the [surface energy]({{ reference_url }}/properties-directory/scalar/surface-energy/) of crystalline gold (Au) in its equilibrium face-centred cubic (fcc) crystal structure using [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT) with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/). -!!!note "Quantum ESPRESSO version considered in this tutorial" - The present tutorial is written for Quantum ESPRESSO at versions 5.2.1, 5.4.0, 6.0.0 or 6.3. +!!!note "Quantum ESPRESSO version" + This tutorial applies to Quantum ESPRESSO versions 5.2.1, 5.4.0, 6.0.0, 6.3, and later. -More information on the conduction of surface energy calculations, together with their results on a sample set of materials, can be found in Ref. [^1]. +Further information on surface energy calculations and results on a sample material set can be found in Ref. [^1]. -## Create Surface -In order to create a surface of crystalline gold using the [Materials Designer Interface](../../../materials-designer/overview.md), the reader should follow the instructions contained in [this page](../../../materials-designer/header-menu/advanced/surface-slab.md). +## 1. Create the surface -For the present example, we consider a simple surface for Au 111 and 50% vacuum ratio, keeping the supercell dimensions along x-y to one and the slab thickness to 3 layers (corresponding to roughly 10 Angstroms). This gives a total of 3 atoms of gold within our surface. +A surface of crystalline gold is created using the [Materials Designer]({{ interface_url }}/materials-designer/overview/) following the instructions in [this page]({{ interface_url }}/materials-designer/header-menu/advanced/surface-slab/). -## Workflow Structure +For this example, a simple Au (111) surface with 50% vacuum ratio is used, keeping the supercell dimensions along x-y to 1 and the slab thickness to 3 layers (~10 Å). This yields a total of 3 gold atoms. -We shall now describe the computational implementation of Surface Energy calculations on our platform, illustrating the various [unit](../../../workflows/components/units.md) steps constituting the overall [Workflow](../../../workflows/overview.md). Each unit will now be reviewed in turn: -### io-slab +## 2. Understand the workflow structure -This [input/output type of unit](../../../workflows/components/units.md#i/o) launches a request to the account-owned [collection](../../../accounts/collections.md) of materials, in order to retrieve the relevant identification information about the material under investigation. This request is made via the corresponding endpoint address of the [Rest API](../../../rest-api/overview.md), and is directed at the material entry with id given by the "MATERIAL_ID" keyword. The material information is then assigned to the variable "DATA". +
+ Expand to view unit details -### slab +The [workflow]({{ reference_url }}/workflows/overview/) is composed of the following [units]({{ reference_url }}/workflows/components/units/): -This [assignment unit](../../../workflows/components/units.md#assignment) assigns the above-mentioned material information stored under the "DATA" variable to a new variable called "SLAB". The previous unit where DATA was first defined is specified through reference to its scope. +**io-slab** — An [I/O unit]({{ reference_url }}/workflows/components/units/#i/o) that retrieves material identification information from the account-owned [collection]({{ reference_url }}/accounts/collections/) via the [REST API]({{ developers_url }}/rest-api/overview/). -### io-bulk +**slab** — An [assignment unit]({{ reference_url }}/workflows/components/units/#assignment) that stores the material information as the "SLAB" variable. -This i/o unit sends a query to the account-owned collection of materials, looking again for the "MATERIAL_ID" keyword identifying the material under consideration. This id is stored as metadata within the previously-defined "SLAB" variable. +**io-bulk** — Queries the collection for the bulk material identifier stored as metadata within the "SLAB" variable. -### bulk +**bulk** — Assigns the bulk material data to the "BULK" variable. -This assignment unit assigns the new variable "BULK" to the identification data of the material extracted by the previous unit, as defined by its scope. Hence at this stage both the "SLAB" and "BULK" variables have been assigned to the same material id. +**assert-bulk** — Verifies that the bulk material exists in the collection. If not, an error is raised. -### assert-bulk +!!!tip "Missing bulk data" + If the bulk material information is not already in the collection, a [Total Energy]({{ reference_url }}/properties-directory/scalar/total-energy/) calculation can be prepended to the surface energy workflow. -This assertion unit makes sure that the material previously assigned to the "BULK" variable indeed exists inside the account owned collection of materials. Consequently, if the Bulk material does not have any information in the database, an error message is raised that the corresponding surface energy cannot be calculated. +**io-e-bulk** — Extracts the [Total Energy]({{ reference_url }}/properties-directory/scalar/total-energy/) property of the bulk material. -!!!tip "Inclusion of Bulk material properties calculation in Workflow" - In case the relevant bulk material information is not already contained in the collection database, such property calculations can readily be included at the start of the surface energy workflow. The only relevant bulk material information that is necessary for computing the surface energy is the [Total Energy](../../../properties-directory/scalar/total-energy.md) of the material. +**e-bulk** — Assigns the bulk total energy to the "E_BULK" variable. -### io-e-bulk +**assert-e-bulk** — Asserts that the bulk total energy exists in the collection. -Here, the information about the relevant properties ([Total Energy](../../../properties-directory/scalar/total-energy.md)) of the bulk material is extracted. The "exabyteId" is also necessary in this case to retrieve the appropriate properties information. +**surface** — Uses [Python]({{ reference_url }}/software-directory/scripting/python/overview/) logic to compute the magnitude of the vector normal to the surface. -### e-bulk +**n-bulk / n-slab** — Count the total number of atoms in the bulk and slab materials respectively. -At this stage, we assign the new variable "E_BULK" to the total energy of the bulk material retrieved in the previous unit. +**pw_scf** — Performs an SCF computation to calculate the slab energy. Since the slab is much thinner than it is wide, the [k-point grid]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) is set with a smaller z-dimension (e.g. 8 × 8 × 1). -### assert-e-bulk +**e-slab** — Assigns the slab energy to the "E_SLAB" variable. -This unit asserts that the total energy of the bulk material is indeed listed within the collection database. +**surface-energy** — Computes the final surface energy from "E_BULK" and "E_SLAB" according to the [formula]({{ reference_url }}/properties-directory/scalar/surface-energy/). -### surface +
-Assignment units in general allow for [Python](../../../software-directory/scripting/python/overview.md) logic and expressions to be executed. Here, we take advantage of this to compute the magnitude of the vector normal to the surface. -### n-bulk and n-slab +## 3. Select the workflow and create the job -In these two units, the total number of atoms in the bulk and slab material respectively are counted. +[Workflows]({{ reference_url }}/workflows/overview/) for surface energy calculations with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/). The workflow can then be [selected]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) and added to the [job being created]({{ interface_url }}/jobs-designer/workflow-tab/). -### pw_scf -A ground-state energy self-consistent field (SCF) computation is finally performed with [DFT](../../../models-directory/dft/overview.md) in order to calculate the energy of the slab material. Since the slab is by definition always much thinner than it is wide in terms of its cross-sectional area, the size of the [grid of k-points](../../../models/auxiliary-concepts/reciprocal-space/sampling.md) can be set to be smaller in the $z$ dimension than across the $x-y$ cross-section (e.g. 8 x 8 x 1). +## 4. Submit the job -### e-slab +Before [submitting]({{ interface_url }}/jobs/actions/run/) the [job]({{ reference_url }}/jobs/overview/), review the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) of [Job Designer]({{ interface_url }}/jobs-designer/overview/) to verify the [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/). The gold slab is a relatively small structure, so 4 CPUs and a few minutes of runtime are sufficient. -The variable "E_SLAB" is assigned to the energy of the slab material computed in the previous step. -### surface-energy +## 5. Examine the results -Finally, the last unit gathers together the previously-defined variables "E_BULK" and "E_SLAB" in order to compute the final value for the surface energy of the material under investigation, according to the formula defined [in this page](../../../properties-directory/scalar/surface-energy.md). +Once all [units]({{ reference_url }}/workflows/components/units/) complete, the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) displays the surface energy for Au (0.049 eV/Ų). This result is in good agreement with the tabulated value for the same surface orientation [^2]. -## Choose Workflow and Create Job -[Workflows](../../../workflows/overview.md) for calculating the surface energy through [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) can readily be [imported](../../../workflows/actions/copy-bank.md) from the [Workflows Bank](../../../workflows/bank.md) into the account-owned [collection](../../../accounts/collections.md). This workflow can later be [selected](../../../jobs-designer/actions-header-menu/select-workflow.md) and added to the [Job being created](../../../jobs-designer/workflow-tab.md). +## 6. Video walkthrough -## Submit Job - -Before [submitting](../../../jobs/actions/run.md) the [job](../../../jobs/overview.md), the user should click on the ["Compute" tab](../../../jobs-designer/compute-tab.md) of [Job Designer](../../../jobs-designer/overview.md) and inspect the [compute parameters](../../../infrastructure/compute/parameters.md) included therein. Our slab of gold is a relatively small structure, so four CPUs and a few minutes of calculation runtime should be sufficient. - -## Examine results - -When all aforementioned [units](../../../workflows/components/units.md) computations are complete at the end of Job execution, switching to the [Results tab](../../../jobs/ui/results-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md) will show the results of the simulation, including the surface energy found for Au (0.049 eV/A^2). This final result is in good agreement with the tabulated value for the same surface orientation of gold [^2]. - -## Animation - -We demonstrate the above-mentioned steps involved in the creation and execution of a Surface Energy computation workflow on gold using the [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) simulation engine in the following animation. +The animation below demonstrates the full surface energy workflow on gold using Quantum ESPRESSO.
-## Links -[^1]: [Tran R., Xu Z., Radhakrishnan B., Winston D., Sun W., Persson K.A., Ong S.P.: "Surface energies of elemental crystals"; Nature Sci. Data., 3 (2016)](https://www.nature.com/articles/sdata201680) +## 7. Links -[^2]: [Crystalium Surfaces Database, Website](http://crystalium.materialsvirtuallab.org/) +[^1]: [Tran R., Xu Z., Radhakrishnan B., Winston D., Sun W., Persson K.A., Ong S.P.: "Surface energies of elemental crystals"; Nature Sci. Data., 3 (2016)](https://www.nature.com/articles/sdata201680) +[^2]: [Crystalium Surfaces Database](http://crystalium.materialsvirtuallab.org/) diff --git a/lang/en/docs/tutorials/dft/upload-pseudopotential.md b/lang/en/docs/tutorials/dft/upload-pseudopotential.md index cc97ff95e..80aac6891 100644 --- a/lang/en/docs/tutorials/dft/upload-pseudopotential.md +++ b/lang/en/docs/tutorials/dft/upload-pseudopotential.md @@ -1,38 +1,46 @@ -This page explains how to upload a custom pseudopotential during a simulation setup. +# Upload a Custom Pseudopotential -# Default pseudopotentials +This page explains how to upload a custom pseudopotential during simulation setup. -We have a set of default pseudopotentials available for each application. Such a set is meant to provide flexibility in choosing chemical elements and reliability of results. For Quantum ESPRESSO we choose [gbrv v1.5 potentials from Rutgers](#links). For VASP we support v5.2 and v5.4 pseudopotential sets. -# Navigate into Job Designer +## 1. Default pseudopotentials -We will assume that reader knows how to navigate into the job designer and open the workflow tab (more information on that available in [quickstart](../../getting-started/run-first-simulation/web-interface.md) and [ui overview](../../ui/overview.md). +A set of default pseudopotentials is available for each application. The set is designed to provide flexibility in choosing chemical elements and reliability of results. For Quantum ESPRESSO, the platform uses [GBRV v1.5 potentials from Rutgers](#links). For VASP, v5.2 and v5.4 pseudopotential sets are supported. -# Choose alternative pseudopotential -When on the workflow tab, navigate to the "Method" section and expand the "Pseudopotential" section. You will see alist of all chemical elements that the constitute materials currently included into the job (ie. if there are 2 materials - Si FCC and Ge FCC you will see 2 entries, same will happen if there is one SiGe compound chosen as the job material). +## 2. Navigate to Job Designer -Next click on the input field (delete text inside it if needed) to see the list of available pseudopotenial options for each element. You may type text in the input field to narrow down the list (eg. type "GW" or "1.0"). The items in the list show the basename of the pseudopotential file and the full path to it (as it will be accessed during the calculation). +This tutorial assumes familiarity with navigating into the [Job Designer]({{ interface_url }}/jobs-designer/overview/) and opening the [workflow tab]({{ interface_url }}/jobs-designer/workflow-tab/). -!!! note "Name and Path" - Expert users can use pseudopotential name and path when editing the input for workflow units. -Click on one of the items in the list to select it as the pseudopotential for the chemical element in question. +## 3. Choose an alternative pseudopotential -# Upload pseudopotential +On the workflow tab, navigate to the *Method* section and expand the *Pseudopotential* section. A list of all chemical elements that constitute the materials currently included in the job is displayed (e.g. if there are 2 materials — Si FCC and Ge FCC — two entries appear; the same applies if a single SiGe compound is chosen as the job material). -Users may upload their custom pseudopotentials like it is demonstrated in the animation below. We encourage users to correctly indicate the exchange correlation scheme and pseudopotential type during upload as this information is likely to be useful during their future work. +Next, click the input field (delete existing text if needed) to see the list of available pseudopotential options for each element. Text can be typed in the input field to narrow down the list (e.g. type "GW" or "1.0"). The items in the list show the basename of the pseudopotential file and the full path to it (as it is accessed during the calculation). -Uploaded pseudopotentials will be automatically assoticated with the corresponding element and will be available during the job runtime at the path indicated by selector item (see video below). +!!!note "Name and Path" + Expert users can use the pseudopotential name and path when editing the input for workflow units. -# Demonstration +Click one of the items in the list to select it as the pseudopotential for the chemical element in question. -The animation below demonstrates the user experience for choosing an alternative pseudopotential, filtering the list of available pseudopotentials, uploading a custom file and navigating to it in "Dropbox" page. + +## 4. Upload a pseudopotential + +Custom pseudopotentials can be uploaded as demonstrated in the animation below. It is recommended to correctly indicate the exchange-correlation scheme and pseudopotential type during upload, as this information is useful for future work. + +Uploaded pseudopotentials are associated with the corresponding element and become available during the job runtime at the path indicated by the selector item (see animation below). + + +## 5. Demonstration + +The animation below demonstrates the process of choosing an alternative pseudopotential, filtering the list of available pseudopotentials, uploading a custom file, and navigating to it on the *Dropbox* page. -# Links + +## 6. Links 1. [Quantum ESPRESSO UPF pseudopotentials list](http://www.quantum-espresso.org/pseudopotentials/) 1. [GBRV pseudopotential set](https://www.physics.rutgers.edu/gbrv/) -1. [Vienna ab-inito simulation package, Website](https://www.vasp.at/) +1. [Vienna Ab-initio Simulation Package, Website](https://www.vasp.at/) diff --git a/lang/en/docs/tutorials/dft/vibrational/overview.md b/lang/en/docs/tutorials/dft/vibrational/overview.md index 6a8aefa31..f2b627143 100644 --- a/lang/en/docs/tutorials/dft/vibrational/overview.md +++ b/lang/en/docs/tutorials/dft/vibrational/overview.md @@ -1,15 +1,15 @@ # Vibrational Properties Tutorials -In the present section, we introduce the most common operations supported on our platform for performing **vibrational properties** computations on [materials](../../../materials/overview.md), implemented through the [Density Functional Theory model](../../../models-directory/dft/overview.md). +This section covers tutorials for computing **vibrational properties** of [materials]({{ reference_url }}/materials/overview/) using [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT). ## [Zero Point Energy](zero-point-energy.md) -We review the procedure for computing the [Zero Point Energy](../../../properties-directory/scalar/zero-point-energy.md) of crystalline samples [in this tutorial](zero-point-energy.md). +[This tutorial](zero-point-energy.md) demonstrates how to compute the [Zero Point Energy]({{ reference_url }}/properties-directory/scalar/zero-point-energy/) of crystalline samples. -## [Phonon Dispersion Curve and Density of States](phonon-dispersion-dos.md) +## [Phonon Dispersion Curves and Density of States](phonon-dispersion-dos.md) -We review the procedure for computing the [vibrational phonon dispersion curve](../../../properties-directory/non-scalar/phonon-dispersions.md) and [Phonon Density of States](../../../properties-directory/non-scalar/phonon-dos.md) of material samples [in this tutorial](phonon-dispersion-dos.md). +[This tutorial](phonon-dispersion-dos.md) covers the computation of [phonon dispersion curves]({{ reference_url }}/properties-directory/non-scalar/phonon-dispersions/) and [Phonon Density of States]({{ reference_url }}/properties-directory/non-scalar/phonon-dos/). ## [Phonon Calculations with the Grid Method](phonons-grid.md) -[This tutorial page](phonons-grid.md) explains how to calculate the [Phonon Dispersion Curves](../../../properties-directory/non-scalar/phonon-dispersions.md) and [Phonon Density of States](../../../properties-directory/non-scalar/phonon-dos.md) of materials, based on the Grid Method for the distributed computing of the lattice vibrational modes. +[This tutorial](phonons-grid.md) explains how to calculate phonon dispersions and density of states using the Grid Method for distributed parallel computation of lattice vibrational modes. diff --git a/lang/en/docs/tutorials/dft/vibrational/phonon-dispersion-dos.md b/lang/en/docs/tutorials/dft/vibrational/phonon-dispersion-dos.md index 9e0a7227e..048c156f6 100644 --- a/lang/en/docs/tutorials/dft/vibrational/phonon-dispersion-dos.md +++ b/lang/en/docs/tutorials/dft/vibrational/phonon-dispersion-dos.md @@ -1,45 +1,48 @@ # Phonon Dispersions and Density of States Calculation -This tutorial page explains how to calculate the [Phonon Dispersion Curves](../../../properties-directory/non-scalar/phonon-dispersions.md) and [Phonon Density of States](../../../properties-directory/non-scalar/phonon-dos.md) of materials based on [Density Functional Theory](../../../models-directory/dft/overview.md). We will be studying crystalline Silicon in the standard cubic-diamond crystal structure, and we will use [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) as our simulation engine. +This tutorial explains how to calculate the [Phonon Dispersion Curves]({{ reference_url }}/properties-directory/non-scalar/phonon-dispersions/) and [Phonon Density of States]({{ reference_url }}/properties-directory/non-scalar/phonon-dos/) of crystalline silicon in its cubic-diamond crystal structure using [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT) with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/). -!!!note "Quantum ESPRESSO version considered in this tutorial" - The present tutorial is written for Quantum ESPRESSO at versions 5.2.1, 5.4.0, 6.0.0 or 6.3. +!!!note "Quantum ESPRESSO version" + This tutorial applies to Quantum ESPRESSO versions 5.2.1, 5.4.0, 6.0.0, 6.3, and later. -## Create Job -Silicon in its cubic-diamond crystal structure is the [default material](../../../materials/default.md) that is shown on [new job creation](../../../jobs-designer/overview.md), unless this default was [changed](../../../entities-general/actions/set-default.md) by the user following [account](../../../accounts/overview.md) creation. If silicon is still the default choice, it will as such be automatically loaded at the moment of the [opening](../../../jobs/actions/create.md) of [Job Designer](../../../jobs-designer/overview.md). +## 1. Create the job -## Choose Workflow +Silicon in its cubic-diamond crystal structure is the [default material]({{ reference_url }}/materials/default/) loaded on [new job creation]({{ interface_url }}/jobs-designer/overview/), unless the default was [changed]({{ interface_url }}/entities-general/actions/set-default/) after [account]({{ reference_url }}/accounts/overview/) creation. -[Workflows](../../../workflows/overview.md) for calculating the [Phonon Dispersion Curves](../../../properties-directory/non-scalar/phonon-dispersions.md) and [Density of States](../../../properties-directory/non-scalar/phonon-dos.md) of [materials](../../../materials/overview.md) with [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) can readily be [imported](../../../workflows/actions/copy-bank.md) from the [Workflows Bank](../../../workflows/bank.md) into the account-owned [collection](../../../accounts/collections.md). This workflow can later be [selected](../../../jobs-designer/actions-header-menu/select-workflow.md) and added to the [Job being created](../../../jobs-designer/workflow-tab.md). -## Set Sampling in Reciprocal Space +## 2. Select the workflow -It is critical to have a high [q-point density](../../../models/auxiliary-concepts/reciprocal-space/sampling.md#other-types-of-reciprocal-space-grids) in order to resolve enough details for the phonon dispersion plot. +[Workflows]({{ reference_url }}/workflows/overview/) for phonon calculations with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/). The workflow can then be [selected]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) and added to the [job being created]({{ interface_url }}/jobs-designer/workflow-tab/). -The Phonon calculation workflow based on Quantum ESPRESSO is composed of multiple [units](../../../workflows/components/units.md). The first unit specifies the settings for the self-consistent calculation of the energy eigenvalues and wave functions. The subsequent units are narrated in detail in the theoretical explanation contained in Ref. [^1] of [this page](../../../models/auxiliary-concepts/reciprocal-space/sampling.md). -We set the size of the [grid of q-points (q-grid)](../../../models/auxiliary-concepts/reciprocal-space/sampling.md#other-types-of-reciprocal-space-grids) to 3 x 3 x 3 under the [Important Settings](../../../workflow-designer/subworkflow-editor/important-settings.md) of [Workflow Designer](../../../workflow-designer/overview.md). This provides a dense enough q-point sampling in order to resolve the fine features present within the output of the phonon dispersion computation. In order to make the q- and k-point grids commensurate and make the phonon calculation less computationally demanding, we also reduce the size of the grid of electronic k-points from its original default value to 6 x 6 x 6. +## 3. Set sampling in reciprocal space -In addition, the associated "interpolated" grid or [i-grid](../../../models/auxiliary-concepts/reciprocal-space/sampling.md#other-types-of-reciprocal-space-grids) necessary for performing the transformation to and from the reciprocal and real space, and subsequent interpolation, should be set to 18 x 18 x 18. +A high [q-point density]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/#other-types-of-reciprocal-space-grids) is critical for resolving phonon dispersion details. -Finally, we also apply the recommended [q-point path](../../../models/auxiliary-concepts/reciprocal-space/paths.md) to effectively sample the vibrational states throughout the Brillouin Zone of the crystal, based on the crystal symmetry. +The phonon workflow contains multiple [units]({{ reference_url }}/workflows/components/units/). The first unit configures the self-consistent calculation of energy eigenvalues and wave functions. Subsequent units are described in the theoretical explanation in Ref. [^1] of [this page]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/). -## Submit Job +Set the [q-point grid]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/#other-types-of-reciprocal-space-grids) to 3 × 3 × 3 under [Important Settings]({{ interface_url }}/workflow-designer/subworkflow-editor/important-settings/). Also reduce the k-point grid from its default to 6 × 6 × 6 to make the q- and k-point grids commensurate and reduce computational cost. -Before [submitting](../../../jobs/actions/run.md) the [job](../../../jobs/overview.md), the user should click on the ["Compute" tab](../../../jobs-designer/compute-tab.md) of [Job Designer](../../../jobs-designer/overview.md) and examine the [compute parameters](../../../infrastructure/compute/parameters.md) included therein. +The associated [i-grid]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/#other-types-of-reciprocal-space-grids) for reciprocal/real-space transformation and interpolation should be set to 18 × 18 × 18. The recommended [q-point path]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/paths/) should also be applied to sample the vibrational states across the Brillouin Zone. -Phonon calculations are quite computationally expensive and therefore, despite Silicon being a small structure, with the aforementioned settings for the sampling grids the user should account for at least 45 minutes of calculation runtime executed on 16 compute cores for example. -## Examine Final Results +## 4. Submit the job -When all [unit](../../../workflows/components/units.md) computations are complete at the end of Job execution, switching to the [Results tab](../../../jobs/ui/results-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md) will show the [phonon lattice vibrations](../../../properties-directory/non-scalar/phonon-dispersions.md) of silicon, plotted as a dispersion curve on the [q-point path](../../../models/auxiliary-concepts/reciprocal-space/paths.md) chosen in the preceding steps. +Before [submitting]({{ interface_url }}/jobs/actions/run/) the [job]({{ reference_url }}/jobs/overview/), review the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) of [Job Designer]({{ interface_url }}/jobs-designer/overview/) to verify the [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/). -The plot for the [Phonon Density of States](../../../properties-directory/non-scalar/phonon-dos.md) can also be retrieved in the [Results tab](../../../jobs/ui/results-tab.md), directly above the dispersion curve. +!!!tip "Computational cost" + Phonon calculations are computationally demanding. Despite silicon being a small structure, the settings above require at least 45 minutes on 16 compute cores. -## Animation -We demonstrate the above-mentioned steps involved in the creation and execution of a phonon lattice vibration calculation for silicon, using the [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) simulation engine, in the following animation. +## 5. Examine the results + +Once all [units]({{ reference_url }}/workflows/components/units/) complete, the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) displays the [phonon dispersion curves]({{ reference_url }}/properties-directory/non-scalar/phonon-dispersions/) and the [Phonon Density of States]({{ reference_url }}/properties-directory/non-scalar/phonon-dos/) (directly above the dispersion curve). + + +## 6. Video walkthrough + +The animation below demonstrates the full phonon calculation workflow on silicon using Quantum ESPRESSO.
diff --git a/lang/en/docs/tutorials/dft/vibrational/phonons-grid.md b/lang/en/docs/tutorials/dft/vibrational/phonons-grid.md index 260df0d4e..deb502205 100644 --- a/lang/en/docs/tutorials/dft/vibrational/phonons-grid.md +++ b/lang/en/docs/tutorials/dft/vibrational/phonons-grid.md @@ -1,85 +1,71 @@ -# Phonon Dispersions and Density of States Calculation on Grid +# Phonon Dispersions and Density of States on Grid -This tutorial page explains how to calculate the [Phonon Dispersion Curves](../../../properties-directory/non-scalar/phonon-dispersions.md) and [Phonon Density of States](../../../properties-directory/non-scalar/phonon-dos.md) of materials based on [Density Functional Theory](../../../models-directory/dft/overview.md). We will be studying crystalline Silicon in the standard cubic-diamond crystal structure, and we will use [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) as our simulation engine. +This tutorial explains how to calculate the [Phonon Dispersion Curves]({{ reference_url }}/properties-directory/non-scalar/phonon-dispersions/) and [Phonon Density of States]({{ reference_url }}/properties-directory/non-scalar/phonon-dos/) of crystalline silicon using the **Grid Method** with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/). -!!!note "Quantum ESPRESSO version considered in this tutorial" - The present tutorial is written for Quantum ESPRESSO at versions 5.2.1, 5.4.0, 6.0.0 or 6.3. +!!!note "Quantum ESPRESSO version" + This tutorial applies to Quantum ESPRESSO versions 5.2.1, 5.4.0, 6.0.0, 6.3, and later. -What sets the present tutorial apart from the [other tutorial](phonon-dispersion-dos.md) on phonon calculations is the employment of the "Grid Method" for computing the vibrational properties of materials, which is reviewed in the subsequent paragraph. This method is based on a [map type workflow](../../../workflows/components/maps.md), where multiple branches are executed in parallel as separate independent [Jobs](../../../jobs/overview.md), with the consequent gain in computational efficiency and overall speed of the phonon calculation. More information on this method, together with a demonstration of its application and results on a sample set of materials, can be found in Ref. [^1]. +The Grid Method is based on a [map type workflow]({{ reference_url }}/workflows/components/maps/) where multiple branches execute in parallel as separate [jobs]({{ reference_url }}/jobs/overview/), providing faster overall phonon calculations. More information and results on a sample material set are available in Ref. [^1]. For the alternative serial approach, see the [standard phonon tutorial](phonon-dispersion-dos.md). -## The Grid Method for Phonon Calculations -The Grid Method allows for an efficient **parallelization** of the tasks for calculating the individual vibrational modes. This method optimizes the corresponding [workflow](../../../workflows/overview.md) in order to obtain the frequencies for each individual **symmetry-irreducible representation** [^2] of the phonon lattice perturbations in parallel. +## 1. Understand the Grid Method -### Steps Involved in Grid Method +The Grid Method parallelizes the computation of individual vibrational modes by optimizing the [workflow]({{ reference_url }}/workflows/overview/) to calculate frequencies for each **symmetry-irreducible representation** [^2] of phonon lattice perturbations in parallel. -We thus implement a grid-parallel workflow for the calculation of the phonon dynamical matrices, initially explained in the first reference cited [in this page](../../../models/auxiliary-concepts/reciprocal-space/sampling.md). During the actual phonon calculation part of the workflow, the following steps happen: +The workflow follows a **map-reduce** pattern: -- First, the irreducible representations for the vibrational modes (irreps) are generated, based on the [sampling grid in the reciprocal space](../../../models/auxiliary-concepts/reciprocal-space/sampling.md) (**q-point grid**). +1. Irreducible representations (irreps) are generated based on the [q-point grid]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/#other-types-of-reciprocal-space-grids). +2. A separate calculation is prepared and submitted for each irrep-q-point pair via a [Map]({{ reference_url }}/workflows/components/maps/) (**map stage**). +3. After all pair calculations complete, the dynamical matrices are collected and aggregated, and phonon dispersions and DOS are calculated (**reduce stage**). -- Second, a separate calculation is prepared and submitted for execution in parallel for each pair or irreducible representation and q-point, via the implementation of a [Map](../../../workflows/components/maps.md) for performing a distributed calculation (**"map" stage**). - -- Finally, after the calculations for all irreps-q points pairs are finished, the dynamical matrices are collected and aggregated together, and phonon dispersions and density of states are calculated (**"reduce" stage**). - -Thus, we employ a **"map-reduce"** general type of logic and scenario within the overall workflow, where the individual calculation tasks are performed independently and in parallel with one another. This allows for an improved efficiency and speedup of phonon calculations compared to the [more traditional serial approach](phonon-dispersion-dos.md), such that the limiting factor within the overall calculation is the longest run per individual irreducible representation-q point pair. - -### Schematic Visualization of Grid Method - -A schematic summary of the above workflow procedure is offered in the figure below. This flowchart depicts all different approaches to the calculation of the phonon dispersions and lattice vibrations. The approach used in the present tutorial is the rightmost one. Here, ”SCF” stands for the self consistent field preliminary calculation, ”ph.x” denotes the phonon calculations by means of Density Functional Perturbation Theory, and "irrep" is an irreducible representation of a vibrational phonon mode. +The limiting factor is the longest run per individual irrep-q-point pair. ![phonons grid method](../../../images/tutorials/phonons-grid.png "phonons grid method") -## Workflow Structure -We review now the different steps involved in implementing the above general Grid Phonon theoretical framework in an actual [Workflow](../../../workflows/overview.md) deployable on our platform. We shall consider the example case of the [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) modeling engine. +## 2. Understand the workflow structure -### 1. Preliminary SCF Calculation +The workflow contains five main [subworkflow]({{ reference_url }}/workflows/components/subworkflows/) steps: -The first [subworkflow step](../../../workflows/components/subworkflows.md) in the overall "Phonons Grid" Workflow is a standard self-consistent field (scf) total energy calculation, providing the ensuing steps of the workflow with the wavefunctions of the material structure under investigation. +### 2.1. Preliminary SCF calculation -For the sake of this example, we can set the [grid of special k-points](../../../models/auxiliary-concepts/reciprocal-space/sampling.md) to 6 x 6 x 6, under [Important Settings](../../../workflow-designer/subworkflow-editor/important-settings.md). +A standard self-consistent field (SCF) total energy calculation provides the wavefunctions. The [k-point grid]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) is set to 6 × 6 × 6 under [Important Settings]({{ interface_url }}/workflow-designer/subworkflow-editor/important-settings/). -### 2. Q-points and Irrep Generation +### 2.2. Q-points and irrep generation -The second subworkflow step ("ph-init-qpoints") is composed of a single [unit](../../../workflows/components/units.md), which consists in generating the [grid of q-points](../../../models/auxiliary-concepts/reciprocal-space/sampling.md#other-types-of-reciprocal-space-grids) over which the vibrational phonon modes calculations will be performed, for each irreducible representation of such modes. +The "ph-init-qpoints" subworkflow generates the [q-point grid]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/#other-types-of-reciprocal-space-grids) over which phonon calculations are performed. The q-grid must be a divisor of the k-grid — a q-grid of 2 × 2 × 2 is appropriate here. -The size of this q-grid should be a divisor of the size of the above-mentioned k-grid. Hence, a q-grid of 2 x 2 x 2 should suffice in this case, which can be set under [Important Settings](../../../workflow-designer/subworkflow-editor/important-settings.md). +### 2.3. Extract q-point/irrep pairs -### 3. Extraction of q-points/irrep pairs +The "espresso-xml-get-qpt-irr" subworkflow uses a [Python script]({{ reference_url }}/software-directory/scripting/python/overview/) to parse and extract q-points and irreducible representations from the Quantum ESPRESSO XML data. -The "espresso-xml-get-qpt-irr" subworkflow comprises a main [python script](../../../software-directory/scripting/python/overview.md), whose role is to parse and extract q-points and irreducible representations from the previously-generated Quantum ESPRESSO XML data. Each distinct combination of q-point and irrep is added as a separate entry to what follows. +### 2.4. Map distributed phonon calculation -### 4. Map Distributed Phonon Calculation +The [Map]({{ reference_url }}/workflows/components/maps/) subworkflow distributes parallel phonon calculations across each q-point/irrep pair. The q-grid under the "Important Settings" of the "ph-single-irr-qpt" map subworkflow should also be set to 2 × 2 × 2. -The ensuing subworkflow consists in the [Map](../../../workflows/components/maps.md) for performing the distributed parallel phonon calculations across each q-point/irrep pair extracted previously. The list of q-points/irrep pairs can be inspected under the "Data" tab of the Map editor interface. +### 2.5. Reduce and aggregate results -Care should be taken to set the q-grid under the "Important Settings" of the "ph-single-irr-qpt" map subworkflow again to 2 x 2 x 2, as in the previous steps. +The final "Reduce" subworkflow collects results from all independent pair calculations via "ph_grid_restart". The q-grid under [Important Settings]({{ interface_url }}/workflow-designer/subworkflow-editor/important-settings/) should again be 2 × 2 × 2. Results are then processed through the Quantum ESPRESSO "q2r" and "matdyn" [executables]({{ reference_url }}/software-directory/modeling/quantum-espresso/components/#executables). -### 5. Reduce and Aggregate Results -The final "Reduce" subworkflow collects together the results of the previous calculations over each independent q-point/irrep pair, via the "ph_grid_restart" unit. Here, the size of the q-grid under [Important Settings](../../../workflow-designer/subworkflow-editor/important-settings.md) should once again be set to the 2 x 2 x 2 value being considered in the present example. +## 3. Create and submit the job -These combined results are then used to complete the phonon dispersion and density of states calculation, through the help of the Quantum ESPRESSO "q2r" and "matdyn" [executables](../../../software-directory/modeling/quantum-espresso/components.md#executables). +"Phonon Map" [workflows]({{ reference_url }}/workflows/overview/) can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/). Follow the same instructions as in the [standard phonon tutorial](phonon-dispersion-dos.md) for creating and launching the job and inspecting results. -## Creating and Executing Job -"Phonon Map" [workflows](../../../workflows/overview.md) can readily be [imported](../../../workflows/actions/copy-bank.md) into the account-owned [collection](../../../accounts/collections.md) from the [Workflows Bank](../../../workflows/bank.md). - -Apart from this, the same procedural instructions as in the [other phonons calculation tutorial](phonon-dispersion-dos.md) should be followed for [creating and launching](../../../jobs-designer/overview.md) the corresponding grid-based phonon [Job](../../../jobs/overview.md) through our [Web Interface](../../../ui/overview.md), and for inspecting the associated results. +## 4. Video walkthrough -## Animation +The animation below demonstrates the Grid Method phonon calculation on crystalline silicon using Quantum ESPRESSO. -In the video animation below, we outline the procedure for creating and executing a phonon calculation job via the Grid Method. We conclude by inspecting the corresponding results for the [Phonon Dispersion Curves](../../../properties-directory/non-scalar/phonon-dispersions.md) and [Density of States](../../../properties-directory/non-scalar/phonon-dos.md), considering crystalline silicon as our demonstrative sample operated in conjunction with the [Quantum ESPRESSO](../../../software-directory/modeling/quantum-espresso/overview.md) simulation engine. - -!!!tip "Computational cost of phonon calculation" - Phonon calculations are in general quite computationally demanding. We therefore recommend the employment of at least 8 computing cores. For larger calculations, [OF queues](../../../infrastructure/resource/queues.md) will have faster turnaround than the OR queues considered in the video. +!!!tip "Computational cost" + Phonon calculations are computationally demanding. At least 8 computing cores are recommended. For larger calculations, [OF queues]({{ resources_url }}/infrastructure/resource/queues/) offer faster turnaround than OR queues.
-## Links -[^1]: [T. Bazhirov, E. X. Abot: "Fast and accessible first-principles calculations of vibrational properties of materials"; arXiv:1808.10011v1, 29 Aug 2018](https://arxiv.org/pdf/1808.10011.pdf) +## 5. Links +[^1]: [T. Bazhirov, E. X. Abot: "Fast and accessible first-principles calculations of vibrational properties of materials"; arXiv:1808.10011v1, 29 Aug 2018](https://arxiv.org/pdf/1808.10011.pdf) [^2]: ["Introduction to lattice modes and their symmetry", Oxford University Lecture Document](https://www2.physics.ox.ac.uk/sites/default/files/CrystalStructure_Handout8_0.pdf) diff --git a/lang/en/docs/tutorials/dft/vibrational/zero-point-energy.md b/lang/en/docs/tutorials/dft/vibrational/zero-point-energy.md index 7e3c1764a..78681f1fc 100644 --- a/lang/en/docs/tutorials/dft/vibrational/zero-point-energy.md +++ b/lang/en/docs/tutorials/dft/vibrational/zero-point-energy.md @@ -1,43 +1,48 @@ # Calculate Zero Point Energy -This page explains how to run a [zero point energy](../../../properties-directory/scalar/zero-point-energy.md) calculation based on [density functional theory](../../../models-directory/dft/overview.md). For the sake of this presentation, we will calculate the zero point energy for crystalline silicon in its equilibrium cubic-diamond crystal structure, making use of [VASP](../../../software-directory/modeling/vasp/overview.md) as our simulation engine. +This tutorial explains how to calculate the [zero point energy]({{ reference_url }}/properties-directory/scalar/zero-point-energy/) of crystalline silicon in its equilibrium cubic-diamond crystal structure using [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT) with [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/). -!!!note "VASP version considered in this tutorial" - The present tutorial is written for VASP at versions 5.3.5 or 5.4.4. +!!!note "VASP version" + This tutorial applies to VASP versions 5.3.5, 5.4.4, and later. -## Create Job -Silicon in its cubic-diamond crystal structure is the [default material](../../../materials/default.md) that is shown on [new job creation](../../../jobs-designer/overview.md), unless this default was [changed](../../../entities-general/actions/set-default.md) by the user following [account](../../../accounts/overview.md) creation. If silicon is still the default choice, it will as such be automatically loaded at the moment of the [opening](../../../jobs/actions/create.md) of [Job Designer](../../../jobs-designer/overview.md). +## 1. Create the job -## Choose Workflow +Silicon in its cubic-diamond crystal structure is the [default material]({{ reference_url }}/materials/default/) loaded on [new job creation]({{ interface_url }}/jobs-designer/overview/), unless the default was [changed]({{ interface_url }}/entities-general/actions/set-default/) after [account]({{ reference_url }}/accounts/overview/) creation. -[Workflows](../../../workflows/overview.md) for calculating the Zero Point Energy through [VASP](../../../software-directory/modeling/vasp/overview.md) can readily be [imported](../../../workflows/actions/copy-bank.md) from the [Workflows Bank](../../../workflows/bank.md) into the account-owned [collection](../../../accounts/collections.md). This workflow can later be [selected](../../../jobs-designer/actions-header-menu/select-workflow.md) and added to the [Job being created](../../../jobs-designer/workflow-tab.md). -## Examine Input File +## 2. Select the workflow - The unique [unit](../../../workflows/components/units.md) for this tutorial is the "vasp_zpe" unit. Clicking it will show the corresponding input files. The `IBRION = 5` flag within the INCAR file enables VASP to run the displacements for the zero point energy calculation. +[Workflows]({{ reference_url }}/workflows/overview/) for the Zero Point Energy calculation with [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/). The workflow can then be [selected]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) and added to the [job being created]({{ interface_url }}/jobs-designer/workflow-tab/). -## Set Sampling in Reciprocal Space -It is critical that a [well-relaxed structure](../../../workflows/addons/structural-relaxation.md) with [converged k-point density](../../../models/auxiliary-concepts/reciprocal-space/convergence.md) is used for zero point energy calculations. +## 3. Examine the input file -The default value of sampling, set according to KPPRA of 2000, is sufficient as can be verified by performing the relevant [convergence study](../../../models/auxiliary-concepts/reciprocal-space/convergence.md). When dealing with larger cells, setting k-grid dimensions through KPPRA should generally provide a reliable guess. +The single [unit]({{ reference_url }}/workflows/components/units/) for this calculation is "vasp_zpe". Clicking it reveals the corresponding input files. The `IBRION = 5` flag within the INCAR file enables VASP to run the atomic displacements required for the zero point energy calculation. -We explain how to perform both [structural relaxations](../addons/structural-relaxation.md) and [k-points convergence studies](../addons/kpt-convergence.md) in their respective tutorials. -## Submit Job +## 4. Set sampling in reciprocal space -Before [submitting](../../../jobs/actions/run.md) the [Job](../../../jobs/overview.md), the user should click on the ["Compute" tab](../../../jobs-designer/compute-tab.md) of [Job Designer](../../../jobs-designer/overview.md) and inspect the [compute parameters](../../../infrastructure/compute/parameters.md) included therein. Silicon is a small structure, so four CPUs and one minute of calculation runtime should be sufficient. +A [well-relaxed structure]({{ reference_url }}/workflows/addons/structural-relaxation/) with [converged k-point density]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/convergence/) is critical for zero point energy calculations. -## Examine Results +The default sampling (KPPRA of 2000) is sufficient, as can be verified by performing a [convergence study]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/convergence/). For larger cells, setting k-grid dimensions through KPPRA generally provides a reliable starting point. -Once the Job execution is finished, switching to the [Results tab](../../../jobs/ui/results-tab.md) of [Job Viewer](../../../jobs/ui/viewer.md) will show the results of the simulation, including a card titled "Zero Point Energy" that displays the value of this [property](../../../properties/overview.md) for the material in question. +Instructions for [structural relaxations](../addons/structural-relaxation.md) and [k-point convergence studies](../addons/kpt-convergence.md) are available in their respective tutorials. -The larger its value, the more critical it becomes to include the zero point energy in ab-initio thermodynamic calculations performed at zero temperature. -## Animation +## 5. Submit the job -We demonstrate the above-mentioned steps involved in the creation and execution of a Zero Point Energy computation workflow on silicon, using the [VASP](../../../software-directory/modeling/vasp/overview.md) simulation engine, in the following animation. +Before [submitting]({{ interface_url }}/jobs/actions/run/) the [job]({{ reference_url }}/jobs/overview/), review the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) of [Job Designer]({{ interface_url }}/jobs-designer/overview/) to verify the [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/). Silicon is a small structure, so 4 CPUs and 1 minute of runtime are sufficient. + + +## 6. Examine the results + +Once the job completes, the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) displays a "Zero Point Energy" card with the calculated value. The larger this value, the more important it becomes to include zero point energy in ab-initio thermodynamic calculations performed at zero temperature. + + +## 7. Video walkthrough + +The animation below demonstrates the full zero point energy workflow on silicon using VASP.
diff --git a/lang/en/docs/tutorials/formation-energy.md b/lang/en/docs/tutorials/formation-energy.md index 8ff3e5184..6e00131d3 100644 --- a/lang/en/docs/tutorials/formation-energy.md +++ b/lang/en/docs/tutorials/formation-energy.md @@ -1,89 +1,64 @@ -# Formation Energy - VASP +# Formation Energy — VASP -This page explains how to calculate formation energy[^1] based on density -functional theory[^2]. We will be studying copper oxide CuO2 and use -VASP[^3] as our simulation engine. +!!!warning "Unused tutorial" + This tutorial is not currently linked in the main navigation. It is retained for reference. -!!! Note "Pre-calculated energy values for default pseudopotentials" - Formation energy requires the knowledge of the total and zero point energies - of constituents in their standard state. We have pre-calculated these values - at a converged k-point density for all supported pseudopotentials. These - values are automatically populated to eliminate the need to recalculate them - again. +This page explains how to calculate [formation energy](https://en.wikipedia.org/wiki/Standard_Gibbs_free_energy_of_formation) [^1] based on [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT) [^2]. The example uses copper oxide CuO2 with [VASP](https://www.vasp.at/) [^3] as the simulation engine. +!!!note "Pre-calculated energy values for default pseudopotentials" + Formation energy requires the total and zero-point energies of constituents in their standard state. These values have been pre-calculated at a converged k-point density for all supported pseudopotentials and are populated automatically. -## Import Material -Click on "Create a Job" from left-hand sidebar on the home page. Silicon will -automatically be loaded as it is the default material. The formation energy of -elements is zero, so for this test case we will need to import CuO2 -structure. +## 1. Import the material -To import CuO2 use sidebar again, and select the "Materials" page. -Then click the cloud button on the upper right of that page to initiate import. -In the search box, put CuO2 and after a few seconds, the entries for -CuO2 from [materialsproject.org]( -https://materialsproject.org){:target="_blank"} will appear. +Click **Create a Job** from the left-hand sidebar on the home page. Silicon is loaded automatically as the default material. Since the formation energy of elements is zero, a compound structure — CuO2 — is needed for this example. -Choose the version of CuO2 with the lowest formation energy and click -on it. Then click on the right side of the entry to bring up the option to -import the material +In order to import CuO2, open the sidebar again and select the *Materials* page. Then click the cloud button in the upper right of that page to initiate an import. In the search box, enter CuO2; after a few seconds, entries from [materialsproject.org](https://materialsproject.org){:target="_blank"} appear. + +Select the version of CuO2 with the lowest formation energy and click it. Then click the right side of the entry to bring up the option to import the material. -## Create job -Now that you have imported CuO2 we are ready to use that structure to -reproduce formation energy calculation. Click "Create Job" link again. If you go -to the "Choose A Material" section of the page, and click on the drop-down menu, -CuO2 should be one of your options to select as the material for the -simulation. +## 2. Create the job + +After importing CuO2, click **Create Job** again. Under the *Choose A Material* section, open the drop-down menu — CuO2 should appear as one of the selectable materials. -## Choose workflow -Next go to the workflow tab and select "Formation Energy" as the workflow type. -The units displayed as part of this workflow will look similar to a combination -of the [kpt-convergence](kpt-convergence) and [relaxation tutorials]( -relaxation), but will include a couple of extra units after the vc_relax unit -used to obtain the elements total and zero point energies and calculate the -formation energy. +## 3. Select the workflow + +Navigate to the workflow tab and select *Formation Energy* as the workflow type. The units displayed are similar to a combination of the [k-point convergence](dft/addons/kpt-convergence.md) and [relaxation](dft/addons/structural-relaxation.md) tutorials, with additional units after vc_relax for obtaining elemental total and zero-point energies and calculating the formation energy. -## Submit job -This calculation will take some time to complete due to both k-point convergence -and relaxation being run on a relatively large supercell. It's important to -adjust the computation parameters accordingly. Click on the "Compute" tab and -increase the maximum run time limit to 30 minutes and the number of cores to 4. -Also click on your username in the box to turn on email notifications about the -jobs status. +## 4. Submit the job + +This calculation takes some time due to both k-point convergence and relaxation being run on a relatively large supercell. The computation parameters should be adjusted accordingly: click the *Compute* tab, increase the maximum runtime limit to 30 minutes, and set the number of cores to 4. Email notifications can be enabled by clicking the username in the notifications box. -## Monitor status -As each unit in the workflow is executing, you can monitor its progress live by -viewing both the output of the executable as well as a graphical representation -of the total energy convergence on the "Status" tab under each unit's sub-tab. +## 5. Monitor status + +As each unit in the workflow executes, its progress can be monitored in real time by viewing both the output of the executable and the graphical representation of total energy convergence on the *Status* tab under each unit's sub-tab. -## Check results -When the execution of all units finished, switching to the Results tab and the -sub-tab for the final execution unit will have an entry titled "Formation -Energy" that will display formation energy of the material. The more -negative the value, the more stable the material is. This "Formation Energy" box -will also show the energetic parameters (total energy and zero-point energy) for -constituent elements used to calculate the property. +## 6. Check the results + +Once all units have completed, switching to the *Results* tab and the sub-tab for the final execution unit reveals an entry titled *Formation Energy* that displays the formation energy of the material. More negative values indicate greater thermodynamic stability. The *Formation Energy* box also shows the energetic parameters (total energy and zero-point energy) for constituent elements used to calculate the property. + +## 7. Links + [^1]: [Formation Energy (Wikipedia)](https://en.wikipedia.org/wiki/Standard_Gibbs_free_energy_of_formation) [^2]: [Density Functional Theory (Wikipedia)](https://en.wikipedia.org/wiki/Density_functional_theory) -[^3]: [Vienna ab-inito simulation package (Official Website)](https://www.vasp.at/) +[^3]: [Vienna Ab-initio Simulation Package (Official Website)](https://www.vasp.at/) diff --git a/lang/en/docs/tutorials/general-functionality/tensorflow-gpu.md b/lang/en/docs/tutorials/general-functionality/tensorflow-gpu.md index b4cbd018c..1fe954295 100644 --- a/lang/en/docs/tutorials/general-functionality/tensorflow-gpu.md +++ b/lang/en/docs/tutorials/general-functionality/tensorflow-gpu.md @@ -2,8 +2,8 @@ TensorFlow [^1] is a powerful oepn-source machine-learning platform geared towards neural networks. -In this tutorial, we will create an [Anaconda](../../cli/modules.md) environment for TensorFlow, and will run a test job -on a [GPU](../../infrastructure/resource/category.md) queue within [AWS](../../infrastructure/clusters/aws.md). +In this tutorial, we will create an [Anaconda]({{ cli_url }}/cli/modules/) environment for TensorFlow, and will run a test job +on a [GPU]({{ resources_url }}/infrastructure/resource/category/) queue within [AWS]({{ resources_url }}/infrastructure/clusters/aws/). ## 1. Create the Test Job @@ -50,7 +50,7 @@ prefix: tfgpu ### job.pbs -We'll finish our job setup by writing a PBS [submission script](../../jobs-cli/batch-scripts/overview.md) to take care +We'll finish our job setup by writing a PBS [submission script]({{ cli_url }}/jobs-cli/batch-scripts/overview/) to take care of setting up the TensorFlow environment and running the Python script. We will name this file `job.pbs`: ```bash @@ -118,7 +118,7 @@ qsub job.pbs ``` The job will enter the GPU queue, and after a few minutes should start. The job's -status [can be monitored](../../jobs-cli/actions/check-status.md) with the `qstat` command. +status [can be monitored]({{ cli_url }}/jobs-cli/actions/check-status/) with the `qstat` command. ## 3. Analyze the Results @@ -159,7 +159,7 @@ coreClock: 1.53GHz coreCount: 80 deviceMemorySize: 15.78GiB deviceMemoryBandwidt In this output, we can see that a single GPU was found: an nVidia TESLA V100-SXM2-16GB. In this case, this is the GPU that would have been used by TensorFlow to perform its calculations. -## Links +## 4. Links [^1]: [TensorFlow Documentation](https://www.tensorflow.org/) diff --git a/lang/en/docs/tutorials/jobs-cli/cli-job-import.md b/lang/en/docs/tutorials/jobs-cli/cli-job-import.md index af2885ccc..f7b87eb63 100644 --- a/lang/en/docs/tutorials/jobs-cli/cli-job-import.md +++ b/lang/en/docs/tutorials/jobs-cli/cli-job-import.md @@ -1,48 +1,52 @@ # Import Command Line Jobs to Web Interface -The present tutorial page explains how to import the results of a [job](../../jobs-cli/overview.md) run via [command-line interface](../../cli/overview.md) to the main [Web Interface](../../ui/overview.md) of our platform. +This tutorial explains how to import the results of a [job]({{ cli_url }}/jobs-cli/overview/) run via [command-line interface]({{ cli_url }}/cli/overview/) to the main [Web Interface]({{ interface_url }}/ui/overview/). -When this feature is employed, the user can see the job output files extracted and available for analysis in the web interface, under the [Files Tab](../../jobs/ui/files-tab.md) of [Job Viewer](../../jobs/ui/viewer.md). +When this feature is employed, the job output files are extracted and available for analysis in the web interface under the [Files Tab]({{ interface_url }}/jobs/ui/files-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). -## Note about Job Scripts -We use the content of the [job batch script file](../../jobs-cli/batch-scripts/overview.md) in order to collect job information and create an entry for it inside the web interface. Currently, only simple job scripts containing a single [execution command](../../jobs-cli/batch-scripts/general-structure.md#4.-commands) are supported. Hence, the user should make sure that the script's content is properly formatted and straightforward. +## 1. Understand job script requirements -[In this page](../../jobs-cli/batch-scripts/sample-scripts.md), the reader can find **sample job script files** for running [Job simulations via Command Line Interface](../../jobs-cli/overview.md) that can be used as template. The general structure of such scripts is instead explained [here](../../jobs-cli/batch-scripts/general-structure.md). +The content of the [job batch script file]({{ cli_url }}/jobs-cli/batch-scripts/overview/) is used to collect job information and create an entry inside the web interface. Only simple job scripts containing a single [execution command]({{ cli_url }}/jobs-cli/batch-scripts/general-structure.md#4.-commands) are supported. The script content should be properly formatted and straightforward. + +[Sample job script files]({{ cli_url }}/jobs-cli/batch-scripts/sample-scripts/) for running [Job simulations via Command Line Interface]({{ cli_url }}/jobs-cli/overview/) can be used as templates. The general structure of such scripts is explained [here]({{ cli_url }}/jobs-cli/batch-scripts/general-structure/). !!!note "Keep job scripts simple" - Please avoid using complex formatting and extra indentations or spacing in the job script. + Complex formatting and extra indentations or spacing in the job script should be avoided. + + +## 2. Open the Web Terminal -## Open Web Terminal +[Navigate]({{ cli_url }}/remote-connection/actions/open-terminal/) to the [Web Terminal]({{ cli_url }}/remote-connection/web-terminal/) for accessing the [command-line interface]({{ cli_url }}/cli/overview/). -First, [navigate](../../remote-connection/actions/open-terminal.md) to the [Web Terminal](../../remote-connection/web-terminal.md) for accessing the [command-line interface](../../cli/overview.md) of our platform. -## Import New Job Results +## 3. Import new job results -In order to submit a new job through [command-line interface](../../cli/overview.md), and then view the corresponding output files under the [Web Interface](../../ui/overview.md), the following [directive](../../jobs-cli/batch-scripts/directives.md) should be added to the [job submission script](../../jobs-cli/batch-scripts/overview.md). +In order to submit a new job through the [command-line interface]({{ cli_url }}/cli/overview/) and view the corresponding output files under the [Web Interface]({{ interface_url }}/ui/overview/), the following [directive]({{ cli_url }}/jobs-cli/batch-scripts/directives/) should be added to the [job submission script]({{ cli_url }}/jobs-cli/batch-scripts/overview/): ```bash #PBS -R y ``` !!!note "Default Behavior" - The `#PBS -R y` [directive](../../jobs-cli/batch-scripts/directives.md) is always enabled by default, but it can still be added manually as a failsafe. + The `#PBS -R y` [directive]({{ cli_url }}/jobs-cli/batch-scripts/directives/) is always enabled by default, but can still be added manually as a failsafe. -This directive instructs our software to automatically parse the output of the calculation, and send back the results to the web interface. After adding this directive, the job can then be [submitted](../../jobs-cli/actions/submit.md) as usual. +This directive instructs the software to parse the output of the calculation and send back the results to the web interface. After adding this directive, the job can be [submitted]({{ cli_url }}/jobs-cli/actions/submit/) as usual. -Once the job starts executing, the user should be able to see the job entry in the web interface under [Jobs Explorer](../../jobs/ui/explorer.md), and thus monitor the corresponding [status](../../jobs/status.md) of its execution. +Once the job starts executing, the job entry is visible in the web interface under [Jobs Explorer]({{ interface_url }}/jobs/ui/explorer/), where the [status]({{ reference_url }}/jobs/status/) of its execution can be monitored. -This feature can conversely be disabled by inserting the following other directive option in the [job submission script](../../jobs-cli/batch-scripts/overview.md). +This feature can be disabled by inserting the following directive instead: ```bash #PBS -R n ``` -## Animation -In the below video, we first navigate to a directory under the [command-line interface](../../cli/overview.md) where we have copied the contents of the [VASP template Job](../../jobs-cli/batch-scripts/directories.md#job-templates). Here, we edit the [job submission script](../../jobs-cli/batch-scripts/overview.md) to insert the aforementioned `#PBS -R y` [directive](../../jobs-cli/batch-scripts/directives.md) for completeness, even though as explained earlier this directive is already enabled by default. - -This allows us to monitor the job [status](../../jobs/status.md) under [Jobs Explorer](../../jobs/ui/explorer.md) in [Web Interface](../../ui/overview.md), which we inspect towards the end of the animation. +## 4. Video walkthrough + +The animation below first navigates to a directory under the [command-line interface]({{ cli_url }}/cli/overview/) where the contents of the [VASP template Job]({{ cli_url }}/jobs-cli/batch-scripts/directories.md#job-templates) have been copied. The [job submission script]({{ cli_url }}/jobs-cli/batch-scripts/overview/) is edited to insert the `#PBS -R y` [directive]({{ cli_url }}/jobs-cli/batch-scripts/directives/) for completeness (though this directive is already enabled by default). + +The job [status]({{ reference_url }}/jobs/status/) is then monitored under [Jobs Explorer]({{ interface_url }}/jobs/ui/explorer/) in the [Web Interface]({{ interface_url }}/ui/overview/).
diff --git a/lang/en/docs/tutorials/jobs-cli/job-cli-example.md b/lang/en/docs/tutorials/jobs-cli/job-cli-example.md index dcd658d76..05e2a472c 100644 --- a/lang/en/docs/tutorials/jobs-cli/job-cli-example.md +++ b/lang/en/docs/tutorials/jobs-cli/job-cli-example.md @@ -1,12 +1,12 @@ # Running Jobs via Command Line Interface -This page explains how to run a [job](../../jobs/overview.md) via the [Command Line Interface](../../cli/overview.md) (CLI) of our platform. The reader is recommended to first consult the [relevant part of the documentation](../../jobs-cli/overview.md) before proceeding further with the present Tutorial. +This page explains how to run a [job]({{ reference_url }}/jobs/overview/) via the [Command Line Interface]({{ cli_url }}/cli/overview/) (CLI) of our platform. The reader is recommended to first consult the [relevant part of the documentation]({{ cli_url }}/jobs-cli/overview/) before proceeding further with the present Tutorial. -Here, we will use a template input file and a bash script to sweep the lattice parameter space for a given structure. We will use [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md) as an example simulations engine, however all command-line related directives apply universally. +Here, we will use a template input file and a bash script to sweep the lattice parameter space for a given structure. We will use [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) as an example simulations engine, however all command-line related directives apply universally. ## 1. Input File -We start with preparing an **input file** for [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md). Below is an example input file for performing a total ground-state "self-consistent field" (scf) energy computation, with pseudopotential paths set to use the default **"gbrv" set of pseudopotentials** [^1] implemented on our platform. +We start with preparing an **input file** for [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/). Below is an example input file for performing a total ground-state "self-consistent field" (scf) energy computation, with pseudopotential paths set to use the default **"gbrv" set of pseudopotentials** [^1] implemented on our platform. The material being considered in this particular example is a supercell of "Strontium Zirconate" (SrZrO3), in its ground state equilibrium crystal structure with space group "Pnma" [^2]. The reader is referred to the official documentation for the "PWscf" module of Quantum ESPRESSO [^3] [^4] for a description of the keyword parameters contained here. @@ -84,9 +84,9 @@ K_POINTS (automatic) 3 3 3 1 1 1 ``` -Note that we are using a template variable in place of `celldm(1)`, indicating the lattice parameter of the underlying simple cubic [Bravais Lattice](../../properties-directory/structural/lattice.md) of the crystal structure. These template variables are defined once the combined `run.sh` script is put together, as explained in what follows. +Note that we are using a template variable in place of `celldm(1)`, indicating the lattice parameter of the underlying simple cubic [Bravais Lattice]({{ reference_url }}/properties-directory/structural/lattice/) of the crystal structure. These template variables are defined once the combined `run.sh` script is put together, as explained in what follows. -We also need to copy the pseudopotential files into the current [working directory](../../jobs-cli/batch-scripts/directories.md) where the input file is stored, as follows. +We also need to copy the pseudopotential files into the current [working directory]({{ cli_url }}/jobs-cli/batch-scripts/directories/) where the input file is stored, as follows. ```bash cp /export/share/pseudo/si/gga/pbe/gbrv/1.0/us/sr_pbe_gbrv_1.0.upf . @@ -96,7 +96,7 @@ cp /export/share/pseudo/o/gga/pbe/gbrv/1.0/us/o_pbe_gbrv_1.2.upf . ## 2. Batch Script -Secondly, we prepare the [Batch Script](../../jobs-cli/batch-scripts/overview.md) necessary for [submitting jobs via CLI](../../jobs-cli/overview.md). +Secondly, we prepare the [Batch Script]({{ cli_url }}/jobs-cli/batch-scripts/overview/) necessary for [submitting jobs via CLI]({{ cli_url }}/jobs-cli/overview/). ```bash #!/bin/bash @@ -112,12 +112,13 @@ Secondly, we prepare the [Batch Script](../../jobs-cli/batch-scripts/overview.md module add espresso cd $PBS_O_WORKDIR -mpirun -np $PBS_NP pw.x -in pw.in > pw.out +# $EXEC_CMD is set by the environment module +mpirun -np $PBS_NP $EXEC_CMD pw.x -in pw.in > pw.out ``` -Just like before, we are using template variables again instead of the [project](../../jobs/projects.md) name and email. Variables starting with `$PBS` are automatically set by the [resource manager](../../infrastructure/resource/overview.md), and are known as the ["PBS Directives"](../../jobs-cli/batch-scripts/directives.md). +Just like before, we are using template variables again instead of the [project]({{ reference_url }}/jobs/projects/) name and email. Variables starting with `$PBS` are automatically set by the [resource manager]({{ resources_url }}/infrastructure/resource/overview/), and are known as the ["PBS Directives"]({{ cli_url }}/jobs-cli/batch-scripts/directives/). -The rest of the Batch Script contains UNIX commands necessary for [loading the required modules](../../cli/actions/modules-actions.md) and running the executables in parallel. +The rest of the Batch Script contains UNIX commands necessary for [loading the required modules]({{ cli_url }}/cli/actions/modules-actions/) and running the executables in parallel. ## 3. Shell Script @@ -258,39 +259,39 @@ EOF module add espresso cd \$PBS_O_WORKDIR -mpirun -np \$PBS_NP pw.x -in srzro3_${celldm1}.in | tee srzro3_${celldm1}.out +mpirun -np \$PBS_NP $EXEC_CMD pw.x -in srzro3_${celldm1}.in | tee srzro3_${celldm1}.out EOF qsub run_QE_${celldm1}.pbs done ``` -The reader should note that within the `mpirun` command we make use of the `tee` command. This redirects the output of the simulation to both the standard output (abbreviated as "stdout") and to the output file simultaneously. Redirecting to "stdout" in this way allows the status of the job to be regularly updated and refreshed under the corresponding [Job Viewer](../../jobs/ui/viewer.md) in the [Web Interface](../../ui/overview.md), as demonstrated in [another Tutorial](cli-job-import.md). +The reader should note that within the `mpirun` command we make use of the `tee` command. This redirects the output of the simulation to both the standard output (abbreviated as "stdout") and to the output file simultaneously. Redirecting to "stdout" in this way allows the status of the job to be regularly updated and refreshed under the corresponding [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) in the [Web Interface]({{ interface_url }}/ui/overview/), as demonstrated in [another Tutorial](cli-job-import.md). We can put the content of the above file into a bash script called `run.sh` for example, and then make the script executable with `chmod a+x run.sh` command. -The job can finally be [submitted](../../jobs-cli/actions/submit.md) as a set to the [Resource Manager](../../infrastructure/resource/overview.md) by invoking the script via the `./run.sh` command (the `qsub` command is not necessary in this case since it is already included as part of `run.sh`, towards the end of the script). +The job can finally be [submitted]({{ cli_url }}/jobs-cli/actions/submit/) as a set to the [Resource Manager]({{ resources_url }}/infrastructure/resource/overview/) by invoking the script via the `./run.sh` command (the `qsub` command is not necessary in this case since it is already included as part of `run.sh`, towards the end of the script). ## 5. View Submitted Jobs -The user can view the currently submitted jobs and their statuses in CLI with the `qstat` [command](../../jobs-cli/actions/check-status.md). +The user can view the currently submitted jobs and their statuses in CLI with the `qstat` [command]({{ cli_url }}/jobs-cli/actions/check-status/). -The reader is referred to the video below for an explanation on how to inspect the results of the above simulation under the [Web Interface](../../ui/overview.md) of our platform. +The reader is referred to the video below for an explanation on how to inspect the results of the above simulation under the [Web Interface]({{ interface_url }}/ui/overview/) of our platform. -## Animation +## 6. Animation We summarize the above-mentioned steps in the following video. -Here, we begin by entering the [Command Line Interface](../../cli/overview.md) via the [Web Terminal](../../remote-connection/web-terminal.md) connection method. We then navigate to the directory containing the `run.sh` script under the [Home Folder](../../infrastructure/clusters/directories.md) of `cluster-007`, where we submit it for execution. +Here, we begin by entering the [Command Line Interface]({{ cli_url }}/cli/overview/) via the [Web Terminal]({{ cli_url }}/remote-connection/web-terminal/) connection method. We then navigate to the directory containing the `run.sh` script under the [Home Folder]({{ resources_url }}/infrastructure/clusters/directories/) of `cluster-007`, where we submit it for execution. -We conclude by inspecting the [status of the job](../../jobs-cli/actions/check-status.md) on the selected cluster number "007" by entering the `watch qstat` command, for an automatically-refreshing version of `qstat`. Since only one lattice parameter was tested in this example animation for simplicity, only one job has been launched and is returned by `qstat` in this case (scanning over all three lattice parameters, as in the original script shown above, would have correspondingly launched three distinct jobs). +We conclude by inspecting the [status of the job]({{ cli_url }}/jobs-cli/actions/check-status/) on the selected cluster number "007" by entering the `watch qstat` command, for an automatically-refreshing version of `qstat`. Since only one lattice parameter was tested in this example animation for simplicity, only one job has been launched and is returned by `qstat` in this case (scanning over all three lattice parameters, as in the original script shown above, would have correspondingly launched three distinct jobs).
-## Links +## 7. Links [^1]: [GBRV pseudopotential library, Official Website](https://www.physics.rutgers.edu/gbrv/) diff --git a/lang/en/docs/tutorials/jobs-cli/overview.md b/lang/en/docs/tutorials/jobs-cli/overview.md index cbea2d737..116fd47e2 100644 --- a/lang/en/docs/tutorials/jobs-cli/overview.md +++ b/lang/en/docs/tutorials/jobs-cli/overview.md @@ -1,11 +1,11 @@ # Tutorials on Jobs via Command Line Interface -We explain how the user can go through the procedure for [submitting jobs via the Command Line Interface (CLI)](../../jobs-cli/overview.md) of our platform with the help of the following tutorials. +We explain how the user can go through the procedure for [submitting jobs via the Command Line Interface (CLI)]({{ cli_url }}/jobs-cli/overview/) of our platform with the help of the following tutorials. ## [Creating and Running Jobs](job-cli-example.md) -[This first tutorial](job-cli-example.md) explains how to create the input scripts for running a materials science computation with the [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md) modeling application. We also explain how to submit the corresponding [simulation job](../../jobs/overview.md) to the [Resource Manager](../../infrastructure/resource/overview.md) of our computational [infrastructure](../../infrastructure/overview.md) via the [Command Line Interface](../../cli/overview.md). +[This first tutorial](job-cli-example.md) explains how to create the input scripts for running a materials science computation with the [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) modeling application. We also explain how to submit the corresponding [simulation job]({{ reference_url }}/jobs/overview/) to the [Resource Manager]({{ resources_url }}/infrastructure/resource/overview/) of our computational [infrastructure]({{ resources_url }}/infrastructure/overview/) via the [Command Line Interface]({{ cli_url }}/cli/overview/). ## [Import Command Line Jobs to Web Interface](cli-job-import.md) -[This tutorial](cli-job-import.md) explains how to import the results of a [job](../../jobs-cli/overview.md) run via [command-line interface](../../cli/overview.md) to the main [Web Interface](../../ui/overview.md) of our platform. +[This tutorial](cli-job-import.md) explains how to import the results of a [job]({{ cli_url }}/jobs-cli/overview/) run via [command-line interface]({{ cli_url }}/cli/overview/) to the main [Web Interface]({{ interface_url }}/ui/overview/) of our platform. diff --git a/lang/en/docs/tutorials/jobs-cli/qe-gpu.md b/lang/en/docs/tutorials/jobs-cli/qe-gpu.md index edede9f5a..0de2a910c 100644 --- a/lang/en/docs/tutorials/jobs-cli/qe-gpu.md +++ b/lang/en/docs/tutorials/jobs-cli/qe-gpu.md @@ -5,52 +5,64 @@ tags: hide: - tags --- -# Accelerate Quantum ESPRESSO simulation with GPUs +# Accelerate Quantum ESPRESSO Simulation with GPUs -We will walk through a step-by-step example of running a Quantum ESPRESSO job on -GPUs. As of the time of writing, the GPU (CUDA) build of Quantum ESPRESSO is -only available via the Command Line Interface (CLI). We will see that we can -dramatically speedup our Quantum ESPRESSO simulation by using GPUs. +This tutorial walks through a step-by-step example of running a Quantum ESPRESSO job on GPUs. As of the time of writing, the GPU (CUDA) build of Quantum ESPRESSO is only available via the Command Line Interface (CLI). GPU acceleration can provide dramatic speedups for Quantum ESPRESSO simulations. -1. First connect to login node via [SSH client](../../remote-connection/ssh.md), -or [web terminal](../../remote-connection/web-terminal.md). Note that it is also -possible to run CLI jobs by creating a [bash workflow]( -../../software-directory/scripting/shell/overview.md). - ![Wen Terminal](../../images/jobs-cli/open-web-terminal.webp) +## 1. Connect to the login node + +Connect to the login node via [SSH client]({{ cli_url }}/remote-connection/ssh/) or [web terminal]({{ cli_url }}/remote-connection/web-terminal/). It is also possible to run CLI jobs by creating a [bash workflow]({{ reference_url }}/software-directory/scripting/shell/overview/). + +![Web Terminal](../../images/jobs-cli/open-web-terminal.webp) + + +## 2. Clone the example repository + +The example job is available in the git repository [mat3ra/cli-job-examples](https://github.com/mat3ra/cli-job-examples). Clone the repository to the working directory: -2. Example job that we are going to run is available in git repository -[exabyte-io/cli-job-examples](https://github.com/exabyte-io/cli-job-examples). -You may clone the repository to your working directory: ```bash -git clone https://github.com/exabyte-io/cli-job-examples +git clone https://github.com/mat3ra/cli-job-examples cd cli-job-examples git lfs pull cd espresso/gpu ``` -3. You will find all required input files and job script under `espresso/gpu`. -Please review the input files and PBS job script, update the project name, and -other parameters as necessary. -4. We will use [GOF](../../infrastructure/clusters/aws.md#hardware-specifications) -queue, which comprises 8 CPUs and 1 NVIDIA V100 GPU per node. +## 3. Review the input files + +All required input files and the job script are located under `espresso/gpu`. Review the input files and PBS job script, and update the project name and other parameters as necessary. + + +## 4. Select the compute queue + +The [GOF]({{ resources_url }}/infrastructure/clusters/aws/#hardware-specifications) queue is used, which comprises 8 CPUs and 1 NVIDIA V100 GPU per node. + + +## 5. Configure MPI and OpenMP + +Since the compute node contains 8 CPUs with 1 GPU, the job runs 1 MPI process with 8 OpenMP threads: -5. Since our compute node contains 8 CPUs with 1 GPU, we will run 1 MPI process -with 8 OpenMP threads. ```bash module load espresso/7.4-cuda-12.4-cc-70 export OMP_NUM_THREADS=8 -mpirun -np 1 pw.x -npool 1 -ndiag 1 -in pw.cuo.scf.in > pw.cuo.gpu.scf.out +mpirun -np 1 $EXEC_CMD pw.x -npool 1 -ndiag 1 -in pw.cuo.scf.in > pw.cuo.gpu.scf.out ``` -6. Finally, we can submit our job using: + +## 6. Submit the job + +Submit the job using: + ```bash qsub job.gpu.pbs ``` -7. Once, the job is completed, we can inspect the output file `pw.cuo.gpu.scf.out`. -We will see that GPU was used, and the job took about 1 minute wall time. + +## 7. Inspect the results + +Once the job completes, inspect the output file `pw.cuo.gpu.scf.out`. The output confirms that GPU acceleration was used and the job took approximately 1 minute wall time: + ``` Parallel version (MPI & OpenMP), running on 8 processor cores Number of MPI processes: 1 @@ -66,8 +78,11 @@ Parallel routines PWSCF : 37.94s CPU 50.77s WALL ``` -8. For comparison, we ran the same calculation using only CPUs, and it took -about 20 times longer. + +## 8. Compare with CPU-only performance + +For comparison, the same calculation using only CPUs took about 20 times longer: + ``` Parallel version (MPI), running on 8 processors @@ -79,12 +94,11 @@ Parallel routines PWSCF : 18m 0.56s CPU 18m25.33s WALL ``` -You may experiment different combinations of MPI and OpenMP, various -[parallelization options](https://www.quantum-espresso.org/Doc/user_guide/node20.html), -and find what gives you the best performance. +Different combinations of MPI and OpenMP, as well as various [parallelization options](https://www.quantum-espresso.org/Doc/user_guide/node20.html), can be tested to find the best performance. + -## Step-by-step screenshare video +## 9. Video walkthrough
- +
diff --git a/lang/en/docs/tutorials/materials/combinatorial-screening.md b/lang/en/docs/tutorials/materials/combinatorial-screening.md index 069757b85..f58133592 100644 --- a/lang/en/docs/tutorials/materials/combinatorial-screening.md +++ b/lang/en/docs/tutorials/materials/combinatorial-screening.md @@ -1,125 +1,129 @@ # Generate Combinatorial Sets -This tutorial demonstrates how to create a **combinatorial set** of materials. We use III-V semiconductor compounds as example with permutations and combinations of n and p-type dopants. Combinatorial set of materials can be used to execute **combinatorial screening** to investigate, for example, the impact of inserting dopants on the [electronic band gap](../../properties-directory/non-scalar/band-gaps.md) of such semiconductors. +This tutorial demonstrates how to create a **combinatorial set** of materials. III-V semiconductor compounds are used as an example, with permutations and combinations of n- and p-type dopants. Combinatorial sets of materials can be used to execute **combinatorial screening** to investigate, for example, the impact of inserting dopants on the [electronic band gap]({{ reference_url }}/properties-directory/non-scalar/band-gaps/) of such semiconductors. -## Import Material into Collection -We begin by importing one of the III-V compound semiconductors, Gallium Phosphide (GaP), into the user's [collection](../../accounts/collections.md) of materials, starting from which we will then build further combinatorial sets. This crystal structure can be **imported** directly from a remote repository, by following the instructions outlined in [this page](../../materials/actions/import.md).We select the F-43m space group lowest energy structure, the most stable, polymorph of GaP. +## 1. Import the material into the collection -## Use Material in Materials Designer +The first step is to import one of the III-V compound semiconductors, Gallium Phosphide (GaP), into the account-owned [collection]({{ reference_url }}/accounts/collections/) of materials. This crystal structure can be **imported** directly from a remote repository by following the instructions in [this page]({{ interface_url }}/materials/actions/import/). The F-43m space group lowest-energy structure (the most stable polymorph of GaP) should be selected. -The reader should now [open](../../entities-general/actions/create.md) a new instance of the [Materials Designer Interface](../../materials-designer/overview.md) for creating and designing new material structures. The first step here involves importing the above-mentioned Gallium Phosphide crystal structure into the designer itself, via the [Import option](../../materials-designer/header-menu/input-output/import.md) under the [Input/Output Menu](../../materials-designer/header-menu/input-output.md) of the interface. -## Create Combinatorial Set +## 2. Open the material in Materials Designer -### Open "Generate Combinatorial Set" Dialog +[Open]({{ interface_url }}/entities-general/actions/create/) a new instance of the [Materials Designer Interface]({{ interface_url }}/materials-designer/overview/). Import the above-mentioned Gallium Phosphide crystal structure via the [Import option]({{ interface_url }}/materials-designer/header-menu/input-output/import/) under the [Input/Output Menu]({{ interface_url }}/materials-designer/header-menu/input-output/). -The functionality to create combinatorial sets can be accessed via the [Advanced Menu](../../materials-designer/header-menu/advanced.md) of the [Materials Designer Interface](../../materials-designer/overview.md). Under this menu, the user should select the relevant "Combinatorial Set" option. -The main operations made possible by the resulting "Generate Combinatorial Set" dialog are further reviewed in detail [in this page](../../materials-designer/header-menu/advanced/combinatorial-set.md). +## 3. Create the combinatorial set -### n and p-type Dopants for Gallium Phosphide +### 3.1. Open the Generate Combinatorial Set dialog -We will examine the effects of n and p-type dopants on Gallium Phosphide. We remind the reader about which elements constitute dopant atoms when inserted into the Gallium Phosphide crystal structure. +The functionality to create combinatorial sets is accessible via the [Advanced Menu]({{ interface_url }}/materials-designer/header-menu/advanced/) of the [Materials Designer Interface]({{ interface_url }}/materials-designer/overview/). Select the "Combinatorial Set" option. -- n-type: tellurium, selenium, sulphur (substituting phosphorus). -- p-type: zinc, magnesium (substituting Ga), tin (substituting P). +The operations available in the resulting dialog are described in detail [in this page]({{ interface_url }}/materials-designer/header-menu/advanced/combinatorial-set/). -### Generate Permutations +### 3.2. Identify n- and p-type dopants for Gallium Phosphide -**Permutations** change all element atoms in the [basis](../../properties-directory/structural/basis.md) of the crystal structure simultaneously, and are enabled when chemical elements are separated by slashes (`/`) with no trailing spaces. +The following elements constitute dopant atoms when inserted into the Gallium Phosphide crystal structure: -The user should hence try replacing the first line under the "Generate Combinatorial Set" dialog, containing the Gallium atom located at the origin of the unit cell, with the following line. +- n-type: tellurium, selenium, sulphur (substituting phosphorus) +- p-type: zinc, magnesium (substituting Ga), tin (substituting P) + +### 3.3. Generate permutations + +**Permutations** change all element atoms in the [basis]({{ reference_url }}/properties-directory/structural/basis/) of the crystal structure simultaneously, and are enabled when chemical elements are separated by slashes (`/`) with no trailing spaces. + +Replace the first line under the dialog, containing the Gallium atom located at the origin of the unit cell, with the following line: ```text Zn/Mg 0.0 0.0 0.0 ``` -Pressing the "Generate Combinatorial Set" button at the bottom of the dialog will generate the permutations of the Gallium Phosphide crystal structure containing p-type dopants, which are added to the [left-hand sidebar list of structures](../../materials-designer/sidebar-items.md) of Materials Designer, on top of the original GaP material structure. +Pressing the **Generate Combinatorial Set** button generates the permutations of the Gallium Phosphide crystal structure containing p-type dopants, which are added to the [left-hand sidebar list]({{ interface_url }}/materials-designer/sidebar-items/}) of Materials Designer. -The basis atoms of the original GaP structure had the following atomic positions, expressed in fractional coordinates and viewable under the [source editor](../../materials-designer/source-editor/basis.md) interface component: +The basis atoms of the original GaP structure had the following atomic positions, expressed in fractional coordinates and viewable under the [source editor]({{ interface_url }}/materials-designer/source-editor/basis/): ```text -Ga 0.000000 0.000000 0.000000 -P 0.750000 0.750000 0.750000 +Ga 0.000000 0.000000 0.000000 +P 0.750000 0.750000 0.750000 ``` -Consequently, the resulting permutations consist in the following two crystal structure possibilities: +The resulting permutations consist of the following two crystal structure possibilities: ```text -Zn 0.000000 0.000000 0.000000 -P 0.750000 0.750000 0.750000 +Zn 0.000000 0.000000 0.000000 +P 0.750000 0.750000 0.750000 ``` ```text -Mg 0.000000 0.000000 0.000000 -P 0.750000 0.750000 0.750000 +Mg 0.000000 0.000000 0.000000 +P 0.750000 0.750000 0.750000 ``` -Therefore, we see how permutations had the effect of replacing the original Gallium atom at the origin with each of the Zinc and Magnesium p-type dopants. +Permutations thus replaced the original Gallium atom at the origin with each of the Zinc and Magnesium p-type dopants. -### Generate Combinations +### 3.4. Generate combinations -**Combinations** change the elements in the [basis](../../properties-directory/structural/basis.md) of the crystal structure one at a time, and are enabled when commas are used as separators (`,`) with no trailing spaces. +**Combinations** change the elements in the [basis]({{ reference_url }}/properties-directory/structural/basis/) one at a time, and are enabled when commas are used as separators (`,`) with no trailing spaces. -In order to explore the alternative case of Combinations, we shall replace both the Phosphorus and Gallium atoms in GaP with all possible aforementioned n and p-type dopant atoms. This can be achieved by replacing the two lines in the "Generate Combinatorial Set" dialog with the following content. +In order to explore combinations, replace both the Phosphorus and Gallium atoms in GaP with all possible n- and p-type dopant atoms. This can be achieved by entering the following content in the dialog: ```text Zn,Mg 0.000000 0.000000 0.000000 -Te,Se,S,Sn 0.750000 0.750000 0.750000 +Te,Se,S,Sn 0.750000 0.750000 0.750000 ``` -We reproduce below the resulting combinatorial list of atomic positions contained in the generated structures, which can be retrieved under the [left-hand sidebar](../../materials-designer/sidebar-items.md) of Materials Designer, once the "Generate Combinatorial Set" button is clicked. +The resulting combinatorial list of atomic positions in the generated structures can be retrieved under the [left-hand sidebar]({{ interface_url }}/materials-designer/sidebar-items/) of Materials Designer, once the **Generate Combinatorial Set** button is clicked: ```text -Zn 0.000000 0.000000 0.000000 -Te 0.750000 0.750000 0.750000 +Zn 0.000000 0.000000 0.000000 +Te 0.750000 0.750000 0.750000 ``` ```text -Zn 0.000000 0.000000 0.000000 -Se 0.750000 0.750000 0.750000 +Zn 0.000000 0.000000 0.000000 +Se 0.750000 0.750000 0.750000 ``` ```text -Zn 0.000000 0.000000 0.000000 -S 0.750000 0.750000 0.750000 +Zn 0.000000 0.000000 0.000000 +S 0.750000 0.750000 0.750000 ``` ```text -Zn 0.000000 0.000000 0.000000 -Sn 0.750000 0.750000 0.750000 +Zn 0.000000 0.000000 0.000000 +Sn 0.750000 0.750000 0.750000 ``` ```text -Mg 0.000000 0.000000 0.000000 -Te 0.750000 0.750000 0.750000 +Mg 0.000000 0.000000 0.000000 +Te 0.750000 0.750000 0.750000 ``` ```text -Mg 0.000000 0.000000 0.000000 -Se 0.750000 0.750000 0.750000 +Mg 0.000000 0.000000 0.000000 +Se 0.750000 0.750000 0.750000 ``` ```text -Mg 0.000000 0.000000 0.000000 -S 0.750000 0.750000 0.750000 +Mg 0.000000 0.000000 0.000000 +S 0.750000 0.750000 0.750000 ``` ```text -Mg 0.000000 0.000000 0.000000 -Sn 0.750000 0.750000 0.750000 +Mg 0.000000 0.000000 0.000000 +Sn 0.750000 0.750000 0.750000 ``` -### Generate Vacancy Sites +### 3.5. Generate vacancy sites + +When the "VAC" keyword is used instead of an element name, a vacancy is created at the corresponding crystal site. Vacancies can be added as part of the generated combinatorial set, and can be combined with either slashes for permutations or commas for combinations (with no trailing spaces). -When the "VAC" keyword is used instead of an element name, such as "Ga" or "P", a vacancy will be created at the corresponding crystal site. Vacancies can be added as part of the generated combinatorial set, and can be combined with either slashes to generate corresponding permutations, or commas for combinations (with no trailing spaces). +An example of this functionality is provided [in this page]({{ interface_url }}/materials-designer/header-menu/advanced/combinatorial-set/#vacancy-sites). -An example of this functionality is provided [in this page](../../materials-designer/header-menu/advanced/combinatorial-set.md#vacancy-sites). -## Animation +## 4. Video walkthrough -We demonstrate how the above-mentioned combinatorial sets can be generated within [Materials Designer](../../materials-designer/overview.md) in the following animation, where we first import the original Gallium Phosphide crystal structure. +The animation below demonstrates how the above-mentioned combinatorial sets can be generated within [Materials Designer]({{ interface_url }}/materials-designer/overview/), starting from the original Gallium Phosphide crystal structure.
diff --git a/lang/en/docs/tutorials/materials/import-from-files.md b/lang/en/docs/tutorials/materials/import-from-files.md index 768234431..ea890e201 100644 --- a/lang/en/docs/tutorials/materials/import-from-files.md +++ b/lang/en/docs/tutorials/materials/import-from-files.md @@ -1,49 +1,55 @@ -# Import Materials from files in various formats +# Import Materials from Files in Various Formats -This tutorial explains how to import materials from files in various formats into the Materials Designer interface. With the help of notebook that uses ASE python package to extract structural information from files in multiple formats (CIF, POSCAR, etc., as supported by ASE). Some formats, like espresso-in and espresso-out can be inferred from the file content. +This tutorial explains how to import materials from files in various formats into the Materials Designer interface. A JupyterLite notebook using the ASE Python package extracts structural information from files in multiple formats (CIF, POSCAR, etc., as supported by ASE). Some formats, such as espresso-in and espresso-out, can be inferred from the file content. -## Step 0: Open Materials Designer -Start by opening an instance of the [Materials Designer Interface](../../materials-designer/overview.md) for creating and designing new [Materials structures](../../materials/overview.md) on our platform. +## 1. Open Materials Designer -## Step 1: Open JupyterLite Environment +[Open]({{ interface_url }}/entities-general/actions/create/) an instance of the [Materials Designer Interface]({{ interface_url }}/materials-designer/overview/). -Open the [JupyterLite Environment](../../materials-designer/header-menu/advanced/jupyterlite-dialog.md) by navigating to "Advanced" > "JupyterLite Transformation" menu item in the Materials Designer interface. -## Step 2: Open the Notebook +## 2. Open the JupyterLite environment -Open the "Materials import from files in ASE-supported formats" in the Introduction.ipynb notebook. +Open the [JupyterLite Environment]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/) by navigating to *Advanced* > *JupyterLite Transformation* in the Materials Designer interface. + + +## 3. Open the notebook + +Open "Materials import from files in ASE-supported formats" in the Introduction.ipynb notebook. ![JupyterLite session with Introduction notebook](../../images/tutorials/import_from_files/open_notebook.webp "Open Notebook") -## Step 3: Upload files -Double-click the `uploads` folder in the File Browser tab on the left to open it. Drag and drop the files you want to import into the field. +## 4. Upload files + +Double-click the `uploads` folder in the File Browser tab on the left to open it. Drag and drop the files to be imported into the field. ![JupyterLite session with uploaded files in the files browser](../../images/tutorials/import_from_files/upload_files.webp "Upload Files") -## Step 4: Run the Notebook -Run the notebook by clicking the "Run All Cells" button in the toolbar or execute each cell by pressing "Shift + Enter" if you want to review results or change the code in the process. +## 5. Run the notebook + +Run the notebook by clicking the **Run All Cells** button in the toolbar, or execute each cell individually by pressing **Shift + Enter** to review results or modify the code in the process. ![JupyterLite session with Run menu open](../../images/tutorials/import_from_files/run_notebook.webp "Run Notebook") -## Step 5: Review the Results and Submit -Materials should appear in the "Materials Out" dropdown at the bottom of the dialog. Select the material you want to work with and click "Submit" to load it into the Materials Designer. +## 6. Review the results and submit + +Materials should appear in the "Materials Out" dropdown at the bottom of the dialog. Select the material to work with and click **Submit** to load it into the Materials Designer. -In case ASE is unable to read the file, an error message will be printed stating the unreadable files and a table of available formats. -In this case, you can try to fix the issue and re-run the notebook. The error with some files does not prevent other files from being read. +If ASE is unable to read a file, an error message is printed stating the unreadable files and a table of available formats. The issue can be fixed and the notebook re-run. Errors with some files do not prevent other files from being read. ![JupyterLite Transformation dialog with materials_out dropdown populated](../../images/tutorials/import_from_files/submit_results.webp "Review Results and Submit") -## Additional Information -### ASE +## 7. Additional information + +### 7.1. ASE -The information about ASE IO can be found [here](https://wiki.fysik.dtu.dk/ase/ase/io/io.html). The version of ASE used in the JupyterLite environment is 3.22.1 (as of 2024-04-05). +Information about ASE IO can be found [here](https://wiki.fysik.dtu.dk/ase/ase/io/io.html). The version of ASE used in the JupyterLite environment is 3.22.1 (as of 2024-04-05). -### Supported Formats +### 7.2. Supported formats `ase.io.formats.ioformats` provides the list of supported formats: diff --git a/lang/en/docs/tutorials/materials/interpolated-sets.md b/lang/en/docs/tutorials/materials/interpolated-sets.md index a73d92c9d..07920d187 100644 --- a/lang/en/docs/tutorials/materials/interpolated-sets.md +++ b/lang/en/docs/tutorials/materials/interpolated-sets.md @@ -1,14 +1,15 @@ # Create Interpolated Sets -This tutorial page explains how to create an [interpolated set](../../materials-designer/header-menu/advanced/interpolated-set.md), necessary for the calculation of the energy profile and activation barrier for the multi-dimensional energy space of chemical reactions via the Nudged Elastic Bands (NEB) method, which is reviewed in a [separate tutorial](../dft/chemical/reaction-profile-qe.md). +This tutorial explains how to create an [interpolated set]({{ interface_url }}/materials-designer/header-menu/advanced/interpolated-set/), necessary for calculating the energy profile and activation barrier for chemical reactions via the Nudged Elastic Bands (NEB) method, which is described in a [separate tutorial](../dft/chemical/reaction-profile-qe.md). -We consider the example of a one-dimensional, three-atom molecule of Hydrogen (H3) throughout the present tutorial. +The example system is a one-dimensional, three-atom molecule of Hydrogen (H3). -## Upload Initial and Final Images to Materials Collection -The datafiles containing the structural information about the initial and final states of the H3 molecule under consideration should first be [uploaded](../../materials/actions/upload.md) to the account-owned collection of materials. +## 1. Upload initial and final images to the materials collection -For the sake of the present tutorial, we will consider the following two POSCAR files, containing the structural parameters for the initial and final molecular configurations respectively: +The datafiles containing the structural information for the initial and final states of the H3 molecule should first be [uploaded]({{ interface_url }}/materials/actions/upload/) to the account-owned collection of materials. + +The following two POSCAR files contain the structural parameters for the initial and final molecular configurations respectively: ```text initial @@ -38,57 +39,56 @@ direct 0.380558400 0.000000000 0.000000000 H ``` -## Create an Interpolated Set via Materials Designer -### Open Materials Designer and Import Initial/Final Configurations +## 2. Create an interpolated set via Materials Designer + +### 2.1. Open Materials Designer and import the configurations + +[Open]({{ interface_url }}/entities-general/actions/create/) an instance of the [Materials Designer Interface]({{ interface_url }}/materials-designer/overview/). Import the initial and final configurations by following [these instructions]({{ interface_url }}/materials-designer/header-menu/input-output/import/). It is essential to [clone]({{ interface_url }}/materials-designer/header-menu/edit/#clone) both initial and final images before generating the interpolated set, and to [delete]({{ interface_url }}/materials-designer/sidebar-items/#delete-item) the original structures from the [left-hand sidebar]({{ interface_url }}/materials-designer/sidebar-items/) for correct index attribution within the resulting ordered set. -The user should now [open](../../entities-general/actions/create.md) an instance of the [Materials Designer Interface](../../materials-designer/overview.md), through which we aim to create our Interpolated Set in between the above-mentioned initial and final configurations of the H3 molecule. +### 2.2. Generate the interpolated set -The first step consists in importing these two configurations into the interface by following [these instructions](../../materials-designer/header-menu/input-output/import.md). It is essential then to [clone](../../materials-designer/header-menu/edit.md#clone) both initial and final images before generating the interpolated set, as well as to [delete](../../materials-designer/sidebar-items.md#delete-item) the original structures from the [left-hand items list sidebar](../../materials-designer/sidebar-items.md) of the Materials Designer Interface, for a correct final attribution of the indices within the resulting ordered set. +Before creating a new interpolated set, the active structure selected on the [left-hand sidebar]({{ interface_url }}/materials-designer/sidebar-items/) must be the initial image (not the final). This ensures that intermediate images are correctly injected between the initial and final configurations. -### Generate Interpolated Set +The Interpolated Set can be generated via the [corresponding option]({{ interface_url }}/materials-designer/header-menu/advanced/interpolated-set/) within the [Advanced Menu]({{ interface_url }}/materials-designer/header-menu/advanced/) of the [header bar]({{ interface_url }}/materials-designer/header-menu/header-menu-intro/). -Before creating a new interpolated set, the user should make sure that the active structure selected on the [left-hand items list sidebar](../../materials-designer/sidebar-items.md) is the initial one, and not final. This ensures that the intermediate images will be correctly injected between the initial and final ones at the moment of creation of the new interpolated set. +In the resulting dialog, the total number of intermediate images to generate can be selected — 3 intermediate images are used in this example. -The Interpolated Set itself can be generated via the [corresponding option](../../materials-designer/header-menu/advanced/interpolated-set.md) within the [Advanced Menu](../../materials-designer/header-menu/advanced.md) of the [header bar](../../materials-designer/header-menu/header-menu-intro.md). - -In the resulting "Generate Interpolated Set" dialog, the user is able to select the total number of intermediate images that need to be generated, which we select to be 3 for the sake of the present demonstrative explanation. +### 2.3. Add atomic constraints -### Adding Atomic Constraints +**Atomic Constraints**, specifying the constraints on atom movement, can be defined as explained [in this page]({{ reference_url }}/properties-directory/structural/basis/#atomic-constraints). -**Atomic Constraints**, specifying the constraints on the movement of atoms, can be also be defined as explained [in this page](../../properties-directory/structural/basis.md#atomic-constraints). +These constraints need only be added to the initial image before the creation of the interpolated set, under the [basis panel]({{ interface_url }}/materials-designer/source-editor/basis/) of the [source editor]({{ interface_url }}/materials-designer/source-editor/) in [Materials Designer]({{ interface_url }}/materials-designer/overview/). Once the interpolated set is generated, the same constraints are applied to all other intermediate images. -These constraints need only be added to the initial image before the creation of the interpolated set, under the [basis panel](../../materials-designer/source-editor/basis.md) of the [source editor](../../materials-designer/source-editor.md) in [Materials Designer](../../materials-designer/overview.md). Later, once the interpolated set is generated, the same constraints will be applied automatically to all other intermediate images. +Adding atomic constraints can help make the ensuing NEB calculation more computationally efficient. -Adding atomic constraints in this way can help to make the ensuing NEB calculation more computationally efficient. +### 2.4. Inspect intermediate images -### Inspect Intermediate Images +The structures for all resulting intermediate images are listed alongside the initial and final molecular configurations in the [left-hand sidebar]({{ interface_url }}/materials-designer/sidebar-items/). These images can be visualized and cycled through using the [3D structure editor]({{ interface_url }}/materials-designer/3d-editor/). -The user should now be able to inspect the structures for all the resulting intermediate images, which are listed together with the previously-imported initial and final molecular configurations within the [left-hand items list sidebar](../../materials-designer/sidebar-items.md) of the Materials Designer Interface. -These images can be visualized and cycled through with the help of the incorporated [3D structure editor](../../materials-designer/3d-editor.md). +## 3. Save all images in an NEB SET -## Save all Images in NEB SET +All generated images should be [saved]({{ interface_url }}/materials-designer/header-menu/input-output/save/) into an ordered set called "NEB SET", as described below. The creation and selection of sets is made possible by the appropriate option of the "Save Items" dialog. -Finally, **all** generated images should now be [saved](../../materials-designer/header-menu/input-output/save.md) into an ordered set called "NEB SET", which can be created as explained in what follows. The creation and selection of sets in which to save images is made possible by the appropriate option of the "Save Items" dialog. +### 3.1. Create an ordered set -### Create an Ordered SET +[These instructions]({{ interface_url }}/entities-general/actions/create-sets/) demonstrate how to create a [Set]({{ reference_url }}/entities-general/sets/) within the account-owned [collection]({{ reference_url }}/accounts/collections/) of materials, named "NEB SET". After creation, the type of this set should be [changed]({{ interface_url }}/entities-general/actions/change-set-type/) to **ordered**. -[These instructions](../../entities-general/actions/create-sets.md) demonstrate how to create a [Set](../../entities-general/sets.md) within the account-owned [collection](../../accounts/collections.md) of materials, which we shall name and refer to as "NEB SET". Following its creation, the type of this set should then be [changed](../../entities-general/actions/change-set-type.md) to **ordered**. -## Animations +## 4. Video walkthroughs -### General Interpolated Set Creation +### 4.1. General interpolated set creation -We summarize the aforementioned steps involved in generating an Interpolated Set for our linear H3 molecule in the animation below. We conclude the video by inspecting the full list of images, including the initial and final molecular configurations, under the [Explorer Interface](../../entities-general/ui/explorer.md) of the newly-created "NEB SET". +The animation below demonstrates the steps involved in generating an Interpolated Set for the linear H3 molecule. The video concludes by inspecting the full list of images under the [Explorer Interface]({{ interface_url }}/entities-general/ui/explorer/) of the newly-created "NEB SET".
-### Constrained Interpolated Set Creation +### 4.2. Constrained interpolated set creation -In this second animation, we demonstrate how to add the atomic constraints discussed previously into a new "Constrained" Interpolated Set for NEB applications, confining the movement of atoms to only the x-direction since our H3 molecules are entirely one-dimensional. This is done by adding the "1 0 0" line next to the atoms in the initial image, except for the atom located at the origin, for which a "0 0 0" constraint suffices since this this atom remains fixed at all times. +The animation below demonstrates how to add atomic constraints to a new "Constrained" Interpolated Set for NEB applications. The movement of atoms is confined to the x-direction since the H3 molecules are entirely one-dimensional. This is done by adding the "1 0 0" line next to the atoms in the initial image, except for the atom located at the origin, for which a "0 0 0" constraint suffices since it remains fixed at all times.
diff --git a/lang/en/docs/tutorials/materials/jupyterlite-zsl.md b/lang/en/docs/tutorials/materials/jupyterlite-zsl.md index cd68b948a..778e1b245 100644 --- a/lang/en/docs/tutorials/materials/jupyterlite-zsl.md +++ b/lang/en/docs/tutorials/materials/jupyterlite-zsl.md @@ -1,77 +1,85 @@ -# Create an interface between two materials in JupyterLite notebook +# Create an Interface with JupyterLite (ZSL Algorithm) -This tutorial explains how to create an interface between two materials in Materials Designer employing ZSL algorithm. Example is given for creating an interface between Graphene and Ni(111). +This tutorial explains how to create an interface between two materials in Materials Designer using the Zur and McGill Superlattice (ZSL) algorithm. The example demonstrates creating an interface between Graphene and Ni(111). -## Step 0: Open Materials Designer -We start with [opening](../../entities-general/actions/create.md) an instance of the [Materials Designer Interface](../../materials-designer/overview.md) for creating and designing new [Materials structures](../../materials/overview.md) on our platform. +## 1. Open Materials Designer -## Step 1: Import Materials +[Open]({{ interface_url }}/entities-general/actions/create/) an instance of the [Materials Designer Interface]({{ interface_url }}/materials-designer/overview/). -In order to use Graphene and Ni, the user should first [import](../../materials-designer/header-menu/input-output/import.md) sample crystalline structures of the two respective materials into the current Materials Designer session, from the account-owned [collection](../../accounts/collections.md) of materials. -Another option is to use materials from a Standard Materials Dataset via [Import from Standata](../../materials-designer/header-menu/input-output/standata-import.md). +## 2. Import the materials + +In order to use Graphene and Ni, the respective crystalline structures should first be [imported]({{ interface_url }}/materials-designer/header-menu/input-output/import/) into the current Materials Designer session from the account-owned [collection]({{ reference_url }}/accounts/collections/) of materials. + +Another option is to use materials from a Standard Materials Dataset via [Import from Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/). After importing, Graphene and Ni should be available in the materials list. Gr and Ni available in materials list -## Step 2: Use JupyterLite Session Dialog -Navigate to `Advanced` > `JupyterLite Session` from the main interface. +## 3. Open the JupyterLite Session dialog + +Navigate to *Advanced* > *JupyterLite Session* from the main interface. Open JupyterLite Dialog -- In the Introduction notebook find the link to the example under `Examples` > `1. Builders / Transformations` > `1.1. Interface creation with Zur and McGill Superlattice algorithm` +In the Introduction notebook, find the link to the example under *Examples* > *1. Builders / Transformations* > *1.1. Interface creation with Zur and McGill Superlattice algorithm*. Open Example Notebook - -- The link will open the example notebook in a new tab. -## Step 3: Run the Example +The link opens the example notebook in a new tab. + + +## 4. Run the example -- Select Input Materials from the dropdown list to make them available in the notebook. (Ni and Graphene in this case) +Select Input Materials from the dropdown list to make them available in the notebook (Ni and Graphene in this case). Select Input Materials - -- Run the cell marked as `Run first` to load the input materials into the notebook. (Loading is done asynchronously from outside JupyterLite kernel, so it may take a few seconds for the kernel to register) + +Run the cell marked as *Run first* to load the input materials into the notebook. Loading is done asynchronously from outside the JupyterLite kernel, so it may take a few seconds for the kernel to register. Run First Cell - -- Set Input Parameters for substrate and layer materials, resulting interface and the algorithm. (In this case, Ni regarded as the substrate and Graphene as the layer. Since unit lattices of Graphene and Ni(111) plane are close, we should reduce the maximum search area for superlattice matching to 100 Angstrom^2 to speed up the search) + +Set Input Parameters for substrate and layer materials, the resulting interface, and the algorithm. In this case, Ni is the substrate and Graphene is the layer. Since the unit lattices of Graphene and Ni(111) are close in size, the maximum search area for superlattice matching should be reduced to 100 Ų to speed up the search. Set Input Parameters - -- Click `Run` > `Run All` to run cells and wait for the results to appear. (Depending on the `MAX_AREA` parameter, the search may take from seconds to a few minutes to complete.) + +Click *Run* > *Run All* to run all cells and wait for the results to appear. Depending on the `MAX_AREA` parameter, the search may take from seconds to a few minutes. Run All Cells -## Step 4: Analyze the Results -- Output of cell under "2. Install Packages" should display a list of successfully installed packages + +## 5. Analyze the results + +The output of the cell under "2. Install Packages" displays a list of installed packages. Install Packages - -- Output of cell under "3.2. Print out the interfaces and terminations" should display the number of possible terminations (in this case 1) and the number of interfaces for each termination (in this case 1211) + +The output of the cell under "3.2. Print out the interfaces and terminations" displays the number of possible terminations (1 in this case) and the number of interfaces for each termination (1211 in this case). Print Interfaces and Terminations - -- Output of cell under "4.2. Print out interfaces with the lowest strain for each termination" should display the strain and number of atoms for the interface with the lowest strain for each termination. -- Output of cell under "5. Plot the results" should display a plot of the strain vs number of atoms for each interface. Each point on the plot represents an interface with data for termination, interface index, strain and number of atoms. + +The output of cell "4.2. Print out interfaces with the lowest strain for each termination" displays the strain and number of atoms for the interface with the lowest strain per termination. The output of cell "5. Plot the results" displays a plot of strain vs. number of atoms for each interface. Each point on the plot represents an interface with data for termination, interface index, strain, and number of atoms. Plot Results -## Step 5: Select the Interfaces to Return -- Select the termination for the interface by setting variable `termination_index` to respective value (0 by default), and then the number of interfaces with lowest strain to return (by default set to 1). -- Verify that Output Materials dropdown contains the selected interface(s). -- Click "Submit" to pass materials to the Materials Designer session and take it from there. -- Graphene on Ni(111) interface should now be available in the materials list and can be viewed in the 3D viewer. + +## 6. Select the interfaces to return + +Select the termination for the interface by setting the variable `termination_index` to the respective value (0 by default), then set the number of interfaces with the lowest strain to return (1 by default). Verify that the Output Materials dropdown contains the selected interfaces. Click **Submit** to pass materials to the Materials Designer session. + +The Graphene-on-Ni(111) interface should now be available in the materials list and can be viewed in the 3D viewer. Select Interfaces - -- We can add repetition alongside x and y directions and add bonds to see the result more clearly. + +Repetitions along x and y directions and bonds can be added to visualize the result more clearly. Add repetitions and bonds -## Links -- Zur and McGill Superlattice algorithm paper: (https://doi.org/10.1063/1.333084) -- Zur and McGill Superlattice algorithm implementation by PyMatGen documentation: (https://pymatgen.org/pymatgen.analysis.interfaces.html) \ No newline at end of file + +## 7. Links + +- [Zur and McGill Superlattice algorithm paper](https://doi.org/10.1063/1.333084) +- [PyMatGen ZSL implementation documentation](https://pymatgen.org/pymatgen.analysis.interfaces.html) \ No newline at end of file diff --git a/lang/en/docs/tutorials/materials/molecule-surface.md b/lang/en/docs/tutorials/materials/molecule-surface.md index 7681fc8a8..8efcb23ac 100644 --- a/lang/en/docs/tutorials/materials/molecule-surface.md +++ b/lang/en/docs/tutorials/materials/molecule-surface.md @@ -1,10 +1,11 @@ -# Create Molecule on a Surface +# Create a Molecule on a Surface -In this tutorial, the user will learn about how the [Material Designer Interface](../../materials-designer/overview.md) of our platform can be used to create a geometry for modeling a **surface chemical reaction**, whereby a **molecule interacts with a surface**, and undergoes for example a chemical **adsorption** process [^1]. +This tutorial demonstrates how the [Material Designer Interface]({{ interface_url }}/materials-designer/overview/) can be used to create a geometry for modeling a **surface chemical reaction**, where a **molecule interacts with a surface** and undergoes, for example, a chemical **adsorption** process [^1]. -We consider the example of a **benzene molecule** adsorbed on a **gold (Au) (211) surface** throughout the present tutorial. The chemical structure of the benzene molecule is given in the expandable section below for reference purposes, in the POSCAR input data format. +The example system is a **benzene molecule** adsorbed on a **gold (Au) (211) surface**. The chemical structure of the benzene molecule is given in the expandable section below in the POSCAR input data format. -## Structures + +## 1. Reference structures
@@ -35,84 +36,95 @@ Direct
-Alternatively, the above benzene molecular structure can also be retrieved from the **Pubchem** public repository [^2], and then converted to the POSCAR format for uploading on our platform through any online converter, such as the **OpenBabel** Open Source Chemistry Toolbox [^3], which allows to convert between nearly all the chemical data formats. +Alternatively, the benzene molecular structure can be retrieved from the **Pubchem** public repository [^2] and converted to POSCAR format using any online converter such as the **OpenBabel** Open Source Chemistry Toolbox [^3]. + + +## 2. Create the benzene molecule entry in the materials collection + +The chemical structure for benzene can be [imported]({{ interface_url }}/materials/actions/copy-bank/) from the [Materials Bank]({{ reference_url }}/materials/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/), if not already present. -## Create Benzene Molecule Entry in Materials Collection +Alternatively, the above-mentioned POSCAR structure can be manually [uploaded]({{ interface_url }}/materials/actions/upload/) into the materials collection after saving its data contents to a new file on the local disk. -The chemical structure for Benzene can readily be [imported](../../materials/actions/copy-bank.md) from the [Materials Bank](../../materials/bank.md) into the account-owned [collection](../../accounts/collections.md), if it is not already present there. -Alternatively, the above-mentioned POSCAR structure can be manually [uploaded](../../materials/actions/upload.md) by the user into the materials collection, after saving its data contents into a new file on the local disk. - -## Open Materials Designer +## 3. Open Materials Designer -We start with [opening](../../entities-general/actions/create.md) an instance of the [Materials Designer Interface](../../materials-designer/overview.md) for creating and designing new [Materials structures](../../materials/overview.md) on our platform. +[Open]({{ interface_url }}/entities-general/actions/create/) an instance of the [Materials Designer Interface]({{ interface_url }}/materials-designer/overview/). -## Create a Gold Surface -In order to create a gold surface, the user should first [import](../../materials-designer/header-menu/input-output/import.md) a sample crystalline structure of pure gold into the current Materials Designer session, from the account-owned [collection](../../accounts/collections.md) of materials. +## 4. Create the gold surface -The instructions contained [in this page](../../materials-designer/header-menu/advanced/surface-slab.md) should then be followed in order to create a surface of Gold, with normal vector oriented along the [211] axis, using our surface creator in Materials Designer, starting from the original gold crystalline sample. +In order to create a gold surface, first [import]({{ interface_url }}/materials-designer/header-menu/input-output/import/) a sample crystalline structure of pure gold into the current Materials Designer session from the account-owned [collection]({{ reference_url }}/accounts/collections/). + +Follow the instructions [in this page]({{ interface_url }}/materials-designer/header-menu/advanced/surface-slab/) to create a surface of gold with normal vector oriented along the [211] axis. !!!warning "Order of structures is important" - The gold surface has to be created first in order for it to appear first in the list of materials shown on the [left-had items list sidebar](../../materials-designer/sidebar-items.md) of the Materials Designer interface, so that its cell is used when later combining the two materials together. + The gold surface must be created first so that it appears first in the [left-hand sidebar]({{ interface_url }}/materials-designer/sidebar-items/), ensuring its cell is used when later combining the two materials together. + + +## 5. Import the benzene molecule into Materials Designer -## Import the Benzene Molecule into Materials Designer +The benzene molecule should be [imported]({{ interface_url }}/materials-designer/header-menu/input-output/import/) into the current Materials Designer session from the account-owned [collection]({{ reference_url }}/accounts/collections/). -The Benzene molecule should now be [imported](../../materials-designer/header-menu/input-output/import.md) into the current Materials Designer session, from the account-owned [collection](../../accounts/collections.md) of materials. +Once imported, the benzene molecule appears as a distinct entry in the [left-hand sidebar]({{ interface_url }}/materials-designer/sidebar-items/), alongside the previously-generated gold surface. -Once imported into Materials Designer, the benzene molecule will appear as a new distinct entry item within the list of structures shown on the [left-had items list sidebar](../../materials-designer/sidebar-items.md) of the Designer interface, besides the previously-generated gold surface. - -Care should be taken by the user to [remove](../../materials-designer/sidebar-items.md#delete-item) any other material structure entry listed in the sidebar, besides benzene and the gold surface being considered here, that may have been loaded by [default](../../materials/default.md) initially at the moment of the opening of Materials Designer. +Any other material structure entries listed in the sidebar — aside from benzene and the gold surface — should be [removed]({{ interface_url }}/materials-designer/sidebar-items/#delete-item). -## Open Multi-Materials 3D Editor -After both the benzene molecule and the gold surface have been created as two separate structural items in the current session of Materials Designer, the user should now open an instance of the [Multi-Materials 3D Editor](../../materials-designer/3d-editor/edit.md) via the ["View" Menu](../../materials-designer/header-menu/view.md#multi-material-3d-editor), located within the [header bar](../../materials-designer/header-menu/header-menu-intro.md) of the Materials Deigner Interface. +## 6. Open the Multi-Materials 3D Editor -## Combine the Two Materials +After both the benzene molecule and the gold surface are listed as separate structural items, open the [Multi-Materials 3D Editor]({{ interface_url }}/materials-designer/3d-editor/edit/) via the [View Menu]({{ interface_url }}/materials-designer/header-menu/view/#multi-material-3d-editor). -The Multi-Materials 3D Editor allows the two materials under investigation, the benzene molecule and the gold surface, to be **combined** together into a new unified materials entity. -Care should be taken by the user to place the molecule on top of the surface in as "symmetrical" a way as possible, for example by positioning the center of the benzene ring on the central portion of the surface. Relocation of the benzene molecule position can be done by following the instructions contained [in this page](../../materials-designer/3d-editor/editor-actions/move-rotate-atoms.md), after selecting the benzene atom components under the ["Scene" sidebar list](../../materials-designer/3d-editor/edit.md#3.-scene) of the 3D Editor interface. +## 7. Combine the two materials -Since in this example the plane of the 2D benzene molecule and the gold (211) surface are already parallel to each other, a simple [translation](../../materials-designer/3d-editor/editor-actions/move-rotate-atoms.md#translation) of the benzene atoms on top of the surface should suffice. +The Multi-Materials 3D Editor allows the two materials to be **combined** into a new unified entity. -## Exit Multi-Materials 3D Editor +The molecule should be positioned on top of the surface in as "symmetrical" a way as possible, for example by placing the center of the benzene ring over the central portion of the surface. Relocation of the benzene molecule position can be done following the instructions [in this page]({{ interface_url }}/materials-designer/3d-editor/editor-actions/move-rotate-atoms/), after selecting the benzene atom components under the [Scene sidebar list]({{ interface_url }}/materials-designer/3d-editor/edit/#3.-scene). -After the correct desired positioning of the benzene molecule on top of the gold surface, the user should now [exit](../../materials-designer/3d-editor/edit.md#exit-the-editor) the Multi-Materials 3D Editor, and return to the original Materials Designer interface. +Since in this example the plane of the 2D benzene molecule and the gold (211) surface are already parallel, a [translation]({{ interface_url }}/materials-designer/3d-editor/editor-actions/move-rotate-atoms/#translation) of the benzene atoms onto the surface is sufficient. -The user will notice that a new material entry, called "New Material" by default, has now been created automatically and is listed within the [left-had items list sidebar](../../materials-designer/sidebar-items.md) of the Materials Designer interface. It contains the combined benzene-gold surface crystallographic structure, as a new single material entity. + +## 8. Exit the Multi-Materials 3D Editor + +After correct positioning of the benzene molecule on top of the gold surface, [exit]({{ interface_url }}/materials-designer/3d-editor/edit/#exit-the-editor) the Multi-Materials 3D Editor. + +A new material entry, called "New Material" by default, is created and listed in the [left-hand sidebar]({{ interface_url }}/materials-designer/sidebar-items/). It contains the combined benzene-gold surface crystallographic structure as a single material entity. !!!tip "Toggling of Orthographic Camera" - The user is recommended to toggle the use of the [Orthographic camera](../../materials-designer/3d-editor/view.md#toggle-orthographic-camera) functionality, accessible via the [3D Editor interface](../../materials-designer/3d-editor.md) of Materials Designer, in order to verify the correct alignment and centrality of the benzene molecule over the surface. + Toggling the [Orthographic camera]({{ interface_url }}/materials-designer/3d-editor/view/#toggle-orthographic-camera) via the [3D Editor]({{ interface_url }}/materials-designer/3d-editor/) helps verify the correct alignment and centrality of the benzene molecule over the surface. + +This new entry should be [renamed]({{ interface_url }}/materials-designer/sidebar-items/#edit-name-of-item) to a more memorable form and [saved]({{ interface_url }}/materials-designer/header-menu/input-output/save/) into the account-owned materials [collection]({{ reference_url }}/accounts/collections/). -This new entry should first be [renamed](../../materials-designer/sidebar-items.md#edit-name-of-item) to a more memorable form, and should finally be [saved](../../materials-designer/header-menu/input-output/save.md) via the ["Input/Output" Menu](../../materials-designer/header-menu/input-output.md) located at the top-left corner into the account-owned materials [collection](../../accounts/collections.md), as a new material structure entry which is distinct from both the original isolated benzene molecule and gold structure. -## Resulting Material +## 9. View the resulting material An animation of the final combined benzene molecule-gold surface structure can be viewed below. -## Run Further Analysis -The user is now free to use the newly generated benzene-gold surface system, in order to perform its further analysis, such as studying the adsorption energy. +## 10. Run further analysis -The [Nudged Elastic Band (NEB)](../../models/auxiliary-concepts/nudged-elastic-band.md) method can be used for reaction energy profile calculations. We offer two alternative approaches for implementing the NEB method on our platform, based on the use of the [VASP](../../software-directory/modeling/vasp/overview.md) or [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md) modeling engines, which are narrated in two separate tutorials accessible [here](../dft/chemical/reaction-profile-vasp.md) and [here](../dft/chemical/reaction-profile-qe.md) respectively. +The newly generated benzene-gold surface system can be used for further analysis, such as studying the adsorption energy. -## Animation +The [Nudged Elastic Band (NEB)]({{ reference_url }}/models/auxiliary-concepts/nudged-elastic-band/) method can be used for reaction energy profile calculations. Two alternative approaches for implementing NEB are available, based on [VASP](../dft/chemical/reaction-profile-vasp.md) and [Quantum ESPRESSO](../dft/chemical/reaction-profile-qe.md) respectively. -We demonstrate the above-mentioned steps which lead to the creation of a combined benzene molecule/gold surface crystallographic system, made possible via the functionalities of the [Materials Designer Interface](../../materials-designer/overview.md) of our platform, in the following animation. -In this example, we consider a 3x3x3 slab supercell of the primitive unit cell of gold as a surface approximation (larger supercell dimensions should be envisaged for a more realistic surface representation). We also place the benzene molecule over the gold surface such that the molecule-surface distance is approximately 3.6 Angstroms, as measured by the difference in the z coordinates of the positions of the benzene atoms and gold surface atoms. +## 11. Video walkthrough + +The animation below demonstrates the creation of a combined benzene molecule/gold surface crystallographic system using the [Materials Designer Interface]({{ interface_url }}/materials-designer/overview/). + +In this example, a 3×3×3 slab supercell of the primitive unit cell of gold is used as a surface approximation (larger supercell dimensions should be used for a more realistic surface representation). The benzene molecule is placed over the gold surface at a molecule-surface distance of approximately 3.6 Å, as measured by the difference in z coordinates of the benzene and gold surface atoms.
-## Links -[^1]: [Wikipedia Adsorption, Website](https://en.wikipedia.org/wiki/Adsorption) +## 12. Links + +[^1]: [Wikipedia Adsorption](https://en.wikipedia.org/wiki/Adsorption) -[^2]: [Pubchem Benzene Datasheet, Official Website](https://pubchem.ncbi.nlm.nih.gov/compound/241) +[^2]: [Pubchem Benzene Datasheet](https://pubchem.ncbi.nlm.nih.gov/compound/241) -[^3]: [OpenBabel Web Interface, ChemInfo Website](http://www.cheminfo.org/Chemistry/Cheminformatics/FormatConverter/index.html) +[^3]: [OpenBabel Web Interface, ChemInfo](http://www.cheminfo.org/Chemistry/Cheminformatics/FormatConverter/index.html) diff --git a/lang/en/docs/tutorials/materials/overview.md b/lang/en/docs/tutorials/materials/overview.md index 1b90c8380..ef9eb9bc4 100644 --- a/lang/en/docs/tutorials/materials/overview.md +++ b/lang/en/docs/tutorials/materials/overview.md @@ -1,11 +1,11 @@ # Materials Operations Tutorials -In the present section, we introduce the most common operations supported on our platform for investigating and/or designing new [material structures](../../materials/overview.md). +In the present section, we introduce the most common operations supported on our platform for investigating and/or designing new [material structures]({{ reference_url }}/materials/overview/). ## [Create Materials With VESTA under Remote Desktop](vesta-remote-desktop.md) -We explain [in this tutorial](vesta-remote-desktop.md) how a new crystal structure can be designed with the help of the [VESTA](../../software-directory/analysis/vesta.md) graphical analysis and visualization software, implemented under our [Remote Desktop Interface](../../remote-connection/remote-desktop.md). We then illustrate also how the numerical information pertaining to such a crystal structure can later be transferred and retrieved in the main [Web Interface](../../ui/overview.md) of our platform. +We explain [in this tutorial](vesta-remote-desktop.md) how a new crystal structure can be designed with the help of the [VESTA]({{ reference_url }}/software-directory/analysis/vesta/) graphical analysis and visualization software, implemented under our [Remote Desktop Interface]({{ cli_url }}/remote-connection/remote-desktop/). We then illustrate also how the numerical information pertaining to such a crystal structure can later be transferred and retrieved in the main [Web Interface]({{ interface_url }}/ui/overview/) of our platform. ## [Generate Combinatorial Sets](combinatorial-screening.md) -In [this other tutorial](combinatorial-screening.md), we outline an example use of [combinatorial sets](../../materials-designer/header-menu/advanced/combinatorial-set.md) functionality for generating combinations and permutations of n and p-type dopant atoms in the Gallium Phosphide (GaP) semiconducting material structure. +In [this other tutorial](combinatorial-screening.md), we outline an example use of [combinatorial sets]({{ interface_url }}/materials-designer/header-menu/advanced/combinatorial-set/) functionality for generating combinations and permutations of n and p-type dopant atoms in the Gallium Phosphide (GaP) semiconducting material structure. diff --git a/lang/en/docs/tutorials/materials/slabs-interface.md b/lang/en/docs/tutorials/materials/slabs-interface.md index 23afbcd06..f46fca731 100644 --- a/lang/en/docs/tutorials/materials/slabs-interface.md +++ b/lang/en/docs/tutorials/materials/slabs-interface.md @@ -1,68 +1,76 @@ # Create an Interface -In this tutorial, the user will learn about how the [Material Designer Interface](../../materials-designer/overview.md) of our platform can be used to create **two slabs**, and how to put them next to each other to create an **interface** [^1]. +This tutorial demonstrates how the [Material Designer Interface]({{ interface_url }}/materials-designer/overview/) can be used to create **two slabs** and combine them to form an **interface** [^1]. -We consider the example of a **semiconductor-metal interface**, which is commonly encountered in a broad variety of semiconducting devices, by considering the case of a slab of gold placed next to a slab of silicon. +The example system is a **semiconductor-metal interface** — a gold slab placed next to a silicon slab — commonly encountered in semiconducting devices. -## Open Materials Designer -We start with [opening](../../entities-general/actions/create.md) an instance of the [Materials Designer Interface](../../materials-designer/overview.md) for creating and designing new [Materials structures](../../materials/overview.md) on our platform. +## 1. Open Materials Designer -## Create Slabs +[Open]({{ interface_url }}/entities-general/actions/create/) an instance of the [Materials Designer Interface]({{ interface_url }}/materials-designer/overview/). -In order to create the gold and silicon slabs, the user should first [import](../../materials-designer/header-menu/input-output/import.md) sample crystalline structures of the two respective materials into the current Materials Designer session, from the account-owned [collection](../../accounts/collections.md) of materials. + +## 2. Create the slabs + +In order to create the gold and silicon slabs, first [import]({{ interface_url }}/materials-designer/header-menu/input-output/import/) sample crystalline structures of the two materials into the current Materials Designer session from the account-owned [collection]({{ reference_url }}/accounts/collections/). !!!info "Default Material" - Silicon may have been loaded by [default](../../materials/default.md) initially at the moment of the opening of Materials Designer. - -Once imported into Materials Designer, the gold and silicon crystals will appear as two distinct entry items within the list of structures shown on the [left-had items list sidebar](../../materials-designer/sidebar-items.md) of the Designer interface. + Silicon may have been loaded by [default]({{ reference_url }}/materials/default/) at the moment of opening Materials Designer. + +Once imported, the gold and silicon crystals appear as two distinct entries in the [left-hand sidebar]({{ interface_url }}/materials-designer/sidebar-items/). -The instructions contained [in this page](../../materials-designer/header-menu/advanced/surface-slab.md) should then be followed in order to create a slab for each material, both with normal vector oriented along the [211] axis so as to be parallel to each other, using our surface/slab creator in Materials Designer, starting from the original crystalline samples. +Follow the instructions [in this page]({{ interface_url }}/materials-designer/header-menu/advanced/surface-slab/) to create a slab for each material, both with normal vector oriented along the [211] axis so as to be parallel to each other. !!!warning "Straining needed" - It is important to slightly strain the gold slab away from its equilibrium lattice configuration, in order to ensure a better matching between the two crystal structures across the interface. + It is important to slightly strain the gold slab away from its equilibrium lattice configuration in order to ensure a better matching between the two crystal structures across the interface. + + +## 3. Open the Multi-Materials 3D Editor -## Open Multi-Materials 3D Editor +After both slabs have been created as separate structural items, open the [Multi-Materials 3D Editor]({{ interface_url }}/materials-designer/3d-editor/edit/) via the [View Menu]({{ interface_url }}/materials-designer/header-menu/view/#multi-material-3d-editor). -After both the silicon and the gold slabs have been created as two separate structural items in the current session of Materials Designer, the user should now open an instance of the [Multi-Materials 3D Editor](../../materials-designer/3d-editor/edit.md) via the ["View" Menu](../../materials-designer/header-menu/view.md#multi-material-3d-editor), located within the [header bar](../../materials-designer/header-menu/header-menu-intro.md) of the Materials Deigner Interface. -## Combine the Two Materials +## 4. Combine the two materials -The Multi-Materials 3D Editor allows the two materials under investigation, gold and silicon, to be **combined** together into a new unified materials entity, separated by a small distance across an **interface** boundary. +The Multi-Materials 3D Editor allows the two materials to be **combined** into a new unified entity separated by a small distance across an **interface** boundary. -Care should be taken by the user to place the two slabs on top of each other in as "symmetrical" a way as possible, for example by positioning the center of the gold slab on the central portion of the other silicon slab. Relocation of each slab's position can be done by following the instructions contained [in this page](../../materials-designer/3d-editor/editor-actions/move-rotate-atoms.md), after selecting the slab's atom components under the ["Scene" sidebar list](../../materials-designer/3d-editor/edit.md#3.-scene) of the 3D Editor interface. +The two slabs should be placed on top of each other as symmetrically as possible. Relocation of each slab can be done following the instructions [in this page]({{ interface_url }}/materials-designer/3d-editor/editor-actions/move-rotate-atoms/), after selecting the slab's atom components under the [Scene sidebar list]({{ interface_url }}/materials-designer/3d-editor/edit/#3.-scene). -Since in this example the planes of the two slabs are already parallel to each other, a simple [translation](../../materials-designer/3d-editor/editor-actions/move-rotate-atoms.md#translation) of the gold atoms on top of the silicon slab should suffice. +Since in this example the planes of the two slabs are already parallel, a [translation]({{ interface_url }}/materials-designer/3d-editor/editor-actions/move-rotate-atoms/#translation) of the gold atoms on top of the silicon slab is sufficient. -## Exit Multi-Materials 3D Editor -After the correct desired positioning of the gold slab on top of the silicon slab, the user should now [exit](../../materials-designer/3d-editor/edit.md#exit-the-editor) the Multi-Materials 3D Editor, and return to the original Materials Designer interface. +## 5. Exit the Multi-Materials 3D Editor -The user will notice that a new material entry, called "New Material" by default, has now been created automatically and is listed within the [left-had items list sidebar](../../materials-designer/sidebar-items.md) of the Materials Designer interface. It contains the combined gold-silicon interface crystallographic structure, as a new single material entity. +After correct positioning, [exit]({{ interface_url }}/materials-designer/3d-editor/edit/#exit-the-editor) the Multi-Materials 3D Editor. + +A new material entry, called "New Material" by default, is created and listed in the [left-hand sidebar]({{ interface_url }}/materials-designer/sidebar-items/). It contains the combined gold-silicon interface crystallographic structure as a single material entity. !!!tip "Toggling of Orthographic Camera" - The user is recommended to toggle the use of the [Orthographic camera](../../materials-designer/3d-editor/view.md#toggle-orthographic-camera) functionality, accessible via the [3D Editor interface](../../materials-designer/3d-editor.md) of Materials Designer, in order to verify the correct alignment and centrality of the gold slab over the other slab made of silicon. + Toggling the [Orthographic camera]({{ interface_url }}/materials-designer/3d-editor/view/#toggle-orthographic-camera) via the [3D Editor]({{ interface_url }}/materials-designer/3d-editor/) helps verify the correct alignment and centrality of the gold slab over the silicon slab. + +This new entry should be [renamed]({{ interface_url }}/materials-designer/sidebar-items/#edit-name-of-item) and [saved]({{ interface_url }}/materials-designer/header-menu/input-output/save/) into the account-owned materials [collection]({{ reference_url }}/accounts/collections/). -This new entry should first be [renamed](../../materials-designer/sidebar-items.md#edit-name-of-item) to a more memorable form, and should finally be [saved](../../materials-designer/header-menu/input-output/save.md) via the ["Input/Output" Menu](../../materials-designer/header-menu/input-output.md) located at the top-left corner into the account-owned materials [collection](../../accounts/collections.md), as a new material structure entry which is distinct from both the original isolated gold and silicon structures. -## Resulting Material +## 6. View the resulting material An animation of the final combined gold-silicon interface structure can be viewed below. -## Animation -We demonstrate the above-mentioned steps which lead to the creation of a combined gold-silicon interface crystallographic system, made possible via the functionalities of the [Materials Designer Interface](../../materials-designer/overview.md) of our platform, in the following animation. +## 7. Video walkthrough -In this example, we consider a 3x3 supercell of the primitive unit cell of gold along the x-y basal plane as an approximate slab (larger supercell dimensions should be envisaged for a more realistic surface representation). For the case of silicon on the other hand, we limit the x-y supercell size of the slab to 2x2, due to the larger dimensions of the silicon unit cell compared to gold. This ensures that the two slabs are of approximately similar sizes across their interface on the x-y plane, for their easier superposition. For the case of both slabs, we define their vertical thickness to be composed of 6 layers. +The animation below demonstrates the creation of a combined gold-silicon interface crystallographic system using [Materials Designer]({{ interface_url }}/materials-designer/overview/). -We finally place the gold over the silicon slab such that the interface distance separating the two slabs along the vertical dimension is of approximately 2 Angstroms, as measured by the difference in the z coordinates of the positions of the gold and silicon interface atoms. Care needs to be taken to ensure that such separating distance applies also across the vertical periodic boundary condition of the system. +In this example, a 3×3 supercell of the primitive unit cell of gold along the x-y basal plane is used as an approximate slab. For silicon, the x-y supercell size is limited to 2×2 due to the larger silicon unit cell, ensuring the two slabs are of approximately similar sizes across their interface. For both slabs, the vertical thickness is set to 6 layers. + +The gold slab is placed over the silicon slab such that the interface distance separating the two slabs along the vertical dimension is approximately 2 Å, as measured by the difference in z coordinates of the gold and silicon interface atoms. Care is taken to ensure that this separating distance also applies across the vertical periodic boundary condition.
-## Links -[^1]: [Wikipedia Grain boundary, Website](https://en.wikipedia.org/wiki/Grain_boundary) +## 8. Links + +[^1]: [Wikipedia Grain boundary](https://en.wikipedia.org/wiki/Grain_boundary) diff --git a/lang/en/docs/tutorials/materials/specific/defect-planar-grain-boundary-2d-boron-nitride.md b/lang/en/docs/tutorials/materials/specific/defect-planar-grain-boundary-2d-boron-nitride.md index 80eca1687..2f75abba3 100644 --- a/lang/en/docs/tutorials/materials/specific/defect-planar-grain-boundary-2d-boron-nitride.md +++ b/lang/en/docs/tutorials/materials/specific/defect-planar-grain-boundary-2d-boron-nitride.md @@ -6,6 +6,7 @@ tags: - interface - twist-angle - atom-restoration + - D-2D-GBP hide: - tags @@ -15,7 +16,7 @@ render_macros: true # 2D Grain Boundaries in Hexagonal Boron Nitride. -## Introduction. +## 1. Introduction This tutorial demonstrates the process of creating 2D grain boundary structures in hexagonal boron nitride (h-BN), based on the work presented in the following manuscript: @@ -26,11 +27,11 @@ We will focus on creating h-BN grain boundary structures similar to Figure 2c fr ![h-BN Grain Boundary](../../../images/tutorials/materials/defects/defect_planar_grain_boundary_2d_boron_nitride/0-figure-from-manuscript.webp "h-BN Grain Boundary, FIG. 2c.") -## 1. Create Initial h-BN Structure. +## 2. Create Initial h-BN Structure -### 1.1. Load h-BN Material. +### 2.1. Load h-BN Material -Navigate to [Materials Designer](../../../materials-designer/overview.md) and import the h-BN material from the [Standata](../../../materials-designer/header-menu/input-output/standata-import.md). +Navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and import the h-BN material from the [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/). 1. Click on "Input/Output" menu 2. Select "Import from Standata" @@ -39,11 +40,11 @@ Navigate to [Materials Designer](../../../materials-designer/overview.md) and im ![Standata h-BN Import](../../../images/tutorials/materials/interfaces/twisted-bilayer-boron-nitride/standata-import-bn.png "Standata h-BN Import") -### 1.2. Launch JupyterLite Session. +### 2.2. Launch JupyterLite Session -Select "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" to open JupyterLite. +Select "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" to open JupyterLite. -### 1.3. Open and Configure Notebook. +### 2.3. Open and Configure Notebook Find and open `create_grain_boundary_film.ipynb`. Edit the grain boundary parameters in section 1.1: @@ -54,21 +55,33 @@ Find and open `create_grain_boundary_film.ipynb`. Edit the grain boundary parame `EDGE_INCLUSION_TOLERANCE = 0.0` -- Edge inclusion parameter, in Angstroms. Controls the overlap of the second phase onto the first phase. ```python +# Material selection +MATERIAL_INDEX = 0 # Index in the list of materials + # Grain boundary parameters TARGET_TWIST_ANGLE = 9.0 # in degrees -BOUNDARY_GAP = 0.0 # Gap between orientations in X direction -XY_SUPERCELL_MATRIX = [[1, 0], [0, 2]] +BOUNDARY_GAP = 0.0 # Gap between two orientations in X direction, in Angstroms +XY_SUPERCELL_MATRIX = [[1, 0], [0, 2]] # Supercell matrix to be applied to each of the orientations before matching +MILLER_INDICES = (0, 0, 1) # Miller indices for the supercell matching +VACUUM = 10.0 # Vacuum thickness in Angstroms, added to the top and bottom of the grain boundary # Search algorithm parameters -MAX_REPETITION = None +MAX_REPETITION = None # Maximum supercell matrix element value ANGLE_TOLERANCE = 0.5 # in degrees -RETURN_FIRST_MATCH = True +RETURN_FIRST_MATCH = True # If True, returns first solution within tolerance -# Distance tolerance for atom merging +# Distance tolerance for two atoms to be considered too close. +# Used when merging two orientations to remove the atoms of the first one. +# Should be less than the expected bond length DISTANCE_TOLERANCE = 1.43 # in Angstroms -# Edge inclusion parameter +# How much to expand inclusion of the edge atoms for both orientations and fill in the gap region. +# A fine-tuning parameter EDGE_INCLUSION_TOLERANCE = 0.0 # in Angstroms + +# Visualization parameters +SHOW_INTERMEDIATE_STEPS = True +CELL_REPETITIONS_FOR_VISUALIZATION = [3, 3, 1] ``` ![Notebook Setup](../../../images/tutorials/materials/defects/defect_planar_grain_boundary_2d_boron_nitride/2-jl-setup-nb-gb.webp "Notebook Setup") @@ -76,7 +89,7 @@ EDGE_INCLUSION_TOLERANCE = 0.0 # in Angstroms !!!note "Important Parameter" The `DISTANCE_TOLERANCE` parameter (1.43 Å) is larger than B-N distances at the one specific spot in the boundary. This will cause certain nitrogen atoms to be removed during structure generation, which we'll need to restore later. -## 2. Run the Notebook. +## 3. Run the Notebook Run the notebook by selecting "Run" > "Run All Cells". @@ -84,59 +97,54 @@ The notebook will generate the h-BN grain boundary structure based on the parame ![Initial h-BN Structure](../../../images/tutorials/materials/defects/defect_planar_grain_boundary_2d_boron_nitride/4-wave-result-gb.webp "Initial h-BN Structure") -## 3. Restore Missing Nitrogen Atom. +## 4. Restore Missing Nitrogen Atom Due to the `DISTANCE_TOLERANCE` setting, one nitrogen atom at the boundary is removed. We need to restore it: -### 3.1. Add Missing Nitrogen. +### 4.1. Add Missing Nitrogen Open JupyterLite Session and find `create_point_defect.ipynb` notebook. Select the h-BN grain boundary structure as input material and configure the adatom defect parameters in the "1.1. Set Notebook Parameters" section: ```python -DEFECT_TYPE = "interstitial" # (e.g. "vacancy", "substitution", "interstitial") -SITE_ID = None # Site index of the defect -COORDINATE = [0.5, 0.45, 0.5] # Position of the defect in crystal coordinates -APPROXIMATE_COORDINATE = None # Approximate coordinates of the defect in crystal coordinates -CHEMICAL_ELEMENT = "N" # Element to be placed at the site (ignored for vacancy) - +# Selected material will be used as a unit cell to create a supercell first. SUPERCELL_MATRIX = [[1, 0, 0], [0, 1, 0], [0, 0, 1]] -# List of dictionaries with defect parameters DEFECT_CONFIGS = [ { - "defect_type": DEFECT_TYPE, - "coordinate": COORDINATE, - "chemical_element": CHEMICAL_ELEMENT, - } + "type": "interstitial", + "coordinate": [0.5, 0.45, 0.5], # Crystal coordinates + "element": "N", + "placement_method": "closest_site", + }, ] ``` ![Notebook Setup](../../../images/tutorials/materials/defects/defect_planar_grain_boundary_2d_boron_nitride/5-jl-setup-nb-final-gb.webp "Notebook Setup") -### 3.2. Run the Notebook. +### 4.2. Run the Notebook Run the notebook to add the missing nitrogen atom to the h-BN grain boundary structure. ![Final Structure Preview](../../../images/tutorials/materials/defects/defect_planar_grain_boundary_2d_boron_nitride/6-jl-result-preview-final-gb.webp "Final Structure Preview") -## 4. Pass Final Material to Materials Designer. +## 5. Pass Final Material to Materials Designer The user can pass the material with substitution defects in the current Materials Designer environment and save it. ![Final Material](../../../images/tutorials/materials/defects/defect_planar_grain_boundary_2d_boron_nitride/7-wave-result-final-gb.webp "Final Material") -Or the user can [save or download](../../../materials-designer/header-menu/input-output.md) the material in Material JSON format or POSCAR format. +Or the user can [save or download]({{ interface_url }}/materials-designer/header-menu/input-output/) the material in Material JSON format or POSCAR format. -## 5. Manual Adjustment. +## 6. Manual Adjustment To fill the gaps between two phases edge atoms can be adjusted manually in Materials Designer 3D editor. The resulting structure should be similar to the one shown in the manuscript. ![Adjusted Structure](../../../images/tutorials/materials/defects/defect_planar_grain_boundary_2d_boron_nitride/8-wave-result-final-gb-relaxed.webp "Adjusted Structure") -## Interactive JupyterLite Notebook. +## 7. Interactive JupyterLite Notebook The following JupyterLite notebook demonstrates the complete process. Select "Run" > "Run All Cells". @@ -148,4 +156,4 @@ The following JupyterLite notebook demonstrates the complete process. Select "Ru {% endwith %} {% endwith %} -## References. +## 8. References diff --git a/lang/en/docs/tutorials/materials/specific/defect-planar-grain-boundary-3d-fcc-metals-copper.md b/lang/en/docs/tutorials/materials/specific/defect-planar-grain-boundary-3d-fcc-metals-copper.md index 4e22d533a..0e0231784 100644 --- a/lang/en/docs/tutorials/materials/specific/defect-planar-grain-boundary-3d-fcc-metals-copper.md +++ b/lang/en/docs/tutorials/materials/specific/defect-planar-grain-boundary-3d-fcc-metals-copper.md @@ -6,6 +6,7 @@ tags: - Cu - FCC - metal + - D-1D-GBL hide: - tags @@ -15,7 +16,7 @@ render_macros: true # Grain Boundaries in FCC Metals (Copper). -## Introduction. +## 1. Introduction This tutorial demonstrates the process of creating grain boundary structures in FCC metals, specifically copper, based on the work presented in the following manuscript, where structural phase transformations in metallic grain boundaries are studied. @@ -27,11 +28,11 @@ We will focus on creating copper grain boundary structures similar to Figure 1b ![Copper Grain Boundary](../../../images/tutorials/materials/defects/defect_planar_grain_boundary_3d_fcc_metal/0-figure-from-manuscript.webp "Copper Grain Boundary, FIG. 1") -## 1. Create Initial Copper Structure. +## 2. Create Initial Copper Structure -### 1.1. Load Copper Material. +### 2.1. Load Copper Material -Navigate to [Materials Designer](../../../materials-designer/overview.md) and import the copper material from the [Standata](../../../materials-designer/header-menu/input-output/standata-import.md). +Navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and import the copper material from the [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/). 1. Click on "Input/Output" menu 2. Select "Import from Standata" @@ -39,13 +40,13 @@ Navigate to [Materials Designer](../../../materials-designer/overview.md) and im ![Copper Material Import](../../../images/tutorials/materials/defects/defect_planar_grain_boundary_3d_fcc_metal/1-standata-import-cu.webp "Copper Material Import") -### 1.2. Launch JupyterLite Session. +### 2.2. Launch JupyterLite Session -Select "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" to open JupyterLite. +Select "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" to open JupyterLite. ![JupyterLite Dialog](../../../images/jupyterlite/md-advanced-jl.webp "JupyterLite Dialog") -### 1.3. Open and Configure Notebook. +### 2.3. Open and Configure Notebook Find and open `create_grain_boundary.ipynb`. Edit the grain boundary parameters in section 1.1 of the notebook: @@ -89,16 +90,16 @@ These parameters will create: ![Grain Boundary Parameters](../../../images/tutorials/materials/defects/defect_planar_grain_boundary_3d_fcc_metal/2-jl-setup-nb.webp "Grain Boundary Parameters") -## 2. Run the Notebook. +## 3. Run the Notebook After setting the parameters, run the notebook by selecting "Run > Run All Cells" from the menu. ![Run All](../../../images/jupyterlite/run-all.webp "Run All") -## 3. Analyze the Results. +## 4. Analyze the Results -### 3.1. Review the Structure. +### 4.1. Review the Structure After running the notebook, user can visualize the grain boundary structure: @@ -108,7 +109,7 @@ After running the notebook, user can visualize the grain boundary structure: ![Grain Boundary Preview](../../../images/tutorials/materials/defects/defect_planar_grain_boundary_3d_fcc_metal/3-jl-result-preview.webp "Grain Boundary Preview") -### 3.2. Structure Details. +### 4.2. Structure Details The resulting structure should show: @@ -124,15 +125,15 @@ Grain boundary from the top (XY) and side (XZ) views: The structure has differences from the original figure in the manuscript, since grain boundary achieved by strain-matching two symmetrical surfaces with no changes to either surfaces. Discrepancies might be removed with further adjustments like shifting the phases, removing atom layers and reconstructing the interface. -## 4. Save the Structure. +## 5. Save the Structure The final structure can be: 1. Passed back to Materials Designer -2. [Saved or downloaded](../../../materials-designer/header-menu/input-output.md) in Material JSON format +2. [Saved or downloaded]({{ interface_url }}/materials-designer/header-menu/input-output/) in Material JSON format 3. Exported as a POSCAR file -## Interactive JupyterLite Notebook. +## 6. Interactive JupyterLite Notebook The following JupyterLite notebook demonstrates the complete process. Select "Run" > "Run All Cells". @@ -144,4 +145,4 @@ The following JupyterLite notebook demonstrates the complete process. Select "Ru {% endwith %} {% endwith %} -## References. +## 7. References diff --git a/lang/en/docs/tutorials/materials/specific/defect-point-adatom-island-molybdenum-disulfide-platinum.md b/lang/en/docs/tutorials/materials/specific/defect-point-adatom-island-molybdenum-disulfide-platinum.md index 0d0050560..ed96bb354 100644 --- a/lang/en/docs/tutorials/materials/specific/defect-point-adatom-island-molybdenum-disulfide-platinum.md +++ b/lang/en/docs/tutorials/materials/specific/defect-point-adatom-island-molybdenum-disulfide-platinum.md @@ -9,6 +9,7 @@ tags: - Mo - S - Pt + - D-2D-ISL hide: - tags @@ -18,7 +19,7 @@ render_macros: true # Pt Nanoparticles on MoS2(001) Surface via Adatoms. -## Introduction. +## 1. Introduction This tutorial demonstrates how to create a platinum island on MoS2 by sequentially adding Pt adatoms, following the methodology described in the literature. @@ -32,68 +33,69 @@ We will recreate the Pt island structure shown in Figure 4b: ![Pt Island on MoS2](../../../images/tutorials/materials/defects/defect_point_adatom_island_molybdenum_disulfide_platinum/0-figure-from-manuscript.webp "Pt island formation on MoS2") -## 1. Create MoS2 Substrate. +## 2. Create MoS2 Substrate -### 1.1. Load Base Material. +### 2.1. Load Base Material -Navigate to [Materials Designer](../../../materials-designer/overview.md) and import the MoS2 2D material from [Standata](../../../materials-designer/header-menu/input-output/standata-import.md). +Navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and import the MoS2 2D material from [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/). -### 1.2. Launch JupyterLite Session. +### 2.2. Launch JupyterLite Session -Select the "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" menu item to launch the JupyterLite environment. +Select the "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" menu item to launch the JupyterLite environment. -### 1.3. Open `create_adatom_defect.ipynb` Notebook. +### 2.3. Open `create_adatom_defect.ipynb` Notebook Find and open the `create_adatom_defect.ipynb` notebook. Select MoS2 as input material. -## 2. Configure and Create Structure. +## 3. Configure and Create Structure -### 2.1. Set Parameters. +### 3.1. Set Parameters Set up the slab and defect parameters in the notebook: ```python -# Slab parameters -MILLER_INDICES = (0, 0, 1) # MoS2 basal plane -SLAB_THICKNESS = 1 # Single layer -VACUUM = 10.0 # in Angstrom -SUPERCELL_MATRIX = [[3, 0, 0], [0, 3, 0], [0, 0, 1]] # 3x3 supercell +# Index in the list of materials, to access as materials[MATERIAL_INDEX] +MATERIAL_INDEX = 0 +ELEMENT = "Pt" # Chemical element of the adatom -# Defect configurations for all Pt atoms +# Dictionaries are validated and converted to AdatomDefectDict objects below DEFECT_CONFIGS = [ { - "defect_type": "adatom", - "placement_method": "coordinate", - "chemical_element": "Pt", - "position_on_surface": [5/9, 4/9], # First Pt: atop central Mo - "distance_z": 1.2, # Distance from surface S atoms - "use_cartesian_coordinates": False + "type": "adatom", + "coordinate_2d": [5/9, 4/9], # Crystal coordinates on the surface (x, y) + "distance_z": 1.2, # Method to place the adatom + "element": ELEMENT, }, { - "defect_type": "adatom", - "placement_method": "coordinate", - "chemical_element": "Pt", - "position_on_surface": [2/9, 4/9], # Second Pt: next clockwise atop Mo - "distance_z": 1.2, # Distance from surface S atoms - "use_cartesian_coordinates": False + "type": "adatom", + "coordinate_2d": [2/9, 4/9], # Crystal coordinates on the surface (x, y) + "distance_z": 1.2, # Method to place the adatom + "element": ELEMENT, }, { - "defect_type": "adatom", - "placement_method": "coordinate", - "chemical_element": "Pt", - "position_on_surface": [5/9, 7/9], # Third Pt: next clockwise atop Mo - "distance_z": 1.2, # Distance from surface S atoms - "use_cartesian_coordinates": False + "type": "adatom", + "coordinate_2d": [5/9, 7/9], # Crystal coordinates on the surface (x, y) + "distance_z": 1.2, # Method to place the adatom + "element": ELEMENT, }, { - "defect_type": "adatom", - "placement_method": "coordinate", - "chemical_element": "Pt", - "position_on_surface": [4/9, 5/9], # Fourth Pt: centered atop S - "distance_z": 1.6, # Distance between Pt atom layers, in Angstrom - "use_cartesian_coordinates": False - } + "type": "adatom", + "coordinate_2d": [4/9, 5/9], # Crystal coordinates on the surface (x, y) + "distance_z": 1.6, # Method to place the adatom + "element": ELEMENT, + }, ] + + +PLACEMENT_METHOD = "new_crystal_site" # Method to place the adatom, e.g., "new_crystal_site", "exact_coordinate", "equidistant" + + +# Slab parameters +MILLER_INDICES = (0, 0, 1) # Miller indices of the surface +SLAB_THICKNESS = 1 # Thickness of the slab in unit cells +VACUUM = 10.0 # Vacuum thickness in Angstrom +XY_SUPERCELL_MATRIX = [[3, 0], [0, 3]] # Supercell matrix for the slab +TERMINATION_FORMULA = None # Stoichiometric formula of the slab termination to be used. ``` Key parameters explained: @@ -111,13 +113,13 @@ Key parameters explained: ![Adatoms Setup](../../../images/tutorials/materials/defects/defect_point_adatom_island_molybdenum_disulfide_platinum/1-jl-setup-nb.webp "Pt adatoms setup") -### 2.2. Run the Notebook. +### 3.2. Run the Notebook Execute the notebook to create the Pt island structure on MoS2 by selecting "Run" > "Run All Cells" from the JupyterLite menu. ![Results Preview](../../../images/tutorials/materials/defects/defect_point_adatom_island_molybdenum_disulfide_platinum/2-jl-result-preview.webp "Pt island results preview") -### 2.3. Pass the Result to Materials Designer. +### 3.3. Pass the Result to Materials Designer The result can be passed to Materials Designer for visualization and viewed from the top: @@ -127,24 +129,24 @@ And from the side: ![Complete Island, side view](../../../images/tutorials/materials/defects/defect_point_adatom_island_molybdenum_disulfide_platinum/5-wave-result-side.webp "Complete Pt island structure, side view") -## 3. Analyze the Structure. +## 4. Analyze the Structure After adding all Pt atoms, verify the following: -### 3.1. Base Layer Geometry. +### 4.1. Base Layer Geometry - Three Pt atoms should form a triangular base - Each base Pt should be positioned atop Mo atoms - Distance from surface S atoms should be ~1.2 Å - Relaxation is needed to achieve the exact geometry from the publication, can be performed elsewhere -### 3.2. Top Atom Position. +### 4.2. Top Atom Position - Fourth Pt should be centered above the triangle - Position should be approximately above a surface S atom - Height should be ~2.8 Å from surface (1.6 Å from base Pt atoms) -## 4. Save the Structure. +## 5. Save the Structure The final structure will be automatically passed back to Materials Designer where user can: @@ -152,7 +154,7 @@ The final structure will be automatically passed back to Materials Designer wher 2. Export it in various formats 3. Use it for further transformations -## Interactive JupyterLite Notebook. +## 6. Interactive JupyterLite Notebook The following embedded notebook demonstrates the complete process. Select "Run" > "Run All Cells". @@ -164,7 +166,7 @@ The following embedded notebook demonstrates the complete process. Select "Run" {% endwith %} {% endwith %} -## Parameter Fine-tuning. +## 7. Parameter Fine-tuning To adjust the island structure: @@ -176,5 +178,5 @@ To adjust the island structure: - Adjust position to change island shape - Modify height to change Pt-Pt spacing -## References. +## 8. References diff --git a/lang/en/docs/tutorials/materials/specific/defect-point-interstitial-tin-oxide.md b/lang/en/docs/tutorials/materials/specific/defect-point-interstitial-tin-oxide.md index 28aad98fc..d44f3c579 100644 --- a/lang/en/docs/tutorials/materials/specific/defect-point-interstitial-tin-oxide.md +++ b/lang/en/docs/tutorials/materials/specific/defect-point-interstitial-tin-oxide.md @@ -8,6 +8,7 @@ tags: - point defects - Sn - O + - D-0D-INT hide: - tags @@ -17,7 +18,7 @@ render_macros: true # Oxygen interstitial Defect(s) in SnO. -## Introduction. +## 1. Introduction This tutorial demonstrates how to create an oxygen interstitial defect in tin monoxide (SnO), following the methodology described in the literature. @@ -27,50 +28,48 @@ This tutorial demonstrates how to create an oxygen interstitial defect in tin mo Physical Review B 74, 195128 (2006) [DOI: 10.1103/PhysRevB.74.195128](https://doi.org/10.1103/PhysRevB.74.195128){:target='_blank'}. [@Togo2006; @Wang2014; @Na-Phattalung2006] -We will recreate the O-interstitial defect structure shown in Fig. 4 a) using [Voronoi](https://github.com/Exabyte-io/made/blob/9e13b350eaaa5d49c81a3b30f76c165480825d72/src/py/mat3ra/made/tools/build/defect/builders.py#L125) placement method. +We will recreate the O-interstitial defect structure shown in Fig. 4 a) using [Voronoi](https://github.com/mat3ra/made/blob/9e13b350eaaa5d49c81a3b30f76c165480825d72/src/py/mat3ra/made/tools/build/defect/builders.py#L125) placement method. ![SnO O-interstitial](../../../images/tutorials/materials/defects/defect_point_interstitial_tin_oxide/0-figure-from-manuscript.webp "O-interstitial defect in SnO") -## 1. Prepare Base Structure. +## 2. Prepare Base Structure -### 1.1. Load Base Material. +### 2.1. Load Base Material -Navigate to [Materials Designer](../../../materials-designer/overview.md) and import the SnO material from [Standata](../../../materials-designer/header-menu/input-output/standata-import.md) using the search term "SnO". +Navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and import the SnO material from [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/) using the search term "SnO". ![Original SnO](../../../images/tutorials/materials/defects/defect_point_interstitial_tin_oxide/2-wave-original-material.webp "SnO from Standata, 2x2x2 repetitions") -### 1.2. Launch JupyterLite Session. +### 2.2. Launch JupyterLite Session -Select the "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" menu item to launch the JupyterLite environment. +Select the "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" menu item to launch the JupyterLite environment. -### 1.3. Open `create_defect.ipynb` Notebook. +### 2.3. Open `create_defect.ipynb` Notebook Find and open the `create_defect.ipynb` notebook. Select "SnO" input material. We'll modify its parameters to create the Sn-vacancy O-interstitial defects according to the image above. -### 1.4. Set Defect Parameters. +### 2.4. Set Defect Parameters Replace the default parameters in section 1.1 with: ```python -# Supercell parameters. +# Selected material will be used as a unit cell to create a supercell first. SUPERCELL_MATRIX = [[2, 0, 0], [0, 2, 0], [0, 0, 2]] -# Defect parameters. DEFECT_CONFIGS = [ { - "defect_type": "vacancy", - # Coordiante will be resolved to nearest atom. - "approximate_coordinate": [0.0, 0.25, 0.525], + "type": "vacancy", + "coordinate": [0.0, 0.25, 0.525], # Crystal coordinates + "placement_method": "closest_site", }, { - "defect_type": "interstitial", - # Coordiante will be resolved to nearest Voronoi site. - "coordinate": [0.0, 0.25, 0.35], - "chemical_element": "O", - "placement_method": "voronoi_site" - } + "type": "interstitial", + "coordinate": [0.0, 0.25, 0.35], # Crystal coordinates + "element": "O", + "placement_method": "voronoi_site", + }, ] ``` ![Defect Parameters](../../../images/tutorials/materials/defects/defect_point_interstitial_tin_oxide/3-jl-setup-nb.webp "Defect parameters for O-interstitial in SnO") @@ -89,9 +88,9 @@ Second defect: - `chemical_element`: "O" for oxygen interstitial - `placement_method`: "voronoi_site" to place atom at appropriate interstitial position -## 2. Create the Defect. +## 3. Create the Defect -### 2.1. Run Supercell Creation. +### 3.1. Run Supercell Creation Run the notebook by selecting "Run" > "Run All Cells". This will: @@ -99,25 +98,25 @@ Run the notebook by selecting "Run" > "Run All Cells". This will: 2. Create the O-interstitial at the specified position 3. Generate the final defect structure -## 3. Analyze Results. +## 4. Analyze Results After creating the defect, examine the structure to verify: ![SnO with O-interstitial defect](../../../images/tutorials/materials/defects/defect_point_interstitial_tin_oxide/4-wave-result-material.webp "SnO with O-interstitial defect") -### 3.1. Defect Position. +### 4.1. Defect Position - O interstitial should be at (0.0, 0.5, 0.5) in crystal coordinates - Position should be in a void space between Sn-O layers - Verify symmetry of surrounding atoms -### 3.2. Local Structure. +### 4.2. Local Structure - Check distances to nearest Sn and O atoms - Verify no unrealistic atom overlaps - Confirm overall crystal structure is maintained -## 4. Save Defect Structure. +## 5. Save Defect Structure The defect structure will be automatically passed back to Materials Designer where you can: @@ -125,7 +124,7 @@ The defect structure will be automatically passed back to Materials Designer whe 2. Export it in various formats 3. Use it for further calculations -## Interactive JupyterLite Notebook. +## 6. Interactive JupyterLite Notebook The following embedded notebook demonstrates the complete process. Select "Run" > "Run All Cells". @@ -138,7 +137,7 @@ The following embedded notebook demonstrates the complete process. Select "Run" {% endwith %} -## Parameter Fine-tuning. +## 7. Parameter Fine-tuning To adjust the defect creation: @@ -153,4 +152,4 @@ To adjust the defect creation: - Change `SUPERCELL_MATRIX` for larger/smaller systems - Consider periodic boundary conditions effects -## References. +## 8. References diff --git a/lang/en/docs/tutorials/materials/specific/defect-point-pair-gallium-nitride.md b/lang/en/docs/tutorials/materials/specific/defect-point-pair-gallium-nitride.md index 41818a692..c1e0215c5 100644 --- a/lang/en/docs/tutorials/materials/specific/defect-point-pair-gallium-nitride.md +++ b/lang/en/docs/tutorials/materials/specific/defect-point-pair-gallium-nitride.md @@ -10,6 +10,7 @@ tags: - nitrogen - GaN - gallium nitride + - D-0D-DFP hide: - tags @@ -19,7 +20,7 @@ render_macros: true # Nitrogen vacancy and Mg substitution in GaN. -## Introduction. +## 1. Introduction This tutorial demonstrates the process of creating material with nitrogen vacancies and magnesium substitution defects in GaN. @@ -29,7 +30,7 @@ This tutorial demonstrates the process of creating material with nitrogen vacanc "Self-compensation due to point defects in Mg-doped GaN", Physical Review B, 2016. [DOI: 10.1103/PhysRevB.93.165207](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.93.165207){:target='_blank'}. [@Miceli2016] -We use the [Materials Designer](../../../materials-designer/overview.md) to create a supercell of GaN, identify the crystal site positions for defects, and introduce nitrogen atoms and vacancies accordingly. +We use the [Materials Designer]({{ interface_url }}/materials-designer/overview/) to create a supercell of GaN, identify the crystal site positions for defects, and introduce nitrogen atoms and vacancies accordingly. We will focus on creating GaN-nitrogen structures from the publication. Specifically, the material from FIG. 2. c) of the manuscript: @@ -38,90 +39,100 @@ Specifically, the material from FIG. 2. c) of the manuscript: ![Point Pair Defects: Mg Substitution and Vacancy in GaN](../../../images/tutorials/materials/defects/defect_point_pair_gallium_nitride/0-figure-from-manuscript.webp "Point Defect Pair: Substitution, Vacancy in GaN, FIG. 2.") -## 1. Create GaN Supercell. +## 2. Create GaN Supercell -First, we navigate to [Materials Designer](../../../materials-designer/overview.md) and import the GaN material from the [Standata](../../../materials-designer/header-menu/input-output/standata-import.md). +First, we navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and import the GaN material from the [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/). ![Standata GaN Import](../../../images/tutorials/materials/defects/defect_point_pair_gallium_nitride/1-standata-GaN.webp "Standata GaN Import") -We then use the [Advanced](../../../materials-designer/header-menu/advanced/supercell.md) menu to create a supercell of GaN with a size of 4x4x1. +We then use the [Advanced]({{ interface_url }}/materials-designer/header-menu/advanced/supercell/) menu to create a supercell of GaN with a size of 4x4x1. ![Supercell Creation for GaN](../../../images/tutorials/materials/defects/defect_point_pair_gallium_nitride/2-advanced-supercell.webp "Supercell GaN") -## 2. Identify Defect Sites. +## 3. Identify Defect Sites -Next, we open the [3D editor](../../../materials-designer/3d-editor.md) to identify the crystal site positions for the defects. +Next, we can toggle the coordinates measurement in the editor to identify the crystal site positions for the defects. -![3D Editor](../../../images/tutorials/materials/defects/defect_point_pair_gallium_nitride/4-threejs-editor-coordinates.webp "3D Editor") +![Coordinates Measurement](../../../images/tutorials/materials/defects/defect_creation_point_substitution_graphene/4-toggle-measure-coordinates.webp "3D Editor Toggle Coordinates") + +Clicking on each atom will copy the coordinates of the atom to the clipboard as an array, which can then be pasted into the cell of the notebook and used to assign the defect coordinates. + +![3D Editor Coordinates](../../../images/tutorials/materials/defects/defect_point_pair_gallium_nitride/4-3d-editor-coordinates.webp "3D Editor Coordinates Copying") -Hover over the atoms to get the coordinates of the atoms to replace. Then copy/paste these coordinates into a text file for later use. `[1.608, 4.642, 5.240]` for the Mg substitution defect and `[1.608, 4.642, 7.210]` for the nitrogen vacancy. -## 3. Create Nitrogen Defects and Vacancies. +## 4. Create Nitrogen Defects and Vacancies -For the defect creation, we will use the [JupyterLite](../../../jupyterlite/overview.md) environment with the corresponding notebook. +For the defect creation, we will use the [JupyterLite]({{ interface_url }}/jupyterlite/overview/) environment with the corresponding notebook. -### 3.1. Launch JupyterLite Session. +### 4.1. Launch JupyterLite Session -Select the "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" menu item to launch the JupyterLite environment. +Select the "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" menu item to launch the JupyterLite environment. ![JupyterLite Dialog](../../../images/jupyterlite/md-advanced-jl.webp "JupyterLite Dialog") -### 3.2. Open `create_point_defect_pair.ipynb` notebook. +### 4.2. Open `create_point_defect_pair.ipynb` notebook Find `create_point_defect_pair.ipynb` in the list of notebooks and click/double-click open it. -### 3.3. Open and modify the notebook. +### 4.3. Open and modify the notebook -Next, edit `create_point_defect_pair.ipynb` notebook to modify the parameters by adding a list of [defect configuration objects](https://github.com/Exabyte-io/made/blob/3d938b4d91a31323dca7a02acb12b646dbb26634/src/py/mat3ra/made/tools/build/defect/configuration.py#L257) containing the approximate coordinates of the atoms to replace. +Next, edit `create_point_defect_pair.ipynb` notebook to modify the parameters by adding a list of [defect configuration objects](https://github.com/mat3ra/made/blob/3d938b4d91a31323dca7a02acb12b646dbb26634/src/py/mat3ra/made/tools/build/defect/configuration.py#L257) containing the approximate coordinates of the atoms to replace. Copy the below content and edit the "1.1. Set up defect parameters" cell in the notebook as follows: ```python +from types import SimpleNamespace + +# Selected material will be used as a unit cell to create a supercell first. SUPERCELL_MATRIX = [[1, 0, 0], [0, 1, 0], [0, 0, 1]] # List of dictionaries with defect parameters -PRIMARY_DEFECT_CONFIG = { - "defect_type": "substitution", - "approximate_coordinate": [1.608, 4.642, 5.240], - "chemical_element": "Mg", - "use_cartesian_coordinates": True, -} - -SECONDARY_DEFECT_CONFIG = { - "defect_type": "vacancy", - "approximate_coordinate": [1.608, 4.642, 7.210], - "use_cartesian_coordinates": True, -} +PRIMARY_DEFECT_CONFIG = SimpleNamespace( + defect_type="substitution", + coordinate=[1.608, 4.642, 5.240], # Approx. coord that will be resolved to the closest site + use_cartesian_coordinates=True, # Use cartesian or crystal coordinates + chemical_element="Mg", + # "site_id": 0, # Index of the atom in the host material + # "coordinate": None, # Exact position (override the approximate coordinate) +) + +SECONDARY_DEFECT_CONFIG = SimpleNamespace( + defect_type="vacancy", + approximate_coordinate=[1.608, 4.642, 7.210], # Approx. coord that will be resolved to the closest site + use_cartesian_coordinates=True, + # "site_id": 0, # Index of the atom in the host material + # "coordinate": None, # Exact position (override the approximate coordinate) +) ``` Here's the visual of the updated content: ![Notebook setup](../../../images/tutorials/materials/defects/defect_point_pair_gallium_nitride/5-jl-setup.webp "Notebook setup") -## 4. Run the Notebook. +## 5. Run the Notebook Run the notebook by clicking `Run` > `Run All` in the top menu to run cells and wait for the results to appear. ![Run All](../../../images/jupyterlite/run-all.webp "Run All") -## 5. Analyze the Results. +## 6. Analyze the Results After running the notebook, the user will be able to visualize the structure of GaN with substitution and vacancy defects. ![Review the Results](../../../images/tutorials/materials/defects/defect_point_pair_gallium_nitride/6-jl-result-preview.webp "Review the Results") -## 6. Pass the Material to Materials Designer. +## 7. Pass the Material to Materials Designer The user can pass the resulting material in the current Materials Designer environment and save it. ![Final Material](../../../images/tutorials/materials/defects/defect_point_pair_gallium_nitride/7-wave-result.webp "Vacancy and Mg Substitution in GaN") -Or the user can [save or download](../../../materials-designer/header-menu/input-output.md) the material in Material JSON format or POSCAR format. +Or the user can [save or download]({{ interface_url }}/materials-designer/header-menu/input-output/) the material in Material JSON format or POSCAR format. -## Interactive JupyterLite Notebook. +## 8. Interactive JupyterLite Notebook The following JupyterLite notebook demonstrates the process of creating materials with substitution defects in GaN. Select "Run" > "Run All Cells". @@ -133,4 +144,4 @@ The following JupyterLite notebook demonstrates the process of creating material {% endwith %} {% endwith %} -## References. +## 9. References diff --git a/lang/en/docs/tutorials/materials/specific/defect-point-substitution-graphene-simulation.md b/lang/en/docs/tutorials/materials/specific/defect-point-substitution-graphene-simulation.md new file mode 100644 index 000000000..08394da28 --- /dev/null +++ b/lang/en/docs/tutorials/materials/specific/defect-point-substitution-graphene-simulation.md @@ -0,0 +1,235 @@ +--- +tags: + - defects + - graphene + - substitutional + - point-defects + - nitrogen + - band-structure + - D-0D-SUB + +hide: + - tags +# YAML header +render_macros: true +--- + +# Substitutional Point Defects in Graphene (Band Structure) + +## 1. Introduction + +This tutorial demonstrates the calculation of the band structure for graphene with vacancy and N substitutions, reproducing results from the following manuscript: + +!!!note "Manuscript" + Yoshitaka Fujimoto and Susumu Saito, "Formation, stabilities, and electronic properties of nitrogen defects in graphene", Physical Review B, 2011. [DOI: 10.1103/PhysRevB.84.245446](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.84.245446){:target='_blank'}. [@Yoshitaka2011] + +This tutorial builds upon the [Substitutional Point Defects in Graphene](defect-point-substitution-graphene.md) tutorial, where the N-doped graphene structure is created. Here, the electronic band structure is calculated using Quantum ESPRESSO and compared with the published results. + +The figure below shows the band structure and atomic structure of N-doped graphene from the manuscript (Figure 3a): + +![Band Structure from Paper](../../../images/tutorials/materials/defects/defect_creation_point_substitution_graphene/band-structure-paper-figure.webp "Band structure and atomic structure of N-doped graphene from Fujimoto & Saito 2011, Figure 3a") + +The calculation uses Density Functional Theory (DFT) with the Local Density Approximation (LDA) and norm-conserving pseudopotentials, following the methodology described in the manuscript. + + +## 2. Prerequisites + +Before starting this tutorial, one of the following steps should be completed: + +1. Complete the [Substitutional Point Defects in Graphene](defect-point-substitution-graphene.md) tutorial to create the N-doped graphene structure, OR +2. Have the N-doped graphene material file saved in the `uploads` folder + + +## 3. Workflow overview + +The band structure calculation workflow consists of the following steps: + +1. **Set up the environment and parameters**: Configure material, workflow, and computational settings +2. **Authenticate and initialize API client**: Connect to the platform +3. **Load material**: Import the N-doped graphene structure from file or Standata +4. **Create workflow**: Set up the band structure calculation workflow with optional relaxation +5. **Configure compute resources**: Select cluster, queue, and processor settings +6. **Create and submit job**: Assemble and run the calculation +7. **Monitor job status**: Wait for completion +8. **Retrieve and visualize results**: Display the calculated band structure + + +## 4. Calculation parameters + +### 4.1. Run profiles + +The notebook supports two run profiles: + +- **Debug mode**: Quick validation run with minimal k-point sampling and no relaxation. Completes in a few minutes. +- **Production mode**: Paper-quality settings with structural relaxation and dense k-point sampling, following Fujimoto & Saito (2011). + +### 4.2. DFT parameters + +The calculation uses the following DFT parameters (consistent with the manuscript): + +- **Functional**: LDA (Perdew-Zunger parametrization) +- **Pseudopotentials**: Norm-conserving (ONCV) +- **Energy cutoff**: 50 Ry for wavefunctions, 200 Ry for density +- **K-point grid** (production): 6×6×1 for SCF and relaxation +- **K-path**: K → Γ → M → K (high-symmetry path in hexagonal Brillouin zone) + +### 4.3. Relaxation settings + +In production mode, the structure is relaxed before the band structure calculation to optimize atomic positions while maintaining the cell parameters. + + +## 5. Step-by-step instructions + +### 5.1. Open the notebook + +Navigate to the API examples repository and open the band structure calculation notebook: + +``` +other/materials_designer/specific_examples/defect_point_substitution_graphene_SIMULATION.ipynb +``` + +### 5.2. Configure parameters + +In cell 1.2, set the run profile and material parameters: + +```python +# Switch between "debug" and "production" modes +RUN_PROFILE = "debug" # Change to "production" for paper-quality results + +# Material parameters +FOLDER = "./uploads" +MATERIAL_NAME = "N-doped Graphene" + +# Workflow parameters +APPLICATION_NAME = "espresso" +MODEL_SUBTYPE = "lda" +``` + +For first-time use, start with `"debug"` mode to validate the workflow. Once confirmed working, switch to `"production"` for final results. + +### 5.3. Set DFT parameters + +The specific DFT parameters are configured in cell 1.3: + +```python +# Pseudopotential settings +PSEUDOPOTENTIAL_TYPE = "nc" +FUNCTIONAL = "pz" + +# Energy cutoffs +ECUTWFC = 50 +ECUTRHO = 4 * ECUTWFC + +# K-point sampling and path (automatically set based on RUN_PROFILE) +``` + +### 5.4. Run the notebook + +Execute all cells by selecting *Run* > *Run All* from the menu. + +The notebook will: + +1. [Authenticate with the platform]({{ interface_url }}/jupyterlite/authentication.md) and initialize the API client +2. Load the N-doped graphene material +3. Create and configure the band structure workflow +4. Submit the calculation job +5. Monitor the job status +6. Display the results when complete + +### 5.5. Monitor progress + +The notebook includes automatic job monitoring with status updates. In debug mode, the calculation typically completes in 5–10 minutes. Production mode may take several hours depending on the cluster load. + +### 5.6. Analyze results + +Once the job completes, the band structure is displayed. The plot shows: + +- Energy bands along the K → Γ → M → K path +- Fermi level position +- Band gap (if present) +- Comparison with pristine graphene (if available) + + +## 6. Expected results + +The calculated band structure should show: + +- **Modified electronic structure** near the Fermi level due to nitrogen substitution +- **Breaking of symmetry** compared to pristine graphene +- **Localized states** introduced by the nitrogen defects +- **Band gap opening** (depending on defect configuration) + +### 6.1. Comparison with published results + +The figure below compares the band structure from the Fujimoto & Saito manuscript (left) with the calculated results (right): + +![Band Structure Comparison](../../../images/tutorials/materials/defects/defect_creation_point_substitution_graphene/band-structure-comparison.webp "Comparison of band structure: manuscript (left) vs. calculated (right)") + +The calculated band structure reproduces the key features from the manuscript, including: + +- The overall band dispersion along the K → Γ → M → K path +- The position of bands relative to the Fermi level +- The electronic structure modifications due to nitrogen substitution +- The characteristic features near the K and Γ points + + +## 7. Customization options + +### 7.1. Modify the K-path + +In order to change the k-point path for the band structure calculation, edit the `KPATH` parameter in cell 1.3: + +```python +KPATH = [ + {"point": "K", "steps": 20}, + {"point": "Г", "steps": 20}, + {"point": "M", "steps": 20}, + {"point": "K", "steps": 1}, +] +``` + +### 7.2. Adjust computational resources + +Modify the compute parameters in cell 1.2: + +```python +CLUSTER_NAME = "101" # Your cluster name +QUEUE_NAME = QueueName.D # Queue selection +PPN = 1 # Processors per node +``` + +### 7.3. Add or remove relaxation + +Toggle structural relaxation by changing the `ADD_RELAXATION` flag (set by `RUN_PROFILE`): + +```python +ADD_RELAXATION = True # Enable relaxation +RELAXATION_KGRID = [6, 6, 1] # K-point grid for relaxation +``` + + +## 8. Troubleshooting + +### 8.1. Material not found + +If the material is not found in the uploads folder: + +1. Run the [defect creation notebook](defect-point-substitution-graphene.md) first +2. Ensure the material is saved with the exact name ("N-doped Graphene") +3. Check that the material file is in the correct `uploads` folder + + +## 9. Interactive JupyterLite notebook + +The following JupyterLite notebook demonstrates the workflow for calculating the band structure of N-doped graphene. Select *Run* > *Run All Cells*. + +{% with origin_url=config.extra.jupyterlite.origin_url_lab %} +{% with notebooks_path_root=config.extra.jupyterlite.notebooks_path_root %} +{% with notebook_name='specific_examples/defect_point_substitution_graphene_SIMULATION.ipynb' %} +{% include 'jupyterlite_embed.html' %} +{% endwith %} +{% endwith %} +{% endwith %} + + +## 10. References diff --git a/lang/en/docs/tutorials/materials/specific/defect-point-substitution-graphene.md b/lang/en/docs/tutorials/materials/specific/defect-point-substitution-graphene.md index c5cd3408c..94398eb36 100644 --- a/lang/en/docs/tutorials/materials/specific/defect-point-substitution-graphene.md +++ b/lang/en/docs/tutorials/materials/specific/defect-point-substitution-graphene.md @@ -5,6 +5,7 @@ tags: - substitutional - point-defects - nitrogen + - D-0D-SUB hide: - tags @@ -14,7 +15,7 @@ render_macros: true # Substitutional Point Defects in Graphene. -## Introduction. +## 1. Introduction This tutorial demonstrates the process of creating materials with substitution defects, based on the work presented in the following manuscript, where nitrogen defects in graphene are studied. @@ -23,7 +24,7 @@ This tutorial demonstrates the process of creating materials with substitution d !!!note "Manuscript" Yoshitaka Fujimoto and Susumu Saito, "Formation, stabilities, and electronic properties of nitrogen defects in graphene", Physical Review B, 2011. [DOI: 10.1103/PhysRevB.84.245446](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.84.245446){:target='_blank'}. [@Yoshitaka2011] -We use the [Materials Designer](../../../materials-designer/overview.md) to create a supercell of graphene, identify the crystal site positions for defects, and introduce nitrogen atoms and vacancies accordingly. +We use the [Materials Designer]({{ interface_url }}/materials-designer/overview/) to create a supercell of graphene, identify the crystal site positions for defects, and introduce nitrogen atoms and vacancies accordingly. We will focus on creating graphene-nitrogen structures from FIG. 1. Specifically, the material from FIG. 1. b) of the paper: @@ -32,106 +33,107 @@ Specifically, the material from FIG. 1. b) of the paper: ![Point Defect, Substitution, 0](../../../images/tutorials/materials/defects/defect_creation_point_substitution_graphene/0-figure-from-manuscript.webp "Point Defect, Substitution, FIG. 1.") -## 1. Create Graphene Supercell. +## 2. Create Graphene Supercell -First, we navigate to [Materials Designer](../../../materials-designer/overview.md) and import the graphene material from the [Standata](../../../materials-designer/header-menu/input-output/standata-import.md). +First, we navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and import the graphene material from the [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/). ![Standata Graphene Import](../../../images/tutorials/materials/defects/defect_creation_point_substitution_graphene/1-standata-graphene.webp "Standata Graphene Import") -We then use the [Advanced](../../../materials-designer/header-menu/advanced/supercell.md) menu to create a supercell of graphene with a size of 4x4x1. +We then use the [Advanced]({{ interface_url }}/materials-designer/header-menu/advanced/supercell/) menu to create a supercell of graphene with a size of 4x4x1. ![Supercell Creation for Graphene](../../../images/tutorials/materials/defects/defect_creation_point_substitution_graphene/2-advanced-supercell.webp "Supercell Graphene") -## 2. Identify Defect Sites. +## 3. Identify Defect Sites +Next, we can toggle the coordinates measurement in the editor to identify the crystal site positions for the defects. -Next, we open the [3D editor](../../../materials-designer/3d-editor.md) to identify the crystal site positions for the defects. +![Coordinates Measurement](../../../images/tutorials/materials/defects/defect_creation_point_substitution_graphene/4-toggle-measure-coordinates.webp "3D Editor Toggle Coordinates") -![3D Editor](../../../images/tutorials/materials/defects/defect_creation_point_substitution_graphene/4-threejs-editor-coordinates.webp "3D Editor") +Clicking on each atom will copy the coordinates of the atom to the clipboard as an array, which can then be pasted into the cell of the notebook and used to assign the defect coordinates. -Hover over the atoms to get the coordinates of the atoms to replace. Then copy/paste these coordinates into a text file for later use. +![3D Editor Coordinates](../../../images/tutorials/materials/defects/defect_creation_point_substitution_graphene/4-3d-editor-coordinates.webp "3D Editor Coordinates Copying") -## 3. Create Nitrogen Defects and Vacancies. -For the defect creation, we will use the [JupyterLite](../../../jupyterlite/overview.md) environment with the corresponding notebook. +## 4. Create Nitrogen Defects and Vacancies -### 3.1. Launch JupyterLite Session. +For the defect creation, we will use the [JupyterLite]({{ interface_url }}/jupyterlite/overview/) environment with the corresponding notebook. -Select the "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" menu item to launch the JupyterLite environment. +### 4.1. Launch JupyterLite Session + +Select the "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" menu item to launch the JupyterLite environment. ![JupyterLite Dialog](../../../images/jupyterlite/md-advanced-jl.webp "JupyterLite Dialog") -### 3.2. Open `create_point_defect.ipynb` notebook. +### 4.2. Open `create_point_defect.ipynb` notebook Find `create_point_defect.ipynb` in the list of notebooks and click/double-click open it. -### 3.3. Open and modify the notebook. +### 4.3. Open and modify the notebook -Next, edit `create_point_defect.ipynb` notebook to modify the parameters by adding a list of [defect configuration objects](https://github.com/Exabyte-io/made/blob/3d938b4d91a31323dca7a02acb12b646dbb26634/src/py/mat3ra/made/tools/build/defect/configuration.py#L32) containing the approximate coordinates of the atoms to replace. +Next, edit `create_point_defect.ipynb` notebook to modify the parameters by adding a list of [defect configuration objects](https://github.com/mat3ra/made/blob/3d938b4d91a31323dca7a02acb12b646dbb26634/src/py/mat3ra/made/tools/build/defect/configuration.py#L32) containing the approximate coordinates of the atoms to replace. Copy the below content and edit the "1.1. Set up defect parameters" cell in the notebook as follows: ```python -DEFECT_TYPE = "substitution" -SITE_ID = None # `from_site_id` method will be ignored -COORDINATE = None # default method will be ignored -APPROXIMATE_COORDINATE = None -CHEMICAL_ELEMENT = "N" +# Selected material will be used as a unit cell to create a supercell first. SUPERCELL_MATRIX = [[1, 0, 0], [0, 1, 0], [0, 0, 1]] -USE_CARTESIAN_COORDINATES = True DEFECT_CONFIGS = [ { - "defect_type": "substitution", - "approximate_coordinate": [4.9, 2.85, 10], - "chemical_element": CHEMICAL_ELEMENT, - "use_cartesian_coordinates": USE_CARTESIAN_COORDINATES + "type": "substitution", + "coordinate": [4.9, 2.85, 10], + "element": "N", + "placement_method": "closest_site", + "use_cartesian_coordinates": True }, { - "defect_type": "substitution", - "approximate_coordinate": [3.7, 4.9, 10], - "chemical_element": CHEMICAL_ELEMENT, - "use_cartesian_coordinates": USE_CARTESIAN_COORDINATES + "type": "substitution", + "coordinate": [3.7, 4.9, 10], + "element": "N", + "placement_method": "closest_site", + "use_cartesian_coordinates": True }, { - "defect_type": "substitution", - "approximate_coordinate": [2.45, 2.85, 10], - "chemical_element": CHEMICAL_ELEMENT, - "use_cartesian_coordinates": USE_CARTESIAN_COORDINATES + "type": "substitution", + "coordinate": [2.45, 2.85, 10], + "element": "N", + "placement_method": "closest_site", + "use_cartesian_coordinates": True }, { - "defect_type": "vacancy", - "approximate_coordinate": [3.7, 3.55, 10], - "use_cartesian_coordinates": USE_CARTESIAN_COORDINATES + "type": "vacancy", + "coordinate": [3.7, 3.55, 10], + "placement_method": "closest_site", + "use_cartesian_coordinates": True }, -] +] ``` Here's the visual of the updated content: ![Notebook setup](../../../images/tutorials/materials/defects/defect_creation_point_substitution_graphene/5-jl-setup.webp "Notebook setup") -## 4. Run the Notebook. +## 5. Run the Notebook Run the notebook by clicking `Run` > `Run All` in the top menu to run cells and wait for the results to appear. ![Run All](../../../images/jupyterlite/run-all.webp "Run All") -## 5. Analyze the Results. +## 6. Analyze the Results After running the notebook, the user will be able to visualize the structure of Graphene with substitution defects. ![Review the Results](../../../images/tutorials/materials/defects/defect_creation_point_substitution_graphene/6-jl-result-preview.webp "Review the Results") -## 6. Pass the Material to Materials Designer. +## 7. Pass the Material to Materials Designer The user can pass the material with substitution defects in the current Materials Designer environment and save it. ![Final Material](../../../images/tutorials/materials/defects/defect_creation_point_substitution_graphene/7-wave-result.webp "N-doped Graphene") -Or the user can [save or download](../../../materials-designer/header-menu/input-output.md) the material in Material JSON format or POSCAR format. +Or the user can [save or download]({{ interface_url }}/materials-designer/header-menu/input-output/) the material in Material JSON format or POSCAR format. -## Interactive JupyterLite Notebook. +## 8. Interactive JupyterLite Notebook The following JupyterLite notebook demonstrates the process of creating materials with substitution defects in graphene. Select "Run" > "Run All Cells". @@ -143,4 +145,4 @@ The following JupyterLite notebook demonstrates the process of creating material {% endwith %} {% endwith %} -## References. +## 9. References diff --git a/lang/en/docs/tutorials/materials/specific/defect-point-vacancy-boron-nitride.md b/lang/en/docs/tutorials/materials/specific/defect-point-vacancy-boron-nitride.md index fac376944..79d314cc0 100644 --- a/lang/en/docs/tutorials/materials/specific/defect-point-vacancy-boron-nitride.md +++ b/lang/en/docs/tutorials/materials/specific/defect-point-vacancy-boron-nitride.md @@ -6,6 +6,7 @@ tags: - h-BN - boron-nitride - 2D-materials + - D-0D-VAC hide: - tags @@ -15,28 +16,28 @@ render_macros: true # Vacancy Point Defects in Hexagonal Boron Nitride. -## Introduction. +## 1. Introduction This tutorial demonstrates the process of creating materials with vacancy point defects, based on the work presented in the following manuscript: !!!note "Manuscript" Fabian Bertoldo, Sajid Ali, Simone Manti & Kristian S. Thygesen, "Quantum point defects in 2D materials - the QPOD database", Nature, 2022. [DOI:10.1038/s41524-022-00730-w](https://doi.org/10.1038/s41524-022-00730-w){:target='_blank'}. [@Bertoldo2022; @Kohan2000] -We use the [Materials Designer](../../../materials-designer/overview.md) and JupyterLite environment to create a nanoribbon of hexagonal boron nitride (h-BN) and introduce vacancy defects. The process combines the capabilities of nanoribbon creation and point defect introduction. +We use the [Materials Designer]({{ interface_url }}/materials-designer/overview/) and JupyterLite environment to create a nanoribbon of hexagonal boron nitride (h-BN) and introduce vacancy defects. The process combines the capabilities of nanoribbon creation and point defect introduction. We will focus on creating a structure similar to Figure 6 from the manuscript, which demonstrates boron vacancy defects in hexagonal boron nitride: ![Vacancy in h-BN](../../../images/tutorials/materials/defects/defect_point_vacancy_boron_nitride/0-figure-from-manuscript.webp "Vacancy in h-BN") -## 1. Import Base Material. +## 2. Import Base Material -First, we need to import the hexagonal boron nitride (h-BN) material from the [Standata](../../../materials-designer/header-menu/input-output/standata-import.md) database. +First, we need to import the hexagonal boron nitride (h-BN) material from the [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/) database. -### 1.1. Open Materials Designer. +### 2.1. Open Materials Designer -Navigate to [Materials Designer](../../../materials-designer/overview.md) and click on the "Input/Output" menu. +Navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and click on the "Input/Output" menu. -### 1.2. Import from Standata. +### 2.2. Import from Standata 1. Select "Import from Standata" in the Input/Output menu 2. In the search box, enter "Boron Nitride" @@ -44,35 +45,39 @@ Navigate to [Materials Designer](../../../materials-designer/overview.md) and cl ![Standata h-BN Import](../../../images/tutorials/materials/interfaces/twisted-bilayer-boron-nitride/standata-import-bn.png "Standata h-BN Import") -## 2. Create h-BN Nanoribbon. +## 3. Create h-BN Nanoribbon Next, we'll create a nanoribbon structure using the JupyterLite environment. -### 2.1. Launch JupyterLite Session. +### 3.1. Launch JupyterLite Session -Select the "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" menu item to launch the JupyterLite environment. +Select the "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" menu item to launch the JupyterLite environment. ![JupyterLite Dialog](../../../images/jupyterlite/md-advanced-jl.webp "JupyterLite Dialog") -### 2.2. Open and Configure Nanoribbon Notebook. +### 3.2. Open and Configure Nanoribbon Notebook Find and open `create_nanoribbon.ipynb` in the list of notebooks. Edit the nanoribbon parameters in section 1.1 of the notebook: ```python -WIDTH = 3 # in number of unit cells -LENGTH = 6 # in number of unit cells -VACUUM_WIDTH = 0 # in number of unit cells -VACUUM_LENGTH = 0 # in number of unit cells -EDGE_TYPE = "zigzag" # "zigzag" or "armchair" +# Index in the list of materials, to access as materials[MATERIAL_INDEX] +MATERIAL_INDEX = 0 + +# Widths and lengths are in number of unit cells +WIDTH = 3 # in unit cells +LENGTH = 6 # in unit cells +VACUUM_WIDTH = 0 # in Angstroms +VACUUM_LENGTH = 0 # in Angstroms +EDGE_TYPE = "zigzag" # "zigzag" or "armchair" ``` ![Nanoribbon Parameters](../../../images/tutorials/materials/defects/defect_point_vacancy_boron_nitride/2-jl-nb-setup-nanoribbon.webp "Nanoribbon Parameters") -### 2.3. Run the Notebook. +### 3.3. Run the Notebook Run the notebook by clicking `Run` > `Run All` in the top menu. This will create a nanoribbon structure from the imported h-BN material. -### 2.4. Review Nanoribbon in Materials Designer. +### 3.4. Review Nanoribbon in Materials Designer After the notebook completes: @@ -83,20 +88,23 @@ After the notebook completes: ![Nanoribbon Preview](../../../images/tutorials/materials/defects/defect_point_vacancy_boron_nitride/3-wave-preview-nanoribbon.webp "Nanoribbon Preview") -## 3. Create the Vacancy Defect. +## 4. Create the Vacancy Defect After creating the nanoribbon, we'll introduce the vacancy defect using the point defect notebook. -### 3.1. Open Point Defect Notebook. +### 4.1. Open Point Defect Notebook Open `create_point_defect.ipynb` and modify the defect configuration parameters: ```python +# Selected material will be used as a unit cell to create a supercell first. SUPERCELL_MATRIX = [[1, 0, 0], [0, 1, 0], [0, 0, 1]] + DEFECT_CONFIGS = [ { - "defect_type": "vacancy", - "approximate_coordinate": [0.5, 0.5, 0.5], + "type": "vacancy", + "coordinate": [0.5, 0.5, 0.5], + "placement_method": "closest_site", "use_cartesian_coordinates": False } ] @@ -110,22 +118,22 @@ The configuration specifies: ![Point Defect Parameters](../../../images/tutorials/materials/defects/defect_point_vacancy_boron_nitride/4-jl-nb-setup-point-defect.webp "Point Defect Parameters") -### 3.2. Run the Notebook. +### 4.2. Run the Notebook Click `Run` > `Run All` in the top menu to run the notebook and preview the results. ![Review the Results](../../../images/tutorials/materials/defects/defect_point_vacancy_boron_nitride/5-jl-result-preview.webp "Review the Results") -## 4. Save the Material. +## 5. Save the Material After running both notebooks, user can visualize the structure of h-BN with the vacancy defect in the Materials Designer 3D viewer. ![Vacancy in h-BN](../../../images/tutorials/materials/defects/defect_point_vacancy_boron_nitride/6-wave-result.webp "Vacancy in h-BN") -[Save or download](../../../materials-designer/header-menu/input-output.md) in Material JSON format +[Save or download]({{ interface_url }}/materials-designer/header-menu/input-output/) in Material JSON format -## Interactive JupyterLite Notebook. +## 6. Interactive JupyterLite Notebook The following JupyterLite notebooks demonstrate the complete process. Select "Run" > "Run All Cells". @@ -137,5 +145,5 @@ The following JupyterLite notebooks demonstrate the complete process. Select "Ru {% endwith %} {% endwith %} -## References. +## 7. References diff --git a/lang/en/docs/tutorials/materials/specific/defect-surface-adatom-graphene.md b/lang/en/docs/tutorials/materials/specific/defect-surface-adatom-graphene.md index 263a55da1..fba696dfa 100644 --- a/lang/en/docs/tutorials/materials/specific/defect-surface-adatom-graphene.md +++ b/lang/en/docs/tutorials/materials/specific/defect-surface-adatom-graphene.md @@ -5,6 +5,7 @@ tags: - metal - surface - defect + - D-2D-ADA hide: - tags @@ -14,7 +15,7 @@ render_macros: true # Adatom on Graphene Surface. -## Introduction. +## 1. Introduction This tutorial demonstrates the process of creating a graphene structure with an adatom on the surface based on the work presented in the following manuscript. @@ -23,29 +24,29 @@ This tutorial demonstrates the process of creating a graphene structure with an "First-principles study of metal adatom adsorption on graphene" Phys. Rev. B 77, 235430, 2008 [DOI: 10.1103/PhysRevB.77.235430](https://doi.org/10.1103/PhysRevB.77.235430){:target='_blank'}. [@Chan2008] -We use the [Materials Designer](../../../materials-designer/overview.md) to create a graphene structure with a metal adatom on the surface. +We use the [Materials Designer]({{ interface_url }}/materials-designer/overview/) to create a graphene structure with a metal adatom on the surface. The image shows the adatom on the graphene surface. ![Adatom on Graphene Surface](../../../images/tutorials/materials/defects/defect-surface-adatom-graphene/me_adatom_on_hollow_graphene.webp "Fig. 1. Adatom on Graphene Surface") -## 1. Load and preview Graphene structure. +## 2. Load and preview Graphene structure -First, we navigate to [Materials Designer](../../../materials-designer/overview.md) and import the Graphene material from the [Standata](../../../materials-designer/header-menu/input-output/standata-import.md). +First, we navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and import the Graphene material from the [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/). ![Standata Graphene Import](../../../images/tutorials/materials/defects/defect_creation_point_substitution_graphene/1-standata-graphene.webp "Standata Graphene Import") -Then we will use the [JupyterLite](../../../jupyterlite/overview.md) environment to create a graphene structure with an adatom on the surface. +Then we will use the [JupyterLite]({{ interface_url }}/jupyterlite/overview/) environment to create a graphene structure with an adatom on the surface. -## 2. Add Li adatom. +## 3. Add Li adatom -### 2.1 Launch JupyterLite Session. +### 2.1 Launch JupyterLite Session -Select the "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" menu item to launch the JupyterLite environment. +Select the "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" menu item to launch the JupyterLite environment. ![JupyterLite Dialog](../../../images/jupyterlite/md-advanced-jl.webp "JupyterLite Dialog") -### 2.2. Open and modify the notebook. +### 3.2. Open and modify the notebook Next, edit `create_adatom_defect.ipynb` notebook to modify the parameters by changing values: @@ -64,27 +65,39 @@ Next, edit `create_adatom_defect.ipynb` notebook to modify the parameters by cha Copy the content below and adjust the "1.1. Set up slab parameters" cell in the notebook: ```python -DEFECT_TYPE = "adatom" -PLACEMENT_METHOD = "equidistant" -CHEMICAL_ELEMENT = "Li" -APPROXIMATE_POSITION_ON_SURFACE = [0.5, 0.5] -USE_CARTESIAN_COORDINATES = False -DISTANCE_Z = 1.71 +# Index in the list of materials, to access as materials[MATERIAL_INDEX] +MATERIAL_INDEX = 0 +ELEMENT = "Li" # Chemical element of the adatom + +# Dictionaries are validated and converted to AdatomDefectDict objects below +DEFECT_CONFIGS = [ + { + "type": "adatom", + "coordinate_2d": [0.5, 0.5], # Crystal coordinates on the surface (x, y) + "distance_z": 1.71, # Method to place the adatom + "element": ELEMENT, + } +] + + +PLACEMENT_METHOD = "equidistant" # Method to place the adatom, e.g., "new_crystal_site", "exact_coordinate", "equidistant" + # Slab parameters -MILLER_INDICES = (0, 0, 1) -SLAB_THICKNESS = 1 -VACUUM = 6 -SUPERCELL_MATRIX = [[4, 0, 0], [0, 4, 0], [0, 0, 1]] +MILLER_INDICES = (0, 0, 1) # Miller indices of the surface +SLAB_THICKNESS = 1 # Thickness of the slab in unit cells +VACUUM = 6.0 # Vacuum thickness in Angstrom +XY_SUPERCELL_MATRIX = [[4, 0], [0, 4]] # Supercell matrix for the slab +TERMINATION_FORMULA = None # Stoichiometric formula of the slab termination to be used. ``` -### 2.3. Run the notebook. +### 3.3. Run the notebook Run the notebook by selecting "Run > Run All Cells" from the menu. ![Run All](../../../images/jupyterlite/run-all.webp "Run All") -### 2.4. Analyze the Results. +### 3.4. Analyze the Results After running the notebook, the Graphene structure with a Li adatom on the surface will be created. @@ -92,17 +105,17 @@ The user will be able to visualize the created structure and download the corres ![Adatom on Graphene Surface](../../../images/tutorials/materials/defects/defect-surface-adatom-graphene/jl-result-preview-li.webp "Li Adatom on Graphene Surface") -### 2.5. Pass the Material to the Materials Designer. +### 3.5. Pass the Material to the Materials Designer After reviewing the results, the user can pass the material to Materials Designer for further analysis. ![Final Material](../../../images/tutorials/materials/defects/defect-surface-adatom-graphene/wave-result-li.webp "Li Adatom on Graphene Surface") -Or the user can [save or download](../../../materials-designer/header-menu/input-output.md) the material in Material JSON format or POSCAR format. +Or the user can [save or download]({{ interface_url }}/materials-designer/header-menu/input-output/) the material in Material JSON format or POSCAR format. -## 3. Add other metal adatoms. +## 4. Add other metal adatoms -### 3.1. Repeat the steps above. +### 4.1. Repeat the steps above To create a Graphene structure with other metal adatoms, repeat the steps above by changing the `CHEMICAL_ELEMENT`, `APPORXIMATE_POSITION_ON_SURFACE`, and `DISTANCE_Z` parameters according to he values in the table 1 of the manuscript. Notice, that some of the adatoms have more favorable position on top or bridge sites. @@ -111,7 +124,7 @@ For example, to create a Graphene structure with a Na adatom, adjust the paramet ```python CHEMICAL_ELEMENT = "Na" -APPROXIMATE_POSITION_ON_SURFACE = [0.5, 0.5] +COORDINATE_2D = [0.5, 0.5] DISTANCE_Z = 2.28 ``` @@ -120,7 +133,7 @@ DISTANCE_Z = 2.28 For K adatom on hollow site: ```python CHEMICAL_ELEMENT = "K" -APPROXIMATE_POSITION_ON_SURFACE = [0.5, 0.5] +COORDINATE_2D = [0.5, 0.5] DISTANCE_Z = 2.60 ``` @@ -130,7 +143,7 @@ DISTANCE_Z = 2.60 For Ca adatom on hollow site: ```python CHEMICAL_ELEMENT = "Ca" -APPROXIMATE_POSITION_ON_SURFACE = [0.5, 0.5] +COORDINATE_2D = [0.5, 0.5] DISTANCE_Z = 2.29 ``` @@ -140,7 +153,7 @@ DISTANCE_Z = 2.29 For Al adatom on hollow site: ```python CHEMICAL_ELEMENT = "Al" -APPROXIMATE_POSITION_ON_SURFACE = [0.5, 0.5] +COORDINATE_2D = [0.5, 0.5] DISTANCE_Z = 2.13 ``` @@ -150,7 +163,7 @@ DISTANCE_Z = 2.13 For Ga adatom on hollow site: ```python CHEMICAL_ELEMENT = "Ga" -APPROXIMATE_POSITION_ON_SURFACE = [0.5, 0.5] +COORDINATE_2D = [0.5, 0.5] DISTANCE_Z = 2.20 ``` @@ -160,7 +173,7 @@ DISTANCE_Z = 2.20 For In adatom on hollow site: ```python CHEMICAL_ELEMENT = "In" -APPROXIMATE_POSITION_ON_SURFACE = [0.5, 0.5] +COORDINATE_2D = [0.5, 0.5] DISTANCE_Z = 2.45 ``` @@ -170,7 +183,7 @@ DISTANCE_Z = 2.45 For Sn adatom on top site: ```python CHEMICAL_ELEMENT = "Sn" -APPROXIMATE_POSITION_ON_SURFACE = [7/12, 5/12] +COORDINATE_2D = [7/12, 5/12] DISTANCE_Z = 2.82 ``` @@ -216,7 +229,7 @@ DISTANCE_Z = 2.69 ![Au Adatom on Graphene Surface](../../../images/tutorials/materials/defects/defect-surface-adatom-graphene/jl-result-preview-au.webp "Au Adatom on Graphene Surface") -## Interactive JupiterLite Notebook. +## 5. Interactive JupiterLite Notebook The interactive JupyterLite notebook for creating Graphene structures with metal adatoms can be accessed below. To run the notebook, click on the "Run All" button. @@ -228,4 +241,4 @@ The interactive JupyterLite notebook for creating Graphene structures with metal {% endwith %} {% endwith %} -## References. +## 6. References diff --git a/lang/en/docs/tutorials/materials/specific/defect-surface-island-titanium-nitride.md b/lang/en/docs/tutorials/materials/specific/defect-surface-island-titanium-nitride.md index 1119fa8e2..41a229d9e 100644 --- a/lang/en/docs/tutorials/materials/specific/defect-surface-island-titanium-nitride.md +++ b/lang/en/docs/tutorials/materials/specific/defect-surface-island-titanium-nitride.md @@ -7,6 +7,7 @@ tags: - TiN - nitrogen - titanium + - D-2D-ISL hide: - tags @@ -16,7 +17,7 @@ render_macros: true # Island Surface Defect Formation in TiN. -## Introduction. +## 1. Introduction This tutorial demonstrates the process of creating material with island on the surface of TiN(001) based on the work presented in the following manuscript. @@ -26,7 +27,7 @@ This tutorial demonstrates the process of creating material with island on the s **D. G. Sangiovanni, A. B. Mei, D. Edström, L. Hultman, V. Chirita, I. Petrov, and J. E. Greene**, "Effects of surface vibrations on interlayer mass transport: Ab initio molecular dynamics investigation of Ti adatom descent pathways and rates from TiN/TiN(001) islands", Physical Review B, 2018. [DOI: 10.1103/PhysRevB.97.035406](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.97.035406){:target='_blank'}. [@Sangiovanni2018] -We use the [Materials Designer](../../../materials-designer/overview.md) to create a slab of TiN, identify the cartesian coordinates for an island on the surface, and build it. +We use the [Materials Designer]({{ interface_url }}/materials-designer/overview/) to create a slab of TiN, identify the cartesian coordinates for an island on the surface, and build it. We will focus on creating graphene-nitrogen structures from FIG. 2. Specifically, the material from FIG. 2. a) of the paper: @@ -35,23 +36,23 @@ Specifically, the material from FIG. 2. a) of the paper: ![Surface Defect](../../../images/tutorials/materials/defects/defect-creation-surface-island-titanium-nitride/0.png "Surface Defect, Island FIG. 2. a)") -## 1. Create and preview TiN Slab. +## 2. Create and preview TiN Slab -First, we navigate to [Materials Designer](../../../materials-designer/overview.md) and import the graphene material from the [Standata](../../../materials-designer/header-menu/input-output/standata-import.md). +First, we navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and import the graphene material from the [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/). ![Standata Graphene Import](../../../images/tutorials/materials/defects/defect_creation_point_substitution_graphene/1-standata-graphene.webp "Standata Graphene Import") -Then we will use the [JupyterLite](../../../jupyterlite/overview.md) environment to create a TiN slab. +Then we will use the [JupyterLite]({{ interface_url }}/jupyterlite/overview/) environment to create a TiN slab. -### 1.1. Launch JupyterLite Session. +### 2.1. Launch JupyterLite Session -Select the "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" menu item to launch the JupyterLite environment. +Select the "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" menu item to launch the JupyterLite environment. ![JupyterLite Dialog](../../../images/jupyterlite/md-advanced-jl.webp "JupyterLite Dialog") -### 1.2. Open and modify the notebook. +### 2.2. Open and modify the notebook Next, edit `create_slab.ipynb` notebook to modify the parameters by adding the following content to the "1.1. Set up slab parameters" cell in the notebook: @@ -63,20 +64,22 @@ MILLER_INDICES = (0, 0, 1) THICKNESS = 3 # in atomic layers VACUUM = 10.0 # in angstroms XY_SUPERCELL_MATRIX = [[10, 0], [0, 10]] -USE_ORTHOGONAL_Z = True +USE_ORTHOGONAL_C = True USE_CONVENTIONAL_CELL = True -# Index of the termination pair to be selected +# Stoichiometric formula of the slab termination to be used. +SLAB_TERMINATION_FORMULA = None +# if None, the index of all possible terminations will be used TERMINATION_INDEX = 0 ``` -### 1.3. Run the Notebook. +### 2.3. Run the Notebook Run the notebook by clicking `Run` > `Run All` in the top menu to run cells and wait for the results to appear. ![Run All](../../../images/jupyterlite/run-all.webp "Run All") -### 1.4. Analyze the Results. +### 2.4. Analyze the Results After running the notebook, the user will be able to visualize the created TiN slab. @@ -84,7 +87,7 @@ After running the notebook, the user will be able to visualize the created TiN s We don't need to save the material at this point, as we will recreate the slab with island on the surface in the next notebook. This step is needed to identify the coordinates of the island vertices. -## 2. Identifying the Island vertices coordinates. +## 3. Identifying the Island vertices coordinates We are creating an island defect that covers an area of 4.5x4.5 unit cells (which corresponds to 9x9 atoms). This island will be placed inside a 10x10 supercell (20x20 atoms). To position the island correctly, we need to select coordinates that are `0.45` crystal units apart along both lattice directions (a and b), ensuring the island is centered. @@ -106,17 +109,17 @@ The final centered coordinates of the island are: `[0.25, 0.2, 0]` and `[0.65, 0 These coordinates will be used in the next step to create the island on the surface. -## 3. Create Island on the Surface. +## 4. Create Island on the Surface -### 3.1. Open `create_point_defect.ipynb` notebook. +### 4.1. Open `create_point_defect.ipynb` notebook Close the current notebook. `Introduction` notebook should be open by default. Find `create_island_defect.ipynb` in the list of notebooks and double-click open it. -### 3.2. Modify the notebook. +### 4.2. Modify the notebook -Next, edit `create_island_defect.ipynb` notebook to modify the parameters by adding a list of [defect configuration objects](https://github.com/Exabyte-io/made/blob/3d938b4d91a31323dca7a02acb12b646dbb26634/src/py/mat3ra/made/tools/build/defect/configuration.py#L191) containing the cartesian coordinates of the island vertices. +Next, edit `create_island_defect.ipynb` notebook to modify the parameters by adding a list of [defect configuration objects](https://github.com/mat3ra/made/blob/3d938b4d91a31323dca7a02acb12b646dbb26634/src/py/mat3ra/made/tools/build/defect/configuration.py#L191) containing the cartesian coordinates of the island vertices. With the same TiN material selected in the materials input and coordinates for the island vertices from the previous step, the user can create the island on the surface. @@ -125,53 +128,60 @@ Notice, that we did not create the slab yet, so it is necessary to provide slab Copy the below content and edit the "1.1. Set up defect parameters" cell in the notebook as follows: ```python -ISLAND_SHAPE = 'box' -AUTO_ADD_VACUUM = True -VACUUM_THICKNESS = 10.0 -NUMBER_OF_ADDED_LAYERS = 0.5 - -BOX_PARAMETERS = { +# Shape-specific parameters +# Choose the island shape: 'cylinder', 'sphere', 'box', or 'triangular_prism' +# and the corresponding parameters +SHAPE_PARAMETERS = { + 'shape': 'box', 'min_coordinate': [0.25, 0.2, 0], - 'max_coordinate': [0.65, 0.6, 1], - "use_cartesian_coordinates": False + 'max_coordinate': [0.65, 0.6, 1] } +# Common parameters +CENTER_POSITION = [0.5, 0.5, 0.5] # Center of the island +USE_CARTESIAN_COORDINATES = False # Use Cartesian coordinates for the island +NUMBER_OF_ADDED_LAYERS = 0.5 # Number of layers to add to the island + +# Vacuum parameters for builder +AUTO_ADD_VACUUM = True # Automatically add vacuum to the slab +VACUUM_THICKNESS = 10.0 # Thickness of the vacuum + +# Slab parameters for creating a new slab if provided material is not a slab DEFAULT_SLAB_PARAMETERS = { "miller_indices": (0,0,1), "thickness": 3, "vacuum": 0.0, - "use_orthogonal_z": True, + "use_orthogonal_c": True, "xy_supercell_matrix": [[10, 0], [0, 10]] } - ``` Here's the visual of the updated content: ![Notebook setup](../../../images/tutorials/materials/defects/defect-creation-surface-island-titanium-nitride/island-setup.png "Notebook setup") -## 4. Run the Notebook. +## 5. Run the Notebook Run the notebook by clicking `Run` > `Run All` in the top menu to run cells and wait for the results to appear. ![Run All](../../../images/jupyterlite/run-all.webp "Run All") -## 5. Analyze the Results. +## 6. Analyze the Results After running the notebook, the user will be able to visualize the created material with the island on the surface. ![Review the Results](../../../images/tutorials/materials/defects/defect-creation-surface-island-titanium-nitride/original-result.png "Review the Results") -## 6. Pass the Material to Materials Designer. +## 7. Pass the Material to Materials Designer The user can pass the resulting material to the current Materials Designer environment and save it. Resulting Material: Island on the TiN Surface -Or the user can [save or download](../../../materials-designer/header-menu/input-output.md) the material in Material JSON format or POSCAR format. +Or the user can [save or download]({{ interface_url }}/materials-designer/header-menu/input-output/) the material in Material JSON format or POSCAR format. -## Interactive JupyterLite Notebook. +## 8. Interactive JupyterLite Notebook The following JupyterLite notebook demonstrates the process of creating material with island. Select "Run" > "Run All Cells". @@ -183,4 +193,4 @@ The following JupyterLite notebook demonstrates the process of creating material {% endwith %} {% endwith %} -## References. +## 9. References diff --git a/lang/en/docs/tutorials/materials/specific/defect-surface-step-platinum.md b/lang/en/docs/tutorials/materials/specific/defect-surface-step-platinum.md index cc2058789..c75e5b9a6 100644 --- a/lang/en/docs/tutorials/materials/specific/defect-surface-step-platinum.md +++ b/lang/en/docs/tutorials/materials/specific/defect-surface-step-platinum.md @@ -7,6 +7,7 @@ tags: - slab - Pt(211) - Pt(111) + - D-2D-TER hide: - tags @@ -16,7 +17,7 @@ render_macros: true # Terrace Steps on Platinum (111) Surface. -## Introduction. +## 1. Introduction This tutorial demonstrates two different approaches to creating terrace steps on platinum surfaces, based on the work presented in the following manuscript: @@ -32,40 +33,46 @@ We will demonstrate two methods: 1. Creating a Pt(211) surface which inherently contains steps 2. Creating a terrace step on a Pt(111) surface using the TerraceSlabDefectBuilder -## 1. Method I: Create Pt(211) Surface. +## 2. Method I: Create Pt(211) Surface - Creates a surface with inherent steps - Smaller unit cell - Fixed step geometry - Good for studying specific crystal faces -### 1.1. Import Base Material. +### 2.1. Import Base Material First, we need to import the platinum material from Standata: -1. Navigate to [Materials Designer](../../../materials-designer/overview.md) +1. Navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) 2. Click on "Input/Output" menu 3. Select "Import from Standata" 4. Search for "Pt" and select the bulk platinum material ![Standata Import](../../../images/tutorials/materials/defects/defect_surface_step_platinum/1-standata-import-platinum.webp "Standata Import") -### 1.2. Launch JupyterLite Environment. +### 2.2. Launch JupyterLite Environment -Select "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" to open JupyterLite. +Select "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" to open JupyterLite. -### 1.3. Configure Slab Parameters. +### 2.3. Configure Slab Parameters Open a `create_slab.ipynb` notebook and set up the slab parameters in the "1.1. Set up notebook" cell: ```python -MATERIAL_NAME = "Pt" +# Enable interactive selection of terminations via UI prompt +IS_TERMINATIONS_SELECTION_INTERACTIVE = False + MILLER_INDICES = (2, 1, 1) THICKNESS = 6 # in atomic layers VACUUM = 10.0 # in angstroms XY_SUPERCELL_MATRIX = [[1, 0], [0, 1]] -USE_ORTHOGONAL_Z = True +USE_ORTHOGONAL_C = True USE_CONVENTIONAL_CELL = True + +# Stoichiometric formula of the slab termination to be used. +SLAB_TERMINATION_FORMULA = None +# if None, the index of all possible terminations will be used TERMINATION_INDEX = 0 ``` @@ -78,24 +85,24 @@ These parameters will create a Pt(211) surface with: ![Pt(211) Surface Setup](../../../images/tutorials/materials/defects/defect_surface_step_platinum/2-jl-setup-nb-surface.webp "Pt(211) Surface Setup") -### 1.4. Create the Slab. +### 2.4. Create the Slab Run the notebook by clicking `Run` > `Run All` in the top menu. The notebook will generate the Pt(211) surface. ![Pt(211) Surface](../../../images/tutorials/materials/defects/defect_surface_step_platinum/3-wave-result-pt-211-surface.webp "Pt(211) Surface") -## 2. Method II: Create Terrace Step Defect on Pt(111). +## 3. Method II: Create Terrace Step Defect on Pt(111) - More flexible control over step placement - Larger surface area available - Customizable terrace height - Better for complex step arrangements -### 2.1. Open Terrace Defect Notebook. +### 3.1. Open Terrace Defect Notebook First, open `create_terrace_defect.ipynb`and select Pt as the input material. -### 2.2. Configure Terrace Parameters. +### 3.2. Configure Terrace Parameters `CUT_DIRECTION = [0, 1, 1]` -- Normal vector for cutting plane, which will give a perfect periodic match along x and a match along y after rotation. `DEFAULT_SLAB_PARAMETERS["miller_indices"] = (1, 1, 1)` -- Miller indices for Pt(111) surface @@ -104,39 +111,32 @@ First, open `create_terrace_defect.ipynb`and select Pt as the input material. ```python # Material selection -# Which material to use from input list -MATERIAL_INDEX = 0 - -# Terrace parameters: -# Normal vector describing a plane that cuts the terrace from added layers (Miller indices) -CUT_DIRECTION = [0,1,1] -# Point the cutting plane passes through, in crystal coordinates -PIVOT_COORDINATE = [0.5, 0.5, 0.5] -# Height of terrace in atomic layers -NUMBER_OF_ADDED_LAYERS = 1 -# Use cartesian instead of crystal coordinates -USE_CARTESIAN_COORDINATES = False -# Rotate to match periodic boundary conditions -ROTATE_TO_MATCH_PBC = True +MATERIAL_INDEX = 0 # Which material to use from input list + +# Terrace parameters +CUT_DIRECTION = [0, 1, 1] # Normal vector describing a plane that cuts the terrace from added layers (Miller indices) +PIVOT_COORDINATE = [0.5, 0.5, 0.5] # Point the cutting plane passes through, in crystal coordinates +NUMBER_OF_ADDED_LAYERS = 1 # Height of terrace in atomic layers +USE_CARTESIAN_COORDINATES = False # Use cartesian instead of crystal coordinates +ROTATE_TO_MATCH_PBC = True # Rotate to match periodic boundary conditions # Slab parameters for creating a new slab if provided material is not a slab DEFAULT_SLAB_PARAMETERS = { - "miller_indices": (1,1,1), + "miller_indices": (1, 1, 1), "thickness": 6, "vacuum": 10.0, - "use_orthogonal_z": True, + "USE_ORTHOGONAL_C": True, "xy_supercell_matrix": [[2, 0], [0, 2]] } # Visualization parameters SHOW_INTERMEDIATE_STEPS = True -# Structure repeat in view -CELL_REPETITIONS_FOR_VISUALIZATION = [1, 1, 1] +CELL_REPETITIONS_FOR_VISUALIZATION = [1, 1, 1] # Structure repeat in view ``` ![Terrace Parameters](../../../images/tutorials/materials/defects/defect_surface_step_platinum/4-jl-setup-nb-terrace.webp "Terrace Parameters") -### 2.3. Create the Terrace. +### 3.3. Create the Terrace Run the notebook to create the Pt(111) surface with a terrace step. @@ -146,9 +146,9 @@ The same material with repetitions: ![Pt(111) Surface with Terrace Step with repetitions](../../../images/tutorials/materials/defects/defect_surface_step_platinum/6-wave-result-pt-terrace-repetitions.webp "Pt(111) Surface with Terrace Step with repetitions") -The user can [save or download](../../../materials-designer/header-menu/input-output.md) the material in Material JSON format or POSCAR format. +The user can [save or download]({{ interface_url }}/materials-designer/header-menu/input-output/) the material in Material JSON format or POSCAR format. -## Interactive JupyterLite Notebook. +## 4. Interactive JupyterLite Notebook The following JupyterLite notebook demonstrates both approaches. Select "Run" > "Run All Cells" to execute the notebook. @@ -160,4 +160,4 @@ The following JupyterLite notebook demonstrates both approaches. Select "Run" > {% endwith %} {% endwith %} -## References. +## 5. References diff --git a/lang/en/docs/tutorials/materials/specific/heterostructure-silicon-silicon-dioxide-hafnium-dioxide-titanium-nitride.md b/lang/en/docs/tutorials/materials/specific/heterostructure-silicon-silicon-dioxide-hafnium-dioxide-titanium-nitride.md index 0c5012ed1..4d4249d4e 100644 --- a/lang/en/docs/tutorials/materials/specific/heterostructure-silicon-silicon-dioxide-hafnium-dioxide-titanium-nitride.md +++ b/lang/en/docs/tutorials/materials/specific/heterostructure-silicon-silicon-dioxide-hafnium-dioxide-titanium-nitride.md @@ -11,6 +11,7 @@ tags: - SiO2 - HfO2 - TiN + - C-2D-HST hide: - tags @@ -20,7 +21,7 @@ render_macros: true # Creating High-k Metal Gate Stack: Si/SiO2/HfO2/TiN. -## Introduction. +## 1. Introduction This tutorial demonstrates how to create a high-k metal gate stack heterostructure consisting of four materials: Si (substrate), SiO2 (gate oxide), HfO2 (high-k dielectric), and TiN (metal gate). The process involves: @@ -32,13 +33,13 @@ This tutorial demonstrates how to create a high-k metal gate stack heterostructu QuantumATK tutorial: [High-k Metal Gate Stack Builder](https://docs.quantumatk.com/tutorials/hkmg_builder/hkmg_builder.html) [@Muller1999; @Robertson2006] -We use the [Materials Designer](../../../materials-designer/overview.md) to create the high-k metal gate stack as shown in the figure below. +We use the [Materials Designer]({{ interface_url }}/materials-designer/overview/) to create the high-k metal gate stack as shown in the figure below. ![High-k Metal Gate Stack](../../../images/tutorials/materials/heterostructures/heterostructure-silicon-silicon-dioxide-hafnium-dioxide-titanium-nitride/original-figure.webp "High-k Metal Gate Stack") -## 1. Set Up Materials. +## 2. Set Up Materials -First, navigate to Materials Designer and import from [Standata](../../../materials-designer/header-menu/input-output/standata-import.md) the following materials: +First, navigate to Materials Designer and import from [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/) the following materials: - Silicon (Si) - Silicon dioxide (SiO2) @@ -47,11 +48,11 @@ First, navigate to Materials Designer and import from [Standata](../../../materi ![Standata Import](../../../images/tutorials/materials/heterostructures/heterostructure-silicon-silicon-dioxide-hafnium-dioxide-titanium-nitride/import-standata.webp "Standata Import") -## 2. Create HfO2 and TiN Slabs. +## 3. Create HfO2 and TiN Slabs Before building the stack, we need to create properly terminated slabs for HfO2 and TiN. -### 2.1. Create HfO2 Slab. +### 3.1. Create HfO2 Slab More detailed instructions on slab creation can be found in the [SrTiO3 Slab](slab-strontium-titanate.md) tutorial. @@ -74,7 +75,7 @@ Run the notebook to create the HfO2 slab and pass it to Materials Designer. ![HfO2 slab](../../../images/tutorials/materials/heterostructures/heterostructure-silicon-silicon-dioxide-hafnium-dioxide-titanium-nitride/wave-result-hfo2-slab-wave.webp "HfO2 slab") -### 2.2. Create TiN Slab. +### 3.2. Create TiN Slab Open another instance of `create_slab_with_termination.ipynb` for TiN: @@ -94,48 +95,59 @@ Run the notebook to create and pass the TiN slab to Materials Designer. ![TiN slab](../../../images/tutorials/materials/heterostructures/heterostructure-silicon-silicon-dioxide-hafnium-dioxide-titanium-nitride/wave-result-tin-slab.webp "TiN slab") -## 3. Create Si/SiO2 Interface. +## 4. Create Si/SiO2 Interface -### 3.1. Launch ZSL Interface Builder. +### 4.1. Launch ZSL Interface Builder Open `create_interface_with_min_strain_zsl.ipynb` and configure: ```python -MAX_AREA = 200 # Maximum area for strain matching -MAX_AREA_RATIO_TOLERANCE = 0.25 # Maximum area ratio tolerance -MAX_ANGLE_TOLERANCE = 0.15 # Maximum angle tolerance -MAX_LENGTH_TOLERANCE = 0.15 # Maximum length tolerance - FILM_INDEX = 1 # SiO2 FILM_MILLER_INDICES = (1, 0, 0) FILM_THICKNESS = 3 -FILM_XY_SUPERCELL_MATRIX = [[1, 0], [0, 1]] +FILM_TERMINATION_FORMULA = None # if None, the first termination will be used FILM_VACUUM = 0.0 -FILM_USE_ORTHOGONAL_Z = True +FILM_XY_SUPERCELL_MATRIX = [[1, 0], [0, 1]] +FILM_USE_ORTHOGONAL_C = True # Changed from FILM_USE_ORTHOGONAL_Z SUBSTRATE_INDEX = 0 # Si SUBSTRATE_MILLER_INDICES = (1, 0, 0) SUBSTRATE_THICKNESS = 4 -SUBSTRATE_XY_SUPERCELL_MATRIX = [[1, 0], [0, 1]] +SUBSTRATE_TERMINATION_FORMULA = None # if None, the first termination will be used SUBSTRATE_VACUUM = 5.0 -SUBSTRATE_USE_ORTHOGONAL_Z = True +SUBSTRATE_XY_SUPERCELL_MATRIX = [[1, 0], [0, 1]] +SUBSTRATE_USE_ORTHOGONAL_C = True # Changed from SUBSTRATE_USE_ORTHOGONAL_Z INTERFACE_DISTANCE = 2.5 # Angstroms INTERFACE_VACUUM = 5.0 # Angstroms -TERMINATION_PAIR_INDEX = 0 + +# Whether to convert materials to conventional cells before creating slabs. +# To create interfaces with smaller cells, set this flag to False. (and pass already conventional cells as input) +USE_CONVENTIONAL_CELL = True + +# Maximum area for the superlattice search algorithm (the final interface area will be smaller) +MAX_AREA = 200 # in Angstrom^2 +# Additional fine-tuning parameters (increase values to get more strained matches): +MAX_AREA_TOLERANCE = 0.25 # in Angstrom^2 +MAX_LENGTH_TOLERANCE = 0.15 +MAX_ANGLE_TOLERANCE = 0.15 + +# Whether to reduce the resulting interface cell to the primitive cell after the interface creation. +# If the reduction causes unexpected results, try increasing the `MAX_AREA` for search. +REDUCE_RESULT_CELL_TO_PRIMITIVE = True ``` We set a higher tolerances to achieve smaller cell with higher strain of the film (SiO2). ![Interface Setup](../../../images/tutorials/materials/heterostructures/heterostructure-silicon-silicon-dioxide-hafnium-dioxide-titanium-nitride/jl-setup-notebook-si-sio2.webp "Interface Setup") -### 3.2. Create Initial Interface. +### 4.2. Create Initial Interface Run the notebook to create the Si/SiO2 interface. This is the most critical interface, so we use strain matching to optimize it. -## 4. Add HfO2 Layer. +## 5. Add HfO2 Layer -### 4.1. Configure Simple Interface Builder. +### 5.1. Configure Simple Interface Builder Open JupyterLite Session again and select the Si/SiO2 interface and HfO2 slab as input materials. @@ -158,15 +170,15 @@ Film is the material that will be strained (scaled) to match the substrate. ![HfO2 Interface Setup](../../../images/tutorials/materials/heterostructures/heterostructure-silicon-silicon-dioxide-hafnium-dioxide-titanium-nitride/jl-setup-notebook-si-sio2-hfo2.webp "HfO2 Interface Setup") -### 4.2. Add HfO2. +### 5.2. Add HfO2 Run the notebook to add the pre-created HfO2 slab to the Si/SiO2 structure. ![Si/SiO2/HfO2](../../../images/tutorials/materials/heterostructures/heterostructure-silicon-silicon-dioxide-hafnium-dioxide-titanium-nitride/wave-result-si-sio2-hfo2.webp "Si/SiO2/HfO2") -## 5. Add TiN Layer. +## 6. Add TiN Layer -### 5.1. Configure Final Layer Addition. +### 6.1. Configure Final Layer Addition Similar to steps in Section 4, we add the TiN layer to the Si/SiO2/HfO2 stack. @@ -185,15 +197,15 @@ INTERFACE_DISTANCE = 2.5 # Angstroms INTERFACE_VACUUM = 10.0 # Final vacuum spacing ``` -### 5.2. Complete the Stack. +### 6.2. Complete the Stack Run the notebook to add the TiN layer and complete the stack. ![Final Stack](../../../images/tutorials/materials/heterostructures/heterostructure-silicon-silicon-dioxide-hafnium-dioxide-titanium-nitride/wave-result-si-sio2-hfo2-tin.webp "Final Stack") -The user then can [save or download](../../../materials-designer/header-menu/input-output.md) the material in Material JSON format or POSCAR format. +The user then can [save or download]({{ interface_url }}/materials-designer/header-menu/input-output/) the material in Material JSON format or POSCAR format. -## Interactive JupyterLite Notebook. +## 7. Interactive JupyterLite Notebook The following JupyterLite notebook demonstrates the process of creating target material. Select "Run" > "Run All Cells". @@ -205,5 +217,5 @@ The following JupyterLite notebook demonstrates the process of creating target m {% endwith %} {% endwith %} -## References. +## 8. References diff --git a/lang/en/docs/tutorials/materials/specific/interface-2d-2d-graphene-boron-nitride.md b/lang/en/docs/tutorials/materials/specific/interface-2d-2d-graphene-boron-nitride.md index 6aed6233d..28330f6ec 100644 --- a/lang/en/docs/tutorials/materials/specific/interface-2d-2d-graphene-boron-nitride.md +++ b/lang/en/docs/tutorials/materials/specific/interface-2d-2d-graphene-boron-nitride.md @@ -5,6 +5,7 @@ tags: - Hexagonal Boron Nitride - interface - stacking + - C-2D-INT-Z hide: - tags @@ -14,7 +15,7 @@ render_macros: true # Interfaces between 2D Materials: h-BN and Graphene. -## Introduction. +## 1. Introduction This tutorial demonstrates the process of creating interfaces with different stacking configurations between 2D materials, specifically hexagonal boron nitride (h-BN) and graphene, based on the work presented in the following manuscript, where the electronic properties of h-BN-graphene interfaces are studied. @@ -25,32 +26,32 @@ This tutorial demonstrates the process of creating interfaces with different sta [DOI: 10.1038/ncomms7308](https://doi.org/10.1038/ncomms7308) [@Jung2015; @Novoselov2016; @Gupta2024] -We use the [Materials Designer](../../../materials-designer/overview.md) to create interfaces and shift the layers along the y-axis to achieve different stacking configurations. +We use the [Materials Designer]({{ interface_url }}/materials-designer/overview/) to create interfaces and shift the layers along the y-axis to achieve different stacking configurations. The Figure 7 shows the different stacking configurations of graphene on h-BN. ![Graphene on Hexagonal Boron Nitride](../../../images/tutorials/materials/interfaces/interface_2d_2d_graphene_boron_nitride/0-figure-from-manuscript.webp "Graphene on Hexagonal Boron Nitride, FIG. 7") -## 1. Load and preview materials. +## 2. Load and preview materials -First, we navigate to [Materials Designer](../../../materials-designer/overview.md) and import the Graphene and Hexagonal BN materials from the [Standata](../../../materials-designer/header-menu/input-output/standata-import.md). +First, we navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and import the Graphene and Hexagonal BN materials from the [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/). ![Standata Graphene and h-BN Import](../../../images/tutorials/materials/interfaces/interface_2d_2d_graphene_boron_nitride/1-standata-import-gr-hbn.webp "Standata Graphene and h-BN Import") -Then we will use the [JupyterLite](../../../jupyterlite/overview.md) environment to create the target structures. +Then we will use the [JupyterLite]({{ interface_url }}/jupyterlite/overview/) environment to create the target structures. -## 2. Create interface between h-BN and Graphene. +## 3. Create interface between h-BN and Graphene -### 2.1 Launch JupyterLite Session. +### 2.1 Launch JupyterLite Session -Select the "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" menu item to launch the JupyterLite environment. +Select the "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" menu item to launch the JupyterLite environment. ![JupyterLite Dialog](../../../images/jupyterlite/md-advanced-jl.webp "JupyterLite Dialog") -### 2.2. Open and modify the notebook. +### 3.2. Open and modify the notebook Select the input materials with first one being the substrate (h-BN) and the second one being the film (Graphene). @@ -71,38 +72,51 @@ Adjust the "1.1. Set up slab parameters" cell in the notebook according to: # Enable interactive selection of terminations via UI prompt IS_TERMINATIONS_SELECTION_INTERACTIVE = False -FILM_INDEX = 1 # Index in the list of materials, to access as materials[FILM_INDEX] +FILM_INDEX = 1 # Index in the list of materials, to access as materials[FILM_INDEX] FILM_MILLER_INDICES = (0, 0, 1) FILM_THICKNESS = 1 # in atomic layers +FILM_TERMINATION_FORMULA = None # if None, the first termination will be used FILM_VACUUM = 0.0 # in angstroms FILM_XY_SUPERCELL_MATRIX = [[1, 0], [0, 1]] -FILM_USE_ORTHOGONAL_Z = True +FILM_USE_ORTHOGONAL_C = True SUBSTRATE_INDEX = 0 SUBSTRATE_MILLER_INDICES = (0, 0, 1) SUBSTRATE_THICKNESS = 1 # in atomic layers +SUBSTRATE_TERMINATION_FORMULA = None # if None, the first termination will be used SUBSTRATE_VACUUM = 0.0 # in angstroms SUBSTRATE_XY_SUPERCELL_MATRIX = [[1, 0], [0, 1]] -SUBSTRATE_USE_ORTHOGONAL_Z = True - -# Maximum area for the superlattice search algorithm -MAX_AREA = 50 # in Angstrom^2 -# Set the termination pair indices -TERMINATION_PAIR_INDEX = 0 # Will be overridden in interactive selection is used -INTERFACE_DISTANCE = 3.4 # in Angstrom -INTERFACE_VACUUM = 20.0 # in Angstrom +SUBSTRATE_USE_ORTHOGONAL_C = True + +INTERFACE_DISTANCE = 3.4 # Gap between substrate and film, in Angstrom +INTERFACE_VACUUM = 20.0 # Vacuum over film, in Angstrom + +# Whether to convert materials to conventional cells before creating slabs. +# To create interfaces with smaller cells, set this flag to False. (and pass already conventional cells as input) +USE_CONVENTIONAL_CELL = True + +# Maximum area for the superlattice search algorithm (the final interface area will be smaller) +MAX_AREA = 50 # in Angstrom^2 +# Additional fine-tuning parameters (increase values to get more strained matches): +MAX_AREA_TOLERANCE = 0.09 # in Angstrom^2 +MAX_LENGTH_TOLERANCE = 0.05 +MAX_ANGLE_TOLERANCE = 0.02 + +# Whether to reduce the resulting interface cell to the primitive cell after the interface creation. +# If the reduction causes unexpected results, try increasing the `MAX_AREA` for search. +REDUCE_RESULT_CELL_TO_PRIMITIVE = True ``` ![Notebook setup](../../../images/tutorials/materials/interfaces/interface_2d_2d_graphene_boron_nitride/2-jl-setup-notebook.webp "Notebook setup") -### 2.3. Run the Notebook. +### 3.3. Run the Notebook After setting the parameters, run the notebook to create the interface between h-BN and Graphene. ![Run All](../../../images/jupyterlite/run-all.webp "Run All") -### 2.4. View Results and shift the layers. +### 3.4. View Results and shift the layers The generation might take some time. After that, the user can pass the material to the Materials Designer for further analysis. @@ -126,8 +140,8 @@ a = selected_interface.lattice.a shifted_interface = interface_displace_part( interface=selected_interface, displacement=[0, n * a / np.sqrt(3), 0], - use_cartesian_coordinates=True) - + use_cartesian_coordinates=True, +) ``` ![Shift Interface](../../../images/tutorials/materials/interfaces/interface_2d_2d_graphene_boron_nitride/4-jl-setup-shift.webp "Shift Interface") @@ -136,16 +150,16 @@ Preview of interfaces with different stacking configurations is shown below. ![Shifted Interfaces](../../../images/tutorials/materials/interfaces/interface_2d_2d_graphene_boron_nitride/5-jl-result-preview.webp "Shifted Interfaces") -## 3. Pass the Material to Materials Designer. +## 4. Pass the Material to Materials Designer The user can pass the material with the interface in the current Materials Designer environment and save it. ![Final Material](../../../images/tutorials/materials/interfaces/interface_2d_2d_graphene_boron_nitride/6-wave-result.webp "Graphene on Hexagonal Boron Nitride Interface") -Or the user can [save or download](../../../materials-designer/header-menu/input-output.md) the material in Material JSON format or POSCAR format. +Or the user can [save or download]({{ interface_url }}/materials-designer/header-menu/input-output/) the material in Material JSON format or POSCAR format. -## Interactive JupyterLite Notebook. +## 5. Interactive JupyterLite Notebook The interactive JupyterLite notebook for creating Gr/h-BN interface can be accessed below. To run the notebook, click on the "Run All" button. @@ -158,5 +172,5 @@ The interactive JupyterLite notebook for creating Gr/h-BN interface can be acces {% endwith %} {% endwith %} -## References. +## 6. References diff --git a/lang/en/docs/tutorials/materials/specific/interface-2d-3d-graphene-silicon-dioxide.md b/lang/en/docs/tutorials/materials/specific/interface-2d-3d-graphene-silicon-dioxide.md index 8c88720fa..faa2e83cb 100644 --- a/lang/en/docs/tutorials/materials/specific/interface-2d-3d-graphene-silicon-dioxide.md +++ b/lang/en/docs/tutorials/materials/specific/interface-2d-3d-graphene-silicon-dioxide.md @@ -7,6 +7,7 @@ tags: - 3D - oxygen - termination + - C-2D-INT-Z hide: - tags @@ -17,7 +18,7 @@ render_macros: true # Interfaces between 2D and 3D Materials: Graphene on SiO2 (alpha-quartz). -## Introduction. +## 1. Introduction This tutorial demonstrates the process of creating interfaces between 2D and 3D materials, specifically graphene and silicon dioxide (SiO2), based on the work presented in the following manuscript, where the electronic properties of graphene on SiO2 are studied. @@ -27,27 +28,27 @@ This tutorial demonstrates the process of creating interfaces between 2D and 3D Physical Review B 78, 115404 (2008) [DOI: 10.1103/PhysRevB.78.115404](https://doi.org/10.1103/PhysRevB.78.115404) [@Kang2008; @Dahal2014] -We use the [Materials Designer](../../../materials-designer/overview.md) to create interfaces between graphene and silicon dioxide with oxygen termination, as shown in the manuscript. +We use the [Materials Designer]({{ interface_url }}/materials-designer/overview/) to create interfaces between graphene and silicon dioxide with oxygen termination, as shown in the manuscript. We will focus on replicating the material from FIG. 1. (b) -- with Graphene on O-terminated SiO2. The material (a) requires relaxation to correctly reproduce the structure, which is not covered in this tutorial. ![Graphene on Silicon Dioxide](../../../images/tutorials/materials/interfaces/interface_2d_3d_graphene_silicon_dioxide/0-figure-from-manuscript.webp "Graphene on Silicon Dioxide, FIG. 1(b)") -## 1. Load and Preview Materials. +## 2. Load and Preview Materials -Navigate to [Materials Designer](../../../materials-designer/overview.md) and import graphene and silicon dioxide materials from the [Standata](../../../materials-designer/header-menu/input-output/standata-import.md). +Navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and import graphene and silicon dioxide materials from the [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/). -Then use the [JupyterLite](../../../jupyterlite/overview.md) environment to create the target structures. +Then use the [JupyterLite]({{ interface_url }}/jupyterlite/overview/) environment to create the target structures. -## 2. Create Interface Between Graphene and Silicon Dioxide. +## 3. Create Interface Between Graphene and Silicon Dioxide -### 2.1 Launch JupyterLite Session. +### 2.1 Launch JupyterLite Session -Select the "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" menu item to launch the JupyterLite environment. +Select the "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" menu item to launch the JupyterLite environment. ![JupyterLite Dialog](../../../images/jupyterlite/md-advanced-jl.webp "JupyterLite Dialog") -### 2.2 Open and Modify the Notebook. +### 2.2 Open and Modify the Notebook Select the input materials with the first being the substrate (SiO₂) and the second being the film (graphene). @@ -71,23 +72,36 @@ IS_TERMINATIONS_SELECTION_INTERACTIVE = False FILM_INDEX = 1 # Index in the list of materials, to access as materials[FILM_INDEX] FILM_MILLER_INDICES = (0, 0, 1) FILM_THICKNESS = 1 # in atomic layers +FILM_TERMINATION_FORMULA = None # if None, the first termination will be used FILM_VACUUM = 0.0 # in angstroms FILM_XY_SUPERCELL_MATRIX = [[1, 0], [0, 1]] -FILM_USE_ORTHOGONAL_Z = True +FILM_USE_ORTHOGONAL_C = True SUBSTRATE_INDEX = 0 SUBSTRATE_MILLER_INDICES = (0, 0, 1) SUBSTRATE_THICKNESS = 7 # in atomic layers (for 14 bilayers -- from manuscript) +SUBSTRATE_TERMINATION_FORMULA = None # if None, the first termination will be used SUBSTRATE_VACUUM = 0.0 # in angstroms SUBSTRATE_XY_SUPERCELL_MATRIX = [[1, 0], [0, 1]] -SUBSTRATE_USE_ORTHOGONAL_Z = True +SUBSTRATE_USE_ORTHOGONAL_C = True -# Maximum area for the superlattice search algorithm +INTERFACE_DISTANCE = 2.58 # Gap between substrate and film, in Angstrom +INTERFACE_VACUUM = 20.0 # Vacuum over film, in Angstrom + +# Whether to convert materials to conventional cells before creating slabs. +# To create interfaces with smaller cells, set this flag to False. (and pass already conventional cells as input) +USE_CONVENTIONAL_CELL = True + +# Maximum area for the superlattice search algorithm (the final interface area will be smaller) MAX_AREA = 150 # in Angstrom^2 -# Set the termination pair indices -TERMINATION_PAIR_INDICES = [1] # For O-terminated -INTERFACE_DISTANCE = 2.58 # in Angstrom -- from manuscript -INTERFACE_VACUUM = 20.0 # in Angstrom -- from manuscript +# Additional fine-tuning parameters (increase values to get more strained matches): +MAX_AREA_TOLERANCE = 0.09 # in Angstrom^2 +MAX_LENGTH_TOLERANCE = 0.05 +MAX_ANGLE_TOLERANCE = 0.02 + +# Whether to reduce the resulting interface cell to the primitive cell after the interface creation. +# If the reduction causes unexpected results, try increasing the `MAX_AREA` for search. +REDUCE_RESULT_CELL_TO_PRIMITIVE = True ``` ![Notebook Setup](../../../images/tutorials/materials/interfaces/interface_2d_3d_graphene_silicon_dioxide/2-jl-setup-notebook.webp "Notebook Setup") @@ -98,14 +112,14 @@ Run the notebook to generate the interface structure between graphene and silico ![Run All](../../../images/jupyterlite/run-all.webp "Run All") -### 2.4. View Results. +### 3.4. View Results The generation might take some time. After that, the user can pass the material to the Materials Designer for further analysis. ![Gr/SiO2 Interface](../../../images/tutorials/materials/interfaces/interface_2d_3d_graphene_silicon_dioxide/3-jl-result-preview.webp "Gr/SiO2 Interface") -## 3. Pass the Material to Materials Designer. +## 4. Pass the Material to Materials Designer After generating the interface structure, pass the material to the Materials Designer for further analysis. @@ -113,7 +127,7 @@ The interface between graphene and silicon dioxide with oxygen termination is sh ![Gr/SiO2 Interface](../../../images/tutorials/materials/interfaces/interface_2d_3d_graphene_silicon_dioxide/4-wave-result-material.webp "Gr/SiO2 Interface") -## Interactive JupyterLite Notebook. +## 5. Interactive JupyterLite Notebook The interactive JupyterLite notebook for creating interfaces between graphene and silicon dioxide is embedded below. To run the notebook, click on the "Run All" button. @@ -121,10 +135,10 @@ The interactive JupyterLite notebook for creating interfaces between graphene an {% with origin_url=config.extra.jupyterlite.origin_url %} {% with notebooks_path_root=config.extra.jupyterlite.notebooks_path_root %} -{% with notebook_name='specific_examples/interface_3d_2d_graphene_silicon_dioxide.ipynb' %} +{% with notebook_name='specific_examples/interface_2d_3d_graphene_silicon_dioxide.ipynb' %} {% include 'jupyterlite_embed.html' %} {% endwith %} {% endwith %} {% endwith %} -## References. +## 6. References diff --git a/lang/en/docs/tutorials/materials/specific/interface-3d-3d-copper-silicon-dioxide.md b/lang/en/docs/tutorials/materials/specific/interface-3d-3d-copper-silicon-dioxide.md index 75723837e..786b71e58 100644 --- a/lang/en/docs/tutorials/materials/specific/interface-3d-3d-copper-silicon-dioxide.md +++ b/lang/en/docs/tutorials/materials/specific/interface-3d-3d-copper-silicon-dioxide.md @@ -7,6 +7,7 @@ tags: - termination - SiO2 - Cu + - C-2D-INT-Z hide: - tags @@ -16,7 +17,7 @@ render_macros: true # Interfaces between 3D Materials: Copper and SiO2 (Cristobalite). -## Introduction. +## 1. Introduction This tutorial demonstrates the process of creating interfaces between 3D materials, specifically copper (Cu) and cristobalite (SiO2), based on the work presented in the following manuscript, where the electronic properties of Cu-SiO2 interfaces are studied. @@ -26,30 +27,30 @@ This tutorial demonstrates the process of creating interfaces between 3D materia Physical Review B, 83(11). [DOI: 10.1103/PhysRevB.83.115327](https://doi.org/10.1103/PhysRevB.83.115327) [@Shan2011]. -We use the [Materials Designer](../../../materials-designer/overview.md) to create interfaces between Cu and Cristobalite with different termination pairs. +We use the [Materials Designer]({{ interface_url }}/materials-designer/overview/) to create interfaces between Cu and Cristobalite with different termination pairs. The FIG. 1. shows the interfaces with different terminations between Cu and Cristobalite. ![Copper on Cristobalite](../../../images/tutorials/materials/interfaces/interface_3d_3d_copper_cristobalite/0-figure-from-manuscript.webp "Copper on Cristobalite, FIG. 1") -## 1. Load and Preview Materials. +## 2. Load and Preview Materials -Navigate to [Materials Designer](../../../materials-designer/overview.md) and import copper and cristobalite materials from the [Standata](../../../materials-designer/header-menu/input-output/standata-import.md). +Navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and import copper and cristobalite materials from the [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/). -Then use the [JupyterLite](../../../jupyterlite/overview.md) environment to create the target structures. +Then use the [JupyterLite]({{ interface_url }}/jupyterlite/overview/) environment to create the target structures. -## 2. Create Interface Between Copper and Cristobalite. +## 3. Create Interface Between Copper and Cristobalite -### 2.1 Launch JupyterLite Session. +### 2.1 Launch JupyterLite Session -Select the "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" menu item to launch the JupyterLite environment. +Select the "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" menu item to launch the JupyterLite environment. ![JupyterLite Dialog](../../../images/jupyterlite/md-advanced-jl.webp "JupyterLite Dialog") -### 2.2 Open and Modify the Notebook. +### 2.2 Open and Modify the Notebook Select the input materials with the first being the substrate (SiO₂) and the second being the film (Cu). @@ -74,35 +75,48 @@ IS_TERMINATIONS_SELECTION_INTERACTIVE = False FILM_INDEX = 1 # Index in the list of materials, to access as materials[FILM_INDEX] FILM_MILLER_INDICES = (0, 0, 1) FILM_THICKNESS = 3 # in atomic layers +FILM_TERMINATION_FORMULA = None # if None, the first termination will be used FILM_VACUUM = 0.0 # in angstroms FILM_XY_SUPERCELL_MATRIX = [[1, 0], [0, 1]] -FILM_USE_ORTHOGONAL_Z = True +FILM_USE_ORTHOGONAL_C = True SUBSTRATE_INDEX = 0 SUBSTRATE_MILLER_INDICES = (0, 0, 1) SUBSTRATE_THICKNESS = 3 # in atomic layers +SUBSTRATE_TERMINATION_FORMULA = None # if None, the first termination will be used SUBSTRATE_VACUUM = 0.0 # in angstroms SUBSTRATE_XY_SUPERCELL_MATRIX = [[1, 0], [0, 1]] -SUBSTRATE_USE_ORTHOGONAL_Z = True +SUBSTRATE_USE_ORTHOGONAL_C = True -# Maximum area for the superlattice search algorithm +INTERFACE_DISTANCE = 2.4 # Gap between substrate and film, in Angstrom +INTERFACE_VACUUM = 18.0 # Vacuum over film, in Angstrom + +# Whether to convert materials to conventional cells before creating slabs. +# To create interfaces with smaller cells, set this flag to False. (and pass already conventional cells as input) +USE_CONVENTIONAL_CELL = True + +# Maximum area for the superlattice search algorithm (the final interface area will be smaller) MAX_AREA = 150 # in Angstrom^2 -# Set the termination pair indices -TERMINATION_PAIR_INDEX = 0 -INTERFACE_DISTANCE = 2.4 # in Angstrom -INTERFACE_VACUUM = 18.0 # in Angstrom +# Additional fine-tuning parameters (increase values to get more strained matches): +MAX_AREA_TOLERANCE = 0.09 # in Angstrom^2 +MAX_LENGTH_TOLERANCE = 0.05 +MAX_ANGLE_TOLERANCE = 0.02 + +# Whether to reduce the resulting interface cell to the primitive cell after the interface creation. +# If the reduction causes unexpected results, try increasing the `MAX_AREA` for search. +REDUCE_RESULT_CELL_TO_PRIMITIVE = True ``` ![Notebook setup](../../../images/tutorials/materials/interfaces/interface_3d_3d_copper_cristobalite/1-jl-setup-notebook.webp "Notebook setup") -### 2.3. Run the Notebook. +### 3.3. Run the Notebook After setting the parameters, run the notebook to create the interface between Cu and SiO₂. ![Run All](../../../images/jupyterlite/run-all.webp "Run All") -### 2.4. View Results. +### 3.4. View Results The generation might take some time. After that, the user can pass the material to the Materials Designer for further analysis. @@ -112,22 +126,22 @@ Interface between Copper and Cristobalite with the specified parameters is shown ![Cu/SiO2 Interface](../../../images/tutorials/materials/interfaces/interface_3d_3d_copper_cristobalite/2-jl-result-preview.webp "Cu/SiO2 Interface") -## 3. Pass the Material to Materials Designer. +## 4. Pass the Material to Materials Designer The user can pass the material with the interface in the current Materials Designer environment and save it. ![Final Material](../../../images/tutorials/materials/interfaces/interface_3d_3d_copper_cristobalite/3-wave-result.webp "Cu/SiO2 Interface") -Or the user can [save or download](../../../materials-designer/header-menu/input-output.md) the material in Material JSON format or POSCAR format. +Or the user can [save or download]({{ interface_url }}/materials-designer/header-menu/input-output/) the material in Material JSON format or POSCAR format. -## 4. Create Interfaces with other Terminations. +## 5. Create Interfaces with other Terminations To create interfaces with other terminations, repeat the steps 1 - 4 and change the `TERMINATION_PAIR_INDEX` parameter to `1` to get the interface with `Cu/O` termination. Or use the interactive selection of terminations by setting `IS_TERMINATIONS_SELECTION_INTERACTIVE = True`, rerunning the notebook, and selecting the desired termination from the list. -## Interactive JupyterLite Notebook. +## 6. Interactive JupyterLite Notebook The interactive JupyterLite notebook for creating interfaces between Copper and Cristobalite is embedded below. To run the notebook, click on the "Run All" button. @@ -140,4 +154,4 @@ The interactive JupyterLite notebook for creating interfaces between Copper and {% endwith %} {% endwith %} -## References. +## 7. References diff --git a/lang/en/docs/tutorials/materials/specific/interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide-simulation.md b/lang/en/docs/tutorials/materials/specific/interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide-simulation.md new file mode 100644 index 000000000..38c53e2f2 --- /dev/null +++ b/lang/en/docs/tutorials/materials/specific/interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide-simulation.md @@ -0,0 +1,278 @@ +--- +tags: + - 2d-materials + - layers + - bilayer + - twisted + - commensurate + - molybdenum + - disulfide + - band-structure + - band-gap + - interlayer-coupling + - C-2D-INT-C + +hide: + - tags +# YAML header +render_macros: true +--- + +# Twisted Bilayer MoS2 Band Structure + +## 1. Introduction + +This tutorial calculates the electronic band structure and the band gaps of the twisted bilayer +molybdenum disulfide (MoS2) structures created in the +[structure creation tutorial](interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide.md), +reproducing the electronic-structure result of the following manuscript. + +!!!note "Manuscript" + **Kaihui Liu, Liming Zhang, Ting Cao, Chenhao Jin, Diana Qiu, Qin Zhou, Alex Zettl, Peidong Yang, Steve G. Louie & Feng Wang**, + "Evolution of interlayer coupling in twisted molybdenum disulfide bilayers" Nature Communications volume 5, Article number: 4966 (2014) + [DOI: 10.1038/ncomms5966](https://doi.org/10.1038/ncomms5966) [@Liu2014] + +![Twisted Bilayer Molybdenum Disulfide](../../../images/tutorials/materials/interfaces/twisted-bilayer-molybdenum-disulfide/MoS2-twisted-bilayers.png "Twisted Bilayer Molybdenum Disulfide") + +### 1.1. What the manuscript found + +A MoS2 bilayer has an indirect bandgap, between a valence maximum at Γ and a conduction minimum at +or near K. Both of those states are built from orbitals that stick out of the layer, so the +size of the indirect gap measures how strongly the two layers are coupled; the K-valley states are +confined within a layer and barely notice it. + +The manuscript's result is that this coupling is set by the interlayer **distance** and nothing +else: + +* registered AA and AB stacking lets the two layers sit close together, and the indirect gap is + markedly smaller there; +* every intermediate twist angle forces them apart by roughly the same amount — the sulfur atoms of + the two layers can no longer interleave — and every twisted configuration lands on the same, + larger indirect gap; +* the K-valley direct gap moves by around 0.02 eV across the entire range; +* horizontal alignment plays no part beyond setting the distance. Two bilayers at the same + interlayer distance have the same indirect gap whether they are twisted or registered. + +So the mechanism is steric rather than electronic: twisting changes the gap by changing how far +apart the layers can sit. + +### 1.2. Theory and experiment are different numbers + +The manuscript reports photoluminescence peaks as well as calculated gaps, and these are not the +same quantity. Photoluminescence measures optical transition energies, which include the binding +energy of the exciton; a DFT calculation produces Kohn-Sham eigenvalue differences, which do not. +The manuscript makes the point itself: the Kohn-Sham bandgaps should not be compared directly with +the measured optical bandgaps, but the trend with twist angle should be correct. + +This tutorial reproduces the trend, not the photoluminescence peaks. + + +## 2. Prerequisites + +Run the +[structure creation tutorial](interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide.md) +first. Its notebook saves each structure it builds into the `uploads` folder under a name such as +`MoS2 bilayer 21.8deg d6.5`, and this notebook loads them back by exactly those names. A name that +does not resolve stops the notebook rather than silently substituting a different material. + + +## 3. What is calculated + +One job per structure, all with the same settings, so the results can be compared with each other. +The structure notebook builds the manuscript's configurations: + +| structure | twist | d(Mo–Mo) | atoms | +|---|---|---|---| +| `MoS2 bilayer 21.8deg d6.5` | 21.8° | 6.5 Å | 42 | +| `MoS2 bilayer AB1 d6.1` | 60° | 6.1 Å | 6 | +| `MoS2 bilayer AB1 d6.5` | 60° | 6.5 Å | 6 | +| `MoS2 bilayer AA3 d6.8` | 0° | 6.8 Å | 6 | +| `MoS2 bilayer 13.2deg d6.5` | 13.2° | 6.5 Å | 114 | +| `MoS2 bilayer 38.2deg d6.5` | 38.2° | 6.5 Å | 42 | +| `MoS2 bilayer 46.8deg d6.5` | 46.8° | 6.5 Å | 114 | + +`MoS2 bilayer AB1 d6.5` is not one of the manuscript's own configurations — it is the registered +stacking held at the twisted structures' interlayer distance, which separates the effect of the +distance from the effect of the horizontal alignment. + +The simulation notebook computes the first entry by default; uncomment the others to add them. The +114-atom cells are considerably more expensive than the rest. + +### 3.1. Interlayer distances are inputs here, not outputs + +The distances above are the manuscript's Table S1 LDA values — the relaxed results of its own +calculations. This tutorial builds the structures at those distances and does not relax them. + +The structure notebook prints the Mo–Mo separation of each finished structure next to the value it +was aiming for, along with the cell height, so the geometry can be checked against the manuscript at +a glance. + +### 3.2. Which registry a 0° or 60° stack comes out as + +Registered stacking is not a single structure. The manuscript distinguishes sulfur over molybdenum +(AA1, AB1), sulfur over the centre of a hexagon (AA2, AB2) and sulfur over sulfur (AA3, AB3), and +Table S1 gives each a different interlayer distance — 6.1 Å, 6.2 Å and 6.8 Å respectively, the +eclipsed S-over-S stacking being pushed furthest apart. + +The structure builder has no registry parameter: it returns whatever the commensurate lattice search +produces. The structure notebook therefore classifies each registered stack it builds from the +in-plane offset between the facing sulfur planes and prints the answer. With the current builder, 0° +produces AA3 and 60° produces AB1, which is why the 60° structure is the registered member of the +comparison — it is the compact stacking the manuscript's headline sentence is about. + + +## 4. Calculation parameters + +The manuscript used DFT in the local density approximation with norm-conserving pseudopotentials, a +plane-wave cutoff of 140 Ry, 20 Å between periodic images along the out-of-plane direction, and no +spin-orbit coupling. + +| | this tutorial | manuscript | +|---|---|---| +| Functional | LDA (`pz`) | LDA | +| Pseudopotentials | ultrasoft (GBRV) | norm-conserving | +| Wavefunction cutoff | 40 Ry, density 320 Ry | 140 Ry | +| Out-of-plane cell | 20 Å | 20 Å | +| Spin-orbit coupling | off | off | +| Spin polarization | off | not applicable | +| Geometry | interlayer distances from Table S1 | relaxed | + +The pseudopotentials are the one real divergence, and it is forced: the platform carries no +norm-conserving set for Mo or S under LDA, so the closest available match is the ultrasoft GBRV set +at the same functional. Keeping the functional is what matters — LDA is what binds this bilayer. + +The two cutoffs are not the same quantity. 140 Ry is a norm-conserving *wavefunction* cutoff; +ultrasoft pseudopotentials converge the wavefunctions far lower and instead need a charge-density +cutoff eight to twelve times higher, which is the 320 Ry here. + +Expect absolute gaps roughly 0.2 eV below the manuscript's as a result. Differences between +structures computed with identical settings are much less affected, and those carry the result. + +### 4.1. K-point sampling and cell size + +The k-grid is set per structure, alongside its name: + +```python +MATERIALS = { + "MoS2 bilayer 21.8deg d6.5": [6, 6, 1], + # "MoS2 bilayer AB1 d6.1": [12, 12, 1], + ... +} +``` + +The manuscript does not state its k-sampling. A commensurate supercell has a Brillouin zone smaller +by its cell count, so it needs fewer divisions than the 1×1 cell for equivalent sampling — hence +`[6, 6, 1]` for the √7×√7 cell against `[12, 12, 1]` for the 1×1. + +Keep the in-plane divisions a multiple of three. K sits at (1/3, 1/3), so a Γ-centred grid whose +divisions are not divisible by three never samples it, and the K-valley gap is then read at some +other k-point. + +### 4.2. The band structure path belongs to the cell being computed + +The path is Γ–M–K–Γ of whichever cell is being calculated. In a supercell the bands are folded onto +a smaller Brillouin zone, so the point labelled K in the 42-atom plot is not the K point of the +monolayer. The plots are for reading; the numbers the comparison uses come from the `band_gaps` +property, which is extracted from the non-self-consistent k-mesh and is unaffected by folding. + + +## 5. Step-by-step instructions + +### 5.1. Create the structures + +Run the +[structure creation notebook](interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide.md). +Its `INTERFACE_PARAMETERS` list has the three structures compared here active by default — +building a structure costs seconds, so there is no reason to build fewer. Uncomment further entries +for the remaining twist angles. + +### 5.2. Open the simulation notebook + +``` +other/materials_designer/specific_examples/interface_bilayer_twisted_commensurate_lattices_molybdenum_disulfide_SIMULATION.ipynb +``` + +### 5.3. Select the materials + +Cell 1.2 holds the structures to compute and the k-grid for each: + +```python +MATERIALS = { + "MoS2 bilayer 21.8deg d6.5": [6, 6, 1], + # "MoS2 bilayer AB1 d6.1": [12, 12, 1], + # "MoS2 bilayer AB1 d6.5": [12, 12, 1], + ... +} +``` + +One job is created per entry. Uncomment the two AB1 entries to run the full comparison. + +### 5.4. Run the notebook + +Select *Run* > *Run All*. The notebook will +[authenticate with the platform]({{ interface_url }}/jupyterlite/authentication.md), load and save +the materials, build one workflow per material, create and submit one job each, wait for them, and +then print the results. + +The 42-atom job dominates the cost. Raising `PPN` or moving to a larger queue is the sensible lever. +Shrinking the cell is the other one, but there is little room: `TOTAL_CELL_HEIGHT` is already at the +manuscript's 20 Å, which leaves about 11 Å of vacuum above a bilayer roughly 9 Å thick. Going lower +departs from the manuscript, and whatever value is used has to be the same for every job in the +comparison. + + +## 6. Expected results + +### 6.1. Gaps against twist angle + +Each structure produces one row, and the notebook plots the indirect and K-valley direct gaps +against twist angle — the same axes as Fig. 4b of the manuscript. Alongside each row it shows the +manuscript's own value, read off that figure: about 1.27 eV for the registered AB stacking, 1.47 eV +for every twist, 1.60 eV for the eclipsed AA stacking, and a K-valley gap near 1.80 eV throughout. + +Absolute gaps come out roughly 0.2 eV below the manuscript's, because the pseudopotentials are not +its norm-conserving set. Differences between structures computed with identical settings are much +less affected, and those are what carry the manuscript's claim. + +Measured on two structures that differ only in interlayer distance: + +| structure | d(Mo–Mo) | indirect | direct (K) | +|---|---|---|---| +| `MoS2 bilayer AB1 d6.1` | 6.1 Å | 1.098 eV | 1.612 eV | +| `MoS2 bilayer AB1 d6.5` | 6.5 Å | 1.297 eV | 1.624 eV | + +The indirect gap shifts **+0.199 eV** over that 0.4 Å, against **+0.20 eV** in Fig. 4c, while the +K-valley gap moves 0.012 eV — the manuscript's result, that the indirect gap tracks the interlayer +distance and the K-valley gap does not. + +### 6.2. Band structure + +Each job produces a band structure along Γ–M–K–Γ of its own cell. A supercell's bands are folded +onto its smaller Brillouin zone, so it carries proportionally more bands over a smaller range — the +same electronic structure, drawn differently. + +## 7. Troubleshooting + +The comparison at the same interlayer distance is the one sensitive to k-point sampling, because it +is the only one between cells of different size. If it disagrees while the others hold, check that +the supercell's grid is scaled down relative to the 1×1 cell's as described in 4.1. + +If every gap is far from 1.5 eV, check the interlayer distance printed for each material against the +value in its name before looking anywhere else. + + +## 8. Interactive JupyterLite notebook + +The notebook below calculates the band structures and evaluates the comparison. Select +*Run* > *Run All Cells*. + +{% with origin_url=config.extra.jupyterlite.origin_url_lab %} +{% with notebooks_path_root=config.extra.jupyterlite.notebooks_path_root %} +{% with notebook_name='specific_examples/interface_bilayer_twisted_commensurate_lattices_molybdenum_disulfide_SIMULATION.ipynb' %} +{% include 'jupyterlite_embed.html' %} +{% endwith %} +{% endwith %} +{% endwith %} + + +## 9. References diff --git a/lang/en/docs/tutorials/materials/specific/interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide.md b/lang/en/docs/tutorials/materials/specific/interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide.md index 6836d6680..56a23b9f3 100644 --- a/lang/en/docs/tutorials/materials/specific/interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide.md +++ b/lang/en/docs/tutorials/materials/specific/interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide.md @@ -7,6 +7,7 @@ tags: - commensurate - molybdenum - disulfide + - C-2D-INT-C hide: - tags @@ -16,7 +17,7 @@ render_macros: true # Twisted Bilayer Molybdenum Disulfide Structure Creation. -## Introduction. +## 1. Introduction This tutorial demonstrates the process of creating a twisted bilayer molybdenum disulfide (MoS2) structure based on the work presented in the following manuscript. @@ -26,49 +27,69 @@ This tutorial demonstrates the process of creating a twisted bilayer molybdenum [DOI: 10.1038/ncomms5966](https://doi.org/10.1038/ncomms5966) [@Liu2014; @Zhang2016; @Cao2018] -We use the [Materials Designer](../../../materials-designer/overview.md) to create molybdenum disulfide bilayer structure configurations with multiple twist angles. +We use the [Materials Designer]({{ interface_url }}/materials-designer/overview/) to create molybdenum disulfide bilayer structure configurations with multiple twist angles. The Figure 4 shows the twisted bilayer MoS2 configurations. ![Twisted Bilayer Molybdenum Disulfide](../../../images/tutorials/materials/interfaces/twisted-bilayer-molybdenum-disulfide/MoS2-twisted-bilayers.png "Twisted Bilayer Molybdenum Disulfide") -## 1. Load and preview MoS2 structure. +## 2. Load and preview MoS2 structure -First, we navigate to [Materials Designer](../../../materials-designer/overview.md) and import the MoS2 material from the [Standata](../../../materials-designer/header-menu/input-output/standata-import.md). +First, we navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and import the MoS2 material from the [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/). ![Standata MoS2 Import](../../../images/tutorials/materials/interfaces/twisted-bilayer-molybdenum-disulfide/standata-import-mos2.png "Standata MoS2 Import") -Then we will use the [JupyterLite](../../../jupyterlite/overview.md) environment to create a twisted bilayer molybdenum disulfide structure. +Then we will use the [JupyterLite]({{ interface_url }}/jupyterlite/overview/) environment to create a twisted bilayer molybdenum disulfide structure. -## 2. Create MoS2 bilayer with a twist angle of 22 degrees. +## 3. Create the MoS2 bilayers -### 2.1 Launch JupyterLite Session. +### 3.1. Launch JupyterLite Session -Select the "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" menu item to launch the JupyterLite environment. +Select the "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" menu item to launch the JupyterLite environment. ![JupyterLite Dialog](../../../images/jupyterlite/md-advanced-jl.webp "JupyterLite Dialog") -### 2.2. Open and modify the notebook. +### 3.2. Open and modify the notebook -Next, edit `create_twisted_interface_with_commnesurate_lattices.ipynb` notebook to modify the parameters by adding: `TARGET_TWIST_ANGLE = 22` and `INTERFACE_DISTANCE = 6.5` -- found in the publication description. +Open `specific_examples/interface_bilayer_twisted_commensurate_lattices_molybdenum_disulfide.ipynb` +— the notebook embedded in section 5 below. -Adjust the "1.1. Set up slab parameters" cell in the notebook according to: +The first cell lists the configurations to build. Each entry is a name, a twist angle, and an +interlayer separation; the notebook builds every active entry in one run, so there is no need to +edit and re-run once per angle: ```python -# Material selection and basic parameters -FILM_INDEX = 0 # Index in the list of materials, to access as materials[FILM_INDEX] -SUBSTRATE_INDEX = None # Can be None to use same material as film +INTERFACE_PARAMETERS = [ + {"name": "MoS2 bilayer 21.8deg d6.5", "angle": 21.8, "d_mo_mo": 6.5}, + {"name": "MoS2 bilayer AB1 d6.1", "angle": 60.0, "d_mo_mo": 6.1}, + {"name": "MoS2 bilayer AB1 d6.5", "angle": 60.0, "d_mo_mo": 6.5}, + # {"name": "MoS2 bilayer AA3 d6.8", "angle": 0.0, "d_mo_mo": 6.8}, + # {"name": "MoS2 bilayer 13.2deg d6.5", "angle": 13.2, "d_mo_mo": 6.5}, + # {"name": "MoS2 bilayer 38.2deg d6.5", "angle": 38.2, "d_mo_mo": 6.5}, + # {"name": "MoS2 bilayer 46.8deg d6.5", "angle": 46.8, "d_mo_mo": 6.5}, +] +``` + +!!!note "`d_mo_mo` is the Mo–Mo separation, not a gap" + Table S1 of the manuscript tabulates the **averaged Mo–Mo separation** of the two layers, and + `d_mo_mo` is that quantity. The notebook subtracts the monolayer thickness itself to get the gap + the builder needs. Passing 6.5 Å straight through as a gap would put the layers roughly 3 Å + further apart than the manuscript, which is enough to change the indirect gap substantially. + +The second cell holds the cell and search parameters: -# Twisted interface parameters -TARGET_TWIST_ANGLE = 22.0 # in degrees -INTERFACE_DISTANCE = 6.5 # in Angstroms -INTERFACE_VACUUM = 20.0 # in Angstroms +```python +# Slab creation parameters +MILLER_INDICES = (0, 0, 1) # Miller indices for slab creation +NUMBER_OF_LAYERS = 1 # Number of layers in the slab + +TOTAL_CELL_HEIGHT = 20.0 # out-of-plane cell dimension in Angstroms, as in the article # Search algorithm parameters -MAX_REPETITION = 6 # Maximum supercell matrix element value +MAX_REPETITION = None # Maximum supercell matrix element value (None for automatic) ANGLE_TOLERANCE = 0.5 # in degrees RETURN_FIRST_MATCH = True # If True, returns first solution within tolerance @@ -77,69 +98,74 @@ SHOW_INTERMEDIATE_STEPS = True VISUALIZE_REPETITIONS = [3, 3, 1] ``` +`TOTAL_CELL_HEIGHT` is the **total** out-of-plane cell dimension, matching the 20 Å the manuscript +used to separate the bilayer from its periodic images. The notebook derives the vacuum from it, so +the built cell comes out at 20 Å regardless of which interlayer separation is requested. + ![Notebook setup](../../../images/tutorials/materials/interfaces/twisted-bilayer-molybdenum-disulfide/jl-set-nb.png "Notebook setup") -### 2.3. Run the Notebook. +### 3.3. Run the Notebook -After setting the parameters, run the notebook to create the twisted bilayer molybdenum disulfide structure. +After setting the parameters, run the notebook to build every active configuration. ![Run All](../../../images/jupyterlite/run-all.webp "Run All") -### 2.4. View Results and pass to Materials Designer. +### 3.4. Check the geometry -The generation might take some time. -After that, the user can pass the material to the Materials Designer for further analysis. +For each structure the notebook prints the atom count, the achieved Mo–Mo separation next to the +value that was asked for, the cell height, and — for the registered stacks at 0° and 60° — which +stacking registry the search actually produced: -The interface for 22 degrees twist is shown below. - -![Result Material, 22 degrees](../../../images/tutorials/materials/interfaces/twisted-bilayer-molybdenum-disulfide/mos2-result-wavejs-22.png "MoS2 Twisted Bilayer, 22 degrees") +``` +MoS2 bilayer 21.8deg d6.5: 21.8°, 42 atoms, d(Mo-Mo) 6.500 Å (target 6.5 Å), cell c 20.00 Å +MoS2 bilayer AB1 d6.1: 60.0°, 6 atoms, d(Mo-Mo) 6.100 Å (target 6.1 Å), cell c 20.00 Å, AA1/AB1 (S over Mo) +``` -## 3. Create bilayers with other twist angles. +The registry matters because Table S1 gives a different interlayer distance to each one: 6.1–6.2 Å +for the AA1/AB1 and AA2/AB2 stacks, 6.8 Å for AA3/AB3 where sulfur sits directly over sulfur. -### 3.1. Repeat the steps above. -To create a twisted bilayer MoS2 structure with a different twist angle, repeat the steps above, adjusting the `TARGET_TWIST_ANGLE` and `INTERFACE_DISTANCE` parameters accordingly. +### 3.5. View results and pass to Materials Designer -Values for angle and associated interlayer separation provided below come from the description of Figure 4 in the publication, below each example has an image of the resulting material. +The generation might take some time. Each finished structure is saved to the `uploads` folder under +its `name`, and can also be passed to the Materials Designer for further analysis. -```python -TARGET_TWIST_ANGLE = 0.0 -INTERFACE_DISTANCE = 6.8 -``` +The interface for the 21.8° twist is shown below. -![Result Material, 0 degrees](../../../images/tutorials/materials/interfaces/twisted-bilayer-molybdenum-disulfide/mos2-result-wavejs-0.png "MoS2 Twisted Bilayer, 0 degrees") +![Result Material, 22 degrees](../../../images/tutorials/materials/interfaces/twisted-bilayer-molybdenum-disulfide/mos2-result-wavejs-22.png "MoS2 Twisted Bilayer, 21.8 degrees") +## 4. The other twist angles -```python -TARGET_TWIST_ANGLE = 13.0 -INTERFACE_DISTANCE = 6.5 -``` +The remaining configurations are already in `INTERFACE_PARAMETERS`, commented out. Uncomment the +ones needed and re-run; the separations come from Table S1 of the manuscript. -![Result Material, 13 degrees](../../../images/tutorials/materials/interfaces/twisted-bilayer-molybdenum-disulfide/mos2-result-wavejs-13.png "MoS2 Twisted Bilayer, 13 degrees") +| Entry | Angle | `d_mo_mo` | Atoms | +|---|---|---|---| +| `MoS2 bilayer AA3 d6.8` | 0° | 6.8 Å | 6 | +| `MoS2 bilayer 13.2deg d6.5` | 13.2° | 6.5 Å | 114 | +| `MoS2 bilayer 21.8deg d6.5` | 21.8° | 6.5 Å | 42 | +| `MoS2 bilayer 38.2deg d6.5` | 38.2° | 6.5 Å | 42 | +| `MoS2 bilayer 46.8deg d6.5` | 46.8° | 6.5 Å | 114 | +| `MoS2 bilayer AB1 d6.1` | 60° | 6.1 Å | 6 | -```python -TARGET_TWIST_ANGLE = 38.0 -INTERFACE_DISTANCE = 6.5 -``` +The 13.2° and 46.8° cells hold 114 atoms and take noticeably longer to build than the rest. -![Result Material, 38 degrees](../../../images/tutorials/materials/interfaces/twisted-bilayer-molybdenum-disulfide/mos2-result-wavejs-38.png "MoS2 Twisted Bilayer, 38 degrees") +![Result Material, 0 degrees](../../../images/tutorials/materials/interfaces/twisted-bilayer-molybdenum-disulfide/mos2-result-wavejs-0.png "MoS2 Twisted Bilayer, 0 degrees") -```python -TARGET_TWIST_ANGLE = 47.0 -INTERFACE_DISTANCE = 6.5 -``` +![Result Material, 13 degrees](../../../images/tutorials/materials/interfaces/twisted-bilayer-molybdenum-disulfide/mos2-result-wavejs-13.png "MoS2 Twisted Bilayer, 13.2 degrees") -![Result Material, 47 degrees](../../../images/tutorials/materials/interfaces/twisted-bilayer-molybdenum-disulfide/mos2-result-wavejs-47.png "MoS2 Twisted Bilayer, 47 degrees") +![Result Material, 38 degrees](../../../images/tutorials/materials/interfaces/twisted-bilayer-molybdenum-disulfide/mos2-result-wavejs-38.png "MoS2 Twisted Bilayer, 38.2 degrees") -```python -TARGET_TWIST_ANGLE = 60.0 -INTERFACE_DISTANCE = 6.2 -``` +![Result Material, 47 degrees](../../../images/tutorials/materials/interfaces/twisted-bilayer-molybdenum-disulfide/mos2-result-wavejs-47.png "MoS2 Twisted Bilayer, 46.8 degrees") ![Result Material, 60 degrees](../../../images/tutorials/materials/interfaces/twisted-bilayer-molybdenum-disulfide/mos2-result-wavejs-60.png "MoS2 Twisted Bilayer, 60 degrees") +Once the structures exist, the +[band structure tutorial](interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide-simulation.md) +loads them by name and reproduces the manuscript's band gaps. + -## Interactive JupyterLite Notebook. +## 5. Interactive JupyterLite Notebook The interactive JupyterLite notebook for creating twisted bilayer MoS2 structures can be accessed below. To run the notebook, click on the "Run All" button. @@ -152,4 +178,4 @@ The interactive JupyterLite notebook for creating twisted bilayer MoS2 structure {% endwith %} {% endwith %} -## References. +## 6. References diff --git a/lang/en/docs/tutorials/materials/specific/interface-bilayer-twisted-nanoribbons-boron-nitride.md b/lang/en/docs/tutorials/materials/specific/interface-bilayer-twisted-nanoribbons-boron-nitride.md index 1e6d94e5c..c1b2e10b5 100644 --- a/lang/en/docs/tutorials/materials/specific/interface-bilayer-twisted-nanoribbons-boron-nitride.md +++ b/lang/en/docs/tutorials/materials/specific/interface-bilayer-twisted-nanoribbons-boron-nitride.md @@ -6,6 +6,7 @@ tags: - BN - boron - nitrogen + - C-2D-INT-T hide: - tags @@ -15,7 +16,7 @@ render_macros: true # Twisted Bilayer Boron Nitride (TBBN) Structure Creation. -## Introduction. +## 1. Introduction This tutorial demonstrates the process of creating a twisted bilayer boron nitride (TBBN) structure based on the work presented in the following manuscript. @@ -25,83 +26,86 @@ This tutorial demonstrates the process of creating a twisted bilayer boron nitri [DOI: 10.1021/acs.nanolett.9b00986](https://doi.org/10.1021/acs.nanolett.9b00986) [@Xian2020] -We use the [Materials Designer](../../../materials-designer/overview.md) to create Hexagonal boron nitride bilayer structure configurations with 2 specific twist angles. +We use the [Materials Designer]({{ interface_url }}/materials-designer/overview/) to create Hexagonal boron nitride bilayer structure configurations with 2 specific twist angles. The image shows the twisted bilayer h-BN structure with a twist angle of 2.64° (a) and 62.64° (b). ![Twisted Bilayer Boron Nitride](../../../images/tutorials/materials/interfaces/twisted-bilayer-boron-nitride/tbbn-paper-image.png "Twisted Bilayer Boron Nitride") -## 1. Load and preview BN structure. +## 2. Load and preview BN structure -First, we navigate to [Materials Designer](../../../materials-designer/overview.md) and import the BN material from the [Standata](../../../materials-designer/header-menu/input-output/standata-import.md). +First, we navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and import the BN material from the [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/). ![Standata BN Import](../../../images/tutorials/materials/interfaces/twisted-bilayer-boron-nitride/standata-import-bn.png "Standata BN Import") -Then we will use the [JupyterLite](../../../jupyterlite/overview.md) environment to create a twisted bilayer boron nitride structure. +Then we will use the [JupyterLite]({{ interface_url }}/jupyterlite/overview/) environment to create a twisted bilayer boron nitride structure. -## 2. Create bilayer with a twist angle of 2.64°. +## 3. Create bilayer with a twist angle of 2.64° -### 2.1 Launch JupyterLite Session. +### 2.1 Launch JupyterLite Session -Select the "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" menu item to launch the JupyterLite environment. +Select the "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" menu item to launch the JupyterLite environment. ![JupyterLite Dialog](../../../images/jupyterlite/md-advanced-jl.webp "JupyterLite Dialog") -### 2.2. Open and modify the notebook. +### 3.2. Open and modify the notebook Next, edit `create_twisted_interface_with_nanoribbons.ipynb` notebook to modify the parameters by adding: `RIBBON_WIDTH = 50` and `RIBBON_LENGTH = 50`, `TWIST_ANGLE = 2.64`. Adjust the "1.1. Set up slab parameters" cell in the notebook according to: ```python -FILM_INDEX = 0 # Index in the list of materials, to access as materials[FILM_INDEX] +# Material selection and basic parameters +FILM_INDEX = 0 # Index in the list of materials, to access as materials[FILM_INDEX] SUBSTRATE_INDEX = None # Can be None to use same material as film -# Interface parameters -TWIST_ANGLE = 2.64 # in degrees +# Twisted interface parameters +TARGET_TWIST_ANGLE = 2.64 # in degrees INTERFACE_DISTANCE = 3.23 # in Angstroms INTERFACE_VACUUM = 20.0 # in Angstroms # Nanoribbon parameters RIBBON_WIDTH = 50 # Width of the nanoribbon in unit cells RIBBON_LENGTH = 50 # Length of the nanoribbon in unit cells -VACUUM_X = 5.0 # Vacuum along x on both sides, in Angstroms -VACUUM_Y = 5.0 # Vacuum along y on both sides, in Angstroms +VACUUM_WIDTH = 15.0 # Vacuum width around ribbons in Angstroms +VACUUM_LENGTH = 15.0 # Vacuum length around ribbons in Angstroms +VACUUM_X = 2.0 # Additional vacuum along x on both sides, in Angstroms +VACUUM_Y = 2.0 # Additional vacuum along y on both sides, in Angstroms # Visualization parameters SHOW_INTERMEDIATE_STEPS = True -VISUALIZE_REPETITIONS = [1, 1, 1] +VISUALIZE_REPETITIONS = [3, 3, 1] ``` ![Notebook setup](../../../images/tutorials/materials/interfaces/twisted-bilayer-boron-nitride/jl-set-nb.png "Notebook setup") -### 2.3. Run the Notebook. +### 3.3. Run the Notebook After setting the parameters, run the notebook with "Run" > "Run All" option to create the twisted bilayer boron nitride structure. ![Run All](../../../images/jupyterlite/run-all.webp "Run All") -### 2.4. Analyze the Results. +### 3.4. Analyze the Results After running the notebook, the user will be able to visualize the created twisted bilayer boron nitride structure. ![Review the Results](../../../images/tutorials/materials/interfaces/twisted-bilayer-boron-nitride/tbbn-result-jl.png "Review the Results") -### 2.5. Pass Results to the Materials Designer. +### 3.5. Pass Results to the Materials Designer After reviewing the results, the user can pass the material to the Materials Designer for further analysis. ![Result Material](../../../images/tutorials/materials/interfaces/twisted-bilayer-boron-nitride/tbbn-result-wavejs.png "Result Material") -## 3. Create a TBBN structure with a twist angle of 62.64°. +## 4. Create a TBBN structure with a twist angle of 62.64° -### 3.1. Repeat the steps above. +### 4.1. Repeat the steps above To create a twisted bilayer boron nitride structure with a twist angle of 62.64°, repeat the above steps 2.1 -- 2.5 with the following modifications. Set `TWIST_ANGLE = 62.64` in the "1.1. Set up slab parameters" cell in the notebook. -### 3.2. View Results and pass to the Materials Designer. +### 4.2. View Results and pass to the Materials Designer After running the notebook, the user will be able to visualize the created twisted bilayer boron nitride structure with a twist angle of 62.64°. @@ -109,7 +113,7 @@ After reviewing the results, the user can pass the material to the Materials Des ![Twisted Bilayer Boron Nitride Structure with 62.64° Twist Angle](../../../images/tutorials/materials/interfaces/twisted-bilayer-boron-nitride/tbbn-62_64.png "Twisted Bilayer Boron Nitride Structure with 62.64° Twist Angle") -## Interactive JupyterLite Notebook. +## 5. Interactive JupyterLite Notebook The interactive JupyterLite notebook for creating the twisted bilayer boron nitride structure can be accessed below. Select "Run" > "Run All Cells" to create two materials. @@ -121,5 +125,5 @@ The interactive JupyterLite notebook for creating the twisted bilayer boron nitr {% endwith %} {% endwith %} -## References. +## 6. References diff --git a/lang/en/docs/tutorials/materials/specific/nanocluster-gold.md b/lang/en/docs/tutorials/materials/specific/nanocluster-gold.md index bcc6f78c2..e77975ed5 100644 --- a/lang/en/docs/tutorials/materials/specific/nanocluster-gold.md +++ b/lang/en/docs/tutorials/materials/specific/nanocluster-gold.md @@ -5,6 +5,7 @@ tags: - nanoparticle - cuboctahedron - icosahedron + - P-0D-NPR hide: - tags @@ -14,7 +15,7 @@ render_macros: true # Gold Nanoclusters. -## Introduction. +## 1. Introduction This tutorial demonstrates the process of creating a gold nanoparticle structures based on the work presented in the following manuscript. @@ -24,28 +25,28 @@ This tutorial demonstrates the process of creating a gold nanoparticle structure > *Phys. Rev. B 84, 245429 (2011)*, > [DOI: 10.1103/PhysRevB.84.245429](https://doi.org/10.1103/PhysRevB.84.245429){:target='_blank'}. [@Larsen2011] -We use the [Materials Designer](../../../materials-designer/overview.md) to create gold nanoparticle structures of cuboctahedral and icosahedral shapes as shown in the image below. +We use the [Materials Designer]({{ interface_url }}/materials-designer/overview/) to create gold nanoparticle structures of cuboctahedral and icosahedral shapes as shown in the image below. ![Gold Nanoparticles](../../../images/tutorials/materials/0d_materials/nanocluster_gold/0-manuscript-image.webp "Fig. 2. Gold Nanoparticles") -## 1. Load and preview Gold structure. +## 2. Load and preview Gold structure -First, we navigate to [Materials Designer](../../../materials-designer/overview.md) and import the Gold material from the [Standata](../../../materials-designer/header-menu/input-output/standata-import.md). +First, we navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and import the Gold material from the [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/). ![Standata Gold Import](../../../images/tutorials/materials/0d_materials/nanocluster_gold/1-standata-import-gold.webp "Standata Gold Import") -Then we will use the [JupyterLite](../../../jupyterlite/overview.md) environment to create gold nanoparticle structures. +Then we will use the [JupyterLite]({{ interface_url }}/jupyterlite/overview/) environment to create gold nanoparticle structures. -## 2. Create cuboctahedra. +## 3. Create cuboctahedra -### 2.1 Launch JupyterLite Session. +### 2.1 Launch JupyterLite Session -Select the "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" menu item to launch the JupyterLite environment. +Select the "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" menu item to launch the JupyterLite environment. ![JupyterLite Dialog](../../../images/jupyterlite/md-advanced-jl.webp "JupyterLite Dialog") -### 2.2. Open and modify the notebook. +### 3.2. Open and modify the notebook Next, edit `create_cluster_ase.ipynb` notebook to modify the parameters by changing values: @@ -57,7 +58,9 @@ Cuboctahedron shape is achieved by setting parameters of the octahedron to be in Copy the content below and adjust the "1.1. Set up slab parameters" cell in the notebook: ```python -shape = ASENanoparticleShapesEnum.OCTAHEDRON +from mat3ra.made.tools.build.pristine_structures.zero_dimensional.nanoparticle import NanoparticleShapesEnum + +shape = NanoparticleShapesEnum.OCTAHEDRON parameters = { "length": 5, "cutoff": 2 @@ -66,13 +69,13 @@ parameters = { ![Setup for cuboctahedron cluster](../../../images/tutorials/materials/0d_materials/nanocluster_gold/2-jl-setup.webp "Setup for cuboctahedron cluster") -### 2.3. Run the notebook. +### 3.3. Run the notebook Run the notebook by selecting "Run > Run All Cells" from the menu. ![Run All](../../../images/jupyterlite/run-all.webp "Run All") -### 2.4. Analyze the Results. +### 3.4. Analyze the Results After running the notebook, the octahedral gold nanoparticle structure will be created. @@ -82,17 +85,17 @@ For better view of the solid symmetry rotation of image might be needed like `"r ![Cuboctahedron Gold Nanocluster](../../../images/tutorials/materials/0d_materials/nanocluster_gold/3-jl-result-preview.webp "Cuboctahedron Gold Nanocluster") -### 2.5. Pass the Material to the Materials Designer. +### 3.5. Pass the Material to the Materials Designer After reviewing the results, the user can pass the material to Materials Designer for further analysis. ![Final Material](../../../images/tutorials/materials/0d_materials/nanocluster_gold/4-wave-result.webp "Final Material") -Or the user can [save or download](../../../materials-designer/header-menu/input-output.md) the material in Material JSON format or POSCAR format. +Or the user can [save or download]({{ interface_url }}/materials-designer/header-menu/input-output/) the material in Material JSON format or POSCAR format. -## 3. Create clusters with other shapes and sizes. +## 4. Create clusters with other shapes and sizes -### 3.1. Repeat the steps above. +### 4.1. Repeat the steps above Repeat the steps above to create gold nanoparticle structures with other shapes and sizes. @@ -101,7 +104,7 @@ To create the rest of the structures set the `shape` and other parameters accord For Cuboctahedron with 147 atoms: ```python -shape = ASENanoparticleShapesEnum.OCTAHEDRON +shape = NanoparticleShapesEnum.OCTAHEDRON parameters = { "length": 7, "cutoff": 3 @@ -113,7 +116,7 @@ parameters = { For Cuboctahedron with 309 atoms: ```python -shape = ASENanoparticleShapesEnum.OCTAHEDRON +shape = NanoparticleShapesEnum.OCTAHEDRON parameters = { "length": 9, "cutoff": 4 @@ -155,7 +158,7 @@ parameters = { ![Icosahedron 309](../../../images/tutorials/materials/0d_materials/nanocluster_gold/jl-result-preview-icosahedron-309.webp "Icosahedron 309") -## Interactive JupiterLite Notebook. +## 5. Interactive JupiterLite Notebook The interactive JupyterLite notebook for creating Gold Nanoclusters can be accessed below. To run the notebook, click on the "Run All" button. @@ -167,4 +170,4 @@ The interactive JupyterLite notebook for creating Gold Nanoclusters can be acces {% endwith %} {% endwith %} -## References. +## 6. References diff --git a/lang/en/docs/tutorials/materials/specific/optimization-interface-film-xy-position-graphene-nickel.md b/lang/en/docs/tutorials/materials/specific/optimization-interface-film-xy-position-graphene-nickel.md index cd8e24c56..49b621505 100644 --- a/lang/en/docs/tutorials/materials/specific/optimization-interface-film-xy-position-graphene-nickel.md +++ b/lang/en/docs/tutorials/materials/specific/optimization-interface-film-xy-position-graphene-nickel.md @@ -9,6 +9,7 @@ tags: - Gr/Ni(111) - C - Ni + - C-2D-INT-Z hide: - tags @@ -18,7 +19,7 @@ render_macros: true # Graphene/Ni(111) Interface Optimization. -## Introduction. +## 1. Introduction This tutorial demonstrates how to create and optimize a Graphene/Ni(111) interface structure following the experimental observations presented in the literature. We will focus on finding the most energetically favorable position of graphene on the Ni(111) surface. @@ -32,45 +33,66 @@ We will recreate the interface structure and optimize the film position to match ![Gr/Ni Interface](../../../images/tutorials/materials/optimization/optimization_interface_film_xy_position_graphene_nickel/0-figure-from-manuscript.webp "Optimal position of graphene on Ni(111)") -## 1. Create Interface Structure. +## 2. Create Interface Structure -### 1.1. Load Base Materials. +### 2.1. Load Base Materials -Navigate to [Materials Designer](../../../materials-designer/overview.md) and import both graphene and nickel materials from the [Standata](../../../materials-designer/header-menu/input-output/standata-import.md). +Navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and import both graphene and nickel materials from the [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/). ![Import Graphene and Ni](../../../images/materials-designer/import/import_from_standata.webp "Import Gr and Ni from Standata") -### 1.2. Launch JupyterLite Session. +### 2.2. Launch JupyterLite Session -Select the "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" menu item to launch the JupyterLite environment. +Select the "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" menu item to launch the JupyterLite environment. -### 1.3. Open `create_interface_with_min_strain_zsl.ipynb` notebook. +### 2.3. Open `create_interface_with_min_strain_zsl.ipynb` notebook Find and open the `create_interface_with_min_strain_zsl.ipynb` notebook. This notebook will help us create the initial interface structure. -### 1.4. Set up interface parameters. +### 2.4. Set up interface parameters Edit the notebook parameters to create the Gr/Ni(111) interface: ```python # Material selection -SUBSTRATE_NAME = "Nickel" -FILM_NAME = "Graphene" +FILM_INDEX = 1 # Index in the list of materials, to access as materials[FILM_INDEX] +FILM_MILLER_INDICES = (0, 0, 1) +FILM_THICKNESS = 1 # in atomic layers +FILM_TERMINATION_FORMULA = None # if None, the first termination will be used +FILM_VACUUM = 0.0 # in angstroms +FILM_XY_SUPERCELL_MATRIX = [[1, 0], [0, 1]] +FILM_USE_ORTHOGONAL_C = True -# Slab parameters +SUBSTRATE_INDEX = 0 SUBSTRATE_MILLER_INDICES = (1, 1, 1) SUBSTRATE_THICKNESS = 4 # in atomic layers -FILM_THICKNESS = 1 # in atomic layers +SUBSTRATE_TERMINATION_FORMULA = None # if None, the first termination will be used +SUBSTRATE_VACUUM = 0.0 # in angstroms +SUBSTRATE_XY_SUPERCELL_MATRIX = [[1, 0], [0, 1]] +SUBSTRATE_USE_ORTHOGONAL_C = True + +INTERFACE_DISTANCE = 2.58 # Gap between substrate and film, in Angstrom +INTERFACE_VACUUM = 20.0 # Vacuum over film, in Angstrom + +# Whether to convert materials to conventional cells before creating slabs. +# To create interfaces with smaller cells, set this flag to False. (and pass already conventional cells as input) +USE_CONVENTIONAL_CELL = True -# Interface parameters +# Maximum area for the superlattice search algorithm (the final interface area will be smaller) MAX_AREA = 50 # in Angstrom^2 -INTERFACE_DISTANCE = 2.58 # in Angstrom from literature -INTERFACE_VACUUM = 20.0 # in Angstrom +# Additional fine-tuning parameters (increase values to get more strained matches): +MAX_AREA_TOLERANCE = 0.09 # in Angstrom^2 +MAX_LENGTH_TOLERANCE = 0.05 +MAX_ANGLE_TOLERANCE = 0.02 + +# Whether to reduce the resulting interface cell to the primitive cell after the interface creation. +# If the reduction causes unexpected results, try increasing the `MAX_AREA` for search. +REDUCE_RESULT_CELL_TO_PRIMITIVE = True ``` ![Interface Parameters](../../../images/tutorials/materials/optimization/optimization_interface_film_xy_position_graphene_nickel/2-jl-setup-nb-interface.webp "Interface parameters for Gr/Ni(111)") -### 1.5. Run interface creation. +### 2.5. Run interface creation Run the notebook using "Run > Run All Cells". This will: @@ -78,25 +100,27 @@ Run the notebook using "Run > Run All Cells". This will: 2. Find the optimal lattice matching using the ZSL algorithm 3. Generate the initial interface structure -## 2. Optimize Film Position. +## 3. Optimize Film Position -### 2.1. Open `optimize_film_position.ipynb` notebook. +### 3.1. Open `optimize_film_position.ipynb` notebook Find and open the `optimize_film_position.ipynb` notebook which will help us find the optimal position of the graphene layer. -### 2.2. Set optimization parameters. +### 3.2. Set optimization parameters Configure the optimization parameters: ```python +MATERIAL_INDEX = 0 # Index of the material to optimize # Grid parameters GRID_SIZE = (20, 20) # Resolution of the x-y grid -GRID_RANGE_X = (-0.5, 0.5) # Range in crystal coordinates -GRID_RANGE_Y = (-0.5, 0.5) -USE_CARTESIAN = False # Use crystal coordinates +GRID_RANGE_X = (-0.5, 0.5) # Range to search in x direction +GRID_RANGE_Y = (-0.5, 0.5) # Range to search in y direction +USE_CARTESIAN = False # Whether to use Cartesian coordinates # Visualization parameters -STRUCTURE_REPETITIONS = [3, 3, 1] +SHOW_3D_LANDSCAPE = False # Whether to show 3D energy landscape +STRUCTURE_REPETITIONS = [3, 3, 1] # Repetitions for structure visualization ``` Key parameters explained: @@ -106,7 +130,7 @@ Key parameters explained: ![Optimization Parameters](../../../images/tutorials/materials/optimization/optimization_interface_film_xy_position_graphene_nickel/3-jl-setup-nb-final.webp "Optimization parameters for Gr/Ni(111)") -### 2.3. Run optimization. +### 3.3. Run optimization Run all cells in the notebook. The optimization will: @@ -118,7 +142,7 @@ Run all cells in the notebook. The optimization will: ![Energy Heatmap](../../../images/tutorials/materials/optimization/optimization_interface_film_xy_position_graphene_nickel/5-energy-heatmap.webp "Energy heatmap of film positions") -## 3. Analyze Results. +## 4. Analyze Results Compare the original and optimized interface structures to see the difference in the graphene position. @@ -127,14 +151,14 @@ Compare the original and optimized interface structures to see the difference in ![Final Interface](../../../images/tutorials/materials/optimization/optimization_interface_film_xy_position_graphene_nickel/7-wave-result-final.webp "Optimized Gr/Ni Interface") -## 4. Save Optimized Structure. +## 5. Save Optimized Structure The optimized interface structure will be automatically passed back to Materials Designer where you can: 1. Save it in the workspace 2. Export it in various formats (JSON, POSCAR, etc.) 3. Use it for further calculations -## Interactive JupyterLite Notebook. +## 6. Interactive JupyterLite Notebook The following JupyterLite notebook demonstrates the complete process. Select "Run" > "Run All Cells". @@ -146,7 +170,7 @@ The following JupyterLite notebook demonstrates the complete process. Select "Ru {% endwith %} {% endwith %} -## Parameter Fine-tuning. +## 7. Parameter Fine-tuning To adjust the interface optimization: @@ -160,4 +184,4 @@ To adjust the interface optimization: - Adjust `GRID_RANGE` to search different areas - Enable 3D visualization with `SHOW_3D_LANDSCAPE = True` -## References. +## 8. References diff --git a/lang/en/docs/tutorials/materials/specific/overview.md b/lang/en/docs/tutorials/materials/specific/overview.md index c1c85b268..76babc542 100644 --- a/lang/en/docs/tutorials/materials/specific/overview.md +++ b/lang/en/docs/tutorials/materials/specific/overview.md @@ -1,150 +1,254 @@ # Specific Materials Examples -This document contains links to the tutorials that demonstrate how to reproduce material structures from published scientific manuscripts. Each entry lists the tutorial name and the corresponding manuscript reference. +This document provides a comprehensive catalog of materials science tutorials organized by the MCODE (Materials Categorization by Ontology, Dimensionality and Evolution) system. Each entry includes: -## 1. Single-Material Structures +- **Structure Notebook**: Creates the atomic structure from published manuscripts +- **Properties Notebook**: Calculates and reproduces key properties from the manuscript +- **DOI Reference**: Link to the original scientific publication + +## 1. Pristine Structures ### 1.1. 2D Structures -#### 1.1.1. [SrTiO3 Slab](slab-strontium-titanate.md) -[DOI: 10.1103/PhysRevB.77.195408](https://doi.org/10.1103/PhysRevB.77.195408){:target='_blank'} [@Eglitis2008; @Mukhopadhyay2006] + +#### 1.1.1. Slab + +##### 1.1.1.1. SrTiO3 Slab P-2D-SLB-S + +**Structure**: [Create SrTiO3 Slab Structure](slab-strontium-titanate.md) +**Properties**: Calculate surface energy (Coming Soon) +**DOI**: [10.1103/PhysRevB.77.195408](https://doi.org/10.1103/PhysRevB.77.195408){:target='_blank'} [@Eglitis2008; @Mukhopadhyay2006] ![Strontium Titanate Slabs](../../../images/tutorials/materials/2d_materials/slab_strontium_titanate/0-figure-from-manuscript.webp "Strontium Titanate Slabs, FIG. 2."){ style="max-height:500px;width:auto;" } ### 1.2. 0D Structures -#### 1.2.1. [Gold Nanoclusters](nanocluster-gold.md) -[DOI: 10.1103/PhysRevB.84.245429](https://doi.org/10.1103/PhysRevB.84.245429){:target='_blank'}. [@Larsen2011] + +#### 1.2.1. Nanoparticle + +##### 1.2.1.1. Gold Nanoclusters P-0D-NPR + +**Structure**: [Create Gold Nanocluster Structure](nanocluster-gold.md) +**Properties**: Calculate total energy per atom and density of states (Coming Soon) +**DOI**: [10.1103/PhysRevB.84.245429](https://doi.org/10.1103/PhysRevB.84.245429){:target='_blank'} [@Larsen2011] ![Gold Nanoparticles](../../../images/tutorials/materials/0d_materials/nanocluster_gold/0-manuscript-image.webp "Fig. 2. Gold Nanoparticles"){ style="max-height:500px;width:auto;" } +## 2. Compound Pristine Structures + +### 2.1. 2D Structures +#### 2.1.1. Interface -## 2. Multi-Material Structures +##### 2.1.1.1. Graphene/h-BN Interface C-2D-INT-Z -### 2.1. Interfaces -#### 2.1.1. [Interface between Graphene and h-BN](interface-2d-2d-graphene-boron-nitride.md) -[DOI: 10.1038/ncomms7308](https://doi.org/10.1038/ncomms7308){:target='_blank'} [@Jung2015] +**Structure**: [Create Graphene/h-BN Interface](interface-2d-2d-graphene-boron-nitride.md) +**Properties**: Calculate band structure and total energies (Coming Soon) +**DOI**: [10.1038/ncomms7308](https://doi.org/10.1038/ncomms7308){:target='_blank'} [@Jung2015] -![Graphene on Hexagonal Boron Nitride](../../../images/tutorials/materials/interfaces/interface_2d_2d_graphene_boron_nitride/0-figure-from-manuscript.webp "Graphene on Hexagonal Boron Nitride, FIG. 7"){ style="max-height:500px;width:auto;" } +![Graphene on Hexagonal Boron Nitride](../../../images/tutorials/materials/interfaces/interface_2d_2d_graphene_boron_nitride/0-figure-from-manuscript.webp "Graphene on Hexagonal Boron Nitride, FIG. 7"){ style="max-height:500px;width:auto;" } -#### 2.1.2. [Interface between Graphene and SiO2 (alpha-quartz)](interface-2d-3d-graphene-silicon-dioxide.md) -[DOI: 10.1103/PhysRevB.78.115404](https://doi.org/10.1103/PhysRevB.78.115404){:target='_blank'} +##### 2.1.1.2. Graphene/SiO2 Interface C-2D-INT-Z + +**Structure**: [Create Graphene/SiO2 Interface](interface-2d-3d-graphene-silicon-dioxide.md) +**Properties**: Calculate band structure (Coming Soon) +**DOI**: [10.1103/PhysRevB.78.115404](https://doi.org/10.1103/PhysRevB.78.115404){:target='_blank'} ![Graphene on Silicon Dioxide](../../../images/tutorials/materials/interfaces/interface_2d_3d_graphene_silicon_dioxide/0-figure-from-manuscript.webp "Graphene on Silicon Dioxide, FIG. 1(b)"){ style="max-height:500px;width:auto;" } -#### 2.1.3. [Interface between Copper and SiO2 (Cristobalite)](interface-3d-3d-copper-silicon-dioxide.md) -[DOI: 10.1103/PhysRevB.83.115327](https://doi.org/10.1103/PhysRevB.83.115327){:target='_blank'} [@Shan2011]. +##### 2.1.1.3. Copper/SiO2 Interface C-2D-INT-Z + +**Structure**: [Create Copper/Cristobalite Interface](interface-3d-3d-copper-silicon-dioxide.md) +**Properties**: Calculate band structure (Coming Soon) +**DOI**: [10.1103/PhysRevB.83.115327](https://doi.org/10.1103/PhysRevB.83.115327){:target='_blank'} [@Shan2011] + +![Copper on Cristobalite](../../../images/tutorials/materials/interfaces/interface_3d_3d_copper_cristobalite/0-figure-from-manuscript.webp "Copper on Cristobalite, FIG. 1"){ style="max-height:500px;width:auto;" } + + +##### 2.1.1.4. Graphene/Ni(111) Interface Optimization C-2D-INT-Z + +**Structure**: [Create Graphene/Ni(111) Interface](optimization-interface-film-xy-position-graphene-nickel.md) +**Properties**: Calculate total energies versus lateral shift and band structure (Coming Soon) +**DOI**: [10.1039/c3nr05279f](https://doi.org/10.1039/c3nr05279f){:target='_blank'} [@Dahal2014; @Gamo1997; @Bertoni2004] + +![Gr/Ni Interface](../../../images/tutorials/materials/optimization/optimization_interface_film_xy_position_graphene_nickel/0-figure-from-manuscript.webp "Optimal position of graphene on Ni(111)"){ style="max-height:500px;width:auto;" } -![Copper on Cristobalite](../../../images/tutorials/materials/interfaces/interface_3d_3d_copper_cristobalite/0-figure-from-manuscript.webp "Copper on Cristobalite, FIG. 1"){ style="max-height:500px;width:auto;" } -#### 2.1.4. [High-k Metal Gate Stack (Si/SiO2/HfO2/TiN)](heterostructure-silicon-silicon-dioxide-hafnium-dioxide-titanium-nitride.md) -QuantumATK tutorial: [High-k Metal Gate Stack Builder](https://docs.quantumatk.com/tutorials/hkmg_builder/hkmg_builder.html) [@Muller1999; @Robertson2006] +#### 2.1.2. Heterostack + +##### 2.1.2.1. High-k Metal Gate Stack (Si/SiO2/HfO2/TiN) C-2D-HST + +**Structure**: [Create High-k Metal Gate Stack](heterostructure-silicon-silicon-dioxide-hafnium-dioxide-titanium-nitride.md) +**Properties**: Calculate band structure and valence band offset (Coming Soon) +**Reference**: [QuantumATK Tutorial](https://docs.quantumatk.com/tutorials/hkmg_builder/hkmg_builder.html) [@Muller1999; @Robertson2006] + ![High-k Metal Gate Stack](../../../images/tutorials/materials/heterostructures/heterostructure-silicon-silicon-dioxide-hafnium-dioxide-titanium-nitride/original-figure.webp "High-k Metal Gate Stack"){ style="max-height:500px;width:auto;" } +#### 2.1.3. Interface - Twisted + +##### 2.1.3.1. Twisted Bilayer h-BN Nanoribbons C-2D-INT-T -### 2.2. Twisted Interfaces -#### 2.2.1. [Twisted Bilayer h-BN nanoribbons](interface-bilayer-twisted-nanoribbons-boron-nitride.md) -[DOI: 10.1021/acs.nanolett.9b00986](https://doi.org/10.1021/acs.nanolett.9b00986){:target='_blank'} [@Xian2020] +**Structure**: [Create Twisted h-BN Nanoribbons](interface-bilayer-twisted-nanoribbons-boron-nitride.md) +**Properties**: Calculate band structure and total energies versus twist angle (Coming Soon) +**DOI**: [10.1021/acs.nanolett.9b00986](https://doi.org/10.1021/acs.nanolett.9b00986){:target='_blank'} [@Xian2020] ![Twisted Bilayer Boron Nitride](../../../images/tutorials/materials/interfaces/twisted-bilayer-boron-nitride/tbbn-paper-image.png "Twisted Bilayer Boron Nitride"){ style="max-height:500px;width:auto;" } -#### 2.2.2. [Twisted Bilayer MoS2 commensurate lattices](interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide.md) -[DOI: 10.1038/ncomms5966](https://doi.org/10.1038/ncomms5966){:target='_blank'} [@Liu2014; @Zhang2016; @Cao2018] +#### 2.1.4. Interface - Commensurate -![Twisted Bilayer Molybdenum Disulfide](../../../images/tutorials/materials/interfaces/twisted-bilayer-molybdenum-disulfide/MoS2-twisted-bilayers.png "Twisted Bilayer Molybdenum Disulfide"){ style="max-height:500px;width:auto;" } +##### 2.1.4.1. Twisted Bilayer MoS2 Commensurate Lattices C-2D-INT-C +**Structure**: [Create Twisted MoS2 Commensurate Lattices](interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide.md) +**Properties**: [Calculate Band Structure of Twisted MoS2 Bilayers](interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide-simulation.md) +**DOI**: [10.1038/ncomms5966](https://doi.org/10.1038/ncomms5966){:target='_blank'} [@Liu2014; @Zhang2016; @Cao2018] +![Twisted Bilayer Molybdenum Disulfide](../../../images/tutorials/materials/interfaces/twisted-bilayer-molybdenum-disulfide/MoS2-twisted-bilayers.png "Twisted Bilayer Molybdenum Disulfide"){ style="max-height:500px;width:auto;" } -## 3. Defects -### 3.1. Point Defects -#### 3.1.1. [Substitutional Point Defects in Graphene](defect-point-substitution-graphene.md) -[DOI: 10.1103/PhysRevB.84.245446](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.84.245446){:target='_blank'} -![Point Defect, Substitution, 0](../../../images/tutorials/materials/defects/defect_creation_point_substitution_graphene/0-figure-from-manuscript.webp "Point Defect, Substitution, FIG. 1."){ style="max-height:500px;width:auto;" } +## 3. Defective Structures -#### 3.1.2. [Vacancy-Substitution Pair Defects in GaN](defect-point-pair-gallium-nitride.md) -[DOI: 10.1103/PhysRevB.93.165207](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.93.165207){:target='_blank'}. [@Miceli2016] +### 3.1. 2D Structures -![Point Pair Defects: Mg Substitution and Vacancy in GaN](../../../images/tutorials/materials/defects/defect_point_pair_gallium_nitride/0-figure-from-manuscript.webp "Point Defect Pair: Substitution, Vacancy{ style="max-height:500px;width:auto;" } in GaN, FIG. 2.") +#### 3.1.1. Island -#### 3.1.3. [Vacancy Point Defect in h-BN](defect-point-vacancy-boron-nitride.md) -[DOI: 10.1038/s41524-022-00730-w](https://doi.org/10.1038/s41524-022-00730-w){:target='_blank'} +##### 3.1.1.1. Island Surface Defect Formation in TiN D-2D-ISL -![Vacancy in h-BN](../../../images/tutorials/materials/defects/defect_point_vacancy_boron_nitride/0-figure-from-manuscript.webp "Vacancy in h-BN"){ style="max-height:500px;width:auto;" } +**Structure**: [Create Island Defect on TiN Surface](defect-surface-island-titanium-nitride.md) +**Properties**: Calculate island formation energy (Coming Soon) +**DOI**: [10.1103/PhysRevB.97.035406](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.97.035406){:target='_blank'} [@Sangiovanni2018] -#### 3.1.4. [Interstitial Point Defect in SnO](defect-point-interstitial-tin-oxide.md) -[DOI: 10.1103/PhysRevB.74.195128](https://doi.org/10.1103/PhysRevB.74.195128){:target='_blank'}. [@Togo2006; @Wang2014; @Na-Phattalung2006] +![Surface Defect](../../../images/tutorials/materials/defects/defect-creation-surface-island-titanium-nitride/0.png "Surface Defect, Island FIG. 2. a"){ style="max-height:500px;width:auto;" } -![SnO O-interstitial](../../../images/tutorials/materials/defects/defect_point_interstitial_tin_oxide/0-figure-from-manuscript.webp "O-interstitial defect in SnO"){ style="max-height:500px;width:auto;" } +##### 3.1.1.2. Pt Adatoms Island on MoS2 D-2D-ISL +**Structure**: [Create Pt Island on MoS2](defect-point-adatom-island-molybdenum-disulfide-platinum.md) +**Properties**: Calculate binding energy per Pt atom and density of states (Coming Soon) +**DOI**: [10.1021/cg5013395](https://doi.org/10.1021/cg5013395){:target='_blank'} [@Saidi2015; @Jiao2016; @Fichthorn2000; @Neugebauer1993; @Hortamani2007] -### 3.2. Surface Defects -#### 3.2.1. [Island Surface Defect Formation in TiN](defect-surface-island-titanium-nitride.md) -[DOI: 10.1103/PhysRevB.97.035406](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.97.035406){:target='_blank'}. [@Sangiovanni2018] +![Pt Island on MoS2](../../../images/tutorials/materials/defects/defect_point_adatom_island_molybdenum_disulfide_platinum/0-figure-from-manuscript.webp "Pt island formation on MoS2"){ style="max-height:500px;width:auto;" } -![Surface Defect](../../../images/tutorials/materials/defects/defect-creation-surface-island-titanium-nitride/0.png "Surface Defect, Island FIG. 2. a"){ style="max-height:500px;width:auto;" } +#### 3.1.2. Terrace -#### 3.2.2. [Step Surface Defect on Pt(111)](defect-surface-step-platinum.md) -[DOI: 10.1016/s0039-6028(02)01908-8](https://doi.org/10.1016/s0039-6028(02)01908-8){:target='_blank'}. [@Sljivancanin2002] +##### 3.1.2.1. Step Surface Defect on Pt(111) D-2D-TER + +**Structure**: [Create Step Defect on Pt(111)](defect-surface-step-platinum.md) +**Properties**: Calculate energy of dissociation (Coming Soon) +**DOI**: [10.1016/s0039-6028(02)01908-8](https://doi.org/10.1016/s0039-6028(02)01908-8){:target='_blank'} [@Sljivancanin2002] ![Step Surface Defect on Pt](../../../images/tutorials/materials/defects/defect_surface_step_platinum/0-figure-from-manuscript.webp "Fig. 1."){ style="max-height:500px;width:auto;" } -#### 3.2.3. [Adatom Surface Defects on Graphene](defect-surface-adatom-graphene.md) -[DOI: 10.1103/PhysRevB.77.235430](https://doi.org/10.1103/PhysRevB.77.235430){:target='_blank'} +#### 3.1.3. Adatom + +##### 3.1.3.1. Adatom Surface Defects on Graphene D-2D-ADA + +**Structure**: [Create Adatom Defects on Graphene](defect-surface-adatom-graphene.md) +**Properties**: Calculate adsorption energy, density of states, work function, dipole moment, and diffusion barriers (Coming Soon) +**DOI**: [10.1103/PhysRevB.77.235430](https://doi.org/10.1103/PhysRevB.77.235430){:target='_blank'} ![Adatom on Graphene Surface](../../../images/tutorials/materials/defects/defect-surface-adatom-graphene/me_adatom_on_hollow_graphene.webp "Fig. 1. Adatom on Graphene Surface"){ style="max-height:500px;width:auto;" } +#### 3.1.4. Grain Boundary Planar + +##### 3.1.4.1. Grain Boundary in h-BN D-2D-GBP -### 3.3. Planar Defects -#### 3.3.1. [Grain Boundary in FCC Metals (Copper)](defect-planar-grain-boundary-3d-fcc-metals-copper.md) -[DOI: 10.1038/ncomms2919](https://www.nature.com/articles/ncomms2919){:target='_blank'}. [@Frolov2013] +**Structure**: [Create Grain Boundary in h-BN](defect-planar-grain-boundary-2d-boron-nitride.md) +**Properties**: Calculate band gaps and LDOS (Coming Soon) +**DOI**: [10.1021/acs.nanolett.5b01852](https://doi.org/10.1021/acs.nanolett.5b01852){:target='_blank'} + +![h-BN Grain Boundary](../../../images/tutorials/materials/defects/defect_planar_grain_boundary_2d_boron_nitride/0-figure-from-manuscript.webp "h-BN Grain Boundary, FIG. 2c."){ style="max-height:500px;width:auto;" } + +### 3.2. 1D Structures + +#### 3.2.1. Grain Boundary Linear + +##### 3.2.1.1. Grain Boundary in FCC Metals (Copper) D-1D-GBL + +**Structure**: [Create Grain Boundary in Copper](defect-planar-grain-boundary-3d-fcc-metals-copper.md) +**Properties**: Calculate defect energy per atom (Coming Soon) +**DOI**: [10.1038/ncomms2919](https://www.nature.com/articles/ncomms2919){:target='_blank'} [@Frolov2013] ![Copper Grain Boundary](../../../images/tutorials/materials/defects/defect_planar_grain_boundary_3d_fcc_metal/0-figure-from-manuscript.webp "Copper Grain Boundary, FIG. 1"){ style="max-height:500px;width:auto;" } -#### 3.3.2. [Grain Boundary (2D) in h-BN](defect-planar-grain-boundary-2d-boron-nitride.md) -[DOI: 10.1021/acs.nanolett.5b01852](https://doi.org/10.1021/acs.nanolett.5b01852){:target='_blank'} +### 3.3. 0D Structures -![h-BN Grain Boundary](../../../images/tutorials/materials/defects/defect_planar_grain_boundary_2d_boron_nitride/0-figure-from-manuscript.webp "h-BN Grain Boundary, FIG. 2c."){ style="max-height:500px;width:auto;" } +#### 3.3.1. Substitution +##### 3.3.1.1. Substitutional Point Defects in Graphene D-0D-SUB +**Structure**: [Create Substitutional Defects in Graphene](defect-point-substitution-graphene.md) +**Properties**: [Calculate Band Structure of N-doped Graphene](defect-point-substitution-graphene-simulation.md) +**DOI**: [10.1103/PhysRevB.84.245446](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.84.245446){:target='_blank'} -## 4. Passivation +![Point Defect, Substitution, 0](../../../images/tutorials/materials/defects/defect_creation_point_substitution_graphene/0-figure-from-manuscript.webp "Point Defect, Substitution, FIG. 1."){ style="max-height:500px;width:auto;" } -### 4.1. Edge Passivation -#### 4.1.1. [H-Passivated Silicon Nanowire](passivation-edge-nanowire-silicon.md) -[DOI: 10.1103/PhysRevB.76.035305](https://doi.org/10.1103/PhysRevB.76.035305){:target='_blank'} [@Aradi2007] +#### 3.3.2. Defect Pair -![Passivated Silicon nanowire](../../../images/tutorials/materials/passivation/passivation_edge_nanowire_silicon/0-figure-from-manuscript.webp "Passivated Silicon nanowire, FIG. 1."){ style="max-height:500px;width:auto;" } +##### 3.3.2.1. Vacancy-Substitution Pair Defects in GaN D-0D-DFP +**Structure**: [Create Vacancy-Substitution Pair in GaN](defect-point-pair-gallium-nitride.md) +**Properties**: Calculate defect formation energies (Coming Soon) +**DOI**: [10.1103/PhysRevB.93.165207](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.93.165207){:target='_blank'} [@Miceli2016] -### 4.2. Surface Passivation -#### 4.2.1. [H-Passivated Silicon (100) Surface](passivation-surface-silicon.md) -[DOI: 10.1103/PhysRevB.57.13295](https://doi.org/10.1103/PhysRevB.57.13295){:target='_blank'}. [@Hansen1998; @Northrup1991; @Boland1990] +![Point Pair Defects: Mg Substitution and Vacancy in GaN](../../../images/tutorials/materials/defects/defect_point_pair_gallium_nitride/0-figure-from-manuscript.webp "Point Defect Pair: Substitution, Vacancy in GaN, FIG. 2."){ style="max-height:500px;width:auto;" } -![Si(100) H-Passivated Surface](../../../images/tutorials/materials/passivation/passivation_surface_silicon/0-figure-from-manuscript.webp "H-Passivated Silicon (100)"){ style="max-height:500px;width:auto;" } +#### 3.3.3. Vacancy + +##### 3.3.3.1. Vacancy Point Defect in h-BN D-0D-VAC + +**Structure**: [Create Vacancy Defect in h-BN](defect-point-vacancy-boron-nitride.md) +**Properties**: Calculate formation energies (Coming Soon) +**DOI**: [10.1038/s41524-022-00730-w](https://doi.org/10.1038/s41524-022-00730-w){:target='_blank'} + +![Vacancy in h-BN](../../../images/tutorials/materials/defects/defect_point_vacancy_boron_nitride/0-figure-from-manuscript.webp "Vacancy in h-BN"){ style="max-height:500px;width:auto;" } + +#### 3.3.4. Interstitial + +##### 3.3.4.1. Interstitial Point Defect in SnO D-0D-INT +**Structure**: [Create Interstitial Defect in SnO](defect-point-interstitial-tin-oxide.md) +**Properties**: Calculate formation energies and band structure (Coming Soon) +**DOI**: [10.1103/PhysRevB.74.195128](https://doi.org/10.1103/PhysRevB.74.195128){:target='_blank'} [@Togo2006; @Wang2014; @Na-Phattalung2006] +![SnO O-interstitial](../../../images/tutorials/materials/defects/defect_point_interstitial_tin_oxide/0-figure-from-manuscript.webp "O-interstitial defect in SnO"){ style="max-height:500px;width:auto;" } + + + +## 4. Processed Structures -## 5. Perturbations +### 4.1. 3D Structures -### 5.1. Ripples -#### 5.1.1. [Ripple perturbation of a Graphene sheet](perturbation-ripples-graphene.md) -[DOI: 10.1209/0295-5075/85/46002](https://doi.org/10.1209/0295-5075/85/46002){:target='_blank'}. [@ThompsonFlagg2009; @Fasolino2007; @Openov2010] +#### 4.1.1. Perturbation + +##### 4.1.1.1. Ripple Perturbation of Graphene Sheet X-3D-PER + +**Structure**: [Create Rippled Graphene Structure](perturbation-ripples-graphene.md) + +[//]: # (**Properties**: Calculate XXX (Coming Soon) ) +**DOI**: [10.1209/0295-5075/85/46002](https://doi.org/10.1209/0295-5075/85/46002){:target='_blank'} [@ThompsonFlagg2009; @Fasolino2007; @Openov2010] ![Rippled Graphene](../../../images/tutorials/materials/defects/perturbation_ripple_graphene/0-figure-from-manuscript.webp "Rippled Graphene, FIG. 1."){ style="max-height:500px;width:auto;" } -## 6. Other +### 4.2. 2D Structures -### 6.1. Interface Optimization -#### 6.1.1. [Gr/Ni(111) Interface Optimization](optimization-interface-film-xy-position-graphene-nickel.md) -[DOI: 10.1039/c3nr05279f](https://doi.org/10.1039/c3nr05279f){:target='_blank'}. [@Dahal2014; @Gamo1997; @Bertoni2004] +#### 4.2.1. Passivated Surface -![Gr/Ni Interface](../../../images/tutorials/materials/optimization/optimization_interface_film_xy_position_graphene_nickel/0-figure-from-manuscript.webp "Optimal position of graphene on Ni(111)"){ style="max-height:500px;width:auto;" } +##### 4.2.1.1. H-Passivated Silicon (100) Surface X-2D-PAS -#### 6.1.2. [Pt Adatoms Island on MoS2](defect-point-adatom-island-molybdenum-disulfide-platinum.md) -[DOI: 10.1021/cg5013395](https://doi.org/10.1021/cg5013395){:target='_blank'}. [@Saidi2015; @Jiao2016; @Fichthorn2000; @Neugebauer1993; @Hortamani2007] +**Structure**: [Create H-Passivated Si(100) Surface](passivation-surface-silicon.md) +**Properties**: Calculate H and D diffusion barriers, reaction and desorption barriers (Coming Soon) +**DOI**: [10.1103/PhysRevB.57.13295](https://doi.org/10.1103/PhysRevB.57.13295){:target='_blank'} [@Hansen1998; @Northrup1991; @Boland1990] -![Pt Island on MoS2](../../../images/tutorials/materials/defects/defect_point_adatom_island_molybdenum_disulfide_platinum/0-figure-from-manuscript.webp "Pt island formation on MoS2"){ style="max-height:500px;width:auto;" } +![Si(100) H-Passivated Surface](../../../images/tutorials/materials/passivation/passivation_surface_silicon/0-figure-from-manuscript.webp "H-Passivated Silicon (100)"){ style="max-height:500px;width:auto;" } + +### 4.3. 1D Structures + +#### 4.3.1. Passivated Edge +##### 4.3.1.1. H-Passivated Silicon Nanowire X-1D-PAS + +**Structure**: [Create H-Passivated Si Nanowire](passivation-edge-nanowire-silicon.md) +**Properties**: Calculate band gap, density of states, and formation energy (Coming Soon) +**DOI**: [10.1103/PhysRevB.76.035305](https://doi.org/10.1103/PhysRevB.76.035305){:target='_blank'} [@Aradi2007] + +![Passivated Silicon nanowire](../../../images/tutorials/materials/passivation/passivation_edge_nanowire_silicon/0-figure-from-manuscript.webp "Passivated Silicon nanowire, FIG. 1."){ style="max-height:500px;width:auto;" } ## References diff --git a/lang/en/docs/tutorials/materials/specific/passivation-edge-nanowire-silicon.md b/lang/en/docs/tutorials/materials/specific/passivation-edge-nanowire-silicon.md index 743558b98..7981b6758 100644 --- a/lang/en/docs/tutorials/materials/specific/passivation-edge-nanowire-silicon.md +++ b/lang/en/docs/tutorials/materials/specific/passivation-edge-nanowire-silicon.md @@ -6,6 +6,7 @@ tags: - nanowire - Si - H + - X-1D-PAS hide: - tags # YAML header @@ -14,7 +15,7 @@ render_macros: true # Passivation of Silicon Nanowire. -## Introduction. +## 1. Introduction This tutorial demonstrates the process of creating passivated silicon nanowires based on the work presented in the following manuscript, where the chemical gap tuning in silicon nanowires is studied. @@ -33,25 +34,25 @@ Specifically, the material from FIG. 1. of the publication: ![Passivated Silicon nanowire](../../../images/tutorials/materials/passivation/passivation_edge_nanowire_silicon/0-figure-from-manuscript.webp "Passivated Silicon nanowire, FIG. 1.") -## 1. Create Silicon Nanowire. +## 2. Create Silicon Nanowire -### 1.1. Load Silicon Material. +### 2.1. Load Silicon Material Since we're using Silicon, it can be already loaded as the default material and we can skip this step. -Otherwise, we navigate to [Materials Designer](../../../materials-designer/overview.md) and import the silicon material from the [Standata](../../../materials-designer/header-menu/input-output/standata-import.md). +Otherwise, we navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and import the silicon material from the [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/). -### 1.2. Launch JupyterLite Session. +### 2.2. Launch JupyterLite Session -Select the "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" menu item to launch the JupyterLite environment. +Select the "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" menu item to launch the JupyterLite environment. ![JupyterLite Dialog](../../../images/jupyterlite/md-advanced-jl.webp "JupyterLite Dialog") -### 1.3. Open `create_nanowire_custom_shapeipynb` notebook. +### 2.3. Open `create_nanowire_custom_shapeipynb` notebook Find `create_nanowire_custom_shape.ipynb` in the list of notebooks and click/double-click open it. -### 1.4. Open and modify the notebook. +### 2.4. Open and modify the notebook Next, we need to create a nanowire wit ha custom shape. @@ -79,19 +80,21 @@ For that, edit `create_nanowire_custom_shape.ipynb` notebook to modify the param ```python from typing import List import numpy as np -from mat3ra.made.tools.utils.coordinate import CoordinateCondition -# Flag to use Cartesian coordinates for the center and radii -USE_CARTESIAN_COORDINATES = False - -# Miller indices of the nanowire direction -MILLER_INDICES= (1,1,0) -# Supercell matrix to cut the cylinder from -SUPERCELL_MATRIX = [[3, 0, 0], [0, 2, 0], [0, 0, 2]] -# Vacuum thickness on the sides in Angstroms -VACUUM = 10.0 +from mat3ra.made.tools.helpers import CoordinateCondition + +# Cross-section shape parameters +CENTER_COORDINATE = [0.5, 0.5, 0.5] # Center of the cylinder in units specified by flag below +MAJOR_RADIUS = 0.25 # Cylinder wire radius in units specified by the flag below +MINOR_RADIUS = 0.1 # Cylinder wire radius in units specified by the flag below +USE_CARTESIAN_COORDINATES = False # Flag to use Cartesian coordinates for the center and radii + +# Wire parameters +MILLER_INDICES= (1,1,0) # Miller indices of the nanowire direction +SUPERCELL_MATRIX = [[3, 0, 0], [0, 2, 0], [0, 0, 2]] # Supercell matrix to cut the cylinder from +VACUUM = 10.0 # Vacuum thickness on the sides in Angstroms ALIGN_ALONG_X = False -# Custom Coordinate Condition for +# Custom Coordinate Condition for a hollow cylinder shape class CustomCoordinateCondition(CoordinateCondition): vertices: List[List[float]] @@ -126,7 +129,7 @@ vertices = [ condition = CustomCoordinateCondition(vertices=vertices).condition ``` -## 1.5. Run the Notebook and use the Material. +## 3. 1.5. Run the Notebook and use the Material Run the notebook by clicking `Run` > `Run All` in the top menu to run cells and wait for the results to appear. @@ -136,9 +139,9 @@ After running the notebook and submitting the material, the user will be able to ![Silicon Nanowire](../../../images/tutorials/materials/passivation/passivation_edge_nanowire_silicon/3-silicon-nanowire.webp "Silicon Nanowire") -## 2. Passivate with Hydrogen. +## 4. Passivate with Hydrogen -### 2.1. Setup the Passivation. +### 4.1. Setup the Passivation Open JupyterLite Session again and select Silicon Nanowire material for Input Materials. @@ -163,38 +166,42 @@ IS_COORDINATION_SELECTION_INTERACTIVE = False MATERIAL_INDEX = 0 -BOND_LENGTH = 1.46 # in Angstroms -PASSIVANT = "H" # Chemical symbol of the passivant -COORDINATION_SEARCH_RADIUS = 2.5 # in Angstroms (sphere in which to search for neighbors) -COORDINATION_THRESHOLD = 3 # Coordination number below which to passivate -MAX_BONDS_TO_SATURATE = 2 # Maximum number of bonds to saturate +# Passivation parameters +PASSIVANT = "H" # Chemical element for passivating atom +BOND_LENGTH = 1.46 # Distance from atom to passivant, in Angstroms -SYMMETRY_TOLERANCE = 0.1 +# Undercoordinated atoms search algorithm parameters +COORDINATION_THRESHOLD = 3 # Coordination threshold, below which passivation is applied to the atom +COORDINATION_SEARCH_RADIUS = 2.5 # Distance to look for neighbors for coordination, in Angstroms +NUMBER_OF_BONDS_TO_PASSIVATE = 2 # Number of bonds to passivate per undercoordinated atom +SYMMETRY_TOLERANCE = 0.1 # Tolerance for symmetry analysis of existing bonds + +# Visualization parameters SHOW_INTERMEDIATE_STEPS = True -CELL_REPETITIONS_FOR_VISUALIZATION = [1, 1, 1] +CELL_REPETITIONS_FOR_VISUALIZATION = [1, 1, 1] # Structure repeat in view ``` Here's the visual of the updated content: ![Notebook setup](../../../images/tutorials/materials/passivation/passivation_edge_nanowire_silicon/5-jl-setup.webp "Notebook setup") -### 2.2. Run the notebook and analyze the results. +### 4.2. Run the notebook and analyze the results After running the notebook, the user will be able to visualize the structure of Silicon Nanowire with substitution defects. ![Review the Results](../../../images/tutorials/materials/passivation/passivation_edge_nanowire_silicon/6-jl-result-preview.webp "Review the Results") -## 3. Pass the Material to Materials Designer. +## 5. Pass the Material to Materials Designer The user can pass the material with substitution defects in the current Materials Designer environment and save it. ![Final Material](../../../images/tutorials/materials/passivation/passivation_edge_nanowire_silicon/7-wave-result.webp "H-Passivated Silicon Nanowire") -Or the user can [save or download](../../../materials-designer/header-menu/input-output.md) the material in Material JSON format or POSCAR format. +Or the user can [save or download]({{ interface_url }}/materials-designer/header-menu/input-output/) the material in Material JSON format or POSCAR format. -## Interactive JupyterLite Notebook. +## 6. Interactive JupyterLite Notebook The following JupyterLite notebook demonstrates the process of creating materials with hydrogen passivation of silicon nanowire. Select "Run" > "Run All Cells". @@ -206,5 +213,5 @@ The following JupyterLite notebook demonstrates the process of creating material {% endwith %} {% endwith %} -## References. +## 7. References diff --git a/lang/en/docs/tutorials/materials/specific/passivation-surface-silicon.md b/lang/en/docs/tutorials/materials/specific/passivation-surface-silicon.md index 7e94c262c..29f034b30 100644 --- a/lang/en/docs/tutorials/materials/specific/passivation-surface-silicon.md +++ b/lang/en/docs/tutorials/materials/specific/passivation-surface-silicon.md @@ -8,6 +8,7 @@ tags: - surface reconstruction - Si - H + - X-2D-PAS hide: - tags @@ -17,7 +18,7 @@ render_macros: true # Passivation of Silicon (100) Surface. -## Introduction. +## 1. Introduction This tutorial demonstrates how to passivate a reconstructed silicon (100) surface with hydrogen atoms, following the methodology described in the literature. @@ -31,19 +32,19 @@ We will recreate the passivated surface structure shown in Fig. 8: ![Si(100) H-Passivated Surface](../../../images/tutorials/materials/passivation/passivation_surface_silicon/0-figure-from-manuscript.webp "H-Passivated Silicon (100)") -## 1. Obtain the Silicon (100) Surface Structure. +## 2. Obtain the Silicon (100) Surface Structure -### 1.1. Load Base Material. +### 2.1. Load Base Material -Navigate to [Materials Designer](../../../materials-designer/overview.md) and import the reconstructed Si(100) surface from [Standata](../../../materials-designer/header-menu/input-output/standata-import.md). +Navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and import the reconstructed Si(100) surface from [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/). ![Si(100) Structure](../../../images/tutorials/materials/passivation/passivation_surface_silicon/1-wave-original-material.webp "Si(100) Structure") -### 1.2. Launch JupyterLite Session. +### 2.2. Launch JupyterLite Session -Select the "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" menu item to launch the JupyterLite environment. +Select the "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" menu item to launch the JupyterLite environment. -### 1.3. Open Modified `create_supercell.ipynb` Notebook. +### 2.3. Open Modified `create_supercell.ipynb` Notebook Open `create_supercell.ipynb`, select input material as the Si(100) structure, and set the supercell parameters in 1.1.: @@ -54,8 +55,8 @@ SUPERCELL_MATRIX = [ [0, 0, 1] ] -# or use the scaling factor. -SCALING_FACTOR = None # [3, 3, 1]. +# or use the scaling factor +SCALING_FACTOR = None # [3, 3, 1] ``` Also add to the "Get input materials" cell the following code to adjust the Si atom position: @@ -84,7 +85,7 @@ slab.set_coordinates(new_coordinates) ![Supercell Parameters](../../../images/tutorials/materials/passivation/passivation_surface_silicon/2-jl-setup-nb-adjust.webp "Supercell Parameters Visualization") -### 1.4. Run Structure Adjustment. +### 2.4. Run Structure Adjustment Run the notebook using "Run > Run All Cells". This will: @@ -95,28 +96,43 @@ Run the notebook using "Run > Run All Cells". This will: ![Adjusted Structure](../../../images/tutorials/materials/passivation/passivation_surface_silicon/3-wave-adjusted-material.webp "Adjusted Si(100) Structure") -## 2. Passivate the Surface. +## 3. Passivate the Surface -### 2.1. Open `passivate_slab.ipynb` Notebook. +### 3.1. Open `passivate_slab.ipynb` Notebook Find and open the `passivate_slab.ipynb` notebook to add hydrogen atoms to the surface. -### 2.2. Set Passivation Parameters. +### 3.2. Set Passivation Parameters Configure the following parameters for hydrogen passivation: ```python -# Passivation parameters. -PASSIVANT = "H" # Chemical symbol for hydrogen. -BOND_LENGTH = 1.46 # Si-H bond length in Angstroms. -SURFACE = "top" # Passivate only the top surface. - -# Surface detection parameters. -SHADOWING_RADIUS = 1.8 # In Angstroms. -DEPTH = 0.5 # In Angstroms. - -# Visualization parameters. -CELL_REPETITIONS_FOR_VISUALIZATION = [1, 1, 1] +# Material selection +MATERIAL_INDEX = 0 # Which material to use from input list + +# Passivation parameters +PASSIVANT = "H" # Chemical symbol of passivating atom +BOND_LENGTH = 1.46 # Distance from surface to passivant, in Angstroms +SURFACE = "top" # Which surface to passivate: "top", "bottom" or "both" + +# Surface detection parameters +SHADOWING_RADIUS = 1.8 # Radius to exclude subsurface atoms, in Angstroms +DEPTH = 0.5 # How deep to look for surface atoms, in Angstroms + +BYPASS_SLAB_CREATION = False # If True, will use input material directly + +# Slab parameters for creating a new slab if previous option is set to True +DEFAULT_SLAB_PARAMETERS = { + "miller_indices": (0, 0, 1), + "thickness": 3, + "vacuum": 10.0, + "USE_ORTHOGONAL_C": True, + "xy_supercell_matrix": [[3, 0], [0, 3]] +} + +# Visualization parameters +SHOW_INTERMEDIATE_STEPS = True +CELL_REPETITIONS_FOR_VISUALIZATION = [1, 1, 1] # Structure repeat in view ``` Key parameters explained: @@ -128,7 +144,7 @@ Key parameters explained: ![Passivation Parameters](../../../images/tutorials/materials/passivation/passivation_surface_silicon/4-jl-setup-nb-passivate.webp "Passivation Parameters Visualization") -### 2.3. Run Passivation. +### 3.3. Run Passivation Run all cells in the notebook. The passivation process will: @@ -138,7 +154,7 @@ Run all cells in the notebook. The passivation process will: ![Passivated Structure](../../../images/tutorials/materials/passivation/passivation_surface_silicon/5-jl-result-preview.webp "H-Passivated Si(100) Structure") -## 3. Analyze Results. +## 4. Analyze Results After running both notebooks, examine the final structure: @@ -150,14 +166,14 @@ Check that: ![Final Structure](../../../images/tutorials/materials/passivation/passivation_surface_silicon/6-wave-result.webp "Final H-Passivated Si(100)") -## 4. Save the Results. +## 5. Save the Results The final structure will be automatically passed back to Materials Designer where you can: 1. Save it in your workspace 2. Export it in various formats 3. Use it for further calculations -## Interactive JupyterLite Notebook. +## 6. Interactive JupyterLite Notebook The following embedded notebook demonstrates the complete process. Select "Run" > "Run All Cells". @@ -169,7 +185,7 @@ The following embedded notebook demonstrates the complete process. Select "Run" {% endwith %} {% endwith %} -## Parameter Fine-tuning. +## 7. Parameter Fine-tuning To adjust the passivation: @@ -184,4 +200,4 @@ To adjust the passivation: - Change `SURFACE` to passivate different surfaces - Change `PASSIVANT` to use different passivating species -## References. +## 8. References diff --git a/lang/en/docs/tutorials/materials/specific/perturbation-ripples-graphene.md b/lang/en/docs/tutorials/materials/specific/perturbation-ripples-graphene.md index d5822bb01..e6864c64e 100644 --- a/lang/en/docs/tutorials/materials/specific/perturbation-ripples-graphene.md +++ b/lang/en/docs/tutorials/materials/specific/perturbation-ripples-graphene.md @@ -6,6 +6,7 @@ tags: - 2D materials - edge effects - C + - X-3D-PER hide: - tags @@ -15,7 +16,7 @@ render_macros: true # Ripple perturbation of a Graphene sheet. -## Introduction. +## 1. Introduction This tutorial demonstrates the process of creating edge induced ripples in graphene nanosheet based on the work presented in the following manuscript, where the mechanical properties of graphene edges were studied. @@ -29,64 +30,102 @@ We will focus on creating graphene with edge-induced ripples that match the patt ![Rippled Graphene](../../../images/tutorials/materials/defects/perturbation_ripple_graphene/0-figure-from-manuscript.webp "Rippled Graphene, FIG. 1.") -## 1. Create Graphene Nanoribbon. +## 2. Create Graphene Nanoribbon -### 1.1. Load Graphene Material. +### 2.1. Load Graphene Material -Navigate to [Materials Designer](../../../materials-designer/overview.md) and import the graphene material from the [Standata](../../../materials-designer/header-menu/input-output/standata-import.md). +Navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and import the graphene material from the [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/). ![Standata Graphene Import](../../../images/tutorials/materials/defects/defect_creation_point_substitution_graphene/1-standata-graphene.webp "Standata Graphene Import") -### 1.2. Launch JupyterLite Session. +### 2.2. Launch JupyterLite Session -Select the "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" menu item to launch the JupyterLite environment. +Select the "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" menu item to launch the JupyterLite environment. ![JupyterLite Dialog](../../../images/jupyterlite/md-advanced-jl.webp "JupyterLite Dialog") -### 1.3. Open `create_nanoribbon.ipynb` notebook. +### 2.3. Open `create_nanoribbon.ipynb` notebook Find `create_nanoribbon.ipynb` in the list of notebooks and click/double-click to open it. -### 1.4. Set up nanoribbon parameters. +### 2.4. Set up nanoribbon parameters Edit notebook to set the nanoribbon parameters: ```python +# Index in the list of materials, to access as materials[MATERIAL_INDEX] +MATERIAL_INDEX = 0 + # Widths and lengths are in number of unit cells -WIDTH = 40 -VACUUM_WIDTH = 10 -LENGTH = 40 -VACUUM_LENGTH = 10 -EDGE_TYPE = "zigzag" # "zigzag" or "armchair" +WIDTH = 40 # in unit cells +LENGTH = 40 # in unit cells +VACUUM_WIDTH = 10.0 # in Angstroms +VACUUM_LENGTH = 10.0 # in Angstroms +EDGE_TYPE = "zigzag" # "zigzag" or "armchair" ``` ![Setup Nanoribbon Parameters](../../../images/tutorials/materials/defects/perturbation_ripple_graphene/2-jl-setup-nb-nanoribbon.webp "Setup Nanoribbon Parameters") -### 1.5. Run the notebook. +### 2.5. Run the notebook After setting the parameters, run the notebook by selecting "Run > Run All Cells" from the menu. This will create a graphene nanoribbon with the specified dimensions. ![Nanoribbon Result](../../../images/tutorials/materials/defects/perturbation_ripple_graphene/3-wave-result-nanoribbon.webp "Graphene Nanoribbon") -## 2. Create Ripples in the Nanoribbon. +## 3. Create Ripples in the Nanoribbon -### 2.1. Open `create_perturbation_custom.ipynb` notebook. +### 3.1. Open `create_perturbation_custom.ipynb` notebook Find `create_perturbation_custom.ipynb` in the list of notebooks and click/double-click to open it. -### 2.2. Set up perturbation parameters. +### 3.2. Set up perturbation parameters Next, we need to set up the parameters for creating rippled graphene. Edit notebook in 1.2. to set generic perturbation parameters: ```python +import sympy as sp + # Set whether to preserve geodesic distance and scale the cell accordingly to match PBC PRESERVE_GEODESIC_DISTANCE = False +# Set the supercell matrix to apply to original material +SUPERCELL_MATRIX = [[40, 0, 0], [0, 40, 0], [0, 0, 1]] + # Set whether to use Cartesian coordinates for the perturbation function USE_CARTESIAN_COORDINATES = False -MATERIAL_NAME = "Graphene" + +# Variables for the perturbation function (for SymPy) +variable_names = ["x", "y", "z"] +x, y, z = sp.symbols(variable_names) + +# Set the parameters for the perturbation function +AMPLITUDE = 0.09 # Ripple amplitude +WAVELENGTH = 0.2 # Wavelength of ripples +EDGE_WIDTH = 0.25 # Width of edge effect +PHASE_X = 0.0 # Phase shift for x direction +PHASE_Y = sp.pi/2 # Phase shift for y direction + +# Create edge masks for both x and y using polynomial functions +left_edge_x = sp.Max(0, (EDGE_WIDTH - x) / EDGE_WIDTH) +right_edge_x = sp.Max(0, (x - (1 - EDGE_WIDTH)) / EDGE_WIDTH) +left_edge_y = sp.Max(0, (EDGE_WIDTH - y) / EDGE_WIDTH) +right_edge_y = sp.Max(0, (y - (1 - EDGE_WIDTH)) / EDGE_WIDTH) + +# Combine edge masks +edge_mask_x = left_edge_x + right_edge_x +edge_mask_y = left_edge_y + right_edge_y +edge_mask = edge_mask_x + edge_mask_y + +# Wave pattern +wave_pattern = ( + sp.sin(2 * sp.pi * x / WAVELENGTH + PHASE_X) * + sp.sin(2 * sp.pi * y / WAVELENGTH + PHASE_Y) +) + +# Combine waves with edge mask +custom_sympy_function = AMPLITUDE * wave_pattern * edge_mask ``` Then modify section 1.3 to define the custom perturbation function: @@ -135,13 +174,13 @@ Key parameters explained: - `EDGE_WIDTH` Controls how far the ripples extend from the edges (0.25 in crystal coordinates) - `PHASE_X`/`PHASE_Y` Controls the phase shift of the ripple pattern -### 2.3. Run the notebook. +### 3.3. Run the notebook After setting the parameters, run the notebook by selecting "Run > Run All Cells" from the menu. ![Run All](../../../images/jupyterlite/run-all.webp "Run All") -## 3. Pass the Material to Materials Designer. +## 4. Pass the Material to Materials Designer The rippled graphene structure will be automatically passed back to the current Materials Designer environment where user can save it. @@ -153,9 +192,9 @@ Graphene with edge-induced ripples with amplitude of 0.27 crystal units. ![Final Material](../../../images/tutorials/materials/defects/perturbation_ripple_graphene/6-wave-result-final-2.webp "Final Rippled Graphene, amplitude 0.27 crystal units") -Or user can [save or download](../../../materials-designer/header-menu/input-output.md) the material in Material JSON format or POSCAR format. +Or user can [save or download]({{ interface_url }}/materials-designer/header-menu/input-output/) the material in Material JSON format or POSCAR format. -## Interactive JupyterLite Notebook. +## 5. Interactive JupyterLite Notebook The following JupyterLite notebook demonstrates the process of creating rippled graphene. Select "Run" > "Run All Cells". @@ -167,7 +206,7 @@ The following JupyterLite notebook demonstrates the process of creating rippled {% endwith %} {% endwith %} -## Parameters Fine-tuning. +## 6. Parameters Fine-tuning If user need to adjust the ripple pattern, user can modify these key parameters: @@ -183,4 +222,4 @@ If user need to adjust the ripple pattern, user can modify these key parameters: 4. To change the ripple pattern: - Adjust PHASE_X and PHASE_Y to modify the wave interference pattern -## References. +## 7. References diff --git a/lang/en/docs/tutorials/materials/specific/slab-strontium-titanate.md b/lang/en/docs/tutorials/materials/specific/slab-strontium-titanate.md index 6834cee1e..221703d29 100644 --- a/lang/en/docs/tutorials/materials/specific/slab-strontium-titanate.md +++ b/lang/en/docs/tutorials/materials/specific/slab-strontium-titanate.md @@ -5,6 +5,7 @@ tags: - SrTiO3 - terminations - surface + - P-2D-SLB-S hide: - tags @@ -14,7 +15,7 @@ render_macros: true # Strontium Titanate Slabs. -## Introduction. +## 1. Introduction This tutorial demonstrates the process of creating strontium titanate (SrTiO3) slabs based on the work presented in the following manuscript, where the electronic properties of SrTiO3 slabs are studied. @@ -30,25 +31,25 @@ We will focus on creating SrTiO3 (011) slabs with different terminati ![Strontium Titanate Slabs](../../../images/tutorials/materials/2d_materials/slab_strontium_titanate/0-figure-from-manuscript.webp "Strontium Titanate Slabs, FIG. 2.") -## 1. Create Strontium Titanate Slab. +## 2. Create Strontium Titanate Slab -### 1.1. Load Strontium Titanate Material. +### 2.1. Load Strontium Titanate Material -Navigate to [Materials Designer](../../../materials-designer/overview.md) and import the strontium titanate material from the [Standata](../../../materials-designer/header-menu/input-output/standata-import.md). +Navigate to [Materials Designer]({{ interface_url }}/materials-designer/overview/) and import the strontium titanate material from the [Standata]({{ interface_url }}/materials-designer/header-menu/input-output/standata-import/). ![Strontium Titanate Material](../../../images/tutorials/materials/2d_materials/slab_strontium_titanate/original-material.webp "Strontium Titanate Material") -### 1.2. Launch JupyterLite Session. +### 2.2. Launch JupyterLite Session -Select the "Advanced > [JupyterLite Transformation](../../../materials-designer/header-menu/advanced/jupyterlite-dialog.md)" menu item to launch the JupyterLite environment. +Select the "Advanced > [JupyterLite Transformation]({{ interface_url }}/materials-designer/header-menu/advanced/jupyterlite-dialog/)" menu item to launch the JupyterLite environment. ![JupyterLite Dialog](../../../images/jupyterlite/md-advanced-jl.webp "JupyterLite Dialog") -### 1.3. Open `create_slab.ipynb` notebook. +### 2.3. Open `create_slab.ipynb` notebook Find `create_slab.ipynb` in the list of notebooks and click/double-click open it. -### 1.4. Open and modify the notebook. +### 2.4. Open and modify the notebook Next, we need to create a SrTiO3 slab with the (011) orientation. @@ -64,7 +65,6 @@ Terminations can be selected interactively by setting the `IS_TERMINATIONS_SELEC Edit notebook in 1.1. to set parameters of slab: ```python - # Enable interactive selection of terminations via UI prompt IS_TERMINATIONS_SELECTION_INTERACTIVE = False @@ -72,10 +72,12 @@ MILLER_INDICES = (0, 1, 1) THICKNESS = 3 # in atomic layers VACUUM = 10.0 # in angstroms XY_SUPERCELL_MATRIX = [[1, 0], [0, 1]] -USE_ORTHOGONAL_Z = True +USE_ORTHOGONAL_C = True USE_CONVENTIONAL_CELL = True -# Index of the termination to be selected +# Stoichiometric formula of the slab termination to be used. +SLAB_TERMINATION_FORMULA = None +# if None, the index of all possible terminations will be used TERMINATION_INDEX = 0 ``` @@ -97,33 +99,33 @@ This will allow for symmetry breaking and correct detection for all possible ter ![Rotate Material](../../../images/tutorials/materials/2d_materials/slab_strontium_titanate/jl-setup-rotation.webp "Rotate Material") -### 1.5. Run the notebook. +### 2.5. Run the notebook After setting the parameters, run the notebook by selecting "Run > Run All Cells" from the menu. ![Run All](../../../images/jupyterlite/run-all.webp "Run All") -## 2. Analyze the Results. +## 3. Analyze the Results After running the notebook, the slabs for different possible terminations should apper in the preview. ![Strontium Titanate Slab](../../../images/tutorials/materials/2d_materials/slab_strontium_titanate/jl-result-preview.webp "Strontium Titanate Slab") -### 2.1. Select the desired termination. +### 3.1. Select the desired termination If the interactive selection of terminations is enabled, select the desired termination from the list or change the `TERMINATION_INDEX` parameter in the notebook and rerun it. -## 3. Pass the Material to Materials Designer. +## 4. Pass the Material to Materials Designer The user can pass the material with the selected termination in the current Materials Designer environment and save it. ![Final Material](../../../images/tutorials/materials/2d_materials/slab_strontium_titanate/wave-result.webp "Strontium Titanate Slab") -Or the user can [save or download](../../../materials-designer/header-menu/input-output.md) the material in Material JSON format or POSCAR format. +Or the user can [save or download]({{ interface_url }}/materials-designer/header-menu/input-output/) the material in Material JSON format or POSCAR format. -## Interactive JupyterLite Notebook. +## 5. Interactive JupyterLite Notebook The following JupyterLite notebook demonstrates the process of creating strontium titanate slabs. Select "Run" > "Run All Cells". @@ -136,5 +138,5 @@ The following JupyterLite notebook demonstrates the process of creating strontiu {% endwith %} {% endwith %} -## References. +## 6. References diff --git a/lang/en/docs/tutorials/materials/vesta-remote-desktop.md b/lang/en/docs/tutorials/materials/vesta-remote-desktop.md index fbc7a56b5..d492b88b1 100644 --- a/lang/en/docs/tutorials/materials/vesta-remote-desktop.md +++ b/lang/en/docs/tutorials/materials/vesta-remote-desktop.md @@ -1,77 +1,75 @@ -# Create Materials With VESTA under Remote Desktop +# Create Materials with VESTA under Remote Desktop -The present tutorial describes the steps necessary for connecting to our platform via a [Remote Desktop](../../remote-connection/remote-desktop.md), in order to create and manipulate a [material structure](../../materials/overview.md) through [VESTA](../../software-directory/analysis/vesta.md) graphical analysis and visualization software. +This tutorial describes the steps necessary for connecting to the platform via a [Remote Desktop]({{ cli_url }}/remote-connection/remote-desktop/) in order to create and manipulate a [material structure]({{ reference_url }}/materials/overview/) through [VESTA]({{ reference_url }}/software-directory/analysis/vesta/) graphical analysis and visualization software. -We demonstrate how this new crystal structure can be retrieved within the account-owned [collection](../../accounts/collections.md) of materials, accessible via the [Materials Explorer](../../materials/ui/explorer.md) of our [Web Interface](../../ui/overview.md). This transfer of the structure information is achieved through the help of the [Dropbox functionality](../../data-in-objectstorage/dropbox.md) of our platform. - -Additional analysis software similar to VESTA can be retrieved under Remote Desktop, as introduced under the list presented [herein](../../software-directory/overview.md#analysis-tools). +The new crystal structure can be retrieved within the account-owned [collection]({{ reference_url }}/accounts/collections/) of materials, accessible via the [Materials Explorer]({{ interface_url }}/materials/ui/explorer/) of the [Web Interface]({{ interface_url }}/ui/overview/). This transfer of the structure information is achieved through the [Dropbox functionality]({{ resources_url }}/data-in-objectstorage/dropbox/). -## Accessing Remote Desktop +Additional analysis software similar to VESTA can be retrieved under Remote Desktop, as listed [here]({{ reference_url }}/software-directory/overview/#analysis-tools). -One must open a [Remote Desktop Connection](../../remote-connection/remote-desktop.md) via our [Web Interface](../../ui/overview.md) in order to run [graphical interface programs](../../software-directory/overview.md#analysis-tools) for material analysis and visualization purposes. -The instructions for opening and launching a Remote Desktop session can be found under [this page](../../remote-connection/actions/open-desktop.md). +## 1. Access the Remote Desktop -## Launching VESTA Visualization Software +A [Remote Desktop Connection]({{ cli_url }}/remote-connection/remote-desktop/) must be opened via the [Web Interface]({{ interface_url }}/ui/overview/) in order to run [graphical interface programs]({{ reference_url }}/software-directory/overview/#analysis-tools) for material analysis and visualization. -The user should now [follow this procedure](../../remote-connection/actions-rd/open-app.md) in order to start a session of the [VESTA](../../software-directory/analysis/vesta.md) graphical materials analysis software. +The instructions for opening and launching a Remote Desktop session can be found [in this page]({{ cli_url }}/remote-connection/actions/open-desktop/). -!!!warning "Avoid compute intensive visualization tasks" - We kindly ask users to avoid running excessively intensive visualization tasks when interacting with analysis software such as VESTA, as it may interfere with other users' operations during the course of their execution. -## Use VESTA to Create a New Crystal Structure +## 2. Launch VESTA visualization software -We use VESTA to create a new crystal structure consisting in **bcc Iron**, taken in its two-atom conventional unit cell representation. We remind the reader about the basic features of such a crystal structure. +[Follow this procedure]({{ cli_url }}/remote-connection/actions-rd/open-app/) to start a session of the [VESTA]({{ reference_url }}/software-directory/analysis/vesta/) graphical materials analysis software. -- Space Group: Im-3m +!!!warning "Avoid compute-intensive visualization tasks" + Running excessively intensive visualization tasks when interacting with analysis software such as VESTA should be avoided, as it may interfere with other operations on the platform. -- Bravais Lattice: body-centred cubic -- Lattice Constant: 2.87 Angstrom +## 3. Create a new crystal structure with VESTA + +This example creates a **bcc Iron** structure in its two-atom conventional unit cell representation. The basic features of this crystal structure are: +- Space Group: Im-3m +- Bravais Lattice: body-centred cubic +- Lattice Constant: 2.87 Å - Atomic Positions of Fe atoms: (0,0,0); (1/2,1/2,1/2) -A visual representation of the bcc Iron crystal structure is portrayed below. +A visual representation of the bcc Iron crystal structure is shown below. ![bcc Iron Crystal Structure](../../images/tutorials/bcc-iron-crystal-structure.png "bcc Iron Crystal Structure") -### Open New Structure Dialog +### 3.1. Open the New Structure dialog + +In order to create a new material structure through VESTA, click the "New Structure" option at the top of the File Menu. This opens a "New Data" dialog, where new crystal structures can be defined by entering their relevant crystallographic structural information and parameters. + +### 3.2. Insert lattice parameters and atomic positions + +First, enter the lattice parameters of the Iron body-centred cubic unit cell under the "Unit Cell" tab of the dialog. Select the relevant cubic space group (Im-3m, number 229). + +Second, insert the atomic positions and chemical identity of the atoms under the "Structure Parameters" tab, clicking "New" to add each atom. Only a single Fe atom at the origin needs to be added, since the second atom at the centre of the unit cell is related to it by the space group symmetry. + +Close the "New Data" dialog and record the changes by clicking **OK**. The view returns to the main VESTA interface, where the crystal structure of bcc Iron can be visualized and manipulated. + -In order to create a new material structure through VESTA, the user should click the "New Structure" option at the top of the File Menu, accessible at the top-left corner of the VESTA graphical user interface. +## 4. Save the structure as POSCAR to Dropbox -Doing this will open a "New Data" dialog, with which new crystal structures such as bcc Iron can be defined by entering their relevant crystallographic structural information and parameters. - -### Insert Lattice Parameters and Atomic Positions - -The user should first enter the aforementioned lattice parameters of the Iron body-centred cubic unit cell under the "Unit Cell" tab of the dialog. Here, the relevant cubic space group (Im-3m, number 229) can also be selected. - -Secondly, the atomic positions and chemical identity of the atoms present within the crystal structure should be inserted within the "Structure Parameters" tab, by clicking on "New" button every time a new atom is added on top of those already listed under the central table in this tab. In our case, only a single Fe atom at the origin needs to be added, since the second atom at the centre of the unit cell is already related to it by the space group symmetry selected in the preceding step. +Following the creation of the bcc Iron crystal structure, the structural data can be exported under the POSCAR file format directly to the [Dropbox Folder]({{ resources_url }}/data-in-objectstorage/dropbox/). Click the "Export Data" option under the "File" menu. -At the end of entering the appropriate crystallographic data for bcc Iron, the "New Data" dialog should be closed and the corresponding changes recorded by clicking the `OK` button at the bottom of the dialog. The view will hence be returned to the main VESTA interface, with which the crystal structure of bcc Iron can be visualized and manipulated graphically at will by the user. +In the resulting dialog, select the [dropbox folder]({{ resources_url }}/data-on-disk/directories/#dropbox) accessible via the [home folder]({{ resources_url }}/infrastructure/login/directories/), and choose the POSCAR file format. A suitable filename can be entered. The dialog allows choosing between fractional or Cartesian coordinates, and whether to convert to the Niggli reduced cell representation. -## Save Structure as POSCAR to Dropbox -Following the creation of the bcc Iron crystal structure within VESTA, the associated structural data can then be exported under the POSCAR file format directly to the [Dropbox Folder](../../data-in-objectstorage/dropbox.md), affording for the simultaneous sharing of files between all [nodes of our platform](../../infrastructure/overview.md). This should be done by clicking the "Export Data" option under the top-left "File" menu of the VESTA interface. +## 5. Download the structure -Under the resulting "Export Data" dialog, the [dropbox folder](../../data-on-disk/directories.md#dropbox) accessible via the user's [home folder](../../infrastructure/login/directories.md) should be selected, and the appropriate POSCAR file format should be chosen under the bottom-right menu of the dialog. A suitable filename can also be entered at the top for later easier retrieval of the file. The interface will finally allow the user to choose between saving the crystallographic atomic position data in fractional or Cartesian coordinates, and whether to convert the crystal structure to its Niggli reduced cell representation. +After exiting the Remote Desktop session, return to the [Web Interface]({{ interface_url }}/ui/overview/). The POSCAR file saved in the preceding step can be retrieved under the [Dropbox Page]({{ interface_url }}/data-in-objectstorage/ui/dropbox-page/), accessible through the [Left-hand Sidebar Menu]({{ interface_url }}/ui/left-sidebar/). -## Download Structure +The POSCAR file should be downloaded to the local disk following [these instructions]({{ interface_url }}/data-in-objectstorage/actions/download/). -The user can now exit the Remote Desktop session and return to the main [Web Interface](../../ui/overview.md) of our platform. The same crystallographic POSCAR file saved in the preceding step can now be retrieved again under the [Dropbox Page](../../data-in-objectstorage/ui/dropbox-page.md), accessible through the main [Left-hand Sidebar Menu](../../ui/left-sidebar.md) of the Web Interface. -The POSCAR file should be downloaded to the local disk by following [these instructions](../../data-in-objectstorage/actions/download.md). +## 6. Upload the structure to the materials collection -## Upload Structure to Materials Collection +After switching to the [Materials Explorer Page]({{ interface_url }}/materials/ui/explorer/), the POSCAR file can be uploaded and added to the account-owned [collection]({{ reference_url }}/accounts/collections/) of materials, as explained [in this page]({{ interface_url }}/materials/actions/upload/). -After switching to the [Materials Explorer Page](../../materials/ui/explorer.md), this same POSCAR file can then be uploaded again into our platform, and thus added to the account-owned [collection](../../accounts/collections.md) of materials. Uploading a POSCAR structure file is accomplished as explained under [this page](../../materials/actions/upload.md). -## Animation +## 7. Video walkthrough -The steps narrated in the preceding paragraphs of the present tutorial page are illustrated in the below video. - -We begin with the creation and visualization of a new bcc Iron crystal structure through the [VESTA](../../software-directory/analysis/vesta.md) analysis software, incorporated into our [Remote Desktop Interface](../../remote-connection/remote-desktop.md). - -We conclude this animation by saving the crystal structure data under the POSCAR format to the [Dropbox Folder](../../data-in-objectstorage/dropbox.md), and by later retrieving it under the Web Interface in order to upload it and inserting it into the account-owned [collection](../../accounts/collections.md) of materials. This new material entry is finally inspected under the [Materials Viewer Interface](../../materials/ui/viewer.md). +The animation below demonstrates all steps in this tutorial: creating and visualizing a bcc Iron crystal structure through [VESTA]({{ reference_url }}/software-directory/analysis/vesta/) under the [Remote Desktop]({{ cli_url }}/remote-connection/remote-desktop/), saving the structure in POSCAR format to the [Dropbox Folder]({{ resources_url }}/data-in-objectstorage/dropbox/), and retrieving and uploading it to the materials [collection]({{ reference_url }}/accounts/collections/) via the Web Interface.
diff --git a/lang/en/docs/tutorials/ml/deepmd-mlff-with-espresso-cp-and-lammps.md b/lang/en/docs/tutorials/ml/deepmd-mlff-with-espresso-cp-and-lammps.md index 36ac80a61..a6f42567f 100644 --- a/lang/en/docs/tutorials/ml/deepmd-mlff-with-espresso-cp-and-lammps.md +++ b/lang/en/docs/tutorials/ml/deepmd-mlff-with-espresso-cp-and-lammps.md @@ -1,130 +1,89 @@ -# Obtain force field with DeePMD to use in LAMMPS +# Obtain Force Field with DeePMD for LAMMPS -In this tutorial, we demonstrate how to perform large-scale molecular dynamics -simulation using Density Functional Theory, DeePMD, and LAMMPS in Mat3ra web -platform. The workflow consists of the following steps: +This tutorial demonstrates how to perform large-scale molecular dynamics simulation using Density Functional Theory (DFT), DeePMD, and LAMMPS. The workflow consists of the following steps:
    -
  1. Perform *ab-initio* molecular dynamics calculation using Quantum - ESPRESSO Car-Parrinello (cp.x) program
    2. -
  2. Prepare Quantum ESPRESSO output files for DeePMD using - dpdata, split data set into training and validation sets
    3. -
  3. Train DeePMD model, and freeze training results
    4. -
  4. Transform Quantum ESPRESSO structure into LAMMPS format
    5. -
  5. Perform classical molecular dynamics simulation using LAMMPS based on - potential and force fields predicted by DeePMD.
    6. +
  6. Perform ab-initio molecular dynamics using Quantum ESPRESSO Car-Parrinello (cp.x)
    7. +
  7. Prepare Quantum ESPRESSO output files for DeePMD using dpdata, and split the dataset into training and validation sets
    8. +
  8. Train the DeePMD model and freeze the training results
    9. +
  9. Transform the Quantum ESPRESSO structure into LAMMPS format
    10. +
  10. Perform classical molecular dynamics using LAMMPS with the potential and force fields predicted by DeePMD
-## 1. Create Structure +## 1. Create the structure -For this demonstration, we create a new structure from scratch using material -designer. Navigate to **Materials** page from the left sidebar, and click create -new material. We may clone the default structure. +A new structure is created from scratch using the Materials Designer. Navigate to the *Materials* page from the left sidebar and click create new material. The default structure can be cloned as a starting point. ![DeePMD clone structure](../../images/tutorials/deepmd/deepmd-clone-structure.webp "DeePMD clone structure") ![DeePMD edit material](../../images/tutorials/deepmd/deepmd-edit-material.webp "DeePMD edit material") -We use water molecule with simple cubic structure. Set lattice parameters, -atomic positions, and click **apply edits**. Finally, go to **Input/Output** -menu, and save the structure. Alternatively, user can import CIF or POSCAR -structure files. +This example uses a water molecule with simple cubic structure. Set lattice parameters and atomic positions, then click **Apply Edits**. Navigate to the *Input/Output* menu and save the structure. Alternatively, CIF or POSCAR structure files can be imported. -## 2. Create Workflow +## 2. Create the workflow -### 2a. CP calculation +### 2.1. CP calculation -We perform *ab-initio* molecular dynamics calculation using Quantum ESPRESSO -Car-Parrinello (`cp.x`) program. Navigate to workflows page, and click create -new workflow. +The first step performs *ab-initio* molecular dynamics using Quantum ESPRESSO Car-Parrinello (`cp.x`). Navigate to the workflows page and click create new workflow. ![DeePMD create workflow](../../images/tutorials/deepmd/deepmd-create-workflow.webp "DeePMD create workflow") -Click **edit** unit. On the unit modal, expand the details pane, and select -executable to **cp.x** We set `prefix` and unit name to `cp` so that various -output files have the same base name (e.g., cp.out, cp.for, etc.). +Click **Edit** on the unit. In the unit modal, expand the details pane and select `cp.x` as the executable. Set `prefix` and the unit name to `cp` so that output files share the same base name (e.g., cp.out, cp.for). ![DeePMD edit unit](../../images/tutorials/deepmd/deepmd-edit-unit.webp "DeePMD edit unit") ![DeePMD edit unit modal](../../images/tutorials/deepmd/deepmd-edit-unit-modal.webp "DeePMD edit unit modal") -Some of the CP parameters such as the number of steps, time step, etc. can be -set in the **Important Settings** tab. Users can modify or add additional -parameters directly on the template on the unit modal. Close the unit modal, and -return to workflows page. Set Quantum ESPRESSO version (e.g., 7.3) and build -(e.g., GNU). +CP parameters such as the number of steps and time step can be set in the *Important Settings* tab. Additional parameters can be modified directly in the template. Close the unit modal and set the Quantum ESPRESSO version (e.g., 7.3) and build (e.g., GNU). -For the next steps, we need to use another executable (deepmd), so we will add -new subworkflow and select deepmd application. +A new subworkflow is then added with the DeePMD application selected. ![DeePMD add subworkflow](../../images/tutorials/deepmd/deepmd-add-subworkflow.webp "DeePMD add subworkflow") -### 2b. Prepare data sets for DeePMD +### 2.2. Prepare data sets for DeePMD -We will use Python script and `dpdata` to load the Quantum ESPRESSO output files -obtained in the previous CP calculation step. Add first unit to deepmd -subworkflow. +A Python script using `dpdata` loads the Quantum ESPRESSO output files from the CP calculation. Add a unit to the DeePMD subworkflow. ![DeePMD set application and add units](../../images/tutorials/deepmd/deepmd-application-and-units.webp "DeePMD set application and add units") -Select executable to **python** and flavor to **espresso_cp_to_deepmd**. +Select **python** as the executable and **espresso_cp_to_deepmd** as the flavor. ![DeePMD edit python script](../../images/tutorials/deepmd/deepmd-edit-python-script.webp "DeePMD edit python script") -We will split the available number of molecular dynamics steps into training and -validation sets (80% and 20%, respectively). One can modify the python script/ -template directly in the unit modal, and adjust the ratio between sets. +The molecular dynamics steps are split into training and validation sets (80% and 20%, respectively). The ratio can be adjusted by modifying the Python script directly in the unit modal. -### 2c. Run DeePMD model +### 2.3. Train the DeePMD model -We need to specify the descriptor and related model parameters here. Append -another execution unit to deepmd subworkflow. This time select **dp** -executable. Set the descriptor and various model parameters. After the training -step is executed, the output is saved into `graph.pb` file. +Append another execution unit to the DeePMD subworkflow. Select **dp** as the executable and configure the descriptor and model parameters. After training, the output is saved to `graph.pb`. -### 2d. Prepare LAMMPS structure +### 2.4. Prepare the LAMMPS structure -Here we will again use Python script to prepare input structure for LAMMPS -calculation. Again add new executable unit, select **python** executable and -**espresso_to_lammps_structure**. We use `dpdata` to convert the Quantum -ESPRESSO input file in the first step into LAMMPS format. User can extend the -structure, build supercell, or hardcode the structure and save it to -`system.lmp` file. +Add another execution unit with the **python** executable and **espresso_to_lammps_structure** flavor. This script uses `dpdata` to convert the Quantum ESPRESSO input from step 2.1 into LAMMPS format. The structure can be extended, built into a supercell, or hardcoded and saved to `system.lmp`. -### 2e. LAMMPS calculation +### 2.5. LAMMPS calculation -Finally, we perform classical molecular dynamics calculation using LAMMPS. -LAMMPS parameters can be adjusted in `in.lammps` input template. Add the final -unit, and select **lmp** executable. We use deepmd pair style. We can adjust -LAMMPS parameters in the template. The LAMMPS output is written to -`system.dump`. +Add the final unit and select **lmp** as the executable. LAMMPS parameters can be adjusted in the `in.lammps` input template. The DeePMD pair style is used, and the output is written to `system.dump`. ![DeePMD workflow](../../images/tutorials/deepmd/deepmd-workflow.webp "DeePMD workflow") -## 3. Create and submit job +## 3. Create and submit the job -Navigate to Jobs page from the left sidebar. Click create new job. Select -material (in our case, H2O structure we created), select -molecular-dynamics workflow that we created in the previous step. Navigate -**compute** tab adjust compute parameters such as queue, number of nodes and -processors. Submit job for execution. Once the job is completed, various output -files are placed under the **Files** tab of the jobs page. Users may launch a -Jupyter Notebook session in our platform to further analyze output files. +Navigate to the Jobs page from the left sidebar and click create new job. Select the H₂O structure created in step 1 and the molecular dynamics workflow from step 2. Under the *Compute* tab, adjust parameters such as queue, number of nodes, and processors. Submit the job for execution. After completion, output files are available under the *Files* tab. A Jupyter Notebook session can be launched for further analysis. ![DeePMD create job](../../images/tutorials/deepmd/deepmd-create-job.webp "DeePMD create job") -## 4. Step-by-step screenshare video +## 4. Video walkthrough -In the below animation, we walk you through the whole workflow process. +The animation below demonstrates the complete workflow.
- +
diff --git a/lang/en/docs/tutorials/ml/overview.md b/lang/en/docs/tutorials/ml/overview.md index 883c01733..65ad6141d 100644 --- a/lang/en/docs/tutorials/ml/overview.md +++ b/lang/en/docs/tutorials/ml/overview.md @@ -1,18 +1,46 @@ # Machine Learning Tutorials -In the present section, we introduce the basic functionality of the [Machine Learning (ML)](../../models-directory/machine-learning/overview.md) operations supported on our platform, implemented through the [Exabyte Machine Learning Engine](../../software-directory/machine-learning/exabyte/overview.md) component of our [software](../../software/classification/machine-learning.md). +This section covers [Machine Learning]({{ reference_url }}/models-directory/machine-learning/overview/) (ML) workflows on the Mat3ra platform. The tutorials are organized by approach: universal force fields for atomistic simulation, custom potential training, and statistical property prediction. -## Train ML Model -We explain how a **ML model** can be **trained**, based on a set of results of band-gap computations, [in this tutorial page](train-ml-model.md). +## Universal Machine-Learned Force Fields -## Predict New Properties with ML +Pre-trained interatomic potentials that predict energies, forces, and stresses across the periodic table without per-system training. -The ML model trained in the above-mentioned initial tutorial can then be employed to statistically **predict** the band-gap of other similar materials, without the need for further computations. We explain how this can be achieved [in this other tutorial](predict-ml-properties.md). +| Tutorial | Model | Description | +|----------|-------|-------------| +| [MatterSim (Python MLFF)](run-mlff-python-workflows-mattersim.md) | MatterSim | Run pre-trained MatterSim for total energy, relaxation, and phonons — covers bank workflows, custom workflows, GPU execution, and multi-threading | +!!!tip "Running other Python-based models" + Any Python-based MLFF that can be installed via `pip` (e.g. MACE, CHGNet, SevenNet) can be run using the general Python workflow template. See Section 3 of the [MatterSim tutorial](run-mlff-python-workflows-mattersim.md#3-using-the-general-python-template) for the general approach. -## Obtain force field with DeePMD to use in LAMMPS -We explain how large scale molecular dynamics simulation can be performed in our -platform using DFT, DeePMD and LAMMPS - [Molecular dynamics using DeePMD]( -deepmd-mlff-with-espresso-cp-and-lammps.md). +## Custom Potential Training + +Training a neural network potential from first-principles data, then using it for large-scale molecular dynamics. + +| Tutorial | Pipeline | Description | +|----------|----------|-------------| +| [DeePMD (QE → DeePMD → LAMMPS)](deepmd-mlff-with-espresso-cp-and-lammps.md) | QE CP + DeePMD-kit + LAMMPS | End-to-end workflow: generate ab-initio MD data with Quantum ESPRESSO Car–Parrinello, train a DeePMD potential, and run production MD in LAMMPS | + + +## Statistical Property Prediction (Python ML) + +Traditional ML models (regression, classification, clustering) using tabulated materials descriptors and [scikit-learn](https://scikit-learn.org/). These workflows use a dataset (CSV) rather than a crystal structure as input. + +| Tutorial | Task | Description | +|----------|------|-------------| +| [Train a regression model](../python-ml/train-regression-model.md) | Regression | Train a neural network regressor on adsorption energies | +| [Predict with regression](../python-ml/predict-with-regression.md) | Prediction | Apply a trained regression model to new data | +| [Unsupervised clustering](../python-ml/train-clustering-model.md) | Clustering | K-means and hierarchical clustering of materials descriptors | +| [Train a classifier](../python-ml/train-classification-model.md) | Classification | Train a model to classify materials by category | +| [Predict with a classifier](../python-ml/predict-with-classification.md) | Prediction | Apply a trained classifier to new data | + + +## Legacy Tutorials + +!!!warning "Deprecated" + The following tutorial uses the legacy ML engine, which has been superseded by the Python ML infrastructure above. + +- [Train linear regression (legacy)](train-ml-model.md) — uses the older built-in ML engine with Si/Ge band gap data +- [Predict with legacy model](predict-ml-properties.md) — applies a legacy-trained model to predict band gaps diff --git a/lang/en/docs/tutorials/ml/predict-ml-properties.md b/lang/en/docs/tutorials/ml/predict-ml-properties.md index f0fd0f23e..7405b16d5 100644 --- a/lang/en/docs/tutorials/ml/predict-ml-properties.md +++ b/lang/en/docs/tutorials/ml/predict-ml-properties.md @@ -1,48 +1,44 @@ +[//]: # (This tutorial is deprecated) # Machine Learning: Predict New Properties -In the present tutorial page, we will explore how the results of the [Train Model](train-ml-model.md) derived from [Machine Learning (ML)](../../models-directory/machine-learning/overview.md) can be used to predict new material [properties](../../properties/overview.md) by [linear regression](../../methods-directory/linear-regression/overview.md), such as implemented by the [Exabyte Machine Learning Engine](../../software-directory/machine-learning/exabyte/overview.md). +This tutorial demonstrates how the results of the [Train Model](train-ml-model.md) derived from [Machine Learning (ML)]({{ reference_url }}/models-directory/machine-learning/overview/) can be used to predict new material [properties]({{ reference_url }}/properties/overview/) by [linear regression]({{ reference_url }}/methods-directory/linear-regression/overview/). -In the present example, we consider the [Electronic Band Gap](../../properties-directory/non-scalar/band-gaps.md) calculated in the [previous tutorial](train-ml-model.md) for the case of Si/Ge-based materials, however the general approach exposed herein can work for many different **target properties**. +The [Electronic Band Gap]({{ reference_url }}/properties-directory/non-scalar/band-gaps/) calculated in the [training tutorial](train-ml-model.md) for Si/Ge-based materials is used as the example, though the approach works for many different **target properties**. -## Steps -We follow the below steps, by making use of our [Web Interface](../../ui/overview.md). +## 1. Pre-requisite: trained model -1. Pre-requisite: trained model -2. Create "ML Predict" job -3. Select trained model as workflow -4. Select target properties -5. Execute "ML Predict" job -6. View results +This tutorial assumes that an ML model in the [workflow]({{ reference_url }}/workflows/overview/) called "ml_predict" has already been trained to predict the band gap of Si/Ge-based materials, following the steps in the [training tutorial](train-ml-model.md). -## 1. Pre-requisite: Trained Model -The present tutorial assumes that an ML model contained in the [workflow](../../workflows/overview.md) called "ml_predict" has already been trained to predict the band-gap of Si/Ge-based materials, by following the steps outlined in this [other tutorial](train-ml-model.md). +## 2. Create the ML Predict job -## 2. Create "ML Predict" Job +A new "ML Predict" [Job]({{ reference_url }}/jobs/overview/) can be set up by following the general instructions for [creating a new Job]({{ interface_url }}/jobs-designer/overview/). -The general instructions for [creating a new Job](../../jobs-designer/overview.md) can be followed for setting up a new "ML Predict" [Job](../../jobs/overview.md), after [opening](../../jobs/actions/create.md) the relevant interface. - -## 3. Select Trained Model as Workflow - -The aforementioned "ml_predict" workflow should be [selected](../../jobs-designer/actions-header-menu/select-workflow.md) as the main [Workflow](../../jobs-designer/workflow-tab.md) for the "ML Predict" Job being designed, so that it can be applied to predict the properties of a new set of target [materials](../../jobs-designer/materials-tab.md) similar to the ones used originally to train the model. -## 4. Select Target Properties +## 3. Select the trained model as workflow -The properties which will be predicted by a trained model are the **target properties** which have been ticked and selected under the [unit editor interface](../../workflow-designer/unit-editor.md) of the "input" [unit](../../workflows/components/units.md) of the "ml_predict" workflow, under the "Targets" section of the interface. +The "ml_predict" workflow should be [selected]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) as the main [Workflow]({{ interface_url }}/jobs-designer/workflow-tab/) for the job. This applies the trained model to predict properties of new [materials]({{ interface_url }}/jobs-designer/materials-tab/) similar to those used in training. -## 5. Execute "ML Predict" Job -The reader should follow [these instructions](../../jobs/actions/run.md) in order to finally execute the "ML Predict" job, following its creation with [Job Designer](../../jobs-designer/overview.md). +## 4. Select the target properties -## 6. View Results +The properties to be predicted are the **target properties** selected under the [unit editor]({{ interface_url }}/workflow-designer/unit-editor/) of the "input" [unit]({{ reference_url }}/workflows/components/units/) of the "ml_predict" workflow, in the "Targets" section. -The newly predicted properties can finally be inspected under the [results tab](../../jobs/ui/results-tab.md) of [job viewer](../../jobs/ui/viewer.md). -## Animation +## 5. Submit the job -In the following animation, we demonstrate how the above steps can be followed to predict the band-gap of a new set of Si/Ge-based materials, using the model trained in a [previous tutorial](train-ml-model.md). For the sake of this example, we predict the bang-gap for the Si4Ge12 stochiometric composition. The results of the ML prediction for both the direct and indirect band gaps (0.525 and 0.490 - eV respectively) are in very good agreement with the values of their direct computation using [DFT](../../models-directory/dft/overview.md) (0.517 and 0.441 eV respectively). +The "ML Predict" job can be [executed]({{ interface_url }}/jobs/actions/run/) after configuration in [Job Designer]({{ interface_url }}/jobs-designer/overview/). + + +## 6. View the results + +The predicted properties are available under the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). + + +## 7. Video walkthrough + +The animation below demonstrates predicting the band gap of Si₄Ge₁₂ using the model trained in the [training tutorial](train-ml-model.md). The ML-predicted direct and indirect band gaps (0.525 and 0.490 eV) are in good agreement with the [DFT]({{ reference_url }}/models-directory/dft/overview/)-calculated values (0.517 and 0.441 eV).
diff --git a/lang/en/docs/tutorials/ml/run-mlff-python-workflows-mattersim.json b/lang/en/docs/tutorials/ml/run-mlff-python-workflows-mattersim.json new file mode 100644 index 000000000..5fcd97267 --- /dev/null +++ b/lang/en/docs/tutorials/ml/run-mlff-python-workflows-mattersim.json @@ -0,0 +1,257 @@ +{ + "descriptionLinks": [ + "Running Python-based ML workflows in Mat3ra platform: https://docs.mat3ra.com/tutorials/ml/run-mlff-python-workflows-mattersim/" + ], + "description": "How to run Python-based ML workflows in Mat3ra platform.", + "tags": [ + { + "...": "../../metadata/general.json#/tags" + }, + { + "...": "../../software/classification/machine-learning.json#/tags" + }, + "Machine Learning Force Field", + "MLFF", + "MatterSim", + "Python" + ], + "title": "Mat3ra Tutorial: Running Python-based ML workflows in Mat3ra platform", + "youTubeCaptions": [ + { + "text": "Here we will discuss how to run Python-based machine learning models in Matera platform.", + "startTime": "00:00:00.250", + "endTime": "00:00:05.000" + }, + { + "text": "The easiest way to get started is by importing an existing workflow from Matera workflow bank.", + "startTime": "00:00:05.500", + "endTime": "00:00:10.000" + }, + { + "text": "If the desired workflow is not available, we can create a new workflow and select one of our available ML templates.", + "startTime": "00:00:10.500", + "endTime": "00:00:19.000" + }, + { + "text": "If neither the workflow nor the template is found, we can always start from our general purpose Python workflow and provide our Python code and dependencies.", + "startTime": "00:00:19.500", + "endTime": "00:00:29.000" + }, + { + "text": "Now, let's switch to platform dot matera dot com, and see how these various options work in practice.", + "startTime": "00:00:29.500", + "endTime": "00:00:35.000" + }, + { + "text": "First, let's explore how to import an existing workflow from the bank.", + "startTime": "00:00:35.500", + "endTime": "00:00:40.000" + }, + { + "text": "Navigate to the workflow bank and search for 'MatterSim'.", + "startTime": "00:00:40.500", + "endTime": "00:00:43.000" + }, + { + "text": "Before we can use these workflows to create a job, we need to copy them to our account collection.", + "startTime": "00:00:49.000", + "endTime": "00:00:55.000" + }, + { + "text": "Once copied, they will appear under the workflows tab.", + "startTime": "00:00:56.000", + "endTime": "00:00:59.000" + }, + { + "text": "We can open a workflow to inspect and edit it to our needs.", + "startTime": "00:01:00.000", + "endTime": "00:01:03.000" + }, + { + "text": "As we see here, MatterSim total energy workflow consists of three units.", + "startTime": "00:01:03.500", + "endTime": "00:01:08.000" + }, + { + "text": "The first unit: I O material gets the material data from the job context.", + "startTime": "00:01:08.500", + "endTime": "00:01:14.000" + }, + { + "text": "The result is an array of materials.", + "startTime": "00:01:14.500", + "endTime": "00:01:17.000" + }, + { + "text": "The second unit: takes the first item of the 'data' array and assign to another variable named 'material'.", + "startTime": "00:01:17.500", + "endTime": "00:01:24.000" + }, + { + "text": "Finally, the MatterSim unit: uses this material definition to predict its total energy, stress, and other properties.", + "startTime": "00:01:24.500", + "endTime": "00:01:32.000" + }, + { + "text": "Besides the main input script, the MatterSim unit also has a utility script and Python requirements file.", + "startTime": "00:01:32.500", + "endTime": "00:01:39.000" + }, + { + "text": "We can add additional python packages to the requirements file if needed by our python script.", + "startTime": "00:01:39.500", + "endTime": "00:01:46.000" + }, + { + "text": "Once happy with the changes, save and exit the workflow.", + "startTime": "00:01:46.500", + "endTime": "00:01:49.000" + }, + { + "text": "Next, navigate to the job designer page, and click 'create' new job let it be under the default project.", + "startTime": "00:01:49.500", + "endTime": "00:01:55.000" + }, + { + "text": "As we see here, the jobs page is consists of three sections: material, workflow and compute parameters.", + "startTime": "00:01:55.500", + "endTime": "00:02:03.000" + }, + { + "text": "For this demonstration, we will select 'nickel' slab as the material.", + "startTime": "00:02:03.500", + "endTime": "00:02:07.000" + }, + { + "text": "Then we can select the workflow, which in this case is the 'MatterSim' workflow we just imported.", + "startTime": "00:02:07.500", + "endTime": "00:02:13.000" + }, + { + "text": "Let's rename the job to 'MatterSim total energy'.", + "startTime": "00:02:13.500", + "endTime": "00:02:16.000" + }, + { + "text": "Depending on our compute needs, we may adjust compute parameters such as cluster, queue, number of processors, time limit, etc.", + "startTime": "00:02:16.500", + "endTime": "00:02:24.000" + }, + { + "text": "Finally, save and exit the job designer page.", + "startTime": "00:02:24.500", + "endTime": "00:02:28.000" + }, + { + "text": "Now we are ready to submit the job for execution.", + "startTime": "00:02:28.500", + "endTime": "00:02:31.000" + }, + { + "text": "Once the job is completed, a summary of output properties will be shown in the 'results' tab.", + "startTime": "00:02:31.500", + "endTime": "00:02:37.000" + }, + { + "text": "All input and output files are available under the 'Files' tab. We can preview or download them for further analysis.", + "startTime": "00:02:37.500", + "endTime": "00:02:44.000" + }, + { + "text": "Next: let's move to option two: this time instead of using a pre-existing workflow, we will create a new workflow.", + "startTime": "00:02:44.500", + "endTime": "00:02:52.000" + }, + { + "text": "Let's call it cell relaxation mattersim, select Python as application, add an execution unit, edit unit, and select 'MatterSim cell relaxation' flavor categorized under machine learning force field.", + "startTime": "00:02:52.500", + "endTime": "00:03:07.000" + }, + { + "text": "In this case, we do not want to get our materials information from the job context, instead we want to define it using 'A S E' library for demonstration purpose.", + "startTime": "00:03:07.500", + "endTime": "00:03:16.000" + }, + { + "text": "Here we specify gallium nitride with wurtzite structure.", + "startTime": "00:03:16.500", + "endTime": "00:03:21.000" + }, + { + "text": "Once the workflow is created, we can create and run jobs same way as we did in the previous step.", + "startTime": "00:03:21.500", + "endTime": "00:03:27.000" + }, + { + "text": "In this case, a side by side comparison of initial and relaxed structures is shown in the 'Results' tab.", + "startTime": "00:03:27.500", + "endTime": "00:03:34.000" + }, + { + "text": "Initial and final structures are also saved in cif and poscar formats as listed in the 'Files' tab.", + "startTime": "00:03:34.500", + "endTime": "00:03:41.000" + }, + { + "text": "Next: let's discuss how we can run our ML models using GPU acceleration.", + "startTime": "00:03:41.500", + "endTime": "00:03:46.000" + }, + { + "text": "This time, , we create a job using mattersim phonon dispersion workflow.", + "startTime": "00:03:46.500", + "endTime": "00:03:50.000" + }, + { + "text": "For debugging purpose, we print whether the job is running on GPU or CPU.", + "startTime": "00:03:50.500", + "endTime": "00:03:54.000" + }, + { + "text": "Most importantly, in this case, we have to select one of our GPU queues, such as 'G O F' under the compute tab.", + "startTime": "00:03:54.500", + "endTime": "00:04:04.000" + }, + { + "text": "Once the job is done, both phonon dispersion and phonon density of states plots are shown in the 'Results' tab.", + "startTime": "00:04:04.500", + "endTime": "00:04:08.000" + }, + { + "text": "We can open the standard output under the 'Files' tab and verify that the job is indeed ran on GPU.", + "startTime": "00:04:08.500", + "endTime": "00:04:17.000" + }, + { + "text": "Finally, let's discuss how we can run any other Python-based machine learning model that is not available in matera platform.", + "startTime": "00:04:17.500", + "endTime": "00:04:26.000" + }, + { + "text": "In that case, we can select our general Python template, specify all necessary dependencies in the requirements file, and write our python script accordingly.", + "startTime": "00:04:26.500", + "endTime": "00:04:37.000" + }, + { + "text": "As long as our M L model is Python-based, and dependencies can be installed using 'pip', we can run it in Matera platform.", + "startTime": "00:04:37.250", + "endTime": "00:04:44.000" + }, + { + "text": "If your model can use multi-threading, you can specify necessary environment variables on top of your python script.", + "startTime": "00:04:44.500", + "endTime": "00:04:52.000" + }, + { + "text": "Now, please visit platform dot matera dot com to try it out yourself.", + "startTime": "00:04:52.500", + "endTime": "00:04:56.000" + }, + { + "text": "Thank you for watching this tutorial and using Matera platform.", + "startTime": "00:04:56.250", + "endTime": "00:05:00.000" + } + ], + "youTubeId": "DBW3KjdtRyc" +} diff --git a/lang/en/docs/tutorials/ml/run-mlff-python-workflows-mattersim.md b/lang/en/docs/tutorials/ml/run-mlff-python-workflows-mattersim.md new file mode 100644 index 000000000..c96c338be --- /dev/null +++ b/lang/en/docs/tutorials/ml/run-mlff-python-workflows-mattersim.md @@ -0,0 +1,236 @@ +# Running MatterSim and Other Python-Based Machine Learning Models + +[MatterSim](https://github.com/microsoft/mattersim) is a deep-learning +interatomic potential trained across the periodic table for materials property +prediction. This page describes how to run MatterSim and other Python-based +Machine Learning (ML) models on the Mat3ra platform, using three approaches of +increasing customization: + +1. Using a pre-built [workflow]({{ reference_url }}/workflows/overview/) from the +[Mat3ra bank]({{ reference_url }}/workflows/bank/). +2. Creating a new workflow from one of the available MatterSim +flavors/templates. +3. Using the general Python flavor/template and supplying the +dependencies through `requirements.txt`. + +The page also covers running jobs on a Graphics Processing Unit (GPU) and +using multi-threading, and closes with a step-by-step video walkthrough. + +## 1. Using a bank workflow + +A common approach is to import an existing workflow from the [Mat3ra bank]({{ reference_url }}/workflows/bank/) into the user's account. + +### 1.1. Import a bank workflow + +First, navigate to the *Workflows Bank* page from the left sidebar. Then, search +for `MatterSim` and click **Copy** in the *Action* column on the desired +workflow (e.g. *MatterSim total energy*). See [Copy bank workflow]({{ interface_url }}/workflows/actions/copy-bank/) for details. + +![Copy bank workflow](../../images/tutorials/mattersim/mattersim-bank-workflow.webp "Copy bank workflow") + +The workflow then appears in the user's *Workflows* list and becomes available +for selection during job creation. It can be opened for inspection or further +modification. + +The *MatterSim total energy* workflow consists of three [units]({{ reference_url }}/workflows/components/units/): + +- **I/O Material unit:** fetches the input materials from the job context. Its +output is an array of materials. +- **Assignment unit:** takes the first item of that array and assigns it to a +new global variable named `MATERIAL`. +- **MatterSim unit:** builds an [Atomic Simulation Environment(ASE)]( +https://wiki.fysik.dtu.dk/ase/) material definition from `MATERIAL` and runs +MatterSim to predict the total energy (eV), stress, and other properties. + +In addition to the main `script.py`, the MatterSim unit exposes a `utils.py` +helper script and a `requirements.txt` file. Extra Python packages required by +the script can be added to `requirements.txt`. + +![MatterSim workflow units](../../images/tutorials/mattersim/mattersim-workflow.webp "MatterSim workflow units") + +### 1.2. Create and submit a job + +First, open the [Jobs Designer]({{ interface_url }}/jobs-designer/overview/) from the left +sidebar and click **Create New Job** (see [Create job]({{ interface_url }}/jobs/actions/create/)). The page is organized in three sections: +[material]({{ interface_url }}/jobs-designer/materials-tab/), [workflow]({{ interface_url }}/jobs-designer/workflow-tab/), and [compute parameters]({{ interface_url }}/jobs-designer/compute-tab/). + +In the **Select Job Actions** drop-down, choose the material and the workflow: + +- **Material:** any structure is acceptable; the default is Silicon, while the +video walkthrough below uses a nickel slab. +- **Workflow:** the *MatterSim total energy* workflow imported in the +previous section. + +The job can be renamed (e.g. *MatterSim total energy*) and the +[compute parameters]({{ interface_url }}/jobs-designer/compute-tab/) (cluster, queue, +number of processors, time limit, and others) can be adjusted under the +*Compute* section. Save and exit the Jobs Designer. + +![MatterSim job creation](../../images/tutorials/mattersim/mattersim-job.webp "MatterSim job creation") + +Click **Run** in the *Actions* column to [submit]({{ interface_url }}/jobs/actions/run/) +the job. + +### 1.3. View the results + +Once the job completes, the [Job Viewer]({{ interface_url }}/jobs/ui/viewer/) shows the +results: + +- The [*Results* tab]({{ interface_url }}/jobs/ui/results-tab/) shows a summary of the +predicted output properties. +- The *Workflow* tab → *MatterSim* unit exposes the standard output (raw +log). +- The [*Files* tab]({{ interface_url }}/jobs/ui/files-tab/) lists every input and output +file for preview or download. + +![MatterSim total energy results](../../images/tutorials/mattersim/mattersim-results-total-energy.webp "MatterSim total energy results") + + +## 2. Creating a new workflow + +When the desired workflow is not available in the bank, a new one can be built +from an existing MatterSim flavor/template. The example below creates a +*cell relaxation* workflow from scratch. + +### 2.1. Open the Workflow Designer and Unit Editor + +First, open the [Workflows]({{ reference_url }}/workflows/overview/) page and click +**Create** to start a new workflow. Expand the *Details* section and select +**Python Script** as the application. Then, add an **Executable** unit and click +**EDIT** to open the [Unit Editor]({{ interface_url }}/workflow-designer/unit-editor/). + +![MatterSim add unit](../../images/tutorials/mattersim/mattersim-add-unit.webp "MatterSim add unit") + +In the Unit Editor, expand the *Details* section and select +`mlff:mattersim:cell_relaxation` (under the *Machine Learning Force Field* +category) as the flavor. + +![MatterSim edit unit](../../images/tutorials/mattersim/mattersim-edit-unit.webp "MatterSim edit unit") + +### 2.2. Modify the unit script + +Scroll down to edit the Python script if necessary. For example, to use ASE to +build the input material directly (instead of pulling it from the job context), +the material section can be replaced with: + +```python title="SCRIPT.PY" +... +from ase.build import bulk +# Lattice constants in Angstrom (Å) +ase_atoms = bulk("GaN", "wurtzite", a=3.189, c=5.185) +... +``` + +where `GaN` denotes Gallium Nitride. + +Close the Unit Editor by clicking the **X** button in the top right, then save +and exit the workflow editor. + +### 2.3. Create and run a job + +Finally, create and run a job using this workflow as explained in Section 1 +above. + +Once the job completes, the *Results* tab shows a side-by-side comparison of the +initial and relaxed structures, and the *Files* tab contains both structures in +`.cif` and `.poscar` formats. + +![MatterSim cell relaxation results](../../images/tutorials/mattersim/mattersim-results-cell-relaxation.webp "MatterSim cell relaxation results") + +## 3. Using the general Python template + +To run any Python-based ML model that is not covered by an existing workflow or +flavor, the general Python flavor/template can be used. + +### 3.1. Create a new workflow from a template + +Create a new workflow as in the previous section and select the default `python` +flavor/template. Then, add the dependencies in the `requirements.txt` tab +and write the code in the `script.py` tab. + +![General Python template](../../images/tutorials/mattersim/general-py-template.webp "General Python template") + +### 3.2. Set up dependencies + +As long as the model is Python-based and its dependencies can be installed via +`pip`, it runs on the Mat3ra platform. + +!!!info "Shared virtual environment" + Python virtual environments are shared across jobs and users. As long as the + content (hash/fingerprint) of `requirements.txt` is unchanged, the same + environment is reused. The first job may take longer to complete because of + `pip install`, but subsequent runs start faster as no install is required. + If the expected versions of the dependencies are not picked up, they should + be pinned explicitly in `requirements.txt`. + +!!!tip "Multi-threading" + If the model can use multi-threading, the relevant environment variables + should be set at the top of the script, before importing NumPy or any other + library that uses them. + + ```python title="SCRIPT.PY" + import os + + # Number of CPU threads + ncore = "2" + + # Must be set before importing numpy or other thread-aware libraries + os.environ["OMP_NUM_THREADS"] = ncore + os.environ["OPENBLAS_NUM_THREADS"] = ncore + os.environ["MKL_NUM_THREADS"] = ncore + os.environ["VECLIB_MAXIMUM_THREADS"] = ncore + os.environ["NUMEXPR_NUM_THREADS"] = ncore + ``` + +### 3.3. Create and run a job + +Just as in Sections 1 and 2 above, create and run a job using this workflow. + +## 4. Notes about running on GPU + +Because MatterSim is a [PyTorch](https://pytorch.org/)-based model, it benefits +significantly from GPU execution. To run a MatterSim job on GPU, it should be +submitted to one of the platform's GPU queues, for example the `GOF` queue on +the [Google Cloud cluster]({{ resources_url }}/infrastructure/clusters/google/) (internal identifier +`Cluster-001`). + +### 4.1. Confirm GPU availability + +To verify that the job actually runs on GPU, a debug print can be added to the +script, and the standard output can be inspected under the *Files* tab once the +job completes: + +```python title="SCRIPT.PY" +import torch + +print("Using GPU:", torch.cuda.is_available()) +``` + +For non-PyTorch frameworks, the equivalent check should be used (for example, +`tf.config.list_physical_devices('GPU')` for TensorFlow). + +### 4.2. Example results + +Once the run completes, the *Results* tab shows the phonon dispersion and the +phonon density-of-states plots. + +![MatterSim phonon dispersion results](../../images/tutorials/mattersim/mattersim-results-phonon.webp "MatterSim phonon dispersion results") + + +## 5. Video walkthrough + +The animation below walks through the entire flow on the platform. + +
+ +
+ + +## 6. References + +- Yang, H. *et al.* "MatterSim: A Deep Learning Atomistic Model Across Elements, + Temperatures and Pressures." *arXiv:2405.04967* (2024). + [arxiv.org/abs/2405.04967](https://arxiv.org/abs/2405.04967) +- [MatterSim GitHub repository](https://github.com/microsoft/mattersim) +- [MatterSim documentation](https://microsoft.github.io/mattersim/) +- [Atomic Simulation Environment (ASE)](https://wiki.fysik.dtu.dk/ase/) diff --git a/lang/en/docs/tutorials/ml/train-ml-model.md b/lang/en/docs/tutorials/ml/train-ml-model.md index 6faefd74b..875822d41 100644 --- a/lang/en/docs/tutorials/ml/train-ml-model.md +++ b/lang/en/docs/tutorials/ml/train-ml-model.md @@ -1,73 +1,65 @@ # Machine Learning: Train Linear Regression -This tutorial demonstrates how to build a [machine learning (ML)](../../models-directory/machine-learning/overview.md) **training model** based upon a set of [materials](../../materials/overview.md) called **"train materials"**. This model can then be used to predict the [properties](../../properties/overview.md) of another set called **"target materials"**, based on the procedure outlined in a [separate tutorial](predict-ml-properties.md). +!!!warning "Deprecated tutorial" + This tutorial uses the legacy ML engine. For current Machine Learning workflows, see [Python ML tutorials](../python-ml/train-regression-model.md) or the [MatterSim tutorial](run-mlff-python-workflows-mattersim.md). -We consider the [Electronic Band Gap](../../properties-directory/non-scalar/band-gaps.md) in the present example, however the general approach can work for many different **target properties**. +This tutorial demonstrates how to build a [machine learning (ML)]({{ reference_url }}/models-directory/machine-learning/overview/) **training model** from a set of [materials]({{ reference_url }}/materials/overview/) called **"train materials"**. The model can then predict the [properties]({{ reference_url }}/properties/overview/) of another set called **"target materials"**, as described in a [separate tutorial](predict-ml-properties.md). -## Training Set +The [Electronic Band Gap]({{ reference_url }}/properties-directory/non-scalar/band-gaps/) is the target property in this example, though the general approach works for many different properties. -For the sake of the present tutorial example, we will consider the following stochiometric combinations of the elements silicon (Si) and germanium (Ge) to train our ML model for predicting the band-gap. These structures all contain a total of 16 atoms, in the form of a 2x2x2 [supercell](../../materials-designer/header-menu/advanced/supercell.md) of the cubic-diamond primitive unit cell, and can be generated through the help of [combinatorial sets](../../materials-designer/header-menu/advanced/combinatorial-set.md) via [Materials Designer](../../materials-designer/overview.md). -- Si2 Ge14 -- Si6 Ge10 -- Si8 Ge8 -- Si10 Ge6 -- Si12 Ge4 -- Si14 Ge2 +## 1. Prepare the training set -## Targets +The following stoichiometric combinations of silicon (Si) and germanium (Ge) are used to train the ML model. These structures each contain 16 atoms in a 2×2×2 [supercell]({{ interface_url }}/materials-designer/header-menu/advanced/supercell/) of the cubic-diamond primitive unit cell, and can be generated using [combinatorial sets]({{ interface_url }}/materials-designer/header-menu/advanced/combinatorial-set/) via [Materials Designer]({{ interface_url }}/materials-designer/overview/): -In [this other tutorial](predict-ml-properties.md), we explain how the model trained with the above materials can be used to predict the band-gap of another similar target composition, consisting in Si4Ge12. +- Si₂Ge₁₄ +- Si₆Ge₁₀ +- Si₈Ge₈ +- Si₁₀Ge₆ +- Si₁₂Ge₄ +- Si₁₄Ge₂ -## Steps +The trained model can then predict the band gap of a target composition such as Si₄Ge₁₂, as described in [this tutorial](predict-ml-properties.md). -We follow the below steps, by making use of our [Web Interface](../../ui/overview.md). -1. Obtain Training Data -2. Build ML Train model based on the "train materials" -3. Inspect Trained Model +## 2. Obtain training data -## 1. Obtain Training Data +### 2.1. Copy the workflow from the bank -### Copy Workflow from Bank +A pre-assembled [workflow]({{ reference_url }}/workflows/overview/) for band gap calculations can be imported from the [Workflow Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/). The import procedure is described [in this page]({{ interface_url }}/workflows/actions/copy-bank/). -The user can import a pre-assembled [workflow](../../workflows/overview.md) for calculating the band-gap of materials directly from the [Workflow Bank](../../workflows/bank.md) into the account-owned [collection](../../accounts/collections.md). We explain the procedure for doing so [in this page](../../workflows/actions/copy-bank.md). +### 2.2. Create and run the job -### Create and Run Job +Create a new [Job]({{ reference_url }}/jobs/overview/) using the [Job Designer]({{ interface_url }}/jobs-designer/overview/). [Select]({{ interface_url }}/jobs-designer/actions-header-menu/select-materials/) all Si/Ge materials from the account-owned [collection]({{ reference_url }}/accounts/collections/) and add them to the job. Under the [Workflow Tab]({{ interface_url }}/jobs-designer/workflow-tab/), [select]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) the band gap workflow imported in the previous step. The job can then be [executed]({{ interface_url }}/jobs/actions/run/). -Once the appropriate workflow has been copied from the Bank, we can proceed with the creation of a new [Job](../../jobs/overview.md) -using the [Job Designer interface](../../jobs-designer/overview.md). We first need to [select](../../jobs-designer/actions-header-menu/select-materials.md) all the aforementioned materials containing Si and Ge from the account-owned materials [collection](../../accounts/collections.md), and thus add them to the job being created. -Under the [Workflow Tab](../../jobs-designer/workflow-tab.md) of Job Designer, we then need to [select](../../jobs-designer/actions-header-menu/select-workflow.md) the band-gap workflow imported previously. At this point, the Job can be [executed](../../jobs/actions/run.md) for the computation of the band-gap for our set of Si/Ge-based materials. +## 3. Build and train the model -## 2. Build/Train a Model +The "ML Train Model" workflow can be imported from the Bank by following the same [import procedure]({{ interface_url }}/workflows/actions/copy-bank/). Create a new [Job]({{ reference_url }}/jobs/overview/), selecting the "ML Train Model" workflow together with the Si/Ge materials for which the band gap was calculated. This allows the ML engine to build a model from the band gap data, which can then [predict](predict-ml-properties.md) band gaps of similar materials. -The "ML Train Model" Workflow can be imported from the Bank into the account-owned collection by repeating the procedure outlined [here](../../workflows/actions/copy-bank.md). +The [target properties]({{ reference_url }}/properties/classification/machine-learning/) (band gap in this case) can be selected by opening the [unit editor]({{ interface_url }}/workflow-designer/unit-editor/) for the "input" [unit]({{ reference_url }}/workflows/components/units/) and scrolling to the "Targets" section. -The user should then repeat the same procedure for [creating and executing](../../jobs-designer/overview.md) a new [Job](../../jobs/overview.md) as the preceding step, selecting the "ML Train Model" Workflow this time in conjunction with the Si/Ge-containing materials for which the band gap was calculated previously. This allows the [Exabyte Machine Learning Engine](../../software-directory/machine-learning/exabyte/overview.md) to build the ML Train Model based upon the results of such band gap computations, which can then be used to [predict](predict-ml-properties.md) the band gaps of other similar materials. -The [target properties](../../properties/classification/machine-learning.md) (the band gap in this case) can be selected by opening the [unit editor](../../workflow-designer/unit-editor.md) for the "input" [unit](../../workflows/components/units.md) of the "ML Train Model" Workflow, and scrolling down to the "Targets" section within the editor interface. +## 4. Inspect the trained model -## 3. Inspect Trained Model +### 4.1. Retrieve the predict workflow -### Model Stored as Workflow +Once the model is trained, a new [Workflow]({{ reference_url }}/workflows/overview/) called **"ml_predict"** is generated and can be retrieved under the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). This workflow is automatically saved to the account-owned [collection]({{ reference_url }}/accounts/collections/) and can be used to **predict** properties of new materials without further physics-based simulations. The prediction procedure is described [in a separate tutorial](predict-ml-properties.md). -Once the ML Train Model has been built, a new [Workflow](../../workflows/overview.md) called **"ml_predict"** is generated and can be retrieved under the [results tab](../../jobs/ui/results-tab.md) of [job viewer](../../jobs/ui/viewer.md) for the ML train job. +### 4.2. View model coefficients -This "ml_predict" workflow is automatically saved to the account-owned [collection](../../accounts/collections.md) of workflows, visible through [Workflow Explorer](../../workflows/ui/explorer.md). It can subsequently be used at the moment of [creation of a new Job](../../jobs-designer/overview.md), to **predict** the properties (such as the band-gap) of new materials based upon statistical considerations formed from the trained model, without consequently the need for further physics-based simulations. We explain the procedure to perform such predictions [in a separate tutorial page](predict-ml-properties.md). +Open the "ml_predict" workflow and view the "Score" [unit]({{ reference_url }}/workflows/components/units/) in the [unit editor]({{ interface_url }}/workflow-designer/unit-editor/), where model coefficients, feature importance, and model **precision** [^1] are stored. -### Model Coefficients -Opening the "ml_predict" Workflow allows the user to view the "Score" [unit](../../workflows/components/units.md) under the corresponding [unit editor interface](../../workflow-designer/unit-editor.md), where the model coefficients and importance are stored, together with an indication of the model **precision** [^1]. +## 5. Video walkthrough -## Animation - -We demonstrate the [Web Interface](../../ui/overview.md)-based procedure involved in building and then inspecting the ML Train Model in the animation below. +The animation below demonstrates the full procedure for building and inspecting an ML Train Model.
-## Links -[^1]: [Wikipedia Coefficient of determination, Website](https://en.wikipedia.org/wiki/Coefficient_of_determination) +## 6. Links + +[^1]: [Wikipedia, Coefficient of determination](https://en.wikipedia.org/wiki/Coefficient_of_determination) diff --git a/lang/en/docs/tutorials/other/external-upload.json b/lang/en/docs/tutorials/other/external-upload.json deleted file mode 100644 index baa0536f7..000000000 --- a/lang/en/docs/tutorials/other/external-upload.json +++ /dev/null @@ -1,80 +0,0 @@ -{ - "descriptionLinks": [ - "Upload External Data: https://docs.mat3ra.com/tutorials/other/external-upload/" - ], - "description": "This tutorial demonstrates how external command-line calculation data can be uploaded to Exabyte Platform to be parsed and organized.", - "tags": [ - { - "...": "../../metadata/general.json#/tags" - } - ], - "title": "Exabyte.io Tutorial: Upload External Job Data", - "youTubeCaptions": [ - { - "text": "Upload External Data tutorial.", - "endTime": "00:00:02.000", - "startTime": "00:00:00.000" - }, - { - "text": "Here's a folder containing data for an example VASP calculation. It contains a flat list of files, including this FCC Germanium structure.", - "endTime": "00:00:10.000", - "startTime": "00:00:02.500" - }, - { - "text": "Let us now compress the files into a zip archive, that we will use to initiate an External Upload.", - "endTime": "00:00:16.500", - "startTime": "00:00:10.500" - }, - { - "text": "Next, we open the Exabyte platform and navigate to the External Uploads page.", - "endTime": "00:00:21.000", - "startTime": "00:00:17.000" - }, - { - "text": "From here, we open the upload dialog and fill in the upload information form.", - "endTime": "00:00:24.000", - "startTime": "00:00:21.500" - }, - { - "text": "Pay attention to the Job Script File and Standard Output File, as their content will be visible upon completion.", - "endTime": "00:00:33.500", - "startTime": "00:00:24.500" - }, - { - "text": "Let's select the archive we prepared earlier and submit the form.", - "endTime": "00:00:40.500", - "startTime": "00:00:37.500" - }, - { - "text": "The upload task will become active, and will shortly finish, turning from orange to green.", - "endTime": "00:00:51.500", - "startTime": "00:00:46.500" - }, - { - "text": "Next, we find the newly created Job inside the External project. Let's open the projects page and navigate to 'External'. The new job is the last entry.", - "endTime": "00:01:06.000", - "startTime": "00:00:57.000" - }, - { - "text": "Open the job. It contains the results (properties) and material information extracted from the uploaded data.", - "endTime": "00:01:18.000", - "startTime": "00:01:10.000" - }, - { - "text": "All job files are now also available on the platform.", - "endTime": "00:01:34.000", - "startTime": "00:01:31.500" - }, - { - "text": "The input and output for the workflow are extracted too, as we hereby demonstrate.", - "endTime": "00:01:41.500", - "startTime": "00:01:37.500" - }, - { - "text": "This is how one can upload external data to the Exabyte platform.", - "endTime": "00:01:47.500", - "startTime": "00:01:42.500" - } - ], - "youTubeId": "oxTm1a4qnLQ" -} diff --git a/lang/en/docs/tutorials/other/external-upload.md b/lang/en/docs/tutorials/other/external-upload.md deleted file mode 100644 index 2fe999566..000000000 --- a/lang/en/docs/tutorials/other/external-upload.md +++ /dev/null @@ -1,54 +0,0 @@ -# Upload an External command-line Job - -This page explains how to initiate an [External Upload](../../external/overview.md) to parse and organize a folder with a data from an external calculation. - -## Notes - -In the present example we use example data from a [VASP](../../software-directory/modeling/vasp/overview.md) calculation, however the directives work for other simulation engines too. - -The platform will attempt to extract the [Entities](../../entities-general/overview.md), such as [Materials](../../materials/overview.md) and [Properties](../../properties/overview.md) from the calculation data in failsafe manner. - -## Prepare an archive - -First, arrange all the files inside a folder. Then create a .zip archive with the data. On a UNIX-based operating system this could be done in command line or righ-hand context menu. The command-line routine could be, for example: - -```bash -cd JOB_DIRECTORY -zip -r9 ../archive.zip . -``` - -## Upload archive - -### Open Upload Dialog - -Navigate to the [External Uploads Explorer](../../external/ui/explorer.md) page and initiate the upload task [creation](../../external/actions/create.md). Inside the Upload Dialog one can set the name of the and its human-readable description as desired. These will be used for the Job created inside the [External Project](../../jobs/projects.md#external-project) when the upload is complete. - -### Fill the form data - -Pay attention to the [job script file](../../external/actions/create.md#job-script-file) and the [standard output](../../external/actions/create.md#standard-output-file). They will be used as the input/output files for the job accordingly. - -### Submit the dialog - -Use the file selector to select the archive prepared in the previous step. When finished, click "Submit" button to initiate the upload. - -## View the External Job - -### Wait for the task to finish - -The [status](../../external/status.md) of the upload will be set to "A" - active, while the upload task is in progress. When the task finished, the status will change to "F" - finished. - -### Navigate into External Project - -In order to view the job, navigate into the list of Projects from the [Left-hand sidebar](../../ui/left-sidebar.md#), then navigate into the [External Project](../../jobs/projects.md#external-project). - -### View the latest Job - -The latest job inside the project is the one containing the uploaded data. The platform will attempt to extract the Materials, Properties, input/output files and administrative information about the job and make it available in the same manner as for the jobs originating inside the platform. - -## Animation - -In the following animation, we demonstrate the above-mentioned steps: we create a non-nested ".zip" archive from the calculation data, upload it to the platform and view the Job (with Materials and Properties) created inside the "External" project as a result. - -
- -
diff --git a/lang/en/docs/tutorials/other/jupyter.md b/lang/en/docs/tutorials/other/jupyter.md index 4728c29fb..0a8d6e92b 100644 --- a/lang/en/docs/tutorials/other/jupyter.md +++ b/lang/en/docs/tutorials/other/jupyter.md @@ -1,53 +1,64 @@ # Jupyter Notebook -This tutorial page explains how to create a Jupyter Notebook environment through [Jupyter Lab](../../software-directory/scripting/jupyter-lab/overview.md) application following the below steps. +This tutorial explains how to create a Jupyter Notebook environment through the [Jupyter Lab]({{ reference_url }}/software-directory/scripting/jupyter-lab/overview/) application. -## Generate RESTFul API Tokens -The Jupyter notebook environment in the present tutorial is used to run an IPython notebook from [Exabyte API Examples Repository](../../rest-api/api-examples.md) in which a connection is made to the RESTFul API to retrieve a list of materials. In order to establish the connection, one should generate RESTFul API tokens following the steps described in [here](../../rest-api/authentication.md). +## 1. Generate RESTful API tokens -## Upload IPython Notebooks +The Jupyter notebook environment in this tutorial is used to run an IPython notebook from the [Exabyte API Examples Repository]({{ developers_url }}/rest-api/api-examples/) in which a connection is made to the RESTful API to retrieve a list of materials. In order to establish the connection, RESTful API tokens must be generated following the steps described [here]({{ developers_url }}/rest-api/authentication/). -Jupyter Notebook is started on the account [Dropbox](../../data-in-objectstorage/dropbox.md) directory. This directory provides users with access to previously uploaded/created IPython notebooks. Here, **settings.py** file contains the variables required to configure the RESTFul API endpoints and **get_materials_by_formula.ipynb** from the [Exabyte API Examples Github Repository](../../rest-api/api-examples.md) are uploaded to Dropbox to be later used inside the Jupyter notebook environment. -## Create Jupyter Job +## 2. Upload IPython notebooks -A simulation job is required to launch a Jupyter notebook. To create a new job, click on the **Create Job** link located on the [left-hand Sidebar](../../ui/left-sidebar.md) which takes you to the [Job Designer](../../jobs-designer/overview.md) page where you can configure Jupyter Notebook environment. +Jupyter Notebook is started on the account [Dropbox]({{ resources_url }}/data-in-objectstorage/dropbox/) directory. This directory provides access to previously uploaded or created IPython notebooks. The **settings.py** file contains the variables required to configure the RESTful API endpoints, and **get_materials_by_formula.ipynb** from the [Exabyte API Examples GitHub Repository]({{ developers_url }}/rest-api/api-examples/) should be uploaded to Dropbox for later use inside the Jupyter notebook environment. -## Choose Workflow -Jupyter Notebook installation and configuration is handled through the Jupyter Notebook [workflow](../../workflows/overview.md) that should be [imported](../../workflows/actions/copy-bank.md) from the [Workflows Bank](../../workflows/bank.md) into the account-owned [collection](../../accounts/collections.md) before the job is created. This workflow can later be [selected](../../jobs-designer/actions-header-menu/select-workflow.md) and added to the [job being created](../../jobs-designer/workflow-tab.md). +## 3. Create the Jupyter job -## Adjust Jupyter Notebook Environment +A simulation job is required to launch a Jupyter notebook. Click the **Create Job** link on the [left-hand Sidebar]({{ interface_url }}/ui/left-sidebar/) to open the [Job Designer]({{ interface_url }}/jobs-designer/overview/) page. -Jupyter Notebook is installed inside a Python [virtual environment](https://virtualenv.pypa.io/en/latest/) with no additional packages initially. The environment can be customized by navigating to the [workflow tab](../../jobs-designer/workflow-tab.md) and adjusting the **configure.sh** script located inside the **notebook** unit. Here, we install [Exabyte API Client](../../rest-api/api-client.md) Python package to connect to Exabyte RESTFul API. -## Submit Job +## 4. Select the workflow -Before [submitting](../../jobs/actions/run.md) the [job](../../jobs/overview.md), you should click on the ["Compute" tab](../../jobs-designer/compute-tab.md) of [Job Designer](../../jobs-designer/overview.md) and inspect the [compute parameters](../../infrastructure/compute/parameters.md) included therein. +The Jupyter Notebook [workflow]({{ reference_url }}/workflows/overview/) should be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into the account-owned [collection]({{ reference_url }}/accounts/collections/) before the job is created. This workflow can then be [selected]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) and added to the [job being created]({{ interface_url }}/jobs-designer/workflow-tab/). -## Access Jupyter Notebook -The Jupyter notebook can be accessed when the job is active by navigating to the [workflow tab](../../jobs-designer/workflow-tab.md) and opening the **notebook** unit. Wait for the Jupyter Notebook to start, as installation and configuration process takes some time, then click on the **Notebook** or **Lab** links to access the environment. +## 5. Adjust the Jupyter Notebook environment -!!!note "Do not use the URL Inside the Output File" - Do not use the URL printed in the output file as the notebooks can not be accessed via printed URL for security reasons. +Jupyter Notebook is installed inside a Python [virtual environment](https://virtualenv.pypa.io/en/latest/) with no additional packages initially. The environment can be customized by navigating to the [workflow tab]({{ interface_url }}/jobs-designer/workflow-tab/) and adjusting the **configure.sh** script located inside the **notebook** unit. In this example, the [Exabyte API Client]({{ developers_url }}/rest-api/api-client/) Python package is installed to connect to the RESTful API. -## Save Jupyter Notebooks -**Make sure to save and checkpoint the notebook after introducing any changes**. The "save and checkpoint" Jupyter action overwrites the original notebook loaded from Dropbox and saves a copy of the notebook inside **checkpoints** directory located in the [job working directory](../../jobs-cli/batch-scripts/directories.md#working-directory). The checkpoints will be later accessible through the [Job Files Explorer](../../data-in-objectstorage/files.md) tab. +## 6. Submit the job -## Stop Jupyter Environment +Before [submitting]({{ interface_url }}/jobs/actions/run/) the [job]({{ reference_url }}/jobs/overview/), click the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) of [Job Designer]({{ interface_url }}/jobs-designer/overview/) to inspect the [compute parameters]({{ resources_url }}/infrastructure/compute/parameters/). -When don editing, the Jupyter Notebook environment can be stopped by either clicking the **Quit** button in Jupyter Notebook or [terminating](../../jobs/actions/terminate.md) the job. In either case, **make sure to save any changes you have made before stopping the notebook as unsaved changes will be lost otherwise**. -## Access Modified Files +## 7. Access the Jupyter Notebook -As explained in the [dedicated section](../../software-directory/scripting/jupyter-lab/data.md) the modified IPython files, as well as the checkpoints at each save, and the other files associated with the job can be accessed from the Dropbox folder, the job and through command-line. +The Jupyter notebook can be accessed when the job is active by navigating to the [workflow tab]({{ interface_url }}/jobs-designer/workflow-tab/) and opening the **notebook** unit. After the installation and configuration process completes, click the **Notebook** or **Lab** links to access the environment. -## Animation +!!!note "Do not use the URL inside the output file" + The URL printed in the output file cannot be used, as notebooks are not accessible via that URL for security reasons. -We demonstrate the steps mentioned above in the animation below. + +## 8. Save Jupyter notebooks + +**It is essential to save and checkpoint the notebook after introducing any changes.** The "save and checkpoint" Jupyter action overwrites the original notebook loaded from Dropbox and saves a copy inside the **checkpoints** directory located in the [job working directory]({{ cli_url }}/jobs-cli/batch-scripts/directories.md#working-directory). The checkpoints are later accessible through the [Job Files Explorer]({{ resources_url }}/data-in-objectstorage/files/) tab. + + +## 9. Stop the Jupyter environment + +When editing is complete, the Jupyter Notebook environment can be stopped by either clicking the **Quit** button in Jupyter Notebook or [terminating]({{ interface_url }}/jobs/actions/terminate/) the job. **Any unsaved changes are lost when the notebook is stopped.** + + +## 10. Access modified files + +As explained in the [dedicated section]({{ data_url }}/software-directory/scripting/jupyter-lab/data/), the modified IPython files, checkpoints at each save, and other files associated with the job can be accessed from the Dropbox folder, the job, and through the command-line. + + +## 11. Video walkthrough + +The animation below demonstrates all steps described above.
diff --git a/lang/en/docs/tutorials/other/restart-job.md b/lang/en/docs/tutorials/other/restart-job.md index c4bc0c3f7..c96730c84 100644 --- a/lang/en/docs/tutorials/other/restart-job.md +++ b/lang/en/docs/tutorials/other/restart-job.md @@ -1,32 +1,37 @@ -# Restart From Previous Run +# Restart from a Previous Run -This page explains how to **restart** a [Job](../../jobs/overview.md) from the **results of a previous calculation**. - -## Restart File Operations +This page explains how to **restart** a [Job]({{ reference_url }}/jobs/overview/) from the **results of a previous calculation**. -When a job is added as a parent in this way, some directories and files are copied/linked to the new [job working directory](../../jobs-cli/batch-scripts/directories.md#working-directory). For example, for the case of the [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md) modeling engine, we create a link to the parent working directory to restart the calculation from the last checkpoint. Alternatively, for the case of [VASP](../../software-directory/modeling/vasp/overview.md), we copy the output CONTCAR file generated by the parent job as an input POSCAR structure file to restart from the last ionic step. -## Example of Restart Application - -In the present tutorial we will, by way of an example, make use of the "restart" functionality to feed the wavefunction data obtained in a self-consistent field (SCF) [Total Energy](../../properties-directory/scalar/total-energy.md) computation to the subsequent non-self consistent (NSCF) step in an electronic band structure calculation, which is reviewed in a [separate tutorial](../dft/electronic/band-structure.md). +## 1. Understand restart file operations -Restarting and linking the two Jobs in this way allows the band structure to be computed without having to recalculate the charge density and wavefunctions through an SCF calculation a second time, with the consequent gain in computational time. The results of such SCF Job can thus be re-utilized as starting point for multiple other calculations that require such preliminary results. +When a job is added as a parent, some directories and files are copied or linked to the new [job working directory]({{ cli_url }}/jobs-cli/batch-scripts/directories.md#working-directory). For example, with the [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) engine, a link to the parent working directory is created to restart from the last checkpoint. With [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/), the output CONTCAR file generated by the parent job is copied as an input POSCAR structure file to restart from the last ionic step. -## Select Parent Job -Within [Job Designer](../../jobs-designer/overview.md), Job restarting is accomplished via the ["Select Parent" Option](../../jobs-designer/actions-header-menu/select-parent.md) under the main [header menu](../../jobs-designer/header-menu.md) of the interface. +## 2. Example of restart application -The user should first create a new [Job](../../jobs/overview.md), with the NSCF component [unit](../../workflows/components/units.md) of a band structure calculation present on its own in the main [workflow](../../workflows/overview.md). The same instructions as in the [original tutorial](../dft/electronic/band-structure.md#create-job) should be followed to [select and insert](../../jobs-designer/actions-header-menu/select-workflow.md) such a Workflow into the new [Job being designed](../../jobs-designer/overview.md). +This tutorial demonstrates the "restart" functionality by feeding the wavefunction data obtained in a self-consistent field (SCF) [Total Energy]({{ reference_url }}/properties-directory/scalar/total-energy/) computation to the subsequent non-self consistent (NSCF) step in an electronic band structure calculation, which is described in a [separate tutorial](../dft/electronic/band-structure.md). -The next steps consist in finding the previously-run SCF job via the aforementioned ["Select Parent" option](../../jobs-designer/actions-header-menu#select-parent-job), and in selecting that job in order to prepend its results as a restart precursor to the new NSCF job being created. +Restarting and linking the two Jobs in this way allows the band structure to be computed without recalculating the charge density and wavefunctions through an SCF calculation a second time, reducing computational time. The results of such an SCF Job can be re-utilized as a starting point for multiple other calculations that require such preliminary results. -## Submit Job + +## 3. Select the parent job + +Within [Job Designer]({{ interface_url }}/jobs-designer/overview/), job restarting is accomplished via the [Select Parent Option]({{ interface_url }}/jobs-designer/actions-header-menu/select-parent/) under the main [header menu]({{ interface_url }}/jobs-designer/header-menu/). + +First, create a new [Job]({{ reference_url }}/jobs/overview/) with the NSCF component [unit]({{ reference_url }}/workflows/components/units/) of a band structure calculation present on its own in the main [workflow]({{ reference_url }}/workflows/overview/). Follow the same instructions as in the [original tutorial](../dft/electronic/band-structure.md#create-job) to [select and insert]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) such a Workflow. + +Then, find the previously-run SCF job via the [Select Parent option]({{ interface_url }}/jobs-designer/actions-header-menu/select-parent/) and select that job to prepend its results as a restart precursor to the new NSCF job. + + +## 4. Submit the job The same instructions for submitting and executing the restart Job as in the main band structure [tutorial](../dft/electronic/band-structure.md#submit-job) can be followed. -## Animation -In the following animation, we demonstrate the above-mentioned steps involved in restarting an NSCF electronic band structure computation, performed on silicon, based upon the preliminary results of a previously-run SCF calculation. We shall make use of the [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md) simulation engine in the present example, however the same procedure and outcome should be of general applicability. +## 5. Video walkthrough + +The animation below demonstrates the steps involved in restarting an NSCF electronic band structure computation, performed on silicon, based upon the preliminary results of a previously-run SCF calculation. The example uses [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/), however the same procedure is generally applicable.
diff --git a/lang/en/docs/tutorials/overview.md b/lang/en/docs/tutorials/overview.md index 9f5f0f521..504d50bbb 100644 --- a/lang/en/docs/tutorials/overview.md +++ b/lang/en/docs/tutorials/overview.md @@ -1,8 +1,8 @@ # Tutorials -The sub-pages under this section contain detailed tutorials. You can find -specific tutorial from the index below or locate the corresponding entry in the -sidebar navigation. +The sub-pages under this section contain detailed tutorials. A specific tutorial +can be found from the index below or via the corresponding entry in the sidebar +navigation. ## Table of Contents @@ -17,9 +17,6 @@ sidebar navigation. - [Magnetic Moment on Atoms by Specie](templating/set-magnetic-moment.md) - Machine Learning (ML) - [Overview](ml/overview.md) - - ExabyteML (legacy) - - [Train ML Model](ml/train-ml-model.md) - - [Predict New Properties](ml/predict-ml-properties.md) - Python ML - [Training a Regression Model](python-ml/train-regression-model.md) - [Predictions with Regression](python-ml/predict-with-regression.md) @@ -65,7 +62,6 @@ sidebar navigation. - [Accessing the Platform](platform-access.md) - [Jupyter Notebook](other/jupyter.md) - [Restart from Previous Job](other/restart-job.md) - - [Upload External Job Data](other/external-upload.md) - [TensorFlow (GPU)](general-functionality/tensorflow-gpu.md) - Materials - [Overview](materials/overview.md) diff --git a/lang/en/docs/tutorials/platform-access.md b/lang/en/docs/tutorials/platform-access.md index ec6a5dda6..8146094fb 100644 --- a/lang/en/docs/tutorials/platform-access.md +++ b/lang/en/docs/tutorials/platform-access.md @@ -1,24 +1,24 @@ # Accessing the Platform -There are three main modes of accessing the Mat3ra platform: +There are three main modes of accessing the Mat3ra platform: -- (1) Web/browser interface -- (2) [Command line interface](../cli/overview.md) (CLI), and -- (3) [REST API](../rest-api). +1. Web/browser interface +2. [Command line interface]({{ cli_url }}/cli/overview/) (CLI) +3. [REST API]({{ developers_url }}/rest-api/) -- Below we present a short video demonstrating various ways of accessing the Mat3ra platform. It covers: + +## 1. Video overview + +The video below demonstrates the various ways of accessing the Mat3ra platform, covering the following topics: - 00:54 Web platform overview - 01:42 Materials designer -- 02:26 Command Line Interface +- 02:26 Command Line Interface - 02:57 SSH to login node - 04:01 Web terminal - 04:13 API access - 04:37 API access from Jupyter Notebook - -## The Video -
- +
diff --git a/lang/en/docs/tutorials/python-ml/predict-with-classification.md b/lang/en/docs/tutorials/python-ml/predict-with-classification.md index d8812cc5e..4c42ff72e 100644 --- a/lang/en/docs/tutorials/python-ml/predict-with-classification.md +++ b/lang/en/docs/tutorials/python-ml/predict-with-classification.md @@ -1,95 +1,66 @@ -# Machine Learning: Predict With a Random Forest for Classification +# Machine Learning: Predict With a Random Forest Classifier -This tutorial demonstrates how to perform predictions using a Random Forest [^1] trained for classification via -Scikit-Learn. [^2] +This tutorial demonstrates how to perform predictions using a [Random Forest](https://en.wikipedia.org/wiki/Random_forest) [^1] trained for classification via [Scikit-Learn](https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.RandomForestClassifier.html) [^2]. -!!! warning "Pre-Requisites" - In order to perform this tutorial, the [Predict with Classification](predict-with-classification.md) tutorial must - be completed. +!!!warning "Pre-requisite" + The [Train Classification](train-classification-model.md) tutorial must be completed before proceeding. -## 1. Acquire Data -The data we use in this example comes from the QSAR group's biodegredation database, as hosted on Kaggle. [^3] +## 1. Acquire the prediction data -The dataset consists of 41 unique descriptors of each molecule, and the goal of the problem is to predict whether the -molecule is biodegredable or not. +The data used in this example comes from the QSAR group's [biodegradation database on Kaggle](https://www.kaggle.com/muhammetvarl/qsarbiodegradation) [^3]. The dataset consists of 41 unique molecular descriptors. Before uploading, the "Class" column must be removed from the dataset. The resulting file is referred to as "data_to_classify_with.csv". -The dataset can be found on Kaggle, [here](https://www.kaggle.com/muhammetvarl/qsarbiodegradation). -Before uploading to the platform, remove the "Class" column from the dataset. -We will call this dataset "data_to_classify_with.csv" +## 2. Upload the data -## 2. Upload the Data - -In order to upload data for predictions, we first click the `Dropbox` button in the [left sidebar](../../ui/left-sidebar.md). -This will bring us to the [Dropbox Page](../../jobs/ui/files-tab.md). We can then click the "Upload" button, circled -below: +Click the `Dropbox` button in the [left sidebar]({{ interface_url }}/ui/left-sidebar/) to navigate to the [Dropbox Page]({{ interface_url }}/jobs/ui/files-tab/). Then click **Upload**: ![Dropbox Page with Upload Button Circled](../../images/tutorials/pythonML/dropbox-page-with-upload-circled.png "Dropbox Page with Upload Button Circled") -Then, when the browser's upload window appears, we navigate to where we downloaded the file in section 1, and select it -for upload. If the upload was successful, the file will then be visible in the dropbox. +When the browser's upload window appears, navigate to the downloaded file and select it. If successful, the file appears in the dropbox. -## 3. Create the ML Job -Next, we can create a new job by selecting the `Create Job` button in the [left sidebar](../../ui/left-sidebar.md). This -will bring us to a new job on the [Job Designer](../../jobs-designer/overview.md) page. +## 3. Create the ML job -First, we will give the job a friendly name, such as "Python ML Tutorial Prediction" (see below). Then, we will click -the [Actions Button](../../jobs-designer/header-menu.md#Actions) (the three vertical dots in the upper-right of the job -designer), and choose "Select Workflow." +Create a new job by clicking `Create Job` in the [left sidebar]({{ interface_url }}/ui/left-sidebar/). Give the job a descriptive name, such as "Python ML Tutorial Prediction". Then click the [Actions Button]({{ interface_url }}/jobs-designer/header-menu/#Actions) and choose **Select Workflow**. ![Job Designer with Python Machine Learning Tutorial Name Set](../../images/tutorials/pythonML/job-designer-python-ml-predict-name.png "Job Designer with Python Machine Learning Tutorial Name Set") -This will bring up the [Select Workflow](../../jobs-designer/actions-header-menu/select-workflow.md) dialogue. We then -search for "workflow:pyml_predict" and click on it to bring it into the job. +In the [Select Workflow]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) dialogue, search for "workflow:pyml_predict" and select it. -A diagram and detailed description of this workflow can be found -[here](../../software-directory/machine-learning/python-ml/components.md) +A diagram and detailed description of this workflow can be found [here]({{ reference_url }}/software-directory/machine-learning/python-ml/components/). -## 4. Select the Dataset -The job designer changes now that our ML Predict workflow is selected. The "Materials" tab has now been replaced with -a "Dataset" tab. Just as the "Materials" tab shows a preview of the materials the job will use, the "Dataset" tab shows -a preview of the dataset once it is selected. +## 4. Select the dataset -To select a dataset, click the [Actions Button](../../jobs-designer/header-menu.md#Actions) (the three vertical dots in -the upper-right of the job designer) and choose "Select Dataset." This will bring up a files explorer containing all -files presently on the dropbox. Choose the dataset we uploaded earlier, "data_to_classify_with.csv." +Once the ML Predict workflow is selected, the *Materials* tab is replaced with a *Dataset* tab. Click the [Actions Button]({{ interface_url }}/jobs-designer/header-menu/#Actions) and choose **Select Dataset**. Select "data_to_classify_with.csv" from the file explorer. ![Dataset Tab with Random Forest Predictions](../../images/tutorials/classification_tutorial/dataset-tab-with-predict-data.png "Dataset Tab with Random Forest Predictions") -A preview of the data then appears on the dataset tab, indicating that the data has successfully been loaded. +A preview of the data appears on the dataset tab, confirming the data has been loaded. + -## 4. Inspect the ML Workflow +## 5. Inspect the ML workflow -We now have our ML workflow selected and our dataset has been supplied. -Select the [Workflows Tab](../../jobs-designer/workflow-tab.md), and we can see our predict workflow. +Open the [Workflows Tab]({{ interface_url }}/jobs-designer/workflow-tab/) to view the predict workflow. Two [subworkflows]({{ reference_url }}/workflows/components/subworkflows/) are available: `Set Up the Job` and `Machine Learning`. -We can see two [subworkflows](../../workflows/components/subworkflows.md) available: `Set Up the Job` -and `Machine Learning`. +!!!warning "Do not modify the setup subworkflow" + The `Set Up the Job` subworkflow was automatically configured during the training process. Modifying it can render the predict workflow inoperable or produce inaccurate results. -The `Set Up the Job` subworkflow contains instructions to copy in the trained model as well as the data we have selected. +The `Machine Learning` subworkflow contains the trained model steps. No further configuration is required — the prediction job is ready to submit. -!!!warning "A Word of Caution" - The `Set Up the Job` subworkflow has been automatically configured during the training process, and is not - intended for modification by the user. Changing it can render the predict workflow inoperable, and can lead to - inaccurate prediction results. Do not modify the `Set Up the Job` subworkflow. -The `Machine Learning` subworkflow contains the individual steps of the trained model we created previously. +## 6. Submit the job -There is no further configuration required: the workflow is already trained, and the prediction job is ready to submit. +Click the check-mark in the upper right of the job designer, in the [Header Menu]({{ interface_url }}/jobs-designer/header-menu/), to save the job. Then [run the job]({{ interface_url }}/jobs/actions/run/). -## 6. Submit the Job -Click the check-mark in the upper right of the job designer, in the [Header Menu](../../jobs-designer/header-menu.md) to -save the job. We now return to the [job explorer](../../jobs/ui/explorer.md) page with the job in a pre-submission -status. +## 7. Analyze the prediction results -We can now [run the job](../../jobs/actions/run.md) and wait for it to complete. +After a few minutes, the job completes. The [Results tab]({{ interface_url }}/jobs/ui/results-tab/) displays a CSV preview of `predictions.csv`, containing the row-by-row predictions generated by the model. This file is generated inside the `Model Train and Predict` unit. -## Animation +## 8. Video walkthrough This tutorial is demonstrated in the following animation: @@ -97,8 +68,9 @@ This tutorial is demonstrated in the following animation:
-## 7. Analyze the Prediction Results -After a few minutes, the job will complete. We can then visit the job's [results tab](../../jobs/ui/results-tab.md), -where we will see a CSV preview of a file called `predictions.csv`. These are the row-by-row predictions generated by -the model. Under the hood, this file is generated inside the `Model Train and Predict` unit. +## 9. Links + +[^1]: [Wikipedia, Random Forest](https://en.wikipedia.org/wiki/Random_forest) +[^2]: [Scikit-Learn, Random Forest Classifier](https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.RandomForestClassifier.html) +[^3]: [Kaggle, Biodegradation Database](https://www.kaggle.com/muhammetvarl/qsarbiodegradation) diff --git a/lang/en/docs/tutorials/python-ml/predict-with-regression.md b/lang/en/docs/tutorials/python-ml/predict-with-regression.md index e0f112487..321e59e6e 100644 --- a/lang/en/docs/tutorials/python-ml/predict-with-regression.md +++ b/lang/en/docs/tutorials/python-ml/predict-with-regression.md @@ -1,21 +1,16 @@ # Machine Learning: Predict Using a Neural Network Regression Model -This tutorial demonstrates how to perform predictions using -a [multilayer perceptron](https://en.wikipedia.org/wiki/Multilayer_perceptron) -trained for regression -using [SciKit-Learn](https://scikit-learn.org/stable/modules/generated/sklearn.neural_network.MLPRegressor.html). +This tutorial demonstrates how to perform predictions using a [multilayer perceptron](https://en.wikipedia.org/wiki/Multilayer_perceptron) trained for regression via [Scikit-Learn](https://scikit-learn.org/stable/modules/generated/sklearn.neural_network.MLPRegressor.html). -!!! warning "Pre-Requisites" - In order to perform this tutorial, the [ML Training](train-regression-model.md) tutorial must be completed. +!!!warning "Pre-requisite" + The [ML Training](train-regression-model.md) tutorial must be completed before proceeding. -## 1. Acquire Data -The data we use in this tutorial is taken from a [recent model](http://doi.org/10.1126/sciadv.aax5101) of small molecule -adsorption to transition metal nanoparticles. Specifically, we use DFT-calculated values for the adsorption energy of -·CH3, CO, and ·OH radicals to Ag, Au, and Cu nanoparticles ranging in size from 55 to 172 atoms. +## 1. Acquire the prediction data -This File contains the data we -will use in this tutorial for predictions. A sample of the first 5 lines in the file can be found below: +The data used in this tutorial is taken from a [recent model](http://doi.org/10.1126/sciadv.aax5101) of small molecule adsorption to transition metal nanoparticles. Specifically, the dataset contains DFT-calculated descriptors of ·CH3, CO, and ·OH radicals on Ag, Au, and Cu nanoparticles ranging in size from 55 to 172 atoms. + +This file contains the prediction data. A sample of the first 5 lines is shown below: |CE_Local_eV|ChemPot_eV|MADS_eV |----|---|---- @@ -24,86 +19,62 @@ will use in this tutorial for predictions. A sample of the first 5 lines in the |-4.81|-4.96|-2.10 |-4.60|-4.96|-2.10 -## 2. Upload the Data -In order to upload data for predictions, we first click the `Dropbox` button in the [left sidebar](../../ui/left-sidebar.md). -This will bring us to the [Dropbox Page](../../jobs/ui/files-tab.md). We can then click the "Upload" button, circled -below: +## 2. Upload the data + +Click the `Dropbox` button in the [left sidebar]({{ interface_url }}/ui/left-sidebar/) to navigate to the [Dropbox Page]({{ interface_url }}/jobs/ui/files-tab/). Then click **Upload**: ![Dropbox Page with Upload Button Circled](../../images/tutorials/pythonML/dropbox-page-with-upload-circled.png "Dropbox Page with Upload Button Circled") -Then, when the browser's upload window appears, we navigate to where we downloaded the file in section 1, and select it -for upload. If the upload was successful, the file will then be visible in the dropbox. +When the browser's upload window appears, navigate to the downloaded file and select it. If successful, the file appears in the dropbox. -## 3. Create the ML Job -Next, we can create a new job by selecting the `Create Job` button in the [left sidebar](../../ui/left-sidebar.md). This -will bring us to a new job on the [Job Designer](../../jobs-designer/overview.md) page. +## 3. Create the ML job -First, we will give the job a friendly name, such as "Python ML Tutorial Prediction" (see below). Then, we will click -the [Actions Button](../../jobs-designer/header-menu.md#Actions) (the three vertical dots in the upper-right of the job -designer), and choose "Select Workflow." +Create a new job by clicking `Create Job` in the [left sidebar]({{ interface_url }}/ui/left-sidebar/). Give the job a descriptive name, such as "Python ML Tutorial Prediction". Then click the [Actions Button]({{ interface_url }}/jobs-designer/header-menu/#Actions) and choose **Select Workflow**. ![Job Designer with Python Machine Learning Tutorial Name Set](../../images/tutorials/pythonML/job-designer-python-ml-predict-name.png "Job Designer with Python Machine Learning Tutorial Name Set") -This will bring up the [Select Workflow](../../jobs-designer/actions-header-menu/select-workflow.md) dialogue. We then -search for "workflow:pyml_predict" and click on it to bring it into the job. +In the [Select Workflow]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) dialogue, search for "workflow:pyml_predict" and select it. -A diagram and detailed description of this workflow can be found -[here](../../software-directory/machine-learning/python-ml/components.md) +A diagram and detailed description of this workflow can be found [here]({{ reference_url }}/software-directory/machine-learning/python-ml/components/). -## 4. Select the Dataset -The job designer changes now that our ML Predict workflow is selected. The "Materials" tab has now been replaced with -a "Dataset" tab. Just as the "Materials" tab shows a preview of the materials the job will use, the "Dataset" tab shows -a preview of the dataset once it is selected. +## 4. Select the dataset -To select a dataset, click the [Actions Button](../../jobs-designer/header-menu.md#Actions) (the three vertical dots in -the upper-right of the job designer) and choose "Select Dataset." This will bring up a files explorer containing all -files presently on the dropbox. Choose the training set we uploaded earlier, "data_to_predict_with.csv." +Once the ML Predict workflow is selected, the *Materials* tab is replaced with a *Dataset* tab. Click the [Actions Button]({{ interface_url }}/jobs-designer/header-menu/#Actions) and choose **Select Dataset**. This opens a file explorer containing all dropbox files. Select "data_to_predict_with.csv". ![Dataset Tab with Multilayer Perceptron Predictions Visible](../../images/tutorials/pythonML/dataset-tab-visible-predictions.png "Dataset Tab with Multilayer Perceptron Predictions Visible") -A preview of the data then appears on the dataset tab, indicating that the data has successfully been loaded. +A preview of the data appears on the dataset tab, confirming that the data has been loaded. -## 4. Inspect the ML Workflow -We now have our ML workflow selected and our dataset has been supplied. -Select the [Workflows Tab](../../jobs-designer/workflow-tab.md), and we can see our predict workflow. +## 5. Inspect the ML workflow -We can see two [subworkflows](../../workflows/components/subworkflows.md) available: `Set Up the Job` -and `Machine Learning`. +Open the [Workflows Tab]({{ interface_url }}/jobs-designer/workflow-tab/) to view the predict workflow. Two [subworkflows]({{ reference_url }}/workflows/components/subworkflows/) are available: `Set Up the Job` and `Machine Learning`. -The `Set Up the Job` subworkflow contains instructions to copy in the trained model as well as the data we have selected. +The `Set Up the Job` subworkflow contains instructions to copy the trained model and the selected data. -!!!warning "A Word of Caution" - The `Set Up the Job` subworkflow has been automatically configured during the training process, and is not - intended for modification by the user. Changing it can render the predict workflow inoperable, and can lead to - inaccurate prediction results. Do not modify the `Set Up the Job` subworkflow. +!!!warning "Do not modify the setup subworkflow" + The `Set Up the Job` subworkflow was automatically configured during the training process. Modifying it can render the predict workflow inoperable or lead to inaccurate prediction results. -The `Machine Learning` subworkflow contains the individual steps of the trained model we created previously. +The `Machine Learning` subworkflow contains the individual steps of the previously trained model. No further configuration is required — the workflow is already trained and the prediction job is ready to submit. -There is no further configuration required: the workflow is already trained, and the prediction job is ready to submit. -## 6. Submit the Job +## 6. Submit the job -Click the check-mark in the upper right of the job designer, in the [Header Menu](../../jobs-designer/header-menu.md) to -save the job. We now return to the [job explorer](../../jobs/ui/explorer.md) page with the job in a pre-submission -status. +Click the check-mark in the upper right of the job designer, in the [Header Menu]({{ interface_url }}/jobs-designer/header-menu/), to save the job. Then [run the job]({{ interface_url }}/jobs/actions/run/). -We can now [run the job](../../jobs/actions/run.md) and wait for it to complete. -## 7. Analyze the Prediction Results +## 7. Analyze the prediction results -After a few minutes, the job will complete. We can then visit the job's [results tab](../../jobs/ui/results-tab.md), -where we will see a CSV preview of a file called `predictions.csv`. These are the row-by-row predictions generated by -the model. Under the hood, this file is generated inside the `Model Train and Predict` unit. +After a few minutes, the job completes. The [Results tab]({{ interface_url }}/jobs/ui/results-tab/) displays a CSV preview of `predictions.csv`, containing the row-by-row predictions generated by the model. This file is generated inside the `Model Train and Predict` unit. -## Animation + +## 8. Video walkthrough This tutorial is demonstrated in the following animation:
- diff --git a/lang/en/docs/tutorials/python-ml/train-classification-model.md b/lang/en/docs/tutorials/python-ml/train-classification-model.md index 0675f2da5..539d959a1 100644 --- a/lang/en/docs/tutorials/python-ml/train-classification-model.md +++ b/lang/en/docs/tutorials/python-ml/train-classification-model.md @@ -1,127 +1,93 @@ # Machine Learning: Train a Random Forest for Classification -This tutorial demonstrates how to train a Random Forest [^1] classifier using Scikit-Learn. [^2] +This tutorial demonstrates how to train a [Random Forest](https://en.wikipedia.org/wiki/Random_forest) [^1] classifier using [Scikit-Learn](https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.RandomForestClassifier.html) [^2]. -## 1. Acquire Training Data -The data we use in this example comes from the QSAR group's biodegredation database, as hosted on Kaggle. [^3] +## 1. Acquire training data -The dataset consists of 41 unique descriptors of each molecule, and the goal of the problem is to predict whether the -molecule is biodegredable or not. +The data used in this example comes from the QSAR group's [biodegradation database on Kaggle](https://www.kaggle.com/muhammetvarl/qsarbiodegradation) [^3]. The dataset consists of 41 unique descriptors of each molecule, and the goal is to predict whether the molecule is biodegradable or not. -For convenience (and to ensure the ROC curves are predicted on the correct side of the diagonal), we have gently -pre-processed the dataset to encode its class labels as 0 and 1 (previously, they were 1 and 2). This is temporary - -the May update to the platform will automaticlaly encode class labels as 0 and 1, and will automatically un-transform -them to their original labels (e.g. 1 and 2, in this case). +The dataset has been pre-processed to encode class labels as 0 and 1. -Please download the dataset -here. +Download the dataset here. For the purposes of this tutorial, it is referred to as "data_to_train_with.csv". -For the purposes of this tutorial, we will name this dataset "data_to_train_with.csv" from this point onward. -## 2. Upload the Training Data +## 2. Upload the training data -In order to upload training data, we first click the `Dropbox` button in the [left sidebar](../../ui/left-sidebar.md). -This will bring us to the [Dropbox Page](../../jobs/ui/files-tab.md). We can then click the "Upload" button, circled -below: +Click the `Dropbox` button in the [left sidebar]({{ interface_url }}/ui/left-sidebar/) to navigate to the [Dropbox Page]({{ interface_url }}/jobs/ui/files-tab/). Then click the **Upload** button: ![Dropbox Page with Upload](../../images/tutorials/pythonML/dropbox-page-with-upload-circled.png "Dropbox page with upload circled") -Then, when the browser's upload window appears, we navigate to where we downloaded the file in section 1, and select it -for upload. If the upload was successful, the file will then be visible in the dropbox. +When the browser's upload window appears, navigate to the downloaded file and select it. If successful, the file appears in the dropbox. -## 3. Copy the "Python ML Train Classification" Workflow from the Workflow Bank -Next, we select the`Bank Worfklows` button in the [left sidebar](../../ui/left-sidebar.md), which brings us to -the [Bank Workflows Page](../../workflows/bank.md). We then search for the "Python ML Train Classification" workflow owned -by the "Curators" account, and [copy it to our account](../../workflows/actions/copy-bank.md). +## 3. Copy the classification workflow from the bank -A diagram and detailed description of this workflow can be found -[here](../../software-directory/machine-learning/python-ml/components.md). +Click the `Bank Workflows` button in the [left sidebar]({{ interface_url }}/ui/left-sidebar/) to navigate to the [Bank Workflows Page]({{ reference_url }}/workflows/bank/). Search for the "Python ML Train Classification" workflow owned by the "Curators" account, and [copy it to the account]({{ interface_url }}/workflows/actions/copy-bank/). -## 4. Create the ML Job +A diagram and detailed description of this workflow can be found [here]({{ reference_url }}/software-directory/machine-learning/python-ml/components/). -Next, we can create a new job by selecting the `Create Job` button in the [left sidebar](../../ui/left-sidebar.md). This -will bring us to a new job on the [Job Designer](../../jobs-designer/overview.md) page. -First, we will give the job a friendly name, such as "Python ML Tutorial" (see below). Then, we will click -the [Actions Button](../../jobs-designer/header-menu.md#Actions) (the three vertical dots in the upper-right of the job -designer), and choose "Select Workflow." +## 4. Create the ML job + +Create a new job by clicking `Create Job` in the [left sidebar]({{ interface_url }}/ui/left-sidebar/). Give the job a descriptive name, such as "Python ML Tutorial". Then click the [Actions Button]({{ interface_url }}/jobs-designer/header-menu/#Actions) and choose **Select Workflow**. ![Job Designer with Circles](../../images/tutorials/pythonML/job-designer-with-python-ml-name-and-three-dots-circled.png "Job designer page") -This will bring up the [Select Workflow](../../jobs-designer/actions-header-menu/select-workflow.md) dialogue. We then -search for "Python ML Train Classification" and select it. +In the [Select Workflow]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) dialogue, search for "Python ML Train Classification" and select it. -## 5. Select the Dataset -The job designer changes now that our ML Training workflow is selected. The "Materials" tab has now been replaced with -a "Dataset" tab. Just as the "Materials" tab shows a preview of the materials the job will use, the "Dataset" tab shows -a preview of the dataset once it is selected. +## 5. Select the dataset -![Dataset Tab](../../images/tutorials/classification_tutorial/dataset-tab-with-data.png "Dataset Tab") +Once the ML Training workflow is selected, the *Materials* tab is replaced with a *Dataset* tab. -To select a dataset, click the [Actions Button](../../jobs-designer/header-menu.md#Actions) (the three vertical dots in -the upper-right of the job designer) and choose "Select Dataset." This will bring up a files explorer containing all -files presently on the dropbox. Choose the training set we uploaded earlier, "data_to_train_with.csv." +![Dataset Tab](../../images/tutorials/classification_tutorial/dataset-tab-with-data.png "Dataset Tab") -A preview of the data then appears on the dataset tab, indicating that the data has successfully been loaded. +Click the [Actions Button]({{ interface_url }}/jobs-designer/header-menu/#Actions) and choose **Select Dataset**. Select "data_to_train_with.csv" from the file explorer. A preview appears on the dataset tab, confirming the data has been loaded. -## 6. Configure the Workflow -We have now chosen our ML workflow and training set. Select the [Workflows Tab](../../jobs-designer/workflow-tab.md), and we -can see our training workflow. +## 6. Configure the workflow -We can see two [subworkflows](../../workflows/components/subworkflows.md) available: `Set Up the Job` -and `Machine Learning`. +Open the [Workflows Tab]({{ interface_url }}/jobs-designer/workflow-tab/) to view the training workflow. Two [subworkflows]({{ reference_url }}/workflows/components/subworkflows/) are available: `Set Up the Job` and `Machine Learning`. -The `Set Up the Job` subworkflow contains instructions to copy in the training data. +!!!warning "Do not modify the setup subworkflow" + The `Set Up the Job` subworkflow is automatically configured during training. Modifying it can disrupt the Predict workflow. -!!!warning "A Word of Caution" - The `Set Up the Job` subworkflow is automatically configured during the training process. Modifying it can disrupt - creation of the Predict workflow, leading to inaccurate results, or a failure to generate a predict workflow. +Select the `Machine Learning` subworkflow. The following workflow units are visible: -Select the `Machine Learning` subworkflow by clicking on it. The following workflow units should now be visible: +0. `Setup Packages and Variables` — configures the job and downloads required packages via `pip` +1. `Data Input` — reads the training data from disk +2. `Train Test Split` — splits the data into training and testing sets +3. `Data Standardize` — scales the data to mean 0 and standard deviation 1 +4. `Model Train and Predict` — handles model training and prediction +5. `ROC Curve Plot` — draws a [Receiver Operating Characteristic](https://en.wikipedia.org/wiki/Receiver_operating_characteristic) (ROC) curve [^4] -0. `Setup Packages and Variables` - Configures the job and downloads all required packages with `pip` -1. `Data Input` - Reads the training data from disk -2. `Train Test Split` - Splits the data into a training set and a testing set -3. `Data Standardize` - Scales the data such that it has mean 0 and standard deviation 1 -4. `Model Train and Predict` - Handles model training, and prediction -5. `ROC Curve Plot` - Draws a plot of the Receiver Operator Characteristic (ROC) curve [^4] +### 6.1. Set the target column and problem category -We will begin by configuring our `Machine Learning` subworkflow. To begin, select the "Important Settings" portion of the -workflow editor. Then, set `target_column_name` to "Class" to define the target column of the training set. Then, -set the `problem_category` to be classification. +Open the *Important Settings* portion of the workflow editor. Set `target_column_name` to "Class" and `problem_category` to "classification". -![Important settings with target column name set](../../images/tutorials/classification_tutorial/important-settings-chosen.png "Important settings with target column name set" ) +![Important settings with target column name set](../../images/tutorials/classification_tutorial/important-settings-chosen.png "Important settings with target column name set") -The workflow has now been configured, and we are ready to train. -## 7. Submit the Job +## 7. Submit the job -Click the check-mark in the upper right of the job designer, in the [Header Menu](../../jobs-designer/header-menu.md) to -save the job. We now return to the [job explorer](../../jobs/ui/explorer.md) page with the job in a pre-submission -status +Click the check-mark in the upper right of the job designer, in the [Header Menu]({{ interface_url }}/jobs-designer/header-menu/), to save the job. ![Jobs Tab with ML Training Calculation Set Up](../../images/tutorials/pythonML/jobs-tab-with-ml-train-job-set-up.png "Jobs Tab with ML Training Calculation Set Up") -We can now [run the job](../../jobs/actions/run.md) and wait for it to complete. +The job can now be [run]({{ interface_url }}/jobs/actions/run/). + -## 8. Analyze the Training Results +## 8. Analyze the training results -After a few minutes, the job will complete. We can then visit the job's [results tab](../../jobs/ui/results-tab.md), -where we will see that two properties have been calculated. The first, `Machine Learning - Model Train and Predict` is -the predict workflow that was generated by the machine learning job. The predict workflow can be used to leverage the -trained model for additional predictions on new data. +After a few minutes, the job completes. The [Results tab]({{ interface_url }}/jobs/ui/results-tab/) shows two calculated properties. The first, `Machine Learning - Model Train and Predict`, is the predict workflow generated by the training job, which can be used for predictions on new data. -The second result visible is `Machine Learning - ROC Curve Plot`, which contains the ROC curve we calculated to assess -the model. +The second result is `Machine Learning - ROC Curve Plot`, containing the ROC curve for model assessment. -![Results Tab Showcasing Parity Plot](../../images/tutorials/classification_tutorial/ml-train-results-tab.png "Results Tab Showcasing Parity Plot") +![Results Tab Showcasing ROC Curve](../../images/tutorials/classification_tutorial/ml-train-results-tab.png "Results Tab Showcasing ROC Curve") -## Animation +## 9. Video walkthrough This tutorial is demonstrated in the following animation: @@ -129,12 +95,10 @@ This tutorial is demonstrated in the following animation:
-## Links -[^1]: [Wikipedia, Random Forest](https://en.wikipedia.org/wiki/Random_forest) +## 10. Links +[^1]: [Wikipedia, Random Forest](https://en.wikipedia.org/wiki/Random_forest) [^2]: [Scikit-Learn, Random Forest Classifier](https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.RandomForestClassifier.html) - -[^3]: [Kaggle, Biodegredation Database](https://www.kaggle.com/muhammetvarl/qsarbiodegradation) - +[^3]: [Kaggle, Biodegradation Database](https://www.kaggle.com/muhammetvarl/qsarbiodegradation) [^4]: [Wikipedia, Receiver Operating Characteristic](https://en.wikipedia.org/wiki/Receiver_operating_characteristic) diff --git a/lang/en/docs/tutorials/python-ml/train-clustering-model.md b/lang/en/docs/tutorials/python-ml/train-clustering-model.md index 69edf6f20..e588ebd21 100644 --- a/lang/en/docs/tutorials/python-ml/train-clustering-model.md +++ b/lang/en/docs/tutorials/python-ml/train-clustering-model.md @@ -1,146 +1,110 @@ # Train a K-Means Clustering Model with Scikit-Learn -This tutorial demonstrates how to train a K-Means Clustering [^1] model using Scikit-Learn. [^2] +This tutorial demonstrates how to train a [K-Means Clustering](https://en.wikipedia.org/wiki/K-means_clustering) [^1] model using [Scikit-Learn](https://scikit-learn.org/stable/modules/generated/sklearn.cluster.KMeans.html) [^2]. -## 1. Acquire Training Data -Unsupervised learning [^3] is a technique that takes in unlabeled training data, and generates its own labels for a -dataset. Oftentimes, it is used as an exploratory tool to find collections of similar items. For example, to find -molecules or crystals with similar properties. +## 1. Acquire training data -The data used in this example was acquired from Kaggle [^4]. +[Unsupervised learning](https://en.wikipedia.org/wiki/Unsupervised_learning) [^3] takes in unlabeled training data and generates its own labels. It is often used as an exploratory tool to find collections of similar items — for example, molecules or crystals with similar properties. -It consists of a group of 21,263 superconductors, along with the following properties: +The data used in this example was acquired from [Kaggle](https://www.kaggle.com/anlgrbz/super-conductors) [^4]. It consists of a group of 21,263 superconductors with the following properties: - Atomic Mass (AMU) - First Ionization Energy (kJ/mol) - Atomic Radius (pm) -- Density (kg/m^3) +- Density (kg/m³) - Electron Affinity (kJ/mol) - Fusion Heat (kJ/mol) - Thermal Conductivity (kJ/mol) - Valence (number of bonds) -For each property, various properties including mean, the weighted mean, and standard deviation are calculated. The -dataset was originally posted to Kaggle to pose the regression problem of predicting a superconductor's critical -temperature [^5], but for our purposes, we will train a clustering model to separate the superconductors into several -groups. +For each property, various statistics including mean, weighted mean, and standard deviation are calculated. The dataset was originally posted for predicting superconductor [critical temperatures](https://en.wikipedia.org/wiki/Superconductivity#By_critical_temperature) [^5], but this tutorial uses it to separate the superconductors into clusters. -Due to the filesize limits imposed by our upload system (20 MB), we will truncate at 15,000 examples, -for a 16 MB training set. For convenience, we have processed this file to meet our upload constraint; download it -it here. +Due to the platform's upload limit (20 MB), the dataset is truncated to 15,000 examples (16 MB). A pre-processed version is available for download here. -## 2. Upload the Training Data -In order to upload training data, we first click the `Dropbox` button in the [left sidebar](../../ui/left-sidebar.md). -This will bring us to the [Dropbox Page](../../jobs/ui/files-tab.md). We can then click the "Upload" button, circled -below: +## 2. Upload the training data + +Click the `Dropbox` button in the [left sidebar]({{ interface_url }}/ui/left-sidebar/) to navigate to the [Dropbox Page]({{ interface_url }}/jobs/ui/files-tab/). Then click **Upload**: ![Dropbox Page with Upload](../../images/tutorials/pythonML/dropbox-page-with-upload-circled.png "Dropbox page with upload circled") -Then, when the browser's upload window appears, we navigate to where we downloaded the file in section 1, and select it -for upload. If the upload was successful, the file will then be visible in the dropbox. +When the browser's upload window appears, navigate to the downloaded file and select it. If successful, the file appears in the dropbox. + -## 3. Copy the "Python ML Train Clustering" Workflow from the Workflow Bank +## 3. Copy the clustering workflow from the bank -Next, we select the`Bank Worfklows` button in the [left sidebar](../../ui/left-sidebar.md), which brings us to -the [Bank Workflows Page](../../workflows/bank.md). We then search for the "Python ML Train Clustering" workflow owned -by the "Curators" account, and [copy it to our account](../../workflows/actions/copy-bank.md). +Click the `Bank Workflows` button in the [left sidebar]({{ interface_url }}/ui/left-sidebar/) to navigate to the [Bank Workflows Page]({{ reference_url }}/workflows/bank/). Search for the "Python ML Train Clustering" workflow owned by the "Curators" account, and [copy it to the account]({{ interface_url }}/workflows/actions/copy-bank/). -A diagram and detailed description of this workflow can be found -[here](../../software-directory/machine-learning/python-ml/components.md). +A diagram and detailed description of this workflow can be found [here]({{ reference_url }}/software-directory/machine-learning/python-ml/components/). -## 4. Create the ML Job -Next, we can create a new job by selecting the `Create Job` button in the [left sidebar](../../ui/left-sidebar.md). This -will bring us to a new job on the [Job Designer](../../jobs-designer/overview.md) page. +## 4. Create the ML job -First, we will give the job a friendly name, such as "Python ML Tutorial" (see below). Then, we will click -the [Actions Button](../../jobs-designer/header-menu.md#Actions) (the three vertical dots in the upper-right of the job -designer), and choose "Select Workflow." +Create a new job by clicking `Create Job` in the [left sidebar]({{ interface_url }}/ui/left-sidebar/). Give the job a descriptive name, such as "Python ML Tutorial". Then click the [Actions Button]({{ interface_url }}/jobs-designer/header-menu/#Actions) and choose **Select Workflow**. ![Job Designer with Circles](../../images/tutorials/pythonML/job-designer-with-python-ml-name-and-three-dots-circled.png "Job designer page") -This will bring up the [Select Workflow](../../jobs-designer/actions-header-menu/select-workflow.md) dialogue. We then -search for "Python ML Train Clustering" and select it. +In the [Select Workflow]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) dialogue, search for "Python ML Train Clustering" and select it. + -## 5. Select the Dataset +## 5. Select the dataset -The job designer changes now that our ML Training workflow is selected. The "Materials" tab has now been replaced with -a "Dataset" tab. Just as the "Materials" tab shows a preview of the materials the job will use, the "Dataset" tab shows -a preview of the dataset once it is selected. +Once the ML Training workflow is selected, the *Materials* tab is replaced with a *Dataset* tab. ![Dataset Tab with Data Preview](../../images/tutorials/clustering_tutorial/dataset-tab-with-data.png "Dataset Tab with Data") -To select a dataset, click the [Actions Button](../../jobs-designer/header-menu.md#Actions) (the three vertical dots in -the upper-right of the job designer) and choose "Select Dataset." This will bring up a files explorer containing all -files presently on the dropbox. Choose the training set we uploaded earlier, "clustering_data.csv." +Click the [Actions Button]({{ interface_url }}/jobs-designer/header-menu/#Actions) and choose **Select Dataset**. Select "clustering_data.csv" from the file explorer. A preview appears on the dataset tab, confirming the data has been loaded. -A preview of the data then appears on the dataset tab, indicating that the data has successfully been loaded. -## 6. Configure the Workflow +## 6. Configure the workflow -We have now chosen our ML workflow and training set. Select the [Workflows Tab](../../jobs-designer/workflow-tab.md), and we -can see our training workflow. +Open the [Workflows Tab]({{ interface_url }}/jobs-designer/workflow-tab/) to view the training workflow. Two [subworkflows]({{ reference_url }}/workflows/components/subworkflows/) are available: `Set Up the Job` and `Machine Learning`. -We can see two [subworkflows](../../workflows/components/subworkflows.md) available: `Set Up the Job` -and `Machine Learning`. +!!!warning "Do not modify the setup subworkflow" + The `Set Up the Job` subworkflow is automatically configured during training. Modifying it can disrupt the Predict workflow. -The `Set Up the Job` subworkflow contains instructions to copy in the training data. +Select the `Machine Learning` subworkflow. The following workflow units are visible: -!!!warning "A Word of Caution" - The `Set Up the Job` subworkflow is automatically configured during the training process. Modifying it can disrupt - creation of the Predict workflow, leading to inaccurate results, or a failure to generate a predict workflow. +0. `Setup Packages and Variables` — configures the job and downloads required packages via `pip` +1. `Data Input` — reads the training data from disk +2. `Train Test Split` — splits the data into training and testing sets +3. `Data Standardize` — scales the data to mean 0 and standard deviation 1 +4. `Model Train and Predict` — handles model training and prediction +5. `2D PCA Clusters Plot` — draws the clusters projected onto the first two [principal components](https://en.wikipedia.org/wiki/Principal_component_analysis) [^6] -Select the `Machine Learning` subworkflow by clicking on it. The following workflow units should now be visible: +### 6.1. Set the problem category -0. `Setup Packages and Variables` - Configures the job and downloads all required packages with `pip` -1. `Data Input` - Reads the training data from disk -2. `Train Test Split` - Splits the data into a training set and a testing set -2. `Data Standardize` - Scales the data such that it has mean 0 and standard deviation 1 -3. `Model Train and Predict` - Handles model training, and prediction -4. `2D PCA Clusters Plot` - Draws a plot of the clusters in the training and testing set, projected onto the first two -principle components [^6] of the dataset. +Open the *Important Settings* portion of the workflow editor. Set `problem_category` to "clustering". -We will begin by configuring our `Machine Learning` subworkflow. To begin, select the "Important Settings" portion of the -workflow editor. Then, set `problem_category` to "clustering" to state that we are solving a clustering problem. +![Important settings with clustering set](../../images/tutorials/clustering_tutorial/important-settings-problem-category.png "Important settings with clustering set") -![Important settings with clustering set](../../images/tutorials/clustering_tutorial/important-settings-problem-category.png "Important settings with clustering set" ) +### 6.2. Adjust the number of clusters -By default, the workflow will split the dataset into 4 clusters. This can be configured within the -`Model Train and Predict` unit. We will click the `Model Train and Predict` unit to bring up the workflow unit editor. -Then, scroll down to line 27, and change `n_clusters` from 4 to 2. Then, close the unit editor. +By default, the workflow splits the dataset into 4 clusters. In order to change this, click the `Model Train and Predict` unit to open the editor. Scroll to line 27 and change `n_clusters` from 4 to 2. Close the unit editor. ![K Means set to two clusters](../../images/tutorials/clustering_tutorial/kmeans-set-to-two-clusters.png "K Means Set to Two Clusters") -The workflow has now been configured, and we are ready to train. -## 7. Submit the Job +## 7. Submit the job -Click the check-mark in the upper right of the job designer, in the [Header Menu](../../jobs-designer/header-menu.md) to -save the job. We now return to the [job explorer](../../jobs/ui/explorer.md) page with the job in a pre-submission -status +Click the check-mark in the upper right of the job designer, in the [Header Menu]({{ interface_url }}/jobs-designer/header-menu/), to save the job. ![Jobs Tab with ML Training Calculation Set Up](../../images/tutorials/pythonML/jobs-tab-with-ml-train-job-set-up.png "Jobs Tab with ML Training Calculation Set Up") -We can now [run the job](../../jobs/actions/run.md) and wait for it to complete. +The job can now be [run]({{ interface_url }}/jobs/actions/run/). -## 8. Analyze the Training Results -After a few minutes, the job will complete. We can then visit the job's [results tab](../../jobs/ui/results-tab.md), -where we will see that two properties have been calculated. The first, `Machine Learning - Model Train and Predict` is -the predict workflow that was generated by the machine learning job. The predict workflow can be used to leverage the -trained model for additional predictions on new data. In the case of clustering, this means assigning new values to the -clusters identified by the model. +## 8. Analyze the training results -The second result visible is `Machine Learning - 2D PCA Clusters Plot`, which draws the clusters projected along their -first two principle components. Each color represents a different group. Circles represent the training set, and squares -represent the testing set. +After a few minutes, the job completes. The [Results tab]({{ interface_url }}/jobs/ui/results-tab/) shows two calculated properties. The first, `Machine Learning - Model Train and Predict`, is the predict workflow generated by the training job, which can be used to assign new data points to the identified clusters. + +The second result is `Machine Learning - 2D PCA Clusters Plot`, which draws the clusters projected onto their first two principal components. Each color represents a different group; circles represent the training set and squares represent the testing set. ![Results Tab Showcasing Clusters Plot](../../images/tutorials/clustering_tutorial/2d-pca-clusters-plot.png "Results Tab Showcasing Clusters Plot") -## Animation +## 9. Video walkthrough This tutorial is demonstrated in the following animation: @@ -148,16 +112,12 @@ This tutorial is demonstrated in the following animation:
-## Links -[^1]: [Wikipedia, K-Means Clustering](https://en.wikipedia.org/wiki/K-means_clustering) +## 10. Links +[^1]: [Wikipedia, K-Means Clustering](https://en.wikipedia.org/wiki/K-means_clustering) [^2]: [Scikit-Learn, K-Means](https://scikit-learn.org/stable/modules/generated/sklearn.cluster.KMeans.html) - [^3]: [Wikipedia, Unsupervised Learning](https://en.wikipedia.org/wiki/Unsupervised_learning) - [^4]: [Kaggle, Superconductors Dataset](https://www.kaggle.com/anlgrbz/super-conductors) - [^5]: [Wikipedia, Superconductivity](https://en.wikipedia.org/wiki/Superconductivity#By_critical_temperature) - -[^6]: [Wikipedia, Principle Component Analysis](https://en.wikipedia.org/wiki/Principal_component_analysis) +[^6]: [Wikipedia, Principal Component Analysis](https://en.wikipedia.org/wiki/Principal_component_analysis) diff --git a/lang/en/docs/tutorials/python-ml/train-regression-model.md b/lang/en/docs/tutorials/python-ml/train-regression-model.md index 9f3575962..04c46b80a 100644 --- a/lang/en/docs/tutorials/python-ml/train-regression-model.md +++ b/lang/en/docs/tutorials/python-ml/train-regression-model.md @@ -1,15 +1,13 @@ # Machine Learning: Train a Neural Network for Regression -This tutorial demonstrates how to train a multilayer perceptron [^1] for regression using Scikit-Learn. [^2] +This tutorial demonstrates how to train a multilayer perceptron [^1] for regression using Scikit-Learn [^2]. -## 1. Acquire Training Data -The data we use in this tutorial is taken from a recent model [^3] of small molecule -adsorption to transition metal nanoparticles. Specifically, we use DFT-calculated values for the adsorption energy of -·CH3, CO, and ·OH radicals to Ag, Au, and Cu nanoparticles ranging in size from 55 to 172 atoms. +## 1. Acquire training data -This File contains the data we will -use in this tutorial. A sample of the first 5 lines in the file can be found below: +The data used in this tutorial is taken from a recent model [^3] of small molecule adsorption to transition metal nanoparticles. Specifically, the dataset contains DFT-calculated adsorption energies of ·CH3, CO, and ·OH radicals on Ag, Au, and Cu nanoparticles ranging in size from 55 to 172 atoms. + +This file contains the data used in this tutorial. A sample of the first 5 lines is shown below: |PBE_BE_eV|CE_Local_eV|ChemPot_eV|MADS_eV |-----|----|---|---- @@ -18,121 +16,103 @@ use in this tutorial. A sample of the first 5 lines in the file can be found bel |-0.95|-4.81|-4.96|-2.10 |-0.74|-4.60|-4.96|-2.10 -## 2. Upload the Training Data -In order to upload training data, we first click the `Dropbox` button in the [left sidebar](../../ui/left-sidebar.md). -This will bring us to the [Dropbox Page](../../jobs/ui/files-tab.md). We can then click the "Upload" button, circled -below: +## 2. Upload the training data + +First, click the `Dropbox` button in the [left sidebar]({{ interface_url }}/ui/left-sidebar/) to navigate to the [Dropbox Page]({{ interface_url }}/jobs/ui/files-tab/). Then click the **Upload** button, circled below: ![Dropbox Page with Upload](../../images/tutorials/pythonML/dropbox-page-with-upload-circled.png "Dropbox page with upload circled") -Then, when the browser's upload window appears, we navigate to where we downloaded the file in section 1, and select it -for upload. If the upload was successful, the file will then be visible in the dropbox. +When the browser's upload window appears, navigate to the downloaded file from section 1 and select it for upload. If the upload was successful, the file appears in the dropbox. + -## 3. Copy the "Python ML Train Regression" Workflow from the Workflow Bank +## 3. Copy the regression workflow from the bank -Next, we select the`Bank Worfklows` button in the [left sidebar](../../ui/left-sidebar.md), which brings us to -the [Bank Workflows Page](../../workflows/bank.md). We then search for the "Python ML Train Regression" workflow owned -by the "Curators" account, and [copy it to our account](../../workflows/actions/copy-bank.md). +Next, click the `Bank Workflows` button in the [left sidebar]({{ interface_url }}/ui/left-sidebar/) to navigate to the [Bank Workflows Page]({{ reference_url }}/workflows/bank/). Search for the "Python ML Train Regression" workflow owned by the "Curators" account, and [copy it to the account]({{ interface_url }}/workflows/actions/copy-bank/). -A diagram and detailed description of this workflow can be found -[here](../../software-directory/machine-learning/python-ml/components.md). +A diagram and detailed description of this workflow can be found [here]({{ reference_url }}/software-directory/machine-learning/python-ml/components/). -## 4. Create the ML Job -Next, we can create a new job by selecting the `Create Job` button in the [left sidebar](../../ui/left-sidebar.md). This -will bring us to a new job on the [Job Designer](../../jobs-designer/overview.md) page. +## 4. Create the ML job -First, we will give the job a friendly name, such as "Python ML Tutorial" (see below). Then, we will click -the [Actions Button](../../jobs-designer/header-menu.md#Actions) (the three vertical dots in the upper-right of the job -designer), and choose "Select Workflow." +Create a new job by clicking the `Create Job` button in the [left sidebar]({{ interface_url }}/ui/left-sidebar/). This opens a new job on the [Job Designer]({{ interface_url }}/jobs-designer/overview/) page. + +First, give the job a descriptive name, such as "Python ML Tutorial" (see below). Then, click the [Actions Button]({{ interface_url }}/jobs-designer/header-menu/#Actions) (the three vertical dots in the upper-right of the job designer), and choose **Select Workflow**. ![Job Designer with Circles](../../images/tutorials/pythonML/job-designer-with-python-ml-name-and-three-dots-circled.png "Job designer page") -This will bring up the [Select Workflow](../../jobs-designer/actions-header-menu/select-workflow.md) dialogue. We then -search for "Python ML Train Regression" and select it. +This brings up the [Select Workflow]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) dialogue. Search for "Python ML Train Regression" and select it. + -## 5. Select the Dataset +## 5. Select the dataset -The job designer changes now that our ML Training workflow is selected. The "Materials" tab has now been replaced with -a "Dataset" tab. Just as the "Materials" tab shows a preview of the materials the job will use, the "Dataset" tab shows -a preview of the dataset once it is selected. +The job designer changes once the ML Training workflow is selected. The *Materials* tab is replaced with a *Dataset* tab. Just as the *Materials* tab shows a preview of the materials a job uses, the *Dataset* tab shows a preview of the selected dataset. ![Dataset Tab](../../images/tutorials/pythonML/dataset-tab-visible.png "Dataset Tab") -To select a dataset, click the [Actions Button](../../jobs-designer/header-menu.md#Actions) (the three vertical dots in -the upper-right of the job designer) and choose "Select Dataset." This will bring up a files explorer containing all -files presently on the dropbox. Choose the training set we uploaded earlier, "data_to_train_with.csv." +In order to select a dataset, click the [Actions Button]({{ interface_url }}/jobs-designer/header-menu/#Actions) (the three vertical dots in the upper-right of the job designer) and choose **Select Dataset**. This brings up a files explorer containing all files on the dropbox. Select the training set uploaded earlier, "data_to_train_with.csv." + +A preview of the data then appears on the dataset tab, indicating that the data has been loaded successfully. -A preview of the data then appears on the dataset tab, indicating that the data has successfully been loaded. -## 6. Configure the Workflow +## 6. Configure the workflow -We have now chosen our ML workflow and training set. Select the [Workflows Tab](../../jobs-designer/workflow-tab.md), and we -can see our training workflow. +With the ML workflow and training set selected, open the [Workflows Tab]({{ interface_url }}/jobs-designer/workflow-tab/) to view the training workflow. -We can see two [subworkflows](../../workflows/components/subworkflows.md) available: `Set Up the Job` -and `Machine Learning`. +Two [subworkflows]({{ reference_url }}/workflows/components/subworkflows/) are available: `Set Up the Job` and `Machine Learning`. The `Set Up the Job` subworkflow contains instructions to copy in the training data. -!!!warning "A Word of Caution" - The `Set Up the Job` subworkflow is automatically configured during the training process. Modifying it can disrupt - creation of the Predict workflow, leading to inaccurate results, or a failure to generate a predict workflow. +!!!warning "Do not modify the setup subworkflow" + The `Set Up the Job` subworkflow is automatically configured during the training process. Modifying it can disrupt creation of the Predict workflow, leading to inaccurate results or a failure to generate a predict workflow. -Select the `Machine Learning` subworkflow by clicking on it. The following workflow units should now be visible: +Select the `Machine Learning` subworkflow by clicking on it. The following workflow units should be visible: -0. `Setup Packages and Variables` - Configures the job and downloads all required packages with `pip` -1. `Data Input` - Reads the training data from disk -2. `Train Test Split` - Splits the data into a training set and a testing set -3. `Data Standardize` - Scales the data such that it has mean 0 and standard deviation 1 -4. `Model Train and Predict` - Handles model training, and prediction -5. `Parity Plot` - Draws a plot of model predictions versus training data, and saves it to the disk. This plot is shown - on the Results tab. +0. `Setup Packages and Variables` — configures the job and downloads all required packages with `pip` +1. `Data Input` — reads the training data from disk +2. `Train Test Split` — splits the data into a training set and a testing set +3. `Data Standardize` — scales the data to mean 0 and standard deviation 1 +4. `Model Train and Predict` — handles model training and prediction +5. `Parity Plot` — draws a plot of model predictions versus training data and saves it to disk (displayed on the Results tab) -We will begin by configuring our `Machine Learning` subworkflow. To begin, select the "Important Settings" portion of the -workflow editor. Then, set `target_column_name` to "PBE_BE_eV" to define the target column of the training set. +### 6.1. Set the target column -![Important settings with target column name set](../../images/tutorials/pythonML/important-settings-with-target-column-name-set.png "Important settings with target column name set" ) +Open the *Important Settings* portion of the workflow editor. Set `target_column_name` to "PBE_BE_eV" to define the target column of the training set. -Then, go back to the "Overview" portion of the workflow editor. We can now demonstrate how a workflow unit's parameters -can be changed. +![Important settings with target column name set](../../images/tutorials/pythonML/important-settings-with-target-column-name-set.png "Important settings with target column name set") -Begin by selecting the `Model Train and Predict` workflow unit, as below: +### 6.2. Adjust model parameters -![Workflows tab with ml train subworkflow and train unit circled](../../images/tutorials/pythonML/workflows-tab-with-ml-train-subworkflow-and-train-unit-circled.png "Workflows tab with ml train subworkflow and train unit circled") +Return to the *Overview* portion of the workflow editor. Select the `Model Train and Predict` workflow unit, as shown below: -We can then scroll down and change the `hidden_layer_sizes` argument from `(100,)` to `(100,100)` to make -our model contain two hidden layers of 100 neurons each. We also change `max_iter` to 5000 to train for up to 5000 -iterations. +![Workflows tab with ML train subworkflow and train unit circled](../../images/tutorials/pythonML/workflows-tab-with-ml-train-subworkflow-and-train-unit-circled.png "Workflows tab with ML train subworkflow and train unit circled") + +Scroll down and change the `hidden_layer_sizes` argument from `(100,)` to `(100,100)` to create two hidden layers of 100 neurons each. Also change `max_iter` to 5000 to train for up to 5000 iterations. ![ML Train Neural Network with 2 Hidden Layers](../../images/tutorials/pythonML/ml-train-neural-network-with-2-hidden-layers.png "ML Train Neural Network with 2 Hidden Layers") -Then, close the dialogue. The workflow has now been configured, and we are ready to train. +Close the dialogue. The workflow is now configured. + -## 7. Submit the Job +## 7. Submit the job -Click the check-mark in the upper right of the job designer, in the [Header Menu](../../jobs-designer/header-menu.md) to -save the job. We now return to the [job explorer](../../jobs/ui/explorer.md) page with the job in a pre-submission -status +Click the check-mark in the upper right of the job designer, in the [Header Menu]({{ interface_url }}/jobs-designer/header-menu/), to save the job. The [job explorer]({{ interface_url }}/jobs/ui/explorer/) page displays the job in a pre-submission status. ![Jobs Tab with ML Training Calculation Set Up](../../images/tutorials/pythonML/jobs-tab-with-ml-train-job-set-up.png "Jobs Tab with ML Training Calculation Set Up") -We can now [run the job](../../jobs/actions/run.md) and wait for it to complete. +The job can now be [run]({{ interface_url }}/jobs/actions/run/). + -## 8. Analyze the Training Results +## 8. Analyze the training results -After a few minutes, the job will complete. We can then visit the job's [results tab](../../jobs/ui/results-tab.md), -where we will see that two properties have been calculated. The first, `Machine Learning - Model Train and Predict` is -the predict workflow that was generated by the machine learning job. The predict workflow can be used to leverage the -trained model for additional predictions on new data. +After a few minutes, the job completes. The job's [Results tab]({{ interface_url }}/jobs/ui/results-tab/) shows two calculated properties. The first, `Machine Learning - Model Train and Predict`, is the predict workflow generated by the training job. This workflow can be used to apply the trained model to new data for additional predictions. -The second result visible is `Machine Learning - Parity Plot`, which contains the predicted versus actual values for the -adsorption energies we trained the model on. +The second result is `Machine Learning - Parity Plot`, which contains the predicted versus actual values for the adsorption energies. ![Results Tab Showcasing Parity Plot](../../images/tutorials/pythonML/ml-train-results-tab.png "Results Tab Showcasing Parity Plot") -## Animation + +## 9. Video walkthrough This tutorial is demonstrated in the following animation: @@ -140,7 +120,8 @@ This tutorial is demonstrated in the following animation:
-## Links + +## 10. Links [^1]: [Wikipedia, Multilayer Perceptron](https://en.wikipedia.org/wiki/Multilayer_perceptron) diff --git a/lang/en/docs/tutorials/templating/overview.md b/lang/en/docs/tutorials/templating/overview.md index bb4f1f529..820c4ebe9 100644 --- a/lang/en/docs/tutorials/templating/overview.md +++ b/lang/en/docs/tutorials/templating/overview.md @@ -1,6 +1,6 @@ # Tutorials on Templating -In the present section we provide some examples of how [templates](../../workflows/templating/overview.md) for generating simulation input files, can be written and customized by using the [template engine](../../workflows/templating/jinja.md) implemented on our platform. +In the present section we provide some examples of how [templates]({{ reference_url }}/workflows/templating/overview/) for generating simulation input files, can be written and customized by using the [template engine]({{ reference_url }}/workflows/templating/jinja/) implemented on our platform. ## [Setting Input Parameter Based on Elemental Composition](set-magnetic-moment.md) diff --git a/lang/en/docs/tutorials/templating/set-flag-by-composition.md b/lang/en/docs/tutorials/templating/set-flag-by-composition.md index c79a407b6..89e945323 100644 --- a/lang/en/docs/tutorials/templating/set-flag-by-composition.md +++ b/lang/en/docs/tutorials/templating/set-flag-by-composition.md @@ -1,19 +1,25 @@ +--- +render_macros: true +--- # Setting Input Parameter Based on Elemental Composition -## Introduction +## 1. Introduction -In this page we review setting input flags based on the data about material(s) and elemental constitution in particular. We present the template source that can be further re-used (copied and inserted) during the [workflow design](../../workflow-designer/overview.md) stage. +This page explains how to set input flags based on material elemental composition data. The template source presented below can be re-used (copied and inserted) during the [workflow design]({{ interface_url }}/workflow-designer/overview/) stage. -## Source -The code below automatically sets the value of the "ENCUT" variable to higher values for materials that contain Nitrogen within their structures than for those than don't. In particular, ENCUT = 600 eV if Nitrogen is present, or ENCUT = 450 eV otherwise. This variable is found in [VASP](../../software-directory/modeling/vasp/overview.md) input file, and defines the cutoff energy characterizing the precision of the [DFT computation](../../models-directory/dft/parameters.md). +## 2. Source +The code below sets the value of the "ENCUT" variable to a higher value for materials that contain Nitrogen than for those that do not. ENCUT is set to 600 eV if Nitrogen is present, or 450 eV otherwise. This variable is found in [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) input files and defines the cutoff energy characterizing the precision of the [DFT computation]({{ reference_url }}/models-directory/dft/parameters/). + +{% raw %} ```jinja {% spaceless %} {% set high_cutoff_element = "N" %} {% set poscar_string = input.POSCAR|e("js") %} {% set atoms = poscar_string.split('direct')[0] %} -{% set lines = atoms.split("\u000A") %} +{% set lines = atoms.split(" +") %} {% set element_lines = lines[5] %} {% if element_lines.includes(high_cutoff_element) %} {% set ENCUT = 600 %} @@ -23,40 +29,42 @@ The code below automatically sets the value of the "ENCUT" variable to higher va ENCUT = {{ ENCUT }} {% endspaceless %} ``` +{% endraw %} + +Each line in the above block of statements is described in the following sections. -Each line number in the above block of statements is described in what follows. +### 2.1. Spaceless rendering -### 1. Spaceless Rendering +The initial {% raw %}`{% spaceless %}`{% endraw %} flag is explained [here]({{ reference_url }}/workflows/templating/swig/#spaceless). -The initial `{% spaceless %}` flag is explained [here](../../workflows/templating/swig.md#spaceless) +### 2.2. Set the element requiring a higher cutoff parameter (Nitrogen) -### 2. Set Element Requiring Higher Cutoff Parameter (Nitrogen) +The logic of the template begins by defining the element that needs a high plane-wave cutoff as "N" for Nitrogen, using the [set statement]({{ reference_url }}/workflows/templating/jinja/#variables-assignment). -We begin the logic of our template by defining the element that needs a high plane-wave cutoff to be "N" for Nitrogen, using the [set statement](../../workflows/templating/jinja.md#variables-assignment). +### 2.3. Read structural data -### 3. Read Structural Data +The POSCAR input file for [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) is then read, and the text contents of this file are assigned to the variable "poscar_string". Examples of POSCAR files are included at the end of this section. -We then read the POSCAR input file for [VASP](../../software-directory/modeling/vasp/overview.md), and assign the text contents of this file to the variable "poscar_string". Examples of POSCAR files are included at the end of this section. +### 2.4. Extract elements contained in the material -### 4 - 6. Extract Elements Contained in Material +The lines within the POSCAR file containing the element chemical symbols are identified by using the "split" function to break up the file text at every occurrence of the argument passed to this function. -We then identify the lines within the POSCAR file containing the element chemical symbols, by using the "split" function for breaking up the file text contents at every occurrence of the argument passed to this function. +The lines are first split at the mention of the `direct` string, taking all preceding content. This content is then split at every new line (denoted by the newline unicode character). As shown in the POSCAR examples below, the line under index 5 in the POSCAR format (counting from zero at the top of the file) contains the chemical symbols. The list of elements is assigned to the variable "element_lines". -We first break the lines at the mention of the `direct` string, and take all the preceding content. We then split this content at every new line (denoted by the newline unicode character "\u000A"). As can be seen from the POSCAR examples shown below, the line under index 5 in the POSCAR format (starting to count from zero at the top of the file) is the line containing the chemical symbols. The list of elements contained in the material is consequently assigned to the variable "element_lines". +### 2.5. Check for the presence of Nitrogen in the material -### 7 - 11. Check for Presence of Nitrogen in Material +An "if/else" [conditional block]({{ reference_url }}/workflows/templating/jinja/#conditionals) checks for the presence of "N" within the list of elements extracted from the POSCAR file. If a positive match is found, "ENCUT" is set to 600 eV; otherwise it is set to 450 eV. -An "if/else" [conditional block of statements](../../workflows/templating/jinja.md#conditionals) is then included in the remainder of the above template. This checks for the presence of "Al" within the list of elements extracted from the POSCAR file of the material under investigation. If a positive match is encountered, then the variable "ENCUT" for the material simulation is correspondingly set to the higher value of 600 eV, otherwise in the contrary case it is set to a lower 450 eV. +### 2.6. Print the ENCUT variable result -### 12. Print Encut Variable Result +The value of "ENCUT" identified in the preceding step is printed using the double curly braces notation for variable output in Jinja syntax. -We conclude this first templating example by printing out the value of "ENCUT" identified in the preceding step, through the use of the double curly braces notation for printing the value of variables in the Jinja syntax. -### Example Outputs +## 3. Example outputs -#### Negative Match +### 3.1. Negative match -Let us first assume that the POSCAR file under consideration consists in the following crystal structure data. +Assume the POSCAR file under consideration consists of the following crystal structure data: ``` Ga4 Sb4 @@ -77,11 +85,11 @@ direct 0.750000 0.750000 0.750000 Sb ``` -Hence, the output of the above template at the moment of rendering would in this case be `ENCUT =450`, since no Nitrogen is present in this particular material structure. +The output of the template at rendering time would be `ENCUT =450`, since no Nitrogen is present. -#### Positive Match +### 3.2. Positive match -If, on the other hand, we consider the following alternative crystal structure definition, also expressed in a POSCAR format. +Consider the following alternative crystal structure in POSCAR format: ``` Example @@ -98,10 +106,11 @@ direct 0.333333000 0.666667000 0.380713000 N ``` -Then the rendered output of the template would in this case consist in `ENCUT = 600`, since Nitrogen is this time present within the crystal structure. +The rendered output in this case is `ENCUT = 600`, since Nitrogen is present. + -### Animation +## 4. Video walkthrough -In the animation below, we demonstrate how to switch between viewing the POSCAR structure file within the [Workflow Designer Interface](../../workflow-designer/unit-editor/input-templates.md), to viewing the same template as above for setting the "ENCUT" parameter, and finally its rendered output. The final result is `ENCUT =600` in this case since the material under investigation consists in the Nitrogen-containing Al2N2 structure, shown in the above POSCAR file example. +The animation below demonstrates switching between viewing the POSCAR structure file within the [Workflow Designer Interface]({{ interface_url }}/workflow-designer/unit-editor/input-templates/), viewing the template for setting the "ENCUT" parameter, and its rendered output. The result is `ENCUT =600` since the material under investigation is the Nitrogen-containing Al₂N₂ structure. diff --git a/lang/en/docs/tutorials/templating/set-magnetic-moment.md b/lang/en/docs/tutorials/templating/set-magnetic-moment.md index d01ec4986..46938b56e 100644 --- a/lang/en/docs/tutorials/templating/set-magnetic-moment.md +++ b/lang/en/docs/tutorials/templating/set-magnetic-moment.md @@ -1,20 +1,26 @@ +--- +render_macros: true +--- # Setting Magnetic Moment on Atoms by Specie -## Introduction +## 1. Introduction -In this page we review setting input atom-specific flags based on the data about material. We present the template source that can be further re-used (copied and inserted) during the [workflow design](../../workflow-designer/overview.md) stage. +This page explains how to set atom-specific input flags based on material data. The template source presented below can be re-used (copied and inserted) during the [workflow design]({{ interface_url }}/workflow-designer/overview/) stage. -## Source -The template code below sets the value of magnetic moments for ferromagnetic elements present in a material structure to number `5`, and alternates the sign. Non-magnetic elements are instead set to zero. The rendered output of this template is suitable for a [VASP](../../software-directory/modeling/vasp/overview.md) simulation. +## 2. Source +The template code below sets the value of magnetic moments for ferromagnetic elements present in a material structure to 5 and alternates the sign. Non-magnetic elements are set to zero. The rendered output is suitable for a [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) simulation. + +{% raw %} ```jinja MAGMOM = {% spaceless %} {% set magnetic_elements = ['V', 'Cr', 'Mn', 'Fe', 'Co', 'Ni'] %} {% set poscar_string = input.POSCAR|e("js") %} {% set coordinates = poscar_string.split('direct')[1] %} {% set sign = 1 %} -{% for line in coordinates.split("\u000A") %} +{% for line in coordinates.split(" +") %} {% if loop.index0 > 0 %} {% set trimmed_line = line.trim() | replace(' +(?= )','','g') %} {% set element = trimmed_line.split(' ')[3] %} @@ -25,42 +31,45 @@ MAGMOM = {% spaceless %} {% endif magnetic_elements.includes(element) %} {% if is_magnetic == 0 %}{{' '}}{{ 0 }}{% endif %} {% endif loop.index0 %} -{% endfor line in coordinates.split("\u000A") %} +{% endfor line in coordinates.split(" +") %} {% endspaceless %} ``` +{% endraw %} + +Each line in the above block of statements is described in the following sections. -Each line number in the above block of statements is further explained in the ensuing sections. +### 2.1. Define the MAGMOM variable -### 1. Define MAGMOM Variable +The "MAGMOM" variable [^1] is defined for inclusion in the [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) "INCAR" input parameters file. The {% raw %}`{% spaceless %}`{% endraw %} flag is explained [here]({{ reference_url }}/workflows/templating/swig/#spaceless). -We begin by defining the "MAGMOM" variable [^1], which will be included in the input file for a [VASP](../../software-directory/modeling/vasp/overview.md) computation, within the "INCAR" input parameters file associated with this code. `{% spaceless %}` flag is explained [here](../../workflows/templating/swig.md#spaceless) +### 2.2. Define ferromagnetic elements -### 2. Define Ferromagnetic Elements +The ferromagnetic elements that need magnetic moments assigned are defined using the [set statement]({{ reference_url }}/workflows/templating/jinja/#variables-assignment): Vanadium (V), Chromium (Cr), Manganese (Mn), Iron (Fe), Cobalt (Co), and Nickel (Ni). -In the second line, we [set](../../workflows/templating/jinja.md#variables-assignment) the ferromagnetic elements, that need to have magnetic moments attributed to them, to be constituted of the following list: Vanadium (V), Chromium (Cr), Manganese (Mn), Iron (Fe), Cobalt (Co), and Nickel (Ni). +### 2.3. Read POSCAR content -### 3. Read POSCAR Content +The content of the POSCAR file used by [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/), containing the numerical data defining the crystal structure, is read and assigned to the variable "poscar_string". -We then read the content ot POSCAR used by [VASP](../../software-directory/modeling/vasp/overview.md), containing the numerical data defining the crystal structure under investigation. We assign the text contents of this structure file to the variable "poscar_string". +### 2.4. Read atomic coordinates -### 4. Read Atomic Coordinates +The lines containing atomic coordinates and element chemical symbols within the POSCAR file are extracted by splitting the file contents following the "direct" line, and assigned to the "coordinates" variable. -The lines containing the atomic coordinates and element chemical symbols within the POSCAR file are then read. This is done by splitting the file contents ensuing the "direct" line, which are then passed to the "coordinates" variable. +### 2.5. Set the magnetic moments -### 5-17. Set Magnetic Moments +The list of atomic coordinates is looped through using a [for loop]({{ reference_url }}/workflows/templating/jinja/#for-loops). -The list of atomic coordinates defined previously is then looped over through the use of a [for loop](../../workflows/templating/jinja.md#for-loops). +The element symbol at the end of each coordinate line is isolated and checked against the list of ferromagnetic elements through a [conditional statement]({{ reference_url }}/workflows/templating/jinja/#conditionals). If a positive match is detected, the element is assigned a magnetic moment value of ±5 in alternating order. Otherwise, a magnetic moment of zero is assigned. -The element symbol indicated at the end of each coordinate line is isolated in turn (line 8) and assigned to the variable "element", which is checked against the aforementioned list of ferromagnetic elements (line 10) through a [conditional statement](../../workflows/templating/jinja.md#conditionals). If a positive match is detected, this element is assigned a magnetic moment value of +/- 5 in an alternating order (line 11). Otherwise, in case the element is found to be non-ferromagnetic, it is given a magnetic moment of zero (line 15). +### 2.6. Return the final output -### 18. Return Final Output +The final "MAGMOM" variable is returned once the template is rendered, as a list of magnetic moment values. -The final result of the "MAGMOM" variable is returned once the template is rendered, as a list of magnetic moment values. -### Example Output +## 3. Example output -Let us consider the following hypothetical example of a material structure (Cobalt Oxide), inserted under the POSCAR format. +Consider the following hypothetical example of a material structure (Cobalt Oxide) in POSCAR format: ``` Cobalt Oxide @@ -86,18 +95,20 @@ direct 0.611256 0.388744 0.611256 O ``` -The rendered output of the above template for this particular case would be the following line, since Cobalt is ferromagnetic and Oxygen is not. +The rendered output for this case is the following line, since Cobalt is ferromagnetic and Oxygen is not: ``` MAGMOM = 5 -5 5 -5 5 -5 5 -5 0 0 0 0 0 ``` -### Animation -In the following animation, we demonstrate how to switch between viewing the POSCAR structure file for Cobalt Oxide within [Workflow Designer](../../workflow-designer/unit-editor/input-templates.md), to viewing the template for adding the MAGMOM parameter to the INCAR input file, and finally its rendered output. +## 4. Video walkthrough + +The animation below demonstrates switching between viewing the POSCAR structure file for Cobalt Oxide within [Workflow Designer]({{ interface_url }}/workflow-designer/unit-editor/input-templates/), viewing the template for adding the MAGMOM parameter to the INCAR input file, and its rendered output. -## Links + +## 5. Links [^1]: [MAGMOM Tag in VASP, Official Documentation](https://cms.mpi.univie.ac.at/vasp/vasp/MAGMOM_tag.html) diff --git a/lang/en/docs/ui/account-menu.md b/lang/en/docs/ui/account-menu.md new file mode 100644 index 000000000..93969aff0 --- /dev/null +++ b/lang/en/docs/ui/account-menu.md @@ -0,0 +1,66 @@ +# Account Menu + +Clicking [Account Badge](../accounts/ui/account-badge.md) in the top right +corner opens the Account Navigator modal on the right-hand side of the page. The +general appearance of this sidebar is portrayed in the following image. + +![Account Menu](../images/ui/account-menu.webp "Account Menu") + +The following menu entries are worth noticing. + +Menu Item & Icon | Description +:--------------- |:------------- +Account Switcher | Enables switching between personal and organizational accounts. Opens in a small window showing the user's active accounts. Clicking one triggers switch to that account. +Quota, Queue, Service Level | This section shows a quick snapshot of the status of the user's quota: Storage, job queue breakdown and the service level. The user can easily upgrade the service level, to obtain more compute power, by clicking the upgrade button. If the user wants to compare service levels, the user can find more information in the Account menu, below. +Account Balance | A snapshot of the user's current balance, quickly credit the balance using the Apply Credit Button +   [Account Preferences](../accounts/ui/preferences-overview.md) | A link to [the user's account](../accounts/ui/profile-page.md) page. In here the user can find his/her profile, preferences and service level. +   [Billing & Payments]({{ reference_url }}/accounts/payments-charges/) | A link to the [billings and payments]({{ reference_url }}/accounts/payments-charges/) section. In here the user can inspect compute charges, payment records and payment methods. +   Remote Desktop | Opens a desktop session (VNC) on Exabyte.io remote server. +   Invite a friend | Earn credits by inviting people to join Exabyte.io +   Logout | Secure logout + + +## Account Switcher + +Switching between Accounts is described in a +[separate part of the documentation](../accounts/ui/switcher.md). + +## Account Snapshot + +The right-hand sidebar also offers a snapshot of the Account, containing some +basic information: storage [quota]({{ reference_url }}/accounts/quota/) on each available +computing cluster, [job]({{ reference_url }}/jobs/overview/) queue summary, [service level]({{ reference_url }}/accounts/service-levels/), and finally the current [balance]({{ reference_url }}/accounts/balance/). The possibility to expand or replenish these two latter +items is also offered next to each one of them. + + +## Account Preferences + +Clicking `Account Preferences` lets the user +customize account-related information and settings. Such preferences are +reviewed extensively in their own [documentation section]( +../accounts/ui/preferences-overview.md). + +## Billing and Payments + +The `Billing and Payments` link +redirects to the Billing page. Here, a series of tabs at the top show in turn +the different charges applied to the Account (for each job separately) +, the payments made by the +owner , and the chosen payment +methods . More details about such +billing and payments information can be found [here]( +../accounts/accounting/overview.md). + + +## Invite a Friend + +The `Invite a Friend` option +lets users send an email invitation to a friend or colleague who might also +benefit from using our platform. Both the sender and recipient will get a gift +in the form of Account balance credit when the new registration is approved. + +## Logout + +The `Logout` option should be +pressed once operations under the current Account have been completed. Other +users can then login to the platform with their own credentials. diff --git a/lang/en/docs/ui/header-footer.md b/lang/en/docs/ui/header-footer.md index b9e51a914..c4bb7f45d 100644 --- a/lang/en/docs/ui/header-footer.md +++ b/lang/en/docs/ui/header-footer.md @@ -2,11 +2,13 @@ The appearance and functionality of the header bar is illustrated below. -![ui-header](../images/ui/ui-header.png "UI header") +![ui-header](../images/ui/ui-header.webp "UI header with Terminal dropdown menu") ## Left-hand Sidebar Trigger -The left-hand sidebar can be activated by clicking the top left corner anchor , or alternatively through the toggle slider towards the right-end of the header. +The left-hand sidebar can be activated by clicking the top left corner anchor +, or alternatively through the +toggle slider towards the right-end of the header. ## Link to Homepage @@ -14,7 +16,8 @@ Navigate back to the homepage of the account by clicking the main company logo. ## Previous Page Trigger -The user can revert to the previous screen using the back arrow, similarly to internet browsers. +The user can revert to the previous screen using the back arrow, similarly to +internet browsers. ## Page Name @@ -22,8 +25,17 @@ The title of the page currently viewed is shown for reference purposes. ## Right-hand Sidebar Trigger -The right-hand sidebar can be opened by clicking the [Account Badge](../accounts/ui/account-badge.md) at the top-right corner of the page. +The right-hand sidebar can be opened by clicking the [Account Badge]( +../accounts/ui/account-badge.md) at the top-right corner of the page. + +## Terminal and Remote Desktop + +The Terminal and Remote Desktop functionality provide alternative methods for +accessing Accounts. More information about such practices can be retrieved +[here]({{ cli_url }}/remote-connection/overview/). ## Footer -Additional links can be accessed from within the footer: the homepage of Exabyte.io, the present documentation, and relevant information about our privacy conditions and Terms of Service. +Additional links can be accessed from within the footer: the homepage of +Mat3ra.com, the present documentation, and relevant information about our +privacy conditions and Terms of Service. diff --git a/lang/en/docs/ui/left-sidebar.md b/lang/en/docs/ui/left-sidebar.md index 36f9c12dc..18b4c5e94 100644 --- a/lang/en/docs/ui/left-sidebar.md +++ b/lang/en/docs/ui/left-sidebar.md @@ -1,56 +1,67 @@ # Left-hand Sidebar (Items Navigation) -Click the Trigger Icon in the top-left corner to open and navigate sidebar as shown below. +By default, the left-hand sidebar items are minimized with only icons visible, +hovering mouse over the minimized sidebar will expand the sidebar as shown +below. -![Left-hand Sidebar](../images/ui/ui-left-sidebar.png "Left-hand Sidebar") +![Left-hand Sidebar](../images/ui/ui-left-sidebar.webp "Left-hand Sidebar") ## Items -The following table summarizes the different types of items contained in this sidebar. The more complex entries are -further described comprehensively in dedicated documentation pages, referenced in the paragraphs that follow the table. - -| Menu Item & Icon | Description -| :--------------------------- |:------------- -|   Load | Compute load shows how busy the compute system is. There are three levels: low, medium and high. It is opportune to start jobs when the indicator is low in order to achieve a quicker turnaround. Conversely, if the compute load is high, wait times for job turnaround may be longer. -|   Dashboard | Dashboard highlights important datapoints and files of recent activity -|   Create Job | This is a quick link to get started straight away on a job. Jobs saved are collected in the default user project, which is named the same as the username and can be found in the projects page]. -|   Projects | Shows the user's list of projects -|   Jobs | Shows the user's list of jobs -|   Materials | Shows the user's list of materials -|   Workflows | Shows the user's list of Workflows -|   Bank | Import pre-defined Materials and Workflows from a central "Bank" repository -|   Dropbox | File browser for cloud-based file/directories -|   Accounts | General list of user accounts -|   Shared with me | Items made available by other users -|   Shared publicly | Items shared to the general public -|   Documentation | A link to this documentation +The following table summarizes the different types of items contained in this +sidebar. The more complex entries are further described comprehensively in +dedicated documentation pages. + +Menu Item & Icon | Description +:--------------------------- |:------------- +   Dashboard | Dashboard highlights important datapoints and files of recent activity +   Create Job | This is a quick link to get started straight away on a job. Jobs saved are collected in the default user project, which is named the same as the username and can be found in the projects page. +   Projects | Shows the user's list of projects +   Jobs | Shows the user's list of jobs +   Materials | Shows the user's list of materials +   Workflows | Shows the user's list of Workflows +   Bank | Import pre-defined Materials and Workflows from a central "Bank" repository +   Dropbox | File browser for cloud-based file/directories +   Accounts | General list of user accounts +   Shared with me | Items made available by other users +   Shared publicly | Items shared to the general public +   Documentation | A link to this documentation ## Dashboard -The Dashboard component of the user interface is reviewed in the [following page](../ui/specific/dashboard.md). +The Dashboard component of the user interface is reviewed in the +[following page](../ui/specific/dashboard.md). ## Create Job -Job creation, explained in more detail [here](../jobs/actions/create.md), can be accessed from this link. +Job creation, explained in more detail [here](../jobs/actions/create.md), can be +accessed from this link. ## Projects -Click "Projects" to navigate to the list of the [Projects](../jobs/projects.md). +Click "Projects" to navigate to the list of the [Projects]({{ reference_url }}/jobs/projects/). ## Jobs, Materials and Workflows *Entities* -The "Jobs", "Materials" and "Workflows" pages contain lists of the respective entities. Due to the numerous different aspect that these entities have in common, they are reviewed together starting from [this page](../entities-general/overview.md). +The "Jobs", "Materials" and "Workflows" pages contain lists of the respective +entities. Due to the numerous different aspect that these entities have in +common, they are reviewed together starting from [this page]({{ reference_url }}/entities-general/overview/). ## Bank -Links to [Entity Bank](../entities-general/bank.md) pages for Materials and Workflows are presented under the "Bank" menu. +Links to [Entity Bank]({{ reference_url }}/entities-general/bank/) pages for Materials and +Workflows are presented under the "Bank" menu. ## Dropbox -[Dropbox](../data-in-objectstorage/dropbox.md), a central limited-capacity cloud-based data storage, is available under this link. +[Dropbox]({{ resources_url }}/data-in-objectstorage/dropbox/), a central limited-capacity +cloud-based data storage, is available under this link. ## Accounts and Data Sharing -Information about the other user accounts present in the Exabyte platform, about data shared bilaterally between accounts, and about data made publicly-available to the entire users community, can also be accessed from within the final section of the menu. +Information about the other user accounts present in the Exabyte platform, about +data shared bilaterally between accounts, and about data made publicly-available +to the entire users community, can also be accessed from within the final +section of the menu. diff --git a/lang/en/docs/ui/overview.md b/lang/en/docs/ui/overview.md index 68b34181a..27ebc4ec5 100644 --- a/lang/en/docs/ui/overview.md +++ b/lang/en/docs/ui/overview.md @@ -1,38 +1,46 @@ -# Component Types +# User Interface Components -We subdivide the generic user interface into universal components that are present in each and every page, and other components that appear in specific cases. +There are two types of UI components: (1) global components that are present in +each and every page, and (2) page specific components that appear or change +according to the page context and functionality. -!!!note "Coloring of the highlighted sections in images" - In images presented throughout this documentation manual, we encircle the relevant interface components in **red**, and the access points (or click triggers) to the components in **orange**. -## Universal Components +## Global Components -Five components are highlighted in the image below. Clicking each area of this image redirects the user to the corresponding documentation page. +Below is the screenshot of the Exabyte platform homepage, expanded left-hand +sidebar, and Account menu opened. There are three global UI components in the +Mat3ra web interface: - +1. [header and footer areas](header-footer.md) +2. [left-hand sidebar](left-sidebar.md) +3. [account menu](account-menu.md). - - - - - - - +UI Overview -## Specific Components +## Page Specific Components -Other general user interface components are instead accessible only from specific locations. The panels highlighted below are worth a separate discussion. +Other general user interface components are instead accessible only from +specific locations, such as the Navigation Tab bar, which is present in the +Materials, Workflows, and Jobs pages. -![ui-specific](../images/ui/ui-specific.png "ui specific") +![ui-specific](../images/ui/ui-specific.webp "ui specific") ### 1. [Link to Homepage Navigation](specific/homepage.md) -The Navigation page is accessible through our company logo present at all times in the top [header bar](header-footer.md). [This page](specific/homepage.md) explains how to use Navigation to make the initial general choices on the nature of the computations to be performed on our platform. +The Navigation page is accessible through our company logo present at all times +in the top [header bar](header-footer.md). [This page](specific/homepage.md) +explains how to use Navigation to make the initial general choices on the nature +of the computations to be performed on our platform. ### 2. [Link to Dashboard](specific/dashboard.md) -A system status "Dashboard" can be accessed via the [left-hand sidebar menu](left-sidebar.md). It is explained in more detail in [this page](specific/dashboard.md). +A system status "Dashboard" can be accessed via the [left-hand sidebar menu]( +left-sidebar.md). It is explained in more detail in [this page]( +specific/dashboard.md). ### 3. [Tabs Navigation](specific/tabs-navigator.md) -Numerous pages on our platform, and most notably the [Account Profile](../accounts/ui/profile-page.md) page, contain a series of Tabs for ease of navigation within the page. Such Tabs are reviewed [here](specific/tabs-navigator.md). +Numerous pages on our platform, and most notably the [Account Profile]( +../accounts/ui/profile-page.md) page, contain a series of Tabs for ease of +navigation within the page. Such Tabs are reviewed [here]( +specific/tabs-navigator.md). diff --git a/lang/en/docs/ui/right-sidebar.md b/lang/en/docs/ui/right-sidebar.md deleted file mode 100644 index f1ece8b66..000000000 --- a/lang/en/docs/ui/right-sidebar.md +++ /dev/null @@ -1,52 +0,0 @@ -# Right-hand sidebar (account navigation) - -Clicking [Account Badge](../accounts/ui/account-badge.md) in the top right corner opens the Account Navigator, in the form of a sidebar menu towards the right-hand side of the page. The general appearance of this sidebar is portrayed in the following image. - -![Right-hand sidebar](../images/ui/ui-right-sidebar.png "Right-hand sidebar") - -The following menu entries are worth noticing. - -| Menu Item & Icon | Description -|:----------------------------------------------------------------------- |:------------- -| Account Switcher | Enables switching between personal and organizational accounts. Opens in a small window showing the user's active accounts. Clicking one triggers switch to that account. -| Quota, Queue, Service Level | This section shows a quick snapshot of the status of the user's quota: Storage, job queue breakdown and the service level. The user can easily upgrade the service level, to obtain more compute power, by clicking the upgrade button. If the user wants to compare service levels, the user can find more information in the Account menu, below. -| Account Balance | A snapshot of the user's current balance, quickly credit the balance using the Apply Credit Button -|   [Account Preferences](../accounts/ui/preferences-overview.md) | A link to [the user's account](../accounts/ui/profile-page.md) page. In here the user can find his/her profile, preferences and service level. -|   [Billing & Payments](../accounts/payments-charges.md) | A link to the [billings and payments](../accounts/payments-charges.md) section. In here the user can inspect compute charges, payment records and payment methods. -|   Terminal | Access to an in-browser command line terminal through which the user can directly access his/her cloud account. -|   Remote Desktop | Opens a desktop session (VNC) on Exabyte.io remote server. -|   Invite a friend | Earn credits by inviting people to join Exabyte.io -|   Logout | Secure logout - - -## Account Switcher - -Switching between Accounts is described in a [separate part of the documentation](../accounts/ui/switcher.md). - -## Account Snapshot - -The right-hand sidebar also offers a snapshot of the Account, containing some basic information: storage [quota](../accounts/quota.md) on each available computing cluster, [job](../jobs/overview.md) queue summary, [service level](../accounts/service-levels.md), and finally the current [balance](../accounts/balance.md). The possibility to expand or replenish these two latter items is also offered next to each one of them. - -An example of snapshot is shown below, for the case of an account with access to three different (relatively empty) clusters, and with no jobs currently being submitted or active. - -![Account Snapshot](../images/ui/account-snapshot.png "Account Snapshot") - -## Account Preferences - -Clicking `Account Preferences` lets the user customize account-related information and settings. Such preferences are reviewed extensively in their own [documentation section](../accounts/ui/preferences-overview.md). - -## Billing and Payments - -The `Billing and Payments` link redirects to the Billing page. Here, a series of tabs at the top show in turn the different charges applied to the Account (for each job separately) , the payments made by the owner , and the chosen payment methods . More details about such billing and payments information can be found [here](../accounts/accounting/overview.md). - -## Terminal and Remote Desktop - -The Terminal and Remote Desktop functionality provide alternative methods for accessing Accounts. More information about such practices can be retrieved [here](..//remote-connection/overview.md). - -## Invite a Friend - -The `Invite a Friend` option lets users send an email invitation to a friend or colleague who might also benefit from using our platform. Both the sender and recipient will get a gift in the form of Account balance credit when the new registration is approved. - -## Logout - -The `Logout` option should be pressed once operations under the current Account have been completed. Other users can then login to the platform with their own credentials. diff --git a/lang/en/docs/ui/specific/dashboard.md b/lang/en/docs/ui/specific/dashboard.md index ce1983577..8655fd1de 100644 --- a/lang/en/docs/ui/specific/dashboard.md +++ b/lang/en/docs/ui/specific/dashboard.md @@ -1,30 +1,42 @@ # User Dashboard -The Dashboard page provides the user with an instant snapshot of the system status, and of his/her own recent work. Four main component panels can be recognized, as shown below. +The Dashboard page provides the user with an instant snapshot of the system +status, and of his/her own recent work. Four main component panels can be +recognized, as shown below. -![User Dashboard](../../images/ui/user-dashboard.png "User Dashboard") +![User Dashboard](../../images/ui/user-dashboard.webp "User Dashboard") ## 1. Jobs summary -The "Jobs Summary" panel summarizes the total number of [jobs](../../jobs/overview.md) run during a certain period of time, as indicated at the top of the panel. It also offers a break down of the job's current status between "Active", "Submitted", "Pre-submission", "Success" and "Errors". There is finally a quick link to jump to the jobs list at the bottom of the panel, labelled "View All Jobs". +The "Jobs Summary" panel summarizes the total number of [jobs]({{ reference_url }}/jobs/overview/) run during a certain period of time, as indicated at the +top of the panel. It also offers a break down of the job's current status +between "Active", "Submitted", "Pre-submission", "Success" and "Errors". There +is finally a quick link to jump to the jobs list at the bottom of the panel, +labelled "View All Jobs". ## 2. Compute Usage -The "Compute Usage" chart shows the combined financial cost for recent calculations, over the given duration of time. +The "Compute Usage" chart shows the combined financial cost for recent +calculations, over the given duration of time. ## 3. Storage Quota -This widget displays a summary of the user's current [storage quota](../../accounts/quota.md), in the form of the ratio between used and total available storage space. The user can click the icon at the top-right corner of the panel to request an increase in storage space. In addition, the neighbouring icon can be used to refresh the data. +This widget displays a summary of the user's current [storage quota]({{ reference_url }}/accounts/quota/), in the form of the ratio between used and total +available storage space. The user can click the + icon at the top-right +corner of the panel to request an increase in storage space. In addition, the +neighbouring icon can be +used to refresh the data. ## 4. Datapoints -| Datapoint | Description -| :------------- |:------------- -| Total charges | Shows a summary of the total charges over all time -| Recent charges | Shows charges of last week -| Longest Job | Shows compute walltime of the longest job ever performed by the user -| Current Compute Load | Shows current server [compute load](../left-sidebar.md#items) (low/medium/high) -| Estimated Wait Time | Shows an estimated wait time for newly submitted jobs +Datapoint | Description +:------------- |:------------- +Total charges | Shows a summary of the total charges over all time +Recent charges | Shows charges of last week +Longest Job | Shows compute walltime of the longest job ever performed by the user +Current Compute Load | Shows current server [compute load](../left-sidebar.md#items) (low/medium/high) +Estimated Wait Time | Shows an estimated wait time for newly submitted jobs diff --git a/lang/en/docs/ui/specific/homepage.md b/lang/en/docs/ui/specific/homepage.md index 8bd03c006..1ec8448fb 100644 --- a/lang/en/docs/ui/specific/homepage.md +++ b/lang/en/docs/ui/specific/homepage.md @@ -1,128 +1,182 @@ -# Account Homepage / Entry Gateway +# Account Homepage (Entry Gateway) -When the user first logs into our platform, he/she is presented with the **Entry Gateway**. This homepage is presented under the user's **default Account**, which can be modified through the [Account Switcher](../../accounts/ui/switcher.md) by following [this procedure](../../entities-general/actions/set-default.md). The initial screen of the Entry Gateway can be retrieved at all times by clicking the Exabyte Company logo in the [header](../header-footer.md). +When a user first logs into our platform, he/she is presented with the +**Entry Gateway**. This homepage shows a summary of various entities such as +materials, workflows and jobs. + + presented under the user's +**default Account**, which can be modified through the [Account Switcher]( +../../accounts/ui/switcher.md) by following [this procedure]( +../../entities-general/actions/set-default.md). The initial screen of the Entry +Gateway can be retrieved from any page by clicking the Mat3ra Company logo in +the [header](../header-footer.md). ## Initial Options -Immediately after login, the user is first presented with three main options, as displayed in the image below. +Immediately after login, the user is first presented with three main options, as +displayed in the image below. -![Entry Gateway](../../images/ui/entry-gateway.png "Entry Gateway") +![Platform Homepage](../../images/ui/homepage.webp "Platform Homepage") -These initial options can be navigated by clicking their panels, or `Select` buttons. The overall result is a tree diagrams of sequential options, which will be reviewed throughout the rest of this documentation page. +These initial options can be navigated by clicking their panels, or `Select` +buttons. The overall result is a tree diagrams of sequential options, which will +be reviewed throughout the rest of this documentation page. !!!note "Access to platform features" - Numerous features can be accessed directly by opening either the [left-hand](../left-sidebar.md) or [right-hand](../right-sidebar.md) sidebars. Some options may still be under development. Only features already enabled are reviewed in this page. Please [contact us](../../ui/support.md) if you would like any of these features to be given urgent attention. + Numerous features can be accessed directly by opening either the + [left-hand](../left-sidebar.md) or [account menu](../account-menu.md). + Please [contact us](../../ui/support.md) if you have any features requests. ## Query Bar -A query bar is present on top of the page, allowing the options to be searched at any level. +A query bar is present on top of +the page, allowing the options to be searched at any level. ### Search Tags -This Query bar is populated automatically with tags as the options are selected by the user. The search is performed under the level of the latest tag. +This Query bar is populated automatically with tags as the options are selected +by the user. The search is performed under the level of the latest tag. -All tags can be removed simultaneously by clicking the "X" button on the right-hand side. This reverts the screen to its initial default appearance. Alternatively, each tag can be deleted in turn, which takes the interface up by one level each time. +All tags can be removed simultaneously by clicking the "X" button on the +right-hand side. This reverts the screen to its initial default appearance. +Alternatively, each tag can be deleted in turn, which takes the interface up by +one level each time. ### Search Suggestions -Suggestions are also displayed in real time under the query bar, as new search keywords are being entered. They can be added as tags to the query by clicking them. - -### Animation - -The query functionality is demonstrated in the following animation. Here, we first navigate to the "Run Simulations" option under "Modeling and Simulations", and then we revert back to the original screen by deleting the corresponding tags. - - +Suggestions are also displayed in real time under the query bar, as new search +keywords are being entered. They can be added as tags to the query by clicking +them. ## Modeling and Simulations -The first option allows for the creation of simulation workflows for material modeling. They can be based on any of the supported theoretical [models](../../models/overview.md), operated under the associated computational [methods](../../methods/overview.md) and [applications](../../software-directory/overview.md). +The first option allows for the creation of simulation workflows for material +modeling. They can be based on any of the supported theoretical [models]({{ reference_url }}/models/overview/), operated under the associated computational +[methods]({{ reference_url }}/methods/overview/) and [applications]({{ reference_url }}/software-directory/overview/). !!!note "Note: labeling of options" - In each flowchart presented in this page, a number or number-letter code is present inside each sub-component. It should be referred to in the headers of their dedicated explanation paragraphs. + In each flowchart presented in this page, a number or number-letter code is + present inside each sub-component. It should be referred to in the headers + of their dedicated explanation paragraphs. ![Modeling Flowchart](../../images/ui/modeling-flowchart.png "Modeling Flowchart") -### 1. Run Simulations +### 1. Run Simulations -Here, the user can choose to calculate [material properties](../../properties/overview.md) of interest, through the selection of the corresponding workflow template. Examples of pre-defined templates may include total energy calculations, phonon dispersions or electronic bandstructure calculations. +Here, the user can choose to calculate [material properties]({{ reference_url }}/properties/overview/) of interest, through the selection of the +corresponding workflow template. Examples of pre-defined templates may include +total energy calculations, phonon dispersions or electronic bandstructure +calculations. -A sample of workflow templates included under this option is portrayed in the image below. Clicking any of these available templates creates a new job implementing the workflow, under the default Project of the user's Account. +A sample of workflow templates included under this option is portrayed in the +image below. Clicking any of these available templates creates a new job +implementing the workflow, under the default Project of the user's Account. ![Workflow Templates](../../images/ui/workflow-templates.png "Workflow Templates") -### 2. Design Workflows +### 2. Design Workflows -Here, the possibility to design new computational workflows is offered. +Here, the possibility to design new computational workflows is offered. -#### 2A. Density Functional Theory +#### 2A. Density Functional Theory -For example, our platform supports the [Density Functional Theory](../../models-directory/dft/overview.md) (DFT) theoretical framework for executing electronic structure calculations, as implemented by the [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md) or [VASP](../../software-directory/modeling/vasp/overview.md) applications. Plans are under way to expand the offer to new atomistic simulation approaches, such as the classical Molecular Dynamics and Multi-scale techniques. +For example, our platform supports the [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT) theoretical framework for +executing electronic structure calculations, as implemented by the +[Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) +or [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) applications. +Plans are under way to expand the offer to new atomistic simulation approaches, +such as the classical Molecular Dynamics and Multi-scale techniques. -### 3. Connect Remotely +### 3. Connect Remotely -In this section, users can connect to our computational engine through alternative channels, other than our graphical user interface-based platform. +In this section, users can connect to our computational engine through +alternative channels, other than our graphical user interface-based platform. -In future, further remote connection interfaces will be offered to our customers, including for example the Jupyter web-based python environment provided with a set of pre-loaded libraries and tools. +In future, further remote connection interfaces will be offered to our +customers, including for example the Jupyter web-based python environment +provided with a set of pre-loaded libraries and tools. -#### 3A. Command Line Terminal +#### 3A. Command Line Terminal -The first remote connection method consists in the [Command Line interface/remote-connection/overview.md) (option "3A"). +The first remote connection method consists in the [Command Line interface]( +{{ cli_url }}/remote-connection/web-terminal/) (option "3A"). -#### 3B. Remote Desktop +#### 3B. Remote Desktop -Alternatively, the [Remote Desktop environment](../../remote-connection/remote-desktop.md) (option "3B") can also be employed. +Alternatively, the [Remote Desktop environment]( +{{ cli_url }}/remote-connection/remote-desktop/) (option "3B") can also be employed. ## Machine Learning -The Machine Learning functionality offered by our platform can be accessed as the second main option. Such functionality affords for the building of data-driven statistical models, based on results of materials simulations. The techniques implemented in our platform are the object of a [dedicated tutorial](../../tutorials/ml/train-ml-model.md). +The Machine Learning functionality offered by our platform can be accessed as +the second main option. Such functionality affords for the building of +data-driven statistical models, based on results of materials simulations. The +techniques implemented in our platform are the object of a [dedicated tutorial]({{ guide_url }}/tutorials/ml/overview/). -Machine Learning allows to predict new material properties by applying previously-trained models. In addition, new models can be trained by designing appropriate workflows, or use some of their pre-defined templates. +Machine Learning allows to predict new material properties by applying +previously-trained models. In addition, new models can be trained by designing +appropriate workflows, or use some of their pre-defined templates. !!! note "Limited availability" - Machine learning is a feature under active development and has a proof-of-concept status. Some items below may not be available yet. + Machine learning is a feature under active development and has a + proof-of-concept status. Some items below may not be available yet. ![Machine Learning Flowchart](../../images/ui/ml-flowchart.png "Machine Learning Flowchart") -### 2. Train New Model +### 2. Train New Model -New models can be created under this option, by either designing new training workflows or using a pre-defined template. +New models can be created under this option, by either designing new training +workflows or using a pre-defined template. -#### 2A. Regression linear +#### 2A. Regression linear -This option allows for the building of a predictive model using the linear regression method. Selecting this option creates the corresponding workflow under a new job inside the default Project. +This option allows for the building of a predictive model using the linear +regression method. Selecting this option creates the corresponding workflow +under a new job inside the default Project. ## Data Analytics -"Data analytics" option gives the user the possibility to interact with data as explained below. +"Data analytics" option gives the user the possibility to interact with data as +explained below. ![Data Analytics Flowchart](../../images/ui/data-flowchart.png "Data Analytics Flowchart") -### 1. Upload/import +### 1. Upload/import -Here, the user can upload or import a new material into the Account-owned collection from multiple external sources. +Here, the user can upload or import a new material into the Account-owned +collection from multiple external sources. -#### 1A. Upload Material from File +#### 1A. Upload Material from File -This option gives the user the possibility to [upload](../../materials/actions/upload.md) one or multiple local files containing the relevant crystallographic information about the material under investigation. We support the CIF, POSCAR and XYZ crystal structure data formats. +This option gives the user the possibility to [upload]( +../../materials/actions/upload.md) one or multiple local files containing the +relevant crystallographic information about the material under investigation. We +support the CIF, POSCAR and XYZ crystal structure data formats. -#### 1B. Import from a Web Database +#### 1B. Import from a Web Database -We have made the third-party "Materials Project" repository of materials available to the users of our platform. The materials contained there can thus be [imported](../../materials/actions/import.md) into the Account-owned collection. +We have made the third-party "Materials Project" repository of materials +available to the users of our platform. The materials contained there can thus +be [imported](../../materials/actions/import.md) into the Account-owned +collection. Support for other databases will be added in future. -### 2. Analyze Data +### 2. Analyze Data -This features allows materials to be [searched](../../entities-general/actions/search.md) and inspected by the user. +This features allows materials to be [searched]( +../../entities-general/actions/search.md) and inspected by the user. -#### 2A. Search my Materials +#### 2A. Search my Materials -This option searches only within the limits of the Account-owned collection of materials. +This option searches only within the limits of the Account-owned collection of +materials. -#### 2B. Search all Materials +#### 2B. Search all Materials -Publicly available materials, originating from across the entire platform, can be searched and analyzed collectively with this option. +Publicly available materials, originating from across the entire platform, can +be searched and analyzed collectively with this option. diff --git a/lang/en/docs/ui/specific/tabs-navigator.md b/lang/en/docs/ui/specific/tabs-navigator.md index 9b5c0163f..1116fd282 100644 --- a/lang/en/docs/ui/specific/tabs-navigator.md +++ b/lang/en/docs/ui/specific/tabs-navigator.md @@ -1,9 +1,15 @@ # Tabs Navigation -Tabs are widely used in our platform, and offer a convenient way of navigating the contents of a certain page. Tabs are needed, for example, when navigating the [Account Profile page](../../accounts/ui/profile-page.md) or the [Jobs Designer](../../jobs-designer/overview.md). +Tabs are widely used in our platform, and offer a convenient way of navigating +the contents of a certain page. Tabs are needed, for example, when navigating +the [Account Profile page](../../accounts/ui/profile-page.md) or the +[Jobs Designer](../../jobs-designer/overview.md). ## Switching Between Tabs -Switching between tabs and their associated content is achieved by clicking the relevant tab header towards the top of the page. If we take the [Jobs Designer](../../jobs-designer/overview.md) as an example, then its three main tabs can be browsed as shown in the following animation. +Switching between tabs and their associated content is achieved by clicking the +relevant tab header towards the top of the page. If we take the [Jobs Designer]( +../../jobs-designer/overview.md) as an example, then its three main tabs can be +browsed as shown in the following animation. diff --git a/lang/en/docs/ui/support.md b/lang/en/docs/ui/support.md index b858bd23c..6e4db2c9d 100644 --- a/lang/en/docs/ui/support.md +++ b/lang/en/docs/ui/support.md @@ -1,15 +1,30 @@ # Support Widget -Support Widget for Users to communicate with our support team. We attempt to respond to support requests as soon as possible, and, depending on the [service level](../accounts/service-levels.md). Normally, we reply within 24 hours during business days. Clicking the `Support` button at the bottom-left corner of any page opens the following dialog. +Support Widget for Users to communicate with our support team. We attempt to +respond to support requests as soon as possible, and, depending on the +[service level]({{ reference_url }}/accounts/service-levels/). Normally, we reply within 24 +hours during business days. Clicking the `Support` button at the bottom-left +corner of any page opens the following dialog. ![support-widget](../images/ui/support-widget.png "Support Widget") -## Required Information +## Required Information -Here, the user can submit support requests for overcoming technical issues. They will be dealt with by the Exabyte Support Staff in the shortest delay possible, via e-mail. For this reason, the user is kindly asked to provide his/her email address in the central text field of the widget, besides the question being posed. Optionally, the user's name can also be entered. Finally, the Support Widget offers the possibility to include up to five file attachments, in order to clarify the nature of the problem. We recommend attaching a screen cast video demonstrating the problem, with a screenshot(s) as a second option. +Here, the user can submit support requests for overcoming technical issues. They +will be dealt with by the Exabyte Support Staff in the shortest delay possible, +via e-mail. For this reason, the user is kindly asked to provide his/her email +address in the central text field of the widget, besides the question being +posed. Optionally, the user's name can also be entered. Finally, the Support +Widget offers the possibility to include up to five file attachments, in order +to clarify the nature of the problem. We recommend attaching a screen cast video +demonstrating the problem, with a screenshot(s) as a second option. ## Send Support Request -The email message can finally be sent to the Exabyte support staff by pressing the `Send` button at the bottom of the widget. The user shall immediately receive an email from our support server about the receipt of the request. +The email message can finally be sent to the Exabyte support staff by pressing +the `Send` button at the bottom of the widget. The user shall immediately +receive an email from our support server about the receipt of the request. -Alternatively, the message contents can be erased by selecting the `Cancel` option, or equivalently by clicking the minimization icon at the top-right corner of the widget. +Alternatively, the message contents can be erased by selecting the `Cancel` +option, or equivalently by clicking the minimization icon at the top-right +corner of the widget. diff --git a/lang/en/docs/workflow-designer/header-menu.md b/lang/en/docs/workflow-designer/header-menu.md index 6404cf0fc..6568d5a37 100644 --- a/lang/en/docs/workflow-designer/header-menu.md +++ b/lang/en/docs/workflow-designer/header-menu.md @@ -24,7 +24,7 @@ The Save operation can be accomplished via either of two alternative buttons, bo ## Inserting Add-ons -The header menu bar of the Workflows Designer interface finally gives the user the possibility to include [Add-ons](../workflows/addons/overview.md), in the form of an additional subworkflow. +The header menu bar of the Workflows Designer interface finally gives the user the possibility to include [Add-ons]({{ reference_url }}/workflows/addons/overview/), in the form of an additional subworkflow. The location of this drop-down menu is highlighted below: diff --git a/lang/en/docs/workflow-designer/overview.md b/lang/en/docs/workflow-designer/overview.md index b04840f26..b563b95ce 100644 --- a/lang/en/docs/workflow-designer/overview.md +++ b/lang/en/docs/workflow-designer/overview.md @@ -20,4 +20,4 @@ The Workflow Designer is structured into three main building blocks, and has the ## Add-ons -When creating a new workflow, important preliminary controls are typically required at the beginning of the workflow, and can be implemented in the context of the Workflow Designer interface in the form of [**add-on** subworkflow modules](../workflows/addons/overview.md). +When creating a new workflow, important preliminary controls are typically required at the beginning of the workflow, and can be implemented in the context of the Workflow Designer interface in the form of [**add-on** subworkflow modules]({{ reference_url }}/workflows/addons/overview/). diff --git a/lang/en/docs/workflow-designer/sidebar.md b/lang/en/docs/workflow-designer/sidebar.md index 7f59754cf..973e02eb1 100644 --- a/lang/en/docs/workflow-designer/sidebar.md +++ b/lang/en/docs/workflow-designer/sidebar.md @@ -1,6 +1,6 @@ # Items List Sidebar -Each workflow may contain multiple **subworkflows**, which are reviewed in the corresponding [documentation page](../workflows/components/subworkflows.md). The complete workflow can be visualized as a list of items in the sidebar on the left-hand side of the Workflow Designer interface. Here, the current workflow under consideration is presented in the form of a **flowchart**, with the modules executing different operations listed sequentially in logical order. This flowchart of subworkflows initially defaults to a single entry named "Empty Subworkflow" when a new workflow is being created from scratch. +Each workflow may contain multiple **subworkflows**, which are reviewed in the corresponding [documentation page]({{ reference_url }}/workflows/components/subworkflows/). The complete workflow can be visualized as a list of items in the sidebar on the left-hand side of the Workflow Designer interface. Here, the current workflow under consideration is presented in the form of a **flowchart**, with the modules executing different operations listed sequentially in logical order. This flowchart of subworkflows initially defaults to a single entry named "Empty Subworkflow" when a new workflow is being created from scratch. ## Selecting Active Items diff --git a/lang/en/docs/workflow-designer/subworkflow-editor/actions-menu.md b/lang/en/docs/workflow-designer/subworkflow-editor/actions-menu.md index 5a15ec4a2..3dba6f43e 100644 --- a/lang/en/docs/workflow-designer/subworkflow-editor/actions-menu.md +++ b/lang/en/docs/workflow-designer/subworkflow-editor/actions-menu.md @@ -8,7 +8,7 @@ The subworkflow name is visible at the left-end of the subworkflow actions menu ## Insert Add-ons -On the right-hand side of the subworkflow actions menu bar, a series of buttons and a number spinner are present. The first one of these, starting from the left, is a three-dotted drop-down menu button allowing for the insertion of further [Add-on subworkflows](../../workflows/addons/overview.md) to the overall workflow flowchart, in addition to those already described in the final section of [this page](../header-menu.md#inserting-add-ons). +On the right-hand side of the subworkflow actions menu bar, a series of buttons and a number spinner are present. The first one of these, starting from the left, is a three-dotted drop-down menu button allowing for the insertion of further [Add-on subworkflows]({{ reference_url }}/workflows/addons/overview/) to the overall workflow flowchart, in addition to those already described in the final section of [this page](../header-menu.md#inserting-add-ons). Following any such addition, the resulting sorted and complete list of subworkflows will always be shown on the left-hand sidebar of the Designer interface. @@ -18,7 +18,7 @@ To create a new subworkflow and insert it as part of the general workflow flowch ![Add Subworkflows](../../images/workflow-designer/sw-addition.png "Add Subworkflows") -In this dialog, the user can choose whether to insert a new subworkflow or a map through the first drop-down menu (please refer to [this](../../workflows/components/subworkflows.md) and [this other](../../workflows/components/maps.md) documentation pages respectively for an explanation of the fundamental differences between these two types of computing units). +In this dialog, the user can choose whether to insert a new subworkflow or a map through the first drop-down menu (please refer to [this]({{ reference_url }}/workflows/components/subworkflows/) and [this other]({{ reference_url }}/workflows/components/maps/) documentation pages respectively for an explanation of the fundamental differences between these two types of computing units). Secondly, the choice between whether to append or prepend this new map or subworkflow with respect to the currently selected subworkflow module can also be made. The user can identify and change the currently selected subworkflow by referring to the main left-hand sidebar of the overall Workflow Designer interface, and clicking on the corresponding item out of the contained flowchart list. Once the "Apply" button is pressed, the new subworkflow or map with default initial parameters will be added to the workflow flowchart at the desired position. diff --git a/lang/en/docs/workflow-designer/subworkflow-editor/compute.md b/lang/en/docs/workflow-designer/subworkflow-editor/compute.md index 9a9a41dc8..edaeeff52 100644 --- a/lang/en/docs/workflow-designer/subworkflow-editor/compute.md +++ b/lang/en/docs/workflow-designer/subworkflow-editor/compute.md @@ -2,10 +2,10 @@ By ticking the box "Run inside a separate job" in the "Compute" tab of the Subworkflow Editor, the user will be presented with a series of options for executing the complete workflow calculation on the Exabyte supercomputing cloud, according to all the various input parameters selected in the other three tabs of the Subworkflow Editor interface as outlined in their respective documentation pages. -Please refer to [this page](../../infrastructure/overview.md) for a detailed technical explanation about the cloud architecture and general supercomputing infrastructure implemented as part of the Exabyte platform. +Please refer to [this page]({{ resources_url }}/infrastructure/overview/) for a detailed technical explanation about the cloud architecture and general supercomputing infrastructure implemented as part of the Exabyte platform. The appearance of this "Compute" tab is displayed below, with its corresponding different sections highlighted: ![The Compute tab](../../images/workflow-designer/compute-tab.png "The Compute tab") -Please refer to [this page](../../infrastructure/compute/overview.md) for a comprehensive description of each separate section in this tab. +Please refer to [this page]({{ resources_url }}/infrastructure/compute/overview/) for a comprehensive description of each separate section in this tab. diff --git a/lang/en/docs/workflow-designer/subworkflow-editor/detailed-view.md b/lang/en/docs/workflow-designer/subworkflow-editor/detailed-view.md index 3802d35be..80ddf1715 100644 --- a/lang/en/docs/workflow-designer/subworkflow-editor/detailed-view.md +++ b/lang/en/docs/workflow-designer/subworkflow-editor/detailed-view.md @@ -11,9 +11,9 @@ For each Unit listed in the "Detailed View" tab, under the label "Properties", a As explained in the initial part of the [Overview tab page](overview-tab.md), the check-box "Draft" can optionally be ticked in each unit separately, at the top of each unit's "Properties" section. This option is suitable when only preliminary superficial tests of new prototypical subworkflows need to be performed. -The complete list of quantities available to be computed within the Subworkflow Editor interface are presented [in this page](../../properties/overview.md). +The complete list of quantities available to be computed within the Subworkflow Editor interface are presented [in this page]({{ reference_url }}/properties/overview/). ## The "Monitors" section -The second lower section of each unit's entry in the "Detailed View" tab, under the label "Monitors", offers the user the possibility to choose which output information to monitor during the course of the execution of the current subworkflow calculation. The options [listed in this page](../../properties/overview.md) are available. +The second lower section of each unit's entry in the "Detailed View" tab, under the label "Monitors", offers the user the possibility to choose which output information to monitor during the course of the execution of the current subworkflow calculation. The options [listed in this page]({{ reference_url }}/properties/overview/) are available. diff --git a/lang/en/docs/workflow-designer/subworkflow-editor/important-settings.md b/lang/en/docs/workflow-designer/subworkflow-editor/important-settings.md index efdf60bb7..d7bdb4e17 100644 --- a/lang/en/docs/workflow-designer/subworkflow-editor/important-settings.md +++ b/lang/en/docs/workflow-designer/subworkflow-editor/important-settings.md @@ -2,8 +2,8 @@ When a new subworkflow is being created from scratch, the "Important Settings" tab is initially devoid of content. Once new computational Units are added to this new subworkflow (following the procedure outlined in [this page](units-flowchart.md)), the user will begin to see the settings global to all units contained in the subworkflow, as well as unit-specific settings, appearing in this tab. -The settings that can be set within this tab concern primarily the important [computational parameters](../../methods/parameters.md) related to the particular [method](../../methods-directory/overview.md) under consideration. +The settings that can be set within this tab concern primarily the important [computational parameters]({{ reference_url }}/methods/parameters/) related to the particular [method]({{ reference_url }}/methods-directory/overview/) under consideration. ## Specific Implementation -Consult [Methods Directory](../../methods-directory/overview.md) for specifics about the important settings of each supported method. +Consult [Methods Directory]({{ reference_url }}/methods-directory/overview/) for specifics about the important settings of each supported method. diff --git a/lang/en/docs/workflow-designer/subworkflow-editor/overview-tab.md b/lang/en/docs/workflow-designer/subworkflow-editor/overview-tab.md index 6d0f82003..e36e64fd3 100644 --- a/lang/en/docs/workflow-designer/subworkflow-editor/overview-tab.md +++ b/lang/en/docs/workflow-designer/subworkflow-editor/overview-tab.md @@ -8,7 +8,7 @@ The general appearance of the typical content of the "Overview" tab is presented The first line in the "Overview" tab, labeled "Properties", contains a summary of the physical properties that will be computed during the course of the present calculation. These can be selected from a list of properties on the "Detailed View" tab, which is described [here](detailed-view.md). -For a complete list of physical properties available for calculation, the reader is referred to [this page](../../properties/overview.md). +For a complete list of physical properties available for calculation, the reader is referred to [this page]({{ reference_url }}/properties/overview/). ### Low-fidelity Runs @@ -16,11 +16,11 @@ Optionally, the check-box "Draft" on the left can be selected. In this case the ## The "Application" Section -The subsequent "Application" section in the "Overview" tab allows the user to choose the computational engine (otherwise known as [application](../../software/components.md)) to apply under the present Workflow. +The subsequent "Application" section in the "Overview" tab allows the user to choose the computational engine (otherwise known as [application]({{ reference_url }}/software/components/)) to apply under the present Workflow. ## The "Model" Section -The concept of "Model" is documented extensively in its own dedicated [documentation section](../../models/overview.md). +The concept of "Model" is documented extensively in its own dedicated [documentation section]({{ reference_url }}/models/overview/). ### Refiners @@ -34,4 +34,4 @@ Several modifiers can also be included as part of the subworkflow under consider ## The "Method" Section -Methods are also the object of a [dedicated section](../../methods/overview.md) of the documentation. +Methods are also the object of a [dedicated section]({{ reference_url }}/methods/overview/) of the documentation. diff --git a/lang/en/docs/workflow-designer/subworkflow-editor/units-flowchart.md b/lang/en/docs/workflow-designer/subworkflow-editor/units-flowchart.md index 8897107f7..f9f21de56 100644 --- a/lang/en/docs/workflow-designer/subworkflow-editor/units-flowchart.md +++ b/lang/en/docs/workflow-designer/subworkflow-editor/units-flowchart.md @@ -1,8 +1,8 @@ # Units Flowchart -At the bottom of the "Overview" tab page within the Subworkflow Editor interface, under the section titled "Units", the user can inspect the **units flowchart** offering a graphical representation of the subworkflow under consideration. Each unit included in this flowchart represents a distinct elementary unit computation, which can be mainly of purely logical (eg. "if" condition) or simulation (eg. ab-initio calculation) nature. The former category is further is narrated further [in its dedicated page](../../workflows/components/units.md). +At the bottom of the "Overview" tab page within the Subworkflow Editor interface, under the section titled "Units", the user can inspect the **units flowchart** offering a graphical representation of the subworkflow under consideration. Each unit included in this flowchart represents a distinct elementary unit computation, which can be mainly of purely logical (eg. "if" condition) or simulation (eg. ab-initio calculation) nature. The former category is further is narrated further [in its dedicated page]({{ reference_url }}/workflows/components/units/). -An example of elementary units flowchart at the bottom of an "Overview" tab, concerning a [band structure calculation](https://platform.mat3ra.com/bank/workflows/HPcabYa3gq4BPcb2u) (with density of states) implemented with the [Quantum ESPRESSO application](../../software-directory/modeling/quantum-espresso/overview.md), is depicted in the image below: +An example of elementary units flowchart at the bottom of an "Overview" tab, concerning a [band structure calculation](https://platform.mat3ra.com/bank/workflows/HPcabYa3gq4BPcb2u) (with density of states) implemented with the [Quantum ESPRESSO application]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/), is depicted in the image below: ![Units Flowchart](../../images/workflow-designer/units-flowchart.png "Units Flowchart") diff --git a/lang/en/docs/workflow-designer/unit-editor.md b/lang/en/docs/workflow-designer/unit-editor.md index c926f595a..4e3e713ed 100644 --- a/lang/en/docs/workflow-designer/unit-editor.md +++ b/lang/en/docs/workflow-designer/unit-editor.md @@ -14,17 +14,17 @@ This first line also contains a reminder of the unit's type (*execution* in the ## Application -Similar to the "Application" settings section in the [Overview tab](subworkflow-editor/overview-tab.md) of the parent [Subworkflow Editor](subworkflow-editor/overview-tab.md), this section reviews the computational engine (otherwise known as [application](../software-directory/overview.md)) to be employed in the current unit. +Similar to the "Application" settings section in the [Overview tab](subworkflow-editor/overview-tab.md) of the parent [Subworkflow Editor](subworkflow-editor/overview-tab.md), this section reviews the computational engine (otherwise known as [application]({{ reference_url }}/software-directory/overview/)) to be employed in the current unit. Normally, the application, its specific version and build cannot be changed by the user within the "Unit Editor" interface, as they are set at the parent subworkflow level. What can be changed inside this "Application" section of the Unit Editor is the specific **executable** of the simulation engine that is to be employed as part of the current unit calculation, under the corresponding "Executable" drop-down menu. We maintain a set of input templates (as further explained [here](unit-editor/input-templates.md)) for some of the most common use cases per each application and executable - **flavors**. Users may choose to pre-populate the input based one of the templates by selecting a flavor. -> NOTE: Examples "application", "executables" and "flavors. [Quantum Espresso](../software-directory/modeling/quantum-espresso/overview.md) application breaks its operations into a set of distinct executables with "pw.x" being the most commonly encountered one and "ph.x" being another example. Many different types of computations can be performed within the context of the pw.x executable itself, such as [variable-cell relaxation calculations](../workflows/addons/structural-relaxation.md) via the "pw_vc-relax" flavor, or electronic band structure calculations with "pw_bands". The input content for each of these represent the different flavors. +> NOTE: Examples "application", "executables" and "flavors. [Quantum Espresso]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) application breaks its operations into a set of distinct executables with "pw.x" being the most commonly encountered one and "ph.x" being another example. Many different types of computations can be performed within the context of the pw.x executable itself, such as [variable-cell relaxation calculations]({{ reference_url }}/workflows/addons/structural-relaxation/) via the "pw_vc-relax" flavor, or electronic band structure calculations with "pw_bands". The input content for each of these represent the different flavors. ## Properties and Monitors -The "Properties" and "Monitors" sections of the Unit Editor interface are presented in a way which is exactly analogous to the equivalent sections under the "Detailed View" tab of the parent Subworkflow Editor interface. The reader is therefore referred to the relevant parts of the "Detailed View" [documentation page](../workflow-designer/subworkflow-editor/detailed-view.md#the-"properties"-section), and to [this general reference page](../properties/overview.md). This part allows for the selections of physical properties to be retrieved as part of the final output of the unit's computational task, and secondly a list of quantities that can be monitored for during the course of the execution. +The "Properties" and "Monitors" sections of the Unit Editor interface are presented in a way which is exactly analogous to the equivalent sections under the "Detailed View" tab of the parent Subworkflow Editor interface. The reader is therefore referred to the relevant parts of the "Detailed View" [documentation page](../workflow-designer/subworkflow-editor/detailed-view.md#the-"properties"-section), and to [this general reference page]({{ reference_url }}/properties/overview/). This part allows for the selections of physical properties to be retrieved as part of the final output of the unit's computational task, and secondly a list of quantities that can be monitored for during the course of the execution. ## Next diff --git a/lang/en/docs/workflow-designer/unit-editor/input-templates.md b/lang/en/docs/workflow-designer/unit-editor/input-templates.md index 5e9f065b3..7f8d15fb5 100644 --- a/lang/en/docs/workflow-designer/unit-editor/input-templates.md +++ b/lang/en/docs/workflow-designer/unit-editor/input-templates.md @@ -1,18 +1,21 @@ +--- +render_macros: true +--- # Unit input templates -[Unit input templates](../../workflows/templating/overview.md) allow input text files to be rendered based on unique data per each material, and to be subsequently fed to the simulation engine being employed as part of the present unit calculation. The original input file templates, as well as their final preview appearances, can be inspected in the visual below. The typical appearance of an input template within the Unit Editor interface, for the specific example of a "pw_scf" self-consistent field total ground-state energy unit calculation using the pw.x executable of the [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md) simulation package, is depicted on the left-hand side in the image below. +[Unit input templates]({{ reference_url }}/workflows/templating/overview/) allow input text files to be rendered based on unique data per each material, and to be subsequently fed to the simulation engine being employed as part of the present unit calculation. The original input file templates, as well as their final preview appearances, can be inspected in the visual below. The typical appearance of an input template within the Unit Editor interface, for the specific example of a "pw_scf" self-consistent field total ground-state energy unit calculation using the pw.x executable of the [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) simulation package, is depicted on the left-hand side in the image below. !["Example Input Template"](../../images/workflow-designer/input-template.png "Example Input Template") -The reader is referred to the Quantum ESPRESSO-specific [documentation page](../../software-directory/modeling/quantum-espresso/overview.md), and to its official online documentation page pertaining specifically to the pw.x executable code [^1], for a detailed description of the meaning of the input flags displayed in the above example. +The reader is referred to the Quantum ESPRESSO-specific [documentation page]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/), and to its official online documentation page pertaining specifically to the pw.x executable code [^1], for a detailed description of the meaning of the input flags displayed in the above example. ## Template Data -By clicking on the `Template Data` button to the right of the unit input template the user can inspect the corresponding JSON representation of the data used to render the template and produce the final text. The templates themselves are built starting from this JSON data using the [Jinja template engine](../../workflows/templating/jinja.md). +By clicking on the `Template Data` button to the right of the unit input template the user can inspect the corresponding JSON representation of the data used to render the template and produce the final text. The templates themselves are built starting from this JSON data using the [Jinja template engine]({{ reference_url }}/workflows/templating/jinja/). The user can notice that some commands are allowed as part of the template syntax, such as the "for" loop contained in the final line of the template for defining the size of the grid of k-points employed as part of the current "pw_scf" computation, according to the specific format of Quantum ESPRESSO input files [^1]. -More about the logic behind templates and rendering is explained in [this part of the documentation](../../workflows/templating/overview.md). +More about the logic behind templates and rendering is explained in [this part of the documentation]({{ reference_url }}/workflows/templating/overview/). ## Example JSON Representation @@ -50,8 +53,11 @@ The example of a JSON data structure, containing the input data for the template "RESTART_MODE": "from_scratch", "NAT": 2, "NTYP": 1, - "ATOMIC_POSITIONS": "Si 0.000000000 0.000000000 0.000000000\nSi 0.250000000 0.250000000 0.250000000", - "CELL_PARAMETERS": "3.348920236 0.000000000 1.933500000\n1.116306745 3.157392278 1.933500000\n0.000000000 0.000000000 3.867000000", + "ATOMIC_POSITIONS": "Si 0.000000000 0.000000000 0.000000000 +Si 0.250000000 0.250000000 0.250000000", + "CELL_PARAMETERS": "3.348920236 0.000000000 1.933500000 +1.116306745 3.157392278 1.933500000 +0.000000000 0.000000000 3.867000000", "ATOMIC_SPECIES": "Si 28.0855 si_pbe_gbrv_1.0.upf" }, "isInputEdited": false, @@ -77,11 +83,11 @@ An example of an input template matching the above JSON source data, and referri ```jinja -&CONTROL +{% raw %}&CONTROL calculation = 'scf' title = '' verbosity = 'low' - restart_mode = '{{ input.RESTART_MODE }}' + restart_mode = '{{ input.RESTART_MODE }}'{% endraw %} wf_collect = .true. tstress = .true. tprnfor = .true. @@ -89,7 +95,7 @@ An example of an input template matching the above JSON source data, and referri wfcdir = {% raw %}'{{ JOB_WORK_DIR }}/outdir'{% endraw %} prefix = '__prefix__' pseudo_dir = {% raw %}'{{ JOB_WORK_DIR }}/pseudo'{% endraw %} -/ +{% raw %}/ &SYSTEM ibrav = {{ input.IBRAV }} nat = {{ input.NAT }} @@ -117,14 +123,14 @@ ATOMIC_POSITIONS crystal CELL_PARAMETERS angstrom {{ input.CELL_PARAMETERS }} K_POINTS automatic -{% for d in kgrid.dimensions %}{{d}} {% endfor %}{% for s in kgrid.shifts %}{{s}} {% endfor %} +{% for d in kgrid.dimensions %}{{d}} {% endfor %}{% for s in kgrid.shifts %}{{s}} {% endfor %}{% endraw %} ```
## Preview of the input file -By clicking on the "Preview" tab next to "Template" at the bottom of the Unit Editor interface, the user can visualize a preview of the corresponding input file, in its final form to be stored in the database and sent to the computational infrastructure for execution. Such process completes the [design time render](../../workflows/templating/examples.md#design-time-render) This text will be further processed during the [runtime render](../../workflows/templating/examples.md#run-time-render) into the final text to be passed directly to the application executable. +By clicking on the "Preview" tab next to "Template" at the bottom of the Unit Editor interface, the user can visualize a preview of the corresponding input file, in its final form to be stored in the database and sent to the computational infrastructure for execution. Such process completes the [design time render]({{ reference_url }}/workflows/templating/examples/#design-time-render) This text will be further processed during the [runtime render]({{ reference_url }}/workflows/templating/examples/#run-time-render) into the final text to be passed directly to the application executable. An example of input text, resulting from the above-mentioned JSON data structure and input template is displayed in the expandable section below: @@ -133,6 +139,7 @@ An example of input text, resulting from the above-mentioned JSON data structure "Expand to view": ... +{% raw %} ```Fortran &CONTROL calculation = 'scf' @@ -179,6 +186,7 @@ CELL_PARAMETERS angstrom K_POINTS automatic 10 10 10 0 0 0 ``` +{% endraw %} ## Selecting different materials diff --git a/lang/en/docs/workflows/actions/copy-bank.md b/lang/en/docs/workflows/actions/copy-bank.md index 657c6cec4..ac66b764a 100644 --- a/lang/en/docs/workflows/actions/copy-bank.md +++ b/lang/en/docs/workflows/actions/copy-bank.md @@ -2,6 +2,6 @@ The general procedure for importing entities from Banks is reviewed [in this page](../../entities-general/actions/copy-bank.md). -In the animation below, we demonstrate how to import a Bank Workflow, performing the electronic band structure calculation, into the account-owned [collection](../../accounts/collections.md). The workflow is retrieved upon entering and searching for the "band structure" keywords in the [search bar](../../entities-general/actions/search.md). +In the animation below, we demonstrate how to import a Bank Workflow, performing the electronic band structure calculation, into the account-owned [collection]({{ reference_url }}/accounts/collections/). The workflow is retrieved upon entering and searching for the "band structure" keywords in the [search bar](../../entities-general/actions/search.md). diff --git a/lang/en/docs/workflows/actions/set-default.md b/lang/en/docs/workflows/actions/set-default.md index cd404893f..82b619d20 100644 --- a/lang/en/docs/workflows/actions/set-default.md +++ b/lang/en/docs/workflows/actions/set-default.md @@ -1,3 +1,3 @@ # Change Default Workflow -As the user begins to grow the collection of workflows by creating new ones, or [importing them](../bank.md) directly from the Bank, this default choice might subsequently need to be changed. We provide an explanation of this procedure [here](../../entities-general/actions/set-default.md). +As the user begins to grow the collection of workflows by creating new ones, or [importing them]({{ reference_url }}/workflows/bank/) directly from the Bank, this default choice might subsequently need to be changed. We provide an explanation of this procedure [here](../../entities-general/actions/set-default.md). diff --git a/lang/en/docs/workflows/actions/update.md b/lang/en/docs/workflows/actions/update.md index 6727eeb4a..521293193 100644 --- a/lang/en/docs/workflows/actions/update.md +++ b/lang/en/docs/workflows/actions/update.md @@ -1,6 +1,6 @@ # Why Update Workflows? -As explained [here](../bank.md#pre-built-bank-workflows), some commonly encountered types of calculations are **pre-packaged** in the workflows "Bank". They can as such be imported directly by the user into the Account-owned collection. When this happens, the link between the Bank and Account-owned item is retained. Sometimes the *Pre-built Bank Workflows* are updated by our personnel. The user who had already imported a previous version of one of such workflows can then "Pull" the updates to his/her account-owned entry. +As explained [here]({{ reference_url }}/workflows/bank/#pre-built-bank-workflows), some commonly encountered types of calculations are **pre-packaged** in the workflows "Bank". They can as such be imported directly by the user into the Account-owned collection. When this happens, the link between the Bank and Account-owned item is retained. Sometimes the *Pre-built Bank Workflows* are updated by our personnel. The user who had already imported a previous version of one of such workflows can then "Pull" the updates to his/her account-owned entry. ## How to Spot Outdated Workflows? diff --git a/lang/en/docs/workflows/addons/convergence-algorithms.md b/lang/en/docs/workflows/addons/convergence-algorithms.md index 372e4000b..b709b416a 100644 --- a/lang/en/docs/workflows/addons/convergence-algorithms.md +++ b/lang/en/docs/workflows/addons/convergence-algorithms.md @@ -1,7 +1,7 @@ # Convergence Algorithms -It is often required to test the convergence of [input computational parameters](../../methods/parameters.md) for the [method](../../methods/overview.md) under consideration, in order to achieve a certain [numerical precision](../../methods/precision.md) in the final results. +It is often required to test the convergence of [input computational parameters]({{ reference_url }}/methods/parameters/) for the [method]({{ reference_url }}/methods/overview/) under consideration, in order to achieve a certain [numerical precision]({{ reference_url }}/methods/precision/) in the final results. -This feature is accessible as a stand-alone workflow, or as an [add-on](../../workflow-designer/subworkflow-editor/actions-menu.md#insert-add-ons) to an existing subworkflow in [Wokflow Designer](../../workflow-designer/overview.md). +This feature is accessible as a stand-alone workflow, or as an [add-on]({{ interface_url }}/workflow-designer/subworkflow-editor/actions-menu/#insert-add-ons) to an existing subworkflow in [Wokflow Designer]({{ interface_url }}/workflow-designer/overview/). -For example, we explain how to add a [k-points](../../models/auxiliary-concepts/reciprocal-space/sampling.md) convergence test to a total energy subworkflow [in this page](../../models/auxiliary-concepts/reciprocal-space/convergence.md). +For example, we explain how to add a [k-points]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) convergence test to a total energy subworkflow [in this page]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/convergence/). diff --git a/lang/en/docs/workflows/addons/overview.md b/lang/en/docs/workflows/addons/overview.md index 1fc5aa300..45eb117b2 100644 --- a/lang/en/docs/workflows/addons/overview.md +++ b/lang/en/docs/workflows/addons/overview.md @@ -1,6 +1,6 @@ # Add-on Subworkflows -We allow for the insertion of **Add-ons** for performing certain specialized calculations, such as convergence studies. These can be added from either the [Header Menu](../../workflow-designer/header-menu.md#inserting-add-ons) or the [Actions Menu](../../workflow-designer/subworkflow-editor/actions-menu.md#insert-add-ons) of the [Workflow Designer Interface](../../workflow-designer/overview.md). +We allow for the insertion of **Add-ons** for performing certain specialized calculations, such as convergence studies. These can be added from either the [Header Menu]({{ interface_url }}/workflow-designer/header-menu/#inserting-add-ons) or the [Actions Menu]({{ interface_url }}/workflow-designer/subworkflow-editor/actions-menu/#insert-add-ons) of the [Workflow Designer Interface]({{ interface_url }}/workflow-designer/overview/). ## [Convergence Studies](convergence-algorithms.md) diff --git a/lang/en/docs/workflows/addons/structural-relaxation.md b/lang/en/docs/workflows/addons/structural-relaxation.md index 501559478..c48495145 100644 --- a/lang/en/docs/workflows/addons/structural-relaxation.md +++ b/lang/en/docs/workflows/addons/structural-relaxation.md @@ -19,17 +19,17 @@ Secondly, a relaxation calculation ensures that the inter-atomic forces within t ## Why relaxations are recommended -Performing such an initial relaxation at the beginning of any type of workflow is in general a recommended practice, since having a fully-optimized crystal structure as the starting point will ensure more reliable results throughout the course of the execution of the rest of the workflow tasks. The user is advised that not even the pre-defined crystal structures which can be imported directly from centralized databases, such as the [Materials Bank](../../materials/bank.md) or the [Material Project](../../materials/actions/import.md) repositories reachable on the Exabyte platform, are always guaranteed to be fully pre-relaxed and pre-optimized. +Performing such an initial relaxation at the beginning of any type of workflow is in general a recommended practice, since having a fully-optimized crystal structure as the starting point will ensure more reliable results throughout the course of the execution of the rest of the workflow tasks. The user is advised that not even the pre-defined crystal structures which can be imported directly from centralized databases, such as the [Materials Bank](../../materials/bank.md) or the [Material Project]({{ interface_url }}/materials/actions/import/) repositories reachable on the Exabyte platform, are always guaranteed to be fully pre-relaxed and pre-optimized. ## Numerical Implementation -Structural relaxation computations are typically implemented through suitable numerical minimization and optimization algorithms, such as those introduced [in this page](../../methods/auxiliary-concepts/optimization-algorithms.md). +Structural relaxation computations are typically implemented through suitable numerical minimization and optimization algorithms, such as those introduced [in this page]({{ reference_url }}/methods/auxiliary-concepts/optimization-algorithms/). ## Execution of the Variable-cell Relaxation calculation The user can add such a variable-cell relaxation calculation as the first subworkflow step in a newly-created workflow by clicking on the `Relaxation` option under the drop-down menu button labelled with three vertical dots located at the right-hand side of the header menu of the Workflow Designer interface. -Once the Relaxation calculation has been selected and added to the beginning of the current workflow, a tick will appear next to the previously-clicked `Relaxation` option to remind the user about this inclusion. The "Variable-cell Relaxation" calculation will furthermore be inserted as a subworkflow module at the start of the flowchart portraying the overall workflow on the left-hand sidebar of the Designer interface, as elaborated in its respective [documentation page](../../workflow-designer/sidebar.md). +Once the Relaxation calculation has been selected and added to the beginning of the current workflow, a tick will appear next to the previously-clicked `Relaxation` option to remind the user about this inclusion. The "Variable-cell Relaxation" calculation will furthermore be inserted as a subworkflow module at the start of the flowchart portraying the overall workflow on the left-hand sidebar of the Designer interface, as elaborated in its respective [documentation page]({{ interface_url }}/workflow-designer/sidebar/). ## Animation @@ -46,7 +46,7 @@ Relaxations are usually classified by the number of degrees of freedom allowed t 2. Cell shape - angles between lattice vectors 3. Cell size - length of lattice vectors and/or parameters -Default settings include the relaxation of all three above aspects of the crystal structure. Experienced users can open the input files to edit the exact behavior, as explained [in this page](../../workflow-designer/subworkflow-editor/overview.md). +Default settings include the relaxation of all three above aspects of the crystal structure. Experienced users can open the input files to edit the exact behavior, as explained [in this page]({{ interface_url }}/workflow-designer/subworkflow-editor/overview/). ## Constrained relaxation @@ -55,18 +55,18 @@ For large structures where a full relaxation of cell size is not computationally In many cases, simulation software allows one to specify constraints in certain directions or specific atoms. In some cases one can significantly reduce the computation time for relaxations by only relaxing a certain number of atoms within the structure when appropriate. For example, when simulating a 256 atom Si silicon supercell with 1 Si atom replaced by a P atom, fixing positions of all atoms other than the 2nd nearest neighbors of P will improve the speed of the calculation significantly. !!! Note "Tutorial" - Please visit the [relaxation tutorial](../../tutorials/dft/addons/structural-relaxation.md) for a more expansive and detailed look at adding a relaxation calculation as part of a workflow. + Please visit the [relaxation tutorial]({{ guide_url }}/tutorials/dft/addons/structural-relaxation/) for a more expansive and detailed look at adding a relaxation calculation as part of a workflow. ## Initial/Final Structures Set -In some circumstances, where a structural relaxation calculation is required, a copy of the original and fully relaxed structures is stored in a special [set](../../entities-general/sets.md). This set can be retrieved within the account-owned materials [collection](../../accounts/collections.md), accessible via the [Explorer Interface](../../materials/ui/explorer.md) of our platform. It is typically labelled **"initial/final structures"**, and is created automatically at the end of the relevant Job execution. +In some circumstances, where a structural relaxation calculation is required, a copy of the original and fully relaxed structures is stored in a special [set](../../entities-general/sets.md). This set can be retrieved within the account-owned materials [collection](../../accounts/collections.md), accessible via the [Explorer Interface]({{ interface_url }}/materials/ui/explorer/) of our platform. It is typically labelled **"initial/final structures"**, and is created automatically at the end of the relevant Job execution. -For the case of **multi-material jobs**, when the job contains a set of multiple materials associated with it, this "initial/final structures" set is composed of two sub-sets, one containing a copy of the original (initial) non-relaxed structures, and the second comprising a copy of the fully relaxed final structures. Both sub-sets have the id of the corresponding [Job](../../jobs/overview.md) assigned to them as a [tag](../../entities-general/data.md#metadata). Each structure included in such sets can then be [opened](../../entities-general/actions/open-edit.md) and inspected under [Materials Viewer](../../materials/ui/viewer.md). +For the case of **multi-material jobs**, when the job contains a set of multiple materials associated with it, this "initial/final structures" set is composed of two sub-sets, one containing a copy of the original (initial) non-relaxed structures, and the second comprising a copy of the fully relaxed final structures. Both sub-sets have the id of the corresponding [Job](../../jobs/overview.md) assigned to them as a [tag]({{ data_url }}/entities-general/data/#metadata). Each structure included in such sets can then be [opened]({{ interface_url }}/entities-general/actions/open-edit/) and inspected under [Materials Viewer]({{ interface_url }}/materials/ui/viewer/). For jobs containing a single material, we create final and initial copies of materials at the top level of the "initial/final structures" set, and not in a sub-set. ### Example for NEB Calculations -In the special case of [Nudged Elastic Band](../../tutorials/dft/chemical/reaction-profile-qe.md) (NEB) computations for evaluating the [Reaction Energy Profile](../../properties-directory/non-scalar/reaction-energy-profile.md) of chemical reactions for example, these structure copies include the end-point images of the [Interpolated Set](../../materials-designer/header-menu/advanced/interpolated-set.md) of molecular configurations under consideration, as well as its [intermediate transition state](../../properties-directory/scalar/reaction-energy-barrier.md#transition-states). +In the special case of [Nudged Elastic Band]({{ guide_url }}/tutorials/dft/chemical/reaction-profile-qe/) (NEB) computations for evaluating the [Reaction Energy Profile]({{ reference_url }}/properties-directory/non-scalar/reaction-energy-profile/) of chemical reactions for example, these structure copies include the end-point images of the [Interpolated Set]({{ interface_url }}/materials-designer/header-menu/advanced/interpolated-set/) of molecular configurations under consideration, as well as its [intermediate transition state]({{ reference_url }}/properties-directory/scalar/reaction-energy-barrier/#transition-states). It is also worth noting that the "initial/final structures" sub-sets created in the context of NEB calculations are always of [ordered type](../../entities-general/sets.md), in order to preserve the correct order of the interpolated set images. diff --git a/lang/en/docs/workflows/bank.md b/lang/en/docs/workflows/bank.md index 8a616647e..a4bad3e2e 100644 --- a/lang/en/docs/workflows/bank.md +++ b/lang/en/docs/workflows/bank.md @@ -8,8 +8,8 @@ Some common types of calculations routinely encountered have already been assemb ## Mapping Function -Workflows [Mapping Function](../entities-general/bank.md#bank-mapping-function) consists in an assessment of the sequence of logical operations and [application](../software-directory/overview.md) input files employed in the workflow and subsequent calculation of the [hash string](../entities-general/bank.md#hash-strings). The hash is then compared against those of existing Bank entries in the [same manner](../entities-general/bank.md) as for other bank entries. +Workflows [Mapping Function](../entities-general/bank.md#bank-mapping-function) consists in an assessment of the sequence of logical operations and [application]({{ reference_url }}/software-directory/overview/) input files employed in the workflow and subsequent calculation of the [hash string](../entities-general/bank.md#hash-strings). The hash is then compared against those of existing Bank entries in the [same manner](../entities-general/bank.md) as for other bank entries. ## Copy from Bank -The procedure of copying (or importing) Bank Workflows into Account-owned Workflows collection is described [here](actions/copy-bank.md). +The procedure of copying (or importing) Bank Workflows into Account-owned Workflows collection is described [here]({{ interface_url }}/workflows/actions/copy-bank/). diff --git a/lang/en/docs/workflows/components/maps.md b/lang/en/docs/workflows/components/maps.md index 696f0ed81..4405025af 100644 --- a/lang/en/docs/workflows/components/maps.md +++ b/lang/en/docs/workflows/components/maps.md @@ -1,13 +1,13 @@ # Maps -Maps refer to a convenient approach for performing a distributed calculation. This is achieved by splitting the input data into several distinct independent calculation branches (mapping), and then by merging the output of such calculations again at the end (reduce operation). +Maps refer to a convenient approach for performing a distributed calculation. This is achieved by splitting the input data into several distinct independent calculation branches (mapping), and then by merging the output of such calculations again at the end (reduce operation). An example of application of this kind of distributed computing approach is for splitting a phonon dispersion calculation to many independent calculations for the individual vibration modes. ## Map units in Workflow flowcharts -In practice, when a new map is added to a workflow [flowchart](../../workflow-designer/sidebar.md), via the actions introduced [in this page](../../workflow-designer/subworkflow-editor/actions-menu.md#Adding Subworkflows), an entire new workflow will be created and contained within the original parent workflow. The typical appearance of this "workflow inside another workflow" map unit is shown in the example below. +In practice, when a new map is added to a workflow [flowchart]({{ interface_url }}/workflow-designer/sidebar/), via the actions introduced [in this page]({{ interface_url }}/workflow-designer/subworkflow-editor/actions-menu/#Add Subworkflows), an entire new workflow will be created and contained within the original parent workflow. The typical appearance of this "workflow inside another workflow" map unit is shown in the example below. ![Example Map Workflow](../../images/workflows/maps-workflow.png "Example Map Workflow") -The overall content of this workflow map is in general identical to that of a normal parent workflow, except for an extra tab labelled "Data" where an array of the corresponding map data can be inserted. +The overall content of this workflow map is in general identical to that of a normal parent workflow, except for an extra tab labelled "Data" where an array of the corresponding map data can be inserted. diff --git a/lang/en/docs/workflows/components/subworkflows.md b/lang/en/docs/workflows/components/subworkflows.md index 034e75cbd..cd3d9b110 100644 --- a/lang/en/docs/workflows/components/subworkflows.md +++ b/lang/en/docs/workflows/components/subworkflows.md @@ -1,18 +1,18 @@ # Subworkflow -We define a **Subworkflow** as a set of distinct **units** (elementary calculations) combined together in a flowchart (algorithm), in order to extract one or more [properties](../../properties/overview.md). A subworkflow must be specific to a particular simulation engine [application](../../software/components.md), [model](../../models/overview.md) and [method](../../methods/overview.md). +We define a **Subworkflow** as a set of distinct **units** (elementary calculations) combined together in a flowchart (algorithm), in order to extract one or more [properties](../../properties/overview.md). A subworkflow must be specific to a particular simulation engine [application]({{ reference_url }}/software/components/), [model]({{ reference_url }}/models/overview/) and [method]({{ reference_url }}/methods/overview/). ## Model -A **Model** is an entity that contains **scientifically valuable information** about the approximations used for a **simulation**. Models are the object of a [separate discussion](../../models/overview.md). +A **Model** is an entity that contains **scientifically valuable information** about the approximations used for a **simulation**. Models are the object of a [separate discussion]({{ reference_url }}/models/overview/). ## Method -A model may have multiple numerical **Methods**, or computational implementations, which are described in detail [here](../../methods/overview.md). A method is implemented inside a [simulation engine](#simulation-engine) (or application), and a single simulation engine can also use one or more methods. +A model may have multiple numerical **Methods**, or computational implementations, which are described in detail [here]({{ reference_url }}/methods/overview/). A method is implemented inside a [simulation engine](#simulation-engine) (or application), and a single simulation engine can also use one or more methods. ## Simulation Engine -A **Simulation Engine** is an implementation of a simulation algorithm in software. The engines available on our platform are reviewed [in this section](../../software/components.md) of the documentation. +A **Simulation Engine** is an implementation of a simulation algorithm in software. The engines available on our platform are reviewed [in this section]({{ reference_url }}/software/components/) of the documentation. ## Subworkflow Add-ons diff --git a/lang/en/docs/workflows/components/units.md b/lang/en/docs/workflows/components/units.md index 4c3ce7821..2f9c44b07 100644 --- a/lang/en/docs/workflows/components/units.md +++ b/lang/en/docs/workflows/components/units.md @@ -8,7 +8,7 @@ The following types of units are available. ### Execution -Used for computationally-heavy tasks, e.g. for a singular run of a physics-based simulation engine. For physics-based [modeling engines](../../software/components.md), the execution unit is the main one. It contains the information about the input parameters and runtime environment for the specific simulation engine. +Used for computationally-heavy tasks, e.g. for a singular run of a physics-based simulation engine. For physics-based [modeling engines]({{ reference_url }}/software/components/), the execution unit is the main one. It contains the information about the input parameters and runtime environment for the specific simulation engine. ### Processing diff --git a/lang/en/docs/workflows/data/overview.md b/lang/en/docs/workflows/data/overview.md index 88dc513b1..28a50d971 100644 --- a/lang/en/docs/workflows/data/overview.md +++ b/lang/en/docs/workflows/data/overview.md @@ -1,15 +1,15 @@ # Structured Representations of Workflow Components -We introduce in this section the JSON representations for [Workflows](../overview.md), and for each of their sub-components. We base such representations on the data convention, which is the object of a [separate discussion](../../data-structured/overview.md). +We introduce in this section the JSON representations for [Workflows]({{ reference_url }}/workflows/overview/), and for each of their sub-components. We base such representations on the data convention, which is the object of a [separate discussion]({{ data_url }}/data-structured/overview/). ## [Workflows](workflows.md) -The structured representation of [workflows](../overview.md) is described [here](workflows.md), by way of example. +The structured representation of [workflows]({{ reference_url }}/workflows/overview/) is described [here](workflows.md), by way of example. ## [Subworkflow](subworkflows.md) -We introduce the representation of [subworkflow](../components/subworkflows.md) components [in this separate page](subworkflows.md). +We introduce the representation of [subworkflow]({{ reference_url }}/workflows/components/subworkflows/) components [in this separate page](subworkflows.md). ## [Units](units.md) -The structured representation of compute [units](../components/units.md) is the object of a [separate discussion](units.md) +The structured representation of compute [units]({{ reference_url }}/workflows/components/units/) is the object of a [separate discussion](units.md) diff --git a/lang/en/docs/workflows/data/subworkflows.md b/lang/en/docs/workflows/data/subworkflows.md index b3fdb366c..6c2d2cefd 100644 --- a/lang/en/docs/workflows/data/subworkflows.md +++ b/lang/en/docs/workflows/data/subworkflows.md @@ -1,13 +1,13 @@ # Subworkflows: Structured Representation -The JSON [structured representation](../../data-structured/overview.md) of [subworkflows](../components/subworkflows.md), together with an example, is contained below. +The JSON [structured representation]({{ data_url }}/data-structured/overview/) of [subworkflows]({{ reference_url }}/workflows/components/subworkflows/), together with an example, is contained below. === "Schema" - ``` json + ```json --8<-- "data/esse/schema/workflow/subworkflow.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/workflow/subworkflow.json" ``` diff --git a/lang/en/docs/workflows/data/units.md b/lang/en/docs/workflows/data/units.md index 85cdb1115..ad7d0d790 100644 --- a/lang/en/docs/workflows/data/units.md +++ b/lang/en/docs/workflows/data/units.md @@ -1,42 +1,42 @@ # Units: Structured Representation -The JSON [structured representations](../../data-structured/overview.md) for the different [types of units](../components/units.md) supported on our platform are contained in the expandable sections presented throughout the present page, accompanied each time by a corresponding example. +The JSON [structured representations]({{ data_url }}/data-structured/overview/) for the different [types of units]({{ reference_url }}/workflows/components/units/) supported on our platform are contained in the expandable sections presented throughout the present page, accompanied each time by a corresponding example. -For a description of unit input templating, the reader is referred to [this section](../templating/overview.md) of the documentation. +For a description of unit input templating, the reader is referred to [this section]({{ reference_url }}/workflows/templating/overview/) of the documentation. ## General Case === "Schema" - ``` json + ```json --8<-- "data/esse/schema/workflow/unit.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/workflow/unit.json" ``` ## Execution === "Schema" - ``` json + ```json --8<-- "data/esse/schema/workflow/unit/execution.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/workflow/unit/execution.json" ``` ## Processing === "Schema" - ``` json + ```json --8<-- "data/esse/schema/workflow/unit/processing.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/workflow/unit/processing.json" ``` @@ -44,95 +44,95 @@ For a description of unit input templating, the reader is referred to [this sect ### DataFrame === "Schema" - ``` json + ```json --8<-- "data/esse/schema/workflow/unit/io.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/workflow/unit/io.json" ``` ### API === "Schema" - ``` json + ```json --8<-- "data/esse/schema/workflow/unit/io/api.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/workflow/unit/io/api.json" ``` ### Database === "Schema" - ``` json + ```json --8<-- "data/esse/schema/workflow/unit/io/db.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/workflow/unit/io/db.json" ``` ### Object Storage === "Schema" - ``` json + ```json --8<-- "data/esse/schema/workflow/unit/io/object_storage.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/workflow/unit/io/object_storage.json" ``` ## Assignment === "Schema" - ``` json + ```json --8<-- "data/esse/schema/workflow/unit/assignment.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/workflow/unit/assignment.json" ``` ## Conditional === "Schema" - ``` json + ```json --8<-- "data/esse/schema/workflow/unit/condition.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/workflow/unit/condition.json" ``` ## Map === "Schema" - ``` json + ```json --8<-- "data/esse/schema/workflow/unit/map.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/workflow/unit/map.json" ``` ## Reduce === "Schema" - ``` json + ```json --8<-- "data/esse/schema/workflow/unit/reduce.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/workflow/unit/reduce.json" ``` diff --git a/lang/en/docs/workflows/data/workflows.md b/lang/en/docs/workflows/data/workflows.md index e9c89063e..e91abe93c 100644 --- a/lang/en/docs/workflows/data/workflows.md +++ b/lang/en/docs/workflows/data/workflows.md @@ -1,8 +1,8 @@ # Workflows: Structured Representation -In order to organize and store the information about [workflows](../overview.md), we employ the **Exabyte Data Convention**, as explained [elsewhere](../../data-structured/overview.md) in this documentation. +In order to organize and store the information about [workflows]({{ reference_url }}/workflows/overview/), we employ the **ESSE Data Convention**, as explained [elsewhere]({{ data_url }}/data-structured/overview/) in this documentation. -In the expandable section below, the user can find the JSON representation of a [workflow](../overview.md) with a corresponding example. It contains a series of [subworkflows](../components/subworkflows.md), each of which contains a number of [units](../components/units.md) in turn. +In the expandable section below, the user can find the JSON representation of a [workflow]({{ reference_url }}/workflows/overview/) with a corresponding example. It contains a series of [subworkflows]({{ reference_url }}/workflows/components/subworkflows/), each of which contains a number of [units]({{ reference_url }}/workflows/components/units/) in turn.
@@ -10,12 +10,12 @@ In the expandable section below, the user can find the JSON representation of a === "Schema" - ``` json + ```json --8<-- "data/esse/schema/workflow.json" ``` === "Example" - ``` json + ```json --8<-- "data/esse/example/workflow.json" ``` @@ -29,8 +29,8 @@ We use top-level workflow as a "container", and separate the details of each ind ## Templating -We allow for using [templates](../templating/overview.md) inside the input to individual units. In this way, we can decouple material-specific information from the workflow-specific one. More explanation can be found inside the [units documentation page](../components/units.md). +We allow for using [templates]({{ reference_url }}/workflows/templating/overview/) inside the input to individual units. In this way, we can decouple material-specific information from the workflow-specific one. More explanation can be found inside the [units documentation page]({{ reference_url }}/workflows/components/units/). ## Properties -The "Properties" section serves as an aggregator of all the [properties](../../properties/overview.md) that are extracted at the workflow or subworkflow levels. The "results" key serves the same purpose, but for the case of units. +The "Properties" section serves as an aggregator of all the [properties]({{ reference_url }}/properties/overview/) that are extracted at the workflow or subworkflow levels. The "results" key serves the same purpose, but for the case of units. diff --git a/lang/en/docs/workflows/default.md b/lang/en/docs/workflows/default.md index a1381ac15..9775cb64b 100644 --- a/lang/en/docs/workflows/default.md +++ b/lang/en/docs/workflows/default.md @@ -1,3 +1,3 @@ # Default Workflow -When a new Exabyte account is created, its default workflow is set to the [total energy](../properties/overview.md) calculation with [Quantum ESPRESSO](../software-directory/modeling/quantum-espresso/overview.md) and can later be adjusted by the account member(s) according to [these instructions](actions/set-default.md). +When a new Exabyte account is created, its default workflow is set to the [total energy](../properties/overview.md) calculation with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) and can later be adjusted by the account member(s) according to [these instructions]({{ interface_url }}/workflows/actions/set-default/). diff --git a/lang/en/docs/workflows/overview.md b/lang/en/docs/workflows/overview.md index 0c62900e0..a7fad7850 100644 --- a/lang/en/docs/workflows/overview.md +++ b/lang/en/docs/workflows/overview.md @@ -1,31 +1,51 @@ # Workflows -This section contains information about how we organize, store and apply **workflows** for modeling and simulations. +A **workflow** defines the complete sequence of computational steps needed to calculate one or more [properties](../properties/overview.md) of a [material](../materials/overview.md). Workflows encode the simulation logic — which [software](../software-directory/overview.md) to run, with what parameters, and in what order — in a reusable, shareable format. + + +## Key Concepts + +A workflow is composed of hierarchical sub-components: + +1. **[Subworkflows](components/subworkflows.md)** — self-contained computational stages (e.g. SCF calculation, band structure extraction). +2. **[Units](components/units.md)** — individual execution steps within a subworkflow (e.g. a single `pw.x` run, a Python script). + +Each unit contains an [input template]({{ interface_url }}/workflow-designer/unit-editor/input-templates/) that is rendered at runtime with the specific material and compute parameters for the job. + + +## Workflow Sources + +Workflows can be obtained in three ways: + +- **[Bank](bank.md)** — pre-built, curated workflows maintained by the platform team, covering common calculations (band structure, DOS, relaxation, formation energy, ML training, etc.). +- **Account collection** — user-created or bank-imported workflows stored in the account-owned [collection](../accounts/collections.md). +- **Custom creation** — workflows assembled from scratch using the [Workflow Designer]({{ interface_url }}/workflow-designer/overview/). + ## [Components](components/overview.md) -We introduce the computational sub-components of workflows, with particular attention to **subworkflows** and **units**, [in this section](components/overview.md). +The computational sub-components of workflows — **subworkflows** and **units** — are described in detail [in this section](components/overview.md). -## [Data](data/overview.md) +## [Data]({{ data_url }}/workflows/data/overview/) -The [Data](data/overview.md) section contains information about the structured data convention used to store workflows and their sub-components, with example JSON representations for each. +The [Data]({{ data_url }}/workflows/data/overview/) section describes the structured data convention used to store workflows and their sub-components, with example JSON representations. ## [Templating](templating/overview.md) -**Templating** is an important concept which we apply to automate and generalize the mass-generation of simulation input files. It is described in detail in a [dedicated section](templating/overview.md) of the documentation. +**[Templating](templating/overview.md)** automates the generation of simulation input files by combining workflow templates with material-specific parameters (lattice constants, atomic positions, k-points, etc.) at runtime. ## [Bank](bank.md) -[Workflows Bank](bank.md) collection and its related operations is explained in the corresponding section. +The [Workflows Bank](bank.md) is a curated collection of ready-to-use workflows. Bank workflows can be [copied]({{ interface_url }}/workflows/actions/copy-bank/) into an account and optionally modified before use. ## [Default](default.md) -The default workflow present at the moment of creation of a new account on our platform is introduced [here](default.md). +The [default workflow](default.md) is automatically assigned to new jobs. It is set at account creation and can be changed at any time. ## User Interface -Specific features pertaining to the Explorer Interface of the Workflows collection are explained [here](ui/explorer.md). Descriptions on [Viewer](ui/viewer.md) and [Designer](../workflow-designer/overview.md) in the context of workflows are also offered. +The [Explorer]({{ interface_url }}/workflows/ui/explorer/) provides an overview of all workflows in the account. The [Viewer]({{ interface_url }}/workflows/ui/viewer/) displays workflow details, and the [Designer]({{ interface_url }}/workflow-designer/overview/) enables creation and editing. -## [Actions](actions/overview.md) +## [Actions]({{ interface_url }}/workflows/actions/overview/) -The [Actions](actions/overview.md) section explains and provides visual examples of actions that users can perform on workflows. +Available [actions]({{ interface_url }}/workflows/actions/overview/) include copying from the bank, creating, editing, deleting, and setting a default workflow. diff --git a/lang/en/docs/workflows/templating/concept.md b/lang/en/docs/workflows/templating/concept.md index 318d36a2c..6c6db8a47 100644 --- a/lang/en/docs/workflows/templating/concept.md +++ b/lang/en/docs/workflows/templating/concept.md @@ -12,7 +12,7 @@ The basic process for a web templating system is illustrated in the picture belo ## Use within the platform -We make use of [Jinja](jinja.md) templating syntax. During the [**design time**](concept.md#template-rendering) render we use **Swig** [^2], a JavaScript template engine supporting Jinja syntax. During the [**runtime**](concept.md#template-rendering) templates are rendered by python implementation of Jinja. +We make use of [Jinja](jinja.md) templating syntax. During the [**design time**](concept.md#template-rendering) render we use **Swig** [^2], a JavaScript template engine supporting Jinja syntax. During the [**runtime**](concept.md#template-rendering) templates are rendered by python implementation of Jinja. ### Native Language Constructs @@ -20,11 +20,11 @@ The templating syntax for the above two scenarios is almost equivalent. There ar ### Usage Scenarios -In this respect, templates are applied to many different [materials](../../materials/overview.md) during the creation of [Jobs](../../jobs/overview.md), in conjunction with different input parameters (or template variables/context), specific for each material. +In this respect, templates are applied to many different [materials](../../materials/overview.md) during the creation of [Jobs](../../jobs/overview.md), in conjunction with different input parameters (or template variables/context), specific for each material. We allow for using templates specifically inside the input of [units](../components/units.md) comprised in a [subworkflow](../components/subworkflows.md). In this way, we can decouple material-specific information from workflow-specific. The latter lets us apply a workflow for multiple materials at the same time, without having to adjust it extensively. -The templates (input files) are rendered in two places, on [web interface](../../ui/overview.md) when workflows (or jobs) are designed and on [computing clusters](../../infrastructure/clusters/overview.md) when the job is executed, henceforth referred to as **Design-time Rendering** and **Runtime Rendering** respectively. The is necessary as some templates require data which is only available at runtime (e.g. `outdir` in Quantum Espresso PWScf input file) +The templates (input files) are rendered in two places, on [web interface]({{ interface_url }}/ui/overview/) when workflows (or jobs) are designed and on [computing clusters]({{ resources_url }}/infrastructure/clusters/overview/) when the job is executed, henceforth referred to as **Design-time Rendering** and **Runtime Rendering** respectively. The is necessary as some templates require data which is only available at runtime (e.g. `outdir` in Quantum Espresso PWScf input file) ## Links diff --git a/lang/en/docs/workflows/templating/exabyte-convention.md b/lang/en/docs/workflows/templating/exabyte-convention.md index 9534df2b2..d9228b953 100644 --- a/lang/en/docs/workflows/templating/exabyte-convention.md +++ b/lang/en/docs/workflows/templating/exabyte-convention.md @@ -1,3 +1,7 @@ +--- +render_macros: true +--- + # Exabyte Templating Convention Following the [general introduction](concept.md) to the templating concepts and [engines](jinja.md), we now review the specific aspects concerning its implementation in the context of our platform. @@ -12,11 +16,11 @@ The context available to templates on web interface, containing materials, workf ### Runtime-time Context -The context passed to the templates at runtime. This context provides system-level parameters such as `JOB_WORK_DIR` variable which defines the main [Working Directory](../../jobs-cli/batch-scripts/directories.md) for the [Job](../../jobs/overview.md) under consideration. This is a system-level [Environment Variable](../../jobs-cli/batch-scripts/directives.md#environment-variables) that will be resolved only during the the runtime. +The context passed to the templates at runtime. This context provides system-level parameters such as `JOB_WORK_DIR` variable which defines the main [Working Directory]({{ cli_url }}/jobs-cli/batch-scripts/directories/) for the [Job](../../jobs/overview.md) under consideration. This is a system-level [Environment Variable]({{ cli_url }}/jobs-cli/batch-scripts/directives/#environment-variables) that will be resolved only during the the runtime. ### Raw Syntax -The "Raw" filter syntax is used to prevent the Web Interface from rendering variables during the **Design-time Rendering**, given that such variables are only available during the ensuing **Runtime Rendering**. Hence, for example, the above-mentioned `JOB_WORK_DIR` variable would need to be entered as follows in a [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md) input file template, containing the line which defines the pseudopotential directory inside the [Working Directory](../../jobs-cli/batch-scripts/directories.md). +The "Raw" filter syntax is used to prevent the Web Interface from rendering variables during the **Design-time Rendering**, given that such variables are only available during the ensuing **Runtime Rendering**. Hence, for example, the above-mentioned `JOB_WORK_DIR` variable would need to be entered as follows in a [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) input file template, containing the line which defines the pseudopotential directory inside the [Working Directory]({{ cli_url }}/jobs-cli/batch-scripts/directories/). ```jinja pseudo_dir = {% raw %}'{{ JOB_WORK_DIR }}/pseudo'{% endraw %} diff --git a/lang/en/docs/workflows/templating/examples.md b/lang/en/docs/workflows/templating/examples.md index d7a0fcf3a..0dd30468d 100644 --- a/lang/en/docs/workflows/templating/examples.md +++ b/lang/en/docs/workflows/templating/examples.md @@ -1,21 +1,25 @@ +--- +render_macros: true +--- + # Template Examples -The present page contains example(s) of [unit](../components/units.md) input [templates](overview.md), implemented using the [templating engine](jinja.md), in order to generate the input files for the [simulation engines](../../software/overview.md) supported on our platform. +The present page contains example(s) of [unit](../components/units.md) input [templates](overview.md), implemented using the [templating engine](jinja.md), in order to generate the input files for the [simulation engines]({{ reference_url }}/software/overview/) supported on our platform. ## Quantum ESPRESSO Example -For example, the input file template shown in the expandable section below, for a sample [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md) calculation. +For example, the input file template shown in the expandable section below, for a sample [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) calculation. ### Template The text below contains references to data that will be different for different materials, such as the number of atoms (`nat` flag). ```jinja -&CONTROL +{% raw %}&CONTROL calculation = 'scf' title = '' verbosity = 'low' - restart_mode = '{{ input.RESTART_MODE }}' + restart_mode = '{{ input.RESTART_MODE }}'{% endraw %} wf_collect = .true. tstress = .true. tprnfor = .true. @@ -23,7 +27,7 @@ The text below contains references to data that will be different for different wfcdir = {% raw %}'{{ JOB_WORK_DIR }}/outdir'{% endraw %} prefix = '__prefix__' pseudo_dir = {% raw %}'{{ JOB_WORK_DIR }}/pseudo'{% endraw %} -/ +{% raw %}/ &SYSTEM ibrav = {{ input.IBRAV }} nat = {{ input.NAT }} @@ -51,7 +55,7 @@ ATOMIC_POSITIONS crystal CELL_PARAMETERS angstrom {{ input.CELL_PARAMETERS }} K_POINTS automatic -{% for d in kgrid.dimensions %}{{d}} {% endfor %}{% for s in kgrid.shifts %}{{s}} {% endfor %} +{% for d in kgrid.dimensions %}{{d}} {% endfor %}{% for s in kgrid.shifts %}{{s}} {% endfor %}{% endraw %} ``` ### Context @@ -104,6 +108,7 @@ K_POINTS automatic For Silicon FCC as a default material, the resulting text of the unit input, will be as shown as below: +{% raw %} ```fortran &CONTROL calculation = 'scf' @@ -150,6 +155,7 @@ CELL_PARAMETERS angstrom K_POINTS automatic 10 10 10 0 0 0 ``` +{% endraw %} #### Runtime Render diff --git a/lang/en/docs/workflows/templating/jinja.md b/lang/en/docs/workflows/templating/jinja.md index d72898891..168486107 100644 --- a/lang/en/docs/workflows/templating/jinja.md +++ b/lang/en/docs/workflows/templating/jinja.md @@ -1,3 +1,7 @@ +--- +render_macros: false +--- + # Template Engines We introduce in this page the basics of Jinja2 syntax used by templating on our platform. The reader is referred to the official documentations for further information [^1][^2]. diff --git a/lang/en/docs/workflows/templating/overview.md b/lang/en/docs/workflows/templating/overview.md index 59c3351d0..c923e3f5c 100644 --- a/lang/en/docs/workflows/templating/overview.md +++ b/lang/en/docs/workflows/templating/overview.md @@ -1,6 +1,6 @@ # Templating for Input Scripts -We implement **templating** for generalizing and automating the generation of **input files**, which are necessary for executing relevant simulations through the required [simulation engine](../../software/components.md). This ensures, for example, that the same template can conveniently be applied to many different [materials](../../materials/overview.md) under the same [simulation job](../../jobs/overview.md). +We implement **templating** for generalizing and automating the generation of **input files**, which are necessary for executing relevant simulations through the required [simulation engine]({{ reference_url }}/software/components/). This ensures, for example, that the same template can conveniently be applied to many different [materials](../../materials/overview.md) under the same [simulation job](../../jobs/overview.md). ## [Concepts](concept.md) @@ -20,8 +20,8 @@ We provide an example of input file templating for a materials science computati ## [User Interface](ui.md) -The [User Interface components](ui.md) which are pertinent to setting templating options, for the generation of input files during the [Design stage of a new Workflow](../../workflow-designer/overview.md), are reviewed [in this page](../../workflow-designer/unit-editor/input-templates.md). +The [User Interface components](ui.md) which are pertinent to setting templating options, for the generation of input files during the [Design stage of a new Workflow]({{ interface_url }}/workflow-designer/overview/), are reviewed [in this page]({{ interface_url }}/workflow-designer/unit-editor/input-templates/). -## [Tutorials](../../tutorials/templating/overview.md) +## [Tutorials]({{ guide_url }}/tutorials/templating/overview/) -More information about how templating can be adapted to different circumstances, are discussed in the corresponding Tutorial section of our documentation [here](../../tutorials/templating/overview.md). +More information about how templating can be adapted to different circumstances, are discussed in the corresponding Tutorial section of our documentation [here]({{ guide_url }}/tutorials/templating/overview/). diff --git a/lang/en/docs/workflows/templating/swig.md b/lang/en/docs/workflows/templating/swig.md index 30b0068ec..1393e9f0a 100644 --- a/lang/en/docs/workflows/templating/swig.md +++ b/lang/en/docs/workflows/templating/swig.md @@ -1,11 +1,16 @@ +--- +render_macros: true +--- + # Swig -As mentioned in [the concept explanation](concept.md) we make use of **Swig** to render the templates on the [Web Interface](../../ui/overview.md). We introduce in this page the content specific to Swig. The reader is also referred to Swig official documentation for further reading [^1]. +As mentioned in [the concept explanation](concept.md) we make use of **Swig** to render the templates on the [Web Interface]({{ interface_url }}/ui/overview/). We introduce in this page the content specific to Swig. The reader is also referred to Swig official documentation for further reading [^1]. ## Javascript Native Prototypes All Javascript-related prototypes such as *Array* and *Object* [^2] are supported by Swig, as long as the function does not require a callback (function) as one of its arguments. For example `Array.prototype.find()` is not supported by Swig as it needs a callback, however it can be implemented by pure templating features as below. +{% raw %} ```jinja {% set elements = [ {"id": 0, "value": "Si"}, @@ -21,12 +26,13 @@ All Javascript-related prototypes such as *Array* and *Object* [^2] are supporte {% endfor %} element = {{ element["value"] }} ``` +{% endraw %} ## Specific Statements ### Spaceless -`{% spaceless %}` statement ensures that the text is rendered with no extra white spaces or empty lines added to it, and has to be terminated by `{% endspaceless %}`. +`{% raw %}{% spaceless %}{% endraw %}` statement ensures that the text is rendered with no extra white spaces or empty lines added to it, and has to be terminated by `{% raw %}{% endspaceless %}{% endraw %}`. ## Links diff --git a/lang/en/docs/workflows/templating/ui.md b/lang/en/docs/workflows/templating/ui.md index 23462b20f..f69053be8 100644 --- a/lang/en/docs/workflows/templating/ui.md +++ b/lang/en/docs/workflows/templating/ui.md @@ -1,6 +1,6 @@ # Templating: User Interface -The user interface component implementing the [Templating and Rendering](concept.md) concept for simulation input files can be found and employed by the user under the relevant section of the [Workflow Designer Interface](../../workflow-designer/unit-editor/input-templates.md) of our platform. +The user interface component implementing the [Templating and Rendering](concept.md) concept for simulation input files can be found and employed by the user under the relevant section of the [Workflow Designer Interface]({{ interface_url }}/workflow-designer/unit-editor/input-templates/) of our platform. ## Editing Unit Input @@ -8,8 +8,8 @@ There are two ways to access the Workflow Designer Interface and edit the templa ### From Workflow Explorer -The user can edit and save the template directly inside the [workflow](../../workflows/overview.md) itself, by [opening](../../entities-general/actions/open-edit.md) its entry as listed under the [Workflows Explorer Interface](../../workflows/ui/explorer.md) for browsing the corresponding account-owned [collection](../../accounts/collections.md). In this case, **all** [jobs](../../jobs/overview.md) that will subsequently be created with this workflow will inherit the changes. +The user can edit and save the template directly inside the [workflow](../../workflows/overview.md) itself, by [opening]({{ interface_url }}/entities-general/actions/open-edit/) its entry as listed under the [Workflows Explorer Interface]({{ interface_url }}/workflows/ui/explorer/) for browsing the corresponding account-owned [collection](../../accounts/collections.md). In this case, **all** [jobs](../../jobs/overview.md) that will subsequently be created with this workflow will inherit the changes. ### From Job Designer -Alternatively, the user can edit the template during [job creation](../../jobs-designer/overview.md), under the corresponding [Workflow Tab](../../jobs-designer/workflow-tab.md). In this other case, only the job being currently designed will have its input changed, but not the original entry of the workflow itself. +Alternatively, the user can edit the template during [job creation]({{ interface_url }}/jobs-designer/overview/), under the corresponding [Workflow Tab]({{ interface_url }}/jobs-designer/workflow-tab/). In this other case, only the job being currently designed will have its input changed, but not the original entry of the workflow itself. diff --git a/lang/en/docs/workflows/ui/explorer.md b/lang/en/docs/workflows/ui/explorer.md index a3e7a4e77..5c7af59e6 100644 --- a/lang/en/docs/workflows/ui/explorer.md +++ b/lang/en/docs/workflows/ui/explorer.md @@ -12,4 +12,4 @@ In the above image, we highlight the area that indicates whether a workflow is [ ## Filter Workflows by Applications -Workflows can be [filtered (or searched)](../../entities-general/actions/search.md) conventionally just like other types of entities. The possibility to search them by the [application](../../software-directory/overview.md) used within them, for performing the relevant computational tasks, also exists in this case. +Workflows can be [filtered (or searched)](../../entities-general/actions/search.md) conventionally just like other types of entities. The possibility to search them by the [application]({{ reference_url }}/software-directory/overview/) used within them, for performing the relevant computational tasks, also exists in this case. diff --git a/lang/en/docs/workflows/ui/viewer.md b/lang/en/docs/workflows/ui/viewer.md index e7bd7d236..6c13e3944 100644 --- a/lang/en/docs/workflows/ui/viewer.md +++ b/lang/en/docs/workflows/ui/viewer.md @@ -4,4 +4,4 @@ In order to inspect a workflow, the user can [open it](../../entities-general/ac ## Viewer = Designer -In the case of workflows, the user interface and editing functionality of the Viewer is **exactly** the same as that of the [Designer](../../workflow-designer/overview.md). The user is therefore referred to the latter documentation page for more details. +In the case of workflows, the user interface and editing functionality of the Viewer is **exactly** the same as that of the [Designer]({{ interface_url }}/workflow-designer/overview/). The user is therefore referred to the latter documentation page for more details. diff --git a/mkdocs-base.yml b/mkdocs-base.yml new file mode 100644 index 000000000..551f75958 --- /dev/null +++ b/mkdocs-base.yml @@ -0,0 +1,118 @@ +repo_name: 'mat3ra/documentation' +repo_url: 'https://github.com/mat3ra/documentation' +edit_uri: 'edit/main/lang/en/docs/' + +extra_css: + - https://cdnjs.cloudflare.com/ajax/libs/material-design-iconic-font/2.2.0/css/material-design-iconic-font.min.css + - extra/css/general.css + - extra/css/tables.css + - extra/css/images.css + - extra/css/super-fences.css + - extra/css/properties.css + - extra/css/docs-agent.css + - https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css + +extra_javascript: + - extra/js/giffer.js + - extra/js/ga.js + - extra/js/url_parameters.js + - extra/js/katex.js + - extra/js/clickable-rows.js + - extra/js/search-hint.js + # Self-mounting; hides itself when the agent service is unreachable, so a + # documentation page never shows a launcher that leads nowhere. + - extra/js/docs-agent.js + - https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js + - https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js + - 'https://www.googletagmanager.com/gtag/js?id=UA-69270713-5' + +copyright: Exabyte Inc. All rights reserved. | Back to platform + +extra: + version: "2026.6.25" + preload_javascript: + - /extra/js/preload_hotjar.js + - /extra/js/preload.js + social: + - icon: fontawesome/brands/github + link: https://github.com/mat3ra + - icon: fontawesome/brands/youtube + link: https://www.youtube.com/c/Mat3ra/videos + - icon: fontawesome/brands/linkedin + link: https://www.linkedin.com/company/mat3ra/ + - icon: fontawesome/brands/x-twitter + link: https://x.com/mat3ra_com + analytics: + provider: google + property: UA-69270713-5 + jupyterlite: + origin_url: https://jupyterlite.mat3ra.com/retro/notebooks + origin_url_lab: https://jupyterlite.mat3ra.com/lab/tree + notebooks_path_root: made + +theme: + name: material + custom_dir: theme + palette: + primary: deep purple + accent: deep purple + scheme: mat3ra + logo: "images/logo/logo-white.png" + favicon: "images/logo/favicon.svg" + icon: + edit: material/pencil + repo: fontawesome/brands/github + font: + text: Roboto + code: Roboto Mono + features: + - announce.dismiss + - content.action.edit + - content.code.annotate + - content.code.copy + - content.tooltips + - navigation.footer + - navigation.top + - search.highlight + - search.suggest + +markdown_extensions: + - admonition + - attr_list + - def_list + - footnotes: + PLACE_MARKER: "///FOOTNOTES GO HERE///" + - markdown.extensions.def_list + - md_in_html + - toc: + permalink: true + - pymdownx.arithmatex: + generic: true + - pymdownx.betterem + - pymdownx.details + - pymdownx.highlight: + pygments_lang_class: true + linenums: true + - pymdownx.snippets + - pymdownx.striphtml + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + +plugins: + - git-revision-date-localized: + type: date + enable_creation_date: false + - search + - tags + - macros: + include_dir: "lang/en/docs/includes/" + render_by_default: true + - bibtex: + bib_file: "lang/en/docs/includes/references.bib" + citation_template: "{{author}} ({{year}})" + bibliography_template: "{{author}} ({{year}}). {{title}}. {{journal}}. {{volume}}. {{pages}}." diff --git a/mkdocs-cli.yml b/mkdocs-cli.yml new file mode 100644 index 000000000..c58e1d920 --- /dev/null +++ b/mkdocs-cli.yml @@ -0,0 +1,161 @@ +# Command-Line Interface — CLI environment, batch jobs, and remote access. +# Deploy to: docs.mat3ra.com/cli/ + +INHERIT: mkdocs-base.yml + +docs_dir: !!python/object/apply:os.getenv ["DOCS_DIR", "lang/en/docs"] + +# Exclude pages that belong to other sites. +exclude_docs: | + accounts/ + benchmarks/ + collaboration/ + data/ + data-in-objectstorage/ + data-on-disk/ + data-structured/ + entities-general/ + getting-started/ + infrastructure/ + jobs/ + jobs-designer/ + materials/ + materials-designer/ + methods/ + methods-directory/ + models/ + models-directory/ + other/ + pricing/ + properties/ + properties-directory/ + rest-api/ + security/ + site-policy/ + software/ + software-directory/ + tutorials/ + jupyterlite/ + ui/ + workflow-designer/ + workflows/ + migrating-to-new-platform.md + + # Other sites' homepages + index.md + index-guide.md + index-interface.md + index-concepts.md + index-dev.md + index-resources.md + index-developers.md + index-standards.md + + # Data Standards site pages + models/data.md + methods/data.md + software/data.md + models-directory/dft/data.md + models-directory/machine-learning/data.md + methods-directory/pseudopotential/data.md + methods-directory/linear-regression/data.md + materials/data.md + jobs/data.md + +validation: + nav: + omitted_files: info + not_found: warn + links: + absolute_links: info + +site_name: "Command-Line Interface" +site_url: https://docs.mat3ra.com/command-line +site_description: "CLI environment, batch jobs, and remote connection for the Mat3ra platform." +dev_addr: "localhost:8008" + +theme: + features: + - announce.dismiss + - content.action.edit + - content.code.annotate + - content.code.copy + - content.tooltips + - navigation.footer + - navigation.top + - search.highlight + - search.suggest + - navigation.expand + +extra: + # Cross-site URL variables (resolved by macros plugin at build time) + guide_url: https://docs.mat3ra.com/guide + interface_url: https://docs.mat3ra.com/interface + reference_url: https://docs.mat3ra.com/reference + resources_url: https://docs.mat3ra.com/resources + developers_url: https://docs.mat3ra.com/developers + cli_url: https://docs.mat3ra.com/command-line + data_url: https://docs.mat3ra.com/standards + + + + +nav: + - "← All Docs": / + - Home: index-cli.md + +# COMMAND LINE INTERFACE + - CLI Environment: + - Overview: cli/overview.md + - Environment: cli/environment.md + - Environment Modules: cli/modules.md + - Accounting: cli/accounting.md + - Actions: + - Overview: cli/actions/overview.md + - Load / Unload Modules: cli/actions/modules-actions.md + - Customize Environment: cli/actions/customize.md + - Add new software: cli/actions/add-software.md + - Create Python Environment: cli/actions/create-python-env.md + - Create Anaconda Environment: cli/actions/create-anaconda-env.md + - List Clusters and Nodes: cli/actions/list-clusters.md + - Check Balance and Quota: cli/actions/balance-quota.md + +# JOBS VIA COMMAND LINE + - Jobs via Command Line: + - Overview: jobs-cli/overview.md + - Accounting: jobs-cli/accounting.md + - Batch Scripts: + - Overview: jobs-cli/batch-scripts/overview.md + - General Structure: jobs-cli/batch-scripts/general-structure.md + - Directives: jobs-cli/batch-scripts/directives.md + - Working Directory: jobs-cli/batch-scripts/directories.md + - Apptainer & Environment Modules: jobs-cli/batch-scripts/apptainer.md + - Sample Scripts: jobs-cli/batch-scripts/sample-scripts.md + - Actions: + - Overview: jobs-cli/actions/overview.md + - Create: jobs-cli/actions/create.md + - Submit: jobs-cli/actions/submit.md + - Check status: jobs-cli/actions/check-status.md + - Terminate: jobs-cli/actions/terminate.md + - View Jobs List: jobs-cli/actions/view-job-list.md + +# REMOTE CONNECTION + - Remote Connection: + - Overview: remote-connection/overview.md + - SSH Terminal (SSH): remote-connection/ssh.md + - Web Terminal (WT): remote-connection/web-terminal.md + - Remote Desktop (RD): remote-connection/remote-desktop.md + - Actions > (WT) & (RD): + - Overview: remote-connection/actions/overview.md + - Open Web Terminal: remote-connection/actions/open-terminal.md + - Open Remote Desktop: remote-connection/actions/open-desktop.md + - Open Sidebar: remote-connection/actions/sidebar.md + - Upload: remote-connection/actions/upload.md + - Download: remote-connection/actions/download.md + - Transfer Files via SCP: remote-connection/actions/transfer-files-scp.md + - Copy / Paste Text: remote-connection/actions/copy-paste.md + - Access data in Web Platfrom: remote-connection/actions/access-data.md + - Actions > Remote Desktop: + - Overview: remote-connection/actions-rd/overview.md + - Browse Directories: remote-connection/actions-rd/browse.md + - Open Applications: remote-connection/actions-rd/open-app.md diff --git a/mkdocs-concepts.yml b/mkdocs-concepts.yml new file mode 100644 index 000000000..880d993a6 --- /dev/null +++ b/mkdocs-concepts.yml @@ -0,0 +1,358 @@ +INHERIT: mkdocs-base.yml + +# Concepts & Reference — encyclopedic documentation of platform abstractions. +# Covers entities, models, methods, software, and properties. +# Deploy to: docs.mat3ra.com/reference/ + +docs_dir: !!python/object/apply:os.getenv ["DOCS_DIR", "lang/en/docs"] + +# Exclude pages that belong to other sites (Guide or Dev). +# Cross-site links use absolute URLs instead. +exclude_docs: | + # Guide-only top-level dirs + cli/ + data-in-objectstorage/ + getting-started/ + /jobs-cli/ + jobs-designer/ + jupyterlite/ + materials-designer/ + pricing/ + remote-connection/ + tutorials/ + ui/ + workflow-designer/ + migrating-to-new-platform.md + + # Resources site top-level dirs + data-on-disk/ + infrastructure/ + + # Developers site top-level dirs + rest-api/ + + # Guide-only pages in shared dirs + accounts/accounting/ + accounts/ui/ + collaboration/actions/ + collaboration/sharing/actions.md + collaboration/sharing/ui.md + collaboration/ui/ + entities-general/actions/ + entities-general/ui/ + jobs/actions/ + jobs/ui/ + materials/actions/ + materials/ui/ + properties/ui/ + workflows/actions/ + workflows/ui/ + other/support.md + other/community-programs.md + other/registration.md + other/faq.md + + # Other sites' homepages + index.md + index-guide.md + index-interface.md + index-dev.md + index-resources.md + index-developers.md + index-cli.md + index-standards.md + + # Data Standards site pages + data/ + data-structured/ + properties/data/ + workflows/data/ + entities-general/data.md + materials/data.md + jobs/data.md + models/data.md + methods/data.md + software/data.md + models-directory/dft/data.md + models-directory/machine-learning/data.md + methods-directory/pseudopotential/data.md + methods-directory/linear-regression/data.md + +validation: + nav: + omitted_files: info + not_found: warn + links: + absolute_links: info + +site_name: "Concepts & Reference" +site_url: https://docs.mat3ra.com/reference +site_description: "Explanatory reference for Mat3ra platform concepts, data models, and scientific methods." +dev_addr: "localhost:8002" + +extra: + # Cross-site URL variables (resolved by macros plugin at build time) + guide_url: https://docs.mat3ra.com/guide + interface_url: https://docs.mat3ra.com/interface + reference_url: https://docs.mat3ra.com/reference + resources_url: https://docs.mat3ra.com/resources + developers_url: https://docs.mat3ra.com/developers + cli_url: https://docs.mat3ra.com/command-line + data_url: https://docs.mat3ra.com/standards + + + + +nav: + - "← All Docs": / + - Home: index-concepts.md + +# ENTITIES — Concepts + - Entities & Common Aspects: + - Overview: entities-general/overview.md + - Lifecycle: entities-general/lifecycle.md + - Ownership: entities-general/ownership.md + - Permissions: entities-general/permissions.md + - Sets: entities-general/sets.md + - Bank: entities-general/bank.md + - Default: entities-general/default.md + +# ACCOUNTS — Concepts + - Accounts: + - Overview: accounts/overview.md + - Users: accounts/users.md + - Balance: accounts/balance.md + - Service Levels: accounts/service-levels.md + - Quota: accounts/quota.md + - Payments and Charges: accounts/payments-charges.md + - Collections: accounts/collections.md + +# COLLABORATION — Concepts + - Collaboration: + - Organizations: + - Overview: collaboration/organizations/overview.md + - Roles: collaboration/organizations/roles.md + - Teams: collaboration/organizations/teams.md + - Entity Sharing: + - Account Access Levels: collaboration/sharing/access-levels.md + +# MATERIALS — Concepts + - Materials: + - Overview: materials/overview.md + - Bank: materials/bank.md + - Default: materials/default.md + - Classification: + - Crystalline: materials/classification/crystalline.md + - Non-Periodic: materials/classification/non-periodic.md + +# WORKFLOWS — Concepts + - Workflows: + - Overview: workflows/overview.md + - Bank: workflows/bank.md + - Default: workflows/default.md + - Components: + - Overview: workflows/components/overview.md + - Subworkflows: workflows/components/subworkflows.md + - Units: workflows/components/units.md + - Maps: workflows/components/maps.md + + - Templating: + - Overview: workflows/templating/overview.md + - Concept: workflows/templating/concept.md + - Jinja: workflows/templating/jinja.md + - Swig: workflows/templating/swig.md + - Exabyte Convention: workflows/templating/exabyte-convention.md + - Examples: workflows/templating/examples.md + - UI Implementation: workflows/templating/ui.md + - Add-ons: + - Overview: workflows/addons/overview.md + - Convergence: workflows/addons/convergence-algorithms.md + - Structural Relaxation: workflows/addons/structural-relaxation.md + +# JOBS — Concepts + - Jobs: + - Overview: jobs/overview.md + - Projects: jobs/projects.md + - Status: jobs/status.md + +# MODELS + - Models: + - Overview: models/overview.md + - Accuracy: models/accuracy.md + - Parameters: models/parameters.md + - Auxiliary Concepts: + - Nudged Elastic Band: models/auxiliary-concepts/nudged-elastic-band.md + - Effective Screening Medium: models/auxiliary-concepts/esm.md + - Reciprocal space: models/auxiliary-concepts/reciprocal-space.md + - Reciprocal space > sampling: models/auxiliary-concepts/reciprocal-space/sampling.md + - Reciprocal space > paths: models/auxiliary-concepts/reciprocal-space/paths.md + - Reciprocal space > convergence: models/auxiliary-concepts/reciprocal-space/convergence.md + - Reciprocal space > electronic occupations: models/auxiliary-concepts/reciprocal-space/electronic-occupations.md + + - Models Directory: + - Overview: models-directory/overview.md + - Density Functional Theory: + - Overview: models-directory/dft/overview.md + - Parameters: models-directory/dft/parameters.md + - Accuracy: models-directory/dft/accuracy.md + - Special Notes: models-directory/dft/notes.md + - References: models-directory/dft/references.md + - Machine Learning: + - Overview: models-directory/machine-learning/overview.md + - Parameters: models-directory/machine-learning/parameters.md + - Units: models-directory/machine-learning/units.md + - Example Workflow: models-directory/machine-learning/example-workflow.md + - Accuracy: models-directory/machine-learning/accuracy.md + +# METHODS + - Methods: + - Overview: methods/overview.md + - Parameters: methods/parameters.md + - Precision: methods/precision.md + - Auxiliary Concepts: + - Optimization Algorithms: methods/auxiliary-concepts/optimization-algorithms.md + + - Methods Directory: + - Overview: methods-directory/overview.md + - Plane-waves and Pseudopotentials: + - Overview: methods-directory/pseudopotential/overview.md + - Default: methods-directory/pseudopotential/default.md + - Parameters: methods-directory/pseudopotential/parameters.md + - Precision: methods-directory/pseudopotential/precision.md + - Important Settings: methods-directory/pseudopotential/important-settings.md + - Actions: methods-directory/pseudopotential/actions.md + - Linear Regression: + - Overview: methods-directory/linear-regression/overview.md + - Parameters: methods-directory/linear-regression/parameters.md + +# SOFTWARE + - Software: + - Overview: software/overview.md + - Components: software/components.md + - Classification: + - Overview: software/classification/overview.md + - Analysis: software/classification/analysis.md + - Development: software/classification/development.md + - Machine Learning: software/classification/machine-learning.md + - Modeling: software/classification/modeling.md + - Scripting: software/classification/scripting.md + +# PROPERTIES + - Properties: + - Overview: properties/overview.md + - Lifecycle: + - Overview: properties/lifecycle/overview.md + - Extractors: properties/lifecycle/extractor.md + - Refinement: properties/lifecycle/refinement.md + - Retrieval: properties/lifecycle/retrieval.md + + - Classification: + - Overview: properties/classification/overview.md + - General: properties/classification/general.md + - Machine Learning: properties/classification/machine-learning.md + - Materials: properties/classification/materials.md + + - Properties Directory: + - Overview: properties-directory/overview.md + - Scalar: + - Total Energy: properties-directory/scalar/total-energy.md + - Fermi Energy: properties-directory/scalar/fermi-energy.md + - Surface Energy: properties-directory/scalar/surface-energy.md + - Zero Point Energy: properties-directory/scalar/zero-point-energy.md + - Pressure: properties-directory/scalar/pressure.md + - Total Force: properties-directory/scalar/total-force.md + - Reaction Energy Barrier: properties-directory/scalar/reaction-energy-barrier.md + - Valence Band Offset: properties-directory/scalar/valence-band-offset.md + - Non-scalar: + - Stress Tensor: properties-directory/non-scalar/stress-tensor.md + - Band Structure: properties-directory/non-scalar/bandstructure.md + - Electronic Density of States: properties-directory/non-scalar/electronic-dos.md + - Band Gaps: properties-directory/non-scalar/band-gaps.md + - Phonon Dispersions: properties-directory/non-scalar/phonon-dispersions.md + - Phonon Density of States: properties-directory/non-scalar/phonon-dos.md + - Reaction Energy Profile: properties-directory/non-scalar/reaction-energy-profile.md + - File Content: properties-directory/non-scalar/file-content.md + - Workflow: properties-directory/non-scalar/workflow.md + - Elemental: + - Atomic Radius: properties-directory/elemental/atomic-radius.md + - Electronegativity: properties-directory/elemental/electronegativity.md + - Ionization Potential: properties-directory/elemental/ionization-potential.md + - Structural: + - Basis: properties-directory/structural/basis.md + - Atomic Forces: properties-directory/structural/atomic-forces.md + - Lattice: properties-directory/structural/lattice.md + - Symmetry: properties-directory/structural/symmetry.md + - Final Structure: properties-directory/structural/final-structure.md + - Magnetic Moment: properties-directory/structural/magnetic-moment.md + - Inchi: properties-directory/structural/inchi.md + - Inchi Key: properties-directory/structural/inchi-key.md + + +# SOFTWARE DIRECTORY + - Software Directory: + - Overview: software-directory/overview.md + - Modeling: + - Quantum ESPRESSO: + - Overview: software-directory/modeling/quantum-espresso/overview.md + - Components: software-directory/modeling/quantum-espresso/components.md + - Compute Parameters: software-directory/modeling/quantum-espresso/compute-parameters.md + - VASP: + - Overview: software-directory/modeling/vasp/overview.md + - Components: software-directory/modeling/vasp/components.md + - Compute Parameters: software-directory/modeling/vasp/compute-parameters.md + - TurboMole: software-directory/modeling/turbomole.md + - LAMMPS: software-directory/modeling/lammps.md + - NWChem: software-directory/modeling/nwchem.md + - CP2K: software-directory/modeling/cp2k.md + - Gromacs: software-directory/modeling/gromacs.md + - WIEN2k: software-directory/modeling/wien2k.md + - Scripting: + - Shell: + - Overview: software-directory/scripting/shell/overview.md + - Python: + - Overview: software-directory/scripting/python/overview.md + - Jupyter Lab: + - Overview: software-directory/scripting/jupyter-lab/overview.md + - Machine Learning (ML): + - TensorFlow: software-directory/machine-learning/tensorflow.md + - Python ML: + - Overview: software-directory/machine-learning/python-ml/overview.md + - Components: software-directory/machine-learning/python-ml/components.md + - Workflow Structure: software-directory/machine-learning/python-ml/workflow-structure.md + - Analysis & Visualization: + - VESTA: software-directory/analysis/vesta.md + - XCRYSDEN: software-directory/analysis/xcrysden.md + - P4VASP: software-directory/analysis/p4vasp.md + - VMD: software-directory/analysis/vmd.md + - Development Tools: + - Compilers: software-directory/development/compilers.md + - Libraries: software-directory/development/libraries.md + - Text Editors: software-directory/development/text-editors.md + +# SECURITY + - Security: + - Current State of Cloud Security: security/current-state.md + - Overview: security/overview.md + - Security Policies: security/security-policies.md + - Threats Analysis: security/threats-analysis.md + +# BENCHMARKS + - Benchmarks: + - Overview: benchmarks/overview.md + - High Throughput Screening: benchmarks/high-throughput-screening.md + - Distributed Memory Runs: benchmarks/distributed-memory.md + - Vendor Comparison: benchmarks/vendor-comparison.md + - High-Performance Linpack: benchmarks/hpl-benchmark.md + - 2018-11 HPL VASP GROMACS: benchmarks/2018-11-12-comparison.md + +# LEGAL + - Site Policy: + - Privacy: site-policy/privacy-statement.md + - Sharing: site-policy/sharing-policy.md + - Terms of Service: site-policy/terms-of-service.md + +# OTHER + - Other: + - Publications: other/publications.md + - Terms of Service: other/terms-of-service.md + - Restricted Content: other/restricted.md diff --git a/mkdocs-dev.yml b/mkdocs-dev.yml new file mode 100644 index 000000000..e29785239 --- /dev/null +++ b/mkdocs-dev.yml @@ -0,0 +1,141 @@ +# Developer Guide — under-the-hood documentation for power users and developers. +# Covers REST API, infrastructure, and data storage internals. +# Deploy to: docs.mat3ra.com/dev/ + +INHERIT: mkdocs-base.yml + +docs_dir: !!python/object/apply:os.getenv ["DOCS_DIR", "lang/en/docs"] + +# Exclude pages that belong to other sites (Guide or Concepts). +# Cross-site links use absolute URLs instead. +exclude_docs: | + accounts/ + benchmarks/ + cli/ + collaboration/ + data/ + data-structured/ + entities-general/ + getting-started/ + jobs/ + jobs-cli/ + jobs-designer/ + jupyterlite/ + materials/ + materials-designer/ + methods/ + methods-directory/ + models/ + models-directory/ + other/ + pricing/ + properties/ + properties-directory/ + remote-connection/ + security/ + site-policy/ + software/ + software-directory/ + tutorials/ + ui/ + workflow-designer/ + workflows/ + migrating-to-new-platform.md + + # Guide-only pages in shared dirs + data-in-objectstorage/actions/ + data-in-objectstorage/ui/ + + # Other sites' homepages + index.md + index-guide.md + index-interface.md + index-concepts.md + index-standards.md + +validation: + nav: + omitted_files: info + not_found: warn + links: + absolute_links: info + +site_name: "Developer Guide" +site_url: https://docs.mat3ra.com/dev +site_description: "Developer-focused documentation for the Mat3ra platform: REST API, infrastructure, and data storage." +dev_addr: "localhost:8003" + +theme: + features: + - announce.dismiss + - content.action.edit + - content.code.annotate + - content.code.copy + - content.tooltips + - navigation.footer + - navigation.top + - search.highlight + - search.suggest + - navigation.expand + +extra: + # Cross-site URL variables (resolved by macros plugin at build time) + guide_url: https://docs.mat3ra.com/guide + interface_url: https://docs.mat3ra.com/interface + reference_url: https://docs.mat3ra.com/reference + dev_url: https://docs.mat3ra.com/dev + data_url: https://docs.mat3ra.com/standards + + + + +nav: + - "← All Docs": / + - Home: index-dev.md + +# REST API + - REST API: + - Overview: rest-api/overview.md + - Authentication: rest-api/authentication.md + - Query structure: rest-api/query-structure.md + - Endpoints: rest-api/endpoints.md + - API Explorer: rest-api/api-explorer.md + - API client: rest-api/api-client.md + - API examples: rest-api/api-examples.md + +# INFRASTRUCTURE + - General Infrastructure: + - Overview: infrastructure/overview.md + - Storage System: infrastructure/storage.md + - Login Node: + - Overview: infrastructure/login/overview.md + - Directory Structure: infrastructure/login/directories.md + - Clusters: + - Overview: infrastructure/clusters/overview.md + - Directory Structure: infrastructure/clusters/directories.md + - Hardware Specifications: infrastructure/clusters/hardware.md + - Google Clusters: infrastructure/clusters/google.md + - AWS Clusters: infrastructure/clusters/aws.md + - Azure Clusters: infrastructure/clusters/azure.md + - Resource Management: + - Overview: infrastructure/resource/overview.md + - Category: infrastructure/resource/category.md + - Queues: infrastructure/resource/queues.md + - Compute: + - Overview: infrastructure/compute/overview.md + - Parameters: infrastructure/compute/parameters.md + - Data: infrastructure/compute/data.md + +# DATA ON DISK + - Data on Disk: + - Overview: data-on-disk/overview.md + - Directory Structure: data-on-disk/directories.md + - Quotas: data-on-disk/quotas.md + - Security: data-on-disk/security.md + +# DATA IN OBJECT STORAGE — Concepts + - Data in Object Storage: + - Overview: data-in-objectstorage/overview.md + - Files: data-in-objectstorage/files.md + - Security: data-in-objectstorage/security.md + - Dropbox: data-in-objectstorage/dropbox.md diff --git a/mkdocs-developers.yml b/mkdocs-developers.yml new file mode 100644 index 000000000..9628a45ec --- /dev/null +++ b/mkdocs-developers.yml @@ -0,0 +1,117 @@ +# Developers — REST API reference and contribution guides. +# Deploy to: docs.mat3ra.com/developers/ + +INHERIT: mkdocs-base.yml + +docs_dir: !!python/object/apply:os.getenv ["DOCS_DIR", "lang/en/docs"] + +# Exclude pages that belong to other sites. +exclude_docs: | + accounts/ + benchmarks/ + cli/ + collaboration/ + data/ + data-structured/ + data-in-objectstorage/ + data-on-disk/ + entities-general/ + getting-started/ + infrastructure/ + jobs/ + /jobs-cli/ + jobs-designer/ + jupyterlite/ + materials/ + materials-designer/ + methods/ + methods-directory/ + models/ + models-directory/ + other/ + pricing/ + properties/ + properties-directory/ + remote-connection/ + security/ + site-policy/ + software/ + software-directory/ + tutorials/ + ui/ + workflow-designer/ + workflows/ + migrating-to-new-platform.md + + # Other sites' homepages + index.md + index-guide.md + index-interface.md + index-concepts.md + index-dev.md + index-resources.md + index-cli.md + index-standards.md + + # Data Standards site pages + models/data.md + methods/data.md + software/data.md + models-directory/dft/data.md + models-directory/machine-learning/data.md + methods-directory/pseudopotential/data.md + methods-directory/linear-regression/data.md + materials/data.md + jobs/data.md + +validation: + nav: + omitted_files: info + not_found: warn + links: + absolute_links: info + +site_name: "Developers" +site_url: https://docs.mat3ra.com/developers +site_description: "REST API reference and contribution guides for the Mat3ra platform." +dev_addr: "localhost:8006" + +theme: + features: + - announce.dismiss + - content.action.edit + - content.code.annotate + - content.code.copy + - content.tooltips + - navigation.footer + - navigation.top + - search.highlight + - search.suggest + - navigation.expand + +extra: + # Cross-site URL variables (resolved by macros plugin at build time) + guide_url: https://docs.mat3ra.com/guide + interface_url: https://docs.mat3ra.com/interface + reference_url: https://docs.mat3ra.com/reference + resources_url: https://docs.mat3ra.com/resources + developers_url: https://docs.mat3ra.com/developers + cli_url: https://docs.mat3ra.com/command-line + data_url: https://docs.mat3ra.com/standards + + + + +nav: + - "← All Docs": / + - Home: index-developers.md + +# REST API + - REST API: + - Overview: rest-api/overview.md + - Authentication: rest-api/authentication.md + - Query structure: rest-api/query-structure.md + - Endpoints: rest-api/endpoints.md + - API Explorer: rest-api/api-explorer.md + - API client: rest-api/api-client.md + - API examples: rest-api/api-examples.md diff --git a/mkdocs-guide.yml b/mkdocs-guide.yml new file mode 100644 index 000000000..ea40f040f --- /dev/null +++ b/mkdocs-guide.yml @@ -0,0 +1,274 @@ +INHERIT: mkdocs-base.yml + +# Platform Guide — tutorials, software directory, and CLI reference. +# Deploy to: docs.mat3ra.com/guide/ + +docs_dir: !!python/object/apply:os.getenv ["DOCS_DIR", "lang/en/docs"] + +# Exclude pages that belong to other sites. +exclude_docs: | + # Concepts/Reference top-level dirs + benchmarks/ + data/ + data-structured/ + methods/ + methods-directory/ + models/ + models-directory/ + properties-directory/ + security/ + site-policy/ + software/ + software-directory/ + + # Resources site top-level dirs + data-on-disk/ + infrastructure/ + + # Developers site top-level dirs + rest-api/ + + other/terms-of-service.md + + # Interface site top-level dirs + jobs-designer/ + materials-designer/ + ui/ + workflow-designer/ + + # CLI site top-level dirs + /cli/ + /jobs-cli/ + /jupyterlite/ + /remote-connection/ + + # Home site sections (linked from homepage) + getting-started/ + pricing/ + /other/ + + # Concepts-only pages in shared dirs + accounts/overview.md + accounts/users.md + accounts/balance.md + accounts/payments-charges.md + accounts/quota.md + accounts/service-levels.md + accounts/collections.md + collaboration/organizations/ + entities-general/overview.md + entities-general/data.md + entities-general/sets.md + entities-general/bank.md + entities-general/permissions.md + entities-general/default.md + entities-general/lifecycle.md + entities-general/ownership.md + jobs/overview.md + jobs/projects.md + jobs/data.md + jobs/status.md + materials/overview.md + materials/data.md + materials/bank.md + materials/default.md + materials/classification/ + properties/overview.md + properties/classification/ + properties/lifecycle/ + properties/data/ + workflows/overview.md + workflows/bank.md + workflows/default.md + workflows/addons/ + workflows/components/ + workflows/data/ + workflows/templating/ + other/publications.md + other/documentation.md + other/citation.md + + # Interface site pages in shared dirs + accounts/accounting/ + accounts/ui/ + collaboration/actions/ + collaboration/sharing/ + collaboration/ui/ + entities-general/actions/ + entities-general/ui/ + jobs/actions/ + jobs/ui/ + materials/actions/ + materials/ui/ + properties/ui/ + workflows/actions/ + workflows/ui/ + data-in-objectstorage/ + + # Dev-only pages in shared dirs + data-in-objectstorage/overview.md + data-in-objectstorage/files.md + data-in-objectstorage/security.md + data-in-objectstorage/dropbox.md + + # Other sites' homepages + index.md + index-concepts.md + index-dev.md + index-resources.md + index-developers.md + index-standards.md + index-interface.md + index-cli.md + + # Data Standards site pages + software-directory/modeling/vasp/data.md + software-directory/modeling/quantum-espresso/data.md + software-directory/scripting/python/data.md + software-directory/scripting/shell/data.md + software-directory/scripting/jupyter-lab/data.md + software-directory/machine-learning/python-ml/data.md + models/data.md + methods/data.md + software/data.md + models-directory/dft/data.md + models-directory/machine-learning/data.md + methods-directory/pseudopotential/data.md + methods-directory/linear-regression/data.md + materials/data.md + jobs/data.md + +validation: + nav: + omitted_files: info + not_found: warn + links: + absolute_links: info + +site_name: "Tutorials" +site_url: https://docs.mat3ra.com/guide +site_description: "Step-by-step tutorials for DFT, ML, materials construction, and simulation workflows." +dev_addr: "localhost:8001" + +theme: + features: + - announce.dismiss + - content.action.edit + - content.code.annotate + - content.code.copy + - content.tooltips + - navigation.footer + - navigation.top + - search.highlight + - search.suggest + - navigation.expand + +extra: + # Cross-site URL variables (resolved by macros plugin at build time) + guide_url: https://docs.mat3ra.com/guide + interface_url: https://docs.mat3ra.com/interface + reference_url: https://docs.mat3ra.com/reference + resources_url: https://docs.mat3ra.com/resources + developers_url: https://docs.mat3ra.com/developers + cli_url: https://docs.mat3ra.com/command-line + data_url: https://docs.mat3ra.com/standards + + + + +nav: + - "← All Docs": / + - Home: /guide/ + +# 1. Materials Design + - 1. Materials Design: + - 1.1. General: + - Import from Files: tutorials/materials/import-from-files.md + - Combinatorial Sets: tutorials/materials/combinatorial-screening.md + - Interpolated Sets: tutorials/materials/interpolated-sets.md + - Molecule on a Surface: tutorials/materials/molecule-surface.md + - Interface, quick setup (3D Editor): tutorials/materials/slabs-interface.md + - Interface, minimal strain (JupyterLite): tutorials/materials/jupyterlite-zsl.md + - VESTA via Remote Desktop: tutorials/materials/vesta-remote-desktop.md + - 1.2. Reproducing Published Structures: + - Overview: tutorials/materials/specific/overview.md + - Substitutional Defects in Graphene: tutorials/materials/specific/defect-point-substitution-graphene.md + - Substitutional Defects in Graphene (Band Structure): tutorials/materials/specific/defect-point-substitution-graphene-simulation.md + - Vacancy-Substitution Pair in GaN: tutorials/materials/specific/defect-point-pair-gallium-nitride.md + - Vacancy Defect in h-BN: tutorials/materials/specific/defect-point-vacancy-boron-nitride.md + - Interstitial Defect in SnO: tutorials/materials/specific/defect-point-interstitial-tin-oxide.md + - Island Surface Defect in TiN: tutorials/materials/specific/defect-surface-island-titanium-nitride.md + - Step Surface Defect on Pt(111): tutorials/materials/specific/defect-surface-step-platinum.md + - Twisted Bilayer h-BN Nanoribbons: tutorials/materials/specific/interface-bilayer-twisted-nanoribbons-boron-nitride.md + - Twisted Bilayer MoS2: tutorials/materials/specific/interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide.md + - Twisted Bilayer MoS2 (Band Structure): tutorials/materials/specific/interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide-simulation.md + - Adatom Surface Defects on Graphene: tutorials/materials/specific/defect-surface-adatom-graphene.md + - H-Passivated Silicon Nanowire: tutorials/materials/specific/passivation-edge-nanowire-silicon.md + - H-Passivated Silicon (100) Surface: tutorials/materials/specific/passivation-surface-silicon.md + - Gold Nanoclusters: tutorials/materials/specific/nanocluster-gold.md + - SrTiO3 Slab: tutorials/materials/specific/slab-strontium-titanate.md + - Graphene / h-BN Interface: tutorials/materials/specific/interface-2d-2d-graphene-boron-nitride.md + - Cu / SiO2 Interface: tutorials/materials/specific/interface-3d-3d-copper-silicon-dioxide.md + - Graphene / SiO2 Interface: tutorials/materials/specific/interface-2d-3d-graphene-silicon-dioxide.md + - High-k Metal Gate Stack: tutorials/materials/specific/heterostructure-silicon-silicon-dioxide-hafnium-dioxide-titanium-nitride.md + - Ripple Perturbation in Graphene: tutorials/materials/specific/perturbation-ripples-graphene.md + - Grain Boundary in Cu (FCC): tutorials/materials/specific/defect-planar-grain-boundary-3d-fcc-metals-copper.md + - Grain Boundary (2D) in h-BN: tutorials/materials/specific/defect-planar-grain-boundary-2d-boron-nitride.md + - Gr/Ni(111) Interface Optimization: tutorials/materials/specific/optimization-interface-film-xy-position-graphene-nickel.md + - Pt Adatoms Island on MoS2: tutorials/materials/specific/defect-point-adatom-island-molybdenum-disulfide-platinum.md + +# 2. Simulations + - 2. Simulations: + - 2.1. Density Functional Theory: + - Electronic Properties: + - Band Structure: tutorials/dft/electronic/band-structure.md + - Band Structure, HSE (QE): tutorials/dft/electronic/hse-qe-bs.md + - Band Structure, HSE (VASP): tutorials/dft/electronic/hse-vasp-bg.md + - Band Structure, GW Full Freq. (QE): tutorials/dft/electronic/gw-qe-bs-fullfreq.md + - Band Structure, GW Plasmon P. (QE): tutorials/dft/electronic/gw-qe-bs-plasmon.md + - Band Gap: tutorials/dft/electronic/band-gap.md + - Band Gap, HSE (QE): tutorials/dft/electronic/hse-qe-bg.md + - Band Gap, GW (VASP): tutorials/dft/electronic/gw-vasp-bg.md + - Density of States: tutorials/dft/electronic/density-of-states.md + - Density Mesh: tutorials/dft/electronic/electronic-density-mesh.md + - Fermi Surface: tutorials/dft/electronic/fermi-surface.md + - Valence Band Offset: tutorials/dft/electronic/valence-band-offset.md + - Effective Screening Medium: tutorials/dft/electronic/esm-qe.md + - Hubbard U (QE): tutorials/dft/electronic/hubbard.md + - Magnetic Properties (QE): tutorials/dft/electronic/spin-magnetic-qe.md + - Spin-Orbit Coupling (QE): tutorials/dft/electronic/spin-orbit-coupling-qe.md + - Optical Properties: + - Dielectric Constant (QE): tutorials/dft/optical/epsilon-optimal-basis.md + - Vibrational Properties: + - Zero Point Energy: tutorials/dft/vibrational/zero-point-energy.md + - Phonons: tutorials/dft/vibrational/phonon-dispersion-dos.md + - Phonons on a Grid: tutorials/dft/vibrational/phonons-grid.md + - Thermodynamic Properties: + - Surface Energy: tutorials/dft/thermodynamic/surface-energy.md + - Chemical Properties: + - Reaction Energy Profile (QE): tutorials/dft/chemical/reaction-profile-qe.md + - Reaction Energy Profile (VASP): tutorials/dft/chemical/reaction-profile-vasp.md + - Workflow Add-ons: + - k-point Convergence: tutorials/dft/addons/kpt-convergence.md + - Structural Relaxation: tutorials/dft/addons/structural-relaxation.md + - 2.2. Machine Learning: + - Train a NN Potential (QE, DeePMD, LAMMPS): tutorials/ml/deepmd-mlff-with-espresso-cp-and-lammps.md + - Python MLFF (MatterSim/GPU): tutorials/ml/run-mlff-python-workflows-mattersim.md + +# 3. Other + - 3. Other: + - 3.1. Command-Line Jobs: + - Create + Run a CLI Job: tutorials/jobs-cli/job-cli-example.md + - Import a CLI Job to Web Interface: tutorials/jobs-cli/cli-job-import.md + - QE GPU Job: tutorials/jobs-cli/qe-gpu.md + - 3.2. Templating: + - Flags by Elemental Composition: tutorials/templating/set-flag-by-composition.md + - Magnetic Moment on Atoms by Specie: tutorials/templating/set-magnetic-moment.md + - 3.3. Tools and Environments: + - Accessing the Platform: tutorials/platform-access.md + - Jupyter Notebook: tutorials/other/jupyter.md + - Restart from Previous Job: tutorials/other/restart-job.md + - TensorFlow (GPU): tutorials/general-functionality/tensorflow-gpu.md + - Add New Software: /command-line/cli/actions/add-software/ + + diff --git a/mkdocs-interface.yml b/mkdocs-interface.yml new file mode 100644 index 000000000..9ad008d5f --- /dev/null +++ b/mkdocs-interface.yml @@ -0,0 +1,385 @@ +# User Interface — platform UI components, entity management, and designer tools. +# Deploy to: docs.mat3ra.com/interface/ + +INHERIT: mkdocs-base.yml + +docs_dir: !!python/object/apply:os.getenv ["DOCS_DIR", "lang/en/docs"] + +# Exclude pages that belong to other sites. +exclude_docs: | + # Concepts-only top-level dirs + benchmarks/ + data/ + data-structured/ + methods/ + methods-directory/ + models/ + models-directory/ + properties-directory/ + security/ + site-policy/ + software/ + + # Resources site top-level dirs + data-on-disk/ + infrastructure/ + + # Developers site top-level dirs + rest-api/ + + other/terms-of-service.md + + # Guide site top-level dirs + getting-started/ + pricing/ + software-directory/ + tutorials/ + migrating-to-new-platform.md + + # CLI site top-level dirs + cli/ + /jobs-cli/ + remote-connection/ + + # Concepts-only pages in shared dirs + accounts/overview.md + accounts/users.md + accounts/balance.md + accounts/payments-charges.md + accounts/quota.md + accounts/service-levels.md + accounts/collections.md + collaboration/organizations/ + entities-general/overview.md + entities-general/data.md + entities-general/sets.md + entities-general/bank.md + entities-general/permissions.md + entities-general/default.md + entities-general/lifecycle.md + entities-general/ownership.md + jobs/overview.md + jobs/projects.md + jobs/data.md + jobs/status.md + materials/overview.md + materials/data.md + materials/bank.md + materials/default.md + materials/classification/ + properties/overview.md + properties/classification/ + properties/lifecycle/ + properties/data/ + workflows/overview.md + workflows/bank.md + workflows/default.md + workflows/addons/ + workflows/components/ + workflows/data/ + workflows/templating/ + other/publications.md + other/documentation.md + other/citation.md + other/faq.md + other/support.md + other/community-programs.md + other/registration.md + + # Resources site pages in shared dirs + data-in-objectstorage/overview.md + data-in-objectstorage/files.md + data-in-objectstorage/security.md + data-in-objectstorage/dropbox.md + + # Other sites' homepages + index.md + index-guide.md + index-concepts.md + index-dev.md + index-resources.md + index-developers.md + index-standards.md + index-cli.md + + # Data Standards site pages + software-directory/modeling/vasp/data.md + software-directory/modeling/quantum-espresso/data.md + software-directory/scripting/python/data.md + software-directory/scripting/shell/data.md + software-directory/scripting/jupyter-lab/data.md + software-directory/machine-learning/python-ml/data.md + models/data.md + methods/data.md + software/data.md + models-directory/dft/data.md + models-directory/machine-learning/data.md + methods-directory/pseudopotential/data.md + methods-directory/linear-regression/data.md + materials/data.md + jobs/data.md + +validation: + nav: + omitted_files: info + not_found: warn + links: + absolute_links: info + +site_name: "User Interface" +site_url: https://docs.mat3ra.com/interface +site_description: "Platform interface components, entity management, designer tools, and actions reference for the Mat3ra platform." +dev_addr: "localhost:8004" + +theme: + features: + - announce.dismiss + - content.action.edit + - content.code.annotate + - content.code.copy + - content.tooltips + - navigation.footer + - navigation.top + - search.highlight + - search.suggest + + +extra: + # Cross-site URL variables (resolved by macros plugin at build time) + guide_url: https://docs.mat3ra.com/guide + interface_url: https://docs.mat3ra.com/interface + reference_url: https://docs.mat3ra.com/reference + resources_url: https://docs.mat3ra.com/resources + developers_url: https://docs.mat3ra.com/developers + cli_url: https://docs.mat3ra.com/command-line + data_url: https://docs.mat3ra.com/standards + + + + +nav: + - "← All Docs": / + - Home: index-interface.md + +# UI COMPONENTS + - Interface Components: + - Overview: ui/overview.md + - Header and Footer: ui/header-footer.md + - Left-hand Sidebar: ui/left-sidebar.md + - Account Menu: ui/account-menu.md + - Support: ui/support.md + - Specific: + - Homepage Navigation: ui/specific/homepage.md + - Dashboard: ui/specific/dashboard.md + - Tabs Navigation: ui/specific/tabs-navigator.md + +# ACCOUNTS — UI & Actions + - Accounts: + - User Interface: + - Overview: accounts/ui/overview.md + - Profile Page: accounts/ui/profile-page.md + - Account Badge: accounts/ui/account-badge.md + - Switcher: accounts/ui/switcher.md + - Explorer: accounts/ui/explorer.md + - Bio: accounts/ui/bio.md + - Service Levels: accounts/ui/service-level.md + - Payments and Charges: accounts/ui/charges-payments.md + - Preferences: accounts/ui/preferences-overview.md + - Preferences > Profile: accounts/ui/preferences/profile.md + - Preferences > User Settings: accounts/ui/preferences/settings.md + - Preferences > API Tokens: accounts/ui/preferences/api.md + - Preferences > SSH Keys: accounts/ui/preferences/ssh.md + - Preferences > Change Password: accounts/ui/preferences/password.md + - Accounting Actions: + - Overview: accounts/accounting/overview.md + - Check balance and quota: accounts/accounting/check-balance-quota.md + - Increase balance: accounts/accounting/increase-balance.md + - Increase Quota: accounts/accounting/increase-quota.md + - Change Payment Method: accounts/accounting/payment-methods.md + - Charges > Advanced search: accounts/accounting/charges-advanced-search.md + +# COLLABORATION — UI & Actions + - Collaboration: + - User Interface: + - Overview: collaboration/ui/overview.md + - Teams Explorer: collaboration/ui/teams-explorer.md + - Team Page: collaboration/ui/team-page.md + - People Explorer: collaboration/ui/people-explorer.md + - Entity Sharing: + - User Interface: collaboration/sharing/ui.md + - Actions: collaboration/sharing/actions.md + - Actions: + - Organization > Overview: collaboration/actions/organization/overview.md + - Organization > Create: collaboration/actions/organization/create.md + - Organization > Add / Remove Member: collaboration/actions/organization/add-remove-member.md + - Organization > Make / Revoke Admin: collaboration/actions/organization/make-revoke-admin.md + - Organization > Create / Delete Team: collaboration/actions/organization/create-delete-team.md + - Organization > Create Entities: collaboration/actions/organization/create-entities.md + - Team > Overview: collaboration/actions/team/overview.md + - Team > Edit Permissions: collaboration/actions/team/edit-permissions.md + - Team > Add / Remove Member: collaboration/actions/team/add-remove-member.md + - Team > Add / Remove Entity: collaboration/actions/team/add-remove-entity.md + +# ENTITIES — UI & Actions + - Entities (Common Actions): + - User Interface: + - Overview: entities-general/ui/overview.md + - Explorer: entities-general/ui/explorer.md + - Designer: entities-general/ui/designer.md + - Viewer: entities-general/ui/viewer.md + - Actions: + - Overview: entities-general/actions/overview.md + - Select: entities-general/actions/select.md + - Search: entities-general/actions/search.md + - Advanced search: entities-general/actions/advanced-search.md + - Open: entities-general/actions/open-edit.md + - Clone: entities-general/actions/clone.md + - Delete: entities-general/actions/delete.md + - Set default: entities-general/actions/set-default.md + - Add metadata: entities-general/actions/metadata.md + - Change name: entities-general/actions/name.md + - Create: entities-general/actions/create.md + - Bank > Copy from: entities-general/actions/copy-bank.md + - Sets > Create / Delete: entities-general/actions/create-sets.md + - Sets > Change Type: entities-general/actions/change-set-type.md + - Sets > Set Index: entities-general/actions/set-entity-index.md + - Sets > Move To: entities-general/actions/move-to-sets.md + +# MATERIALS — UI & Actions + - Materials: + - User Interface: + - Explorer: materials/ui/explorer.md + - Viewer: materials/ui/viewer.md + - Actions: + - Overview: materials/actions/overview.md + - Import: materials/actions/import.md + - Upload: materials/actions/upload.md + - Set default: materials/actions/set-default.md + - Advanced search: materials/actions/advanced-search.md + - Bank > Copy from: materials/actions/copy-bank.md + +# MATERIALS DESIGNER + - Materials Designer: + - Overview: materials-designer/overview.md + - Header Menu: + - Overview: materials-designer/header-menu/header-menu-intro.md + - Input/Output: materials-designer/header-menu/input-output.md + - "Input/Output > Import": materials-designer/header-menu/input-output/import.md + - "Input/Output > Import from Standata": materials-designer/header-menu/input-output/standata-import.md + - "Input/Output > Export": materials-designer/header-menu/input-output/export.md + - "Input/Output > Save": materials-designer/header-menu/input-output/save.md + - Edit: materials-designer/header-menu/edit.md + - View: materials-designer/header-menu/view.md + - Advanced: materials-designer/header-menu/advanced.md + - "Advanced > Supercell": materials-designer/header-menu/advanced/supercell.md + - "Advanced > Combinatorial Set": materials-designer/header-menu/advanced/combinatorial-set.md + - "Advanced > Interpolated Set": materials-designer/header-menu/advanced/interpolated-set.md + - "Advanced > Surface / Slab": materials-designer/header-menu/advanced/surface-slab.md + - "Advanced > Boundary Conditions": materials-designer/header-menu/advanced/boundary-conditions.md + - "Advanced > JupyterLite Transformation": materials-designer/header-menu/advanced/jupyterlite-dialog.md + - Help: materials-designer/header-menu/help.md + - Sidebar: + - Items List: materials-designer/sidebar-items.md + - Source Editor: + - Overview: materials-designer/source-editor.md + - Lattice Editor: materials-designer/source-editor/lattice.md + - Basis Editor: materials-designer/source-editor/basis.md + - 3D Viewer/Editor: + - Overview: materials-designer/3d-editor.md + - View Options: materials-designer/3d-editor/view.md + - Parameters Options: materials-designer/3d-editor/parameters.md + - Edit Options: materials-designer/3d-editor/edit.md + - "Edit Actions > Overview": materials-designer/3d-editor/editor-actions/overview.md + - "Edit Actions > Add/Remove Atoms": materials-designer/3d-editor/editor-actions/add-remove-atoms.md + - "Edit Actions > Adjust Cell Parameters": materials-designer/3d-editor/editor-actions/adjust-cell-parameters.md + - "Edit Actions > Move/Rotate Atoms": materials-designer/3d-editor/editor-actions/move-rotate-atoms.md + - Export Options: materials-designer/3d-editor/export.md + +# WORKFLOWS — UI & Actions + - Workflows: + - User Interface: + - Explorer: workflows/ui/explorer.md + - Viewer: workflows/ui/viewer.md + - Actions: + - Overview: workflows/actions/overview.md + - Update: workflows/actions/update.md + - Set default: workflows/actions/set-default.md + - Bank > Copy from: workflows/actions/copy-bank.md + +# WORKFLOW DESIGNER + - Workflow Designer: + - Overview: workflow-designer/overview.md + - Header Menu: + - Overview: workflow-designer/header-menu.md + - Sidebar: + - Items List: workflow-designer/sidebar.md + - Subworkflow Editor: + - Overview: workflow-designer/subworkflow-editor/overview.md + - Actions Menu: workflow-designer/subworkflow-editor/actions-menu.md + - Tabs: workflow-designer/subworkflow-editor/tabs-general.md + - Tabs > Overview: workflow-designer/subworkflow-editor/overview-tab.md + - Tabs > Important Settings: workflow-designer/subworkflow-editor/important-settings.md + - Tabs > Detailed View: workflow-designer/subworkflow-editor/detailed-view.md + - Tabs > Compute: workflow-designer/subworkflow-editor/compute.md + - Units Flowchart: workflow-designer/subworkflow-editor/units-flowchart.md + - Unit Editor: + - Overview: workflow-designer/unit-editor.md + - Input Templates: workflow-designer/unit-editor/input-templates.md + +# JOBS — UI & Actions + - Jobs: + - User Interface: + - Explorer: jobs/ui/explorer.md + - Viewer: jobs/ui/viewer.md + - Results Tab: jobs/ui/results-tab.md + - Files Tab: jobs/ui/files-tab.md + - Projects Explorer: jobs/ui/projects-explorer.md + - Projects Page: jobs/ui/project-page.md + - Actions: + - Overview: jobs/actions/overview.md + - Create: jobs/actions/create.md + - Run: jobs/actions/run.md + - Terminate: jobs/actions/terminate.md + - Purge: jobs/actions/purge.md + - Projects > Create / Delete: jobs/actions/create-delete-project.md + +# JOBS DESIGNER + - Jobs Designer: + - Overview: jobs-designer/overview.md + - Header Menu: jobs-designer/header-menu.md + - Materials Tab: jobs-designer/materials-tab.md + - Workflow Tab: jobs-designer/workflow-tab.md + - Compute Tab: jobs-designer/compute-tab.md + - Actions > Header Menu: + - Select Materials: jobs-designer/actions-header-menu/select-materials.md + - Select Workflow: jobs-designer/actions-header-menu/select-workflow.md + - Select Parent: jobs-designer/actions-header-menu/select-parent.md + +# PROPERTIES — UI only + - Properties: + - User Interface: + - Explorer: properties/ui/explorer.md + - Viewer: properties/ui/viewer.md + +# DATA IN OBJECT STORAGE — UI & Actions + - Data in Object Storage: + - User Interface: + - Dropbox Page: data-in-objectstorage/ui/dropbox-page.md + - Files Explorer: data-in-objectstorage/ui/explorer.md + - Actions > Files: + - Overview: data-in-objectstorage/actions/overview.md + - Download: data-in-objectstorage/actions/download.md + - Copy Path: data-in-objectstorage/actions/copy-path.md + - Upload: data-in-objectstorage/actions/upload.md + - Create Folder: data-in-objectstorage/actions/create-folder.md + +# JUPYTERLITE + - JupyterLite Environment: + - Overview: jupyterlite/overview.md + - Accessing JupyterLite: jupyterlite/accessing-jupyterlite.md + - Authentication: jupyterlite/authentication.md + - Pyodide: jupyterlite/pyodide.md + - Dependencies and Imports: jupyterlite/dependencies-installation.md + - Data Exchange: jupyterlite/data-exchange.md + - File Storage and Synchronization: jupyterlite/file-storage-synchronization.md + - Common Actions: jupyterlite/common-actions.md diff --git a/mkdocs-resources.yml b/mkdocs-resources.yml new file mode 100644 index 000000000..ec46cc5ed --- /dev/null +++ b/mkdocs-resources.yml @@ -0,0 +1,147 @@ +# Platform Resources — infrastructure, storage, and compute resources. +# Covers clusters, login nodes, resource management, and data storage. +# Deploy to: docs.mat3ra.com/resources/ + +INHERIT: mkdocs-base.yml + +docs_dir: !!python/object/apply:os.getenv ["DOCS_DIR", "lang/en/docs"] + +# Exclude pages that belong to other sites. +exclude_docs: | + accounts/ + benchmarks/ + cli/ + collaboration/ + data/ + data-structured/ + entities-general/ + getting-started/ + jobs/ + /jobs-cli/ + jobs-designer/ + jupyterlite/ + materials/ + materials-designer/ + methods/ + methods-directory/ + models/ + models-directory/ + other/ + pricing/ + properties/ + properties-directory/ + remote-connection/ + rest-api/ + security/ + site-policy/ + software/ + software-directory/ + tutorials/ + ui/ + workflow-designer/ + workflows/ + migrating-to-new-platform.md + + # Interface-only pages in shared dirs + data-in-objectstorage/actions/ + data-in-objectstorage/ui/ + + # Other sites' homepages + index.md + index-guide.md + index-interface.md + index-concepts.md + index-dev.md + index-developers.md + index-cli.md + index-standards.md + + # Data Standards site pages + models/data.md + methods/data.md + software/data.md + models-directory/dft/data.md + models-directory/machine-learning/data.md + methods-directory/pseudopotential/data.md + methods-directory/linear-regression/data.md + materials/data.md + jobs/data.md + +validation: + nav: + omitted_files: info + not_found: warn + links: + absolute_links: info + +site_name: "Platform Resources" +site_url: https://docs.mat3ra.com/resources +site_description: "Compute clusters, storage systems, and resource management for the Mat3ra platform." +dev_addr: "localhost:8005" + +theme: + features: + - announce.dismiss + - content.action.edit + - content.code.annotate + - content.code.copy + - content.tooltips + - navigation.footer + - navigation.top + - search.highlight + - search.suggest + - navigation.expand + +extra: + # Cross-site URL variables (resolved by macros plugin at build time) + guide_url: https://docs.mat3ra.com/guide + interface_url: https://docs.mat3ra.com/interface + reference_url: https://docs.mat3ra.com/reference + resources_url: https://docs.mat3ra.com/resources + developers_url: https://docs.mat3ra.com/developers + cli_url: https://docs.mat3ra.com/command-line + data_url: https://docs.mat3ra.com/standards + + + + +nav: + - "← All Docs": / + - Home: index-resources.md + +# INFRASTRUCTURE + - General Infrastructure: + - Overview: infrastructure/overview.md + - Storage System: infrastructure/storage.md + - Login Node: + - Overview: infrastructure/login/overview.md + - Directory Structure: infrastructure/login/directories.md + - Clusters: + - Overview: infrastructure/clusters/overview.md + - Directory Structure: infrastructure/clusters/directories.md + - Hardware Specifications: infrastructure/clusters/hardware.md + - Google Clusters: infrastructure/clusters/google.md + - AWS Clusters: infrastructure/clusters/aws.md + - Azure Clusters: infrastructure/clusters/azure.md + - Resource Management: + - Overview: infrastructure/resource/overview.md + - Category: infrastructure/resource/category.md + - Queues: infrastructure/resource/queues.md + - Compute: + - Overview: infrastructure/compute/overview.md + - Parameters: infrastructure/compute/parameters.md + - Data: infrastructure/compute/data.md + +# DATA ON DISK + - Data on Disk: + - Overview: data-on-disk/overview.md + - Directory Structure: data-on-disk/directories.md + - Quotas: data-on-disk/quotas.md + - Security: data-on-disk/security.md + +# DATA IN OBJECT STORAGE — Concepts + - Data in Object Storage: + - Overview: data-in-objectstorage/overview.md + - Files: data-in-objectstorage/files.md + - Security: data-in-objectstorage/security.md + - Dropbox: data-in-objectstorage/dropbox.md diff --git a/mkdocs-standards.yml b/mkdocs-standards.yml new file mode 100644 index 000000000..1ce95dd4c --- /dev/null +++ b/mkdocs-standards.yml @@ -0,0 +1,260 @@ +# Data Standards — JSON schemas, data convention, and structured representations. +# Consolidates all ESSE schema content and data structure documentation. +# Deploy to: docs.mat3ra.com/standards/ + +INHERIT: mkdocs-base.yml + +docs_dir: !!python/object/apply:os.getenv ["DOCS_DIR", "lang/en/docs"] + +# Exclude pages that belong to other sites. +# Only include data-related pages: data/, data-structured/, and +# data.md schema pages from entity/directory sections. +exclude_docs: | + # --- Entire directories belonging to other sites --- + accounts/ + benchmarks/ + cli/ + collaboration/ + data-in-objectstorage/ + data-on-disk/ + getting-started/ + images/accounts/ + images/benchmarks/ + images/cli/ + images/collaboration/ + images/data-in-objectstorage/ + images/getting-started/ + images/infrastructure/ + images/jobs/ + images/jobs-cli/ + images/jobs-designer/ + images/jupyterlite/ + images/materials/ + images/materials-designer/ + images/methods/ + images/models/ + images/notebooks/ + images/properties/ + images/properties-directory/ + images/remote-connection/ + images/rest-api/ + images/software-directory/ + images/tutorials/ + images/ui/ + images/workflow-designer/ + images/workflows/ + infrastructure/ + /jobs-cli/ + jobs-designer/ + jupyterlite/ + materials-designer/ + other/ + pricing/ + properties-directory/ + remote-connection/ + rest-api/ + security/ + site-policy/ + tutorials/ + ui/ + workflow-designer/ + + # --- Entity sections: exclude everything except data.md --- + entities-general/actions/ + entities-general/bank.md + entities-general/default.md + entities-general/lifecycle.md + entities-general/overview.md + entities-general/ownership.md + entities-general/permissions.md + entities-general/sets.md + entities-general/ui/ + + materials/actions/ + materials/bank.md + materials/classification/ + materials/default.md + materials/overview.md + materials/ui/ + + jobs/actions/ + jobs/overview.md + jobs/projects.md + jobs/status.md + jobs/ui/ + + models/accuracy.md + models/auxiliary-concepts/ + models/overview.md + models/parameters.md + + methods/auxiliary-concepts/ + methods/overview.md + methods/parameters.md + methods/precision.md + + software/classification/ + software/components.md + software/overview.md + + workflows/actions/ + workflows/addons/ + workflows/bank.md + workflows/components/ + workflows/default.md + workflows/overview.md + workflows/templating/ + workflows/ui/ + + properties/classification/ + properties/lifecycle/ + properties/overview.md + + # --- Directory sections: exclude everything except data.md --- + models-directory/overview.md + models-directory/dft/accuracy.md + models-directory/dft/notes.md + models-directory/dft/overview.md + models-directory/dft/parameters.md + models-directory/dft/references.md + models-directory/machine-learning/accuracy.md + models-directory/machine-learning/actions.md + models-directory/machine-learning/example-workflow.md + models-directory/machine-learning/overview.md + models-directory/machine-learning/parameters.md + models-directory/machine-learning/units.md + + methods-directory/overview.md + methods-directory/pseudopotential/actions.md + methods-directory/pseudopotential/default.md + methods-directory/pseudopotential/important-settings.md + methods-directory/pseudopotential/overview.md + methods-directory/pseudopotential/parameters.md + methods-directory/pseudopotential/precision.md + methods-directory/linear-regression/overview.md + methods-directory/linear-regression/parameters.md + + # Software directory: exclude everything except data.md files + software-directory/analysis/ + software-directory/development/ + software-directory/overview.md + software-directory/modeling/cp2k/ + software-directory/modeling/deepmd/ + software-directory/modeling/espresso-pw/ + software-directory/modeling/exciting/ + software-directory/modeling/gromacs/ + software-directory/modeling/lammps/ + software-directory/modeling/nwchem/ + software-directory/modeling/turbomole/ + software-directory/modeling/turbomole.md + software-directory/modeling/vasp/overview.md + software-directory/modeling/vasp/components.md + software-directory/modeling/vasp/compute-parameters.md + software-directory/modeling/quantum-espresso/overview.md + software-directory/modeling/quantum-espresso/components.md + software-directory/modeling/quantum-espresso/compute-parameters.md + software-directory/scripting/python/overview.md + software-directory/scripting/python/components.md + software-directory/scripting/shell/overview.md + software-directory/scripting/jupyter-lab/overview.md + software-directory/machine-learning/python-ml/overview.md + software-directory/machine-learning/python-ml/components.md + software-directory/machine-learning/tensorflow.md + + # Other sites' homepages + index.md + index-guide.md + index-interface.md + index-concepts.md + index-dev.md + index-resources.md + index-developers.md + index-cli.md + migrating-to-new-platform.md + +validation: + nav: + omitted_files: info + not_found: warn + links: + absolute_links: info + +site_name: "Data Standards" +site_url: https://docs.mat3ra.com/standards +site_description: "JSON schemas, data convention, and structured data representations for the Mat3ra platform." +dev_addr: "localhost:8007" + +theme: + features: + - announce.dismiss + - content.action.edit + - content.code.annotate + - content.code.copy + - content.tooltips + - navigation.footer + - navigation.top + - search.highlight + - search.suggest + - navigation.expand + +extra: + # Cross-site URL variables (resolved by macros plugin at build time) + guide_url: https://docs.mat3ra.com/guide + interface_url: https://docs.mat3ra.com/interface + reference_url: https://docs.mat3ra.com/reference + resources_url: https://docs.mat3ra.com/resources + developers_url: https://docs.mat3ra.com/developers + cli_url: https://docs.mat3ra.com/command-line + data_url: https://docs.mat3ra.com/standards + + + + +nav: + - "← All Docs": / + - Home: index-standards.md + +# OVERVIEW & CONVENTION + - Overview & Convention: + - Structured Data: data-structured/overview.md + - ESSE Data Convention: data-structured/convention.md + - Data Classification: data/classification.md + - Data Lifecycle: data/lifecycle.md + +# ENTITY SCHEMAS + - Entity Schemas: + - Overview: data/overview.md + - General Entity: entities-general/data.md + - Materials: materials/data.md + - Jobs: jobs/data.md + - Workflows: + - Overview: workflows/data/overview.md + - Workflows: workflows/data/workflows.md + - Subworkflows: workflows/data/subworkflows.md + - Units: workflows/data/units.md + - Models: models/data.md + - Methods: methods/data.md + - Software: software/data.md + +# PROPERTY SCHEMAS + - Property Schemas: + - Overview: properties/data/overview.md + - Core Types: properties/data/core.md + - Full List: properties/data/list.md + - Periodic Table: properties/data/periodic-table.md + +# ENTITY DIRECTORIES + - Entity Directories: + - Models: + - DFT: models-directory/dft/data.md + - Machine Learning: models-directory/machine-learning/data.md + - Methods: + - Pseudopotential: methods-directory/pseudopotential/data.md + - Linear Regression: methods-directory/linear-regression/data.md + - Software: + - VASP: software-directory/modeling/vasp/data.md + - Quantum ESPRESSO: software-directory/modeling/quantum-espresso/data.md + - Python: software-directory/scripting/python/data.md + - Python ML: software-directory/machine-learning/python-ml/data.md + - Shell: software-directory/scripting/shell/data.md + - JupyterLab: software-directory/scripting/jupyter-lab/data.md diff --git a/mkdocs.yml b/mkdocs.yml index 55d5ec961..17e81bb45 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,135 +1,62 @@ +INHERIT: mkdocs-base.yml + # get docs dir from the environment. Defaults to lang/en/docs. docs_dir: !!python/object/apply:os.getenv ["DOCS_DIR", "lang/en/docs"] -site_name: Mat3ra Documentation +exclude_docs: | + index-guide.md + index-interface.md + index-concepts.md + index-dev.md + index-resources.md + index-developers.md + index-cli.md + index-standards.md + # Schema data pages (live in Data Standards sub-site) + entities-general/data.md + materials/data.md + jobs/data.md + models/data.md + methods/data.md + software/data.md + workflows/data/ + properties/data/ + models-directory/dft/data.md + models-directory/machine-learning/data.md + methods-directory/pseudopotential/data.md + methods-directory/linear-regression/data.md + software-directory/modeling/vasp/data.md + software-directory/modeling/quantum-espresso/data.md + software-directory/scripting/python/data.md + software-directory/scripting/shell/data.md + software-directory/scripting/jupyter-lab/data.md + software-directory/machine-learning/python-ml/data.md + +site_name: Documentation site_url: https://docs.mat3ra.com -site_description: Documentation for the users of Mat3ra materials modeling platform. +site_description: Mat3ra platform documentation. dev_addr: "localhost:8000" -repo_name: 'exabyte-io/documentation' -repo_url: 'https://github.com/exabyte-io/documentation' -edit_uri: 'edit/master/lang/en/docs/' -extra_css: - - https://cdnjs.cloudflare.com/ajax/libs/material-design-iconic-font/2.2.0/css/material-design-iconic-font.min.css - - extra/css/general.css - - extra/css/tables.css - - extra/css/images.css - - extra/css/super-fences.css - - extra/css/properties.css - - https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css - -extra_javascript: - - extra/js/giffer.js - - extra/js/ga.js - - extra/js/url_parameters.js - - extra/js/katex.js - - https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js - - https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js - - 'https://www.googletagmanager.com/gtag/js?id=UA-69270713-5' - -copyright: Exabyte Inc. All rights reserved. | Back to platform - extra: - version: "2025.5.29" - preload_javascript: - - /extra/js/preload_hotjar.js - - /extra/js/preload.js - social: - - icon: fontawesome/brands/github - link: https://github.com/exabyte-io - - icon: fontawesome/brands/youtube - link: https://www.youtube.com/c/Mat3ra/videos - - icon: fontawesome/brands/linkedin - link: https://www.linkedin.com/company/mat3ra/ - - icon: fontawesome/brands/x-twitter - link: https://x.com/mat3ra_com - analytics: - provider: google - property: UA-69270713-5 - jupyterlite: - origin_url: https://jupyterlite.mat3ra.com/retro/notebooks - # Ucomment to use lab instead of notebook - # origin_url: https://jupyterlite.mat3ra.com/lab/tree - notebooks_path_root: made - -markdown_extensions: - - admonition - - attr_list - - codehilite: - linenums: true - - def_list - # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/?h=footnotes#footnotes - - footnotes: - PLACE_MARKER: "///FOOTNOTES GO HERE///" - - markdown.extensions.def_list - - md_in_html - - toc: - permalink: true - # https://facelessuser.github.io/pymdown-extensions/ - - pymdownx.arithmatex: # Render Latex Formulas - generic: true - - pymdownx.betterem # Better bold/italic text - - pymdownx.details # Allow admonition-type collapsible
- # https://squidfunk.github.io/mkdocs-material/reference/code-blocks/?h=code+hi#highlighting-inline-code-blocks - - pymdownx.highlight: - pygments_lang_class: true - - pymdownx.snippets - - pymdownx.striphtml # Strip html comments before processing - - pymdownx.superfences # Allow for code blocks "fencing" - - pymdownx.tabbed: - alternate_style: true - -theme: - name: material - custom_dir: theme - palette: - primary: indigo - accent: indigo - logo: "images/logo/logo-white.png" - favicon: "images/logo/favicon.ico" - icon: - edit: material/pencil - repo: fontawesome/brands/github - font: - text: Roboto - code: Roboto Mono - features: - - announce.dismiss - - content.action.edit - - content.code.copy - - content.tooltips - - navigation.footer - - navigation.top - - search.highlight - - search.suggest - -plugins: - # https://timvink.github.io/mkdocs-git-revision-date-localized-plugin/options/ - - git-revision-date-localized: - type: date - enable_creation_date: false - - search - - tags - - macros: - include_dir: "lang/en/docs/includes/" - render_by_default: false - # add header from https://mkdocs-macros-plugin.readthedocs.io/en/stable/rendering/#opt-in-through-the-config-file to enable in the specific markdown - - bibtex: - bib_file: "lang/en/docs/includes/references.bib" - citation_template: "{{author}} ({{year}})" - bibliography_template: "{{author}} ({{year}}). {{title}}. {{journal}}. {{volume}}. {{pages}}." + # Cross-site URL variables (resolved by macros plugin at build time). + # In the legacy build all content is at the root, so these point to root paths. + guide_url: https://docs.mat3ra.com + interface_url: https://docs.mat3ra.com + reference_url: https://docs.mat3ra.com + resources_url: https://docs.mat3ra.com + developers_url: https://docs.mat3ra.com + cli_url: https://docs.mat3ra.com/command-line + data_url: https://docs.mat3ra.com/standards nav: - - Home: index.md + - Home: index.md # INTRODUCTION - Getting Started: - - Content highlights: getting-started/content-highlights.md - - Important Concepts: getting-started/important-concepts.md - - Terminology: getting-started/terminology.md - - Useful Links: getting-started/useful-links.md - - Frequently Asked Questions: other/faq.md - - Run first simulation: + - First Steps: getting-started/first-steps.md + - Content Highlights: getting-started/content-highlights.md + - Key Concepts: getting-started/concepts.md + - Running First Simulations: - Web Interface: getting-started/run-first-simulation/web-interface.md - Command Line: getting-started/run-first-simulation/cli-job.md @@ -161,9 +88,6 @@ nav: - Machine Learning (ML): # Differentiate between Legacy and PythonML tutorials in Overview - Overview: tutorials/ml/overview.md - - ExabyteML (legacy): - - Train ML Model: tutorials/ml/train-ml-model.md - - Predict New Properties: tutorials/ml/predict-ml-properties.md - Python ML: - Training a Regression Model: tutorials/python-ml/train-regression-model.md #Todo: Tutorial demonstrates how to share a trained model with another user @@ -173,6 +97,7 @@ nav: - Training a Classifier: tutorials/python-ml/train-classification-model.md - Predicting with a Classifier: tutorials/python-ml/predict-with-classification.md - DeePMD (molecular dynamics): tutorials/ml/deepmd-mlff-with-espresso-cp-and-lammps.md + - Python MLFF (MatterSim): tutorials/ml/run-mlff-python-workflows-mattersim.md - Density Functional Theory: - Electronic Properties: - Overview: tutorials/dft/electronic/overview.md @@ -201,6 +126,9 @@ nav: - Phonons on Grid: tutorials/dft/vibrational/phonons-grid.md - Thermodynamic Prop.: - Surface Energy: tutorials/dft/thermodynamic/surface-energy.md + - Interfacial Energy: tutorials/dft/thermodynamic/interfacial-energy.md + - Formation Energy: tutorials/dft/thermodynamic/formation-energy.md + - Defect Formation Energy: tutorials/dft/thermodynamic/defect-formation-energy.md - Chemical Prop.: - Reaction Energy Profile (QE): tutorials/dft/chemical/reaction-profile-qe.md - Reaction Energy Profile (VASP): tutorials/dft/chemical/reaction-profile-vasp.md @@ -211,7 +139,6 @@ nav: - Accessing the Platform: tutorials/platform-access.md - Jupyter Notebook: tutorials/other/jupyter.md - Restart from Previous Job: tutorials/other/restart-job.md - - Upload External Job Data: tutorials/other/external-upload.md - TensorFlow (GPU): tutorials/general-functionality/tensorflow-gpu.md - Materials: - Overview: tutorials/materials/overview.md @@ -226,6 +153,7 @@ nav: - Reproducing Specific Manuscripts: - Overview: tutorials/materials/specific/overview.md - Substitutional Point Defects in Graphene: tutorials/materials/specific/defect-point-substitution-graphene.md + - Substitutional Point Defects in Graphene (Band Structure): tutorials/materials/specific/defect-point-substitution-graphene-simulation.md - Vacancy-Substitution Pair Defects in GaN: tutorials/materials/specific/defect-point-pair-gallium-nitride.md - Vacancy Point Defect in h-BN: tutorials/materials/specific/defect-point-vacancy-boron-nitride.md - Interstitial Point Defect in SnO: tutorials/materials/specific/defect-point-interstitial-tin-oxide.md @@ -233,6 +161,7 @@ nav: - Step Surface Defect on Pt(111): tutorials/materials/specific/defect-surface-step-platinum.md - Twisted Bilayer h-BN nanoribbons: tutorials/materials/specific/interface-bilayer-twisted-nanoribbons-boron-nitride.md - Twisted Bilayer MoS2 commensurate lattices: tutorials/materials/specific/interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide.md + - Twisted Bilayer MoS2 commensurate lattices (Band Structure): tutorials/materials/specific/interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide-simulation.md - Adatom Surface Defects on Graphene: tutorials/materials/specific/defect-surface-adatom-graphene.md - H-Passivated Silicon Nanowire: tutorials/materials/specific/passivation-edge-nanowire-silicon.md - H-Passivated Silicon (100) Surface: tutorials/materials/specific/passivation-surface-silicon.md @@ -253,7 +182,7 @@ nav: - Overview: ui/overview.md - Header and Footer: ui/header-footer.md - Left-hand Sidebar: ui/left-sidebar.md - - Right-hand Sidebar: ui/right-sidebar.md + - Account Menu: ui/account-menu.md - Support: ui/support.md - Specific: - Homepage Navigation: ui/specific/homepage.md @@ -306,7 +235,7 @@ nav: - People Explorer: collaboration/ui/people-explorer.md - Entity Sharing: - User Interface: collaboration/sharing/ui.md - - Actions: collaboration/sharing/common-actions.md + - Actions: collaboration/sharing/actions.md - Account Access Levels: collaboration/sharing/access-levels.md - Actions: - Organization > Overview: collaboration/actions/organization/overview.md @@ -325,7 +254,7 @@ nav: - Models: - Overview: models/overview.md - Accuracy: models/accuracy.md - - Data: models/data.md + - Parameters: models/parameters.md - Auxiliary Concepts: - Nudged Elastic Band: models/auxiliary-concepts/nudged-elastic-band.md @@ -340,7 +269,7 @@ nav: - Overview: models-directory/overview.md - Density Functional Theory: - Overview: models-directory/dft/overview.md - - Data: models-directory/dft/data.md + - Parameters: models-directory/dft/parameters.md - Accuracy: models-directory/dft/accuracy.md - Special Notes: models-directory/dft/notes.md @@ -349,13 +278,13 @@ nav: - Overview: models-directory/machine-learning/overview.md - Parameters: models-directory/machine-learning/parameters.md - Units: models-directory/machine-learning/units.md - - Data: models-directory/machine-learning/data.md + - Example Workflow: models-directory/machine-learning/example-workflow.md - Accuracy: models-directory/machine-learning/accuracy.md - Methods: - Overview: methods/overview.md - - Data: methods/data.md + - Parameters: methods/parameters.md - Precision: methods/precision.md - Auxiliary Concepts: @@ -366,20 +295,20 @@ nav: - Plane-waves and Pseudopotentials: - Overview: methods-directory/pseudopotential/overview.md - Default: methods-directory/pseudopotential/default.md - - Data: methods-directory/pseudopotential/data.md + - Parameters: methods-directory/pseudopotential/parameters.md - Precision: methods-directory/pseudopotential/precision.md - Important Settings: methods-directory/pseudopotential/important-settings.md - - Actions: methods-directory/pseudopotential/common-actions.md + - Actions: methods-directory/pseudopotential/actions.md - Linear Regression: - Overview: methods-directory/linear-regression/overview.md - Parameters: methods-directory/linear-regression/parameters.md - - Data: methods-directory/linear-regression/data.md + - Software: - Overview: software/overview.md - Components: software/components.md - - Data: software/data.md + - Classification: - Overview: software/classification/overview.md - Analysis: software/classification/analysis.md @@ -395,12 +324,12 @@ nav: - Quantum ESPRESSO: - Overview: software-directory/modeling/quantum-espresso/overview.md - Components: software-directory/modeling/quantum-espresso/components.md - - Data: software-directory/modeling/quantum-espresso/data.md + - Compute Parameters: software-directory/modeling/quantum-espresso/compute-parameters.md - VASP: - Overview: software-directory/modeling/vasp/overview.md - Components: software-directory/modeling/vasp/components.md - - Data: software-directory/modeling/vasp/data.md + - Compute Parameters: software-directory/modeling/vasp/compute-parameters.md - TurboMole: software-directory/modeling/turbomole.md - LAMMPS: software-directory/modeling/lammps.md @@ -411,23 +340,21 @@ nav: - Scripting: - Shell: - Overview: software-directory/scripting/shell/overview.md - - Data: software-directory/scripting/shell/data.md + - Python: - Overview: software-directory/scripting/python/overview.md - - Data: software-directory/scripting/python/data.md + - Jupyter Lab: - Overview: software-directory/scripting/jupyter-lab/overview.md - - Data: software-directory/scripting/jupyter-lab/data.md + - Machine Learning (ML): - TensorFlow: software-directory/machine-learning/tensorflow.md - - Exabyte ML: - - Overview: software-directory/machine-learning/exabyte/overview.md - - Data: software-directory/machine-learning/exabyte/data.md + - Python ML: - Overview: software-directory/machine-learning/python-ml/overview.md - Components: software-directory/machine-learning/python-ml/components.md - Workflow Structure: software-directory/machine-learning/python-ml/workflow-structure.md - - Data: software-directory/machine-learning/python-ml/data.md + - Analysis & Visualization: - VESTA: software-directory/analysis/vesta.md - XCRYSDEN: software-directory/analysis/xcrysden.md @@ -445,7 +372,7 @@ nav: - Lifecycle: entities-general/lifecycle.md - Ownership: entities-general/ownership.md - Permissions: entities-general/permissions.md - - Data: entities-general/data.md + - Sets: entities-general/sets.md - Bank: entities-general/bank.md - Default: entities-general/default.md @@ -476,7 +403,7 @@ nav: # ENTITIES - SPECIFIC - Materials: - Overview: materials/overview.md - - Data: materials/data.md + - Bank: materials/bank.md - Default: materials/default.md - Classification: @@ -541,11 +468,7 @@ nav: - Subworkflows: workflows/components/subworkflows.md - Units: workflows/components/units.md - Maps: workflows/components/maps.md - - Data: - - Overview: workflows/data/overview.md - - Workflows: workflows/data/workflows.md - - Subworkflows: workflows/data/subworkflows.md - - Units: workflows/data/units.md + - Templating: - Overview: workflows/templating/overview.md - Concept: workflows/templating/concept.md @@ -592,7 +515,7 @@ nav: - Jobs: - Overview: jobs/overview.md - Projects: jobs/projects.md - - Data: jobs/data.md + - Status: jobs/status.md - User Interface: - Explorer: jobs/ui/explorer.md @@ -631,6 +554,7 @@ nav: - General Structure: jobs-cli/batch-scripts/general-structure.md - Directives: jobs-cli/batch-scripts/directives.md - Working Directory: jobs-cli/batch-scripts/directories.md + - Apptainer & Environment Modules: jobs-cli/batch-scripts/apptainer.md - Sample Scripts: jobs-cli/batch-scripts/sample-scripts.md - Actions: - Overview: jobs-cli/actions/overview.md @@ -641,16 +565,6 @@ nav: - View Jobs List: jobs-cli/actions/view-job-list.md - - External Uploads: - - Overview: external/overview.md - - Status: external/status.md - - User Interface: - - Explorer: external/ui/explorer.md - - Actions: - - Overview: external/actions/overview.md - - Create: external/actions/create.md - - - Properties: - Overview: properties/overview.md - Lifecycle: @@ -658,11 +572,7 @@ nav: - Extractors: properties/lifecycle/extractor.md - Refinement: properties/lifecycle/refinement.md - Retrieval: properties/lifecycle/retrieval.md - - Data: - - Overview: properties/data/overview.md - - Core: properties/data/core.md - - List of Schemas: properties/data/list.md - - Periodic Table: properties/data/periodic-table.md + - Classification: - Overview: properties/classification/overview.md - General: properties/classification/general.md @@ -678,8 +588,7 @@ nav: - Scalar: - Total Energy: properties-directory/scalar/total-energy.md - Fermi Energy: properties-directory/scalar/fermi-energy.md -# TODO: re-enable when implemented -# - Formation Energy: properties-directory/scalar/formation-energy.md + - Formation Energy: properties-directory/scalar/formation-energy.md - Surface Energy: properties-directory/scalar/surface-energy.md - Zero Point Energy: properties-directory/scalar/zero-point-energy.md - Pressure: properties-directory/scalar/pressure.md @@ -724,6 +633,7 @@ nav: - Hardware Specifications: infrastructure/clusters/hardware.md - AWS Clusters: infrastructure/clusters/aws.md - Azure Clusters: infrastructure/clusters/azure.md + - Google Clusters: infrastructure/clusters/google.md - Resource Management: - Overview: infrastructure/resource/overview.md - Category: infrastructure/resource/category.md @@ -792,7 +702,7 @@ nav: - Accounting: cli/accounting.md - Actions: - Overview: cli/actions/overview.md - - Load / Unload Modules: cli/actions/modules-common-actions.md + - Load / Unload Modules: cli/actions/modules-actions.md - Customize Environment: cli/actions/customize.md - Add new software: cli/actions/add-software.md - Create Python Environment: cli/actions/create-python-env.md @@ -803,6 +713,7 @@ nav: - JupyterLite Environment: - Overview: jupyterlite/overview.md - Accessing JupyterLite: jupyterlite/accessing-jupyterlite.md + - Authentication: jupyterlite/authentication.md - Pyodide: jupyterlite/pyodide.md - Dependencies and Imports: jupyterlite/dependencies-installation.md - Data Exchange: jupyterlite/data-exchange.md @@ -814,8 +725,9 @@ nav: - Authentication: rest-api/authentication.md - Query structure: rest-api/query-structure.md - Endpoints: rest-api/endpoints.md - - Exabyte API client: rest-api/api-client.md - - Exabyte API examples: rest-api/api-examples.md + - API Explorer: rest-api/api-explorer.md + - API client: rest-api/api-client.md + - API examples: rest-api/api-examples.md # TODO: refactor/re-implement and re-enable @@ -837,7 +749,6 @@ nav: - Community Programs: other/community-programs.md - Terms of Service: other/terms-of-service.md # duplicate through link - Restricted Content: other/restricted.md - - Account Registration: other/registration.md - Benchmarks: - Overview: benchmarks/overview.md diff --git a/netlify.toml b/netlify.toml index b74e2fd9c..5fffc8006 100644 --- a/netlify.toml +++ b/netlify.toml @@ -4,4 +4,3 @@ [build.environment] PYTHON_VERSION = "3.10" - NODE_VERSION = "20" diff --git a/plans/README.md b/plans/README.md new file mode 100644 index 000000000..9075f9160 --- /dev/null +++ b/plans/README.md @@ -0,0 +1,38 @@ +# Plans + +Internal planning documents for work on this repository. These are **not part of +the published documentation site** — the MkDocs builds only read `lang/en/docs/`, +so nothing here appears on docs.mat3ra.com. + +| Document | Scope | Status | +| --- | --- | --- | +| [`docs-agent-rag.md`](docs-agent-rag.md) | The documentation agent: retrieval-augmented generation over this repository's content. Strategy, corpus analysis, evaluation approach. | Active — Phase 0 of its content is built | +| [`docs-agent-web-delivery.md`](docs-agent-web-delivery.md) | Delivering that agent as a browser-based chat: architecture, hosting, repository layout, deployment. | Active — guides Phase 2 | +| [`docs-agent-implementation.md`](docs-agent-implementation.md) | Execution plan tying the others together: phases, milestones, file-level work items, acceptance criteria, decision register. | Active — the progression tracker (§3) | +| [`docs-agent-platform-actions.md`](docs-agent-platform-actions.md) | Letting the agent execute actions in the user's platform session: test-framework step reuse (Cypress/TeDe), in-page execution, safety model. | Proposed — needs sign-off + security review | + +## Lifecycle + +Documents and work progress separately: + +- **Documents** carry a status — `Draft` (structure still moving), `Active` + (agreed direction, guiding work), `Proposed` (needs sign-off before build), + `Superseded` (kept for history) — and never move between folders, so + cross-links stay stable and Git records the history. +- **Work** progresses by phase and milestone in the + [implementation plan](docs-agent-implementation.md) §3 — the single + tracker. A completed phase or milestone gets its State cell updated with + the date and pull request. +- **Reviews are gates, not a folder:** open sign-offs live in the decision + register (D2, D3, D7, D8), and Phase 5 additionally requires a security + review before build. + +The documents share one phase numbering (Phases 0–5), defined in the +[implementation plan](docs-agent-implementation.md) §3, and one vocabulary: +**the platform** is platform.mat3ra.com, whose repository is `web-app`; +**web delivery** is the browser chat for the documentation site. + +The working implementation lives in the +[`documentation-agent`](https://github.com/mat3ra/documentation-agent) +repository (decision D6). The superseded Phase-0 prototype is still in +[`scripts/rag/`](../scripts/rag/) until that work is pushed. diff --git a/plans/docs-agent-implementation.md b/plans/docs-agent-implementation.md new file mode 100644 index 000000000..124c553ea --- /dev/null +++ b/plans/docs-agent-implementation.md @@ -0,0 +1,514 @@ +# Documentation Agent — Implementation Plan + +Execution plan for shipping the documentation assistant on docs.mat3ra.com. +The companion documents hold the reasoning; this one holds the work: milestones, +file-level work items, acceptance criteria, and the decisions still open. + +- **Status:** Active, living document — §3 is the initiative's progression + tracker. M1–M5 are done: the agent is deployed and answering on Cloud Run. + Only the launch gate (M6) stands between here and a public beta. +- **Last updated:** 2026-07-31 +- **Companion plans:** [`docs-agent-rag.md`](docs-agent-rag.md) (retrieval and + evaluation strategy), [`docs-agent-web-delivery.md`](docs-agent-web-delivery.md) + (architecture and hosting rationale) + +--- + +## 1. Scope and definition of done + +Shipped means: an "Ask AI" launcher on every page of every documentation site +(eight as of 2026-07-31 — see M4) opens a chat that streams grounded, cited +answers from a production service, with abuse limits, spend controls, and an +evaluation gate in CI. + +Out of scope for v1: hybrid/vector retrieval beyond an eval-gated upgrade +(M7), the in-platform "Ask AI" surface (specified in M8, scheduled +post-launch), and platform-action tools (specified in +[`docs-agent-platform-actions.md`](docs-agent-platform-actions.md), +sequenced after M8). + +## 2. Decision register + +Defaults follow the companion plans. Items marked **needs sign-off** block a +later milestone but nothing before it. + +| # | Decision | Default | Status | +| --- | --- | --- | --- | +| D1 | Runtime | Cloud Run, same project as Vertex access ([web delivery plan §5](docs-agent-web-delivery.md), Option A) | Adopted | +| D2 | Service code location | Private repository [`mat3ra/documentation-agent`](https://github.com/mat3ra/documentation-agent), pinned into the platform stack later if wanted | **Adopted** — repository created 2026-07-31 | +| D3 | Google Cloud project | Dedicated project `mat3ra-documentation` with spend controls per M5.1 | **Done 2026-07-31** — project, budget and native spend cap in place; Vertex AI enabled and confirmed end to end from Cloud Run. Claude Model Garden enablement is still outstanding and blocks only the D5 comparison | +| D4 | Public endpoint | Default `*.run.app` URL for beta; a `mat3ra.com` subdomain before general availability | Beta default adopted | +| D5 | Model | Provider abstraction over Vertex: **Gemini by default** (`gemini-3.6-flash`, `global`), Claude (`claude-opus-4-6`, `us-east5`) behind the same interface once Model Garden is enabled. Tier changes only through the evaluation harness | **Revised 2026-07-31** — Gemini needs no Model Garden step, so it unblocks work today; the abstraction keeps the choice reversible | +| D6 | Core package location | The agent core (ingestion, retrieval, prompt, loop) lives in the **`documentation-agent` repository**; this repository provides the corpus only. Ingestion reads a documentation checkout via `--docs-root` | **Revised 2026-07-31** — supersedes the earlier "core stays in `scripts/rag/`" split; one repository owns all agent code, so there is no cross-repository package dependency to keep in step | +| D7 | Logging and retention | Store question, tool trace, answer, and token counts for 30 days to seed the golden set; no IP addresses joined to content; disclosed in the widget footer | Needs sign-off before launch | +| D8 | Launch quality bar | Regression gate set just below the measured BM25 baseline: **recall@5 ≥ 0.65, MRR ≥ 0.50** (baseline 0.688 / 0.543), plus zero hallucinated URLs. Refusal on the unanswerable subset must be **1.00** | **Met with replication 2026-08-01**: refusal 1.00 in four consecutive runs; faithfulness 1.00 in both runs after the judge was corrected to see exactly what the model saw (earlier 0.892 figures were the judge's truncated view, not the agent); zero hallucinated URLs in every run ever made | + +## 3. Phases and workstreams + +The initiative numbering, shared by all four plans (this table is the +authority): + +| Phase | Name | Contents | State | +| --- | --- | --- | --- | +| 0 | Prototypes | BM25 demo in `scripts/rag/`; desktop automation experiment in the platform repository ([`web-app#2894`](https://github.com/mat3ra/web-app/pull/2894)) | **Done** | +| 1 | Foundations | M1 core package, M2 evaluation harness | **Done 2026-07-31** | +| 2 | Docs launch | M3 service, M4 widget, M5 deployment, M6 hardening | In progress — M3–M5 done 2026-07-31; M6 (launch gate) remains | +| 3 | Retrieval quality | M7 upgrades, evaluation-gated | Planned, post-launch | +| 4 | Platform embed | M8, stages M8.1–M8.3 | Planned, post-launch | +| 5 | Platform actions | Stages A1–A4 in [`docs-agent-platform-actions.md`](docs-agent-platform-actions.md) | Proposed | + +Phases 3 and 4 are independent and can interleave; Phase 5 requires M8.2. + +This table (with the milestone table below) is the progression tracker: when +a phase or milestone completes, its State cell gains the date and pull +request. Documents keep their status in place — nothing moves to a +"complete" folder. + +Within Phases 1–2, two tracks run interleaved — delivery (M1, M3–M6) and +quality (M2) — reconciled as: **delivery does not wait for the full +evaluation harness, but launch does.** Retrieval-metric evaluation (cheap, +no model calls) lands before any retrieval change; the answer-quality gate +must pass before M6. + +| Milestone | Phase | Track | Estimate | +| --- | --- | --- | --- | +| M1 Shared core package | 1 | Delivery | **Done 2026-07-31** | +| M2 Evaluation harness + golden set | 1 | Quality | **Done 2026-07-31** | +| M3 Backend service | 2 | Delivery | **Done 2026-07-31** | +| M4 Documentation widget | 2 | Delivery | **Done 2026-08-01** | +| M5 Deployment + index pipeline | 2 | Delivery | **Done 2026-07-31** | +| M6 Launch hardening | 2 | Both | 1–2 days | +| M7 Retrieval upgrades | 3 | Quality | 1–2 weeks | +| M8 In-platform surface | 4 | Delivery | ~1 week, staged | + +Dependencies: M1 → M2 and M3; M3 → M4 (the widget develops against a local +service); M5 can start alongside M4; M6 needs M2, M4, M5; M8 follows M6 and +leans on M4's embeddable-module constraint; stages A1–A4 (Phase 5) follow +M8.2. Elapsed time to a public beta (end of Phase 2): roughly two to three +weeks of focused work. + +--- + +## 4. Milestones + +### M1. Shared core package — **done 2026-07-31** + +The demo became the installable package the service will import, per +[web delivery plan §3.1](docs-agent-web-delivery.md) ("refactor first"), in +the `documentation-agent` repository (D6): + +``` +pyproject.toml # mat3ra-docs-agent; [anthropic] and [dev] extras +mat3ra_docs_agent/ + config.py # environment-driven settings + ingest.py # chunker; --docs-root points at a docs checkout + retriever.py # Retriever, tokenize, format_results + prompt.py # SYSTEM_PROMPT, SEARCH_TOOL + providers/ # base, gemini_vertex, anthropic_vertex + loop.py # run_turn, provider-agnostic + cli.py # docs-agent, docs-agent-ingest +tests/ # 42 tests, offline +.github/workflows/tests.yml # pytest on 3.10 and 3.12 +``` + +Beyond the original scope, the model backend was abstracted (D5): `Provider` +exposes `add_user_message` / `add_tool_results` / `generate` over neutral +types, each adapter holding the conversation in its own native format. The +loop never sees a vendor dialect, which is what makes the Gemini-now, +Claude-later switch a one-line change. + +Verified: 42 offline tests pass; ingestion reproduces the demo exactly (534 +pages → 2,554 chunks); a live query on Gemini returns the same two-method +POSCAR answer with the same citations as the original demo. + +Two findings worth carrying forward: + +- **BM25 needs a realistic corpus.** Inverse document frequency is + meaningless over one document — scores go non-positive and the relevance + filter drops everything. Test fixtures use several pages; the M2 harness + must not evaluate against toy corpora. +- **Gemini 3.x spends thinking tokens before emitting a tool call.** A small + output budget starves the call and produces an empty turn, so + `MAX_OUTPUT_TOKENS` is 8192. + +### M2. Evaluation harness and golden set — **done 2026-07-31** + +The tuning loop from [RAG plan §5](docs-agent-rag.md), in the +`documentation-agent` repository under `eval/`: `golden.yaml`, a free +retrieval harness, a paid answer harness, and a README carrying the +baseline. + +The golden set holds 37 questions — 32 answerable and 5 the documentation +deliberately cannot answer, scored separately, because an assistant that +scores well elsewhere and improvises on those is worse than useless. +Questions are phrased as a user would ask them rather than as the pages are +written. Expected pages are validated against the index before every run, so +a renamed page fails the run instead of quietly depressing the metrics. + +**Recorded BM25 baseline** (32 answerable questions, 534 pages / 2,554 +chunks): + +| recall@1 | recall@3 | recall@5 | recall@10 | MRR | +| --- | --- | --- | --- | --- | +| 0.406 | 0.594 | 0.688 | 0.906 | 0.543 | + +For about a third of questions the top hit is already right; for about a +third the right page is not in the top five. The failures are precisely the +paraphrase weakness §4.3 predicted — "How does authentication work for the +REST API?" ranks the *JupyterLite* authentication page first — which is the +concrete case hybrid retrieval (M7) has to beat. + +Two things this measurement establishes: + +- **The numbers are a lower bound on the agent, not a verdict on it.** The + agent reformulates and re-searches, so a page at rank 8 for the user's + original phrasing is often still cited correctly — verified on the REST API + question. Retrieval recall is a leading indicator. +- **Answer evaluation separates the deterministic from the judged.** Every + cited URL must exist in the corpus; that check cannot itself hallucinate, + so it is reported on its own and any failure fails the run, independent of + a judge's opinion. + +CI gates every pull request on the retrieval metrics at the D8 thresholds; +the answer harness runs on demand (no Batch API on Vertex) and is where the +Gemini/Claude and model-tier comparison gets settled (D5). + +**The answer baseline found two real defects on its first run**, neither +visible from spot-checking, and both now the immediate tuning work: + +| Hallucinated URLs | Cited an expected page | Faithful | Citations support | Completeness | Refused correctly | +| --- | --- | --- | --- | --- | --- | +| 0 | 0.906 | 0.892 | 0.973 | 0.959 | **0.800** | + +- **Refusal, 4 of 5.** Asked whether the platform is faster than VASP on a + 64 GB laptop, the agent answered that it is "significantly faster", + justified with real hardware specifications. The specifications are + documented; the comparative claim is not and cannot be. The dangerous + shape is a question *adjacent* to documented material, where retrieval + returns something plausible and the model completes the argument itself — + which no amount of retrieval improvement fixes. +- **Faithfulness 0.892.** Four answers invented interface details (a + dropdown, a submit button, walltime advice). No URL was ever invented, so + half the grounding rule holds and the half covering UI element names does + not. + +Both are prompt problems, not retrieval problems, and the harness now makes +the fix measurable rather than a matter of opinion. This is the tuning loop +working as designed: §8 listed hallucinated UI paths as a risk to be +"verified by the evaluation judge rather than assumed", and it now has been. + +### M3. Backend service (`documentation-agent` repository, D2) + +FastAPI wrapper around the core package, per [web delivery plan §3.1](docs-agent-web-delivery.md). + +Work items: + +1. Repository skeleton: `app/main.py`, `Dockerfile`, `README.md`, CI. +2. `POST /chat` — request: message history (client-held, no server session + store); response: server-sent events — `text` deltas, `status` events + while a search runs ("Searching documentation…"), one final `sources` + event, then `done`. +3. Streaming tool loop: add a `run_turn_streaming` generator to + `mat3ra_docs_agent.loop`, and a `stream()` method on `Provider` + implemented by both adapters, so the CLI and service share one loop. +4. `GET /health` for the runtime probe. +5. Guards, all request-tested: CORS allowlist (`https://docs.mat3ra.com`, + localhost origins for development), per-IP token-bucket rate limit + (in-process is acceptable at beta scale; note it resets on scale-to-zero), + caps on message count and body size per request, the existing 8-iteration + tool bound, and a per-conversation output-token ceiling. +6. Structured request logs per D7: latency, tool calls, token usage, stop + reason — the observability list from [web delivery plan §6](docs-agent-web-delivery.md). + +Acceptance: `docker run` locally with ADC answers a question end-to-end with +visible streaming; a scripted client verifies each guard (rejected origin, +rate-limit 429, oversized body 413). + +### M4. Documentation widget — **done 2026-08-01** + +Live on the deploy preview and covered by 17 Playwright tests +(`tests/widget/`) that run in CI in under three seconds without cloud access +or a model call — the widget is real, only the service is faked at the +network boundary. + +Four things the first real use taught, each now a test: + +- **Citations must be clickable and same-tab.** The model lists sources as + bare URLs, which the renderer did not recognise, so every citation arrived + as dead text. +- **Emphasised product terms should link**, from a glossary the service + derives from its own index — never from the model. Terms that more than one + page claims are dropped: a confident link to the wrong product's page is + worse than bold text. +- **Citations must stay on the build being read.** The corpus stores + canonical production URLs, so following one from a preview left the preview + — and the conversation with it, storage being per-origin. +- **The conversation has to outlive the page.** Once links open in place, + every citation ended the exchange that produced it. It is now stored, + bounded and expiring, with "New chat" to end it. + +The remaining scope note stands: the site count has grown past the four in +`AGENTS.md` — CI now builds eight (adding Interface, +Resources, Developers, Command Line, Standards), so verify the widget against +the workflow's list rather than a remembered number. + +Work items: + +1. New assets, self-hosted (no CDN): + + ``` + lang/en/docs/extra/js/docs-agent.js # launcher, panel, SSE client, renderer + lang/en/docs/extra/css/docs-agent.css + lang/en/docs/extra/js/vendor/ # marked + DOMPurify, pinned versions + ``` + + `docs-agent.js` is written as a framework-free embeddable module — + `DocsAgent.mount(element, {endpoint, tokenProvider})`, themed through CSS + custom properties, no MkDocs assumptions — so the platform surface (M8) + reuses it through a thin wrapper rather than a rewrite. + +2. Wire into `mkdocs-base.yml` (`extra_javascript`, `extra_css`). All four + site configs `INHERIT` the base, so this is a single edit — verify each + built site picks it up rather than editing four files. +3. Behaviour: floating "Ask AI" launcher; panel with conversation held in + memory only; streamed Markdown rendered incrementally and sanitised + (DOMPurify) — model output is never injected as raw HTML; searching + indicator driven by `status` events; `sources` rendered as links; footer + with the D7 disclosure and an escalation link to support. +4. Endpoint constant in `docs-agent.js` (D4 URL), with a `localStorage` + override for local development against `localhost`. If the endpoint is + unreachable or CORS-blocked (e.g. Netlify deploy previews), the launcher + hides — the widget must never break a documentation page. +5. Keyboard and mobile pass: focus trap in the panel, Escape closes, + usable at phone widths. + +Acceptance: `./scripts/serve-all.sh` + local service answers with citations +from any page of all four sites; `scripts/links/check-links.py` still passes; +widget absent-but-silent when the service is down; the module also mounts in +a bare HTML page with a single `mount()` call (the M8 embeddability check). + +### M5. Deployment and index pipeline — **done 2026-07-31** + +Live at `https://docs-agent-mmrcocqy3a-uc.a.run.app` (D4: the default Cloud +Run hostname for the beta). The Cloud Run choice paid off exactly where §5 +said it would — the attached service account supplies Vertex credentials, so +the pasted access token that development needed is not managed, it is gone. + +Two identities, deliberately separate: the runtime holds only Vertex access, +and the deploy identity may act as it without inheriting anything from it. +CI authenticates through Workload Identity Federation, so no service-account +key exists in either place. + +A revision deploys with **no traffic** behind a `candidate` tag, is +smoke-tested on its own URL for health and one real end-to-end question, and +only then takes traffic. A broken revision never gets the chance to serve. + +Verified against the deployed service, not locally: health reports the +documentation commit its index was built from; an anonymous request streams a +grounded answer; the CORS allowlist admits the documentation origin and +refuses another; an oversized body is rejected; and the rollback drill ran end +to end — promote, roll back to the previous revision, roll forward — with the +traffic split confirmed at each step. + +Three things worth carrying forward: + +- **`git clone --branch` cannot take a commit SHA.** Pinning the index to a + documentation commit failed outright until the build was changed to fetch + the ref and check out `FETCH_HEAD`. Pinning is the whole point of the + artifact, so this would have silently degraded to "whatever `main` was". +- **`builds submit --tag` cannot pass a build argument**, which the pinned + build needs; an explicit build config replaces it. +- **A brand-new project needs a moment.** The first `run deploy --source` + failed with a bare permission error that resolved itself once the freshly + created Artifact Registry repository and its permissions had propagated — + worth knowing before chasing an org policy that is not the cause. + +The original plan for this milestone follows, for the reasoning behind the +shape above. + +Cloud Run runtime plus the two decoupled triggers from +[web delivery plan §5.1](docs-agent-web-delivery.md). + +Work items: + +1. One-time cloud setup (D3): runtime service account with Vertex model + access and read access to the index bucket, nothing else; Workload + Identity Federation for both repositories' GitHub Actions — no key files + anywhere; budget on the project — **done 2026-07-31**: $100/month, + alerts at 50/80/100%, and the console's native spend cap (pauses + services on breach) configured. Costs are recorded with up to ~24 hours + of lag, so the cap is a backstop, not burst protection: Cloud Run + `--max-instances` times the per-request token caps (M3.5) still bounds + the worst-case burn rate, and Vertex per-model quotas can be lowered as + a second bound. +2. Documentation trigger — small workflow in this repository: on push to + `main` touching `lang/en/docs/**`, fire a `repository_dispatch` carrying + the documentation SHA. It runs no ingestion; under D6 all agent logic + lives in the service repository. +3. Service pipeline (service repository): on dispatch or own-repo push, + check out the documentation at that SHA, ingest, build the image + **baking in** the resulting index and the documentation SHA, deploy to a + staging revision, smoke-test (`/health` plus one golden question), then + promote. Rollback = redeploy the previous image, which carries its own + index. +4. Runtime settings: scale-to-zero, small instance, concurrency tuned for + SSE; request timeout above the slowest multi-search answer observed. + +Acceptance: a trivial documentation edit on `main` propagates to a redeployed +service without manual steps; rollback drill performed once; spend alert +fires on a test threshold. + +### M6. Launch hardening + +Gate on all of: D7 signed off, D8 thresholds met on the golden set +(including ≥ 90% correct behaviour on the unanswerable subset), M3 guard +tests green, M5 rollback drill done. + +Work items: + +1. Decide and publish the privacy note (widget footer; optionally a short + documentation page — which adds a `mkdocs.yml` nav entry in the same + change, per repository convention). +2. Re-run the full answer-quality evaluation against the production + endpoint, not just locally. +3. Enable the widget on production by shipping the `mkdocs-base.yml` change + (until then, the widget branch stays unmerged — the docs deploy on push + to `main` via `s3-deploy.yml`, so merging is launching). +4. Soft launch: announce internally, watch logs and spend for a week, then + announce publicly. + +### M7. Post-launch retrieval upgrades (quality track) + +In the order and for the reasons given in [RAG plan §4.3](docs-agent-rag.md), +every step gated on the M2 harness: inline `--8<--` ESSE includes; contextual +retrieval; embeddings + hybrid search (behind the same `Retriever.search` +interface — no service change); `get_page` tool; reranking only if the +numbers justify it; model-tier comparison for cost (D5). + +### M8. In-platform surface (platform.mat3ra.com) + +The second surface from [web delivery plan §2.2](docs-agent-web-delivery.md). The platform +reuses the deployed service and the embeddable widget; retrieval, the agent +loop, and model credentials never enter the platform application (rejected in +[web delivery plan §2.1](docs-agent-web-delivery.md)). + +Reuse boundaries: + +- **Backend — reused as deployed.** The platform calls the same service and + `/chat` contract; there is no second deployment and nothing is ported to + Node. The browser talks to the service directly — the platform never + proxies the SSE stream (Meteor methods are RPC; the streaming mismatch was + §2.1's decisive row). Service change: the platform origin joins the CORS + allowlist. +- **Frontend — reused as a module.** A thin React wrapper (a ref plus + `DocsAgent.mount()`, ~20 lines) hosts the M4 widget inside the platform + shell. The service serves its own built copy of the bundle + (`GET /widget.js`, copied from this repository during the M5 image build), + so the client the platform loads is version-locked to the API it calls; a + pinned vendored copy in the platform repository is the fallback if loading + a service-hosted script is unwanted there. +- **Deliberately not reused:** no Vertex credentials in the platform, and no + platform-action tools in M8 itself — those are specified in + [`docs-agent-platform-actions.md`](docs-agent-platform-actions.md) behind + their own security review. + +Stages, each independently shippable: + +1. **M8.1 — anonymous embed (1–2 days, platform repository).** A + feature-flagged launcher mounts the widget against the production + endpoint. Platform users are treated like documentation visitors + (per-IP limits). Can ship any time after M6. +2. **M8.2 — user identity via OIDC (1–2 days, mostly service-side).** The + platform already authenticates through OpenID Connect, so no token + endpoint is built: `tokenProvider` returns the signed-in user's ID + token, and the service validates it against the identity provider's + published keys (JWKS), checking audience and expiry — no shared secrets + to provision or rotate. Verified callers switch from per-IP to + per-account rate limits, with user context logged. Extends D7 — + retention for identified questions must be decided before M8.2 ships. + This identity gate is what the platform-actions capability + ([`docs-agent-platform-actions.md`](docs-agent-platform-actions.md)) + builds on. +3. **M8.3 — context hints (~1 day).** The wrapper passes the current platform + view (route or screen name) as a request field folded into the prompt, so + answers orient to where the user is. Client-supplied hints only — no + privileged data path. + +Acceptance: M8.1 answers with citations inside the platform behind the flag; +under M8.2, two accounts on one address get independent rate budgets while +anonymous callers stay IP-limited; the same widget keeps working unchanged +on docs.mat3ra.com throughout. + +--- + +## 5. Change inventory by location + +| Location | Changes | +| --- | --- | +| This repository (public) | Widget assets + `mkdocs-base.yml` wiring (M4); documentation-merge trigger (M5.2); privacy page if chosen (M6). The superseded Phase-0 demo still sits in `scripts/rag/` | +| Service repository ([`documentation-agent`](https://github.com/mat3ra/documentation-agent), private) | Core package (M1, done); eval harness (M2); FastAPI app, streaming loop, Dockerfile, guards, deploy pipeline (M3, M5.3); serves the widget bundle, verifies platform tokens, per-account limits (M8) | +| Platform repository (`web-app`, existing) | React wrapper + feature flag (M8.1); OIDC token wiring (M8.2); context hints (M8.3) | +| Google Cloud (one-time) | Service account, WIF, index bucket, budget alert, Cloud Run service (M5.1) | + +## 6. Execution risks + +Strategy risks live in the companions ([RAG plan §8](docs-agent-rag.md), +[web delivery plan §6](docs-agent-web-delivery.md)); these are risks to the execution: + +- **The public endpoint exists before launch** (M5 precedes M6). Keep the + staging service unlisted, CORS-locked, and rate-limited from its first + deploy; the widget merge, not the service deploy, is the launch event. +- **Model deprecation on Vertex.** The pinned id will eventually retire, and + one default (`gemini-3.1-pro-preview`) is explicitly a preview. The M2 + harness is the safety net — upgrade is a config change plus an evaluation + run, never a silent bump. Model availability is also region-specific + (Gemini 3.x is `global`-only today), so region and model move together. +- **Golden-set staleness.** Documentation moves; expected-URL entries rot. + The retrieval evaluation doubles as the detector (a moved page drops + recall), and D7 logs supply replacement questions. +- **Single-maintainer bandwidth.** Milestones are cut to merge + independently: each of M1–M5 leaves `main` shippable, and the plan + survives being picked up and put down between sessions. + +## 7. Immediate next actions + +M1–M5 are done and the agent is deployed and answering. Only the launch gate +remains, and most of what is left is judgement rather than code. + +1. **Merge the open pull requests.** They are stacked and merge in order: + `documentation-agent` #1 (M1) → #2 (M2) → #3 (M3) → #4 (M5); + `documentation` #391 after #389. +2. **D7, the retention decision** (owner). It gates M6 and nothing else is + blocking it. The widget footer already discloses that questions are + logged, so the text and the policy need to agree before anyone sees it. +3. ~~Settle the faithfulness measurement~~ — **settled 2026-08-01.** Repeated + runs exposed a judge defect (it scored against a truncated view of the + evidence); with the corrected judge, faithfulness is 1.00 in both runs. + The quality half of the M6 gate is met; what remains of M6 is D7 and the + merge itself. +4. **Two secrets to add:** `DOCS_AGENT_DISPATCH_TOKEN` in this repository, so + a documentation merge triggers a rebuild; the pipeline skips with a + message until then, rather than failing the build. +5. **The build machine's gcloud is sorted — the story is worth recording.** + The failures were three stacked causes, not one: the machine driving + builds (Mat3rium) is a different computer from the laptop whose logins + kept "not helping"; its 2023-era gcloud minted tokens Google began + rejecting outright on 2026-08-01; and its account session now demands + interactive reauthentication, which no non-interactive shell can + satisfy. Current state: a current SDK runs from a local directory, fed + tokens minted from application-default credentials + (`CLOUDSDK_AUTH_ACCESS_TOKEN`), which refresh fine — no user action + needed per deploy. A proper `gcloud auth login` on Mat3rium plus a brew + upgrade there would retire the workaround; deploys through CI (federated + identity) bypass all of it, which is one more reason to merge the + pipeline. +5. **Retire the superseded demo** in `scripts/rag/` so there is one + implementation rather than two. +6. **Owner, when convenient:** enable the Claude models in Model Garden on + `mat3ra-documentation` to unblock the `anthropic` backend for the D5 + comparison. Nothing is blocked on it — Gemini is the default and works. + +Note what merging does and does not do. The widget only appears once the +service answers its health check, and the service is already live, so +**merging the widget to `main` is the launch** — which is why it waits on +M6 rather than on anything technical. diff --git a/plans/docs-agent-platform-actions.md b/plans/docs-agent-platform-actions.md new file mode 100644 index 000000000..737564927 --- /dev/null +++ b/plans/docs-agent-platform-actions.md @@ -0,0 +1,194 @@ +# Documentation Agent — Platform Actions Plan + +Plan for letting the in-platform assistant execute actions for the user on +platform.mat3ra.com, built on the test-automation framework rather than a +separate action layer. Elaborates Phase 5 of the [RAG plan](docs-agent-rag.md) +and extends milestone M8 of the +[implementation plan](docs-agent-implementation.md). + +- **Status:** Proposed — needs sign-off and a security review before build. + Builds on the working experiment in + [mat3ra/web-app#2894](https://github.com/mat3ra/web-app/pull/2894) + (`experiment/mcp-server`). +- **Initiative phase:** 5, staged A1–A4 (numbering per the + [implementation plan](docs-agent-implementation.md) §3). Throughout, + "the platform repository" means `web-app` — the code behind + platform.mat3ra.com. +- **Last updated:** 2026-07-31 +- **Companion plans:** [`docs-agent-rag.md`](docs-agent-rag.md), + [`docs-agent-web-delivery.md`](docs-agent-web-delivery.md), + [`docs-agent-implementation.md`](docs-agent-implementation.md) + +--- + +## 1. Principle + +The agent may only do what the test suite can prove works, and only what the +signed-in user could do by hand. Concretely: the action vocabulary **is** the +Gherkin step library of the end-to-end tests, and execution happens **in the +user's own browser session**, so the platform's existing authorization +boundary is never widened. + +## 2. What already exists (PR 2894 inventory) + +The experiment branch in the platform repository contains a working desktop +prototype of exactly this capability: + +| Piece | Contents | State | +| --- | --- | --- | +| `src/tests-cypress/` step definitions | Gherkin steps across ~30 domains (materials, jobs, workflows, billing, oidc, …) | In production CI use | +| [`@mat3ra/tede`](https://github.com/mat3ra/tede) | The test framework: Feature → Step → Widget/TAO → Browser → Driver layering; the Browser layer exists precisely so the driver (Cypress, Webdriver, Playwright) is swappable | Published, reused across projects | +| `src/mcp-server/` | `StepCatalog` (scans step definitions — 514 steps), `FeatureGenerator` (LLM → Gherkin with validation against the catalog), `runner` (executes `.feature` via Cypress CLI), LLM providers (Ollama, Gemini on Vertex) | Working | +| `src/mat3ra-agent-desktop/` | Electron shell: chat panel, embedded browser, `PlaywrightStepExecutor` over CDP, widget ports (`LoginPage`, `MaterialDesignerWidget`, …), step log, intent classification (chat vs automation) | Working locally | + +Three things the experiment proves: + +1. Natural language → **validated** Gherkin works: generation is constrained + to catalog steps and rejected otherwise. +2. Steps are driver-portable: the desktop ported Cypress widgets to + Playwright twice ("reuse cy steps with playwright"), confirming TeDe's + Browser abstraction does its job. +3. Execution currently needs a privileged shell (Electron + CDP). Closing + that gap — execution from a plain web page — is what this plan adds. + +## 3. Execution model: in-page, in-session + +Where should steps execute? The options: + +| Option | Verdict | +| --- | --- | +| **In-page runner** in the user's session | **Chosen.** The user watches every step in their own tab; the user's session is the credential — nothing is delegated; nothing to install. Cypress is the existence proof: it already automates this application in-page with synthetic events, and the whole suite passes. | +| Server-side browser (Playwright) acting as the user | Rejected: requires session delegation to a server (credential custody, a new attack surface), invisible to the user, heavy to operate. | +| Browser extension / CDP | Rejected for the widget: install friction. CDP remains the desktop app's mechanism. | +| REST-API tools (the original Phase-5 sketch in the RAG plan) | Deferred, not rejected: robust for bulk/headless operations, but requires API-token custody at the service, bypasses the UI the user is trying to learn, and is not exercised by the UI test suite. Revisit after the UI-step path ships. | + +The TeDe fit: implement a **DOM driver** for TeDe's Browser layer — the +third driver after Cypress and the desktop's Playwright. Widgets, TAOs¹ and +step definitions stay unchanged; the driver queries the live document and +dispatches events (with the known native-setter technique for React +controlled inputs, as Cypress does). + +¹ TAOs are excluded from the agent surface entirely: they exist to seed test +data through privileged paths and have no business running in production. +The agent gets UI widgets only. + +## 4. Architecture + +``` +platform.mat3ra.com (user signed in via OIDC) +│ +│ Platform bundle ships: action runner = TeDe DOM driver + step executor +│ + step catalog (versioned with the app), exposed as window.Mat3raAgentRunner +│ +└─ Ask AI widget (M8, service-served) + │ POST /chat (SSE; OIDC ID token; client-held history; + │ reports the runner's catalog version) + ▼ + docs-agent service ── tools: search_docs | propose_actions + ▼ (validated against the reported catalog) + Claude on Vertex +``` + +Components: + +1. **Step-catalog artifact.** Built in the platform repository's CI from the step definitions + (the MCP server's `StepCatalog` scan, made a build step): step name, + parameters, domain, description, and a **mutation classification** (§5). + Shipped inside the platform bundle and published for the service. +2. **Runner in the platform bundle, widget from the service.** The runner + (DOM driver + executor + catalog) is platform code, versioned and deployed + with the application — selectors, steps, and app can never skew. The chat + widget stays service-served (M8) and talks to the runner through a small + `window` API. The widget without the runner degrades to chat-only; the + service validates plans against the catalog version the client reports. +3. **Planning in the service.** A `propose_actions` tool: the model drafts + steps, the service validates them against the catalog (porting + `FeatureGenerator`'s validation), invalid plans bounce back for repair. + This is where the two workstreams converge: `search_docs` tells the agent + *what* the procedure is (tutorials), the catalog tells it *how* to perform + it (steps) — one grounded loop does both. +4. **Client-executed action protocol** on the existing stateless `/chat`: + when the model calls `propose_actions`, the SSE stream ends with an + `action_request` event carrying the validated plan. The widget renders the + plan with mutating steps highlighted; the user confirms once per plan; + the runner executes step-by-step with a live log and a stop button; the + widget appends the structured results (per-step status, error, DOM + context on failure) as the tool result in the client-held history and + POSTs `/chat` again. The model then continues — explains, repairs the + plan, or finishes. No server session state, exactly as in M3. + +## 5. Safety model (input to the security review) + +- **Vocabulary allowlist.** Only catalog steps can be planned (validated + server-side) or executed (validated again by the runner). There is no + free-form "evaluate JavaScript" or "click arbitrary selector" step. +- **Per-step classification**, stored in the catalog, human-reviewed: + `read` (navigate, open, list, assert) runs unprompted once a plan is + confirmed; `mutate` (create, edit, submit) requires the plan-level + confirmation and is highlighted; `destructive-or-billing` (delete, purge, + purchase, share outside the account) is **blocked in v1** — the agent + explains the manual procedure with documentation citations instead. +- **Session boundary.** Everything runs as the signed-in user in their own + tab; the service holds no platform credentials and cannot act when the + user is absent. OIDC identity (M8.2) gates the capability: anonymous + docs.mat3ra.com traffic never sees action tools. +- **Visible and interruptible.** Live step log in the widget, a stop button + between steps, and per-step timeouts. +- **Prompt injection.** DOM-derived tool results (element text, entity + names) re-enter the model and are treated as data; the vocabulary + constraint bounds what a poisoned string can cause. Injection scenarios — + e.g. a material named "ignore previous instructions…" — are an explicit + security-review test case. +- **Audit.** Plan, confirmation, and per-step outcomes logged per account + (extends decision D7). +- **Rollout.** Internal accounts → feature-flagged beta → general; the + capability flag in service configuration is the kill switch. + +## 6. The test framework as the quality loop + +This is the reason to build actions on the test suite rather than beside it: + +1. **Coverage by construction.** Every step the agent can execute is + exercised by the E2E suite in the platform repository's CI. A step that starts failing in + CI is pulled from the published catalog, and the agent degrades to + instructions-with-citations for that capability instead of failing + mid-action. +2. **Golden action set.** The action analog of the M2 golden questions: + natural-language request → expected Gherkin plan → replay through the + existing Cypress runner against a seeded environment in CI. Catches both + planning regressions (prompt/model changes) and execution regressions + (app changes). +3. **Cross-driver parity.** The same `.feature` must pass under the Cypress + driver (CI) and the DOM driver (the widget runner, driven by Playwright + in CI as the harness). Parity failures mean the DOM driver lies about a + capability. +4. **New capabilities are test-driven.** Adding an agent skill = writing the + step definitions, widgets, and tests first; the catalog regenerates; the + agent can now plan with it. No agent-side code changes — the test suite + is the agent's skill tree. +5. **The desktop app stays** as the step-development harness (interactive + Playwright execution, step log) and a power-user tool. Optional later + convergence: its planner calls the docs-agent service instead of local + Gemini/Ollama, keeping one planning implementation. + +## 7. Staging + +Sequenced after M8.2 (OIDC identity at the service). Each stage shippable +alone. + +| Stage | Scope | Where | Estimate | +| --- | --- | --- | --- | +| A1 | Catalog build step with classification; TeDe DOM driver MVP (navigate, open explorer, click widget control, fill field, assert visible) with cross-driver parity tests | platform repo, `tede` | 3–5 days | +| A2 | `propose_actions` + validation in the service; `action_request` protocol; capability flag, OIDC-gated | service repo, widget | 2–3 days | +| A3 | Widget action mode: plan preview, confirmation, live step log, stop; `read` steps first, then `mutate` | widget, platform repo (runner exposure) | 3–5 days | +| A4 | Golden action set in the platform repository's CI; audit logging; security review; internal beta | platform repo, service | 2–3 days + review | + +## 8. Open decisions + +1. **First domains.** Recommendation: materials and workflows, read-heavy + steps first — they map directly onto the most-read tutorials. +2. **Classification ownership.** Who reviews and signs off the per-step + `read`/`mutate`/`blocked` labels; CI should fail on unclassified steps. +3. **DOM driver home.** Recommendation: inside `@mat3ra/tede` next to the + existing drivers, versioned with the steps that depend on it. +4. **Desktop convergence** on the service planner: worth doing, not urgent. diff --git a/plans/docs-agent-rag.md b/plans/docs-agent-rag.md new file mode 100644 index 000000000..b39f79c66 --- /dev/null +++ b/plans/docs-agent-rag.md @@ -0,0 +1,292 @@ +# Documentation Agent — RAG Plan + +Plan for an assistant that answers user questions from the content of this +repository (docs.mat3ra.com), grounded with Retrieval-Augmented Generation (RAG). + +- **Status:** Active — the strategy reference for retrieval and evaluation. + Of its content, Phase 0 (prototypes) is complete — a working demo is + committed in [`scripts/rag/`](../scripts/rag/) and since rebuilt in the + [`documentation-agent`](https://github.com/mat3ra/documentation-agent) + repository (D6) — while evaluation (§5) and + retrieval upgrades (§4.3) are still ahead. Phase numbering and live + progression: [implementation plan](docs-agent-implementation.md) §3. +- **Last updated:** 2026-07-31 +- **Companion plan:** [`docs-agent-web-delivery.md`](docs-agent-web-delivery.md) (browser delivery) +- **Implementation plan:** [`docs-agent-implementation.md`](docs-agent-implementation.md) + +--- + +## 1. Current state + +A minimal grounded agent runs end-to-end and has been verified against live +Claude on Vertex AI. + +| Piece | State | +| --- | --- | +| Corpus ingestion (`ingest.py`) | **Done.** 534 pages → 2,554 chunks | +| Lexical retrieval (BM25, in-process) | **Done.** No external index or service | +| Agentic loop with a `search_docs` tool | **Done.** Model reformulates and re-searches on its own | +| Grounding + citation rules in the system prompt | **Done.** Answers cite docs.mat3ra.com URLs | +| Vector / hybrid retrieval | Not started | +| Contextual retrieval (chunk situating) | Not started | +| `get_page` tool (fetch a whole page) | Not started | +| Evaluation harness | Not started | +| Any web interface | Not started — see the [web delivery plan](docs-agent-web-delivery.md) | + +Verified behaviour: asked how to import a material from a POSCAR file, the agent +issued four searches (including section-filtered reformulations) and produced a +two-method answer citing `materials/actions/upload/` and +`tutorials/materials/import-from-files/` — both real pages. + +### What changed from the original proposal + +1. **The full-corpus baseline was skipped.** The original plan proposed a + "whole corpus in the context window" baseline before building retrieval. + Retrieval turned out to be cheap enough to build directly, so the baseline + was never needed. It remains useful as a *quality ceiling* for evaluation + (§5) and can still be run later. +2. **The platform is Google Vertex AI, not the Claude API directly.** This + constrains some of the original design — see §3.2. The model is no longer + fixed: as of 2026-07-31 the agent runs behind a provider abstraction with + **Gemini as the default** (Claude on Vertex additionally requires Model + Garden enablement) and Claude selectable by configuration. Which one ships + is an evaluation question (§5), not a preference. +3. **Retrieval is lexical (BM25), not vector-based.** This was a deliberate + scope cut, not an oversight: it removes all index infrastructure from the + demo while still exercising the full agent loop. Its limits are known and + measurable (§4.3). + +--- + +## 2. Terminology: RAG is not fine-tuning + +Fine-tuning changes model weights; RAG injects relevant documentation into the +prompt at question time. For a documentation assistant, RAG is the correct tool: +weight updates would go stale on every documentation change, and the answer +quality problem here is a *retrieval* problem, not a *knowledge* problem. + +What is usually meant by "tuning" such an agent — making it answer better — is +achieved by iterating on **retrieval quality, the system prompt, and an +evaluation harness** (§5). This plan uses "tuning" in that sense throughout. + +--- + +## 3. Architecture + +### 3.1. Agentic RAG + +``` +User question + │ + ▼ +┌─────────────────────────────┐ ┌──────────────────────────┐ +│ Agent (mat3ra_docs_agent) │ tool │ Retrieval │ +│ Gemini or Claude on Vertex │───────▶│ BM25 over doc chunks │ +│ system prompt (cached) │◀───────│ (→ hybrid, later) │ +│ tool: search_docs │ chunks └──────────────────────────┘ +└─────────────┬───────────────┘ + ▼ + Answer + citations (docs.mat3ra.com URLs) +``` + +The agent decides *when and what* to search: it can reformulate the query, +filter by documentation section, and search repeatedly before answering. This +"agentic RAG" pattern outperforms single-shot retrieve-then-answer on multi-step +questions, and the observed behaviour confirms it — the model routinely issues +three or four searches before committing to an answer. + +Design decisions as implemented: + +| Decision | Choice | Rationale | +| --- | --- | --- | +| Model | Gemini by default, Claude behind the same interface | Both do grounded tool use; Gemini needs no Model Garden step, so it unblocks work | +| Region | Per provider: Gemini `global`, Claude `us-east5` | Model availability is region-specific — Gemini 3.x is not served from `us-east5` | +| Loop | Hand-written | The SDK `tool_runner` helper is not available on `AnthropicVertex` (verified against SDK 0.116) | +| Caching | `cache_control` on the system prompt | Stable prefix, re-read on every turn | +| Tool-loop bound | 8 iterations per user turn | Prevents a runaway loop from billing indefinitely | +| Auth | ADC, or `VERTEX_ACCESS_TOKEN` for local dev | No credentials in the repository | + +### 3.2. Vertex AI constraints + +Vertex supports the Messages API, prompt caching, extended thinking, tool use, +and citations — everything this agent needs. Several features assumed by the +original proposal are **not** available on Vertex and the plan is adjusted +accordingly: + +- **Message Batches API** — unavailable. Evaluation runs (§5) cannot be + half-price batched; budget for standard requests, or run evals against the + Claude API directly. +- **Managed Agents** — unavailable. The hosted-agent-loop option is off the + table while on Vertex; the loop stays in our own service. +- **`tool_runner` SDK helper** — not present on the Vertex client. The loop is + written by hand (~30 lines) and is what the web service will reuse. + +### 3.3. System prompt + +The system prompt is the primary grounding control. Its essentials: + +- Role and product context. +- **The grounding rule:** answer only from retrieved content; cite only URLs + that appeared in a tool result; never invent URLs, endpoints, or UI element + names. +- **The escalation rule:** if retrieval finds nothing relevant, say so and point + to support rather than guessing. +- A compact list of top-level documentation sections, so the model can pick a + sensible `section` filter. +- Answer in the user's language, in the documentation's dry style. + +--- + +## 4. The corpus and the retrieval pipeline + +### 4.1. Inventory + +| Property | Value | +| --- | --- | +| Source of truth | `lang/en/docs/` — 536 Markdown files, ~187k words ≈ 260k tokens | +| Indexed | 534 pages → 2,554 chunks | +| Sites | 4 MkDocs builds: full (`/`), Guide (`/guide/`), Reference (`/reference/`), Dev (`/dev/`) | +| Structured data | ESSE JSON schemas/examples included via `--8<--` from `data/esse/` | +| Cross-links | Jinja macros `{{ guide_url }}`, `{{ reference_url }}`, `{{ dev_url }}` | +| Other languages | `lang/ja/` is machine-generated — **not indexed** | + +Two consequences of this size: the corpus is small enough that indexing costs +are negligible, and small enough to fit whole into a 1M-token context window if +a non-retrieval baseline is ever wanted. + +### 4.2. Ingestion (implemented) + +`ingest.py` walks `lang/en/docs/**/*.md` and: + +1. **Resolves the Jinja macros** as the mkdocs-macros plugin would, so + cross-site links in retrieved text are real URLs. +2. **Strips front matter and `{% raw %}` markers**, keeping their contents so + templating tutorials stay searchable verbatim. +3. **Maps each page to its canonical URL.** The full site serves every page, so + `lang/en/docs//.md` → `https://docs.mat3ra.com///`. +4. **Chunks on H2 boundaries** with a breadcrumb (`Page title > Section`) + prepended to every chunk — this materially improves both retrieval and the + quality of the model's citations. + +Known gap: `--8<--` include directives are currently dropped, so questions about +ESSE JSON schema internals are not yet answerable. Inlining them (with a size +cap) is the first ingestion improvement. + +### 4.3. Retrieval: current and next + +Today: BM25 over the chunk text, top 6 results, optional section filter. + +BM25 is strong on exact terms — code identifiers, file formats, UI labels — and +weak on paraphrase. The failure mode is visible in practice: the query "REST API +authentication" ranks the JupyterLite authentication page above the REST API +one, because it matches the literal words rather than the concept. + +Planned upgrades, in order of expected value: + +| Step | Change | Why | +| --- | --- | --- | +| 1 | **Contextual retrieval** — prepend a 50–100 token situating summary to each chunk before indexing, generated once with a cheap model | Anthropic reports ~49% fewer retrieval failures; a one-time cost of a few dollars at this corpus size | +| 2 | **Embeddings + hybrid search** — vector search fused with BM25 by reciprocal-rank fusion | Fixes paraphrase and concept queries; multilingual embeddings also let Japanese questions match English chunks | +| 3 | **Reranking** — top-20 → top-5 with a reranker | Precision gain; add only if evaluation justifies it | +| 4 | **`get_page` tool** — let the agent pull a whole page when a chunk lacks context | Cheap to add; helps multi-step procedural questions | + +The retrieval interface (`Retriever.search`) is deliberately narrow so these +swap in without touching the agent loop or the web service. + +### 4.4. Keeping the index fresh + +The index is currently rebuilt by hand (`python ingest.py`). The generated +`chunks.jsonl` is **not committed** — it is a build artifact. + +For production: rebuild on merge to `main` in CI, and version the artifact with +the documentation commit it was built from, so an answer can always be traced to +a documentation snapshot. See the [web delivery plan](docs-agent-web-delivery.md) for how +that artifact reaches the deployed service. + +--- + +## 5. Evaluation — how the agent actually gets "tuned" + +This is the substitute for fine-tuning: a measurable loop over retrieval and +prompt parameters. It is the highest-leverage unbuilt piece of this plan. + +1. **Golden set (~75–100 question/answer pairs).** Sources: real support + questions, tutorial steps rephrased as questions, pricing and account FAQs, + REST API usage questions, plus ~10 *unanswerable* questions where the correct + behaviour is "not in the documentation, contact support". Each entry records + the question, the expected source page(s), and the key facts a correct answer + must contain. +2. **Retrieval metrics:** recall@5 and MRR of the expected page among retrieved + chunks. These need no model call — fast and cheap enough to run on every + pipeline change. +3. **Answer metrics:** model-as-judge scoring of faithfulness (no claims beyond + retrieved text), citation correctness (URLs resolve and support the claim), + and completeness against the key facts. +4. **Tuning levers**, iterated against the golden set: chunk size, top-k, fusion + weights, reranking, the contextual-retrieval prompt, system prompt wording, + and model tier. +5. **Regression gate:** run the evaluation in CI on every change to the + agent repository — retrieval, prompt, or model configuration. + +Note the Vertex constraint from §3.2: no Batch API, so evaluation runs are +billed at standard rates. + +--- + +## 6. Roadmap + +The phase numbering is shared by all four plans; the +[implementation plan](docs-agent-implementation.md) §3 maps each phase to +concrete milestones. + +| Phase | Scope | State | +| --- | --- | --- | +| 0 | Prototypes: this repository's demo (ingestion, BM25 retrieval, agentic loop, CLI) and the platform repository's desktop automation experiment | **Done** | +| 1 | Foundations: shared core package, golden set + evaluation harness | In progress — the package is done and now lives in the `documentation-agent` repository; the harness is next | +| 2 | Docs launch: service, widget, deployment, hardening | Planned — see the [web delivery plan](docs-agent-web-delivery.md) | +| 3 | Retrieval quality: contextual retrieval, embeddings, hybrid search, `get_page` (§4.3) | Planned, evaluation-gated | +| 4 | Platform embed: the same widget inside platform.mat3ra.com | Planned | +| 5 | Platform actions — the agent performs documented procedures in the user's session | Proposed in [`docs-agent-platform-actions.md`](docs-agent-platform-actions.md) (UI steps via the test framework; REST-API tools deferred); needs its own security review | + +The full-corpus-in-context baseline (the corpus fits a 1M-token window) +remains available outside the numbering as an evaluation ceiling (§5). + +--- + +## 7. Cost + +Order-of-magnitude planning figures only; Vertex bills through Google Cloud and +current rates should be confirmed against Vertex pricing before committing. + +- **Indexing** is negligible — a corpus this small embeds for a few dollars, and + contextual retrieval adds a one-time cost in the same range. +- **Per question**, the dominant cost is the model call: a handful of retrieved + chunks plus a cached system prompt in, a few hundred tokens out, multiplied by + the number of search rounds the agent chooses to make. +- **Prompt caching** on the system prompt is the single largest lever, since the + same prefix is re-read on every turn of every conversation. +- A smaller model tier is worth evaluating for high-volume simple questions once + the golden set can prove parity. + +--- + +## 8. Risks and guardrails + +- **Hallucinated URLs or UI paths** — mitigated by the cite-only-from-tool-results + rule; must be verified by the evaluation judge rather than assumed. +- **Stale answers after documentation edits** — CI re-indexing on merge (§4.4). +- **Runaway tool loops** — bounded at 8 iterations per turn. +- **Prompt injection and abuse** — relevant once the agent is exposed publicly; + covered in the [web delivery plan](docs-agent-web-delivery.md). +- **Query privacy** — user questions may contain proprietary research context. A + logging and retention policy is required before any public deployment. +- **Machine-translated pages** — `lang/ja/` is never indexed; multilingual + answers come from the model, not from translated chunks. + +## 9. Next steps + +1. Build the golden question set — the highest-leverage artifact in this plan. +2. Add the retrieval-metric harness (no model calls needed) and record a BM25 + baseline to measure every later change against. +3. Implement contextual retrieval and hybrid search; keep BM25 as the fallback + and compare on the golden set. diff --git a/plans/docs-agent-web-delivery.md b/plans/docs-agent-web-delivery.md new file mode 100644 index 000000000..563ed811c --- /dev/null +++ b/plans/docs-agent-web-delivery.md @@ -0,0 +1,257 @@ +# Documentation Agent — Web Delivery Plan + +Plan for turning the working command-line agent (the `mat3ra_docs_agent` +package in the +[`documentation-agent`](https://github.com/mat3ra/documentation-agent) +repository) into a browser-based chat. +"Web delivery" here means shipping the documentation agent to browsers — not +to be confused with the platform application, whose repository is named +`web-app`. + +- **Status:** Active — the architecture reference for Phase 2 (docs launch); + nothing built yet. +- **Last updated:** 2026-07-31 +- **Companion plan:** [`docs-agent-rag.md`](docs-agent-rag.md) (agent and retrieval strategy) +- **Implementation plan:** [`docs-agent-implementation.md`](docs-agent-implementation.md) + +--- + +## 1. Two questions answered first + +### 1.1. Can the chat be browser-only, with no backend? + +**No.** A pure front-end implementation is not viable, for three reasons: + +1. **Credentials.** Calling Vertex requires a Google OAuth token or service + account credential. Anything shipped to the browser is public, so embedding + one would expose billable access to everyone. +2. **Transport.** The Anthropic Vertex SDK is server-side, and Vertex endpoints + are not CORS-enabled for arbitrary browser origins. +3. **Control.** Rate limiting, abuse protection and logging must live somewhere + the user cannot tamper with. + +A theoretical exception — signing every visitor in with Google and using their +own token — fails on both CORS and the requirement that each visitor have +Vertex access. Unworkable for public documentation. + +So the architecture is always **browser → our backend → retrieval + Vertex**. +The backend is thin: it is the existing `run_turn()` loop behind an HTTP +endpoint with streaming. + +### 1.2. Does the dataset need a vector representation? + +**Not in order to go browser-based.** Retrieval runs on the backend either way, +so the current in-process BM25 index works unchanged behind an API. Vectors are +a **retrieval-quality** upgrade, orthogonal to web delivery, and are planned +separately in [`docs-agent-rag.md`](docs-agent-rag.md) §4.3. + +Browser-side vector search (shipping an index and embedding in the page) is +technically possible but pointless here: the model call must be server-side +regardless, so there is no round trip to save. + +**Recommendation:** ship the first web version on BM25; add embeddings on the +retrieval plan's own schedule. + +--- + +## 2. Where the service should live + +### 2.1. Not inside the platform application + +The platform (platform.mat3ra.com) is a large Meteor application maintained +in the `web-app` repository. It is the wrong home for a public documentation +assistant: + +| | Standalone service | Inside the platform application | +| --- | --- | --- | +| Reuses the existing demo | Yes, unchanged (Python) | No — retrieval and the Vertex call must be ported | +| Streaming | Native server-sent events | Meteor methods are RPC; needs a non-idiomatic raw route | +| Blast radius | Isolated | Adds an unauthenticated, abuse-exposed endpoint to the application that runs billing, jobs and accounts | +| Deployment coupling | Independent, fast iteration | Tied to the platform release cadence | +| Fit with existing architecture | Matches the existing pattern of separate Python services | Enlarges the monolith | + +The decisive point is the third row: the majority of this agent's users are on +the documentation domain, not signed into the platform, so an anonymous endpoint +would be added to the most sensitive application for the benefit of users who +are mostly somewhere else. + +### 2.2. One service, two surfaces + +Build the agent once and let both front ends call it: + +``` +docs.mat3ra.com widget ──┐ + ├──▶ docs agent service ──▶ Vertex (claude-opus-4-6) +in-platform "Ask AI" ───┘ (BM25 → hybrid retrieval) +``` + +The public documentation widget comes first. The in-platform surface is a later +addition: a small React component calling the same service through a thin +authenticated route that injects user identity for per-user rate limiting — no +duplicated retrieval, no second set of credentials. + +--- + +## 3. Components + +### 3.1. Backend service + +A small Python service (FastAPI) reusing the existing retriever and loop. + +- **`POST /chat`** — accepts the conversation, responds with a server-sent event + stream of text deltas plus a final `sources` event. Streaming is required both + for chat responsiveness and to avoid proxy timeouts on multi-search answers. +- **`GET /health`** — readiness probe. +- Loads the chunk index once at startup (2,554 chunks: sub-second, a few MB). +- Authenticates to Vertex through the runtime service account — no secrets in + the image. + +The one structural difference from the command-line version is streaming +combined with tool use: stream each assistant turn, and when a turn ends in a +tool call, run the search, append the result, and start the next streamed turn. +This also gives the user visible progress ("Searching documentation…"). + +**Refactor first:** split `agent.py` into `rag_core.py` (retriever, tool +definition, system prompt, result formatting) plus a thin command-line wrapper, +so the service imports the same core rather than copying it. The retriever was +written to support this — it raises on a missing index instead of exiting the +process. + +### 3.2. Front-end widget + +An embeddable chat widget injected into the MkDocs theme, so an "Ask AI" +launcher appears on every documentation page. + +- Small self-hosted bundle, referenced from `extra_javascript` in **all** MkDocs + configuration files (the repository requires configuration changes to be + mirrored across every site config). +- Renders streamed Markdown incrementally, shows a searching state during tool + calls, and renders the final sources as clickable links. +- Sanitises rendered output — model text is never injected as raw HTML. +- Conversation kept in memory only. + +--- + +## 4. Repository layout and version control + +The documentation repository is **public**. The service's operational +configuration should not be. Split by what each part is coupled to: + +> **Revised 2026-07-31 (decision D6).** The split below was reconsidered: the +> agent core now lives with the service rather than here. The reasoning about +> what must stay private is unchanged; only the boundary moved. + +| Concern | Repository | Reason | +| --- | --- | --- | +| Corpus (the Markdown itself) | **This (public) repository** | It is the documentation | +| Ingestion, retrieval core, prompt, agent loop, HTTP service, container, deployment | **`documentation-agent` (private)** | One repository owns all agent code, so there is no cross-repository package version to keep in step; ingestion reads a documentation checkout at a pinned commit | +| Built index | **Baked into the service image**, not committed | Generated content; versioned by the documentation commit it was built from | + +The rejected alternative was a one-way package dependency (this repository +publishing an installable core that the service imports). It works, but it +splits one codebase across two release cadences for no gain now that the +service is the only consumer. The service checks out the documentation at a +specific SHA rather than vendoring it, so no Git LFS history enters the image. + +--- + +## 5. Deployment + +Two viable paths. Both use the private-service-repository layout from §4; only +the runtime differs. + +**Option A — Serverless (recommended).** A managed container runtime such as +Cloud Run in the same cloud project as Vertex. Scale-to-zero suits bursty, +low-volume traffic, and — the reason it directly solves a problem already hit in +development — an attached service account makes credentials resolve +automatically, so no token or key is handled anywhere. Deployed by its own +pipeline on merge, independent of the platform release train. + +**Option B — Alongside the platform stack.** The service runs as a container on +existing infrastructure, shipped by the existing configuration-management and CI +pipeline like other backend services, authenticating to Vertex through the +instance service account. One pipeline and one monitoring surface, at the cost +of the platform's slower release cadence and no scale-to-zero. + +Choose A if the agent should iterate independently — appropriate while it is +experimental. Choose B if operations prefers a single pipeline. + +**Fallback — no new service at all.** Since the documentation site is already +deployed on Netlify, the agent loop can run as an edge function in this +repository: same deployment pipeline, nothing new to operate. The trade-offs are +real: a cloud service-account key must be stored as a build secret (which the +serverless option avoids entirely), the retriever must be ported to JavaScript, +and function execution limits constrain long multi-search answers. Reasonable +for a demonstration; weaker as a foundation. + +### 5.1. Practices that apply to any of these + +1. **One service, one repository, pinned as a submodule** — the stack records an + exact commit, so deployments are reproducible and revertible. +2. **No credentials in Git, ever.** Prefer attached or instance service accounts + over key files, and federated identity over long-lived credentials in CI. +3. **Immutable, versioned artifacts.** Bake the index and the documentation + commit it came from into the image: one image is one documentation snapshot, + and rollback is redeploying the previous image. +4. **Two decoupled triggers.** A documentation merge rebuilds the index + artifact; a service change or a new index rebuilds and redeploys the service. + The service pins an index version rather than rebuilding the corpus itself. +5. **Least privilege.** The runtime identity gets model access and read access to + the index, and nothing else. The future in-platform surface injects user + identity at the proxy rather than widening this identity. +6. **Environment parity.** The same container runs locally and in production. + +--- + +## 6. Security and operations + +- **CORS:** restrict to the documentation origins plus localhost for development. +- **Untrusted input:** every request body is attacker-controlled. Rate-limit per + address and session, and cap both conversation length and tool iterations per + turn (the loop is already bounded at 8). +- **Read-only tools.** The public agent can search documentation and nothing + else. Platform actions are a later, separately reviewed capability. +- **Output safety.** Retrieved text comes from our own corpus, but rendered + answers are still sanitised, and the cite-only-from-tool-results rule remains + the guard against fabricated links. +- **Cost control:** per-session token ceiling, spend alerting on the cloud + project, and a bot check in front of the public endpoint if abuse appears. +- **Privacy:** questions may contain proprietary research context. Decide + logging and retention before launch; log minimally. +- **Observability:** record latency, tool-call counts, token usage and stop + reasons. These logs also supply real questions for the golden evaluation set. + +--- + +## 7. Roadmap + +Milestone identifiers and phase numbering follow the +[implementation plan](docs-agent-implementation.md) §3, which supersedes +this table for sequencing. + +| Milestone (phase) | Scope | Estimate | +| --- | --- | --- | +| M1 (Phase 1) | Extract the shared core package; command-line wrapper imports it | 0.5–1 day | +| M3 (Phase 2) | FastAPI `/chat` with streaming and the tool loop; CORS; local run | 2–4 days | +| M4 (Phase 2) | Embeddable widget in the MkDocs theme; streamed Markdown and citations | 3–5 days | +| M5 (Phase 2) | Container, deployment pipeline, service-account auth, rate limiting, spend alerts | 2–3 days | +| M7 (Phase 3) | Hybrid retrieval behind the same interface; evaluation gate; latency tuning | 1–2 weeks | +| Phases 4–5 | In-platform surface (M8); platform actions ([`docs-agent-platform-actions.md`](docs-agent-platform-actions.md), separate security review) | As prioritised | + +## 8. Cost + +Incremental over the agent itself (see [`docs-agent-rag.md`](docs-agent-rag.md) §7): + +- **Hosting:** a scale-to-zero service for low-volume documentation traffic is a + small monthly figure plus per-request compute. Retrieval is CPU-cheap; the + model call dominates. +- **Storage:** none for the first version — the index is in memory. Hybrid + retrieval later adds a small managed-database line item. + +## 9. Next steps + +1. Confirm the surface (documentation-theme widget) and the deployment option. +2. Extract `rag_core.py` so the service and the command-line tool share one core. +3. Stand up `/chat` locally and stream one grounded answer end-to-end. +4. Create the Vertex service account for the target runtime, removing the + developer access-token workaround. diff --git a/requirements.txt b/requirements.txt index ad4f730bf..c35dfdb34 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,69 +1,73 @@ -babel==2.17.0 +babel==2.18.0 backports-abc==0.5 -backrefs==5.8 +backrefs==7.0 cachetools==5.5.2 -certifi==2025.4.26 +certifi==2026.7.22 chardet==4.0.0 -charset-normalizer==3.4.2 -click==8.2.1 +charset-normalizer==3.4.9 +click==8.4.2 colorama==0.4.6 enum34==1.1.10 exabyte-json-include==2020.10.19 ghp-import==2.1.0 gitdb==4.0.12 -GitPython==3.1.44 -google-api-core==2.21.0 +GitPython==3.1.55 +google-api-core==2.30.3 google-api-python-client==2.149.0 google-auth==2.35.0 -google-auth-httplib2==0.2.0 -google-cloud-texttospeech==2.18.0 -googleapis-common-protos==1.65.0 -grpcio==1.66.2 -grpcio-status==1.66.2 -httplib2==0.22.0 -idna==3.10 +google-auth-httplib2==0.2.1 +google-cloud-texttospeech==2.36.0 +googleapis-common-protos==1.74.0 +grpcio==1.80.0 +grpcio-status==1.80.0 +httplib2==0.32.0 +idna==3.18 importlib_metadata==8.5.0 Jinja2==3.1.6 -latexcodec==3.0.0 +latexcodec==3.0.1 livereload==2.6.3 -Markdown==3.8 -MarkupSafe==3.0.2 +Markdown==3.10.2 +MarkupSafe==3.0.3 mergedeep==1.3.4 mkdocs==1.6.1 mkdocs-bibtex==2.16.2 -mkdocs-get-deps==0.2.0 +mkdocs-exclude==1.0.2 +mkdocs-get-deps==0.2.2 mkdocs-git-revision-date-localized-plugin==1.2.9 mkdocs-macros-plugin==1.2.0 -mkdocs-material==9.6.14 +mkdocs-material==9.7.7 mkdocs-material-extensions==1.3.1 oauth2client==4.1.3 -packaging==25.0 +packaging==26.2 paginate==0.5.7 -pathspec==0.12.1 -platformdirs==4.3.8 -proto-plus==1.24.0 -protobuf==5.28.3 -pyasn1==0.6.1 +pathspec==1.1.1 +pip==26.1.2 +platformdirs==4.11.0 +proto-plus==1.27.2 +protobuf==6.33.6 +pyasn1==0.6.4 pyasn1_modules==0.4.2 pybtex==0.24.0 -Pygments==2.19.1 -pymdown-extensions==10.15 -pypandoc==1.15 +Pygments==2.20.0 +pymdown-extensions==11.0.1 +pypandoc==1.16.2 pyparsing==3.1.4 python-dateutil==2.9.0.post0 pytz==2024.2 -PyYAML==6.0.2 +PyYAML==6.0.3 pyyaml_env_tag==1.1 regex==2024.9.11 -requests==2.32.3 +requests==2.34.2 rsa==4.9.1 +setuptools==81.0.0 singledispatch==3.4.0.4 six==1.17.0 -smmap==5.0.2 +smmap==5.0.3 termcolor==2.5.0 -tornado==6.5.1 +tornado==6.5.7 +typing_extensions==4.15.0 uritemplate==4.1.1 -urllib3==2.4.0 +urllib3==2.7.0 validators==0.34.0 watchdog==6.0.0 zipp==3.20.2 diff --git a/scripts/check-links.py b/scripts/check-links.py new file mode 100644 index 000000000..4b02120c9 --- /dev/null +++ b/scripts/check-links.py @@ -0,0 +1,159 @@ +#!/usr/bin/env python3 +"""Post-build internal link checker for the multi-site documentation. + +Scans the built site/ directory for all HTML files, extracts internal + links, and verifies that the target files exist on disk. + +Usage: + python scripts/check-links.py [site_dir] + +Defaults to site_dir = "site". +Exit code 1 if any broken links are found. +""" + +import os +import re +import sys +from html.parser import HTMLParser +from pathlib import Path +from urllib.parse import unquote, urlparse + + +class LinkExtractor(HTMLParser): + """Extract href attributes from tags.""" + + def __init__(self): + super().__init__() + self.links = [] + + def handle_starttag(self, tag, attrs): + if tag == "a": + for name, value in attrs: + if name == "href" and value: + self.links.append(value) + + +def resolve_link(html_file: Path, href: str, site_root: Path) -> Path | None: + """Resolve an href to an absolute filesystem path within the site. + + Returns None if the link is external, a mailto, anchor-only, or + uses a scheme we don't check. + """ + # Skip external links, anchors, mailto, javascript, etc. + if href.startswith(("#", "mailto:", "javascript:", "tel:", "data:")): + return None + + parsed = urlparse(href) + + # Skip external URLs + if parsed.scheme in ("http", "https", "ftp"): + return None + + # Strip fragment + path = unquote(parsed.path) + if not path: + return None + + # Absolute path (starts with /) — resolve from site root + if path.startswith("/"): + resolved = site_root / path.lstrip("/") + else: + # Relative path — resolve from the directory of the current file + resolved = html_file.parent / path + + return resolved.resolve() + + +def check_path_exists(target: Path, site_root: Path) -> bool: + """Check if a link target resolves to an existing file. + + Handles directory links (expecting index.html inside) and direct + file links. + """ + if target.is_file(): + return True + if target.is_dir() and (target / "index.html").is_file(): + return True + # Try adding .html + html_target = target.with_suffix(".html") + if html_target.is_file(): + return True + # Try as directory with index.html (for paths without trailing slash) + if (target / "index.html").is_file(): + return True + return False + + +def main(): + site_dir = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("site") + + if not site_dir.is_dir(): + print(f"Error: site directory '{site_dir}' not found.") + print("Run the build first: ./scripts/serve-all.sh --build") + sys.exit(2) + + site_root = site_dir.resolve() + broken = [] + checked = 0 + + html_files = sorted(site_root.rglob("*.html")) + print(f"Scanning {len(html_files)} HTML files in {site_dir}/...") + + for html_file in html_files: + with open(html_file, "r", encoding="utf-8", errors="ignore") as f: + content = f.read() + + extractor = LinkExtractor() + try: + extractor.feed(content) + except Exception: + continue + + for href in extractor.links: + target = resolve_link(html_file, href, site_root) + if target is None: + continue + + checked += 1 + + # Only check links that should be inside the site + try: + target.relative_to(site_root) + except ValueError: + # Link points outside the site directory — skip + continue + + if not check_path_exists(target, site_root): + rel_source = html_file.relative_to(site_root) + broken.append((str(rel_source), href)) + + # Deduplicate + broken = sorted(set(broken)) + + print(f"Checked {checked} internal links.") + print() + + if broken: + print(f"BROKEN LINKS FOUND: {len(broken)}") + print("=" * 60) + + # Group by source file + by_source = {} + for source, href in broken: + by_source.setdefault(source, []).append(href) + + for source in sorted(by_source): + print(f"\n {source}:") + for href in sorted(by_source[source]): + print(f" → {href}") + + print() + print(f"Total: {len(broken)} broken link(s) in {len(by_source)} file(s).") + sys.exit(1) + else: + print("No broken internal links found.") + sys.exit(0) + + +if __name__ == "__main__": + main() diff --git a/scripts/generate_index_of_sub_section.py b/scripts/generate_index_of_sub_section.py index 8f4306ff5..285c17360 100644 --- a/scripts/generate_index_of_sub_section.py +++ b/scripts/generate_index_of_sub_section.py @@ -58,7 +58,7 @@ def gen_index(config, section): with open(config_path, "r", encoding="utf8") as stream: try: - config = yaml.load(stream, Loader=yaml.CLoader) + config = yaml.safe_load(stream) except yaml.YAMLError as exc: raise SystemError("Error: something went wrong while loading yaml file.") from exc @@ -123,7 +123,6 @@ def gen_index(config, section): # - General Functionality # - [Jupyter Notebook](other/jupyter.md) # - [Restart from Previous Job](other/restart-job.md) -# - [Upload External Job Data](other/external-upload.md) # - [TensorFlow (GPU)](general-functionality/tensorflow-gpu.md) # - Materials # - [Overview](materials/overview.md) diff --git a/scripts/links/check-links.py b/scripts/links/check-links.py new file mode 100644 index 000000000..4b02120c9 --- /dev/null +++ b/scripts/links/check-links.py @@ -0,0 +1,159 @@ +#!/usr/bin/env python3 +"""Post-build internal link checker for the multi-site documentation. + +Scans the built site/ directory for all HTML files, extracts internal + links, and verifies that the target files exist on disk. + +Usage: + python scripts/check-links.py [site_dir] + +Defaults to site_dir = "site". +Exit code 1 if any broken links are found. +""" + +import os +import re +import sys +from html.parser import HTMLParser +from pathlib import Path +from urllib.parse import unquote, urlparse + + +class LinkExtractor(HTMLParser): + """Extract href attributes from tags.""" + + def __init__(self): + super().__init__() + self.links = [] + + def handle_starttag(self, tag, attrs): + if tag == "a": + for name, value in attrs: + if name == "href" and value: + self.links.append(value) + + +def resolve_link(html_file: Path, href: str, site_root: Path) -> Path | None: + """Resolve an href to an absolute filesystem path within the site. + + Returns None if the link is external, a mailto, anchor-only, or + uses a scheme we don't check. + """ + # Skip external links, anchors, mailto, javascript, etc. + if href.startswith(("#", "mailto:", "javascript:", "tel:", "data:")): + return None + + parsed = urlparse(href) + + # Skip external URLs + if parsed.scheme in ("http", "https", "ftp"): + return None + + # Strip fragment + path = unquote(parsed.path) + if not path: + return None + + # Absolute path (starts with /) — resolve from site root + if path.startswith("/"): + resolved = site_root / path.lstrip("/") + else: + # Relative path — resolve from the directory of the current file + resolved = html_file.parent / path + + return resolved.resolve() + + +def check_path_exists(target: Path, site_root: Path) -> bool: + """Check if a link target resolves to an existing file. + + Handles directory links (expecting index.html inside) and direct + file links. + """ + if target.is_file(): + return True + if target.is_dir() and (target / "index.html").is_file(): + return True + # Try adding .html + html_target = target.with_suffix(".html") + if html_target.is_file(): + return True + # Try as directory with index.html (for paths without trailing slash) + if (target / "index.html").is_file(): + return True + return False + + +def main(): + site_dir = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("site") + + if not site_dir.is_dir(): + print(f"Error: site directory '{site_dir}' not found.") + print("Run the build first: ./scripts/serve-all.sh --build") + sys.exit(2) + + site_root = site_dir.resolve() + broken = [] + checked = 0 + + html_files = sorted(site_root.rglob("*.html")) + print(f"Scanning {len(html_files)} HTML files in {site_dir}/...") + + for html_file in html_files: + with open(html_file, "r", encoding="utf-8", errors="ignore") as f: + content = f.read() + + extractor = LinkExtractor() + try: + extractor.feed(content) + except Exception: + continue + + for href in extractor.links: + target = resolve_link(html_file, href, site_root) + if target is None: + continue + + checked += 1 + + # Only check links that should be inside the site + try: + target.relative_to(site_root) + except ValueError: + # Link points outside the site directory — skip + continue + + if not check_path_exists(target, site_root): + rel_source = html_file.relative_to(site_root) + broken.append((str(rel_source), href)) + + # Deduplicate + broken = sorted(set(broken)) + + print(f"Checked {checked} internal links.") + print() + + if broken: + print(f"BROKEN LINKS FOUND: {len(broken)}") + print("=" * 60) + + # Group by source file + by_source = {} + for source, href in broken: + by_source.setdefault(source, []).append(href) + + for source in sorted(by_source): + print(f"\n {source}:") + for href in sorted(by_source[source]): + print(f" → {href}") + + print() + print(f"Total: {len(broken)} broken link(s) in {len(by_source)} file(s).") + sys.exit(1) + else: + print("No broken internal links found.") + sys.exit(0) + + +if __name__ == "__main__": + main() diff --git a/scripts/netlify-build.sh b/scripts/netlify-build.sh index 2d05a4888..e28ac8023 100644 --- a/scripts/netlify-build.sh +++ b/scripts/netlify-build.sh @@ -8,4 +8,86 @@ git lfs pull # pip packages are automatically installed by netlify # if [ -f requirements.txt ]; then pip install -r requirements.txt; fi -python -m mkdocs build + +# On deploy previews, rewrite cross-site URLs to stay within the preview domain. +# On production, use the original configs with production URLs. +LEGACY_CFG="mkdocs.yml" +GUIDE_CFG="mkdocs-guide.yml" +INTERFACE_CFG="mkdocs-interface.yml" +CONCEPTS_CFG="mkdocs-concepts.yml" +RESOURCES_CFG="mkdocs-resources.yml" +DEVELOPERS_CFG="mkdocs-developers.yml" +CLI_CFG="mkdocs-cli.yml" +STANDARDS_CFG="mkdocs-standards.yml" + +cleanup() { + rm -f .preview-mkdocs.yml .preview-mkdocs-guide.yml .preview-mkdocs-interface.yml .preview-mkdocs-concepts.yml .preview-mkdocs-resources.yml .preview-mkdocs-developers.yml .preview-mkdocs-cli.yml .preview-mkdocs-standards.yml +} +trap cleanup EXIT + +if [ "$CONTEXT" = "deploy-preview" ] || [ "$CONTEXT" = "branch-deploy" ]; then + BASE_URL="${DEPLOY_PRIME_URL}" + echo "=== Deploy preview detected: rewriting cross-site URLs to ${BASE_URL} ===" + make_preview_config() { + local src="$1" + local dst=".preview-$(basename "$1")" + sed \ + -e "s|guide_url: https://docs.mat3ra.com/guide|guide_url: ${BASE_URL}/guide|" \ + -e "s|interface_url: https://docs.mat3ra.com/interface|interface_url: ${BASE_URL}/interface|" \ + -e "s|reference_url: https://docs.mat3ra.com/reference|reference_url: ${BASE_URL}/reference|" \ + -e "s|resources_url: https://docs.mat3ra.com/resources|resources_url: ${BASE_URL}/resources|" \ + -e "s|developers_url: https://docs.mat3ra.com/developers|developers_url: ${BASE_URL}/developers|" \ + -e "s|cli_url: https://docs.mat3ra.com/command-line|cli_url: ${BASE_URL}/command-line|" \ + -e "s|data_url: https://docs.mat3ra.com/standards|data_url: ${BASE_URL}/standards|" \ + -e "s|guide_url: https://docs.mat3ra.com$|guide_url: ${BASE_URL}|" \ + -e "s|interface_url: https://docs.mat3ra.com$|interface_url: ${BASE_URL}|" \ + -e "s|reference_url: https://docs.mat3ra.com$|reference_url: ${BASE_URL}|" \ + -e "s|resources_url: https://docs.mat3ra.com$|resources_url: ${BASE_URL}|" \ + -e "s|developers_url: https://docs.mat3ra.com$|developers_url: ${BASE_URL}|" \ + -e "s|cli_url: https://docs.mat3ra.com$|cli_url: ${BASE_URL}|" \ + -e "s|data_url: https://docs.mat3ra.com$|data_url: ${BASE_URL}|" \ + "$src" > "$dst" + echo "$dst" + } + LEGACY_CFG=$(make_preview_config mkdocs.yml) + GUIDE_CFG=$(make_preview_config mkdocs-guide.yml) + INTERFACE_CFG=$(make_preview_config mkdocs-interface.yml) + CONCEPTS_CFG=$(make_preview_config mkdocs-concepts.yml) + RESOURCES_CFG=$(make_preview_config mkdocs-resources.yml) + DEVELOPERS_CFG=$(make_preview_config mkdocs-developers.yml) + CLI_CFG=$(make_preview_config mkdocs-cli.yml) + STANDARDS_CFG=$(make_preview_config mkdocs-standards.yml) +fi + +# Legacy full site (root) +python -m mkdocs build -f "$LEGACY_CFG" + +# Split sites into subfolders +python -m mkdocs build -f "$GUIDE_CFG" -d site/guide +python -m mkdocs build -f "$INTERFACE_CFG" -d site/interface +python -m mkdocs build -f "$CONCEPTS_CFG" -d site/reference +python -m mkdocs build -f "$RESOURCES_CFG" -d site/resources +python -m mkdocs build -f "$DEVELOPERS_CFG" -d site/developers +python -m mkdocs build -f "$CLI_CFG" -d site/command-line +python -m mkdocs build -f "$STANDARDS_CFG" -d site/standards + +# Copy subsite homepages to root index.html, fixing relative paths +fix_and_copy_homepage() { + local src="$1" dst="$2" + [ -f "$src" ] && sed \ + -e 's|"base": ".."|"base": "."|' \ + -e 's|"\.\./assets/|"./assets/|g' \ + -e 's|"\.\./search/|"./search/|g' \ + -e 's|"\.\./extra/|"./extra/|g' \ + -e 's|"\.\./images/|"./images/|g' \ + -e 's|href="\.\./|href="./|g' \ + -e 's|src="\.\./|src="./|g' \ + "$src" > "$dst" || true +} +fix_and_copy_homepage site/guide/index-guide/index.html site/guide/index.html +fix_and_copy_homepage site/interface/index-interface/index.html site/interface/index.html +fix_and_copy_homepage site/reference/index-concepts/index.html site/reference/index.html +fix_and_copy_homepage site/resources/index-resources/index.html site/resources/index.html +fix_and_copy_homepage site/developers/index-developers/index.html site/developers/index.html +fix_and_copy_homepage site/command-line/index-cli/index.html site/command-line/index.html +fix_and_copy_homepage site/standards/index-standards/index.html site/standards/index.html diff --git a/scripts/rag/README.md b/scripts/rag/README.md new file mode 100644 index 000000000..746616b1b --- /dev/null +++ b/scripts/rag/README.md @@ -0,0 +1,85 @@ +# Docs RAG Agent — Minimal Demo (superseded) + +> **Superseded as of 2026-07-31.** This Phase-0 prototype has been rebuilt as +> an installable package with a provider abstraction, tests, and CI in the +> [`documentation-agent`](https://github.com/mat3ra/documentation-agent) +> repository (decision D6 in +> [`plans/docs-agent-implementation.md`](../../plans/docs-agent-implementation.md)). +> It is kept here only until that work is pushed, then removed. New work goes +> in the new repository. + + +A grounded question-answering agent over the Mat3ra documentation. It retrieves +relevant doc sections with BM25 and answers using **Claude Opus 4.6 on Google +Vertex AI**, citing `docs.mat3ra.com` URLs. This is the Phase-0 prototype +from [`plans/docs-agent-rag.md`](../../plans/docs-agent-rag.md). + +## What it does + +1. `ingest.py` walks `lang/en/docs/**/*.md`, resolves the mkdocs cross-site + macros, maps each page to its canonical URL, and splits pages into + heading-scoped chunks → `chunks.jsonl`. +2. `agent.py` loads those chunks into an in-memory BM25 index and runs an + agentic tool-use loop: Claude calls `search_docs`, reads the results, and + answers with citations. If retrieval finds nothing, it says so rather than + guessing. + +Deliberately minimal: lexical retrieval only (no embeddings/vector DB), no +reranking, no web service. Those are the next steps in the plan. + +## Setup + +```bash +cd scripts/rag +python3 -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +``` + +Set the Google Cloud project to use. It needs the **Vertex AI API** enabled and +access to the Anthropic Claude models granted in Model Garden: + +```bash +export VERTEX_PROJECT_ID=my-gcp-project +``` + +Then authenticate, either via Application Default Credentials: + +```bash +gcloud auth application-default login +gcloud auth application-default set-quota-project "$VERTEX_PROJECT_ID" +``` + +…or, if ADC is unavailable/stale, by passing a token from the active gcloud +account via `VERTEX_ACCESS_TOKEN` (see below). + +## Run + +```bash +python ingest.py # build chunks.jsonl + +# ADC configured: +python agent.py "How do I import a POSCAR file?" # one-shot +python agent.py # interactive REPL + +# Or pass a token from the active gcloud account (no ADC needed): +VERTEX_ACCESS_TOKEN=$(gcloud auth print-access-token) python agent.py "How do I import a POSCAR file?" +``` + +## Configuration + +| Env var | Default | Meaning | +| --------------------- | ----------------- | ------------------------------------------- | +| `VERTEX_PROJECT_ID` | _(required)_ | GCP project; falls back to `GOOGLE_CLOUD_PROJECT` | +| `VERTEX_REGION` | `us-east5` | Vertex endpoint (`us-east5`, `global`, …) | +| `RAG_MODEL` | `claude-opus-4-6` | Vertex Claude model ID | +| `VERTEX_ACCESS_TOKEN` | _(unset)_ | OAuth token to use instead of ADC; token is short-lived (~1h) | + +## Known limitations (demo scope) + +- BM25 only — no semantic matching; paraphrased queries can miss. Vector + + hybrid search is the next step. +- `--8<--` ESSE schema includes are dropped during ingest, so deep JSON-schema + questions are not yet answerable. +- No evaluation harness yet; correctness is spot-checked by hand. +- Index is rebuilt manually (`python ingest.py`); no CI refresh on merge. diff --git a/scripts/rag/agent.py b/scripts/rag/agent.py new file mode 100644 index 000000000..d287eab1c --- /dev/null +++ b/scripts/rag/agent.py @@ -0,0 +1,219 @@ +#!/usr/bin/env python3 +"""Minimal grounded docs agent: BM25 retrieval + Claude Opus 4.6 on Vertex AI. + +Runs an agentic tool-use loop against the documentation chunks produced by +``ingest.py``. Claude decides when to call ``search_docs``, reads the returned +chunks, and answers with citations to docs.mat3ra.com URLs. + +Prerequisites: + pip install -U google-cloud-aiplatform "anthropic[vertex]" rank_bm25 + gcloud auth application-default login # once, for ADC + python scripts/rag/ingest.py # produces chunks.jsonl + +Usage: + python scripts/rag/agent.py "How do I import a POSCAR file?" # one-shot + python scripts/rag/agent.py # interactive REPL + +Config via env vars: + VERTEX_PROJECT_ID Google Cloud project (required; falls back to + GOOGLE_CLOUD_PROJECT) + VERTEX_REGION (default: us-east5) + RAG_MODEL (default: claude-opus-4-6) +""" + +import json +import os +import re +import sys +from pathlib import Path + +from anthropic import AnthropicVertex +from rank_bm25 import BM25Okapi + +CHUNKS_PATH = Path(__file__).resolve().parent / "chunks.jsonl" + +PROJECT_ID = os.environ.get("VERTEX_PROJECT_ID") or os.environ.get("GOOGLE_CLOUD_PROJECT", "") +REGION = os.environ.get("VERTEX_REGION", "us-east5") +MODEL = os.environ.get("RAG_MODEL", "claude-opus-4-6") +# Optional: a pre-fetched OAuth token, e.g. +# VERTEX_ACCESS_TOKEN=$(gcloud auth print-access-token) python agent.py ... +# Use this when application-default credentials are unavailable/stale; when unset +# the SDK falls back to ADC (google.auth.default()). +ACCESS_TOKEN = os.environ.get("VERTEX_ACCESS_TOKEN") or None + +TOP_K = 6 +MAX_CHUNK_CHARS_IN_RESULT = 1600 +# Ceiling on search/answer round-trips within a single user turn. Guards against a +# runaway tool loop, which would otherwise never terminate and bill every request. +MAX_TOOL_ITERATIONS = 8 + +SYSTEM_PROMPT = """You are the Mat3ra platform documentation assistant. Mat3ra \ +(mat3ra.com) is a cloud platform for materials and chemicals simulation. + +Answer questions using ONLY content returned by the search_docs tool. Rules: +- Call search_docs before answering any question about the platform. Reformulate \ +and search again (different wording, or a section filter) if the first results \ +do not clearly answer the question. +- Ground every factual claim in a retrieved chunk. After the answer, list the \ +docs.mat3ra.com URLs you used under a "Sources:" heading. Only cite URLs that \ +appeared in a tool result — never invent URLs, REST endpoints, or UI element names. +- If retrieval does not contain the answer, say so plainly and suggest contacting \ +Mat3ra support rather than guessing. +- Be concise and use the docs' dry, third-person style. Answer in the user's language. + +Top-level documentation sections (use as the optional `section` filter): +tutorials, getting-started, materials, materials-designer, workflows, \ +workflow-designer, jobs, jobs-designer, jobs-cli, cli, rest-api, models, methods, \ +properties, models-directory, methods-directory, properties-directory, \ +software, software-directory, accounts, pricing, collaboration, security, \ +infrastructure, data-on-disk, remote-connection, jupyterlite, benchmarks.""" + +SEARCH_TOOL = { + "name": "search_docs", + "description": ( + "Full-text search over the Mat3ra documentation. Returns the most " + "relevant page sections, each with its docs.mat3ra.com URL. Call this " + "before answering any platform question; call it again with reformulated " + "queries if needed." + ), + "input_schema": { + "type": "object", + "properties": { + "query": { + "type": "string", + "description": "Natural-language search query.", + }, + "section": { + "type": "string", + "description": ( + "Optional top-level section to restrict results to, e.g. " + "'tutorials', 'rest-api', 'pricing'. Omit to search everything." + ), + }, + }, + "required": ["query"], + }, +} + +_TOKEN_RE = re.compile(r"[a-z0-9]+") + + +def tokenize(text: str) -> list[str]: + return _TOKEN_RE.findall(text.lower()) + + +class Retriever: + def __init__(self, chunks_path: Path): + if not chunks_path.exists(): + raise FileNotFoundError( + f"Missing {chunks_path}. Run: python scripts/rag/ingest.py" + ) + self.chunks = [json.loads(line) for line in chunks_path.read_text().splitlines() if line] + self.bm25 = BM25Okapi([tokenize(c["text"]) for c in self.chunks]) + + def search(self, query: str, section: str = "", k: int = TOP_K) -> list[dict]: + scores = self.bm25.get_scores(tokenize(query)) + order = sorted(range(len(scores)), key=lambda i: scores[i], reverse=True) + results = [] + for i in order: + if scores[i] <= 0: + continue + chunk = self.chunks[i] + if section and chunk["section"] != section.strip().lower(): + continue + results.append(chunk) + if len(results) >= k: + break + return results + + +def format_results(results: list[dict]) -> str: + if not results: + return "No matching documentation found. Try a different query or section." + blocks = [] + for n, c in enumerate(results, 1): + text = c["text"][:MAX_CHUNK_CHARS_IN_RESULT] + blocks.append(f"[{n}] {c['breadcrumb']}\nURL: {c['url']}\n\n{text}") + return "\n\n---\n\n".join(blocks) + + +def run_turn(client: AnthropicVertex, retriever: Retriever, messages: list[dict]) -> str: + """Run one user turn to completion, executing tool calls in a loop.""" + for _ in range(MAX_TOOL_ITERATIONS): + resp = client.messages.create( + model=MODEL, + max_tokens=4096, + system=[ + {"type": "text", "text": SYSTEM_PROMPT, "cache_control": {"type": "ephemeral"}} + ], + tools=[SEARCH_TOOL], + messages=messages, + ) + messages.append({"role": "assistant", "content": resp.content}) + + if resp.stop_reason != "tool_use": + return "".join(b.text for b in resp.content if b.type == "text") + + tool_results = [] + for block in resp.content: + if block.type != "tool_use": + continue + query = block.input.get("query", "") + section = block.input.get("section", "") + hits = retriever.search(query, section) + print(f" \033[2m[search_docs] {query!r}" + f"{f' section={section}' if section else ''} -> {len(hits)} hits\033[0m") + tool_results.append( + { + "type": "tool_result", + "tool_use_id": block.id, + "content": format_results(hits), + } + ) + messages.append({"role": "user", "content": tool_results}) + + return ( + f"Stopped after {MAX_TOOL_ITERATIONS} search rounds without reaching an " + "answer. Try asking a more specific question." + ) + + +def main() -> None: + if not PROJECT_ID: + sys.exit( + "Set VERTEX_PROJECT_ID (or GOOGLE_CLOUD_PROJECT) to the Google Cloud " + "project with access to Claude models on Vertex AI." + ) + try: + retriever = Retriever(CHUNKS_PATH) + except FileNotFoundError as exc: + sys.exit(str(exc)) + client = AnthropicVertex(project_id=PROJECT_ID, region=REGION, access_token=ACCESS_TOKEN) + print(f"\033[2mModel: {MODEL} via Vertex (project={PROJECT_ID}, region={REGION}) | " + f"{len(retriever.chunks)} chunks\033[0m\n") + + messages: list[dict] = [] + + if len(sys.argv) > 1: + question = " ".join(sys.argv[1:]) + messages.append({"role": "user", "content": question}) + print(run_turn(client, retriever, messages)) + return + + print("Ask a question about the Mat3ra platform (Ctrl-D or 'exit' to quit).\n") + while True: + try: + question = input("\033[1m> \033[0m").strip() + except EOFError: + break + if question.lower() in {"exit", "quit"}: + break + if not question: + continue + messages.append({"role": "user", "content": question}) + answer = run_turn(client, retriever, messages) + print(f"\n{answer}\n") + + +if __name__ == "__main__": + main() diff --git a/scripts/rag/ingest.py b/scripts/rag/ingest.py new file mode 100644 index 000000000..8b172b70e --- /dev/null +++ b/scripts/rag/ingest.py @@ -0,0 +1,146 @@ +#!/usr/bin/env python3 +"""Ingest the Mat3ra docs into a flat JSONL of retrievable chunks. + +Walks ``lang/en/docs/**/*.md``, resolves the mkdocs cross-site Jinja macros, +maps each page to its canonical docs.mat3ra.com URL, and splits pages into +heading-scoped chunks. Output: ``scripts/rag/chunks.jsonl`` (one JSON object +per line: id, url, title, section, heading, text). + +This is the minimal-demo ingester: lexical retrieval (BM25) is used downstream, +so no embeddings are produced here. ``--8<--`` include directives are dropped +(their content lives in the ESSE repo); resolving them is a later enhancement. + +Usage: + python scripts/rag/ingest.py +""" + +import json +import re +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[2] +DOCS_ROOT = REPO_ROOT / "lang" / "en" / "docs" +OUT_PATH = Path(__file__).resolve().parent / "chunks.jsonl" + +BASE_URL = "https://docs.mat3ra.com" + +# mkdocs-macros `extra:` values, resolved at ingest time exactly as the site build would. +MACROS = { + "guide_url": f"{BASE_URL}/guide", + "reference_url": f"{BASE_URL}/reference", + "dev_url": f"{BASE_URL}/dev", +} + +# Directories under lang/en/docs we do not want as answerable pages. +SKIP_DIRS = {"includes", "extra", "metadata"} + +MAX_CHUNK_CHARS = 6000 # split oversized heading sections so BM25 stays focused + + +def resolve_macros(text: str) -> str: + """Replace `{{ guide_url }}`-style macros and strip `{% raw %}` markers.""" + text = re.sub(r"{%-?\s*(end)?raw\s*-?%}", "", text) + for name, value in MACROS.items(): + text = re.sub(r"{{\s*" + name + r"\s*}}", value, text) + return text + + +def strip_frontmatter(text: str) -> str: + if text.startswith("---"): + end = text.find("\n---", 3) + if end != -1: + nl = text.find("\n", end + 1) + return text[nl + 1 :] if nl != -1 else "" + return text + + +def drop_includes(text: str) -> str: + """Remove markdown_include `--8<-- "..."` lines (content not inlined in the demo).""" + return re.sub(r'^\s*--8<--\s*".*?"\s*$', "", text, flags=re.MULTILINE) + + +def page_url(rel_path: Path) -> str: + """Map a repo-relative page path to its canonical full-site URL. + + The legacy full site serves every page, so this mapping always resolves: + ``workflows/overview.md`` -> ``/workflows/overview/`` and + ``workflows/index.md`` -> ``/workflows/``. + """ + parts = list(rel_path.with_suffix("").parts) + if parts and parts[-1] == "index": + parts = parts[:-1] + slug = "/".join(parts) + return f"{BASE_URL}/{slug}/" if slug else f"{BASE_URL}/" + + +def extract_title(body: str, rel_path: Path) -> str: + for line in body.splitlines(): + m = re.match(r"#\s+(.*)", line) + if m: + return m.group(1).strip() + return rel_path.stem.replace("-", " ").title() + + +def split_into_sections(body: str): + """Yield (heading, section_text) tuples split on H2 boundaries. + + The preamble before the first H2 (which includes the H1) is emitted with an + empty heading. Sections longer than MAX_CHUNK_CHARS are hard-split. + """ + lines = body.splitlines() + heading = "" + buf: list[str] = [] + + def flush(h, b): + text = "\n".join(b).strip() + if not text: + return + for i in range(0, len(text), MAX_CHUNK_CHARS): + yield h, text[i : i + MAX_CHUNK_CHARS] + + for line in lines: + m = re.match(r"##\s+(.*)", line) + if m: + yield from flush(heading, buf) + heading = m.group(1).strip() + buf = [] + else: + buf.append(line) + yield from flush(heading, buf) + + +def main() -> None: + rows = [] + for path in sorted(DOCS_ROOT.rglob("*.md")): + rel = path.relative_to(DOCS_ROOT) + if set(rel.parts) & SKIP_DIRS: + continue + raw = path.read_text(encoding="utf-8") + body = drop_includes(resolve_macros(strip_frontmatter(raw))) + title = extract_title(body, rel) + section = rel.parts[0] if len(rel.parts) > 1 else "root" + url = page_url(rel) + for idx, (heading, text) in enumerate(split_into_sections(body)): + breadcrumb = f"{title} > {heading}" if heading else title + rows.append( + { + "id": f"{rel.as_posix()}#{idx}", + "url": url, + "title": title, + "section": section, + "heading": heading, + "breadcrumb": breadcrumb, + "text": f"{breadcrumb}\n\n{text}", + } + ) + + with OUT_PATH.open("w", encoding="utf-8") as f: + for row in rows: + f.write(json.dumps(row, ensure_ascii=False) + "\n") + + pages = len({r["id"].split("#")[0] for r in rows}) + print(f"Ingested {pages} pages -> {len(rows)} chunks -> {OUT_PATH}") + + +if __name__ == "__main__": + main() diff --git a/scripts/rag/requirements.txt b/scripts/rag/requirements.txt new file mode 100644 index 000000000..a75aceb20 --- /dev/null +++ b/scripts/rag/requirements.txt @@ -0,0 +1,3 @@ +anthropic[vertex]>=0.40 +google-cloud-aiplatform>=1.60 +rank_bm25>=0.2.2 diff --git a/scripts/serve-all.sh b/scripts/serve-all.sh new file mode 100755 index 000000000..5be6c9022 --- /dev/null +++ b/scripts/serve-all.sh @@ -0,0 +1,163 @@ +#!/bin/bash +# Build and serve all documentation sites locally. +# +# Usage: +# ./scripts/serve-all.sh # build + serve on localhost:8000 +# ./scripts/serve-all.sh --build # build only, no server +# ./scripts/serve-all.sh --serve # serve only, skip build (uses existing site/) +# +# Cross-site links automatically resolve to localhost for local testing. + +set -euo pipefail +cd "$(dirname "$0")/.." + +# Activate venv if present +if [ -f .venv/bin/activate ]; then + source .venv/bin/activate +elif [ -f venv/bin/activate ]; then + source venv/bin/activate +fi + +PORT="${PORT:-8000}" +LOCAL_BASE="http://localhost:${PORT}" + +# --serve: skip build, just start the server on existing site/ +if [ "${1:-}" = "--serve" ]; then + if [ ! -d site ]; then + echo "Error: site/ directory not found. Run without --serve first to build." >&2 + exit 1 + fi + echo "Serving existing site/ on ${LOCAL_BASE} (no rebuild)" + echo " ${LOCAL_BASE}/guide/" + echo " ${LOCAL_BASE}/interface/" + echo " ${LOCAL_BASE}/reference/" + echo " ${LOCAL_BASE}/resources/" + echo " ${LOCAL_BASE}/developers/" + echo " ${LOCAL_BASE}/command-line/" + echo " ${LOCAL_BASE}/standards/" + echo "" + echo "Press Ctrl+C to stop." + python -m http.server "$PORT" --directory site + exit 0 +fi + +# Create local config overrides in project root (relative paths stay valid) +make_local_config() { + local src="$1" + local dst=".local-$(basename "$1")" + sed \ + -e "s|guide_url: https://docs.mat3ra.com/guide|guide_url: ${LOCAL_BASE}/guide|" \ + -e "s|interface_url: https://docs.mat3ra.com/interface|interface_url: ${LOCAL_BASE}/interface|" \ + -e "s|reference_url: https://docs.mat3ra.com/reference|reference_url: ${LOCAL_BASE}/reference|" \ + -e "s|resources_url: https://docs.mat3ra.com/resources|resources_url: ${LOCAL_BASE}/resources|" \ + -e "s|developers_url: https://docs.mat3ra.com/developers|developers_url: ${LOCAL_BASE}/developers|" \ + -e "s|cli_url: https://docs.mat3ra.com/command-line|cli_url: ${LOCAL_BASE}/command-line|" \ + -e "s|data_url: https://docs.mat3ra.com/standards|data_url: ${LOCAL_BASE}/standards|" \ + -e "s|guide_url: https://docs.mat3ra.com$|guide_url: ${LOCAL_BASE}|" \ + -e "s|interface_url: https://docs.mat3ra.com$|interface_url: ${LOCAL_BASE}|" \ + -e "s|reference_url: https://docs.mat3ra.com$|reference_url: ${LOCAL_BASE}|" \ + -e "s|resources_url: https://docs.mat3ra.com$|resources_url: ${LOCAL_BASE}|" \ + -e "s|developers_url: https://docs.mat3ra.com$|developers_url: ${LOCAL_BASE}|" \ + -e "s|cli_url: https://docs.mat3ra.com$|cli_url: ${LOCAL_BASE}|" \ + -e "s|data_url: https://docs.mat3ra.com$|data_url: ${LOCAL_BASE}|" \ + "$src" > "$dst" + echo "$dst" +} + +cleanup() { + rm -f .local-mkdocs.yml .local-mkdocs-guide.yml .local-mkdocs-interface.yml .local-mkdocs-concepts.yml .local-mkdocs-resources.yml .local-mkdocs-developers.yml .local-mkdocs-cli.yml .local-mkdocs-standards.yml +} +trap cleanup EXIT + +LOCAL_LEGACY=$(make_local_config mkdocs.yml) +LOCAL_GUIDE=$(make_local_config mkdocs-guide.yml) +LOCAL_INTERFACE=$(make_local_config mkdocs-interface.yml) +LOCAL_CONCEPTS=$(make_local_config mkdocs-concepts.yml) +LOCAL_RESOURCES=$(make_local_config mkdocs-resources.yml) +LOCAL_DEVELOPERS=$(make_local_config mkdocs-developers.yml) +LOCAL_CLI=$(make_local_config mkdocs-cli.yml) +LOCAL_STANDARDS=$(make_local_config mkdocs-standards.yml) + +echo "=== Building legacy site (root) ===" +python -m mkdocs build -f "$LOCAL_LEGACY" + +echo "" +echo "=== Building Tutorials → site/guide/ ===" +python -m mkdocs build -f "$LOCAL_GUIDE" -d site/guide + +echo "" +echo "=== Building User Interface → site/interface/ ===" +python -m mkdocs build -f "$LOCAL_INTERFACE" -d site/interface + +echo "" +echo "=== Building Concepts → site/reference/ ===" +python -m mkdocs build -f "$LOCAL_CONCEPTS" -d site/reference + +echo "" +echo "=== Building Resources → site/resources/ ===" +python -m mkdocs build -f "$LOCAL_RESOURCES" -d site/resources + +echo "" +echo "=== Building Developers → site/developers/ ===" +python -m mkdocs build -f "$LOCAL_DEVELOPERS" -d site/developers + +echo "" +echo "=== Building Command-Line Interface → site/command-line/ ===" +python -m mkdocs build -f "$LOCAL_CLI" -d site/command-line + +echo "" +echo "=== Building Data Standards → site/standards/ ===" +python -m mkdocs build -f "$LOCAL_STANDARDS" -d site/standards + +# Each subsite's homepage is built as index-/index.html. +# Copy to root, fixing relative paths (base ".." → "." since we move up one level). +fix_and_copy_homepage() { + local src="$1" + local dst="$2" + if [ -f "$src" ]; then + sed \ + -e 's|"base": ".."|"base": "."|' \ + -e 's|"\.\./assets/|"./assets/|g' \ + -e 's|"\.\./search/|"./search/|g' \ + -e 's|"\.\./extra/|"./extra/|g' \ + -e 's|"\.\./images/|"./images/|g' \ + -e 's|href="\.\./|href="./|g' \ + -e 's|src="\.\./|src="./|g' \ + "$src" > "$dst" + fi +} +fix_and_copy_homepage site/guide/index-guide/index.html site/guide/index.html +fix_and_copy_homepage site/interface/index-interface/index.html site/interface/index.html +fix_and_copy_homepage site/reference/index-concepts/index.html site/reference/index.html +fix_and_copy_homepage site/resources/index-resources/index.html site/resources/index.html +fix_and_copy_homepage site/developers/index-developers/index.html site/developers/index.html +fix_and_copy_homepage site/command-line/index-cli/index.html site/command-line/index.html +fix_and_copy_homepage site/standards/index-standards/index.html site/standards/index.html + +echo "" +echo "Build complete. Output in site/" +echo " site/ → legacy full site" +echo " site/guide/ → Tutorials" +echo " site/interface/ → User Interface" +echo " site/reference/ → Concepts & Reference" +echo " site/resources/ → Resources / Infrastructure" +echo " site/developers/ → Developers" +echo " site/command-line/ → Command-Line Interface" +echo " site/standards/ → Data Standards" + +if [ "${1:-}" = "--build" ]; then + exit 0 +fi + +echo "" +echo "Starting local server on ${LOCAL_BASE}" +echo " ${LOCAL_BASE}/guide/" +echo " ${LOCAL_BASE}/interface/" +echo " ${LOCAL_BASE}/reference/" +echo " ${LOCAL_BASE}/resources/" +echo " ${LOCAL_BASE}/developers/" +echo " ${LOCAL_BASE}/command-line/" +echo " ${LOCAL_BASE}/standards/" +echo "" +echo "Cross-site links resolve to localhost. Press Ctrl+C to stop." +python -m http.server "$PORT" --directory site diff --git a/scripts/video-manager.py b/scripts/video-manager.py index f5f10ff75..ed3b652b7 100755 --- a/scripts/video-manager.py +++ b/scripts/video-manager.py @@ -180,21 +180,40 @@ def insert_caption(youtube_, youtube_id_, name, content): return request.execute() -def create_SSML_text(metadata_): +def create_SSML_text(metadata_, skip=None, until=None): """ Creates SSML text from metadata. See https://cloud.google.com/text-to-speech/docs/ssml for more information. + + The optional `skip` and `until` arguments allow generating the voiceover + in parts to stay within the Google TextToSpeech API's per-request limits. + Captions whose `startTime` is before `skip` are dropped, and iteration + stops once a caption's `startTime` reaches `until`. Leading silence on + the resulting audio is shortened to the gap between `skip` and the first + kept caption, so each part can be aligned back to the original timeline + with `ffmpeg -itsoffset `. Please use exact end times of a segment as + `skip` and `until` values. + Args: metadata_ (dict): video metadata. + skip (str|None): caption timestamp (`HH:MM:SS.MS`) to start from. + until (str|None): caption timestamp (`HH:MM:SS.MS`) to stop at. Returns: str """ + skip_ms = caption_time_to_milliseconds(skip) if skip else 0 + until_ms = caption_time_to_milliseconds(until) if until else None text = "" - previous_end = 0 + previous_end = skip_ms for caption in metadata_["youTubeCaptions"]: - silence = caption_time_to_milliseconds(caption["startTime"]) - previous_end + start_ms = caption_time_to_milliseconds(caption["startTime"]) + if start_ms < skip_ms: + continue + if until_ms is not None and start_ms >= until_ms: + break + silence = start_ms - previous_end text = "".join((text, f"", caption["text"])) previous_end = caption_time_to_milliseconds(caption["endTime"]) return "".join(("", text, "")) @@ -230,15 +249,24 @@ def convert_text_to_speech(ssml_text, speech_path): update.add_argument('--privacyStatus', default="unlisted", help='video privacy status') voiceover = subparsers.add_parser('voiceover') - voiceover.add_argument('--file', required=True, help='video file path') + voiceover.add_argument('--file', help='video file path (required only when --output is set)') voiceover.add_argument('--metadata', required=True, help='video metadata file path') - voiceover.add_argument('--audio', help='path to store audio file') + voiceover.add_argument('--audio', required=True, help='path to store audio file') voiceover.add_argument('--output', help='path to store voiceover video file') voiceover.add_argument('--privacyStatus', default="unlisted", help='video privacy status') + voiceover.add_argument( + '--skip', default=None, + help='skip captions before this timestamp, e.g. 00:05:30.500 (HH:MM:SS.MS)', + ) + voiceover.add_argument( + '--until', default=None, + help='stop at captions at/after this timestamp, e.g. 00:10:00.000 (HH:MM:SS.MS)', + ) args = argparser.parse_args() - if not os.path.exists(args.file): + video_file = getattr(args, "file", None) + if video_file and not os.path.exists(video_file): exit("video file does not exist!") if not os.path.exists(args.metadata): exit("metadata file does not exist!") @@ -268,6 +296,9 @@ def convert_text_to_speech(ssml_text, speech_path): update_metadata(args.metadata, {"youTubeId": youtube_id}) if args.command == "voiceover": - ssml_text = create_SSML_text(metadata) + ssml_text = create_SSML_text(metadata, skip=args.skip, until=args.until) convert_text_to_speech(ssml_text, args.audio) - os.system(FFMPEG_COMMAND_TMPL.format(args.file, args.audio, args.output)) + if args.output: + if not args.file: + exit("--file is required when --output is set") + os.system(FFMPEG_COMMAND_TMPL.format(args.file, args.audio, args.output)) diff --git a/tests/widget/README.md b/tests/widget/README.md new file mode 100644 index 000000000..485c6637f --- /dev/null +++ b/tests/widget/README.md @@ -0,0 +1,54 @@ +# Ask AI widget — browser tests + +Playwright tests for the documentation assistant widget +(`extra/js/docs-agent.js`). + +```bash +cd tests/widget +npm install +npx playwright install chromium +npm test +``` + +## What is real and what is faked + +The **widget is real** — the tests load the file the documentation site ships, +through a fixture page that mounts it the way the site does. + +The **agent service is faked** at the network boundary (`mock-agent.js`). A test +that called a language model would be neither deterministic nor free, and what +is under test is the widget's behaviour, not the model's; the service is covered +by its own suite in the `documentation-agent` repository. + +`server.js` synthesises a page for *every* path. Answers cite canonical +`docs.mat3ra.com` URLs which the widget rewrites onto the origin being read, so +following a citation has to land on a page that mounts the widget again — that +navigation is the thing several tests are about. + +Both mounting styles are covered, because they differ: `?automount=1` loads the +page the way the documentation site does, where the widget only appears once the +service passes a health check; the default mounts explicitly, the way the +platform application will. + +## What is covered + +- **Mounting** — the launcher appears when the service is healthy, and a + documentation page is left untouched when it is not. +- **Rendering** — Markdown becomes structure; searches are announced while they + run. +- **Links** — cited URLs are clickable, known product terms link to the page + that defines them, unknown emphasis stays plain, links open in the same tab + and are coloured, and citations stay on the build being read. +- **Safety** — markup in an answer is displayed rather than executed, and a + non-https link never becomes clickable. +- **The conversation** — it survives a reload and a followed citation, the panel + reopens only if it was open, "New chat" ends it, a week-old conversation is + discarded, and the widget still works where storage is unavailable. + +## Keeping the suite honest + +A green suite means nothing until it has been seen to fail. Both regressions +these tests were written for have been reintroduced deliberately and confirmed +to fail the run: restoring `target="_blank"` fails *links open in the same tab*, +and skipping session restoration fails *it is restored after a reload*. Do the +same when adding a test — break the behaviour first, watch it go red. diff --git a/tests/widget/mock-agent.js b/tests/widget/mock-agent.js new file mode 100644 index 000000000..08d0400f6 --- /dev/null +++ b/tests/widget/mock-agent.js @@ -0,0 +1,59 @@ +/** + * The agent service, faked at the network boundary. + * + * The widget is tested against canned responses rather than the deployed + * service: a test that calls a language model is neither deterministic nor + * free, and what is under test here is the widget's behaviour, not the + * model's. The service's own behaviour is covered by its Python suite. + */ + +const GLOSSARY = { + "materials bank": "https://docs.mat3ra.com/materials/bank/", + "materials designer": "https://docs.mat3ra.com/materials-designer/overview/", +}; + +/** An answer body, as the service streams it. */ +function sse(events) { + return events.map(([name, data]) => `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`).join(""); +} + +const DEFAULT_ANSWER = sse([ + ["status", { message: "Searching the documentation", query: "materials bank" }], + ["text", { text: "## Importing\n\nUse the **Materials Bank** or the " }], + ["text", { text: "**Materials Designer**. Bold **Second unit (NSCF):** is not a term.\n\n" }], + ["text", { text: "1. Open the bank\n2. Copy the material\n\n```bash\nqstat\n```\n\n" }], + ["text", { text: "Sources:\n\n- https://docs.mat3ra.com/materials/bank/\n" }], + ["sources", { urls: ["https://docs.mat3ra.com/materials/bank/"] }], + ["done", {}], +]); + +/** + * Route the widget's calls to `https://agent.test`. + * + * @param {import('@playwright/test').Page} page + * @param {{healthy?: boolean, answer?: string}} options + */ +async function mockAgent(page, options = {}) { + const healthy = options.healthy !== false; + const answer = options.answer || DEFAULT_ANSWER; + + await page.route("https://agent.test/health", (route) => + healthy + ? route.fulfill({ status: 200, contentType: "application/json", body: '{"status":"ok"}' }) + : route.abort() + ); + + await page.route("https://agent.test/glossary", (route) => + route.fulfill({ + status: 200, + contentType: "application/json", + body: JSON.stringify({ terms: GLOSSARY }), + }) + ); + + await page.route("https://agent.test/chat", (route) => + route.fulfill({ status: 200, contentType: "text/event-stream", body: answer }) + ); +} + +module.exports = { mockAgent, sse, GLOSSARY }; diff --git a/tests/widget/package-lock.json b/tests/widget/package-lock.json new file mode 100644 index 000000000..afd9ea3d2 --- /dev/null +++ b/tests/widget/package-lock.json @@ -0,0 +1,76 @@ +{ + "name": "docs-agent-widget-tests", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "docs-agent-widget-tests", + "devDependencies": { + "@playwright/test": "^1.49.0" + } + }, + "node_modules/@playwright/test": { + "version": "1.62.1", + "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.62.1.tgz", + "integrity": "sha512-DTcUc8qii+cpHvtOwggMtBRMjKZHXYWdw8syRYu2vtzuq4Wxphqq4NfCs5Zt44L6mA8rfDfj+PHnxFc/FeK6mQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "playwright": "1.62.1" + }, + "bin": { + "playwright": "cli.js" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/fsevents": { + "version": "2.3.2", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz", + "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, + "node_modules/playwright": { + "version": "1.62.1", + "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.62.1.tgz", + "integrity": "sha512-0M+L3LAD8/nm554LOla9Ayx0j0tmFZ0FBcoQ7F1VuVHpM/XpiC8RcDzBQB8W5+hA8L22THxELzeF+2WcUzvcLg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "playwright-core": "1.62.1" + }, + "bin": { + "playwright": "cli.js" + }, + "engines": { + "node": ">=20" + }, + "optionalDependencies": { + "fsevents": "2.3.2" + } + }, + "node_modules/playwright-core": { + "version": "1.62.1", + "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.62.1.tgz", + "integrity": "sha512-wPYSwEBJY9GHraISXqyqtx0na0LpO3XEX7jNDhntbex7tzUS7kLnZsOlFruFJB4Hi/rhDMjXGqHewDZ68nYZVw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "playwright-core": "cli.js" + }, + "engines": { + "node": ">=20" + } + } + } +} diff --git a/tests/widget/package.json b/tests/widget/package.json new file mode 100644 index 000000000..6370be0eb --- /dev/null +++ b/tests/widget/package.json @@ -0,0 +1,13 @@ +{ + "name": "docs-agent-widget-tests", + "private": true, + "description": "Browser tests for the Ask AI documentation widget.", + "scripts": { + "test": "playwright test", + "test:headed": "playwright test --headed", + "report": "playwright show-report" + }, + "devDependencies": { + "@playwright/test": "^1.49.0" + } +} diff --git a/tests/widget/playwright.config.js b/tests/widget/playwright.config.js new file mode 100644 index 000000000..8ebff9efc --- /dev/null +++ b/tests/widget/playwright.config.js @@ -0,0 +1,25 @@ +const { defineConfig, devices } = require("@playwright/test"); + +const PORT = Number(process.env.PORT || 4173); +const baseURL = `http://localhost:${PORT}`; + +module.exports = defineConfig({ + testDir: __dirname, + fullyParallel: true, + forbidOnly: !!process.env.CI, + retries: process.env.CI ? 1 : 0, + reporter: process.env.CI ? [["github"], ["list"]] : [["list"]], + use: { + baseURL, + trace: "on-first-retry", + }, + projects: [ + { name: "chromium", use: { ...devices["Desktop Chrome"], baseURL } }, + ], + webServer: { + command: `node ${__dirname}/server.js`, + url: baseURL, + reuseExistingServer: !process.env.CI, + env: { PORT: String(PORT) }, + }, +}); diff --git a/tests/widget/server.js b/tests/widget/server.js new file mode 100644 index 000000000..6ee4e24e4 --- /dev/null +++ b/tests/widget/server.js @@ -0,0 +1,73 @@ +#!/usr/bin/env node +/** + * Static server for the widget tests. + * + * Serves the real widget assets from the repository, and synthesises a stub + * documentation page for every other path. That second part matters: answers + * cite canonical docs.mat3ra.com URLs which the widget rewrites onto the origin + * being read, so the test needs every such path to resolve to a page that + * mounts the widget again — that is precisely the navigation being tested. + */ + +const http = require("http"); +const fs = require("fs"); +const path = require("path"); + +const REPO_ROOT = path.resolve(__dirname, "..", ".."); +const PORT = Number(process.env.PORT || 4173); + +const TYPES = { ".js": "text/javascript", ".css": "text/css" }; + +/** + * Two ways to mount, because the widget supports two and they behave + * differently: the documentation site lets the script mount itself only once + * the service passes a health check, while the platform will mount it + * explicitly. `?automount=1` exercises the first, the default the second. + */ +const PAGE = (pathname, autoMount) => ` + + + + Docs fixture ${pathname} + + + +

Documentation fixture

+

${pathname}

+
+${ + autoMount + ? ` + ` + : ` + + ` +} + +`; + +const server = http.createServer((request, response) => { + const url = new URL(request.url, "http://localhost"); + const pathname = url.pathname; + + if (pathname.startsWith("/extra/")) { + const file = path.join(REPO_ROOT, pathname); + if (fs.existsSync(file)) { + response.writeHead(200, { "Content-Type": TYPES[path.extname(file)] || "text/plain" }); + response.end(fs.readFileSync(file)); + return; + } + response.writeHead(404).end("not found"); + return; + } + + response.writeHead(200, { "Content-Type": "text/html" }); + response.end(PAGE(pathname, url.searchParams.get("automount") === "1")); +}); + +server.listen(PORT, () => console.log(`fixture server on http://localhost:${PORT}`)); diff --git a/tests/widget/widget.spec.js b/tests/widget/widget.spec.js new file mode 100644 index 000000000..afbb734b7 --- /dev/null +++ b/tests/widget/widget.spec.js @@ -0,0 +1,220 @@ +const { test, expect } = require("@playwright/test"); +const { mockAgent, sse } = require("./mock-agent"); + +const LAUNCHER = ".docs-agent-launcher"; +const PANEL = ".docs-agent-panel"; +const MESSAGES = ".docs-agent-message"; + +async function ask(page, question = "How do I import a material?", expected = "Importing") { + await page.click(LAUNCHER); + await page.fill(".docs-agent-form input", question); + await page.click(".docs-agent-form button[type=submit]"); + await expect(page.locator(MESSAGES).last()).toContainText(expected); +} + +test.describe("mounting", () => { + test("the launcher appears once the service answers its health check", async ({ page }) => { + await mockAgent(page); + await page.goto("/?automount=1"); + await expect(page.locator(LAUNCHER)).toBeVisible(); + }); + + test("a documentation page is untouched when the service is unreachable", async ({ page }) => { + // The widget must never leave a control that leads nowhere, and must never + // break the page it is embedded in. + await mockAgent(page, { healthy: false }); + await page.goto("/?automount=1"); + await page.waitForLoadState("networkidle"); + + await expect(page.locator(LAUNCHER)).toHaveCount(0); + await expect(page.locator("h1")).toContainText("Documentation fixture"); + }); +}); + +test.describe("answers", () => { + test.beforeEach(async ({ page }) => { + await mockAgent(page); + await page.goto("/"); + }); + + test("markdown is rendered as structure, not as text", async ({ page }) => { + await ask(page); + const answer = page.locator(MESSAGES).last(); + + await expect(answer.locator("h4, h3")).toHaveCount(1); + await expect(answer.locator("ol li")).toHaveCount(2); + await expect(answer.locator("pre code")).toContainText("qstat"); + }); + + test("a search in progress is announced", async ({ page }) => { + let release; + const held = new Promise((resolve) => (release = resolve)); + await page.route("https://agent.test/chat", async (route) => { + await held; + route.fulfill({ status: 200, contentType: "text/event-stream", body: sse([["done", {}]]) }); + }); + + await page.click(LAUNCHER); + await page.fill(".docs-agent-form input", "anything"); + await page.click(".docs-agent-form button[type=submit]"); + await expect(page.locator(".docs-agent-status")).toBeVisible(); + release(); + }); + + test("known product terms link to the page that defines them", async ({ page }) => { + await ask(page); + const term = page.locator("a.docs-agent-term", { hasText: "Materials Bank" }); + await expect(term).toHaveAttribute("href", /\/materials\/bank\/$/); + }); + + test("emphasis the glossary does not know stays plain", async ({ page }) => { + // Over-linking is the failure mode here: a link to the wrong page looks + // deliberate, so anything unrecognised must remain bold text. + await ask(page); + const answer = page.locator(MESSAGES).last(); + const plain = answer.locator("strong", { hasText: "Second unit (NSCF):" }); + + await expect(plain).toHaveCount(1); + await expect(plain.locator("a")).toHaveCount(0); + }); + + test("cited URLs are clickable", async ({ page }) => { + await ask(page); + const links = page.locator(`${MESSAGES} a`); + expect(await links.count()).toBeGreaterThan(0); + }); + + test("links open in the same tab and look like links", async ({ page }) => { + await ask(page); + const link = page.locator(`${MESSAGES} a`).first(); + + await expect(link).not.toHaveAttribute("target", "_blank"); + const colour = await link.evaluate((node) => getComputedStyle(node).color); + expect(colour).not.toBe("rgb(0, 0, 0)"); + }); + + test("citations stay on the documentation build being read", async ({ page }, testInfo) => { + // The corpus stores canonical production URLs. On a preview or a local + // build, following one verbatim would leave the site — and the stored + // conversation, which is per-origin, behind with it. + await ask(page); + const hrefs = await page.locator(`${MESSAGES} a`).evaluateAll((nodes) => + nodes.map((node) => node.href) + ); + + expect(hrefs.length).toBeGreaterThan(0); + for (const href of hrefs) { + expect(href.startsWith(testInfo.project.use.baseURL)).toBeTruthy(); + } + }); +}); + +test.describe("safety", () => { + test("markup in an answer is shown, never executed", async ({ page }) => { + const hostile = sse([ + [ + "text", + { + text: + "Try and " + + "