{"id":22007089,"url":"https://github.com/exabyte-io/materials-designer","last_synced_at":"2026-04-22T04:06:13.542Z","repository":{"id":34448589,"uuid":"173842806","full_name":"Exabyte-io/materials-designer","owner":"Exabyte-io","description":"A standalone React.js/Redux based web application for the design and visualization of atomistic materials structures. Used at Mat3ra.com and can be deployed in standalone mode.","archived":false,"fork":false,"pushed_at":"2025-04-27T22:44:23.000Z","size":18351,"stargazers_count":11,"open_issues_count":21,"forks_count":10,"subscribers_count":8,"default_branch":"dev","last_synced_at":"2025-04-27T23:27:01.881Z","etag":null,"topics":["atomistic-models","computer-aided-design","materials","materials-design","materials-informatics","materials-science","modeling-tool","react","threejs"],"latest_commit_sha":null,"homepage":"https://mat3ra-materials-designer.netlify.app/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Exabyte-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-03-05T00:18:27.000Z","updated_at":"2025-04-16T00:34:13.000Z","dependencies_parsed_at":"2024-01-29T14:24:54.767Z","dependency_job_id":"99b884d3-c9e5-4645-8798-b632a8c96d0e","html_url":"https://github.com/Exabyte-io/materials-designer","commit_stats":{"total_commits":435,"total_committers":16,"mean_commits":27.1875,"dds":0.7379310344827585,"last_synced_commit":"495c22943eefaa8957db83756013ac36e6e3ce0b"},"previous_names":[],"tags_count":209,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Exabyte-io%2Fmaterials-designer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Exabyte-io%2Fmaterials-designer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Exabyte-io%2Fmaterials-designer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Exabyte-io%2Fmaterials-designer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Exabyte-io","download_url":"https://codeload.github.com/Exabyte-io/materials-designer/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252590015,"owners_count":21772929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atomistic-models","computer-aided-design","materials","materials-design","materials-informatics","materials-science","modeling-tool","react","threejs"],"created_at":"2024-11-30T01:17:09.527Z","updated_at":"2026-04-22T04:06:13.538Z","avatar_url":"https://github.com/Exabyte-io.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![npm version](https://badge.fury.io/js/%40exabyte-io%2Fmaterials-designer.svg)](https://badge.fury.io/js/%40exabyte-io%2Fmaterials-designer)\n[![License: Apache](https://img.shields.io/badge/License-Apache-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)\n\n# Materials Designer\n\nA standalone React application for atomistic structural design. Deployed within the Mat3ra.com platform as\ndocumented [here](https://docs.mat3ra.com/materials-designer/overview/) and can be used as a library in any web/Node.js\napplication.\n\n[Try Materials Designer in action here](https://mat3ra-materials-designer.netlify.app/)\n\n![Materials Designer in action](https://i.imgur.com/f7NvNNl.png)\n\n## 1. Installation\n\n### 1.1. From source\n\nMaterials Designer can be installed from the source as follows:\n\n```bash\ngit clone git@github.com:Exabyte-io/materials-designer.git\n```\n\nOr use https, if no SSH authentication is set up with GitHub:\n\n```bash\ngit clone https://github.com/Exabyte-io/materials-designer.git\n```\n\nthen start the application using Node v20.18:\n\n```bash\ncd materials-designer\nnpm install\nnpm start\n```\n\n\u003e Some files might not be downloaded by `git clone` or `git pull` commands if your system doesn't have `git-lfs`\n\u003e installed.\n\u003e To fix this run (on OSX):\n\u003e ```\n\u003e brew install git-lfs\n\u003e git lfs pull\n\u003e ```\n\nOpen http://localhost:3001 to view the application in the browser.\n\n### 1.2. Using Docker\n\nSee the Docker Files section below.\n\n## 2. Functionality\n\n### 2.1. Current Functionality\n\nAs documented [here](https://docs.mat3ra.com/materials-designer/overview/):\n\n- Input/Output Menu\n    - Export materials in JSON/POSCAR formats\n- Edit Menu\n    - Undo/Redo/Reset/Clone operations\n- View\n    - Fullscreen mode\n    - Multi-material Editor (combining multiple materials into one)\n- Advanced Menu\n    - Creating supercells\n    - Creating surfaces/slabs\n    - Creating combinatorial sets\n    - Creating interpolated sets\n    - Run Python Script\n    - Launch a Jupyter Lite session\n- Basis Editor\n    - Adding/Removing/Modifying sites\n    - Adding/Removing/Modifying atomic constraints\n    - Switching Crystal/Cartesian units\n- Lattice Editor\n    - Adjusting lattice units/types/parameters\n- 3D Editor\n    - Visualizing materials\n        - Rotation\n        - Repetition/Radius\n        - Toggle axes\n    - Adjusting materials\n        - add/remove/select atoms\n        - multiple selection with drag-and-drop\n\n### 2.2. TODO list\n\nDesirable features/fixes for implementation.\n\nGeneral Improvements:\n\n- switch the color back to white when the material is back to the original after editing\n- show the total number of materials in the list and the current index\n- fix fullscreen support\n- add lattice vectors form to change lattice vectors in a 3x3 matrix with all components explicitly:\n- highlight atoms that are selected in the source editor in the 3D editor and vice versa\n- add the ability to drop files with material structural data to the materials list\n    - ESSE JSON and POSCAR parsers already implemented in made.js\n    - add a skeleton material with (+) button to the materials list (combines functionality of \"Edit\" -\u003e \"Clone\" and \"\n      I/O\" -\u003e \"Import...\")\n- save the state of Materials Designer to share materials and exact visualization via URL link.\n    - the idea is to be able to share an exact copy of the state of the application\n    - materials data is stored in the redux store\n    - visualization settings stored in wave.js components, via `useState()` hook\n\nSpecific features:\n\n- add logic for Interstitials and vacancy concentrations in combinatorial sets\n\nDeveloper Experience:\n\n- add tests for all the functionality listed above. We only test advanced operations at current.\n- fix modal dialog exceptions for AdvancedGeometryDialog\n- remove the `updateIndex` action when the index is the same\n\n## 3. Development\n\n### 3.1. Run the application\n\nExecute the following commands when running the application in development mode. Use Node v14.19\n\n```bash\nnpm install\nnpm start\n```\n\n### 3.2. Tests\n\nTests are implemented using Cypress. To launch it use Node v20 and run:\n\n```bash\ncd tests\nnpm install\nnpm test\n```\n\nTo run a specific test feature, pass its relative path as an option:\n\n```bash\nsh run-tests.sh -f=menu/advanced/create-supercell.feature\n```\n\n### 3.3. Dependencies\n\nThis package depends on [Made](https://github.com/mat3ra/made), [Wave](https://github.com/Exabyte-io/wave.js),\nand [Cove.js](https://github.com/Exabyte-io/cove.js) among other packages. For the full list,\nsee [package.json](package.json).\n\n### 3.4. CI Docker files\n\nThe first `dockerfiles/app/Dockerfile` builds and runs the application. The second `dockerfiles/tests/Dockerfile` provisions and runs the tests. \n\nProvided `docker compose` is installed, it can be used like so:\n\n```bash\ndocker compose build materials-designer\ndocker compose build materials-designer-test\n\ndocker compose up -d materials-designer\nsleep 30  # let the app actually start\ndocker compose run materials-designer-test\n```\n\nTo run tests in the container use default profile by not specifying it:\n\n```bash\ndocker compose up -d --build\n```\n\nTo run on MacOS, add CYPRESS_BASE_URL=http://host.docker.internal:3001 to the environment variables in the test container\n\n```\nCYRPRESS_BASE_URL=http://host.docker.internal:3001 docker compose run materials-designer-test\n```\n\nTo run both services and execute tests:\n\n```\nCYPRESS_BASE_URL=http://host.docker.internal:3001 docker compose up --abort-on-container-exit --exit-code-from materials-designer-test\n```\n\nFor debugging purposes, Materials Designer and test container can be run interactively with access via VNC:\n\n```bash\ndocker compose --profile use-vnc up -d --build\n```\n\nThen connect to `vnc://localhost:5920` with a VNC client. The password is `123`. (Port set in `.env` file.)\nMake sure to have VNC client installed on the system, when address is typed in the Chrome browser, the VNC prompt will\nappear.\n\n### 3.5. Using Cove.js for local development\n\nIf need to link Cove.js into the app for local development, you need\n\n1. Add the local path of Cove.js to package.json\n\n```bash\n    \"@exabyte-io/cove.js\": \"file:../../cove.js\"\n```\n\n2. Run the app\n\n```bash\n    npm start\n```\n\nIf you need to re-link it again, remove node_modules in cove.js and the app, run npm install, then run npm start again.\n### 3.6. Running tests for JupyterLite Notebooks\n\nTo run tests for JupyterLite Notebooks, set the environment variable in `.env` file.\nAnd update the URL for JL dev distribution by getting the URL from the JupyterLite PR preview.\n\n```bash\nVITE_USE_JUPYTERLITE_DEV_URL=true\nVITE_JUPYTERLITE_DEVELOPMENT_URL=\"https://deploy-preview-56--mat3ra-jupyterlite.netlify.app\"\n```\n\nThis should source JL from the development distribution and run only notebook healthcheck tests.\n\n## 4. Links\n\n1. [Create React App, GitHub Repository](https://github.com/facebook/create-react-app)\n2. [Mat3ra Platform documentation for materials designer](https://docs.mat3ra.com/materials-designer/overview/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexabyte-io%2Fmaterials-designer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexabyte-io%2Fmaterials-designer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexabyte-io%2Fmaterials-designer/lists"}