@mat3ra/prode 2025.11.25-0

package/src/js/properties/non-scalar/BandStructureProperty.ts

@@ -0,0 +1,284 @@
+/* eslint-disable class-methods-use-this */
+// eslint-disable-next-line max-classes-per-file
+import { math as codeJSMath } from "@mat3ra/code/dist/js/math";
+import { deepClone } from "@mat3ra/code/dist/js/utils";
+import type { Constructor } from "@mat3ra/code/dist/js/utils/types";
+import type { BandStructurePropertySchema } from "@mat3ra/esse/dist/js/types";
+import type { KPointPath } from "@mat3ra/made/dist/js/lattice/reciprocal/lattice_reciprocal";
+import type { Options, PlotLines } from "highcharts";
+import zip from "lodash/zip";
+
+import { type FormatterScope, HighChartsConfig } from "../../charts/highcharts";
+import {
+    type BandStructurePropertySchemaMixin,
+    bandStructurePropertySchemaMixin,
+} from "../../generated/BandStructurePropertySchemaMixin";
+import Property from "../../Property";
+import { PropertyName, PropertyType } from "../../settings";
+import {
+    type XDataArray,
+    type XDataArrayNested,
+    type YDataSeries,
+} from "../include/mixins/2d_plot";
+
+export const _POINT_COORDINATES_PRECISION_ = 4; // number of decimals to keep for point coordinates
+
+export class BandStructureConfig extends HighChartsConfig {
+    readonly yDataSeries: YDataSeries;
+
+    readonly spin?: number[];
+
+    readonly xDataArray: XDataArrayNested;
+
+    readonly pointsDistanceArray: number[];
+
+    readonly fermiEnergy: number | null;
+
+    readonly pointsPath: KPointPath | undefined;
+
+    constructor(
+        property: {
+            spin?: number[];
+            subtitle: string;
+            yAxisTitle: string;
+            yDataSeries: [number, ...number[]][];
+            xDataArray: (number | number[])[];
+        },
+        chartConfig?: {
+            fermiEnergy?: number | null;
+            pointsPath?: KPointPath;
+        },
+    ) {
+        super({
+            subtitle: property.subtitle,
+            yAxisTitle: property.yAxisTitle,
+            yAxisType: "linear",
+        });
+
+        this.yDataSeries = property.yDataSeries;
+        this.spin = property.spin;
+        this.xDataArray = this.cleanXDataArray(property.xDataArray);
+
+        this.pointsPath = chartConfig?.pointsPath;
+        this.pointsDistanceArray = this.calculatePointsDistance(this.xDataArray);
+
+        this.fermiEnergy = chartConfig?.fermiEnergy ?? null;
+
+        this.plotXLineAtPoint = this.plotXLineAtPoint.bind(this);
+        this.plotXLines = this.plotXLines.bind(this);
+    }
+
+    // round each value in array to certain precision
+    cleanXDataArray(rawData: XDataArray = []): XDataArrayNested {
+        return rawData.map((p) => {
+            if (!p || !Array.isArray(p)) return [];
+
+            return p.map((c) => {
+                return codeJSMath.roundValueToNDecimals(c, _POINT_COORDINATES_PRECISION_);
+            });
+        });
+    }
+
+    // returns the array of distances calculated from an array of points
+    calculatePointsDistance(listOfPoints: XDataArrayNested = []) {
+        let pointsDistanceSum = 0;
+        return listOfPoints.map((el, idx, arr) => {
+            if (idx !== 0) {
+                const distance = codeJSMath.vDist(el, arr[idx - 1]);
+                pointsDistanceSum += Number(distance);
+            }
+            return pointsDistanceSum;
+        });
+    }
+
+    // find index of a point inside an array of points
+    findSymmetryPointIndex(xDataArray: XDataArrayNested, point: number[]) {
+        return xDataArray.findIndex((p) => codeJSMath.vDist(p, point) === 0);
+    }
+
+    // create config for vertical lines at high symmetry points
+    plotXLines(): PlotLines[] {
+        const copiedXDataArray = deepClone(this.xDataArray);
+        return this.pointsPath
+            ? this.pointsPath
+                  .map((p) => {
+                      const idx = this.findSymmetryPointIndex(copiedXDataArray, p.coordinates);
+                      // "reset" element at index if found to avoid duplicate matches
+                      if (idx > -1) copiedXDataArray[idx] = [-1, -1, -1];
+                      return {
+                          point: p.point,
+                          distance: idx > -1 ? this.pointsDistanceArray[idx] : null,
+                      };
+                  })
+                  .map(this.plotXLineAtPoint)
+            : [];
+    }
+
+    plotXLineAtPoint({ point, distance }: { point: string; distance: number | null }): PlotLines {
+        return {
+            label: {
+                verticalAlign: "bottom",
+                rotation: 0,
+                align: "center",
+                y: 20,
+                x: 0,
+                text: point,
+            },
+            value: distance ?? undefined,
+            width: 1,
+            dashStyle: "solid",
+            color: "#E0E0E0",
+        };
+    }
+
+    get series() {
+        const { fermiEnergy } = this;
+
+        const series_ = this.yDataSeries.map((item, index) => {
+            // shift values by fermiEnergy
+            const itemUpdated = item.map((x) => {
+                return fermiEnergy ? Number(x) - fermiEnergy : Number(x);
+            });
+
+            const spin = this.spin?.[index];
+            const spinText = spin && spin > 0 ? "up" : "down";
+
+            return {
+                data: zip(this.pointsDistanceArray, itemUpdated) as [number, number][],
+                name: spinText,
+                color: spinText === "up" ? "#3677d9" : "#ff7f0e",
+                animation: false,
+            };
+        });
+
+        return series_;
+    }
+
+    xAxis() {
+        return {
+            minorGridLineColor: "#E0E0E0",
+            minorGridLineWidth: 2,
+            minorTickLength: 0,
+            title: {
+                text: "Path in reciprocal space",
+                offset: 40,
+            },
+            type: "linear",
+            tickPositioner: () => [], // disable ticks
+            plotLines: this.pointsPath ? this.plotXLines() : undefined,
+            labels: {
+                enabled: false,
+            },
+        };
+    }
+
+    tooltipFormatter(xDataArray: XDataArrayNested, yAxisName = "energy") {
+        // note 'this' below refers to Highcharts tooltip scope
+        // eslint-disable-next-line func-names
+        return function (this: FormatterScope) {
+            return (
+                "<b>spin:</b> " +
+                this.series.name +
+                "<br>" +
+                "<b>point:</b> " +
+                xDataArray.map((p) => {
+                    if (!Array.isArray(p)) {
+                        console.error("xDataArray is not a nested array", xDataArray);
+                        return [];
+                    }
+                    return p.map((c) => c.toFixed(_POINT_COORDINATES_PRECISION_));
+                })[this.point.index] +
+                "<br>" +
+                "<b>" +
+                yAxisName +
+                ": </b>  " +
+                this.y.toFixed(_POINT_COORDINATES_PRECISION_)
+            );
+        };
+    }
+
+    yAxis() {
+        return {
+            ...super.yAxis(),
+            gridZIndex: 1,
+            plotLines: this.fermiEnergy
+                ? this.plotSingleLine({
+                      value: 0.0,
+                      width: 2, // to be shown above above grid/tickLine at zero
+                      label: {
+                          text: "E_F",
+                          style: {
+                              color: "red",
+                          },
+                          y: -5,
+                          x: -10,
+                      },
+                  })
+                : [],
+        };
+    }
+
+    get overrideConfig() {
+        const { xDataArray } = this;
+        return {
+            chart: {
+                animation: false,
+                type: "spline",
+                zoomType: "xy",
+            },
+            plotOptions: {
+                spline: {
+                    lineWidth: 2,
+                    states: {
+                        hover: {
+                            lineWidth: 6,
+                        },
+                    },
+                    marker: {
+                        enabled: false,
+                    },
+                },
+            },
+            tooltip: {
+                valueSuffix: "",
+                formatter: this.tooltipFormatter(xDataArray),
+            },
+            legend: {
+                enabled: false,
+            },
+        };
+    }
+}
+
+type Schema = BandStructurePropertySchema;
+
+type Base = typeof Property<Schema> & Constructor<BandStructurePropertySchemaMixin>;
+
+export default class BandStructureProperty extends (Property as Base) implements Schema {
+    readonly subtitle: string = "Electronic Bandstructure";
+
+    readonly yAxisTitle: string = `Energy (${this.yAxis.units})`;
+
+    readonly chartConfig: Options;
+
+    static readonly isRefined = true;
+
+    static readonly propertyName = PropertyName.band_structure;
+
+    static readonly propertyType = PropertyType.non_scalar;
+
+    constructor(
+        config: Omit<Schema, "name"> & {
+            fermiEnergy?: number | null;
+            pointsPath?: KPointPath;
+        },
+    ) {
+        super({ ...config, name: BandStructureProperty.propertyName });
+        this.chartConfig = new BandStructureConfig(this, {
+            fermiEnergy: config.fermiEnergy,
+            pointsPath: config.pointsPath,
+        }).config;
+    }
+}
+
+bandStructurePropertySchemaMixin(BandStructureProperty.prototype);

