Our documentation is currently missing an introduction tutorial which is especially important for new users that never worked with rascaline or software that is calculating descriptors.
Idea
The language should be pure python and the tutorial should be created using sphinx galleries to avoid unmaintainable jupyter notebooks (For an initial draft a notebook is fine though). Before you start with a notebook please take time and make yourself familiar with the idea of a tutorial for example on the divio page. Most importantly don't go too much into details and focus on explaining the actual workflow of creating a representation from cartesian coordinates. Avoid abstraction and complicated and long code blocks.
Possible structure
0. The dataset
Load with chemfiles and show atomtypes, number of structures, number of atoms, cell size, etc maybe a plot.
We should only provide 5–10 frames; keeping the data load small
I would prefer a dataset where the chemical species, the numbers of atoms, and the cell size change to explain that rascaline can handle such systems. Ideas?
1. Calculate features with good & reasonable SOAP hyperparameters.
Use the SOAP spherical expansion calculator and use hyperparameters that could also be used for a real system. We don't want a set of parameters that if they are copied to a "real" system produce unusable results.
Explain that the result is an equistore block object. Say that details on the equistore will be covered in the docs of equistore and that this tutorial can be used without knowing how it equistore works. It might already be worth it to emphasize that equistore is like numpy for atomistic ml data.
Look at the results: The shape and show some entries. Maybe talk about the magnitude of features that is reasonable.
1. Effects of changing max radial and max angular
Play with max radial and max angular; show that changing these will change number of features and explain that more features might give more accuracy but take longer to calculate.
2. Effects of the cutoff and the center_atom_weight
Play with the cutoff and reduce it to such a small value that only the center atom is in.
Reduce center atom weight so that all values go to zero
3. Discuss the radial scaling
Play with radial spectrum parameters. Explain what they mean.
radial scaling function should have a S-shape
Show a plot of it and play with the parameters.
4. Next steps
Link to the how-to guides and the reference guide. Also mention that we support gradients which are essential for creating an ML potential
PicoCentauri
commented
1 year ago
Our documentation is currently missing an introduction tutorial which is especially important for new users that never worked with rascaline or software that is calculating descriptors.
Idea
The language should be pure python and the tutorial should be created using sphinx galleries to avoid unmaintainable jupyter notebooks (For an initial draft a notebook is fine though). Before you start with a notebook please take time and make yourself familiar with the idea of a tutorial for example on the divio page. Most importantly don't go too much into details and focus on explaining the actual workflow of creating a representation from cartesian coordinates. Avoid abstraction and complicated and long code blocks.
Possible structure
0. The dataset
1. Calculate features with good & reasonable SOAP hyperparameters.
Use the SOAP spherical expansion calculator and use hyperparameters that could also be used for a real system. We don't want a set of parameters that if they are copied to a "real" system produce unusable results.
1. Effects of changing max radial and max angular
2. Effects of the cutoff and the center_atom_weight
3. Discuss the radial scaling
4. Next steps
Link to the how-to guides and the reference guide. Also mention that we support gradients which are essential for creating an ML potential