{"id":15898682,"url":"https://github.com/dylanljones/lattpy","last_synced_at":"2025-04-07T06:08:00.965Z","repository":{"id":37269350,"uuid":"257843833","full_name":"dylanljones/lattpy","owner":"dylanljones","description":"Simple and efficient Python package for modeling d-dimensional Bravais lattices in solid state physics.","archived":false,"fork":false,"pushed_at":"2025-02-17T19:42:26.000Z","size":1517,"stargazers_count":39,"open_issues_count":3,"forks_count":12,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-31T04:08:10.085Z","etag":null,"topics":["bravais","bravais-lattice","computational-physics","crystal","high-dimensional","lattice","nearest-neighbors","neighbors","physics","python","solid-state-physics"],"latest_commit_sha":null,"homepage":"https://lattpy.readthedocs.io/en/stable/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dylanljones.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-22T08:46:36.000Z","updated_at":"2024-12-29T12:48:50.000Z","dependencies_parsed_at":"2024-01-29T20:40:23.710Z","dependency_job_id":"0c2658c9-f877-4470-b8b1-f008ec66e85f","html_url":"https://github.com/dylanljones/lattpy","commit_stats":{"total_commits":548,"total_committers":4,"mean_commits":137.0,"dds":0.04744525547445255,"last_synced_commit":"852005e4ec85118229c1237cd1eb6272053a0f5f"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylanljones%2Flattpy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylanljones%2Flattpy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylanljones%2Flattpy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylanljones%2Flattpy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dylanljones","download_url":"https://codeload.github.com/dylanljones/lattpy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247601448,"owners_count":20964864,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bravais","bravais-lattice","computational-physics","crystal","high-dimensional","lattice","nearest-neighbors","neighbors","physics","python","solid-state-physics"],"created_at":"2024-10-06T10:07:28.047Z","updated_at":"2025-04-07T06:08:00.942Z","avatar_url":"https://github.com/dylanljones.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/dylanljones/lattpy/dev/docs/source/_static/header.png\" width=\"800\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eLattPy - Simple Lattice Modeling in Python\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://pypi.org/project/lattpy/\"\u003e\u003cimg alt=\"Python Version\" src=\"https://img.shields.io/badge/python-3.7+-blue.svg\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/lattpy/\"\u003e\u003cimg alt=\"Version\" src=\"https://img.shields.io/pypi/v/lattpy?logo=pypi\u0026style=flat\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/lattpy/\"\u003e\u003cimg alt=\"Status\" src=\"https://img.shields.io/pypi/status/lattpy?color=yellow\u0026style=flat\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://pepy.tech/project/lattpy\"\u003e\u003cimg alt=\"Downloads\" src=\"https://pepy.tech/badge/lattpy?style=flat\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/dylanljones/lattpy/blob/master/LICENSE\"\u003e\u003cimg alt=\"MIT License\" src=\"https://img.shields.io/github/license/dylanljones/lattpy?color=lightgray\u0026style=flat\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/psf/black\"\u003e\u003cimg alt=\"Code style: black\" src=\"https://img.shields.io/badge/code%20style-black-000000.svg?style=flat\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/dylanljones/lattpy/actions/workflows/codeql.yml\"\u003e\u003cimg alt=\"LGTM Grade\" src=\"https://github.com/dylanljones/lattpy/actions/workflows/codeql.yml/badge.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n:warning: **WARNING**: This project is still in development and might change significantly in the future!\n\n*LattPy* is a simple and efficient Python package for modeling Bravais lattices and\nconstructing (finite) lattice structures in any dimension.\nIt provides an easy interface for constructing lattice structures by simplifying the\nconfiguration of the unit cell and the neighbor connections - making it possible to\nconstruct complex models in just a few lines of code and without the headache of\nadding neighbor connections manually. You will save time and mental energy for more important matters.\n\n| Master | [![Test][tests-master]][link-tests] | [![Codecov][codecov-master]][codecov-master-link] | [![Read the Docs][docs-master]][docs-master-link] |\n|:-------|:------------------------------------|:--------------------------------------------------|:--------------------------------------------------|\n| Dev    | [![Test][tests-dev]][link-tests]    | [![Codecov][codecov-dev]][codecov-dev-link]       | [![Read the Docs][docs-dev]][docs-dev-link]       |\n\n\n## 🔧 Installation\n\nLattPy is available on [PyPI](https://pypi.org/project/lattpy/):\n````commandline\npip install lattpy\n````\n\nAlternatively, it can be installed via [GitHub](https://github.com/dylanljones/lattpy)\n```commandline\npip install git+https://github.com/dylanljones/lattpy.git@VERSION\n```\nwhere `VERSION` is a release or tag. The project can also be\ncloned/forked and installed via\n````commandline\npython setup.py install\n````\n\n## 📖 Documentation\n\n[Read the documentation on ReadTheDocs!][docs-stable-link]\n\n## 🚀 Quick-Start\n\nSee the [tutorial][docs-tutorial-link] for more information and examples.\n\nFeatures:\n\n- Basis transformations\n- Configurable unit cell\n- Easy neighbor configuration\n- General lattice structures\n- Finite lattice models in world or lattice coordinates\n- Periodic boundary conditions along any axis\n\n### Configuration\n\nA new instance of a lattice model is initialized using the unit-vectors of the Bravais lattice.\nAfter the initialization the atoms of the unit-cell need to be added. To finish the configuration\nthe connections between the atoms in the lattice have to be set. This can either be done for\neach atom-pair individually by calling ``add_connection`` or for all possible pairs at once by\ncallling ``add_connections``. The argument is the number of unique\ndistances of neighbors. Setting a value of ``1`` will compute only the nearest\nneighbors of the atom.\n````python\nimport numpy as np\nfrom lattpy import Lattice\n\nlatt = Lattice(np.eye(2))                 # Construct a Bravais lattice with square unit-vectors\nlatt.add_atom(pos=[0.0, 0.0])             # Add an Atom to the unit cell of the lattice\nlatt.add_connections(1)                   # Set the maximum number of distances between all atoms\n\nlatt = Lattice(np.eye(2))                 # Construct a Bravais lattice with square unit-vectors\nlatt.add_atom(pos=[0.0, 0.0], atom=\"A\")   # Add an Atom to the unit cell of the lattice\nlatt.add_atom(pos=[0.5, 0.5], atom=\"B\")   # Add an Atom to the unit cell of the lattice\nlatt.add_connection(\"A\", \"A\", 1)          # Set the max number of distances between A and A\nlatt.add_connection(\"A\", \"B\", 1)          # Set the max number of distances between A and B\nlatt.add_connection(\"B\", \"B\", 1)          # Set the max number of distances between B and B\nlatt.analyze()\n````\n\nConfiguring all connections using the ``add_connections``-method will call the ``analyze``-method\ndirectly. Otherwise this has to be called at the end of the lattice setup or by using\n``analyze=True`` in the last call of ``add_connection``. This will compute the number of neighbors,\ntheir distances and their positions for each atom in the unitcell.\n\nTo speed up the configuration prefabs of common lattices are included. The previous lattice\ncan also be created with\n````python\nfrom lattpy import simple_square\n\nlatt = simple_square(a=1.0, neighbors=1)  # Initializes a square lattice with one atom in the unit-cell\n````\n\nSo far only the lattice structure has been configured. To actually construct a (finite) model of the lattice\nthe model has to be built:\n````python\nlatt.build(shape=(5, 3))\n````\nThis will compute the indices and neighbors of all sites in the given shape and store the data.\n\nAfter building the lattice periodic boundary conditions can be set along one or multiple axes:\n````python\nlatt.set_periodic(axis=0)\n````\n\nTo view the built lattice the `plot`-method can be used:\n````python\nimport matplotlib.pyplot as plt\n\nlatt.plot()\nplt.show()\n````\n\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/dylanljones/lattpy/master/docs/source/_static/example_square_periodic.png\" width=\"400\"\u003e\n\u003c/p\u003e\n\n### General lattice attributes\n\n\nAfter configuring the lattice the attributes are available.\nEven without building a (finite) lattice structure all attributes can be computed on the fly for a given lattice vector,\nconsisting of the translation vector `n` and the atom index `alpha`. For computing the (translated) atom positions\nthe `get_position` method is used. Also, the neighbors and the vectors to these neighbors can be calculated.\nThe `dist_idx`-parameter specifies the distance of the neighbors (0 for nearest neighbors, 1 for next nearest neighbors, ...):\n````python\nfrom lattpy import simple_square\n\nlatt = simple_square()\n\n# Get position of atom alpha=0 in the translated unit-cell\npositions = latt.get_position(n=[0, 0], alpha=0)\n\n# Get lattice-indices of the nearest neighbors of atom alpha=0 in the translated unit-cell\nneighbor_indices = latt.get_neighbors(n=[0, 0], alpha=0, distidx=0)\n\n# Get vectors to the nearest neighbors of atom alpha=0 in the translated unit-cell\nneighbor_vectors = latt.get_neighbor_vectors(alpha=0, distidx=0)\n````\n\nAlso, the reciprocal lattice vectors can be computed\n````python\nrvecs = latt.reciprocal_vectors()\n````\n\nor used to construct the reciprocal lattice:\n````python\nrlatt = latt.reciprocal_lattice()\n````\n\nThe 1. Brillouin zone is the Wigner-Seitz cell of the reciprocal lattice:\n````python\nbz = rlatt.wigner_seitz_cell()\n````\n\nThe 1.BZ can also be obtained by calling the explicit method of the direct lattice:\n````python\nbz = latt.brillouin_zone()\n````\n\n\n### Finite lattice data\n\n\nIf the lattice has been built the needed data is cached. The lattice sites of the\nstructure then can be accessed by a simple index `i`. The syntax is the same as before,\njust without the `get_` prefix:\n\n````python\nlatt.build((5, 2))\ni = 2\n\n# Get position of the atom with index i=2\npositions = latt.position(i)\n\n# Get the atom indices of the nearest neighbors of the atom with index i=2\nneighbor_indices = latt.neighbors(i, distidx=0)\n\n# the nearest neighbors can also be found by calling (equivalent to dist_idx=0)\nneighbor_indices = latt.nearest_neighbors(i)\n````\n\n### Data map\n\nThe lattice model makes it is easy to construct the (tight-binding) Hamiltonian of a non-interacting model:\n\n\n````python\nimport numpy as np\nfrom lattpy import simple_chain\n\n# Initializes a 1D lattice chain with a length of 5 atoms.\nlatt = simple_chain(a=1.0)\nlatt.build(shape=4)\nn = latt.num_sites\n\n# Construct the non-interacting (kinetic) Hamiltonian-matrix\neps, t = 0., 1.\nham = np.zeros((n, n))\nfor i in range(n):\n    ham[i, i] = eps\n    for j in latt.nearest_neighbors(i):\n        ham[i, j] = t\n````\n\n\nSince we loop over all sites of the lattice the construction of the hamiltonian is slow.\nAn alternative way of mapping the lattice data to the hamiltonian is using the `DataMap`\nobject returned by the `map()` method of the lattice data. This stores the atom-types,\nneighbor-pairs and corresponding distances of the lattice sites. Using the built-in\nmasks the construction of the hamiltonian-data can be vectorized:\n````python\nfrom scipy import sparse\n\n# Vectorized construction of the hamiltonian\neps, t = 0., 1.\ndmap = latt.data.map()               # Build datamap\nvalues = np.zeros(dmap.size)         # Initialize array for data of H\nvalues[dmap.onsite(alpha=0)] = eps   # Map onsite-energies to array\nvalues[dmap.hopping(distidx=0)] = t  # Map hopping-energies to array\n\n# The indices and data array can be used to construct a sparse matrix\nham_s = sparse.csr_matrix((values, dmap.indices))\nham = ham_s.toarray()\n````\n\nBoth construction methods will create the following Hamiltonian-matrix:\n````\n[[0. 1. 0. 0. 0.]\n [1. 0. 1. 0. 0.]\n [0. 1. 0. 1. 0.]\n [0. 0. 1. 0. 1.]\n [0. 0. 0. 1. 0.]]\n````\n\n## 🔥 Performance\n\n\nEven though `lattpy` is written in pure python, it achieves high performance and\na low memory footprint by making heavy use of numpy's vectorized operations and scipy's\ncKDTree. As an example the build times and memory usage in the build process for different\nlattices are shown in the following plots:\n\n\n|                                               Build time                                                |                                               Build memory                                                |\n|:-------------------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------:|\n| \u003cimg src=\"https://raw.githubusercontent.com/dylanljones/lattpy/master/benchmarks/bench_build_time.png\"\u003e | \u003cimg src=\"https://raw.githubusercontent.com/dylanljones/lattpy/master/benchmarks/bench_build_memory.png\"\u003e |\n\n\n\nNote that the overhead of the multi-thread neighbor search results in a slight\nincrease of the build time for small systems. By using `num_jobs=1` in the `build`-method\nthis overhead can be eliminated for small systems. By passing `num_jobs=-1` all cores\nof the system are used.\n\n\n## 💻 Development\n\nSee the [CHANGELOG](https://github.com/dylanljones/lattpy/blob/master/CHANGELOG.md) for\nthe recent changes of the project.\n\nIf you encounter an issue or want to contribute to pyrekordbox, please feel free to\nget in touch, [create an issue](https://github.com/dylanljones/lattpy/issues/new/choose)\nor open a pull request! A guide for contributing to `lattpy` and the commit-message style can be found in\n[CONTRIBUTING](https://github.com/dylanljones/lattpy/blob/master/CONTRIBUTING.md)\n\n\n[docs-stable-link]: https://lattpy.readthedocs.io/en/stable/\n[docs-tutorial-link]: https://lattpy.readthedocs.io/en/stable/tutorial/index.html\n\n[tests-master]: https://img.shields.io/github/actions/workflow/status/dylanljones/lattpy/test.yml?branch=master\u0026label=tests\u0026logo=github\u0026style=flat\n[tests-dev]: https://img.shields.io/github/actions/workflow/status/dylanljones/lattpy/test.yml?branch=dev\u0026label=tests\u0026logo=github\u0026style=flat\n[link-tests]: https://github.com/dylanljones/lattpy/actions/workflows/test.yml\n[codecov-master]: https://codecov.io/gh/dylanljones/lattpy/branch/master/graph/badge.svg?\n[codecov-master-link]: https://app.codecov.io/gh/dylanljones/lattpy/branch/master\n[codecov-dev]: https://codecov.io/gh/dylanljones/lattpy/branch/dev/graph/badge.svg?\n[codecov-dev-link]: https://app.codecov.io/gh/dylanljones/lattpy/branch/dev\n[docs-master]: https://img.shields.io/readthedocs/lattpy/latest?style=flat\u0026logo=readthedocs\n[docs-master-link]: https://lattpy.readthedocs.io/en/latest/\n[docs-dev]: https://img.shields.io/readthedocs/lattpy/dev?style=flat\u0026logo=readthedocs\n[docs-dev-link]: https://lattpy.readthedocs.io/en/dev/\n\n[code-ql]: https://github.com/dylanljones/lattpy/actions/workflows/codeql.yml/badge.svg\n[code-ql-link]: https://github.com/dylanljones/lattpy/actions/workflows/codeql.yml\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdylanljones%2Flattpy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdylanljones%2Flattpy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdylanljones%2Flattpy/lists"}