package/src/js/properties/non-scalar/ChargeDensityProfileProperty.ts

@@ -0,0 +1,48 @@
+/* eslint-disable class-methods-use-this */
+/* eslint-disable max-classes-per-file */
+
+import type { Constructor } from "@mat3ra/code/dist/js/utils/types";
+import type { ChargeDensityProfilePropertySchema } from "@mat3ra/esse/dist/js/types";
+import type { Options } from "highcharts";
+
+import {
+    type ChargeDensityProfilePropertySchemaMixin,
+    chargeDensityProfilePropertySchemaMixin,
+} from "../../generated/ChargeDensityProfilePropertySchemaMixin";
+import Property from "../../Property";
+import { PropertyName, PropertyType } from "../../settings";
+import { TwoDimensionalHighChartConfigMixin } from "../include/mixins/2d_plot";
+
+export class ChargeDensityProfileConfig extends TwoDimensionalHighChartConfigMixin {
+    readonly tooltipXAxisName = "z coordinate";
+
+    readonly tooltipYAxisName = "charge density";
+}
+
+type Schema = ChargeDensityProfilePropertySchema;
+
+type Base = typeof Property<Schema> & Constructor<ChargeDensityProfilePropertySchemaMixin>;
+
+class ChargeDensityProfileProperty extends (Property as Base) implements Schema {
+    readonly subtitle: string = "Charge Density Profile";
+
+    readonly yAxisTitle: string = `Charge Density (${this.yAxis.units})`;
+
+    readonly xAxisTitle: string = "Z Coordinate";
+
+    readonly chartConfig: Options = new ChargeDensityProfileConfig(this).config;
+
+    static readonly isRefined = true;
+
+    static readonly propertyName = PropertyName.charge_density_profile;
+
+    static readonly propertyType = PropertyType.non_scalar;
+
+    constructor(config: Omit<Schema, "name">) {
+        super({ ...config, name: ChargeDensityProfileProperty.propertyName });
+    }
+}
+
+chargeDensityProfilePropertySchemaMixin(ChargeDensityProfileProperty.prototype);
+
+export default ChargeDensityProfileProperty;

