osiris-utils 1.1.10a0__py3-none-any.whl → 1.2.1__py3-none-any.whl

docs/source/examples/example_FFT.md

@@ -0,0 +1,152 @@
+# FFT Analysis
+
+```python
+%load_ext autoreload
+%autoreload 2
+```
+
+
+```python
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.colors import LogNorm
+
+import osiris_utils as ou
+```
+
+## Initialize an object of the Simulation class
+- The Simulation class takes the `simulation_folder`, this is, the file where the input deck is located.
+- It can also take the `species` when we want to use quantities related to a specific species, such as velocities, charge, temperature, etc.
+
+
+```python
+# In this case, since we only want to study the electric field, no species is needed
+sim = ou.Simulation(input_deck_path="example_data/thermal.1d")
+```
+
+The `Simulation` object acts as a container for the simulation diagnostics, that can be easily accessed from the `Simulation` object using a dictionary-like syntax
+In this case, to access the component of the electric field in the z direction, we can use `sim['e3']`. This is a `Diagnostic` object, that loads the data as requested using a data generator, using indices to choose the time step - a lazy loading approach.
+
+
+```python
+# This is a Diagnostic object
+sim["e3"]
+
+# This is also a Diagnostic object but initialized directly and not through the Simulation object
+e3 = ou.Diagnostic(simulation_folder="example_data")
+e3.get_quantity("e3")
+
+print("sim['e3'] class:", sim["e3"].__class__)
+print("e3 class:", e3.__class__)
+```
+
+The data of the diagnostic at a given index can be accessed by indexing the iteration number, e.g. `sim['e3'][0]` will return the electric field in the z direction at the first time step. The data is not stored in memory, but loaded from the file when requested, using a data generator (lazy loading). For example, to plot the electric field in the z direction at the 100th time step, we can use `sim['e3'][100]`, and use the other attributes of the `Diagnostic` object to get the time step, the grid, labels, etc.
+
+
+```python
+plt.figure(figsize=(8, 3))
+plt.plot(sim["e3"].x, sim["e3"][100])
+plt.xlabel(sim["e3"].axis[0]["plot_label"])
+plt.title(rf"${sim['e3'].label}$ @ $t = {sim['e3'].time(100)[0]:.2f}$ $[{sim['e3'].tunits}]$")
+plt.show()
+```
+
+If we want to load the data of the diagnostic at all time steps, we can use the `load_all()` method of the `Diagnostic` object, e.g. `sim['e3'].load_all()` will load the electric field in the z direction at all time steps and store it in memory. This is useful when we want to do the FFT of the data in the time domain, for example. Using the method `unload()` we can clear the data from memory.
+
+
+```python
+sim["e3"].load_all()
+print(sim["e3"].data.shape)
+
+e3.load_all()
+print(e3.data.shape)
+
+np.isclose(sim["e3"].data, e3.data).all()
+
+sim["e3"].unload()
+e3.unload()
+```
+
+Now we are going to use a post process on the simulation data and on the diagnostic. We can think of a `PostProcess` as an operator over the `Diagnostic`'s of the `Simulation`. We define it on the simulation, and to access a post-processed quantity of the simulation, we use the same dictionary-like syntax, e.g. `sim_fft["e3]` to access the FFT of the electric field in the z direction. 
+
+The data is loaded in memory when requested, using a data generator, and can be accessed using the same indexing syntax, e.g. `sim_fft["e3"][0]` to access the FFT of the electric field in the z direction at the first time step. The data can be loaded using the `load_all()` method, and cleared from memory using the `unload()` method.
+
+The post-processing classes inherit from the `PostProcess` class and the `Diagnostic` class, and can be used as a `Diagnostic` object, with the same attributes and methods, ensuring that operations between diagnostics and post-processes are consistent.
+
+Each diagnostic has a version to be applied to `Simulation` objects and another to be applied to `Diagnostic` objects. The first has the name `<name of post-process>`_Simulation, and the second has the name `<name of post-process>_Diagnostic`. For example, the post-process routines for Fast Fourier Transforms are called `FastFourierTransform_Diagnostic` and `FFT_Diagnostic`.
+
+
+```python
+sim_fft = ou.FFT_Simulation(sim, (0, 1))  # "operator" FFT applied to Simulation object, axis 0 and 1
+
+e3_fft = ou.FFT_Diagnostic(e3, (0, 1))  # "operator" FFT applied to Diagnostic object, axis 0 and 1
+```
+
+
+```python
+sim_fft["e3"][100]  # this will only return the kx axis, since we are only requesting the 100th time step of the FFT of e3
+
+e3_fft[100]  # this will return the kx and ky axis, since we are only requesting the 100th time step of the FFT of e3
+
+np.isclose(sim_fft["e3"][100], e3_fft[100]).all()  # They are the same!
+```
+
+Since my goal is to plot the dispersion relation, I will need to use `.load_all()` to load all the time steps, and have access to the data in the frequency domain.
+
+
+```python
+sim_fft["e3"].load_all()
+e3_fft.load_all()
+
+np.isclose(sim_fft["e3"].data, e3_fft.data).all()  # They are the same!
+```
+
+We can now plot!
+
+
+```python
+plt.imshow(
+    sim_fft["e3"].data,
+    origin='lower',
+    norm=LogNorm(vmin=1e-7, vmax=0.01),
+    extent=(-sim_fft["e3"].kmax, sim_fft["e3"].kmax, -sim_fft["e3"].omega_max, sim_fft["e3"].omega_max),
+    aspect='auto',
+    cmap='gray',
+)
+
+# Plotting the dispersion relation
+k = np.linspace(-e3_fft.kmax, e3_fft.kmax, num=512)
+w = np.sqrt(1 + k**2)
+plt.plot(k, w, label=r"$\omega^2 = \omega_p^2 + k^2c^2$", color='r', ls='-.')
+plt.xlim(0, e3_fft.kmax)
+plt.ylim(0, e3_fft.omega_max)
+
+plt.xlabel(r"$k$ $[\omega_e/c]$")
+plt.ylabel(r"$\omega$ $[\omega_e]$")
+plt.legend()
+plt.show()
+```
+
+
+```python
+plt.imshow(
+    e3_fft.data,
+    origin='lower',
+    norm=LogNorm(vmin=1e-7, vmax=0.01),
+    extent=(-e3_fft.kmax, e3_fft.kmax, -e3_fft.omega_max, e3_fft.omega_max),
+    aspect='auto',
+    cmap='gray',
+)
+
+# Plotting the dispersion relation
+k = np.linspace(-e3_fft.kmax, e3_fft.kmax, num=512)
+w = np.sqrt(1 + k**2)
+plt.plot(k, w, label=r"$\omega^2 = \omega_p^2 + k^2c^2$", color='r', ls='-.')
+plt.xlim(0, e3_fft.kmax)
+plt.ylim(0, e3_fft.omega_max)
+
+plt.xlabel(r"$k$ $[\omega_e/c]$")
+plt.ylabel(r"$\omega$ $[\omega_e]$")
+plt.legend()
+plt.show()
+```

