@mat3ra/made 2024.3.22-0

package/.babelrc

@@ -0,0 +1,10 @@
+{
+    "presets": [
+        "@babel/preset-env"
+    ],
+    "plugins": [
+        [
+            "@babel/plugin-proposal-class-properties"
+        ]
+    ]
+}

package/.eslintrc.json

@@ -0,0 +1,11 @@
+{
+    "extends": ["@exabyte-io/eslint-config"],
+    "ignorePatterns": ["dist/"],
+    "settings": {
+        "import/resolver": {
+            "node": {
+                "extensions": [".js", ".jsx", ".ts", ".tsx"]
+            }
+        }
+    }
+}

package/.mocharc.json

@@ -0,0 +1,5 @@
+{
+    "extension": ["ts", "js"],
+    "spec": "tests/**/*.js",
+    "require": ["ts-node/register"]
+  }

package/.prettierignore

@@ -0,0 +1 @@
+tests/fixtures/*.json

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+    "singleQuote": false,
+    "printWidth": 100,
+    "trailingComma": "all",
+    "tabWidth": 4
+}

package/LICENSE.md

@@ -0,0 +1,15 @@
+# LICENSE
+
+Copyright 2019 Exabyte Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,167 @@
+[![npm version](https://badge.fury.io/js/%40mat3ra%2Fmade.svg)](https://badge.fury.io/js/%40mat3ra%2Fmade)
+[![License: Apache](https://img.shields.io/badge/License-Apache-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+
+# Made
+
+Made is a library for **MA**terials **DE**sign in JavaScript/TypeScript and Python. It allows for the creation and manipulation of material structures from atoms up on the web. The library is aimed to be used for the development of web applications, both on the client (web browser) and server (eg. Node.js) side.
+
+The library was originally designed as part of and presently powers materials design capabilities of the [Exabyte.io](https://exabyte.io) platform. For example, [this page](https://platform.exabyte.io/demo/materials/n3HSzCmyoctgJFGGE) representing a crystal of Silicon online uses Made.js.
+
+Exabyte.io believe in a collaborative future of materials design on the web.
+
+## Functionality
+
+As below:
+
+- the package provides a software environment for interacting with Materials-related data structures from ESSE Data Convention [[1]](#links) and is written in ECMAScript 2015 for use on the web
+- High-level classes for the representation of the [Material](src/material.js) and the corresponding structural information, ie:
+    - [Basis](src/basis/basis.js), 
+    - [Lattice](src/lattice/lattice.js), 
+    - [ReciprocalLattice](src/lattice/reciprocal/lattice_reciprocal.js), 
+    - [Cell](src/cell/cell.js), 
+    - [AtomicConstraints](src/constraints/constraints.js) 
+    - and others to be added.
+- input/output support, including:
+    - POSCAR [[3]](#links), 
+    - XYZ [[4]](#links),
+    - Quantum ESPRESSO [[5]](#links),
+    - and others to be added.
+- structural generation and analysis tools:
+    - [supercell](src/tools/supercell.js)
+    - [surfaces](src/tools/surface.js)
+    - [combinatorial sets](src/parsers/xyz_combinatorial_basis.js)
+    - [interpolated sets for chemical reactions](src/tools/basis.js)
+
+The package is written in a modular way easy to extend. Contributions can be in the form of additional tools or modules you develop, or feature requests and [bug/issue reports](https://help.github.com/articles/creating-an-issue/).
+
+## Installation
+
+From NPM for use within a software project:
+
+```bash
+npm install @mat3ra/made
+
+```
+
+From source to contribute to development:
+
+```bash
+git clone git@github.com:Exabyte-io/made
+```
+
+## Contribution
+
+This repository is an [open-source](LICENSE.md) work-in-progress and we welcome contributions.
+
+### Why contribute?
+
+We regularly deploy the latest code containing all accepted contributions online as part of the [Mat3ra.com](https://mat3ra.com) platform, so contributors will see their code in action there.
+
+### Adding new functionality
+
+We suggest forking this repository and introducing the adjustments there to be considered for merging into this repository as explained in more details [here](https://gist.github.com/Chaser324/ce0505fbed06b947d962), for example.
+
+### Source code conventions
+
+Made.js is written in EcmaScript 6th edition [[2]](#links) with the application of object-oriented design patterns encapsulating key concepts following the conventions below.
+
+1. Classes follow the Exabyte Data Convention and data structures defined in ESSE [[1]](#links)
+
+2. Only materials-related code is considered. Properties related to [simulation model](https://docs.exabyte.io/models/overview/) parameters (eg. type of approximation, numerical parameters) shall go elsewhere.
+
+3. `tools` directory contains helper functions that act on one or more classes and include an external parameter. Functions that use class data without any external parameters should be implemented inside the class. For example, `basis.clone()` is implemented in `Basis`, but basis repetition is implemented as a tool in the correspondingly named function ([tools/basis.js#repeat](src/tools/basis.js)) because the repetion requires a parameter external to basis - number of repetitions in 3 spatial dimensions.
+
+4. `parsers` directory contains the parsers to- and from- ESSE format mentioned in 1. All functionality related to external data conversion is contained in this directory. 
+
+
+### TODO list
+
+Desirable features for implementation:
+
+- identify primitive / conventional structures
+- support for molecular geometries
+- support for polymer geometries
+- radial correlation function calculation
+- generation of complex atomic shapes:
+    - fullerene
+    - nanotube
+    - nanowire
+    - nano-cluster
+    - a combination of the above
+    - arbitrary atomic arrangement
+
+## Tests
+
+Made tests are written based on Mocha [6](#links) testing framework and can be executed as follows.
+
+```bash
+git pull
+git lfs pull
+```
+to get the latest test fixtures from LFS, and then:
+
+```bash
+npm install
+npm test
+```
+
+### Tests Important Notes
+
+1. Keep the tests directory structure similar to the main codebase directory structure. Every JS module in the main codebase should have a corresponding module in tests directory which implements the tests for provided functionality.
+
+2. Add tests fixtures into [fixtures](./tests/fixtures) directory. The fixtures are automatically stored on Git LFS [7](#links).
+
+3. If the fixtures are going to be used inside multiple cases, read and export them inside [enums](./tests/enums.js) to avoid code duplicates.
+
+4. [Tests setup module](./tests/setup.js) can be used to implement the hooks that are used to prepare the tests environment.
+
+## Using Linter
+
+Linter setup will prevent committing files that don't adhere to the code standard. It will
+attempt to fix what it can automatically prior to the commit in order to reduce diff noise. This can lead to "unexpected" behavior where a
+file that is staged for commit is not identical to the file that actually gets committed. This happens
+in the `lint-staged` directive of the `package.json` file (by using a `husky` pre-commit hook). For example,
+if you add extra whitespace to a file, stage it, and try to commit it, you will see the following:
+
+```bash
+➜  made git:(feature/SOF-4398-TB) ✗ git add src/basis/constrained_basis.js
+➜  made git:(feature/SOF-4398-TB) ✗ git commit -m "Test commit non-linted code"
+✔ Preparing...
+✔ Running tasks...
+✖ Prevented an empty git commit!
+✔ Reverting to original state because of errors...
+✔ Cleaning up...
+
+  ⚠ lint-staged prevented an empty git commit.
+  Use the --allow-empty option to continue, or check your task configuration
+
+husky - pre-commit hook exited with code 1 (error)
+```
+
+The staged change may remain but will not have been committed. Then it will look like you still have a staged
+change to commit, but the pre-commit hook will not actually commit it for you, quite frustrating! Styling can
+be applied manually and fixed by running:
+
+```bash
+npm run lint:fix
+```
+
+In which case, you may need to then add the linter edits to your staging, which in the example above, puts the
+file back to identical with the base branch, resulting in no staged changes whatsoever.
+
+## Configuring WebStorm for use with Linter
+
+In order for the WebStorm IDE to take full advantage of the linting configuration, it can be configured in the project:
+
+- `Preferences -> Languages & Frameworks -> JavaScript -> Code Quality Tools -> ESLint`
+- Check `Automatic ESLint configuration` which should infer all the configurations from the project directory
+
+## Links
+
+1. [Exabyte Source of Schemas and Examples (ESSE), Github Repository](https://github.com/exabyte-io/exabyte-esse)
+2. [ECMAScript 2015 Language Specifications](https://www.ecma-international.org/ecma-262/6.0/)
+3. [POSCAR file format, official website](https://cms.mpi.univie.ac.at/vasp/guide/node59.html)
+4. [XYZ file format, Wikipedia](https://en.wikipedia.org/wiki/XYZ_file_format)
+5. [Quantum ESPRESSO, Official Website](https://www.quantum-espresso.org/)
+6. [Mocha, Official Website](https://mochajs.org/)
+7. [Git LFS, Official Website](https://git-lfs.github.com/)

package/dist/abstract/array_with_ids.d.ts

@@ -0,0 +1,43 @@
+import { ObjectWithIdAndValue, ValueOrObject } from "./scalar_with_id";
+type Predicate<T> = (o: T) => boolean;
+type MapFunction<T> = (value: T, index: number, array: T[]) => T;
+export declare function isArrayOfObjectsWithIdAndValue<T>(valueOrObjects: ValueOrObject<T>[]): valueOrObjects is ObjectWithIdAndValue<T>[];
+/**
+ * Helper class representing an ArrayWithIds. Used to explicitly track values assigned to atoms, for example.
+ */
+export declare class ArrayWithIds<T> {
+    array: T[];
+    /**
+     * Create a an array with ids.
+     * @param {Array} array - Either regular array or ArrayWithIds (see @example above)
+     */
+    constructor(array?: ObjectWithIdAndValue<T>[] | T[]);
+    /**
+     * Serialize class instance to JSON.
+     * @example [{"id" : 0, "value" : "Si" }, {"id" : 1, "value" : "Si" }]
+     */
+    toJSON(): ObjectWithIdAndValue<T>[];
+    /**
+     * Apply function fn to each element of the array and replace `array` with the result.
+     * @param fn - The function to be applied to each array element.
+     */
+    mapArrayInPlace(fn: MapFunction<T>): void;
+    getArrayElementByIndex(idx: number): T;
+    /**
+     * Get the index of the array element that passes the predicate.
+     * @param {Function} predicate - The function to be applied to each array element.
+     */
+    getArrayIndexByPredicate(predicate: Predicate<T>): number;
+    /**
+     * Add an entity to array.
+     * @param el - The entity to be added to array. If Object with 'value' key, its value will be added.
+     */
+    addElement(el: ValueOrObject<T>): void;
+    /**
+     * Remove an entity to array. Either by passing the entity, or the corresponding index.
+     * @param el - The entity to be added to array. If Object with 'value' key, its value will be added.
+     * @param idx - The entity to be added to array. If Object with 'value' key, its value will be added.
+     */
+    removeElement(el: ValueOrObject<T> | null, idx?: number): void;
+}
+export {};

