@mat3ra/made 2026.6.15-0 → 2026.6.27-0

package/.pre-commit-config.yaml

@@ -13,7 +13,7 @@ repos:
       - id: check-yaml
         exclude: ^tests/fixtures*
       - id: end-of-file-fixer
-        exclude: ^tests/fixtures*
+        exclude: ^tests/fixtures*|^dist*
       - id: trailing-whitespace
         exclude: ^tests/fixtures*|^dist*
   - repo: local

package/.prettierignore

@@ -1 +1,2 @@
 tests/fixtures/*.json
+dist/

package/AGENTS.md

@@ -0,0 +1,133 @@
+# AGENTS.md
+
+This document describes generic architecture and conventions for AI coding agents.
+
+## Conventions
+
+### Design Patterns
+
+- **Factory**: when multiple implementations are possible - e.g. multiple exchange-correlation functionals, or multiple k-point samplers.
+- **Object-oriented design**: define abstract interfaces for components that have multiple implementations - e.g. Method → PseudopotentialMethod, PlaneWaveMethod, Model → DFTModel, HFModel, etc.
+
+### OOP Guidelines & Antipatterns
+
+**Prefer polymorphism over type-checking chains.** Instead of:
+
+```cpp
+// ❌ ANTIPATTERN: long if-chain checking object type
+if (functional.is_lda()) {
+    compute_lda_energy(...);
+} else if (functional.is_gga()) {
+    compute_gga_energy(...);
+} else if (functional.is_meta_gga()) {
+    compute_meta_gga_energy(...);
+}
+```
+
+Use:
+
+```cpp
+// ✅ CORRECT: polymorphic dispatch via virtual method
+Real energy = functional.compute_energy(density);
+```
+
+**Key principles:**
+
+- **Single Responsibility**: each class does one thing. If a class has methods for reading, computing, and writing, split it.
+- **Open/Closed**: add new behavior by adding new classes, not by adding `if` branches to existing code.
+- **Interface Segregation**: keep interfaces small. Don't force implementors to provide methods they don't need.
+- **No `is_xxx()` type queries**: if you need `is_ultrasoft()`, `is_paw()`, `is_norm_conserving()`, your design likely needs a virtual method instead.
+- **Favor composition over inheritance** for combining behaviors: use mixins (e.g., `BinarySerializableMixin`) rather than deep inheritance hierarchies.
+- **Use factories** to create the right subclass from runtime configuration (e.g., `create_diagonalizer("davidson")`).
+
+**Python Coding Guidelines & Antipatterns:**
+
+- **No Function-Local Imports**: Do not put `import` statements inside functions or methods. Place all imports at the top level of the module to maintain visibility, clean dependencies, and prevent runtime cyclic/late failures.
+- **No Nested Functions (Functions Inside Functions)**: Defining a helper function inside another function or method is an antipattern. Define helper functions at the module level or class level instead.
+- **Cap Function Length at 20-25 lines**: Keep Python functions and methods short (capped at 20-25 lines max, excluding docstrings and comments). If a function grows longer, refactor and delegate its sub-tasks to smaller, well-isolated helper functions.
+
+### Logging
+
+- All output via logger
+- Allow log level to be set via command line argument (critical, error, warn, info, debug, trace). Default is error.
+- Only rank 0 outputs (MPI-aware initialization)
+- No print statement in the log
+
+### Testing
+
+- Unit tests: `tests/unit/` (GTest)
+- Integration tests: `tests/integration/`
+
+### Comment Style
+
+- **Multiline docstrings** must have `/**` on its own line followed by the comment body:
+
+```cpp
+// ✅ CORRECT
+/**
+ * Compute the angular phase factor (-i)^l.
+ */
+
+// ❌ INCORRECT
+/** Compute the angular phase factor (-i)^l.
+ */
+```
+
+- Use `///` for single-line doc comments.
+- Use `//` for inline implementation comments.
+- Never use bare `/* ... */` for documentation; use `/** ... */`.
+
+### Linter
+
+Use linting for autoformatting the codebase. Consider language-specific tools and/or prettier.
+
+### Pre-commit
+
+Use pre-commit to run linters and formatters automatically.
+
+### GitHub Actions
+
+Use GitHub Actions to run tests and linters automatically.
+
+## !!! IMPORTANT !!!: Code Editing & Development HARD RULES
+
+### HARD RULE 1: Never commit without explicit ask from user
+
+NEVER commit changes using `git commit` without the user's explicit ask. Leave files in the working directory for the user to review.
+
+### HARD RULE 2: use `<PROJECT_DIRECTORY>/agents/workdir/` for ALL scratch files.
+
+NEVER create any throwaway files at the top level of the project directory (`<PROJECT_DIRECTORY>`). The top level of `<PROJECT_DIRECTORY>` must remain clean and contain only tracked project files. All throw-away scripts — debug helpers, patch scripts, test snippets, one-off analysis scripts — MUST go in `<PROJECT_DIRECTORY>/agents/workdir/tmp/`. Create that directory if it does not exist. Examples of files that belong in `<PROJECT_DIRECTORY>/agents/workdir/tmp/`: `debug_*.py`, `fix_*.py`, `patch_*.py`, `print_*.py`, `test_*.py` / `test_*.cpp` that are not formal tests in `tests/`, any other ephemeral script written to inspect or patch source code. Any potentially reusable agent artifacts should be either in `<PROJECT_DIRECTORY>/agents/workdir/reusable` (if they're intended to be used in the current project only) or in `<PROJECT_DIRECTORY>/agents/plan` (if they're intended to be used in multiple projects). NO EXCEPTIONS.
+
+### HARD RULE 3: Always setup and use a virtual environment
+
+(`venv`) when working with Python. Do NOT install Python packages globally. Use pyenv to select python version(s). Create venv in the agents workdir directory as explained in the next item
+
+## HARD RULE 4: names with no abbreviations, Snake for Py, Camel for JS/TS, classnames
+
+Variables, functions, methods, field names, class names, type names, file names. Always use full, descriptive names. For example:
+
+- ❌ `nkp`, `nbnd`, `nspin`, `npw`, `ik`, `ib`, `ig`, `ia`, `et`, `pw`, `ppset`
+- ✅ `number_of_kpoints`, `number_of_bands`, `number_of_spin_components`, `number_of_plane_waves`, `kpoint_index`, `band_index`, `g_index`, `atom_index`, `eigenvalues`, `planewave_basis`, `pseudopotential_set`
+- ❌ `Vec3`, `Mat3`, `IVec3`
+- ✅ `Vector3D`, `Matrix3x3`, `IntegerVector3D`
+
+Also:
+
+- Use **snake_case** for variables, functions, and file names.
+- Use **PascalCase** for classes and structs.
+- Member variables use trailing underscore: `planewave_basis_`, `number_of_bands_`.
+- General rule: if a name looks abbreviated, spell it out. Exceptions could be made for complex physical and mathematical extpressions where the abbreviation is widely know and used for compacting the representation. However, even in these cases, try to spell it out. Make sure to make it obvious from the context what the abbreviation means.
+
+## Other
+
+### JSON Formatting
+
+- **HARD RULE**: JSON schemas MUST follow ESSE formatting conventions:
+    - **4-space indentation** (matching ESSE `.prettierrc`)
+    - **100 character print width**
+    - **Double quotes** only (standard JSON)
+    - **Trailing newline** at end of file
+    - **Bracket spacing** enabled (e.g., `{ "key": "value" }`)
+    - Q3 postprocessing/result schemas use ESSE-native names (e.g., `density_of_states`, not `dos_result`)
+    - All Q3 result schemas must `$ref` their corresponding ESSE schema in `schemas/esse/schema/`