docs/source/examples/example_InputDeck.md

@@ -0,0 +1,149 @@
+```python
+%load_ext autoreload
+%autoreload 2
+```
+
+
+```python
+import osiris_utils as ou
+```
+
+# Interface with Osiris Input Decks
+
+For many tasks, it might be useful to read simulation parameters directly from the input deck, or algorithmically generate new Osiris input decks (e.g.to run large parameter scans). 
+
+The class `InputDeckIO` allows you to easily perform theses tasks.
+You need to provide it two inputs:
+- `filename`: path to OSIRIS input deck
+- `verbose`: if `True` will print auxiliary information when parsing the input deck
+
+
+## Reading an input deck
+
+
+```python
+deck = ou.InputDeckIO('example_data/thermal.1d', verbose=True)
+```
+
+Not only does the object load the different module parameters, but also automatically determines other useful information for downstream tasks.
+
+Examples include:
+- `dim`: number of dimensions
+- `n_species`: number of species
+- `species`: dictionary with `Species` objects with relevant information (e.g. charge, rqm, etc.)
+
+
+```python
+print("Simulation Dimensions:", deck.dim)
+print("Number of species:", deck.n_species)
+print("Species:", deck.species)
+```
+
+`InputDeckIO` stores the state of the input deck in the parameter `self._sections`.
+
+You should not access this value directly, instead you can use for example its getter function `self.sections` which returns a deepcopy.
+
+The returned value corresponds to a list of pairs [section_name, dictionary] where the section_name matches the Osiris input deck section name and he dictionary contains the list of (key, values) for the parameters of the section.
+
+
+```python
+print(deck.sections[0])
+print(deck.sections[1])
+print('Number of sections:', len(deck.sections))
+```
+
+Another option is to query the object as if it is an iterator, where the key is the section name.
+
+This will return a list of dictionaries, since multiple sections can have the same name (e.g. you might have multiple species).
+
+Once again, a deepcopy is being returned so editing the returned values of the dictionaries will not change the original `InputDeckIO` object.
+
+
+```python
+print(deck['simulation'])
+print(deck['node_conf'])
+```
+
+Finally you can also ask for a specific parameter directly with `get_param()`
+
+
+```python
+# this one returns a list since there can be multiple sections with the same name
+print(deck.get_param(section='simulation', param='random_seed')[0])
+# which is equivalent to doing this
+print(deck["simulation"][0]['random_seed'])
+```
+
+## Editing an input deck
+
+To safely edit the value of a parameter in an input deck you can use `set_parameter()`.
+
+**Note**: This re-writes the object values!
+
+
+
+```python
+# edit a parameter already exists
+print('Before', deck['simulation'])
+deck.set_param('simulation', 'random_seed', value=42)
+print('After', deck['simulation'])
+```
+
+
+```python
+# add a parameter
+print("Before", deck["simulation"])
+deck.set_param("simulation", "new_parameter", value='HI', unexistent_ok=True)
+print("After", deck["simulation"])
+```
+
+And you can also delete the parameter using `delete_param()`.
+
+
+```python
+# delete a parameter
+print("Before", deck["simulation"])
+deck.delete_param("simulation", "new_parameter")
+print("After", deck["simulation"])
+```
+
+Something slighlty more powerful, is the ability to edit a string in the whole input deck (use with care!)
+
+This can be done for example to automatically change multiple parameter values that are shared / depend on an external quantity.
+
+We can do this using the function `set_tag()`.
+
+**Note**: This only works on the parameter values, not section names / parameter names.
+
+
+```python
+# this a dummy example where we change some values to #tag#
+print("Before", deck["simulation"])
+deck.set_tag(
+    '42', # this has to be a string
+    '#tag#',
+)
+deck.set_tag(
+    '23:50:00', # this has to be a string
+    '#tag#',
+)
+print("After 1", deck["simulation"])
+
+# and here we change both values at once
+deck.set_tag('#tag#', "BOTH CHANGED")
+print("After 2", deck["simulation"])
+# There is a reason why wall_clock_limit has an extra "" done worry
+# it is because it should be a string, while random_seed is an int!
+# InputDeckIO handles these things for you
+```
+
+## Writing changes to file
+
+Once you did your changes, you can simply generate a new input deck with `print_to_file()`.
+
+
+```python
+deck.print_to_file("edited-deck.1d")
+with open("edited-deck.1d") as f:
+    print(f.read())
+```