package/dist/abstract/array_with_ids.js

@@ -0,0 +1,88 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArrayWithIds = exports.isArrayOfObjectsWithIdAndValue = void 0;
+const underscore_1 = __importDefault(require("underscore"));
+const scalar_with_id_1 = require("./scalar_with_id");
+function isArrayOfObjectsWithIdAndValue(valueOrObjects) {
+    return (0, scalar_with_id_1.isObjectWithIdAndValue)(valueOrObjects[0]);
+}
+exports.isArrayOfObjectsWithIdAndValue = isArrayOfObjectsWithIdAndValue;
+/**
+ * Helper class representing an ArrayWithIds. Used to explicitly track values assigned to atoms, for example.
+ */
+class ArrayWithIds {
+    /**
+     * Create a an array with ids.
+     * @param {Array} array - Either regular array or ArrayWithIds (see @example above)
+     */
+    constructor(array = []) {
+        if (!underscore_1.default.isArray(array)) {
+            throw new Error("ArrayWithIds.constructor: pass array on initialization");
+        }
+        // if passed an array with ids as config, only store the values in array
+        if (isArrayOfObjectsWithIdAndValue(array)) {
+            this.array = array.sort((a, b) => a.id - b.id).map((element) => element.value);
+        }
+        else {
+            this.array = [...array];
+        }
+    }
+    /**
+     * Serialize class instance to JSON.
+     * @example [{"id" : 0, "value" : "Si" }, {"id" : 1, "value" : "Si" }]
+     */
+    toJSON() {
+        // from ["a", "b"] to [{id: 0, value: "a"}, {id: 1, value: "b"}]
+        return this.array.map((el, idx) => new scalar_with_id_1.ScalarWithId(el, idx).toJSON());
+    }
+    /**
+     * Apply function fn to each element of the array and replace `array` with the result.
+     * @param fn - The function to be applied to each array element.
+     */
+    mapArrayInPlace(fn) {
+        if (!underscore_1.default.isFunction(fn)) {
+            throw new Error("ArrayWithIds.mapArray: must pass function as argument");
+        }
+        this.array = this.array.map(fn);
+    }
+    getArrayElementByIndex(idx) {
+        return this.array[idx];
+    }
+    /**
+     * Get the index of the array element that passes the predicate.
+     * @param {Function} predicate - The function to be applied to each array element.
+     */
+    getArrayIndexByPredicate(predicate) {
+        return this.array.findIndex((el) => predicate(el));
+    }
+    /**
+     * Add an entity to array.
+     * @param el - The entity to be added to array. If Object with 'value' key, its value will be added.
+     */
+    addElement(el) {
+        const value = (0, scalar_with_id_1.isObjectWithIdAndValue)(el) ? el.value : el;
+        if (el)
+            this.array.push(value);
+    }
+    /**
+     * Remove an entity to array. Either by passing the entity, or the corresponding index.
+     * @param el - The entity to be added to array. If Object with 'value' key, its value will be added.
+     * @param idx - The entity to be added to array. If Object with 'value' key, its value will be added.
+     */
+    removeElement(el, idx) {
+        let _idx;
+        if (idx === undefined) {
+            _idx = this.array.findIndex((elm) => elm === el);
+        }
+        else {
+            _idx = idx;
+        }
+        if (_idx !== undefined) {
+            this.array.splice(_idx, 1);
+        }
+    }
+}
+exports.ArrayWithIds = ArrayWithIds;

