226 feature add simple first examplypy

README.rst

@@ -40,65 +40,60 @@ Resources
 .. _Video: https://www.youtube.com/watch?v=7nVCuuZDCYA
 .. _Code: https://github.com/lettucecfd/lettuce-paper
 
-
-Resources
----------
-
-- `Documentation`_
-- Presentation at CFDML2021 - `Preprint`_ | `Slides`_ | `Video`_ | `Code`_
-
-.. _Documentation: https://lettuceboltzmann.readthedocs.io
-.. _Preprint: https://arxiv.org/pdf/2106.12929.pdf
-.. _Slides: https://drive.google.com/file/d/1jyJFKgmRBTXhPvTfrwFs292S4MC3Fqh8/view
-.. _Video: https://www.youtube.com/watch?v=7nVCuuZDCYA
-.. _Code: https://github.com/lettucecfd/lettuce-paper
-
 Getting Started
 ---------------
 
-The following Python code will run a two-dimensional Taylor-Green vortex on a GPU:
+To find some very simple examples of how to use lettuce, please have a look
+at the examples_. These will guide you through lettuce's main features. The
+simplest example is:
 
-.. code:: python
+https://github.com/lettucecfd/lettuce/blob/ef9830b59c6ad50e02fdf0ce24cc47ea520aa354/examples/00_simplest_TGV.py#L6-L21
 
-    import torch
-    import lettuce as lt
-
-    lattice = lt.Lattice(lt.D2Q9, device='cuda', dtype=torch.float64, use_native=False)  # for running on cpu: device='cpu'
-    flow = lt.TaylorGreenVortex2D(resolution=128, reynolds_number=100, mach_number=0.05, lattice=lattice)
-    collision = lt.BGKCollision(lattice, tau=flow.units.relaxation_parameter_lu)
-    streaming = lt.StandardStreaming(lattice)
-    simulation = lt.Simulation(flow=flow, lattice=lattice, collision=collision, streaming=streaming)
-    mlups = simulation.step(num_steps=1000)
-    print("Performance in MLUPS:", mlups)
-
-More advanced examples_ are available as jupyter notebooks.
-
-Please ensure you have Jupyter installed to run these notebooks.
+Please ensure you have Jupyter installed to run the Jupyter notebooks.
 
 .. _examples: https://github.com/lettucecfd/lettuce/tree/master/examples
 
 Installation
 ------------
 
-* Install the anaconda package manager from www.anaconda.org
-* Create a new conda environment and install PyTorch::
+* Install the anaconda or miniconda package manager from www.anaconda.org
+* Create a new conda environment and activate it::
+
+    conda create -n lettuce
+    conda activate lettuce
+
+* Follow the recommendations at https://pytorch.org/get-started/locally/ to
+install pytorch based on your GPU's CUDA version. You may need to install
+the nvidia toolkit. You may follow the instructions at https://developer
+.nvidia.com/cuda-downloads. You may need to check the compatibility of your
+NVIDIA driver with the desired CUDA version:
+https://docs.nvidia.com/deploy/cuda-compatibility/. To get your CUDA version,
+run::
 
-    conda create -n lettuce -c pytorch -c nvidia pytorch pytorch-cuda=12.1
+    nvcc --version
 
-* Activate the conda environment::
+* For CUDA 12.1 (if supported by your GPU) use::
+
+    conda install pytorch pytorch-cuda=12.1 -c pytorch -c nvidia
+
+* Install the remaining dependencies::
 
     conda activate lettuce
+    conda install -c pytorch -c conda-forge matplotlib pytest click pyevtk mmh3 h5py scipy pandas numpy
 
-* Install all requirements::
+* Clone this repository from github and change to it::
 
-    conda install -c conda-forge -c anaconda matplotlib pytest click pyevtk h5py mmh3
+    git clone https://github.com/lettucecfd/lettuce
+    cd lettuce
 
-* Clone this repository from github
-* Change into the cloned directory
-* Run the install script::
+* If you want to only **USE** lettuce, run the install script::
 
     python setup.py install
 
+* If you are a **developer**, do this to update the lettuce package when running a script::
+
+    python setup.py develop
+
 * Run the test cases::
 
     python setup.py test
@@ -107,15 +102,14 @@ Installation
 
     lettuce --no-cuda convergence
 
-* For running a CUDA-driven LBM simulation on one GPU omit the `--no-cuda`. If CUDA is not found,
-  make sure that cuda drivers are installed and compatible with the installed cudatoolkit
-  (see conda install command above).
+* For running a CUDA-driven LBM simulation on one GPU omit the `--no-cuda`.
+If CUDA is not found, make sure that cuda drivers are installed and
+compatible with the installed cudatoolkit (see conda install command above).
 
 * Check out the performance, running on GPU::
 
     lettuce benchmark
 
-
 Citation
 --------
 If you use Lettuce in your research, please cite the following paper::
@@ -128,7 +122,6 @@ If you use Lettuce in your research, please cite the following paper::
       organization={Springer Nature}
     }
 
-
 Credits
 -------
 We use the following third-party packages:

examples/00_simplest_TGV.py

@@ -0,0 +1,21 @@
+"""
+This file showcases the simplicity of the lettuce code.
+The following code will run a two-dimensional Taylor-Green vortex on GPU.
+"""
+
+import torch
+import lettuce as lt
+
+flow = lt.TaylorGreenVortex(
+    lt.Context(dtype=torch.float64),  # for running on cpu: device='cpu'
+    resolution=128,
+    reynolds_number=100,
+    mach_number=0.05,
+    stencil=lt.D2Q9
+)
+simulation = lt.Simulation(
+    flow=flow,
+    collision=lt.BGKCollision(tau=flow.units.relaxation_parameter_lu),
+    reporter=[])
+mlups = simulation(num_steps=1000)
+print("Performance in MLUPS:", mlups)

lettuce/ext/_flows/liddrivencavity.py

@@ -61,7 +61,8 @@ def boundaries(self):
             BounceBackBoundary(boundary),
             # moving fluid on top# moving bounce back top
             EquilibriumBoundaryPU(
-                self.context, top, 
+                self.context,
+                top,
                 [float(self.units.characteristic_velocity_pu), 0.0]
             ),
         ]

lettuce/util/moments.py

@@ -254,9 +254,8 @@ def equilibrium(self, m):
 
 
 """
-D3Q19 is not implemented, yet. Also, the moments should be ordered so that 
-1...D+1 correspond to momentum,
-which is no the case for this matrix.
+D3Q19 is not implemented, yet. Also, the moments should be ordered so that
+1...D+1 correspond to momentum, which is no the case for this matrix.
 """