docs/source/examples/example_Simulation_Diagnostic.md

@@ -0,0 +1,213 @@
+```python
+%load_ext autoreload
+%autoreload 2
+```
+
+
+```python
+import matplotlib.pyplot as plt
+import numpy as np
+
+import osiris_utils as ou
+```
+
+# Example notebook for the `Simulation` and `Diagnostic` classes
+
+## `Simulation`
+The `Simulation` class takes in:
+- `simulation_folder`: the folder where the input deck is located
+- `species`: the species in case we are interested in diagnostics that are species-specific (such as vfl1, T11, etc.)
+
+Acts as a wrapper for the `Diagnostic` class, allowing for an easy access to diagnostics of the simulation using a **dictionary-like** syntax.
+
+## `Diagnostic`
+
+The `Diagnostic` class takes in:
+- `simulation_folder`: the folder where the input deck is located
+- `species`: the species in case we are interested in diagnostics that are species-specific (such as vfl1, T11, etc.)
+
+
+The `Diagnostic` class has the some relevant methods and properties that you should be aware of:
+- `get_quantity`: "loads" the quantity. Accessing the diagnostic through the `Simulations` using the dictionary-like syntax this will be called automatically.
+- once the quantity is loaded, you can access the data at a specific time through indexing (e.g. `diag['vfl1'][0]` for the first time step). This doesn't store the data in memory, only uses a data generator to access the data (lazy loading).
+- `load_all`: loads all the time steps of the quantity, storing it in memory
+- `unload`: unloads the data from memory
+- `time`: the time steps of the quantity at a specific index
+- Has operator overloading for the `+`, `-`, `*`, `/` operators, allowing for easy manipulation of the data, even when it is not loaded in memory and is accessed through indexing.
+
+
+```python
+# sim is a Simulation object
+sim = ou.Simulation(input_deck_path="example_data/thermal.1d")
+
+print("Simulation:")
+print(sim)
+print(sim.__dict__.keys())
+print(f"\n")
+
+# e3 is a Diagnostic object
+e3 = ou.Diagnostic(simulation_folder="example_data")
+# now we need to load the data
+e3.get_quantity("e3")  # it knows the path there since OSIRIS always saves the data in the same way
+
+print("Diagnostic: (e3)")
+print(e3)
+print(e3.__dict__.keys())
+```
+
+If the diagnostic that you want to access if related to a species, you need to access it by using the species name as the first key.
+
+
+```python
+# An electric field if not relatec to a species, so you can access it by doing:
+sim["e3"]
+
+# To access a species-related diagnostic, you can do:
+sim["electrons"]["vfl1"]
+
+# To see the available species of a simulation, you can do:
+sim.species
+```
+
+Notice that the `Diagnostic` class does not have `data` as the data is not saved in memory if `load_all` is not called. The data is accessed through the `__getitem__` method using indexing.
+
+To get a `Diagnostic` from a `Simulation`, you can access it through the dictionary-like syntax, where the key is the name of the diagnostic (e.g. `sim['vfl1']` is a `Diagnostic` with the `vfl1` quantity).
+
+
+```python
+sim["e3"]  # This is equivalent to e3
+
+print(sim["e3"])
+print(sim["e3"].__dict__.keys())
+```
+
+If we want to access the data of the diagnostic at a specific time, we can use the indexing syntax (e.g. `sim['vfl1'][0]` for the first time step, using a `Simulation`, or `e3[0]`, using the `Diagnostic` directly).
+
+
+```python
+print(sim["e3"][100].shape)  # nx
+print(e3[100].shape)  # nx
+
+print("Are they the same?", np.isclose(sim["e3"][100], e3[100]).all())
+```
+
+This is useful when we want to access a specific iteration of the diagnostic, without loading all the data in memory. 
+
+For a quick plot, we can even use the other attributes of the `Diagnostic` class, such as `time`, `x` for the axis, of `axis` for info about the axis.
+
+
+```python
+plt.figure(figsize=(12, 4))
+plt.subplot(121)
+plt.plot(sim["e3"].x, sim["e3"][100], label="Simulation", c="tab:orange")
+plt.title("Using Simulation")
+plt.xlabel(sim["e3"].axis[0]["plot_label"])
+plt.legend()
+
+plt.subplot(122)
+plt.plot(e3.x, e3[100], label="Diagnostic", c="tab:blue")
+plt.title("Using Diagnostic")
+plt.xlabel(e3.axis[0]["plot_label"])
+plt.legend()
+plt.show()
+```
+
+If we want to load all the data in memory, we can use the `load_all` method, which will load all the data in memory. This is useful to study how diagnostics vary in time, for example. 
+
+The data is stored in the `data` attribute of the `Diagnostic` class. 
+
+If we want to unload the data from memory, we can use the `unload` method.
+
+From now on, I'll only use `sim[diagnostic]` to show what can be done with `Diagnostic` objects, but remember that you can access the `Diagnostic` object directly if you want to use the `load_all`, `unload`, `time`, `x`, and `axis` attributes.
+
+
+```python
+sim["e3"].load_all()
+
+# now, the data is loaded in memory
+print(sim["e3"].data.shape)  # (n_steps, nx)
+
+sim["e3"].unload()
+```
+
+Since diagnostics have operator overloading, we can easily manipulate the data, even when it is not loaded in memory. For example, we can do `sim['vfl1'] + sim['e1']` to get the sum of the two diagnostics, or `sim['vfl1'] / sim['e1']` to get the division of the two diagnostics.
+
+When operations are done, a new `Diagnostic` is created, with the new data. This new `Diagnostic` can be accessed through the indexing syntax, and the data can be loaded in memory using the `load_all` method.
+
+
+```python
+sum_of_diag = sim["electrons"]["T11"] + sim["electrons"]["vfl1"]
+
+print(sum_of_diag)
+print(sum_of_diag.__dict__.keys())
+```
+
+We can use the method of the `Diagnostic` class as usual, for example, `load_all`, and `unload`:
+
+
+```python
+# we can load all the data at once
+sum_of_diag.load_all()
+print(sum_of_diag.data.shape)  # (n_steps, nx)
+sum_of_diag.unload()
+```
+
+And accessing a specific time step of the new `Diagnostic` is done through indexing, as usual.
+
+
+```python
+plt.figure(figsize=(12, 4))
+plt.subplot(121)
+plt.plot(sum_of_diag.x, sum_of_diag[100], label="T11 + vfl1", c="tab:orange")
+plt.title("Diagnostic from sum of two diagnostics")
+plt.xlabel(sum_of_diag.axis[0]["plot_label"])
+plt.legend()
+plt.show()
+```
+
+This is really useful when we want a quantity that OSIRIS doesn't provide. For example, when the pressure is adiabatic, we can calculate the pressure using the formula `P = n * T`, where `P` is the pressure, `n` is the density, and `T` is the temperature. We can calculate the pressure using the formula `P = n * T` using the `Diagnostic` class, and then use the pressure to calculate the adiabatic index `gamma = 5/3` using the formula `gamma = P / (n * T)`.
+
+
+```python
+nT = -1 * sim["electrons"]["T11"] * sim["electrons"]["charge"]  # -1 because we are dealing with electrons
+```
+
+
+```python
+plt.figure(figsize=(6, 4))
+plt.plot(nT.x, nT[100], label=r"$n_eT_{11}$", c="tab:green")
+plt.title(r"$n_eT_{11}$")
+plt.xlabel(nT.axis[0]["plot_label"])
+plt.legend()
+plt.show()
+```
+
+If the `load_all` method is called before the operations, the whole data will be stored in the new quantity.
+
+
+```python
+sim["electrons"]["vfl1"].load_all()
+sim["electrons"]["charge"].load_all()
+
+v_times_charge = sim["electrons"]["vfl1"] * sim["electrons"]["charge"]
+
+print(v_times_charge)
+print(v_times_charge.__dict__.keys())
+```
+
+The whole data is computed if stored in the diagnostics before the operations
+
+
+```python
+print(v_times_charge.data.shape)
+```
+
+And it can be unloaded from memory using the `unload` method.
+
+
+```python
+v_times_charge.unload()
+
+# print something that checks that data is none
+print("Is `v_times_charge.data` None?", v_times_charge._data is None)
+```