package/dist/abstract/scalar_with_id.d.ts

@@ -0,0 +1,25 @@
+export interface ObjectWithIdAndValue<T> {
+    id: number;
+    value: T;
+}
+export type ValueOrObject<T> = ObjectWithIdAndValue<T> | T;
+export type ValueOrObjectArray<T> = ObjectWithIdAndValue<T>[] | T[];
+export declare function isObjectWithIdAndValue<T>(valueOrObject: ValueOrObject<T>): valueOrObject is ObjectWithIdAndValue<T>;
+/**
+ * Helper class representing a scalar with an associated id.
+ */
+export declare class ScalarWithId<T> {
+    id: number;
+    value: T;
+    /**
+     * Create a an array with ids.
+     * @param valueOrObject - a ScalarWithID, or any other type.
+     * @param id - numerical id (Integer).
+     */
+    constructor(valueOrObject: ValueOrObject<T>, id?: number);
+    /**
+     * Serialize class instance to JSON.
+     * @example {"id" : 0, "value" : "Si" }
+     */
+    toJSON(): ObjectWithIdAndValue<T>;
+}

package/dist/abstract/scalar_with_id.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScalarWithId = exports.isObjectWithIdAndValue = void 0;
+const underscore_1 = __importDefault(require("underscore"));
+function isObjectWithIdAndValue(valueOrObject) {
+    return Boolean(underscore_1.default.isObject(valueOrObject) && !underscore_1.default.isArray(valueOrObject) && valueOrObject.value);
+}
+exports.isObjectWithIdAndValue = isObjectWithIdAndValue;
+/**
+ * Helper class representing a scalar with an associated id.
+ */
+class ScalarWithId {
+    /**
+     * Create a an array with ids.
+     * @param valueOrObject - a ScalarWithID, or any other type.
+     * @param id - numerical id (Integer).
+     */
+    constructor(valueOrObject, id = 0) {
+        // if already passing a ScalarWithId => preserve original
+        if (isObjectWithIdAndValue(valueOrObject)) {
+            // NOTE - Arrays are Objects too
+            this.id = valueOrObject.id;
+            this.value = valueOrObject.value;
+        }
+        else {
+            this.id = id;
+            this.value = valueOrObject;
+        }
+    }
+    /**
+     * Serialize class instance to JSON.
+     * @example {"id" : 0, "value" : "Si" }
+     */
+    toJSON() {
+        return {
+            id: this.id,
+            value: this.value,
+        };
+    }
+}
+exports.ScalarWithId = ScalarWithId;