Skip to content

Parallel scan¤

Example script: examples/run_parallel_scan.py | Code documentation

Description¤

Python code allowing to run multiple ASTRA simulations at one time, automatically changing the parameters in a defined way. The output of this is a parameter scan.

It is possible to define a list of a parameter values to be scanned and maximum number of simulations to be run at a time. For each value in the list, an ASTRA simulation will be automatically performed.

The parallel scan is not limited to one parameter only. Multiple parameters can be varied at the same time, given that the number of values to be scanned is the same for all parameters, i.e. the scan values have the same dimensions.

Tip

To optimize multiple parameters, one by one, use the basic optimization script. To run complex matrix scan of the parameters, see chain scan script instead.

Example script¤

examples/run_parallel_scan.py
"""Script to run the parallel scan.

It allows to run scan of one or several parameters at once. The script allows to run multiple ASTRA simulations at the same time to decrease the overal scanning time.
"""

import sys
sys.path.append("..")

from astra import parallel_scan

# no changes above
#####################################################################################################
# change the values of the parameters

# directory where the scan should be performed, must be full path
working_dir = r"full path to the working directory"
# number of parallel processes to be run
n_parallel = 3
# initial run number, if None, the run number will be set automatically
# i.e. if there are already existing scans in the working_dir, makes sure to increase the run number
initial_run_number = None 

#####################################################################################################
# no changes here

def main():
    ps = parallel_scan.ParallelScan(working_dir=working_dir,
                                    n_parallel=n_parallel,
                                    initial_run_number = initial_run_number
                                    )
    #####################################################################################################
    # make changes here to match what you want to scan

    ps.add_scanning_parameter("rt", start=1e-6, end=1e-5 , step=10)

    ps.add_scanning_parameter("MaxB(1)", start=0.125, end=0.375, step=0.005)
    ps.add_scanning_parameter("Lx",  start=1.5, end=2.9, step=0.1)

    #####################################################################################################
    # no changes bellow

    ps.run_scan()
    ps.plot()

if __name__ == '__main__':
    main()

For the script to work, the working_dir (working directory) specified when constructing the optimizer must be prepared as described here. The script itself is explained in detail later on this page.

With Python environment well set-up, the script can be simply run as 

python run_parallel_scan.py

Setup¤

Working directory setup¤

Files needed in the working directory are listed in the table bellow. It is recommended not to have any other files and folders in the working directory, except for pure text (.txt) files containing comments. This is to not mess up with the files created by the simulation.

File Comment
Astra.exe Astra executable file.
generator.exe Astra initial particle distribution generator.
.dat files Files defining the structures used in the simulations.
Generator file File obtaining the initial distribution definition, which will be generated by the generator.exe. By default, the python code will assume this file is named generator.in, but this can be changed in the object setup.
Simulation definition file File obtaining the setup definition. By default, the python code will assume this file is named photo_track.in, but this can be changed in the object setup.

Run script setup¤

Important

Please note that the run script does not have to be in the working directory. It is recommended to keep the script and working directory separated and have the run script in a subdirectory of the main code directory (for example create a scripts/ directory inside the main code directory) to avoid problems when importing the code. The working directory will be passed as an argument, as explained later in this section.

The astra/parallel_scan.py must be imported from the astra subpackage of the main package:

from astra import parallel_scan

In case this fails, the main package must be specifically added to the python path so python actually recognizes that. This can be achieved by the sys library and the full import is therefore:

import sys
sys.path.append("..") #(1)

from astra import parallel_scan
  1. Use .. when the script is located in a subdirectory of the main code folder (recommended), otherwise use the full path to the main code directory.

Scan object setup¤

The scan code is written as object-oriented. Therefore, after importing the corresponding source file, the scan object has to be created. 

from astra import parallel_scan


def main():
    # define the optimizer and the working directory
    ps = parallel_scan.ParallelScan(working_dir="<workingDirectory>") #(1)

    ...

if __name__ == "__main__":
    main()
  1. Full path to the working directory. See the full list of possible parameters here.

The full list of parameters to be set when initializing the object is listed here. The most important one is the working_dir parameter, which defines where the scan should take place.

Scan setup¤

Although the parameters to be scanned can be defined in the scan object construction, it is recommended to define them after the construction for better clarity. The ParallelScan.add_optimalization_parameter method.

There are multiple options how to define the range of the parameter to be scanned:

  1. Full values list (values)
  2. Start and end values (start, end) + step size (step)
  3. Start and end values (start, end) + number of steps (n_steps)

This list also corresponds to the order at which the definition of the parameter is checked. Once the parameter is fully defined (one of the points above is fulfilled), the rest of the values may be internally overwritten to match the calculated values from the full definition. See the corresponding page of the ParallelScan.add_optimalization_parameter method for more details.

Multiple parameters can be scanned at the same time, given that their scanning ranges have the same dimensions (the same number of values to be scanned). To configure the scan for multiple parameters, simply use the ParallelScan.add_optimalization_parameter method for each parameter, e.g. if three parameters are to be scanned at the same time, there will be three ParallelScan.add_optimalization_parameter method in the script.

Tip

See the implementation in the provided example.

Output¤

Basic analysis is performed after the end of the scan, see the corresponding page for more details.

Last update: October 29, 2023
Created: September 14, 2023