Subsections


Scripting

All operations that can be performed within the prompt UI are also accessible through scripting (Figure 1.2). First type your commands into a text file ending in *.py - a relax script is a Python script (loaded and executed as a Python module). Note that scripts can also be run through the GUI.

To use this mode of relax, you will need to open up a terminal in your respective operating system:

GNU/Linux:
Here you have an incredible number of choices. If you don't have a preferred shell already, you could try one of Konsole, GNOME Terminal or even XTerm if you are a masochist.
Mac OS X:
This is as simple as in GNU/Linux - just launch Terminal.app from the Utilities folder.
MS Windows:
If your system supports it, you should install and use Windows PowerShell. The alternative is the nasty cmd command line terminal program which comes installed by default on all Windows versions. The PowerShell, although no where near as powerful as the GNU/Linux and Mac terminals, is a huge improvement on the ancient cmd program and will make relax much better to use on MS Windows.

Once your terminal is running, go to the directory containing your script using the cd command (if you do not know what this is, please see the documentation for your terminal program to understand some of its basic usage). Once you are in the correct directory, within the terminal type:


$ relax your_script.py

You will need to replace your_script.py with the name of your script. In most cases you would probably like to keep a log of all of the messages, warnings and errors relax produces for future reference. To active logging within relax, type:


$ relax -log log your_script.py

This will place all output (both STDOUT and STDERR) into the log file (you can choose any name for this log file). Alternatively you can both log the output and simultaneously see the messages in your terminal by typing:


$ relax -tee log your_script.py

These command line arguments could be replaced by IO redirection if this is a familiar concept to you, but note that these arguments are active also in the GUI mode whereby IO redirection in the terminal will have no effect. An example of a simple script which will minimise the model-free model “m4” after loading six relaxation data sets is

# Create the data pipe.
name = 'm4'
pipe.create(name, 'mf')

# Load the PDB file.
structure.read_pdb('1f3y.pdb')

# Set up the 15N and 1H spins.
structure.load_spins('@N', ave_pos=True)
structure.load_spins('@H', ave_pos=True)
spin.isotope('15N', spin_id='@N')
spin.isotope('1H', spin_id='@H')

# Load the relaxation data.
relax_data.read(ri_id='R1_600',  ri_type='R1',  frq=600.0*1e6, file='r1.600.out', res_num_col=1, data_col=3, error_col=4)
relax_data.read(ri_id='R2_600',  ri_type='R2',  frq=600.0*1e6, file='r2.600.out', res_num_col=1, data_col=3, error_col=4)
relax_data.read(ri_id='NOE_600', ri_type='NOE', frq=600.0*1e6, file='noe.600.out', res_num_col=1, data_col=3, error_col=4)
relax_data.read(ri_id='R1_500',  ri_type='R1',  frq=500.0*1e6, file='r1.500.out', res_num_col=1, data_col=3, error_col=4)
relax_data.read(ri_id='R2_500',  ri_type='R2',  frq=500.0*1e6, file='r2.500.out', res_num_col=1, data_col=3, error_col=4)
relax_data.read(ri_id='NOE_500', ri_type='NOE', frq=500.0*1e6, file='noe.500.out', res_num_col=1, data_col=3, error_col=4)

# Initialise the diffusion tensor.
diffusion_tensor.init((2e-8, 1.3, 60, 290), spheroid_type='prolate', param_types=2, fixed=True)

# Create all attached protons.
sequence.attach_protons()

# Define the magnetic dipole-dipole relaxation interaction.
interatom.define(spin_id1='@N', spin_id2='@H', direct_bond=True)
interatom.set_dist(spin_id1='@N', spin_id2='@H', ave_dist=1.02 * 1e-10)
interatom.unit_vectors()

# Define the CSA relaxation interaction.
value.set(-172 * 1e-6, 'csa')

# Select a preset model-free model.
model_free.select_model(model=name)

# Grid search.
minimise.grid_search(inc=11)

# Minimise.
minimise.execute('newton')

# Finish.
results.write(file='results', force=True)
state.save('save', force=True)

Scripting is much more powerful than the prompt as advanced Python programming can be employed (see the file relax_curve_diff.py in the sample_scripts directory for an example).


Sample scripts

A few sample scripts have been provided in the directory sample_scripts. These can be copied and modified for different types of data analysis.

The relax user manual (PDF), created 2020-08-26.