ESS Beam Physics Python Tools
This project provides useful Python tools for executing TraceWin, and reading/writing TraceWin data files.
The files are written primarily for usage at European Spallation Source, but might be useful elsewhere.
You are free to use this code, but no warranty whatsoever is given.
Installation
To install/ upgrade the package, run the command below. It is assumed that you have git and pip installed on your system.
pip install git+https://gitlab.esss.lu.se/ess-bp/ess-python-tools.git -U --user
If you have installed using Anaconda, we recommend to not use the argument --user
.
The argument -U
implies you should upgrade if you have already installed this package but a newer exist. --user
implies that this should be installed for the current user only (usually in the folder ~/.local/lib/).
Usage
Here we will briefly explain how to use the library. Please also see the Online Documentation.
lib_tw
Some example use cases...
from ess import lib_tw
file_name_lat ='lattice2.dat'
file_name_lat_new='lattice2.adjusted.dat'
file_name_fmap =['Field_Maps/1D/'+f for f in ['Spoke_W_coupler.edz','MB_W_coupler.edz','HB_W_coupler.edz']]
file_name_st ='Steerer_Values.txt'
file_name_adj ='Adjusted_Values.txt'
lat=lib_tw.LATTICE(file_name_lat,file_name_fmap)
# Updates based on Steerer_Values:
lat.update_st(file_name_st)
# Updates based on Adjusted_Values:
lat.update_adj(file_name_adj)
lat.get_tw(file_name_lat_new)
#-- If we want to reset all steerers to 0 ...
#for i in range(len(lat.lst)):
# if lat.lst[i].typ=='THIN_STEERING': lat.lst[i].BLx=0.0; lat.lst[i].BLy=0.0
# if lat.lst[i].typ=='STEERER' : lat.lst[i].Bx =0.0; lat.lst[i].By =0.0
lib_tw includes a function to convert loss/elem to loss/elem-length. Examples:
# Note:
# - For a density file, be careful with the number of runs.
# - The instances for losses are "loss_pow", "loss_num", "loss_pow_ave", and etc for DENSITY class.
# - For PARTRAN class, loss_elem2den function is already implemented as a method.
# - If file_name_dt isn't given, the half-cell lengths are used instead of drift-tube lnegths.
# - dlt_dt is a small number used to identify DTL_CEL elements. (Play with this number is there is an error message.)
#
# - An example to make a bar plot with an output file of this script can be found in
# https://gitlab.esss.lu.se/ess-bp/pgfplots-examples/tree/master/loss.den
from ess import lib_tw
file_name_den ='density_file_name'
file_name_ptrn='partran_out_file_name'
file_name_dt ='len.dt_dtl.v85.txt' # File with (half cell length) vs (drift tube length) for DTL cells
#-- An example for a density file
den=DENSITY(file_name_den)
s_from_den =den.s
loss_from_den=den.loss_pow # For a file w/ single run
#loss_from_den=den.loss_pow[Nrun] # For a file w/ multi runs (e.g., file from an error study)
loss_den_from_den=loss_elem2den(s_from_den,loss_from_den,file_name_dt,dtl_dt=5e-6)
# Note len(s_from_den) = len(loss_den_from_den) when writing to a file.
#-- An example for a partran out file
ptrn=PARTRAN(file_name_ptrn)
loss_den_from_ptrn=ptrn.loss_den(file_name_dt,dtl_dt=5e-6)
# Note len(ptrn.s) = len(loss_den_from_ptrn) when writing to a file.
There is another larger example of how you may modify the lattice in the examples folder, see manipulate_lattice.py.
ess.TraceWin module
This module was developed in parallell with lib_tw, and contains some overlapping functionality. The module allows you to read (and sometimes write) the various binary files from TraceWin into a pythonized object. Some example usecases follows below.
For more documentation, also check the built-in help help(ess.TraceWin)
# Example: read in plt file, write dst file for each location
from ess import TraceWin
data=TraceWin.plt('dtl1.plt')
for i in data.Nelp:
data.save_dst(i,'distribution_{}.dst'.format(i))
# Example: read in many Density files from a folder, put data into one HDF5 file
from ess import TraceWin
import os
for f in os.listdir('calc'):
if f[:7]=='Density' and f[-3:]=='dat':
fpath=os.path.join('calc',f)
group_name=f[8:-4]
data=TraceWin.density_file(fpath)
data.savetohdf('Density.h5',group_name)
Error study script
First you need to use the GUI to create an error study folder in your output directory (see functionality Copy set of data
). You may copy as many jobs as you want to run directly in the GUI, but it is very slow and we recommend to rather define the number of runs in the submit command provided here. This submit command use hard links when possible to also save space.
You then send the jobs to the queue manager using the command tracewin_errorstudy
. The help function of this script already says most of what you need to know:
usage: tracewin_errorstudy [-h] [-s SEED] [-c CALC_DIR] [-n NUM_JOBS]
[-t STUDY] [-m MULTI] [-l LATTICE] [-q SETTINGS]
[-p PRIORITY]
Simple setup script to run TraceWin on HT Condor.. Default values in square
brackets
optional arguments:
-h, --help show this help message and exit
-s SEED Define seed [None]
-c CALC_DIR Path to calculation folder [temp/]
-n NUM_JOBS Number of jobs [Count number of copied runs in TW]
-t STUDY Statistical study number [1]
-m MULTI Multi-dynamic study [1]
-l LATTICE The lattice file for the project [lattice.dat]
-q SETTINGS The settings for the project template (yaml) [settings.yml]
-p PRIORITY Job priority
A few things are worth mentioning:
- We provide the option of having the lattice file as a template, with settings specified in a YAML file. It is then assumed that the template has the ending .tmp (so if the default lattice.dat, the template file lattice.dat.tmp is expected to exist). Variables are then replaced as per str.format.
- The default Condor script templates should suffice for most. However we do provide an option to define template files, again to be replaced according to Python's str.format. If any of the files exist in the working directory they will be used in favour of the built-in templates.
- For standard jobs, the templates are head.tmp and queue.tmp
- For multi-jobs, the templates are head.multi.tmp and queue.multi.tmp
- We provide the option to run multi-dynamic study which is perhaps a bit confusing. In this mode, it is assumed that you have already run a number of simulations before. For each new job, we change the seed but read the same error table for dynamical errors. This allows us to understand better if we are limited by static or dynamic tolerances.
Example 1
Standard simulation of 100 machines in the folder calc
tracewin_errorstudy -n 100 -c calc
Example 2
Simulating 50 machines, then run 20 machines with different static errors but same dynamic errors for each of those (1000 machines total)
tracewin_errorstudy -n 50 -c calc
# wait until simulations have finished (check condor_q, condor_status, condor_history)
tracewin_errorstudy -n 50 -m 40 -c calc