package/src/js/properties/non-scalar/DensityOfStatesProperty.ts

@@ -0,0 +1,174 @@
+/* eslint-disable class-methods-use-this */
+/* eslint-disable max-classes-per-file */
+import type { Constructor } from "@mat3ra/code/dist/js/utils/types.js";
+import type { DensityOfStatesPropertySchema } from "@mat3ra/esse/dist/js/types";
+import type { IndividualSeriesOptions, Options } from "highcharts";
+import zip from "lodash/zip";
+
+import { type FormatterScope, HighChartsConfig } from "../../charts/highcharts";
+import {
+    type DensityOfStatesPropertySchemaMixin,
+    densityOfStatesPropertySchemaMixin,
+} from "../../generated/DensityOfStatesPropertySchemaMixin";
+import Property from "../../Property";
+import { PropertyName, PropertyType } from "../../settings";
+import { type YDataSeries } from "../include/mixins/2d_plot";
+
+type Schema = DensityOfStatesPropertySchema;
+
+export class DensityOfStatesConfig extends HighChartsConfig {
+    readonly yDataSeries: YDataSeries;
+
+    readonly fermiEnergy: number | null;
+
+    readonly xDataArray: Schema["xDataArray"];
+
+    readonly legends: Schema["legend"];
+
+    get overrideConfig() {
+        return {
+            colors: [
+                "#7cb5ec",
+                "#90ed7d",
+                "#f7a35c",
+                "#8085e9",
+                "#f15c80",
+                "#e4d354",
+                "#2b908f",
+                "#f45b5b",
+                "#91e8e1",
+            ],
+            credits: {
+                enabled: false,
+            },
+            chart: {
+                type: "spline",
+                zoomType: "xy",
+                animation: false,
+            },
+            legend: {
+                layout: "horizontal",
+                align: "center",
+                verticalAlign: "bottom",
+                borderWidth: 0,
+            },
+        };
+    }
+
+    constructor(
+        property: {
+            subtitle: string;
+            yAxisTitle: string;
+            xAxisTitle: string;
+            yDataSeries: YDataSeries;
+            legend?: Schema["legend"];
+            xDataArray: Schema["xDataArray"];
+        },
+        chartConfig?: {
+            fermiEnergy?: number | null;
+        },
+    ) {
+        super({
+            subtitle: property.subtitle,
+            yAxisTitle: property.yAxisTitle,
+            xAxisTitle: property.xAxisTitle,
+            yAxisType: "linear",
+        });
+
+        this.yDataSeries = property.yDataSeries;
+        this.legends = property.legend || [];
+        this.fermiEnergy = chartConfig?.fermiEnergy ?? 0;
+        this.xDataArray = this.cleanXDataArray(property.xDataArray);
+    }
+
+    // shifting values wrt fermi energy here
+    cleanXDataArray(rawData: Schema["xDataArray"]) {
+        return rawData.flat().map((x) => {
+            const value = this.fermiEnergy ? x - this.fermiEnergy : x;
+            return Number(value.toPrecision(4));
+        });
+    }
+
+    get series(): IndividualSeriesOptions[] {
+        return this.yDataSeries.map((item, index) => {
+            const legend = this.legends[index];
+            const spinText = legend?.spin ? ` ${legend.spin > 0 ? "↑" : "↓"}` : "";
+            const name = legend?.element
+                ? `${legend.element} ${legend.electronicState}${spinText}`
+                : "Total";
+
+            return {
+                data: zip(
+                    this.xDataArray,
+                    item.map((x) => Number(Number(x).toPrecision(4))),
+                ) as IndividualSeriesOptions["data"],
+                name,
+                color: name === "Total" ? "#000000" : undefined,
+                animation: false,
+            };
+        });
+    }
+
+    tooltipFormatter() {
+        // eslint-disable-next-line func-names
+        return function (this: FormatterScope) {
+            return (
+                "<b>state:</b> " +
+                this.series.name +
+                "<br>" +
+                "<b>energy:</b> " +
+                this.key.toFixed(4) +
+                "<br>" +
+                "<b>value: </b>  " +
+                this.y.toFixed(4)
+            );
+        };
+    }
+
+    xAxis() {
+        return {
+            ...super.xAxis(),
+            plotLines: this.fermiEnergy
+                ? this.plotSingleLine({
+                      value: 0.0,
+                      label: {
+                          text: "E_F",
+                          style: {
+                              color: "red",
+                          },
+                          y: 15,
+                          x: 5,
+                          rotation: 0,
+                      },
+                  })
+                : [],
+        };
+    }
+}
+
+type Base = typeof Property<Schema> & Constructor<DensityOfStatesPropertySchemaMixin>;
+
+export default class DensityOfStatesProperty extends (Property as Base) implements Schema {
+    readonly subtitle: string = "Density Of States";
+
+    readonly yAxisTitle: string = `Density Of States (${this.yAxis.units})`;
+
+    readonly xAxisTitle: string = `Energy (${this.xAxis.units})`;
+
+    readonly chartConfig: Options;
+
+    static readonly isRefined = true;
+
+    static readonly propertyName = PropertyName.density_of_states;
+
+    static readonly propertyType = PropertyType.non_scalar;
+
+    constructor(config: Omit<Schema, "name"> & { fermiEnergy?: number | null }) {
+        super({ ...config, name: DensityOfStatesProperty.propertyName });
+        this.chartConfig = new DensityOfStatesConfig(this, {
+            fermiEnergy: config.fermiEnergy,
+        }).config;
+    }
+}
+
+densityOfStatesPropertySchemaMixin(DensityOfStatesProperty.prototype);

