leniax.helpers package

Leniax helper functions

Those functions are provided to ease the use of this library. See them as template gluing core functions together to achieve common usages.

leniax.helpers.init(config, use_init_cells=True, fft=True)[source]

Construct the initial state and metadata to run a simulation.

Parameters

  • config (Dict) – Leniax confguration

  • use_init_cells (bool) – Set to True to use the init_cells configuration property.

  • fft (bool) – Set to True to use FFT optimization

Returns

A 3-tuple representing the initial state, Kernel and mapping data

Return type

Tuple[jax._src.numpy.ndarray.ndarray, jax._src.numpy.ndarray.ndarray, leniax.kernels.KernelMapping]

leniax.helpers.create_init_cells(world_size, nb_channels, other_cells=[], offsets=[])[source]

Construct the initial state

Parameters

  • world_size (List[int]) – World size

  • nb_channels (int) – Number of world channels

  • other_cells (Union[jax._src.numpy.ndarray.ndarray, List[jax._src.numpy.ndarray.ndarray]]) – Other initial states to merge

  • offsets (List[List[int]]) – Offsets used to merge other initial states

Returns

The initial state

Return type

jax._src.numpy.ndarray.ndarray

leniax.helpers.init_and_run(rng_key, config, use_init_cells=True, with_jit=True, fft=True, stat_trunc=False)[source]

Initialize and simulate a Lenia configuration

To simulate a configuration with multiple initializations you must set: - with_jit=True so the function use the scan implementaton. - stat_trunc=False multiple initializations means different simulation length measured by the statistics.

Parameters

  • rng_key (jax._src.prng.PRNGKeyArray) – JAX PRNG key.

  • config (Dict) – Lenia configuration

  • use_init_cells (bool) – Set to True to use the init_cells configuration property.

  • with_jit (bool) – Set to True to use the jitted scan implementation

  • fft (bool) – Set to True to use FFT optimization

  • stat_trunc (bool) – Set to True to truncate run based on its statistics

Returns

A tuple of [nb_iter, nb_init, nb_channels, world_dims…] shaped cells, fields, potentials and statistics of the simulation.

Return type

Tuple[jax._src.numpy.ndarray.ndarray, jax._src.numpy.ndarray.ndarray, jax._src.numpy.ndarray.ndarray, Dict]

leniax.helpers.search_for_mutation(rng_key, config, nb_scale_for_stability=1, use_init_cells=True, fft=True, mutation_rate=1e-05)[source]

Search for a stable mutation

Parameters

  • rng_key (jax._src.prng.PRNGKeyArray) – JAX PRNG key.

  • config (Dict) – Lenia configuration.

  • use_init_cells (bool) – Set to True to use the init_cells configuration property.

  • fft (bool) – Set to True to use FFT optimization.

  • nb_scale_for_stability (int) – Number of time the configuration will be scaled and tested.

  • mutation_rate (float) – Mutation rate.

Returns

A 2-tuple of a dictionnary with the best run data and the number of runs made to find it

Return type

Tuple[Dict, int]

leniax.helpers.search_for_init(rng_key, config, fft=True)[source]

Search for a stable initial state

Parameters

  • rng_key (jax._src.prng.PRNGKeyArray) – JAX PRNG key.

  • config (Dict) – Lenia configuration.

  • fft (bool) – Set to True to use FFT optimization.

Returns

A 2-tuple of a dictionnary with the best run data and the number of runs made to find it

Return type

Tuple[Dict, int]

leniax.helpers.build_update_fn(kernel_shape, mapping, get_state_fn_slug='v1', average_weight=True, fft=True)[source]

Construct an Leniax update function

An update function allows one to update a simulation state.

Parameters

  • kernel_shape (Tuple[int, ...]) – Kernel shape.

  • mapping (leniax.kernels.KernelMapping) – Mapping data.

  • get_state_fn_slug (str) – Which version of Lenia should be run

  • fft (bool) – Set to True to use FFT optimization

  • average_weight (bool) –

Returns

A Leniax update function

Return type

Callable

leniax.helpers.build_get_potential_fn(kernel_shape, true_channels=None, fft=True, channel_first=True)[source]

Construct an Leniax potential function

A potential function allows one to compute the potential from a Lenia state.

Parameters

  • kernel_shape (Tuple[int, ...]) – Kernel shape.

  • true_channels (Optional[List[bool]]) – Boolean array indicating the true potential channels

  • fft (bool) – Set to True to use FFT optimization

  • channel_first (bool) –

Returns

A Leniax potential function

Return type

Callable

leniax.helpers.build_get_field_fn(cin_gfs, average=True)[source]

Construct an Leniax field function

A field function allows one to compute the field from a Lenia potential.

Parameters

  • cin_gfs (List[List[str]]) – List of growth functions per channel.

  • average (bool) – Set to True to average instead of summing input channels

Returns

A Leniax field function

Return type

Callable

leniax.helpers.dump_assets(save_dir, config, all_cells, stats_dict, colormaps=[], transparent_bg=False)[source]

Dump a set of interesting assets.

Those assets include:

  • Simulation statistics (plots and data)

  • Kernels and growth functions plots

  • Last frame

  • Video and Gif of the simulation

Parameters

  • save_dir (str) – directory used to save assets.

  • config (Dict) – Leniax configuration.

  • all_cells (jax._src.numpy.ndarray.ndarray) – Simulation data of shape [nb_iter, C, world_dims...].

  • stats_dict (Dict) – Leniax statistics dictionnary.

  • colormaps (List) – A List of matplotlib compatible colormap.

  • transparent_bg (bool) – Set to True to make the background transparent.

leniax.helpers.dump_last_frame(save_dir, all_cells, center_and_crop=True, colormap=None)[source]

Dump the last frame of the simulation

The dumped last frame is called last_frame.png.

Parameters

  • save_dir (str) – directory used to save assets.

  • all_cells (jax._src.numpy.ndarray.ndarray) – Simulation data of shape [nb_iter, C, world_dims...].

  • center_and_crop (bool) – Set to True to center the stable pattern and crop the margin.

  • colormap – A matplotlib compatible colormap.

leniax.helpers.dump_frame(save_dir, filename, cells, center_and_crop=True, colormap=None)[source]

Dump a Lenia state as a image

Parameters

  • save_dir (str) – directory used to save assets.

  • filename (str) – File name.

  • cells (jax._src.numpy.ndarray.ndarray) – A Lenia state of shape [C, world_dims...].

  • center_and_crop (bool) – Set to True to center the stable pattern and crop the margin.

  • colormap – A matplotlib compatible colormap.

leniax.helpers.dump_viz_data(save_dir, config, stats_dict)[source]

Dump vizualization data as JSON

Parameters

  • save_dir (str) – directory used to save assets.

  • config (Dict) – Leniax configuration.

  • stats_dict (Dict) – Leniax statistics dictionnary.

leniax.helpers.plot_kernels(save_dir, config)[source]

Plots kernels and growth functions

Parameters

  • save_dir (str) – directory used to save assets.

  • config (Dict) – Leniax configuration.