How to run¶

These notes expand on the instructions in How to install and tailor them to the task of setting up simulations.

Under reconstruction

These notes are a bit stale and need updating.

Setting up¶

If you haven't done this already, clone or download/unzip the project repository from GitHub:
```
git clone https://github.com/cstarkjp/Langevin.git
```
This will create a folder called Langevin/. We are going to use its subfolders demos/, simulations/, and experiments/.
Elsewhere, out of this folder hierarchy, create your own "work" folder. Let's say you call it MyDPLangevin/. Copy the three subfolders into it. Your folder should now look something like this:
Optional, but strongly advised: create a Python environment for work in this folder. If you're using uv, all you need to do here is:
```
uv venv --python=3.14
source .venv/bin/activate
```
Then install the langevin package as explained on the How to install page, ideally using uv
```
uv pip install langevin
```
Now you have a local Python environment for work with the langevin package. Remember to always first source .venv/bin/activate from the command line when working here.

If you choose not to set up a virtual environment, you will need to install the langevin package in the usual way for your default Python.

Test scripts¶

Navigate to the demos/ folder. Run the demonstration scripts there as explained on the Demos page.

Full simulations¶

Organization¶

Navigate to the simulation/dp/ folder. There you'll find Jupyter notebooks and Python scripts to run more substantial DP-type Langevin simulations:

These notebooks and scripts can be run using ipython and python respectively (ipython can run both). The notebooks can also be run in jupyter.

Now take a look at your copy of the experiments/ folder. It should look something like this:

Simulations work with Info.json parameters files in correspondingly named folders, and write their results into subfolders within them. Further explanation is provided below. The naming convention is a bit awkward, but it's tough to come up with a perfect solution to organizing simulations with myriad coefficients and model variables. This is what we have.

Running a simulation for fixed grid size¶

Consider the notebook Simulation.ipynb, which runs a job entitled a1p18855_b1_D0p04_η1_x31_y31_Δx1_Δt0p1.

This cumbersome name is a concatenation of the key DP model parameters employed in this particular simulation. It corresponds to a subfolder in experiments/ called a1p18855_b1_D0p04_η1_x31_y31_Δx1_Δt0p1/.

This subfolder is used both for model parameter input and for results output.

Look in this subfolder of experiments/ for Info.json: this JSON file contains all the parameters used by the notebook to run a single integration of the DP Langevin equation on a 2D grid with the model coefficients reflected in the job name.

Run the simulation:

    ipython Simulation.ipynb

and you should see text output in your terminal reporting integration of a 2D Langevin equation — on a small grid with periodic boundary topology in the \(x\) direction and "free" edges in the \(y\) direction.

It should write output files to the experiments/a1p18855_b1_D0p04_η1_x31_y31_Δx1_Δt0p1/ folder like this:

All the output files are written to a subfolder rs1/, which corresponds to the random seed (of value one) chosen for this particular simulation. If you want to run different realizations for different random number seeds, change the Info.json file as appropriate.

Looking at each of the output files in turn:

Outfo.json = a copy of Info.json extended with results data and model run information
ρ_t.npz = a compressed numpy-format data file containing a collection of model results arrays; these may include
- a tuple of the simulation time "epochs"
- a tuple of the grid-averaged "mean density" of the order parameter field at each of these epochs
- a set of "segment" time slices of the order-parameter density grid \(\rho(\mathbf{x},t)\) (if this option is chosen in the Info.json file; by default here it is not)
ρ_t_loglog.png = a graph of mean density over time
ρ_t_rescaled.png = a DP-model rescaled version of this graph

In summary: if you want to run single-grid simulations, with a single set of Langevin coefficients and model parameters, use this notebook as your template.

Running an ensemble of simulations for fixed grid size¶

If instead you want to run an ensemble of simulations for a range of Langevin equation coefficients, look at EnsembleSimulation.ipynb.

    ipython EnsembleSimulation.ipynb

This will run a set of simulations for different size grids:

TBD...

Running a batch of ensemble simulations for several grid sizes¶

For substantial ensemble simulations in which the grid size is varied as well as the model coefficients, a batch Python script is provided. This script hard-codes some parameter choices, loops across a set of grid sizes, and constructs a list of ensemble job names from a tuple of grid size choices. These names must correspond to a "root" folder and a set of subfolders:

It then executes each ensemble job in turn:

For this example batch script, the batch root folder (in experiments/) is assumed to be named ac1p18857, corresponding to the known critical value \(a_c\) (from previous simulations) of the DP Langevin parameter \(a\); its subfolders follow the pattern b1_D0p04_η1_x{size_}_y{size_}_Δx1_Δt0p1, i.e. the other DP Langevin parameters are \(b=1\), \(D=0.04\), and \(\eta=1\), for grid spacing \(\Delta{x}=1\) and time step \(\Delta{t}=0.1\). There must be Info.json files in each of these subfolders with model parameters to match:

Run the batch job using either ipython or python:

    python batch_ensemble.py

In your terminal, you should see summary reports of each ensemble of simulations, two sets of 15 in total, including the name of each simulation job and its computation time. Each set of 15 jobs would have been executed in parallel processes spawned by Python's multiprocessing tool.

The directory tree for this run should now look like this:

where you can see that each set of results files has been placed in parallel with the corresponding Info.json file for that grid size. The combo_ρ_t.npz file in each case is the compressed numpy data file containing a single t_epochs.npy array and a tuple of mean_densities.npy arrays, one for each value of Langevin parameter \(a\) used in the ensemble of simulations. The Outfo.json file records this set of \(a\) values and all the other model variable choices for each simulation.

To run for a wider range of grid sizes, simply modify the list in batch_ensemble.py; if you want to choose different sizes, or different model parameters, you will have to modify the whole ac1p18857/ folder hierarchy, its subfolder names, and the constituent Info.json1 files to match. This is a bit ungainly, but it keeps the organization of simulations coherent.