package/src/js/properties/non-scalar/DielectricTensorProperty.ts

@@ -0,0 +1,153 @@
+/* eslint-disable class-methods-use-this */
+/* eslint-disable max-classes-per-file */
+import type { Constructor } from "@mat3ra/code/dist/js/utils/types";
+import type { DielectricTensorPropertySchema } from "@mat3ra/esse/dist/js/types";
+import type { Options } from "highcharts";
+import zip from "lodash/zip";
+import type { FormatterScope } from "src/js/charts/highcharts";
+
+import {
+    type DielectricTensorPropertySchemaMixin,
+    dielectricTensorPropertySchemaMixin,
+} from "../../generated/DielectricTensorPropertySchemaMixin";
+import Property from "../../Property";
+import { PropertyName, PropertyType } from "../../settings";
+import { TwoDimensionalHighChartConfigMixin } from "../include/mixins/2d_plot";
+
+type Schema = DielectricTensorPropertySchema;
+
+export class DielectricTensorConfig extends TwoDimensionalHighChartConfigMixin {
+    get series() {
+        return this.yDataSeries.map((item, index) => {
+            return {
+                animation: false,
+                name: Array.isArray(this.legend) ? this.legend[index] : "",
+                data: zip(this.xDataArray, item) as [number, number][],
+            };
+        });
+    }
+
+    tooltipFormatter() {
+        // eslint-disable-next-line func-names
+        return function (this: FormatterScope) {
+            return (
+                "<b>part:</b> " +
+                this.series.name +
+                "<br>" +
+                "<b>frequency:</b> " +
+                this.key.toFixed(4) +
+                "<br>" +
+                "<b>epsilon: </b>  " +
+                this.y.toFixed(4)
+            );
+        };
+    }
+
+    get overrideConfig() {
+        return {
+            ...super.overrideConfig,
+            colors: [
+                "#7cb5ec",
+                "#90ed7d",
+                "#f7a35c",
+                "#8085e9",
+                "#f15c80",
+                "#e4d354",
+                "#2b908f",
+                "#f45b5b",
+                "#91e8e1",
+            ],
+            credits: {
+                enabled: false,
+            },
+            chart: {
+                type: "spline",
+                zoomType: "xy",
+                animation: false,
+            },
+            legend: {
+                layout: "horizontal",
+                align: "center",
+                verticalAlign: "bottom",
+                borderWidth: 0,
+            },
+        };
+    }
+}
+
+type Base = typeof Property<Schema> & Constructor<DielectricTensorPropertySchemaMixin>;
+
+export default class DielectricTensorProperty extends (Property as Base) implements Schema {
+    readonly subtitle = "Dielectric Tensor";
+
+    readonly yAxisTitle = "Dielectric Tensor Component";
+
+    readonly xAxisTitle = "Frequency (eV)";
+
+    readonly chartConfig: Options[] = this.getAllChartConfigs().map((chartConfig) => {
+        const cfg = new DielectricTensorConfig(chartConfig);
+        return cfg.config;
+    });
+
+    static readonly propertyName = PropertyName.dielectric_tensor;
+
+    static readonly propertyType = PropertyType.non_scalar;
+
+    constructor(config: Omit<Schema, "name">) {
+        super({ ...config, name: DielectricTensorProperty.propertyName });
+    }
+
+    private rowMajorToColumnMajor(matrix: number[][]) {
+        return matrix.reduce<[number[], number[], number[]]>(
+            (accumulator, item) => {
+                const [x, y, z] = item;
+                accumulator[0].push(x);
+                accumulator[1].push(y);
+                accumulator[2].push(z);
+                return accumulator;
+            },
+            [[], [], []],
+        );
+    }
+
+    private getComplementaryPairs(precision = 3) {
+        const groupedBySpin: Record<string, Schema["values"]> = {};
+
+        this.values.forEach((item) => {
+            // Round the spin value to mitigate floating-point precision issues
+            const spinValue = item.spin !== undefined ? item.spin.toFixed(precision) : "undefined";
+            groupedBySpin[spinValue] = groupedBySpin[spinValue] || [];
+            groupedBySpin[spinValue].push(item);
+        });
+
+        return Object.values(groupedBySpin).filter(
+            (group) =>
+                group.length === 2 &&
+                group.find((item) => item.part === "real") &&
+                group.find((item) => item.part === "imaginary"),
+        );
+    }
+
+    private getAllChartConfigs() {
+        const complementaryPairs = this.getComplementaryPairs();
+
+        return complementaryPairs.map((pair) => {
+            const xDataArray = pair[0].frequencies;
+            const spinChannel = pair[0].spin ? ` - spin(${pair[0].spin})` : "";
+            return {
+                subtitle: `${this.subtitle}${spinChannel}`,
+                xAxisTitle: this.xAxisTitle,
+                yAxisTitle: this.yAxisTitle,
+                yAxisType: "linear",
+                xDataArray,
+                yDataSeries: pair.flatMap((p) => this.rowMajorToColumnMajor(p.components)) as [
+                    number,
+                    ...number[],
+                ][],
+                legend: pair.flatMap((p) => [..."xyz"].map((char) => `eps_${char} (${p.part})`)),
+            };
+        });
+    }
+}
+
+dielectricTensorPropertySchemaMixin(DielectricTensorProperty.prototype);

package/src/js/properties/non-scalar/FileContentProperty.ts

@@ -0,0 +1,27 @@
+import type { Constructor } from "@mat3ra/code/dist/js/utils/types";
+import type { FileContentPropertySchema } from "@mat3ra/esse/dist/js/types";
+
+import {
+    type FileContentPropertySchemaMixin,
+    fileContentPropertySchemaMixin,
+} from "../../generated/FileContentPropertySchemaMixin";
+import Property from "../../Property";
+import { PropertyName, PropertyType } from "../../settings";
+
+type Schema = FileContentPropertySchema;
+
+type Base = typeof Property<Schema> & Constructor<FileContentPropertySchemaMixin>;
+
+export default class FileContentProperty extends (Property as Base) implements Schema {
+    static readonly isAbleToReturnMultipleResults = true;
+
+    static readonly propertyName = PropertyName.file_content;
+
+    static readonly propertyType = PropertyType.non_scalar;
+
+    constructor(config: Omit<Schema, "name">) {
+        super({ ...config, name: FileContentProperty.propertyName });
+    }
+}
+
+fileContentPropertySchemaMixin(FileContentProperty.prototype);