Skip to content

Improve consistency of the lattice API

Vicentini Filippo requested to merge lattice-api into master

Created by: femtobit

Since I've started to actively use Lattice in my own code recently, I have noticed a number of things in the interface that I think can be polished a bit.

In order to not burden you (specifically @chrisrothUT and @attila-i-szabo) with a lot of change requests in subsequent PRs, I've implemented several of the API changes I would like to see myself and propose them here as PR so we can discuss this early (also picking up some of the things that were left open when merging PR #702) and have a solid base for finalizing the symmetries (which this PR just moves around).

While it may look like a lot of changes, this PR is mostly just rearrangement and renaming with the aim of making the lattice interface more intuitive and also making the Lattice implementation easier to follow.

ID, position, and basis coords

Most importantly, I am trying to have the API use consistent terms for the different ways of referring to a lattice site or its location as mentions of position, coordinates, cell, label, etc. can easily get confusing otherwise.

Specifically, I propose the following naming convention which is described by the new Lattice docstring: https://github.com/netket/netket/blob/fc67fa3f526d627721ea7ab4ad8bd27087cc346d/netket/graph/lattice.py#L217-L252

I think by using these (or similar) terms consistently in the interface and having a symmetrical naming convention for look-up functions (id_from_position, id_from_basis_coords) the API becomes much easier to use.

Hashing / position-based lookup

As discussed in https://github.com/netket/netket/pull/702#discussion_r632435892, I've removed the references to "hashing" (as this is mostly an implementation detail of the dict lookup) and also extracted the id_from_position function (which is generally useful and thus should not be hidden in the internal API).

I hope these changes are not causing too many merge conflicts in anyone's code at the moment, otherwise I apologize, but I'd be very happy to get the Lattice interface polished before we finalize our work on the symmetries.

Let me know what you think.

Merge request reports