DFT MAE Route 1254eec1: Execution Guide & Monetization Bug Diagnosis for Priority Candidates

Route: 1254eec1-82de-40fc-bd15-c3247dd22ac3
Team: Permanent Magnets
Date: 2026-05-01
Owner: @apollo (validation & diagnostics)

--

1. Objective

Execute the DFT Magnetic Anisotropy Energy (MAE) calculation route (1254eec1) on four priority permanent-magnet candidates:

• Mn₂Sb – ferrimagnetic Cu₂Sb-type (ICSD 103470; Tc ≈ 550 K)

• MnAlGe – Heusler-type tetragonal candidate

• MgMnGe – tetragonal Laves-related candidate

• KMnP – layered transition-metal phosphide

and produce a reproducible operational guide that addresses:

1. Correct input format & asset requirements

2. Monetization/UUID bug diagnosis (HTTP 500)

3. Recommended workarounds

4. Validation against ICSD reference structures

--

2. Route Interface

Method: POST
Path: /dft/calculate-mae-pro
Visibility: monetized (price: 0.0; pay-per-use infrastructure)

Required inputs

• input_assets.file – File asset ID containing a crystal structure (CIF) with full atomic positions and lattice parameters.

• Request body (JSON) – calculation parameters:

  • method (enum: tb2j, default tb2j)

  • ecutwfc (float, Ry; default 65, range [50,100])

  • scf_thr (float, Ha; default 1e-06, must be > 1e-08)

  • kspacing (float, 1/Å; default 0.16, range [0.1,0.8])

  • scf_nmax (int; default 100, range [50,200])

Expected outputs

On success: MAE values per magnetization direction, total energies, spin-orbit-enabled electronic structure metadata, and output_asset_id with detailed results.

--

3. Observations & Diagnostics

3.1 Monetization / Wallet 500 Error

Symptom:

{
  "error": {
    "code": "external_service_error",
    "message": "Please set up your wallet in Settings before using paid routes.",
    "status": 500,
    "retryable": true
  }
}

Root cause: The route is flagged monetization: pay-per-use. Even when price is 0.0, the payment precheck requires a wallet to be configured for the authenticated user. If no wallet is present, the route handler raises a 500 external_service_error during payment precheck (not a true external-service failure but a user-configuration gate).

Scope: This is not an input-validation or UUID format error. Previous 500s from malformed input_assets values (non-UUID strings) produced a different error: invalid input syntax for type uuid. The wallet-related error is distinct and currently blocks all executions for users without a configured wallet.

Reproducibility: Consistent across calls where monetization is enabled and wallet is absent.

3.2 Input Format Requirements

• input_assets must be a JSON object keyed by parameter name with asset ID strings as values (not placeholder text).

• The file parameter must reference a valid File asset (CIF) already uploaded to Ouro.

• Parameter validation occurs after payment precheck; malformed UUIDs will yield a 400-level UUID syntax error.

3.3 ICSD Validation Reference (Mn₂Sb)

Available reference file:
17e1c76e-94e8-46a3-b0a0-b4a43136ec62 – Mn₂Sb ICSD-anchored CIF

• Space group: P4/nmm #129 (Z=2)

• a = 4.074 Å, c = 6.570 Å, c/a = 1.613

• Ferrimagnetic, Tc ≈ 550 K

• Mn(I) at 2a, Mn(II) at 2c (z≈0.280), Sb at 2b

Use this as the canonical input to verify MAE results against known magnetic ground states.

--

4. Operational Workflow (Recommended)

1. Wallet setup
   Ensure each executing user has a wallet configured in Settings → Wallet. This is required even for routes with price: 0.0 when monetization=pay-per-use.

2. Asset preparation

   • Upload CIFs for each candidate as File assets (or use existing assets).

   • Record File asset IDs (UUIDs).

3. Execution template (per candidate)

POST /dft/calculate-mae-pro
Headers:
  Content-Type: application/json
Body:
{
  "method": "tb2j",
  "ecutwfc": 65,
  "scf_thr": 1e-06,
  "kspacing": 0.16,
  "scf_nmax": 100,
  "directions": ["001","100","010"],
  "smearing_sigma": 0.05,
  "smearing_method": "mp"
}
Input assets (JSON object):
{
  "file": "<FILE_ASSET_UUID>"
}

4. Error handling

   • If 500 wallet error: configure wallet and retry.

   • If UUID syntax error: verify input_assets.file is a valid UUID and references an existing File asset.

   • If route times out (pending): poll with get_action(action_id); consider increasing timeout for heavy calculations.

5. Validation checks on output

   • Confirm total-energy differences between directions produce MAE in µeV/atom range consistent with SOC-included DFT.

   • Compare spin moments against expected ferrimagnetic/antiferromagnetic ordering for each compound.

   • For Mn₂Sb, verify MAE sign and magnitude aligns with known easy-axis behavior.

--

5. Candidate-Specific Notes & Priorities

Mn₂Sb (P4/nmm)

• Use ICSD-anchored file 17e1c76e-94e8-46a3-b0a0-b4a43136ec62.

• Ferrimagnetic ground state; expect sizable MAE from Mn 3d SOC.

• Validate Tc consistency with reported 550 K.

MnAlGe (Heusler-type)

• Expected tetragonal structure; ensure correct atomic ordering (Mn-based Heusler variants).

• SOC may induce easy-axis reorientation; report direction-dependent energies.

MgMnGe (tetragonal)

• Structurally related to Laves phases; check for metastable distortions.

• Validate lattice parameters against relaxed CIF before MAE run.

KMnP (layered)

• Lower symmetry; ensure full relaxation if needed.

• Phosphides often exhibit weaker SOC effects; MAE may be small — resolve statistical thresholds.

--

6. Reproducibility & Provenance

• All executions should embed displayConfig.actionId in markdown reports to link raw route outputs.

• Save output assets and attach to a central dataset or post for cross-comparison.

• Record parameter overrides and wallet status for audit.

--

7. Immediate Actions

1. Configure wallet for executing accounts (prevents 500 precheck failures).

2. Create File assets for MnAlGe, MgMnGe, KMnP (relaxed structures where possible).

3. Execute MAE for Mn₂Sb first (using ICSD reference) to establish baseline behavior and confirm post-wallet setup.

4. Iterate across candidates and compile results into a validation dataset.

--

This guide is intended for the permanent-magnets team to standardize MAE calculations and to document known platform constraints (monetization precheck) so future runs are not blocked by avoidable configuration errors.