package/data/constants.json

@@ -0,0 +1,13 @@
+{
+    "molecule": {
+        "nonPeriodicMinimumLatticeSize": 3.0,
+        "diatomicLatticePaddingFactor": 3.0,
+        "molecularLatticePaddingFactor": 2.0
+    },
+    "precision": {
+        "coordinatesCrystal": 9,
+        "coordinatesCartesian": 6,
+        "latticeLengths": 6,
+        "latticeAngles": 4
+    }
+}

package/data/reciprocal_paths.json

@@ -0,0 +1,111 @@
+{
+    "CUB": [
+        ["Г", "X", "M", "Г", "R", "X"],
+        ["M", "R"]
+    ],
+    "BCC": [
+        ["Г", "H", "N", "Г", "P", "H"],
+        ["P", "N"]
+    ],
+    "FCC": [
+        ["Г", "X", "W", "K", "Г", "L", "U", "W", "L"],
+        ["U", "X"]
+    ],
+    "TET": [
+        ["Г", "X", "M", "Г", "Z", "R", "A", "Z"],
+        ["X", "R"],
+        ["M", "A"]
+    ],
+    "BCT-1": [
+        ["Г", "X", "M", "Г", "Z", "P", "N", "Z1", "M"],
+        ["X", "P"]
+    ],
+    "BCT-2": [
+        ["Г", "X", "Y", "∑", "Г", "Z", "∑1", "N", "P", "Y1", "Z"],
+        ["X", "P"]
+    ],
+    "ORC": [
+        ["Г", "X", "S", "Y", "Г", "Z", "U", "R", "T", "Z"],
+        ["Y", "T"],
+        ["U", "X"],
+        ["S", "R"]
+    ],
+    "ORCF-1": [
+        ["Г", "Y", "T", "Z", "Г", "X", "A1", "Y"],
+        ["T", "X1"],
+        ["X", "A", "Z"],
+        ["L", "Г"]
+    ],
+    "ORCF-2": [
+        ["Г", "Y", "C", "D", "X", "Г", "Z", "D1", "H", "C"],
+        ["C1", "Z"],
+        ["X", "H1"],
+        ["H", "Y"],
+        ["L", "Г"]
+    ],
+    "ORCF-3": [
+        ["Г", "Y", "T", "Z", "Г", "X", "A1", "Y"],
+        ["X", "A", "Z"],
+        ["L", "Г"]
+    ],
+    "ORCI": [
+        ["Г", "X", "L", "T", "W", "R", "X1", "Z", "Г", "Y", "S", "W"],
+        ["L1", "Y"],
+        ["Y1", "Z"]
+    ],
+    "ORCC": [
+        ["Г", "X", "S", "R", "A", "Z", "Г", "Y", "X1", "A1", "T", "Y"],
+        ["Z", "T"]
+    ],
+    "HEX": [
+        ["Г", "M", "K", "Г", "A", "L", "H", "A"],
+        ["L", "M"],
+        ["K", "H"]
+    ],
+    "RHL-1": [
+        ["Г", "L", "B1"],
+        ["B", "Z", "Г", "X"],
+        ["Q", "F", "P1", "Z"],
+        ["L", "P"]
+    ],
+    "RHL-2": [["Г", "P", "Z", "Q", "Г", "F", "P1", "Q1", "L", "Z"]],
+    "MCL": [
+        ["Г", "Y", "H", "C", "E", "M1", "A", "X", "H1"],
+        ["M", "D", "Z"],
+        ["Y", "D"]
+    ],
+    "MCLC-1": [
+        ["Г", "Y", "Г", "L", "I"],
+        ["I1", "Z", "F1"],
+        ["Y", "X1"],
+        ["X", "Г", "N"],
+        ["M", "Г"]
+    ],
+    "MCLC-2": [
+        ["Г", "Y", "F", "L", "I"],
+        ["I1", "Z", "F1"],
+        ["N", "Г", "M"]
+    ],
+    "MCLC-3": [
+        ["Г", "Y", "F", "H", "Z", "I", "F1"],
+        ["H1", "Y1", "X", "Г", "N"],
+        ["M", "Г"]
+    ],
+    "MCLC-4": [
+        ["Г", "Y", "F", "H", "Z", "I"],
+        ["H1", "Y1", "X", "Г", "N"],
+        ["M", "Г"]
+    ],
+    "MCLC-5": [
+        ["Г", "Y", "F", "L", "I"],
+        ["I1", "Z", "H", "F1"],
+        ["H1", "Y1", "X", "Г", "N"],
+        ["M", "Г"]
+    ],
+    "TRI": [
+        ["X", "Г", "Y"],
+        ["L", "Г", "Z"],
+        ["N", "Г", "M"],
+        ["R", "Г"]
+    ]
+}

