Usage¤

This panel provides basic information about using the ASTRA framework.

In general, it is recommended to create a separate python script inside the code directory, from which the scans and other optimization objects from this package are imported, configured and run.

Several example scripts are provided inside the examples/ folder to serve as a starting point and templates for using the framework.

It is however not recommended changing these scripts in order not to mess with the git versioning (if you do not know what that is, you can completely ignore this). Best approach is to create a new directory inside the main code directory (e.g. called scripts/) and copy the relevant scripts there and use them from there. Having the scripts completely outside the main code directory may cause problems when importing the code and is thus not recommended.

On the other hand, the location of the directories with the simulations is not important, they may even be located on a different disk.

The pages in this documentation panel describe in detail the different example scripts.

General workflow¤

The general workflow should therefore look like this:

Initial preparation

Perform this only once. Create a subfolder scripts/ inside the main code directory and copy one of the example scripts from examples/, that you intend to use.

Also, make sure that you have installed python and all the packages needed. See the relevant documentation page.

Simulation preparation

Prepare a folder with the ASTRA files and the simulation input files. The simulations will be performed in this folder and at the end, you can find the outputs here. The contents of this folder is summarized in the table bellow.

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.

The location of this folder can be arbitrary: it does not have to be inside the main code directory.

Update the simulation script

The easiest option is to update one of the example scripts to match your needs. Make sure to work in the scripts/ subfolder of the main code directory (if this subfolder does not exist, create it there and copy the example scripts from the example/ directory).

The provided scripts are mostly self-explanatory, you will need to update the working directory (= the directory with the simulation files prepared in step 1) and correctly set what parameters should be scanned.
How to define the scanning parameter and its range

All variables present in the actual ASTRA input files can be used as scanning parameters, although only those with numerical values are supported.

In most of the example scripts dedicated to scans, the scanning parameter can be added via the add_scanning_parameter method. There are multiple options how to define the range of the parameter to be scanned, depending which arguments of this method are used:
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.
It is recommended to use these three scripts:
- Parallel scan: to perform a single scan of one or multiple parameters in a given range, while running several ASTRA simulations in parallel
- Basic scan: to optimize a set of parameters in a given range. The optimization is performed for a single parameter at a time, the best value of this parameter is then used for the optimization of the following parameters.
- Chan scan: to perform complex matrix scan for a set of parameters, varying each value of single parameter of each value of the rest of the parameters.
Run the script

When both the script and working directory are prepared, run the script in the terminal. Open the terminal (on Windows, click on the Windows logo and write terminal) and navigate to the directory with the script by typing in the terminal the following line (replace scriptDirectory with full path to that directory):
```
cd scriptDirectory
```
After that, the script can be run by typing the following line to the terminal (replace script.py by the actual script name):
```
python script.py
```
or
```
python3 script.py
```
Should both of these command fail, read the error message and try to solve the problem. Alternatively follow these steps:
1. Check if your terminal is working in the directory with the script.
  
  To check this, write the following line into the terminal
  WindowsLinux/MacOS
  dir
  ls
  After typing this into terminal and pressing the return key, you should see a list of contents of this directory. Check if you can see the name of the script you are trying to start in the list.
  
  If the name of script is missing, you are in a wrong directory. Please locate the script, copy the full path of the directory in which the script is located (on Windows, this starts with a letter representing the disk, for example C:\..., on MacOS and Window, the path start with /...). Copy this full path and type in the terminal (replace pathToScript by the copied path)
```
cd pathToScript
```
2. Check if you have correct Python installation
  
  Type
```
python --version
```
  or
```
python3 --version
```
  to the terminal. The output should look like Python 3.9.X, where X is a number. Should this fail, refer to the installation guide.
3. Check if you are missing some python packages
  
  If the error message you saw when trying to run the script as described above included something about missing packages, you probably need to reinstall them. The procedure is described in the framework installation section on the Installation and first setup page, so please refer to that.

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