Series

When doing simulations, the most common data pattern is a series of some kind. Here, we describe the concept assuming a Timeseries, $i.e.$ we dump data for a series of time steps in our simulation.

For this purpose, bamboost includes a concept named Series. Series are tightly coupled to meshes (if there are any). You can have as many series as you need. Each series will be contained within an assigned group in the HDF file.

As there is a common usecase of only needing a single series, bamboost defines a default series – the data group at the root level of the file.

Access or create a series

The default series of a simulation is always available.

sim.data

my_simulation

data series: /data

size: 0

bamboost 0.10.0.post5+g375e0c8

Attributes
Attribute	Value
.series	True

Globals
Name	shape

Fields
Name

If you need another series, you can require it

my_series = sim.require_series("my_series")
my_series

my_simulation

data series: /my_series

size: 0

bamboost 0.10.0.post5+g375e0c8

Attributes
Attribute	Value
.series	True

Globals
Name	shape

Fields
Name

Dumping data

To dump data into a series, first create a new (time)step. Then, append data to that step.

step = sim.data.require_step()

# require_step takes two optional arguments
step = sim.data.require_step(
    value=0.32,  # A (time) value for this step
    step=10,  # Explicitly reference a step
)

The returned StepWriter can then be used to add field or global data.

phi = np.random.rand(10, 10)

step.add_field("phi", phi)
step.add_scalar("energy", 20)

A full minimal example

Let’s assume we loop through timesteps, and at each step we want to dump the values of phi.

coll = Collection(uid="315628DE80")
sim = coll.create_simulation('my_simulation', override=True)  # override replaces a previous simulation with the same name

for i, t in enumerate(np.linspace(0, 1, 10)):
    # ... some computation
    step = sim.data.require_step(t)
    step.add_field('phi', np.random.rand(10, 10))
    step.add_scalar('energy', i**2)

See below for what has been created.

Reading the series

Once the simulation has concluded (or also fine while it is still running), we want an easy interface to read the data in the series. Let’s have a look on a few things.

General information

When we display the series, we see that it contains 10 steps, one field named phi, and a global dataset named energy.

sim.data

my_simulation

data series: /data

size: 10

bamboost 0.10.0.post5+g375e0c8

Attributes
Attribute	Value
.series	True

Globals
Name	shape
energy	(10,)

Fields
Name
phi

series.values returns an array of the values of all steps.

sim.data.values

array([0.        , 0.11111111, 0.22222222, 0.33333333, 0.44444444,
       0.55555556, 0.66666667, 0.77777778, 0.88888889, 1.        ])

See Series for further methods and attributes.

Global data

Display all global datasets in a dataframe with

sim.data.globals.df

	values	energy
0	0.000000	0.0
1	0.111111	1.0
2	0.222222	4.0
3	0.333333	9.0
4	0.444444	16.0
5	0.555556	25.0
6	0.666667	36.0
7	0.777778	49.0
8	0.888889	64.0
9	1.000000	81.0

Access a dataset using square brackets. Remember that the returned dataset does not immediately read the underlying data. So, in order to read it, slice it.

sim.data.globals['energy'][5:]

array([25., 36., 49., 64., 81.])

Field data

To access a specific field, use brackets.

phi = sim.data['phi']

To read the data, you can slice the field as you would expect it. The first dimension is the step number. $E.g.$ to read phi for every third step, use

phi[::3]

# or simply
sim.data['phi'][::3]

