<style>
.reveal {
font-size: 22px;
}
</style>

## CECAM ASE workshop: Breakout 3 Training & Documentation

### Group Members

- Alin Elena
- Esmée Berger
- Auguste TETENOIRE
- Nawaz Qaisrani
- Elisabeth Keller
- Kutand Alkım Bayer (online)
- Morteza Chehel Amirani
- Svenja M. Janke

---

### What is the challenge?

1) Lack of clarity, actuality and visibility of the wiki
3) Tutorials
* Not up to date and untested
1) Documentation
* Lack of consistent documentation
5) Human resource - who will do what?

---

# Challenge 1: Lack of clarity, actuality and visibility of the wiki

- Hard to navigate and inconsistent
- Not beginner friendly
- Design (new template already in open MR: https://ase.gitlab.io/ase/)
- Domain name, hard to search for, logo
- Actuality of information

---

### Outline of how will it be addressed

- Clarity:
- Restructuring
- Templates and guideline for contributions
- Visibility:
- Steering comittee decides and creates domain name
- Usage of [CFF](https://citation-file-format.github.io/) to add citation of ASE (see, e.g., [here](https://github.com/stfc/janus-core/blob/main/CITATION.cff))
- Put news and events clearly on the web page
-  Good practice: use logo in talks
- Actuality of information
- Update list of used calculators, plugins

---

### Restructuring - Current TOC

Current TOC: 

---

#### Restructuring - New proposition

- Home (landing page, not in the TOC)
- About
- Contact
- Installation
- Tutorials/User guide
- Python
- ASE
- Getting started
- The current contents of 'tutorials'
- Issues (Link to the Gitlab issues page)
- Code snippets (something that is useful, too much to put in docstring but too little to make a full tutorial about)
- Command line tool
- Tips and tricks
- Making movies (currently in 'development')
- FAQ
- Development
- API Documentation (currently 'modules')
- Developers guide (currently 'development')
- Gallery
- ASE ecosystem
- Events
- ASE Workshop 2019 - Chalmers
- Ase Workshop 2023 - Copenhagen
- ASE workshop 2023 - Daresbury
- ASE Workshop 2025 - Lausanne
- Release notes

---

### `Skip in presentation`: more details about the contents on some pages

* Home/landing page
* The ASE logo should be there (fixed in the MR with the new template)
* Clearly say what is ASE (much of what is currently in the 'About' page should be on the first page)
* Should contain info on how to cite
* MWE (This should run with a minimal install and not require NWChem, could use EMT instead) - move a bit to the bottom
* Calculator logos. Some are missing.
* The current first page is too long because of the TOC. Make it concise and informative. If one wants to have more one could add collapsable sections and not move away any of the current.
* Make the latest news entry highlighed/more visible

* About
* Remove what is currently on the about page (move that to first page)
* Add a bit of history
* Mention who are the current active developers and 'for getting in contact, please see the contact(link) page'

* Installation
* Good in general
* In the pip install section clearly say that one should make sure to have a virtual environment (this is somewhere on the page but should be clearer)
* The ase test (bottom) does not work
* All code snippets should be tested

* ASE ecosystem
* Add a diagram/graph which also includes the calculators

* Gallery
* Remove he wode not working
* add examples that are used in papers, link to paper, and the code to be download to reproduce figure
* Event
* refactore the ASE workshop 2019
* add the other workshops
* add the events

---

# Challenge 2: Tutorials

- Not up to date
- Untested
- Unintuitive to new users

---

### Outline of how will it be addressed

**0) Scope**
Tutorials teach how to achieve a broader scientific goal involving several parts of ASE targeted mainly at users

**1) Guidelines and structure**
- Interactive: Jupyter/Marimo notebooks Good examples: *e.g.*, [wfl](https://libatoms.github.io/workflow/), [Plumed](https://www.plumed.org/tutorials), [dynasor](https://dynasor.materialsmodeling.org/tutorials/index.html), [janus-core](https://stfc.github.io/janus-core/), [icet](https://icet.materialsmodeling.org), etc.
- Ensure users are able to run example on own local environment, *e.g.* [this tutorial](https://stfc.github.io/janus-core/tutorials/python/single_point.html))
- Ensure compatibility with current version of ASE (add them in the CI (test run))
- Template: Title, Purpose of Tutorial, Main Tutorial, References/Name of contributor
- (Structure of good [MR example](https://https://gitlab.com/ase/ase/-/merge_requests/3550))

---

**3) Old tutorials - restructuring**
- Restructuring: Add landing page, split between basics and advanced tutorials with thematic categories
- Link to already existing external tutorials, e.g. [this tutorial](https://ase-workshop-2023.github.io/tutorial/)

**4) New tutorials - contributions**
- Improve ease of contributions (Add contributors names to encourage contributions, add how to contribute tutorials in the wiki)
- Enforce usage of template
- Every tutorials (and notebooks) must have version of packages.

---

## Detailed proposition: Tutorials

Challenge: Getting started/tutorials currently a bit unstructured.

Solution: Combining Getting started + Tutorials and rearranging tutorial topics

---

### Getting started:

Problems:
- Most tutorials formulated as exercises:
- expects people to already know how to use ASE --> discouraging
- Most tutorials use external calculators
--> if calculator not installed, tutorial won't work

---

### Basic solution: Rearrangement
1. Introduction: Nitrogen on copper (because best tutorial among the rest in the section )
2. External calculators (because other tutorials use an external calculator)
3. Atoms and calculators --> Energy optimisation of diatomic molecule N2
4. Structure optimization: H2O
5. Nanoparticle
6. Crystals and band structure
7. Manipulating atoms

---

### Extended solution: Rewrite, from simple to extended systems
Rewrite tutorials and going from simple molecule to extended system

Rewrite tutorials:
- Go through solution step by step, i.e., explain to beginner without experience
- Check tutorials for completeness, e.g., if MD mentioned, give example
- Merge: Atoms and calculators with basic property calculations from tutorials

From simple to extended system:
1. Structure optimization: H2O
2. Nanoparticle
3. Crystal structure
4. Surface
5. Composite systems (e.g., molecule on surface)

---

### Tutorial:
- Rearrange
1. Basic property calculations
2. Molecular Dynamics
3. Surface Adsorption
4. Global optimization
5. Calculating diffusion/dissociation properties
6. Uncategorized
7. ASE database

- More details on each computational step in tutorials
- Formate: all tutorials should follow the same formate

---

### Tutorial template (Jupyter notebook)


---

# Challenge 3: Documentation

- Source code serves as documentation
- Lack of consistency
- Missing documentation for some function/object

---

### Outline of how will it be addressed

**0) Scope** precise and consistent documentation of the functions and objects of ASE including minimal examples targeted at users and developers

**1) Guidelines and Structure**
- Guideline: all functionalities require a docstring and they should be accompanied by a minimal working example (short -> docstring, long -> code snippet of user guide section)
- Minimal template: explain the arguments and outputs (variable type, structure), link to kwargs, and give minial example.( we can inspire from [numpy](https://numpy.org/doc/stable/reference/generated/numpy.arange.html) or [matplotlib](https://matplotlib.org/stable/api/_as_gen/ )
- Documentation can be exported as pdf

**2) Update current documentation**
- Open issues for each file of the code and review it step by step

**3) Documentation for new code contributions**
- Enforce new contribution to follow documentation guidelines before being merged

---

### Suggestion to update current documentation

Original code:

def set_cell(self, cell, scale_atoms=False, apply_constraint=True):
        """Set unit cell vectors.

        Parameters:

        cell: 3x3 matrix or length 3 or 6 vector
            Unit cell.  A 3x3 matrix (the three unit cell vectors) or
            just three numbers for an orthorhombic cell. Another option is
            6 numbers, which describes unit cell with lengths of unit cell
            vectors and with angles between them (in degrees), in following
            order: [len(a), len(b), len(c), angle(b,c), angle(a,c),
            angle(a,b)].  First vector will lie in x-direction, second in
            xy-plane, and the third one in z-positive subspace.
   ``     scale_atoms: bool
            Fix atomic positions or move atoms with the unit cell?
            Default behavior is to *not* move the atoms (scale_atoms=False).
        apply_constraint: bool
            Whether to apply constraints to the given cell.

        Examples:

        Two equivalent ways to define an orthorhombic cell:

        >>> atoms = Atoms('He')
        >>> a, b, c = 7, 7.5, 8
        >>> atoms.set_cell([a, b, c])
        >>> atoms.set_cell([(a, 0, 0), (0, b, 0), (0, 0, c)])

        FCC unit cell:

        >>> atoms.set_cell([(0, b, b), (b, 0, b), (b, b, 0)])

        Hexagonal unit cell:

        >>> atoms.set_cell([a, a, c, 90, 90, 120])

        Rhombohedral unit cell:

        >>> alpha = 77
        >>> atoms.set_cell([a, a, a, alpha, alpha, alpha])
        """

        # Override pbcs if and only if given a Cell object:
        cell = Cell.new(cell)

        # XXX not working well during initialize due to missing _constraints
        if apply_constraint and hasattr(self, '_constraints'):
            for constraint in self.constraints:
                if hasattr(constraint, 'adjust_cell'):
                    constraint.adjust_cell(self, cell)

        if scale_atoms:
            M = np.linalg.solve(self.cell.complete(), cell.complete())
            self.positions[:] = np.dot(self.positions, M)

        self.cell[:] = cell

---

Copilot prompt asking for creating docstring of the same set_cell funtion without docstring

def set_cell(self, cell, scale_atoms=False, apply_constraint=True):
    """
    Set a new simulation cell for the atomic system.

    Parameters:
    -----------
    cell : array-like or Cell object
        The new cell to be assigned. This can be a list, array, or a Cell object.
        It will be converted to a Cell object internally.

    scale_atoms : bool, optional (default=False)
        If True, atom positions will be scaled according to the transformation
        between the old and new cell. This preserves the relative positions of atoms
        within the new cell.

    apply_constraint : bool, optional (default=True)
        If True, and if the object has constraints that support cell adjustment,
        those constraints will be applied to the new cell.

    Notes:
    ------
    - If `apply_constraint` is True and the object has constraints with an
      `adjust_cell` method, those constraints will be invoked to modify the cell.
    - The transformation matrix used for scaling atoms is computed by solving
      the linear system that maps the old cell to the new one.
    """
    # Override pbcs if and only if given a Cell object:
    cell = Cell.new(cell)

    # XXX not working well during initialize due to missing _constraints
    if apply_constraint and hasattr(self, '_constraints'):
        for constraint in self.constraints:
            if hasattr.adjust_cell(self, cell)

    if scale_atoms:
        M = np.linalg.solve(self.cell.complete(), cell.complete())
        self.positions[:] = np.dot(self.positions, M)

    self.cell[:] = cell

---

# Challenge 4: Human resource - who will do what?

- Hard to encourage people to contribute and maintain tutorials
- How to enforce to create documentation
- How to motivate updating existing documentation

---

### Outline of how will it be addressed

- Create a ASE-wiki group
- coordination of tutorial, maintaining up-to-date ASE website, taking decision to be aproved by steering-comitee
- Do a volunteer call to participate in the ASE-wiki group
- Create a placeholder on the website so one can propose tutorial tutorial contributions

---

## General conclusion

---

## Strengths of proposed approach

- Engage the community

---

## Weaknesses of proposed approach

- Hard to emulate people to actually do the work

---

## Opportunities of proposed approach

- Easier to use and advertise ASE
- Well structured tutorials and documentation
- Easier to maintain ASE
- Involving the whole community

---

## Threats to proposed approach

- People does not engage

---

### Who will do this work?

- Managed by the ASE-wiki group (aproved by the steering comitee)
- Any volunteer from the scientific comunity

---

### Timeline for implementation

- The restructuring of the documentation can be done rather soon. This includes checking that the current tutorials work.
- The information for how to cite ASE clearly can be easily done.
- The addition of new tutorials is continuous and down to volonteers who would like to add these.

---

### Conclusion

- We reviewed the website and documentation
- We came with a strategy to update and improve it
- Suggested guidelines/templates for documentation and tutorials

Actionable items:
- Audience: Feedback on guidelines/templates
- Steering committee: website domain name
- Create ASE-wiki group
- Do volunteer call to several mailing list
- Create the templates and guideline
- Split the work of updating by splitting tasks
- To update current documentation, creat git issues and update step by step

Open questions:
- Who will organize the ASE-wiki group?

---

### Tutorial template (Jupyter notebook)
Some "pseudocode"

# Intro
{Descriptive title
In this tutorial you will learn...}

# Imports:
From ase import ...

# Main tutorial blocks. Repeat as needed
{Description of upcoming code/plan/step}

Code block

(Possibly output/plots. If so, commentary.)


# Conclusion
{If necessary, conclusion, possibly pointing to "further resources/refs."}