docs/source/examples/quick_start.md

@@ -0,0 +1,51 @@
+# Quick Start Guide
+
+```python
+%load_ext autoreload
+%autoreload 2
+```
+
+
+```python
+"""
+Quick demonstration of osiris_utils:
+• opens an OSIRIS simulation directory
+• plots Ez field at t = 2000
+Run with:  python examples/quick_start.py  <PATH_TO_RUN>
+"""
+```
+
+
+```python
+import sys
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+
+import osiris_utils as ou
+
+```
+
+
+```python
+sim_path = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("example_data/thermal.1d")
+sim = ou.Simulation(sim_path)
+```
+
+
+```python
+# grab Ez diagnostic
+ez = sim["e3"]
+```
+
+
+```python
+# plot Ez field at iteration 220
+plt.plot(ez.x, ez[220], label=f"${ez.label}$")
+plt.title(rf"${ez.label}$ at t = {ez.time(220)[0]} $[{ez.time(220)[1]}]$")
+plt.xlabel(ez.axis[0]["plot_label"])
+plt.ylabel(f"${ez.units}$")
+plt.legend()
+plt.tight_layout()
+plt.show()
+```

docs/source/examples.rst

@@ -0,0 +1,14 @@
+Examples
+========
+
+This section contains examples and tutorials on how to use ``osiris_utils``.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Tutorials:
+
+   examples/quick_start
+   examples/example_Simulation_Diagnostic
+   examples/example_InputDeck
+   examples/example_Derivatives
+   examples/example_FFT

docs/source/index.rst

@@ -5,6 +5,13 @@ OSIRIS Utils Documentation
 
 .. include:: ../../README.rst
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Examples:
+   :hidden:
+
+   examples
+
 .. toctree::
    :maxdepth: 2
    :caption: Simulation and Diagnostic API:
@@ -24,6 +31,7 @@ OSIRIS Utils Documentation
    :caption: Utilities API:
    :hidden:
    
+   api/decks
    api/utilities
 
 .. toctree::

examples/edited-deck.1d

@@ -55,7 +55,7 @@ diag_emf
 {
 	ndump_fac = 1,
 	ndump_fac_ene_int = 1,
-	reports = "e1", "e2", "e3",
+	reports = "e3",
 }
 
 particles