array([[[0.22972376, 0.59121769, 0.34241323, 0.87920845, 0.20169786,
         0.42283448, 0.31904754, 0.37792043, 0.06573254, 0.74323568],
        [0.22613639, 0.36939724, 0.77721377, 0.32423274, 0.98299062,
         0.87894525, 0.67998256, 0.11497909, 0.35675659, 0.10119612],
        [0.5244344 , 0.67173253, 0.40127652, 0.05285841, 0.96885748,
         0.55907288, 0.41484024, 0.27195319, 0.17604447, 0.58249797],
        [0.70336289, 0.55095504, 0.11918392, 0.80372198, 0.46908318,
         0.0557014 , 0.30078561, 0.0622876 , 0.5353355 , 0.25987143],
        [0.46458907, 0.34717113, 0.61937174, 0.40430867, 0.32588182,
         0.71785855, 0.70380271, 0.92402882, 0.24021129, 0.35581784],
        [0.2738154 , 0.78734681, 0.02192953, 0.10966192, 0.51940019,
         0.0501316 , 0.90205941, 0.22029401, 0.78420227, 0.28321883],
        [0.82399849, 0.47275911, 0.65634107, 0.10170168, 0.17163927,
         0.75025649, 0.04696192, 0.19478177, 0.89853331, 0.27571602],
        [0.98149238, 0.02021866, 0.12270686, 0.9122688 , 0.47278096,
         0.86490591, 0.29568577, 0.1960819 , 0.47551028, 0.73720247],
        [0.55487185, 0.60947507, 0.70392691, 0.24806152, 0.47074822,
         0.40582537, 0.44787547, 0.70579674, 0.74879688, 0.39448932],
        [0.43416922, 0.25938681, 0.87506334, 0.22710746, 0.32826175,
         0.12266782, 0.69557176, 0.00848019, 0.47082825, 0.94050387]],

       [[0.06908975, 0.30403962, 0.3497386 , 0.01211304, 0.24751498,
         0.94724174, 0.34834979, 0.33370722, 0.64939961, 0.40371255],
        [0.86640301, 0.55662619, 0.44082237, 0.48344877, 0.34723397,
         0.97954267, 0.89906515, 0.73776798, 0.75767611, 0.27703857],
        [0.94991464, 0.24074522, 0.56762308, 0.09394616, 0.77171961,
         0.65113563, 0.00928298, 0.19209518, 0.96225063, 0.53202861],
        [0.3359746 , 0.71438038, 0.86398253, 0.50464464, 0.19859891,
         0.30946491, 0.58226726, 0.42112836, 0.44985978, 0.82533076],
        [0.89684672, 0.19105725, 0.64295839, 0.58053184, 0.86882809,
         0.15942135, 0.33031718, 0.84532873, 0.0447203 , 0.34001934],
        [0.32390666, 0.47225607, 0.50680508, 0.06196443, 0.70081193,
         0.98606629, 0.89135012, 0.03127313, 0.17366769, 0.57924177],
        [0.03339118, 0.68631117, 0.35608898, 0.96053037, 0.29146578,
         0.81457702, 0.38638083, 0.77058869, 0.37800789, 0.85602476],
        [0.6220059 , 0.2167063 , 0.01100086, 0.50648784, 0.76826199,
         0.59833316, 0.56664618, 0.9698637 , 0.13051863, 0.0358194 ],
        [0.38456961, 0.3352686 , 0.5130126 , 0.22346685, 0.74844858,
         0.31741059, 0.7373741 , 0.59204519, 0.87895551, 0.57859969],
        [0.66655498, 0.49009891, 0.35436681, 0.50628915, 0.64919937,
         0.51408282, 0.53079404, 0.39985986, 0.00578283, 0.75427338]],

       [[0.12248994, 0.48401019, 0.38022726, 0.01062809, 0.19306834,
         0.21106113, 0.02626697, 0.06846585, 0.23524533, 0.14473894],
        [0.41587383, 0.35309419, 0.68133866, 0.45700158, 0.3852331 ,
         0.0663709 , 0.19397126, 0.56151193, 0.14183003, 0.00836742],
        [0.30579971, 0.51109516, 0.7737784 , 0.29745483, 0.22464673,
         0.31813341, 0.94162294, 0.58841309, 0.44964954, 0.84946552],
        [0.7318165 , 0.40594997, 0.84698848, 0.61996173, 0.7453022 ,
         0.07260152, 0.04026718, 0.01505783, 0.30485021, 0.64688596],
        [0.3930627 , 0.50679558, 0.94506639, 0.83618065, 0.8670115 ,
         0.52255363, 0.56709259, 0.93183508, 0.96539374, 0.25298457],
        [0.80966006, 0.35236753, 0.49626723, 0.98344954, 0.36854381,
         0.38288279, 0.59235565, 0.71187161, 0.38461636, 0.37543615],
        [0.21712261, 0.11847151, 0.80381877, 0.26160576, 0.99737862,
         0.1919292 , 0.37098681, 0.87363309, 0.87276284, 0.2226804 ],
        [0.29441522, 0.68559546, 0.48774501, 0.49612686, 0.8314558 ,
         0.73840365, 0.92257681, 0.84885645, 0.84207833, 0.07662627],
        [0.8265415 , 0.70085617, 0.28291292, 0.93707892, 0.36527737,
         0.02766411, 0.95072323, 0.00938826, 0.23388691, 0.39445014],
        [0.13578298, 0.51902523, 0.63217806, 0.24320404, 0.40985978,
         0.18266547, 0.60874145, 0.71855758, 0.30766738, 0.93067403]],

       [[0.48166316, 0.80329028, 0.90766255, 0.27781866, 0.57774375,
         0.18041407, 0.36448901, 0.07489767, 0.91680992, 0.42555196],
        [0.46879402, 0.20753947, 0.54332317, 0.73976882, 0.39904637,
         0.27624332, 0.34106765, 0.59789333, 0.27542402, 0.42610869],
        [0.12911726, 0.51238161, 0.58676447, 0.73467707, 0.48065506,
         0.07700829, 0.24770977, 0.60308575, 0.71585998, 0.98541258],
        [0.73153622, 0.67362068, 0.49458627, 0.22600556, 0.11146864,
         0.75503442, 0.75092039, 0.92545064, 0.60123781, 0.93448545],
        [0.85325805, 0.48834088, 0.97241776, 0.06906219, 0.44779753,
         0.85906313, 0.26376529, 0.65076741, 0.3697077 , 0.67342824],
        [0.858104  , 0.13055605, 0.33686318, 0.1038157 , 0.00844819,
         0.52327834, 0.51293218, 0.02408661, 0.69441531, 0.80500101],
        [0.35049662, 0.19370375, 0.40922642, 0.931082  , 0.72830106,
         0.58474099, 0.77983516, 0.9912671 , 0.16351739, 0.45469729],
        [0.4581268 , 0.8259581 , 0.03861959, 0.84272159, 0.18831259,
         0.95428512, 0.72770717, 0.6513915 , 0.35368036, 0.70960893],
        [0.88812454, 0.55657729, 0.87575348, 0.73245873, 0.75379508,
         0.32287047, 0.54894024, 0.70766167, 0.38952601, 0.62901631],
        [0.18863729, 0.6750947 , 0.07609694, 0.77175285, 0.36959539,
         0.0242885 , 0.92154922, 0.33721619, 0.05979809, 0.0110633 ]]])

Series

Access or create a series

Dumping data

A full minimal example

Reading the series

General information

Global data

Field data

On this page