Chemotaxis Simulations CLI Tool

A command-line interface (CLI) tool to simulate chemotaxis processes based on a parabolic-elliptic PDE model.

Table of Contents

• About
• Installation
• Usage
• Features
• Documentation
• Contributing
• License
• Contact

About

This repository contains a program that simulates a chemotaxis process from a parabolic-elliptic system of partial differential equations. It is based on the research paper Global Existence and Asymptotic Behaviour of Classical Solutions of Chemotaxis Models with Signal-dependent Sensitivity and Logistic Source by Dr. Wenxian Shen, Dr. Le Chen, and their PhD student Ian Ruau. Here is a link to the research paper [link to paper]

Simulations for special sets of parameters are consistent with proven theoretical results. The advantage of this package is that it helps us get insights about behaviours outside of the sets of parameters considered in the research paper.

Installation

To get started with these simulations, you can install the package using pip:

pip install chemotaxis-sim

Features

• Run chemotaxis simulations with customizable parameters.
• Terminal plots of initial conditions via termplotlib.
• 3D static surface plots (PNG/JPEG) and optional MP4 animations.
• Progress bar and verbose logging.
• Easy CLI usage with help prompts.

Usage

Once the package is installed, the user can access the help prompt by simply running the following command

chemotaxis-sim --help

Here is an example of a simulation

chemotaxis-sim --chi 30 --meshsize 100 --time 5 --eigen_index 2 --epsilon 0.5 --generate_video yes

Saved data controls (optional):

chemotaxis-sim --save_data yes --save_max_frames 2000 --save_summary6 yes

Output naming controls (optional):

chemotaxis-sim --output_dir images/branch_capture --basename run_beta0_chi2185_epsP

YAML config files

For long parameter lists, you can load defaults from a YAML file via --config. CLI flags always override YAML values, and any missing parameter falls back to the CLI default.

Example:

chemotaxis-sim --config config.example.yaml
chemotaxis-sim --config config.example.yaml --chi 2.185 --meshsize 100

See config.example.yaml for a grouped template.

Paper II constants (Eq. (1.8) and Eq. (1.12))

The module paper2_constants.py computes the equilibrium and the discrete threshold (\chi_a^(u^)) from Paper II:

python paper2_constants.py --a 10 --b 1 --alpha 1 --mu 1 --nu 1 --gamma 1 --m 1 --beta 0 --L 1

Load parameters from a YAML file (same key names as the simulator; missing keys fall back to defaults; CLI overrides YAML):

python paper2_constants.py --config config.example.yaml
python paper2_constants.py --config config.example.yaml --beta 0 --L 1

Or import it in Python:

from paper2_constants import paper2_eq112_constants

c = paper2_eq112_constants(a=10, b=1, alpha=1, mu=1, nu=1, gamma=1, m=1, beta=0)
print(c.u_star, c.v_star, c.chi_a_star)

Stopping automatically when converged

If you do not want to guess a sufficiently large final time, you can run with --until_converged yes. In this mode, --time is interpreted as a maximum time horizon and the solver will stop early once the solution changes by at most --convergence_tol over a time window of length --convergence_window_time (after an initial --convergence_min_time warm-up).

Example:

chemotaxis-sim --chi 2.19 --meshsize 50 --time 200 --eigen_index 2 --epsilon 0.001 --until_converged yes

The command above will show first some characteristic constants of the system of partial differential equations that depend on the parameters input by the user:

A terminal plot of the initial functions u(0,x) and v(0,x) is also shown on the terminal:

Once the simulation is complete, a picture of the results is saved in both .png and .jpeg formats:

In addition, the numerical data are saved for later post-processing in a compressed NumPy file:

• a=..._b=..._c=..._alpha=..._m=..._beta=..._chi=..._mu=..._nu=..._gamma=..._meshsize=..._time=..._epsilon=..._epsilon2=..._eigen_index=....npz

This .npz contains (downsampled) x_values, t_values, u_num, v_num, plus a JSON-encoded copy of the run configuration and some metadata.

The CLI also writes a quick diagnostic figure with 6 time slices of $u(x,t)$ (0%, 20%, …, 100%). The title shows $\chi_0$ and the critical threshold $\chi^(u^)$:

• ..._summary6.png and ..._summary6.jpeg

If the user chose to save the animation of the chemotaxis process, an .mp4 video will be saved as well:

Documentation

For detailed information about the package and its functionalities, visit the documentation webpage.

TODO (performance / workflow)

• Stream RK4 storage for long runs (avoid allocating full u_num/v_num history; store only downsampled frames for plots/npz/video).
• Expose an explicit time-step/CFL knob (current Nt ~ O(T N^2) can be expensive for T=100).
• Add a pure-Python (optional Numba) tridiagonal solver for solve_v as a non-SciPy fallback / speed path.
• Add an option to skip heavy 3D surface plots in batch runs and generate them from saved .npz in post-processing.
• Add a lightweight smoke-test script (short run + basic invariants) since there is no dedicated test suite yet.

Reproducing previous results

In the following page, we reproduce the results of the research paper by ....

Reproducing_Results

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a new branch (git checkout -b feature/my-feature).
3. Commit your changes (git commit -am 'Add my feature').
4. Push to the branch (git push origin feature/my-feature).
5. Open a pull request.

License

This project is licensed under the MIT License – see the LICENSE file for details.

Contact

For any queries or further discussion, feel free to contact us at

• Le Chen: [[email protected]] or [[email protected]] or Homepage.
• Ian Ruau: [[email protected]].