Materials Designer

A standalone React application for atomistic structural design. Deployed within the Mat3ra.com platform as
documented here and can be used as a library in any web/Node.js
application.

Try Materials Designer in action here

!Materials Designer in action

1. Installation

$3

Materials Designer can be installed from the source as follows:

``bash
git clone git@github.com:Exabyte-io/materials-designer.git
`

Or use https, if no SSH authentication is set up with GitHub:

`bash
git clone https://github.com/Exabyte-io/materials-designer.git
`

then start the application using Node v20.18:

`bash
cd materials-designer
npm install
npm start
`

> Some files might not be downloaded by git clone or git pull commands if your system doesn't have git-lfs
> installed.
> To fix this run (on OSX):
> `
> brew install git-lfs
> git lfs pull
> `

Open http://localhost:3001 to view the application in the browser.

$3

See the Docker Files section below.

2. Functionality

$3

As documented here:

- Input/Output Menu
- Export materials in JSON/POSCAR formats
- Edit Menu
- Undo/Redo/Reset/Clone operations
- View
- Fullscreen mode
- Multi-material Editor (combining multiple materials into one)
- Advanced Menu
- Creating supercells
- Creating surfaces/slabs
- Creating combinatorial sets
- Creating interpolated sets
- Run Python Script
- Launch a Jupyter Lite session
- Basis Editor
- Adding/Removing/Modifying sites
- Adding/Removing/Modifying atomic constraints
- Switching Crystal/Cartesian units
- Lattice Editor
- Adjusting lattice units/types/parameters
- 3D Editor
- Visualizing materials
- Rotation
- Repetition/Radius
- Toggle axes
- Adjusting materials
- add/remove/select atoms
- multiple selection with drag-and-drop

$3

Desirable features/fixes for implementation.

General Improvements:

- switch the color back to white when the material is back to the original after editing
- show the total number of materials in the list and the current index
- fix fullscreen support
- add lattice vectors form to change lattice vectors in a 3x3 matrix with all components explicitly:
- highlight atoms that are selected in the source editor in the 3D editor and vice versa
- add the ability to drop files with material structural data to the materials list
- ESSE JSON and POSCAR parsers already implemented in made.js
- add a skeleton material with (+) button to the materials list (combines functionality of "Edit" -> "Clone" and "
I/O" -> "Import...")
- save the state of Materials Designer to share materials and exact visualization via URL link.
- the idea is to be able to share an exact copy of the state of the application
- materials data is stored in the redux store
- visualization settings stored in wave.js components, via useState() hook

Specific features:

- add logic for Interstitials and vacancy concentrations in combinatorial sets

Developer Experience:

- add tests for all the functionality listed above. We only test advanced operations at current.
- fix modal dialog exceptions for AdvancedGeometryDialog
- remove the updateIndex action when the index is the same

3. Development

$3

Execute the following commands when running the application in development mode. Use Node v14.19

`bash
npm install
npm start
`

$3

Tests are implemented using Cypress. To launch it use Node v20 and run:

`bash
cd tests
npm install
npm test
`

To run a specific test feature, pass its relative path as an option:

`bash
sh run-tests.sh -f=menu/advanced/create-supercell.feature
`

$3

This package depends on Made, Wave,
and Cove.js among other packages. For the full list,
see package.json.

$3

The first dockerfiles/app/Dockerfile builds and runs the application. The second dockerfiles/tests/Dockerfile provisions and runs the tests.

Provided docker compose is installed, it can be used like so:

`bash
docker compose build materials-designer
docker compose build materials-designer-test

docker compose up -d materials-designer
sleep 30 # let the app actually start
docker compose run materials-designer-test
`

To run tests in the container use default profile by not specifying it:

`bash
docker compose up -d --build
`

To run on MacOS, add CYPRESS_BASE_URL=http://host.docker.internal:3001 to the environment variables in the test container

`
CYRPRESS_BASE_URL=http://host.docker.internal:3001 docker compose run materials-designer-test
`

To run both services and execute tests:

`
CYPRESS_BASE_URL=http://host.docker.internal:3001 docker compose up --abort-on-container-exit --exit-code-from materials-designer-test
`

For debugging purposes, Materials Designer and test container can be run interactively with access via VNC:

`bash
docker compose --profile use-vnc up -d --build
`

Then connect to vnc://localhost:5920 with a VNC client. The password is 123. (Port set in .env file.)
Make sure to have VNC client installed on the system, when address is typed in the Chrome browser, the VNC prompt will
appear.

$3

If need to link Cove.js into the app for local development, you need

1. Add the local path of Cove.js to package.json

`bash
"@exabyte-io/cove.js": "file:../../cove.js"
`

2. Run the app

`bash
npm start
`

If you need to re-link it again, remove node_modules in cove.js and the app, run npm install, then run npm start again.


$3

To run tests for JupyterLite Notebooks, set the environment variable in .env file.
And update the URL for JL dev distribution by getting the URL from the JupyterLite PR preview.

`bash
VITE_USE_JUPYTERLITE_DEV_URL=true
VITE_JUPYTERLITE_DEVELOPMENT_URL="https://deploy-preview-56--mat3ra-jupyterlite.netlify.app"
``

This should source JL from the development distribution and run only notebook healthcheck tests.

4. Links

1. Create React App, GitHub Repository
2. Mat3ra Platform documentation for materials designer.