CubeFlow 0.1.5

Border handling

As each border cell should have at most one adjacent inner cell in CubeFlow, its following state is determined by the mention adjacent cell alone. Depending of the type of the border, the calculation is more or less complex. In our example we have the following equations that satisfy our conditions:

Inner cell handling

The first part of our handling of the inner cell takes care of calculating the heat flow of each cell by applying the Laplace operator regarding temperature to it while taking the thermal diffusivity into account. We will call this step the preparation step in CubeFlow. In the second part of the simulation we do the actual simulation, which means adding the calculated flow of each cell to its temperature. This step is called simulation step within CubeFlow.

We will start by generating a data type that takes care of the simulation.

from cubeflow.simulator import BaseSimulator, add_derivations, border_handler

@add_derivations
class HeatSimulator(BaseSimulator[HeatCell]):
    Type = HeatCell

The add_derivations decorator adds methods for calculating the first and second derivation as well as the gradient and laplace operator of each HeatCell member variable that is of type Scalar. We will now define a border handler method for handling all borders of type 1, which means our mentioned now-flow borders.

@border_handler(1)
def no_flow_border(self, cells: Dict[Sequence[int], HeatCell]) -> HeatCell:
    cell = cells[(0, 0)]
    adjacent = self._get_adjacent_inner(cells)
if adjacent:
    # cell is not a corner
    cell.temperature = self._get_only_cell(adjacent)[1].temperature
    return cell
else:
    return self._handle_corner(cells)

The Dict[Sequence[int], HeatCell] type represents a mapping window around the current cell which maps vectors to neighbour cells. cells[(0, 0)] represents the inner cell, while cell[(1, 0)] represents the cell right to cell. If such a cell does not exist, which is only possible for border cells, the corresponding value will be None. Almost all functions dealing with cell will take Dict[Sequence[int], HeatCell] as argument. _get_adjacent_inner returns all neighbour cells which are well defined (not None). If the second argument to get_adjacent_inner is omitted or True, only cells along the direction of the grid axis are returned. _get_only_cell is a helper function that returns the coordinates and cell of the only cell present in its argument. The border_handler(1) call tells CubeFlow that this method takes care of every border of type 1 and will be called if a border of type 1 is encountered during the handling of the border. We may define as much border handlers as we wish for every positive integer, type 0 is reserved for inner cells, though. handle_corner is used for corner cells that normally take no part of the simulation at all. For this reason, their values except their cell type are set to any of the surrounding border cells, although ignoring them is fine, too. The next function takes care of the preparation step in which we will calculate the heat flow of every cell. We will do this by overwriting the _prepare method within our simulator class.

def _prepare(self, cells: Dict[Sequence[int], HeatCell]) -> HeatCell:
    cell = cells[(0, 0)]
    cell.flow = -cell.diffusivity * self.laplace_temperature(cells)
    return cell

The _laplace_temperature method has been added to our simulator class by the application of the add_derivations decorator. A similar method _laplace_diffusivity exists although it is not used in our little example. _laplace_temperature as well as all other methods regarding differentiation take additional parameters that modify the way the summands of the denominator in the derivation equations are weighted. The default weights for the _laplace_diffusivity methods represent the center differentiation method we chose early on. The final method we will look at takes care of the actual simulation, the calculation of the cell’s temperature.

def _simulate(self, cells: Dict[Sequence[int], HeatCell]) -> HeatCell:
    cell = cells[(0, 0)]
    cell.temperature += self.dt*cell.flow
    return cell

The dt member is the current time-step of our simulation, which is 0.1 time units per default and constant throughout our simulation. A t member also exists, which represents the current time of our simulation. The last thing we have to do is defining a small entry function for our program that loads a grid from file and performs the actual simulation.

if __name__ == '__main__':
    from sys import argv
    from cubeflow.report.csv import CSVReport
    from cubeflow.predicates.counter import Counter
    simulator = HeatSimulator(CubeGrid.from_file(argv[1], HeatCell), [CSVReport('heat')])
    simulator.simulate_while(Counter(1000))

This will load a grid from command line and perform 1000 simulation steps, where each of them will be output to file heat.csv.i where i ist the current step of the simulation. simulate_while takes a predicate that may evaluate the grid and decide if another simulation step should take place. Counter of course does not do much evaluation. The second argument of the HeatSimulator constructor takes a list of Report instances that will report every simulation step. CSVReport for instance saves every step to a csv file for later analysis (e.g. by the usage of ParaView). Now we run out simulator with the sample grid provided in the Appendix of this document:

python3 heat.py sample_heat_grid.json

Stability conditions

Time-Step calculation