Update README and add example for Landau damping simulation

Author: rogeriojorge

README.md

@@ -48,16 +48,17 @@
 
 ##  Overview
 
-JAX-in-Cell is an open-source project in Python that uses JAX to speedup simulations, leading to a simple to use, fast and concise code. It can be imported in a Python script using the **jaxincell** package, or run directly in python using its `simulation()` function. To install it, use
+JAX-in-Cell is an open-source project in Python that uses JAX to speedup simulations, leading to a simple to use, fast and concise code. It can be imported in a Python script using the **jaxincell** package, or run directly in the command line as `jaxincell`. To install it, use
 
    ```sh
    pip install jaxincell
    ```
 
-Alternatively, you can simple install the Python dependencies `jax`, `jax_tqdm` and `matplotlib`, and run the `main.py` script in the repository after downloading it as
+Alternatively, you can install the Python dependencies `jax`, `jax_tqdm` and `matplotlib`, and run the [example script](example_script.py) in the repository after downloading it as
 
    ```sh
-   python main.py
+   git clone https://github.com/uwplasma/JAX-in-Cell
+   python example_script.py
    ```
 
 This allows JAX-in-Cell to be run without any installation.
@@ -159,7 +160,7 @@ To run a simple case of JAX-in-Cell, you can simply call `jaxincell` from the te
 jaxincell
 ```
 
-This runs JAX-in-Cell using standard input parameters of the two-stream instability. To change input parameters, use a TOML file similar to the [example input](example_input.toml) present in the repository as
+This runs JAX-in-Cell using standard input parameters of Landau damping. To change input parameters, use a TOML file similar to the [example input](example_input.toml) present in the repository as
 
 ```sh
 jaxincell example_input.toml

examples/Landau_damping.py

@@ -0,0 +1,34 @@
+## Langmuir_wave.py
+# Example of plasma oscillations of electrons
+import os, sys;
+sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
+from jaxincell.plot import plot
+from jaxincell.simulation import simulation
+import jax.numpy as jnp
+from jax import block_until_ready
+
+input_parameters = {
+"length"                       : 1e-2,  # dimensions of the simulation box in (x, y, z)
+"amplitude_perturbation_x"     : 5e-4,  # amplitude of sinusoidal perturbation in x
+"wavenumber_electrons": 8, # Wavenumber of sinusoidal electron density perturbation in x (factor of 2pi/length)
+"grid_points_per_Debye_length" : 5,     # dx over Debye length
+"vth_electrons_over_c"         : 0.05,  # thermal velocity of electrons over speed of light
+"ion_temperature_over_electron_temperature": 1e-9, # Temperature of ions over temperature of electrons
+"timestep_over_spatialstep_times_c": 0.5, # dt * speed_of_light / dx
+"print_info"                   : True,  # print information about the simulation
+}
+
+solver_parameters = {
+    "field_solver"           : 0,    # Algorithm to solve E and B fields - 0: Curl_EB, 1: Gauss_1D_FFT, 2: Gauss_1D_Cartesian, 3: Poisson_1D_FFT, 
+    "number_grid_points"     : 33,  # Number of grid points
+    "number_pseudoelectrons" : 3000, # Number of pseudoelectrons
+    "total_steps"            : 1000, # Total number of time steps
+}
+
+output = block_until_ready(simulation(input_parameters, **solver_parameters))
+
+print(f"Dominant FFT frequency (f): {output['dominant_frequency']} Hz")
+print(f"Plasma frequency (w_p):     {output['plasma_frequency']} Hz")
+print(f"Error: {jnp.abs(output['dominant_frequency'] - output['plasma_frequency']) / output['plasma_frequency'] * 100:.2f}%")
+
+plot(output)

jaxincell/simulation.py

@@ -42,17 +42,17 @@ def initialize_simulation_parameters(user_parameters={}):
     default_parameters = {
         # Basic simulation settings
         "length": 1e-2,                           # Dimensions of the simulation box
-        "amplitude_perturbation_x": 1e-7,          # Amplitude of sinusoidal (sin) perturbation in x
+        "amplitude_perturbation_x": 5e-4,          # Amplitude of sinusoidal (sin) perturbation in x
         "wavenumber_electrons": 8,    # Wavenumber of sinusoidal electron density perturbation in x (factor of 2pi/length)
         "wavenumber_ions": 0,    # Wavenumber of sinusoidal ion density perturbation in x (factor of 2pi/length)
         "grid_points_per_Debye_length": 2,        # dx over Debye length
         "vth_electrons_over_c": 0.05,             # Thermal velocity of electrons over speed of light
         "ion_temperature_over_electron_temperature": 0.01, # Temperature ratio of ions to electrons
         "timestep_over_spatialstep_times_c": 1.0, # dt * speed_of_light / dx
         "seed": 1701,                             # Random seed for reproducibility
-        "electron_drift_speed": 1e8,                # Drift speed of electrons
+        "electron_drift_speed": 0,                # Drift speed of electrons
         "ion_drift_speed":      0,                # Drift speed of ions
-        "velocity_plus_minus_electrons": True,   # create two groups of electrons moving in opposite directions
+        "velocity_plus_minus_electrons": False,   # create two groups of electrons moving in opposite directions
         "velocity_plus_minus_ions": False,        # create two groups of electrons moving in opposite directions
         "print_info": True,                       # Print information about the simulation