Run PHARE

PHARE runs as a python script.

Python dependencies

PHARE requires a minimmum version of python 3.11 to run properly. Make sure python3 shows the version is at least 3.11. Python package dependencies are listed in pyproject.toml, and runtime ones also in requirements.txt. Install dependencies in a virtual environment with uv, from the PHARE source directory:

uv sync
source .venv/bin/activate

Install dependencies for the user with pip:

pip3 install --user -r requirements.txt

Install dependencies in a virtual environment with pip:

python3 -m venv phare_venv
source phare_venv/bin/activate
pip3 install -r requirements.txt

Running PHARE

First, make sure it is accessible to python. Assuming PHARE source directory is in /path/to/PHARE, and the build directory is /path/to/build/, then use the following to let python know where to find PHARE:

export PYTHONPATH=/path/to/PHARE/pyphare:/path/to/build:$PYTHONPATH

Write a script declaring a Simulation (see also Models, Diagnostics) and run the following command:

python3 /path/to/my_script.py

Executable PHARE initialization script

Running PHARE from python basically consists in declaring the desired blocks (see Simulation, Models, Diagnostics), and adding a main function to run the simulation.

If running the simulation from python, you need to define a main function that basically runs the simulation. Here is a small example:

from pyphare.simulator.simulator import Simulator
import pyphare.pharein as ph


# define your simulation parameters
# and initial condition...

sim = ph.Simulation(
# ...
)

ph.MaxwellianFluidModel(
# ...
)

ph.ElectronModel(closure="isothermal", Te=0.2)


def main():
    simulator = Simulator(sim)
    simulator.run()


if __name__ == "__main__":
    main()

The Simulator

The simulator is used to initialize and run the simulation. It is given the Simulation object as an argument, as in the simple example above. The simplest way to start the simulation is then to call the run() method.

class pyphare.simulator.simulator.Simulator(simulation, **kwargs)[source]

Mandatory arguments

Optional expert arguments

These arguments have good default, change them at your own risk.

  • print_one_line: (bool), default False, will print simulator info per advance on one line (erasing the previous)

  • post_advance: (Function), default None. A python function called with the current time after each advance, once any diagnostics active at that time have been dumped. Diagnostics may not exist for that time, in which case loading them raises pyphare.pharesee.hierarchy.TimeNotFoundError. With more than one MPI rank, an exception it raises aborts the MPI job, as the other ranks may be waiting on this one

  • log_to_file: if True (default), will log prints made from C++ code per MPI rank to the .log directory

run(plot_times=False, monitoring=None)[source]

Run the simulation until the end time, calling advance() in a loop. The simulator stays alive afterwards (e.g. for data_wrangler()), diagnostic files are closed. It is released by reset(), when another simulator is set up, or at exit.

  • plot_times: (bool), default False. If True, plots (rank 0 only) the wall-clock time taken by each timestep once the run ends.

  • monitoring: (bool or int), default None. Enables periodic resource monitoring (CPU/memory, per MPI rank) written to .phare/stats/rank.<rank>.yaml, sampled every N seconds if given as an int (default 100 if just True), or falls back to the PHARE_SIM_MON environment variable if left None. Requires the optional phlop package (python3 -m pip install phlop); silently does nothing if it isn’t installed.