Setups:

This project consists of two primary components. The first and main component is implemented in C++ using the deal.II libraries, which includes the computational model for running simulations and generating results. The second component is a desktop interface built in Python 3 with PySide6 (Qt) — an adaptive dashboard for adjusting model parameters and visualizing the results.

Note: The current version of this project is optimized for macOS, supporting both Intel and Apple Silicon processors. If you'd like to run it on Linux or Windows, please refer to the respective branches of the project.

Below, you'll find a step-by-step guide for setting up, installing, and configuring the project. If you don't plan to use the second component (the user interface), you may skip directly to the "Configuration without Python3" section.

Note: This project is based on the model introduced in the paper "Zarzor, M. S., Ma, Q., Almurey, M., Kainz, B., & Budday, S. (2024). Exploring the role of different cell types on cortical folding in the developing human brain through computational modeling. Scientific Reports, 14(1), 26103".

Setup and Installation

The following packages and libraries must be installed before running the project:

• Xcode
  Install Xcode from the App Store. You may also need to install command-line tools by running:

   xcode-select --install   
  

  You can verify the installation with xcode-select --version, which should return xcode-select version 2396. If not, the installation was unsuccessful.

• CMake
  Install CMake by first installing Homebrew. Open a new terminal and run:

  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  

  Then install CMake:

      brew install cmake
  

  Verify the installation with cmake --version, which should return cmake version 3.24.1. If not, the installation failed.

• Compiler and MPI
  Install these with Homebrew:

  brew install cmake open-mpi gcc@11
  

• Python3
  Install Python3 using Homebrew:

  brew install python@3.10
  

  Verify the installation with which python3, which should return /opt/homebrew/bin/python3.

  The interface uses Qt through PySide6, so no separate Tkinter installation is required.

  Ensure PIP is installed for managing Python3 packages. Check with pip --version. If PIP is not installed, follow the instructions here.

• deal.II
  To install and set up the deal.II library:

  1. Open the terminal and type clang to trigger installation of command-line tools.
  2. Download the deal.II library:

  git clone https://github.com/dealii/candi.git
  

  3. Navigate to the downloaded folder: cd candi.
  4. Set the environment variables:

  export OMPI_FC=gfortran-11; export OMPI_CC=clang; export OMPI_CXX=clang++
  

  5. Install deal.II:

  ./candi.sh --packages="dealii"
  

  6. Follow on-screen instructions (you can cancel the process by pressing Ctrl+C).

If you encounter issues, please check the deal.II installation guide or the MacOSX wiki.

Note: We recommend using deal.II version 9.4 to avoid compatibility issues with other versions.

Configuration

To download and configure the BFSimulator project:

1. Navigate to your desired download directory and run:

	git clone https://github.com/SaeedZarzor/all-fields.git

2. Enter the project folder:

   cd all-fields

3. Install necessary Python3 packages:

	pip install -r requirements.txt

4. Start the interface:

	python3 BFSimulator.py

`BFSimulator.py` uses the portable `#!/usr/bin/env python3` shebang, so you can also
make it executable once with `chmod +x BFSimulator.py` and run it as `./BFSimulator.py`.
No path editing is needed.

Using the interface

The main window is an adaptive bento dashboard. The six parameter categories — Geometry, Advection–Diffusion, Mechanical Properties, Discretization, Numerical Solver and Growth — are cards in a responsive grid that reflows from three columns to two to one as the window narrows.

• Parameter Guide. Focusing any field updates the guide panel with that parameter's figure, symbol, unit, recommended range, explanation and reference link. It sits on the right in wide windows and docks below the cards in narrow ones, and the Current-value cell widens to a full row when it has to hold a grouped row's recap.
• Grouped parameters. Four rows open a dedicated editor rather than a single box: the cells division ratios (the 9×5 lineage matrix, shown beside a cell-division figure that is redrawn as you type — each phase rung fills with the cell types that exist after that phase, and their counts — with rows that unlock only once their parent population exists), the phases timeline (four sliders running against a shared gestational-week ruler: the ruler covers the sliders' own range, GW 4 to 48, so each handle rests under its week, and one step moves exactly three weeks — one labelled tick — with the phases kept in order), the per-cell-type migration speeds, and the per-cell-type diffusivities. A grouped card row stays compact: it speaks up only when one of its values is unset or out of range. The values themselves live in the editor and in the Parameter Guide.
• Validation is live. Out-of-range entries are flagged inline and in the guide, and Run is blocked until they are fixed.
• Action bar. Restore Defaults loads the 2D or 3D preset; Save / Load Parameters read and write any .prm file; Run Simulation builds if needed and starts the solver.
• Progress and results. The run streams the solver's output into a progress window with a bar driven by the simulation time, and can be stopped. When it finishes, the results browser regenerates each result through ParaView's pvpython only if the output file is missing, then shows it — the folds pattern as an image and the rest as looping videos. The folds pattern and cell density are per cell type; pick RG, ORG, IP or NU with the selector above the buttons.

The interface is split across BFSimulator.py (window, .prm read/write, validation) and the modules bf_fields.py (the parameter registry), bf_widgets.py (reusable components and the group editors), bf_style.py (light/dark theme), bf_runner.py (build/run and ParaView workers) and bf_results.py (results browser).

Configuration without Python3

If you'd like to run only the first part of the project, follow these steps:

1. Ensure that Xcode with command-line tools, CMake, compiler and MPI, and deal.II are installed (see above). Paraview is also recommended for visualizing results.

2. Download the project:

	git clone https://github.com/SaeedZarzor/all-fields.git

3. Navigate to the project folder:

   cd all-fields

4. Generate the Makefile with:

	cmake CMakeLists.txt

5. Run the following command:

   make

To start the simulation:

./Brain_growth Parameters.prm 2

For 3D simulations, replace 2 with 3. Modify simulation parameters directly in the Parameters.prm file.