Rough example using periodic grid

[marco-2023]

@FarnazH @Ali-Tehrani This is a really rough example showcasing the most basic periodic grid functionalities. I want to discuss if you have any other ideas regarding this.

[azhar-ikhtiarudin]

Hi @PaulWAyers and @marco-2023, I am interested to contribute by adding or enhancing this documentation. I checked the API documentation and found that examples for the PeriodicGrid class are not yet available (https://grid.qcdevs.org/pyapi/grid.periodicgrid.html) . I also reviewed the issue 184 which probably related, as well as this pull requests.

I already checked and studied the rough example by @marco-2023 here and it's already great. However, it seems the last update was in January last year, so I assume it has not been updated since.

May I work on this? I have a background in solid-state physics, as well as fundamental quantum mechanics and quantum chemistry, which gives me a basic understanding of periodic boundary conditions. I am planning to write a short introduction to concepts such as the Bravais lattice, as outlined/mentioned in the official API descriptions.

My proposed structure plan is as follows:

1. Brief Background

   • The motivation and importance of grids with periodic boundary conditions.
   • A review of basic crystallographic concepts: Bravais lattice, reciprocal lattice, and fractional coordinates.

2. Comparison of Uniform Grid and PeriodicGrid

   • Adapted from the current notebook [ ].

3. Additional Examples

   • Illustrating the use of the get_localgrid() method.
   • Demonstrating the functionality of the integrate() method.
   • Providing examples for the moments() method.

I am open to any additional suggestions for the structure.

Thank you so much

[azhar-ikhtiarudin]

Dear @PaulWAyers @marco-2023 @FarnazH @Ali-Tehrani, here is the draft for the PeriodicGrid class Jupyter Notebook tutorial, which has been partially improved based on Marco's earlier version:

https://colab.research.google.com/drive/1CQBtJy2xhzK2NUfv0X4YKE2NAKtelvEt?usp=sharing

I have added an introductory section, an example of a 2D simple rectangular lattice using a unit cell from tensor1DGrid, and an integration of electron density within a sphere. I understand that it might need to be explored more deeply, but before going further, I’d like to check if I’m heading in the right direction by asking a few questions:

1. Should I visualize or further explain the periodic grid calculation in 1D, as described with ASCII art in the API documentation? Would it be better to recreate this with graphics?
2. Should I keep the 2D example, or is it not necessary? If it’s useful, is showing the rectangular lattice vectors enough, or should I also include comparisons with other lattice types such as hexagonal or oblique?
3. Am I allowed to use images from the internet (with proper citation), as I did in the 2D periodic grid visualizations? Or should the graphics be redesigned instead?
4. Should I add more examples, for instance, by exploring other properties such as electrostatic potential?
5. One feature I don’t fully understand is the addition of a periodic repetition of a local function to the parent grid using np.add.at(). Should this also be included as an example in the tutorial? I would appreciate more guidance on a suitable use case for this.

I would be very grateful for any feedback or suggestions.

Thank you