package/dist/js/data/reciprocal_paths.json

@@ -0,0 +1,111 @@
+{
+    "CUB": [
+        ["Г", "X", "M", "Г", "R", "X"],
+        ["M", "R"]
+    ],
+    "BCC": [
+        ["Г", "H", "N", "Г", "P", "H"],
+        ["P", "N"]
+    ],
+    "FCC": [
+        ["Г", "X", "W", "K", "Г", "L", "U", "W", "L"],
+        ["U", "X"]
+    ],
+    "TET": [
+        ["Г", "X", "M", "Г", "Z", "R", "A", "Z"],
+        ["X", "R"],
+        ["M", "A"]
+    ],
+    "BCT-1": [
+        ["Г", "X", "M", "Г", "Z", "P", "N", "Z1", "M"],
+        ["X", "P"]
+    ],
+    "BCT-2": [
+        ["Г", "X", "Y", "∑", "Г", "Z", "∑1", "N", "P", "Y1", "Z"],
+        ["X", "P"]
+    ],
+    "ORC": [
+        ["Г", "X", "S", "Y", "Г", "Z", "U", "R", "T", "Z"],
+        ["Y", "T"],
+        ["U", "X"],
+        ["S", "R"]
+    ],
+    "ORCF-1": [
+        ["Г", "Y", "T", "Z", "Г", "X", "A1", "Y"],
+        ["T", "X1"],
+        ["X", "A", "Z"],
+        ["L", "Г"]
+    ],
+    "ORCF-2": [
+        ["Г", "Y", "C", "D", "X", "Г", "Z", "D1", "H", "C"],
+        ["C1", "Z"],
+        ["X", "H1"],
+        ["H", "Y"],
+        ["L", "Г"]
+    ],
+    "ORCF-3": [
+        ["Г", "Y", "T", "Z", "Г", "X", "A1", "Y"],
+        ["X", "A", "Z"],
+        ["L", "Г"]
+    ],
+    "ORCI": [
+        ["Г", "X", "L", "T", "W", "R", "X1", "Z", "Г", "Y", "S", "W"],
+        ["L1", "Y"],
+        ["Y1", "Z"]
+    ],
+    "ORCC": [
+        ["Г", "X", "S", "R", "A", "Z", "Г", "Y", "X1", "A1", "T", "Y"],
+        ["Z", "T"]
+    ],
+    "HEX": [
+        ["Г", "M", "K", "Г", "A", "L", "H", "A"],
+        ["L", "M"],
+        ["K", "H"]
+    ],
+    "RHL-1": [
+        ["Г", "L", "B1"],
+        ["B", "Z", "Г", "X"],
+        ["Q", "F", "P1", "Z"],
+        ["L", "P"]
+    ],
+    "RHL-2": [["Г", "P", "Z", "Q", "Г", "F", "P1", "Q1", "L", "Z"]],
+    "MCL": [
+        ["Г", "Y", "H", "C", "E", "M1", "A", "X", "H1"],
+        ["M", "D", "Z"],
+        ["Y", "D"]
+    ],
+    "MCLC-1": [
+        ["Г", "Y", "Г", "L", "I"],
+        ["I1", "Z", "F1"],
+        ["Y", "X1"],
+        ["X", "Г", "N"],
+        ["M", "Г"]
+    ],
+    "MCLC-2": [
+        ["Г", "Y", "F", "L", "I"],
+        ["I1", "Z", "F1"],
+        ["N", "Г", "M"]
+    ],
+    "MCLC-3": [
+        ["Г", "Y", "F", "H", "Z", "I", "F1"],
+        ["H1", "Y1", "X", "Г", "N"],
+        ["M", "Г"]
+    ],
+    "MCLC-4": [
+        ["Г", "Y", "F", "H", "Z", "I"],
+        ["H1", "Y1", "X", "Г", "N"],
+        ["M", "Г"]
+    ],
+    "MCLC-5": [
+        ["Г", "Y", "F", "L", "I"],
+        ["I1", "Z", "H", "F1"],
+        ["H1", "Y1", "X", "Г", "N"],
+        ["M", "Г"]
+    ],
+    "TRI": [
+        ["X", "Г", "Y"],
+        ["L", "Г", "Z"],
+        ["N", "Г", "M"],
+        ["R", "Г"]
+    ]
+}

