Metadata-Version: 2.4
Name: fvsparcs
Version: 0.1.0
Summary: A reader for the output files of the FV-SPARCS toolkit
Author-email: Christian Huettig <christian.huettig@dlr.de>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy


# This repo contains the FV-SPARCS reader module (compat with GAIAv3)

Howto use:
```py
from fvsparcs import *
```

## Usecases for the module

```py

# Check what cases are in current directory (change with os.chdir)
print(getCases())

# If you only have one run in the directory:
s = Simulation()

# For a specific case:
s = Simulation(caseid = 'bl2a')

# If the simulation is not in the current directory,
s = Simulation(caseid = 'bl2a', sim_dir = 'bl')

# Simulation will try to load the grid. The gridfile is taken from an output file. 
# It searches for that file in ., ../, ../grid, ../../grid and the directory from the full path. 
# If you have it somewhere else, provide that directory with:

s = Simulation(grid_dir = '/my/grid/path')

#ACCESS OUTPUT
#=============

# Get the last output:
o = s.getLast()

# Get at time:
o = s.getAtTime(0.5)

# Get at iteration:
o = s.getAtIter(2549)

# Output will load all fields and create all Field instances.

#ACCESS FIELD DATA
#=================

# Fields are named after their field ID (T,P,S,v,...)
# If output detects a vector (like v) it automatically splits it into magnitude: adds "mag"; radial component: adds "r"

# The raw array with the according positions (n = amount of cells):

pos = o.grid.coords    # [n, 3] array	
temperature = o.temperature.data # [n, 1] array
temperature = o.temperature.data.squeeze() # [n] array

# formatted data (only 2D BOX/CYL or 3D BOX)

temperature = o.temperature.formatted_data  # [n_x, n_y] array
imshow(temperature, origin="lower")

# vector magnitude:
vel_mag = o.velocitymag.data

# Cartesian component of vector
v_x = o.velocity.data[:,0]
v_y = o.velocity.data[:,1]

# Return data for a specific shell:
temperature_shell_5 = o.temperature.getShellData(5)

# Return a profile (radial averaged)
# profile has for each shell: [[radius, min, mean, max], ... nShells]
t_prof = o.temperature.getProfile()

# Get volume averaged mean of field
mean_t = o.temperature.getMean()

# Get RMS velocity
v_rms = o.velocitymag.getMean(order=2)

#ACCESS GEOMETRY
#===============

# access grid via Simulation or Output. s.grid == o.grid (reference)
s.grid.nShells
s.grid.nCells
s.grid.coords
s.grid.coordsSph
s.grid.volumes
s.grid.innerRadius
s.grid.outerRadius
s.grid.resolution # mean distance between cells
s.grid.shellOffset
s.grid.shellCoords
s.grid.shellCoordsSph
s.grid.shellRadius # or height if its a box

Or use s.grid.get_infos() directly to get a summary of the grid properties.

#GRAPHICAL OUTPUT
#================
# Other methods are directly meant for graphic processing.
# Check out the notebooks.

#TIME SERIES
#===========

stats = s.getStats()
# See timeseries notebook on how to use

#PARAMETER STUDIES
#=================
# In case a parameter study is present in the current path just use:
ps = ParameterStudy()

# A dict with all available combinations:
ps.cases

# The entries:
ps.entries

#ADD FIELD DATA TO OUTPUT
#========================
# In case you want to add a constructed field form post-processing to an output to visualize it with ParaView:
o.addScalar("L") # creates a new scalar field containing zeros, equiv. addVector("m")
o.L.data = o.temperature.data + 1
o.save()  # Overwrites original file!
o.save(filename="new_dir/" + o.filename) # ... to another file
# - Only manipulate .data, do not touch raw_data !
# - Remember convention: Uppercase == Scalar, Lowercase == Vector
# - To avoid ParaView conflicts you should add the new field to all outputs of a sim

```
## The Direct interface (not populated to v3 yet)
This interface is available via the GAIA module's `Direct()` class. It loads `libgaia.so` in the current directory and allows control in between time-steps. A few things to note here:
- MPI version(s) do not work yet. MUMPS or CUDA (w/OMP) works.
- When building GAIA, a `libgaia.so` is always created with the executable. This is what the Direct() class needs.
- Calling order is important here!
  - First call `init1()`, this will setup the `ini` instance.
  - Use any number of `iniLoad()` or `setParameter()` calls. 
  - Call `init2()`. This is Gaia's C++ `init()` call and will load / create Grids and prepare the Simulation. 
  - Now you can for the first time call `getState()`
  - Call `doTimestep()`, it returns the next delta time. Zero means MaxTime is reached.
- Look at the `gaia_test.py` within the C++ code for an example 
### `getState()` and God-Mode
Be careful about the contents of the returned dictionary, ***these are references to the Simulation's raw arrays, *not* copies***!
Means you can interact with the simulation in any way. You can also throw in some `setParameter()` calls. Careful, many mods do create a copy on init and never read them again.