package/dist/js/lattice/reciprocal/paths.js

@@ -1,126 +1,21 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.paths = void 0;
 /**
- * Default kpoing paths according to:
+ * Default k-point paths according to:
  *  [AFLOW](https://arxiv.org/abs/1004.2974) methodology.
  *  Paths are split in parts for clarity.
+ *
+ * Raw segment data is stored in data/reciprocal_paths.json (shared with Python).
  */
-const points = {
-    CUB: [
-        ["Г", "X", "M", "Г", "R", "X"],
-        ["M", "R"],
-    ],
-    BCC: [
-        ["Г", "H", "N", "Г", "P", "H"],
-        ["P", "N"],
-    ],
-    FCC: [
-        ["Г", "X", "W", "K", "Г", "L", "U", "W", "L"],
-        ["U", "X"],
-    ],
-    TET: [
-        ["Г", "X", "M", "Г", "Z", "R", "A", "Z"],
-        ["X", "R"],
-        ["M", "A"],
-    ],
-    "BCT-1": [
-        ["Г", "X", "M", "Г", "Z", "P", "N", "Z1", "M"],
-        ["X", "P"],
-    ],
-    "BCT-2": [
-        ["Г", "X", "Y", "∑", "Г", "Z", "∑1", "N", "P", "Y1", "Z"],
-        ["X", "P"],
-    ],
-    ORC: [
-        ["Г", "X", "S", "Y", "Г", "Z", "U", "R", "T", "Z"],
-        ["Y", "T"],
-        ["U", "X"],
-        ["S", "R"],
-    ],
-    "ORCF-1": [
-        ["Г", "Y", "T", "Z", "Г", "X", "A1", "Y"],
-        ["T", "X1"],
-        ["X", "A", "Z"],
-        ["L", "Г"],
-    ],
-    "ORCF-2": [
-        ["Г", "Y", "C", "D", "X", "Г", "Z", "D1", "H", "C"],
-        ["C1", "Z"],
-        ["X", "H1"],
-        ["H", "Y"],
-        ["L", "Г"],
-    ],
-    "ORCF-3": [
-        ["Г", "Y", "T", "Z", "Г", "X", "A1", "Y"],
-        ["X", "A", "Z"],
-        ["L", "Г"],
-    ],
-    ORCI: [
-        ["Г", "X", "L", "T", "W", "R", "X1", "Z", "Г", "Y", "S", "W"],
-        ["L1", "Y"],
-        ["Y1", "Z"],
-    ],
-    ORCC: [
-        ["Г", "X", "S", "R", "A", "Z", "Г", "Y", "X1", "A1", "T", "Y"],
-        ["Z", "T"],
-    ],
-    HEX: [
-        ["Г", "M", "K", "Г", "A", "L", "H", "A"],
-        ["L", "M"],
-        ["K", "H"],
-    ],
-    "RHL-1": [
-        ["Г", "L", "B1"],
-        ["B", "Z", "Г", "X"],
-        ["Q", "F", "P1", "Z"],
-        ["L", "P"],
-    ],
-    "RHL-2": [["Г", "P", "Z", "Q", "Г", "F", "P1", "Q1", "L", "Z"]],
-    MCL: [
-        ["Г", "Y", "H", "C", "E", "M1", "A", "X", "H1"],
-        ["M", "D", "Z"],
-        ["Y", "D"],
-    ],
-    "MCLC-1": [
-        ["Г", "Y", "Г", "L", "I"],
-        ["I1", "Z", "F1"],
-        ["Y", "X1"],
-        ["X", "Г", "N"],
-        ["M", "Г"],
-    ],
-    "MCLC-2": [
-        ["Г", "Y", "F", "L", "I"],
-        ["I1", "Z", "F1"],
-        ["N", "Г", "M"],
-    ],
-    "MCLC-3": [
-        ["Г", "Y", "F", "H", "Z", "I", "F1"],
-        ["H1", "Y1", "X", "Г", "N"],
-        ["M", "Г"],
-    ],
-    "MCLC-4": [
-        ["Г", "Y", "F", "H", "Z", "I"],
-        ["H1", "Y1", "X", "Г", "N"],
-        ["M", "Г"],
-    ],
-    "MCLC-5": [
-        ["Г", "Y", "F", "L", "I"],
-        ["I1", "Z", "H", "F1"],
-        ["H1", "Y1", "X", "Г", "N"],
-        ["M", "Г"],
-    ],
-    TRI: [
-        ["X", "Г", "Y"],
-        ["L", "Г", "Z"],
-        ["N", "Г", "M"],
-        ["R", "Г"],
-    ],
-};
+const reciprocal_paths_json_1 = __importDefault(require("../../data/reciprocal_paths.json"));
 // Export a processed version of the paths
 exports.paths = (() => {
     const result = {};
-    Object.entries(points).forEach(([key, pathSegments]) => {
+    Object.entries(reciprocal_paths_json_1.default).forEach(([key, pathSegments]) => {
         // Flatten arrays of path segments into a single array
         const flattenedPath = pathSegments.reduce((acc, segment) => [...acc, ...segment], []);
         // Convert to KPointStep array

package/dist/js/made.d.ts

@@ -2,7 +2,7 @@ import { Basis } from "./basis/basis";
 import { Cell } from "./cell/cell";
 import { ATOMIC_COORD_UNITS, coefficients, tolerance, units } from "./constants";
 import { AtomicConstraints } from "./constraints/constraints";
-import { Lattice, defaultNonPeriodicMinimumLatticeSize, diatomicLatticePaddingFactor, molecularLatticePaddingFactor } from "./lattice/lattice";
+import { defaultNonPeriodicMinimumLatticeSize, diatomicLatticePaddingFactor, Lattice, molecularLatticePaddingFactor } from "./lattice/lattice";
 import { DEFAULT_LATTICE_UNITS, LATTICE_TYPE_CONFIGS } from "./lattice/lattice_types";
 import { ReciprocalLattice } from "./lattice/reciprocal/lattice_reciprocal";
 import { UnitCell } from "./lattice/unit_cell";

package/dist/js/made.js

@@ -16,9 +16,9 @@ Object.defineProperty(exports, "units", { enumerable: true, get: function () { r
 const constraints_1 = require("./constraints/constraints");
 Object.defineProperty(exports, "AtomicConstraints", { enumerable: true, get: function () { return constraints_1.AtomicConstraints; } });
 const lattice_1 = require("./lattice/lattice");
-Object.defineProperty(exports, "Lattice", { enumerable: true, get: function () { return lattice_1.Lattice; } });
 Object.defineProperty(exports, "defaultNonPeriodicMinimumLatticeSize", { enumerable: true, get: function () { return lattice_1.defaultNonPeriodicMinimumLatticeSize; } });
 Object.defineProperty(exports, "diatomicLatticePaddingFactor", { enumerable: true, get: function () { return lattice_1.diatomicLatticePaddingFactor; } });
+Object.defineProperty(exports, "Lattice", { enumerable: true, get: function () { return lattice_1.Lattice; } });
 Object.defineProperty(exports, "molecularLatticePaddingFactor", { enumerable: true, get: function () { return lattice_1.molecularLatticePaddingFactor; } });
 const lattice_types_1 = require("./lattice/lattice_types");
 Object.defineProperty(exports, "DEFAULT_LATTICE_UNITS", { enumerable: true, get: function () { return lattice_types_1.DEFAULT_LATTICE_UNITS; } });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mat3ra/made",
-    "version": "2026.6.15-0",
+    "version": "2026.6.27-0",
     "description": "MAterials DEsign library",
     "scripts": {
         "lint": "eslint --cache src/js tests/js && prettier --write src/js tests/js",

package/pyproject.toml

@@ -75,8 +75,8 @@ git_describe_command = "git describe --tags --long"
 [tool.setuptools.packages.find]
 where = ["src/py"]
 
-[tool.setuptools.package-data]
-"mat3ra.made" = ["constants.json"]
+[tool.setuptools.data-files]
+"data" = ["data/constants.json", "data/reciprocal_paths.json"]
 
 
 [tool.black]

package/src/js/constants/molecule.ts

@@ -1,7 +1,7 @@
 /**
  * Constants for molecule handling and precision.
  * Source of truth: /constants.json at repository root
- * 
+ *
  * These values are duplicated here for TypeScript compilation.
  * When updating these, also update constants.json.
  */