°  Getting started As you can read this manual, YASARA has been installed successfully. For your convenience, YASARA does not use an invasive installer. If you use Windows, just pull the YASARA icon anywhere in the Start menu to place a shortcut there. Simply delete the directory to uninstall. When you run YASARA, you will see a startup screen. After a few seconds, you are ready to go. Click on 'Help > Play help movie > Working with YASARA', and spend a few minutes to see how YASARA works... If you work with Windows and have not installed Python yet, click Help > Install program > Python. This will enable many useful plugins. If something does not work as expected, look at the description of the command. Most likely, you will find the solution there. If anything goes really wrong, please visit the Troubleshooting-section. Here are the most important hints to get you started: If you do not like the blending windows, go to Window > Animation If you do not like the background colors, go to View > Color > Background If you install YASARA as a different user (not yourself), you must run it once as this other user. Look here for more details. °  The ten magic words Throughout this documentation, there are ten words which YASARA 'overloads' with a specific meaning. °  Atom - YASARA's representation of a true atom Contrary to real atoms, YASARA's atoms can easily be distinguished: Every atom has a unique number and many attached properties, like chemical element, atom name, residue name, residue number, molecule name etc. Each YASARA atom maps directly to one line in a PDB file. Here is an example from 1c9b.pdb: ATOM 105 CA THR A 123 19.779 20.075 26.943 1.00 53.14 C The line above describes atom 105 with name 'CA' and cartesian coordinates (19.8/20.1/27.0), belonging to residue 'Thr 123' in molecule (=chain) 'A', with an occupancy of 1.00 (fully present), a B-factor of 53.1 and finally - the chemical element is 'C'. YASARA numbers all the atoms continuously, starting with 1. As a direct consequence, YASARA atom numbers will not always be the same as those given in the PDB file (because PDB files also number 'TER' entries, and YASARA can load many PDB files at the same time). In addition, atom numbers change frequently (for example when adding hydrogen atoms). When writing a macro, it is therefore suggested to select atoms using their name and the residue they belong to, but not using their number. If you ever have to modify a PDB file, remember that all characters must be placed in the right column. See www.rcsb.org for a complete description of the PDB file format. For chemical consistency, YASARA removes numbers from chemically equivalent hydrogens. More details about this mechanism can be found here. Figure: One single carbon atom, created with the BuildAtom command. °  Residue - any continuous stretch of atoms sharing the same residue name, residue number and molecule name Note the word 'continuous'. If you split a residue in the middle (corresponding to a TER entry in the PDB file), you will end up with two separate residues. The scourge of molecular modeling is the 'residue numbering problem'. PDB files provide space for residue numbers up to 9999. What if there are more than 9999 residues? What if there are several residues with the same number? Most programs answer these questions by introducing a second numbering scheme, so that you have to remember two different numbers per residue. YASARA provides an easy solution: the PDB residue number is the one and only, ambiguities are resolved with the selection language and its new concept 'selection inflation': DelRes 300 Delete residue with PDB number 300 If there is more than one residue with this number, YASARA will delete all of them. What if you want to select only one of these residues? DelRes 300 Mol B Delete residue with PDB number 300 in molecule (=chain) B And finally, what if molecule B contains more than one residue with number 300? As peptide chains are generally shorter than 9999 residues, this hardly ever happens. If it does, select one of the atoms in the residue and use selection inflation : DelRes Atom 13747 Delete the residue which contains atom 13747 Atom numbers are always unique in YASARA. Figure: One single arginine residue, created with the BuildRes command. °  Molecule - any continuous stretch of residues sharing the same molecule name If you already worked with other programs, you may know YASARA's 'molecules' as 'chains'. The name 'molecule' was chosen due to its more convenient abbreviation 'Mol' and for consistency with the WHAT IF program. Note that a YASARA molecule is not always the same as a chemist's molecule. If two molecules ('A' and 'B') are joined with a disulfide bridge, they are still two separate molecules for YASARA as long as their names differ. Also if your structure contains 500 waters, all with the same molecule (=chain) name, they will be treated together as one 'molecule'. Figure: Part of the peptide chain of crambin, created with the BuildMol command. °  Object - a collection of molecules and additional items An object consists of molecules and other items like labels or arrows. If you load a PDB file, you will get one object. If the PDB file contains multiple models (NMR structures), every model will become one object. Objects can be moved around independently with the mouse. Starting with YASARA Model, you can freely split objects into multiple smaller objects, and join them again. Objects can be 'active' or 'inactive'. Inactive objects are removed from the soup , they are neither displayed on screen nor do they participate in molecular dynamics simulations. The only command that works on inactive objects is 'AddObj' - which brings them back to life. Note that many commands act on all the atoms within an object, instead of the complete object (including labels etc.). Example: ColorObj 1crn,red will color all atoms in the object named 1crn red, but not any additional items like labels or arrows that are attached to the object. RotateObj 1crn,Y=90 will rotate object 1crn by 90 degrees about the Y-axis, including all additional items. How can you tell the difference? Take a look at the description of the command. If you find the command listed with an 'Atom' extension (like 'ColorAtom'), you know that it is an atom-only command. Figure: An object - Crambin with arrows, labels, hydrogen bonds and a ribbon backbone. °  Soup - all atoms in active objects A name familiar to WHAT IF users. The soup consists of all the atoms in active objects. It does not include labels etc. Figure: A soup of ~20000 atoms. °  Scene - all objects together The 'Scene' includes all objects, whether active or inactive, including their position and orientation. So if you save the scene, you will also save the current view and all items like labels. Figure: A scene with three objects (molecule A, B and Water), and some labels. °  All - the scene or the soup Again, it depends on the type of the command whether 'all' stands for 'all objects' (the scene) or 'all atoms in active objects' (the soup), look above for an explanation. °  Bond - a covalent link between two atoms with pH dependent order While chemistry knows many different kinds of bonds, YASARA uses the term 'bond' only for classical covalent bonds. Bonds with a high ionic character, e.g. between and to metal ions, are not treated as bonds. Instead, molecular dynamics force fields rely purely on electrostatics to reproduce these 'bonds', and adding explicit bonds would cause problems when assigning force field parameters. If a PDB file nevertheless specifies bonds to metal ions (using the 'CONECT' record), YASARA automatically converts them to pseudo-bonds, i.e. plain cylinders that help the visualization but are not part of the soup and ignored for all other purposes with one exception: at the beginning of a simulation, they are used to add distance constraints . A bond in YASARA has a certain order (single, double, etc.), but contrary to other molecular modeling programs, fractional bond orders somewhere between 'single' and 'double' are also supported. This helps to conserve symmetries and provides a better picture of the underlying chemistry. Bond orders can be visualized by pressing <F2> to show balls & sticks, and coloring bonds by their order . YASARA uses the following color mapping, described in more detail here : Name Order Color Single bond 1 gray Resonance bond 1.25 blue Resonance bond 1.33 magenta Resonance bond 1.5 red Resonance bond 1.66 orange Resonance bond 1.75 bright orange Double bond 2 yellow Triple bond 3 green Quadruple bond 4 cyan Additionally, bond orders (as well as hydrogen atoms ) are assigned in a pH dependent manner. YASARA considers the influence of the pH in two ways: General pH model applied to all molecules: Based on a library of SMILES strings that define protonation patterns and standard pKa values for common functional groups, YASARA assigns bond orders and adds hydrogen atoms according to the currently set default pH. This pH can be changed by clicking on Options > Default pH. If the 'Adjust bond orders and hydrogens' button is checked, YASARA will retype all bonds and reassign all hydrogens to match the new pH. The mentioned SMILES strings can be found in the GROUP_DATA section of the file yasara.def (present in YASARA Dynamics+). A simple example would be that a carboxyl group is neutral below pH 4 and negatively charged above. Specific pH model applied to amino acids: When running molecular dynamics simulations of proteins, the general pH model described above is too crude. Especially active site residues often exhibit large pKa shifts depending on the environment, and instead of the general statement that 'a carboxyl group is neutral below pH 4', one would prefer the specifc conclusion that 'the pKa of residue Glu 42 is raised to 5.1, and a proton sits preferably on the OE1 oxygen'. These pKa predictions are made by the 'cell neutralization experiment', which is used to prepare a molecular dynamics simulation in YASARA Dynamics+. Since pKa predictions are non-trivial, they can be overridden with true experimentally measured pKa values before running the cell neutralization experiment. As a conclusion, apply first the general pH model , most easily by clicking Edit > Clean > All, then fine-tune the results with the cell neutralization experiment. When this is completed, be careful to not apply the crude general model again, since it does not know about the specific tuning results. The whole concept behind the general pH model is best illustrated with a few examples: Figure: Bond orders and protonation patterns of small molecules as a function of pH The figure above shows seven small molecules at pH 0 to 14. Column 1 - Phenol: All carbon-carbon bonds in the aromatic 6-ring are (roughly) equivalent, the bond order is 1.5 (colored red). From pH 10 on, the hydroxyl group loses the proton. Column 2 - Acetic acid: From pH 0 to 4, the carboxyl group is neutral, one oxygen makes a double bond (yellow), the other one carries a hydrogen. From pH 5 on, the proton is gone and both oxygens are equivalent, making bonds of order 1.5 (red). Column 3 - Imidazole ring: From pH 0 to 6, the ring is protonated, both nitrogens carry a hydrogen and make equivalent bonds of order 1.5 to the carbon in between. The nitrogen valence is thus 3.5, corresponding to a formal charge of +0.5 per nitrogen and +1 in total. From pH 7 on the symmetry is broken, the molecule is neutral, and the nitrogen that does not carry a hydrogen makes a double bond instead. Column 4 - Sulfurous acid: Below pH 2, the molecule is neutral, two oxygens make double bonds, the other two carry hydrogens. From pH 2 to 6, one hydrogen is gone, three oxygens are equivalent due to resonance effects, making bonds of order 1.66 (orange) each. The valence of the sulfur atom stays at 6 (1+3*1.66), and each of the three equivalent oxygens gets a formal charge of -0.33, summing up to -1. From pH 7 on, both hydrogens dissociate, all four oxygens make equivalent bonds of order 1.5 (red). The four resulting formal charges of -0.5 sum up to -2. Column 5 - Guanidinium group: The side-chain of the amino acid arginine is a strong base due to resonance effects. From pH 0 to 12, the group is protonated, each nitrogen makes a bond of order 1.33 (magenta) to the central carbon. The carbon valence is thus normal (4), while each nitrogen has a valence of 3.33, the three resulting formal charges of +0.33 sum up to +1 in total. From pH 13 on, the symmetry is broken, one nitrogen loses a proton and makes a double bond. Column 6 - Carbonic acid: Below pH 7, the molecule is neutral, one oxygen makes a double bond, the other two carry hydrogens. From pH 7 to 10, one hydrogen is gone, two oxygens are equivalent and make bonds of order 1.5 (red). From pH 11 on, both hydrogens dissociate, all three bonds are equivalent with order 1.33 (magenta). The three formal charges on the oxygens (-0.66) sum up to -2. Column 7 - Phosphoric acid: Similar to carbonic acid, just the phosphorus has a valence of 5 and therefore carries an additional hydrogen atom. °  Local coordinate system - The coordinate system within one object Because objects can be moved around and rotated independently, every object has its own local coordinate system. The cartesian atom coordinates specified in the PDB file are the same as those in the local coordinate system. (Coordinates shift if you center the object, and the sign of the X-coordinate flips if YASARA uses a left-handed coordinate system). Sometimes it is desirable to let several objects share the same local coordinate system. There are several ways to achieve that: Load the objects right after each other with the 'Center' option disabled, and don't move the first away before loading the second. Transfer one object to the coordinate system of the other object. Superpose the objects. Join the objects. Transform the coordinate system of all objects, then Center them all together. Start a Simulation to transfer all objects into the coordinate system of the simulation cell. °  Global coordinate system - The coordinate system of the scene All objects are positioned and oriented with respect to YASARA's global coordinate system. Only these global coordinates change if you move or rotate an object. Unless you grab a single object, all objects rotate together around their common geometric center (or around the center of the simulation cell if one has been defined). Figure: YASARA's left-handed coordinate system. The X-axis (red) points to the right, the Y-axis (green) points up and the Z-axis (blue) points into the screen. You can use the first three fingers of your left hand to mimic these arrows. Figure: YASARA's right-handed coordinate system . The X-axis (red) points to the left, the Y-axis (green) points up and the Z-axis (blue) points into the screen. You can use the first three fingers of your right hand to mimic these arrows. °  The three potential pitfalls Our main goal was to make YASARA usable without a manual. This is only possible if the program is logically consistent. Usability tests have shown that there are three occasions where logic can seem counter-intuitive without the proper background information. These three potential pitfalls are listed below. °  You never get less than you want Most commands you can choose with the mouse will show you a little pop-up menu where you can define the final selection type. Usually 'All', 'Object', 'Molecule', 'Residue ' or 'Atom'. It is important to remember that you can never get less than the type you choose. So if you click on View > Color > Residue, you will always color entire residues, no matter what you do. Even if you then pick 'Sidechain' in the list titled 'Belongs to or contains', you will not color just the side-chains, but instead all residues that contain side-chains (so no glycines). If you want to color just the side-chains alone, note that a side-chain is less than a residue, so go to View > Color > Atom and pick 'Sidechain' in the list titled 'Belongs to or contains'. Either select the residues in the list on the left side, or type them in the manual selection field at the bottom, e.g. Res 10-20 The same principle holds when creating a color gradient: The color only changes between the units of the selected type. To color all objects in an NMR bundle with a different color, go to View > Color > Object > Apply gradient To color all molecules in an oligomer with a different color, go to View > Color > Molecule > Apply gradient To color all residues in a molecule with a different color, go to View > Color > Residue > Apply gradient °  There is a difference between 'Hide', 'Switch off', 'Remove' and 'Delete' Imagine there is a big lamp with some separate lights in your room, like the one below. Let's think of the lamp as a YASARA object, and of the lights as atoms. Figure: A YASARA object consisting of three atoms, with one hidden atom on the right. The lamp is switched on, you can see all the lights. Now hide the left light by putting a black (burn-proof) cap on top of it. You just cannot see it anymore, but it is still present. So if you hide atoms, they are invisible until you show them again, but they stay part of the object and you can still change their style. Changing their style e.g. from ball to stick does not make them visible. If you now switch off the lamp, it is still at the original place, you just cannot see it in the darkness. So switching off an object will just make it invisible, but it is still fully present, its atoms are part of the soup. Now take away the black cap to show the hidden light again - you still cannot see it, until you switch on the entire lamp. So if you show an atom in an object that is switched off, you will not see it unless you also switch on the object. If you remove the lamp, it still exists somewhere (wherever you put it in the next room), but toggling the switch will give no result. So a removed object is not part of the soup anymore, it is stored somewhere else to be reused again later. There is no way you can do anything with a removed object, unless you bring it back. Take a hammer and smash the entire lamp. Now its existence has been 'Deleted', it is lost forever. Your last remaining option is to turn back time (by pressing the Undo button provided by YASARA Model and above). °  Gaps in a molecule are bridged by default If you load a structure determined by X-ray crystallography, there are often stretches of residues that were not visible in the electron density map, the structure has a gap. Because there is no way to distinguish between a true gap and an unintentional gap created during modeling, YASARA ignores gaps unless they are explicitly marked as true gaps. This can be helpful, as you get for example a continuous ribbon display that bridges gaps, but sometimes it is not what you want. In these cases, just delete all peptide bonds that are longer than 3 Angstroms: Go to Edit > Delete > Bond, click on atom name 'C' in the first window, 'N' in the second window and input 3 A as the minimum bond length required for deletion. If after deleting the bonds, you save the structure as a PDB file and load it again, all bonds will reappear, because PDB files do not store information about deleted bonds. In such a case, you might consider adding a split point (an explicit chain break) at the position of the gap: Go to Edit > Split > Residue and select the residue after the gap. Split points appear as 'TER' entries in the PDB file and as vertical lines in the sequence selector at the bottom. °  The keys and mouse buttons to use Virtually all the keys are explained in the tutorials 'Working with YASARA', and 'Interactive Simulations for Modeling' which you can access by clicking on Help > Play help movie. °  Moving objects around Shift Grab next object for movement/rotation (YASARA Model and above) Ctrl+Shift Grab previous object for movement/rotation (YASARA Model and above) LeftClick in the 'Name' column of the HUD Grab the selected object for movement/rotation (YASARA Model and above) LeftButton+MouseMovement Rotate object or scene or move label Ctrl+LeftButton+MouseMovement Rotate object or scene, centered on the marked atom LeftButton+RightButton+MouseMovement Move object or scene along the X/Y-axes MiddleButton+MouseMovement Move object or scene along the X/Y-axes Cursor keys Move object or scene along the X/Y-axes RightButton+MouseMovement Move object, scene or label along the Z-axis 1..9 Set speed of movements (not on numeric keypad) Q,W,E,R,T,Y Move grabbed object or scene along the three axes (English keyboard) Ctrl+1..9 Set speed of rotations (not on numeric keypad) A,S,D,F,G,H Rotate grabbed object or scene about the three axes (English keyboard) Z,X,C,V,B,N Start automatic rotation of grabbed object or scene about the three axes (English keyboard) LeftClick on a label Mark label and move it around If an object reacts strangely when moving it around , the reason is most likely that some atoms are incorrectly placed far away from the object's center, for example after reading atom coordinates from a corrupted file. This makes the object appear larger, requiring YASARA to slow down or block movements. Delete these atoms or use the keyboard instead of the mouse. The help movie 'Working with YASARA' shows how to configure the MacBook TouchPad and the Apple MightyMouse to function optimally with YASARA. When configured as suggested, the following bindings are available: Apple MacBook TouchPad : Button+SingleFingerMovement Rotate object or scene or move label Ctrl+Button+SingleFingerMovement Rotate object or scene, centered on the marked atom DoubleFingerMovement Move object or scene along the X/Y-axes Button+DoubleFingerMovement Move object, scene or label along the Z-axis Apple MightyMouse: LeftButton+MouseMovement Rotate object or scene or move label Ctrl+LeftButton+MouseMovement Rotate object or scene, centered on the marked atom SideButtons+MouseMovement Move object or scene along the X/Y-axes ScrollBall Move object or scene along the X/Y-axes RightButton+MouseMovement Move object, scene or label along the Z-axis °  Changing the scene style F1 Set scene style to balls F2 Set scene style to balls&sticks F3 Set scene style to sticks F4 Set scene style to Calpha trace F5 Set scene style to tube F6 Set scene style to ribbon F7 Set scene style to cartoon F8 Change side-chain style LeftClick in the VISibility column of the HUD Switch selected object on/off RightClick in the same VISibility column Switch selected object on and all others off °  Editing Delete Delete the marked atom or label Alt+LeftClick on an atom Repeat the last command. KDE by default blocks this combination, use Tab instead. Alt+LeftClick on the sequence selector Repeat the last command. KDE by default blocks this combination, use Tab instead. Ctrl+Z or Ctrl+U Undo (YASARA Model and above) Ctrl+R Redo (YASARA Model and above) °  Analyzing the soup Insert or I Show/hide the head up display (HUD) Ctrl+Insert or Ctrl+I Change the data displayed in the right HUD (YASARA Dynamics and above) LeftClick on atom Mark atom, display its properties in the HUD LeftClick on sequence selector Mark atom in clicked residue PageDown or MouseWheelDown Mark next atom, see MouseWheel command. PageUp or MouseWheelUp Mark previous atom, see MouseWheel command. Ctrl+LeftClick on atoms Display distance / angle / dihedral in the left HUD (one atom must be marked) Ctrl+LeftClick on sequence selector Zoom in on the clicked residue RightClick on marked atom Show atom context menu RightClick on sequence selector Show residue context menu Home Show details about the previous charge or bond in the simulation HUD (YASARA Dynamics and above) End Show details about the next charge or bond in the simulation HUD (YASARA Dynamics and above) Pointer on sequence selector + letters Find the amino acid sequence typed in one letter code while the mouse pointer is placed on top of the sequence selector °  Controlling a simulation These keys only work in YASARA Dynamics and above. F10 Change simulation temperature control Ctrl+F10 Change simulation temperature control, reversed direction F11 Pause/continue simulation Ctrl+F11 Continue a paused simulation for one single step F12 Switch simulation on/off 1..9 Set pulling force (not on numeric keypad) Ctrl+RightButton Pull the marked atom toward the mouse pointer (during simulations) Ctrl+LeftButton+RightButton Pull the object containing the marked atom toward the mouse pointer (during simulations) Ctrl+MiddleButton Pull the object containing the marked atom toward the mouse pointer (during simulations) In MacOSX, the function keys F10 to F12 are normally occupied by Expose. If you do not want to reconfigure its keybindings, you can alternatively use the three keys just below on a typical Apple keyboard: '0' instead of F10, and then the two keys to the right instead of F11 and F12 (the actual characters printed on these keys depend on your location). If you use a MacBook trackpad, you can pull the marked atom by holding down 'Command' and the trackpad button. °  Using the console The console size and font can be configured separately . Space Bring up the console Space If pressed a second time, extend the console to full size Return Leave the console LeftButton Select text and copy to clipboard MiddleButton Paste the clipboard Ctrl+V Paste the clipboard PageUp Scroll console one page down PageDown Scroll console one page up MouseWheelUp Scroll console half a page down MouseWheelDown Scroll console half a page up Ctrl+CursorUp Scroll console one line down Ctrl+CursorDown Scroll console one line up CursorUp Show previous command in the history CursorDown Show next command in the history or clear input line Home Move cursor to start of line End Move cursor to end of line Ins Toggle the HUD Ctrl+Ins Change the HUD Esc Interrupt a running macro that does not Wait °  Other keys Pause or P Pause/continue YASARA Ctrl+Pause or Ctrl+P Continue paused YASARA for one single step Ctrl+M Rerun the last macro or movie Ctrl+Esc Exit YASARA immediately °  The command line parameters You can get a list of all supported command line parameters by running YASARA with the -help option. -con Run YASARA in interactive console mode -txt Run YASARA in plain text mode -upd Update simulation parameters, recompile the force fields Filename.??? Load and display the specified PDB file Filename.log Record all console output to Filename.log Filename.mcr Var=X Execute the specified macro , optionally setting 'Var' to X. Filename.sce Load and display the specified SCE file Filename.yob Load and display the specified YOB file Filename.py Req Execute the specified Python plugin with request 'Req' -norun Tell the installer not to run YASARA directly When you specify a macro to run as 'Filename.mcr' it is sometimes helpful to set certain variables, like the MacroTarget. The following example sets variables 'a' to 5 and 'MacroTarget' to '/home/work/1crn.pdb': yasara MyMacro.mcr a=5 "MacroTarget='/home/work/1crn.pdb'" or Yasara.exe MyMacro.mcr a=5 "MacroTarget='/home/work/1crn.pdb'" Note the double quotes around the last parameter, they prevent the operating system from removing the single quotes before passing the parameter to YASARA. In case you are working with Windows and have not used command line parameters before, there are two ways of passing these parameters to a program: Create a shortcut to yasara.exe, right-click on the shortcut, and select properties. Search for the 'Target input box' containing the path to yasara.exe, e.g. "C:\Program Files\yasara\yasara.exe". Then type the command line parameters right after this path (outside the quotes). Open an MSDOS command prompt, CD to the yasara directory and type 'yasara' followed by the command line parameters, e.g. yasara -upd °  Running YASARA in special environments If you want to use YASARA remotely or if several users want to work with one YASARA installation, read the following sections for helpful hints. °  Running YASARA without graphics Especially Linux users like to run programs in a console, often even remotely from another machine or as a batch job. YASARA offers several ways to achieve that: yasara -con runs YASARA in console mode. The head-up display is also shown and can be scrolled with <CursorUp> and <CursorDown>. If you run a macro that issues a Wait command, you have to press <Space> to interrupt it and return to the console. This is the method of choice for running YASARA interactively without graphics, e.g. from a remote computer via SSH. When you want to run YASARA in the background (with output redirected to a file) or from another program, you need to activate plain text mode: yasara -txt NOTE: Text output is only visible in Linux and MacOSX. In Windows, it is always redirected to the file stdout.txt, which unfortunately prevents interactive use of YASARA in plain text mode. In Linux and MacOSX, you can also redirect output to a file as usually and run in the background while executing MyMacro.mcr: yasara -txt MyMacro.mcr >MyLog.log 2>&1 & or (depending on the shell you use) yasara -txt MyMacro.mcr >& MyLog.log & Some exotic shells my also require this expression: (yasara -txt MyMacro.mcr >& MyLog.log &) IMPORTANT: make sure that your macro ends with 'Exit', otherwise YASARA waits for input in the background, which results in the error message "*** Error: getline(): not interactive, use stdio". This approach has one disadvantage: things written to the file MyLog.log will not appear there immediately, but only once in a while when the operating system's output buffer runs full and is flushed. So you cannot check progress by looking at MyLog. YASARA therefore provides another option: yasara -txt MyLog.log MyMacro.mcr >/dev/null 2>&1 & This way YASARA writes all the output to MyLog.log, which is also flushed permanently. (See above for changes required by other shells). It is essential to specify the log file before the macro file, alternatively you can also use the RecordLog command inside the macro. If your macro switches the console off, only minimal output will be written to the log. For Windows users, the command looks almost the same: Yasara.exe -txt MyLog.log MyMacro.mcr °  Running YASARA on one machine with multiple users If you install YASARA on one single machine, you do not need a multi-user license, as long as all the people work personally on this one machine and do not log on remotely. Note that the user who runs YASARA must have write permissions in the YASARA directory : Towards the end of the last millenium, it became common practice to run programs without write permissions in their own directory, and to store modified data in the users home directory or related places. But in the mean time, new advanced software capabilities like 'self-healing' and 'feedback-induced self-improvements' become more and more popular, which allow applications to permanently modify and improve themselves, which in turn requires write permissions. In Windows, simply install YASARA in a common directory (e.g. c:\Program Files) and set the permissions of the YASARA directory such that all users have WRITE ACCESS there. In Linux, install YASARA as root and also run it once as root. This will automatically adjust permissions and enable write access for the users. In MacOSX, copy the 'YASARA.app' bundle to the /Applications directory and run it once immediately after. If you run YASARA without write permissions, it will display a warning at the bottom of the startup screen and disable a wide range of features. These disabled features may occasionally look like bugs, so please do not report problems when running YASARA without write permissions. °  Running YASARA from an NFS mounted volume If you own a group-leader license of YASARA, you can install the program on an NFS mounted harddrive. While it makes sense for many programs to run them directly from the NFS partition, this is not an efficient solution for YASARA due to a couple of reasons: YASARA is not a static program which gets away with a single .ini file that is stored separately for each user. A large number of files are modified while YASARA is running (force field definition files, caching files, plugin communication data, log files). Changes made by one user to the force fields can easily mess up the work of others. The amount of data read from/written to the YASARA directory quickly exceeds the NFS network bandwith, especially when working with protein databases in YASARA Structure and the Twinset. The solution is to use the Python script rsync.py , which can be found in the yasara/plg directory. Open this script in a text editor and adjust the settings for the first two directories 'masterdir' and 'localdir', then run it on every machine where you want to install YASARA. The script creates a local copy of the NFS mounted YASARA folder, preserves the config file yasara.ini, warns the user when important force field definition files got overwritten and offers to restore them. When YASARA got updated on the NFS volume, users can simply rerun the script. This approach makes sure that everyone can work with YASARA at full speed, while keeping other users safe from local modifications. °  Running YASARA on a 64 bit operating system With the extension of the common x86 CPU architecture to 64 bits by AMD and later also Intel, true 64 bit computing is now available even on low-end PCs. However, YASARA is not an application that benefits in any way from more than about 1 GB of memory, so the main advantage of 64 bits - the larger address space - is not a help. What remains is the larger number of CPU registers, which allows the compiler to create more efficient code - unfortunately at the cost of slower memory accesses, because all pointers now occupy an additional 32 bits in the data cache. Since all critical sections of YASARA have been implemented in Assembly language anyway, we do not expect any noticeable benefit from 64 bits. For simplicity, YASARA will therefore stick to 32 bits, as long as all 64 bit operating systems keep their support for running 32 bit applications. In short: YASARA normally runs out of the box on 64 bit operating systems. Exceptions include some less user friendly Linux distributions (e.g. Kubuntu) that may require you to install additional RPMs to add 32 bit versions of some system libraries. °  Working with extremely large protein structures YASARA has been designed to run fluidly with very large structures consisting of several 100000 atoms. Here are some hints to maximize the performance: Make sure that YASARA has enough memory available: edit the file 'yasara.ini' and set the 'Memory' field to about 75% of the memory present in your computer. E.g. if you have 1GB installed, set 'Memory' to 768. YASARA always shows you the percentage of free memory in the botton left corner after 'Mem'. In YASARA Model+ you can gain speed by disabling the Undo/Redo functionality. Click Options > Undo levels and set them to 0. Make sure that YASARA's built-in antialiasing is disabled: Click Window > Antialiasing. Disable shadows: Click View > Lighting and set the 'Shadow density' to 0. Choose an efficient way of drawing your molecule. Press <F4> or View > Scene style > Trace to show a Calpha trace, which is the fastest style. If you work with surfaces, lower the grid resolution (choose a larger number at View > Show surface > Parameters) Work with multiple objects instead of a single one: e.g. when looking at the foot-and-mouth virus, the PDB file 1qqp contains only one capside fragment with 5200 atoms. Instead of downloading the whole biologically active oligomer, click Edit > Oligomerize and let YASARA Model+ build the complete capside with 60 fragments and 312000 atoms. Many operations (e.g. adding hydrogens) are much faster when applied to many small instead of one huge object. YASARA will also show many more progress bars. OpenGL allows to show objects only up to a certain maximum depth. To prevent objects from disappearing when you move them too far away, YASARA simply blocks mouse movements beyond the maximum depth. If you feel the need to move the object further away, click on View > Atom appearance > Size and reduce the atom size (which is essentially the same as moving the near and far clipping planes away). You can also use the keyboard to move the scene beyond the far clipping plane (keys 'Y' and 'U' on English keyboards). When you end up in the middle of the structure and lose the orientation, click on the zoom icon in the top menu line to center the scene. °  Citing YASARA, its algorithms and force fields If you use YASARA in published work, please add the appropriate references and send us a reprint! If you... generally use YASARA for molecular graphics etc., or specifically energy minimize proteins with the NOVA force field: Increasing the precision of comparative models with YASARA NOVA - a self-parameterizing force field Krieger E, Koraimann G, Vriend G (2002) Proteins 47,393-402 run simulations with YASARA (if you use force fields other than Yamber, e.g. Amber, please also cite the respective paper listed below). Making optimal use of empirical energy functions: force field parameterization in crystal space Krieger E, Darden T, Nabuurs S, Finkelstein A, Vriend G (2004) Proteins 57,678-683 use the Neutralization Experiment to predict pKas: Fast empirical pKa prediction by Ewald summation Krieger E, Nielsen JE, Spronk CA, Vriend G (2006) J.Mol.Graph.Model. 25,481-486 run simulations with the Amber94 force field: A Second Generation Force Field for the Simulation of Proteins, Nucleic Acids, and Organic Molecules Cornell WD, Cieplak P, Bayly CI, Gould IR, Merz Jr. KM, Ferguson DM, Spellmeyer DC, Fox T, Caldwell JW, Kollman PA (1995) J. Am. Chem. Soc. 117, 5179-5197 run simulations with the Amber96 force field: The Development/Application of a 'Minimalist' Organic/Biochemical Molecular Mechanic Force Field using a Combination of ab Initio Calculations and Experimental Data, in Computer Simulation of Biomolecular Systems Kollman P, Dixon R, Cornell W, Fox T, Chipot C and Pohorille A (1997) in Computer Simulation of Biomolecular Systems, van Gunsteren WF, Weiner PK, Wilkinson AJ eds. 3, 83-96 run simulations with the Amber99 force field: How well does a restrained electrostatic potential (RESP) model perform in calculating conformational energies of organic and biological molecules? Wang J, Cieplak P, Kollman PA (2000) J.Comput.Chem. 21,1049-1074 run simulations with long-range electrostatics (Particle Mesh Ewald): A smooth particle mesh Ewald method Essman U, Perera L, Berkowitz ML, Darden T, Lee H, Pedersen LG (1995) J. Chem. Phys.;b 103, 8577-8593 simulate small molecules with the General Amber Force Field (GAFF): Development and Testing of a General Amber Force Field Wang J, Wolf RM, Caldwell JW, Kollman PA and Case DA (2004) J Comput Chem 25, 1157-1174 simulate small molecules with AM1BCC/AutoSMILES point charges: Fast, efficient generation of high-quality atomic charges. AM1-BCC model: II. Parameterization and validation Jakalian A, Jack DB and Bayly CI (2002) J Comput Chem 23,1623-1641 use the GLYCAM force field parameters for carbohydrates: Molecular mechanical and molecular dynamical simulations of glycoproteins and oligosaccharides. 1. GLYCAM_93 parameter development. Woods RJ, Dwek RA, Edge CJ, Fraser-Reid B (1995) J. Phys. Chem. 99,3832-3846 simulate sugars with sulfate groups: Force field parameters for sulfates and sulfamates based on ab initio calculations: extensions of AMBER and CHARMm force fields. Huige CJM, Altona C (1995) J.Comp.Chem. 16,56-79 optimize small molecules using quantum chemistry: MOPAC: A semiempirical molecular orbital program Stewart JJP (2000) J.Comp.Aided Mol.Des. 4,1-103 if the optimization is performed using implicit solvent: Conductor-like screening model for real solvents: a new approach to the quantitative calculation of solvation phenomena Klamt A (1995) J.Phys.Chem. 99, 2224-2235 create analytic molecular surfaces with the MSMS program: Reduced surface: an efficient way to compute molecular surfaces Sanner MF, Spehner JC, Olson AJ (1996) Biopolymers 38,305-320 analyze electrostatics using the Poisson Boltzmann solvation model: Electrostatics of nanosystems: application to microtubules and the ribosome Baker NA, Sept D, Joseph S, Holst MJ, McCammon JA (2001) Proc.Natl.Acad.Sci.USA 98,10037-10041 compare molecules using the distance power or distance expontential: Testing similarity measures with continuous and discrete protein models Wallin S, Farwer J, Bastolla U (2003) Proteins 50 ,144-157 check proteins with the 'Check' command (Twinset): Errors in protein structures Hooft RWW, Vriend G, Sander C, Abola EE (1996) Nature 381,272 align proteins with MOTIF (Twinset): Detection of common three-dimensional substructures in proteins Vriend G, Sander C (1991) Proteins 11,52-58 align proteins with the SHEBA plugin: Protein structure alignment using environmental profiles Jung J, Lee B, (2000) Protein Eng. 13,535-543 sample proteins in cartesian space with the CONCOORD plugin: Prediction of protein conformational freedom from distance constraints de Groot BL, van Aalten DMF, Scheek RM, Amadei A, Vriend G and Berendsen HJC (1997) Proteins 29,240-251 run parallel jobs using the Models@Home cluster system: Models@Home: distributed computing in bioinformatics using a screensaver-based approach Krieger E, Vriend G (2002) Bioinformatics 18, 315-318 publish ray-traced images: Add a note to the figure caption: 'Molecular graphics created with YASARA (www.yasara.org) and PovRay (www.povray.org)'. °  Reporting bugs, problems and inconveniences If you have Python installed, the easiest way of reporting a problem is by clicking on Help > Report error. The second option is to do it manually at www.yasara.org/bugreport. If the problem requires more than a few mouse clicks to reproduce, please send us the corresponding execution log. YASARA logs all commands in the log/ subdirectory with names like log/exec_XY.log, where XY is the process ID. When YASARA exits, the log file is automatically deleted. If YASARA crashes there is no time to delete the log file, so you can just send the newest log file you find. If the problem does not involve a crash, do not exit YASARA, otherwise the log file will be lost. Either get the latest log file while YASARA is still running or type CoreDump in the console to force a crash and preserve the log file. If you experience a true crash in Linux which is not caused by a bug in YASARA but by some specific characteristics of your computer (e.g. a crash immediately when you start YASARA), please analyze it in more detail. Open a terminal and type ulimit -c unlimited Then start YASARA from the terminal and cause the crash. You should now see a message like Segmentation fault (core dumped) ..and there should be a file named core.[ProcessID] in your current directory (if you started a macro that changed the working directory, you have to go there first). Run the GNU debugger with these commands: gdb [PathToYASARA]/yasara core.[ProcessID] info stack info registers disass Please email us the information displayed in the terminal. °  Screenshots as examples of what you can do Click on the link below each screenshot to look at the command that was used to create the scene. Figure: An example for the AddEnv command. Figure: An example for the AddHyd command. Figure: An example for the AtomTexture command. Figure: An example for the AtomTexture command. Figure: An example for the BallStick command. Figure: An example for the Ball command. Figure: An example for the BuildAtom command. Figure: An example for the BuildLoop command. Figure: An example for the BuildMol command. Figure: An example for the BuildRes command. Figure: An example for the Cell command. Figure: An example for the Cell command. Figure: An example for the Cell command. Figure: An example for the Check command. Figure: An example for the ColorBonds command. Figure: An example for the ColorBG command. Figure: An example for the Color command. Figure: An example for the Color command. Figure: An example for the Crystallize command. Figure: An example for the Dihedral command. Figure: An example for the Distance command. Figure: An example for the Experiment command. Figure: An example for the Experiment command. Figure: An example for the Experiment command. Figure: An example for the Experiment command. Figure: An example for the FillCellObj command. Figure: An example for the FillCellObj command. Figure: An example for the FillCellWater command. Figure: An example for the FirstSurf command. Figure: An example for the Fix command. Figure: An example for the Font command. Figure: An example for the ForceField command. Figure: An example for the FormEnergy command. Figure: An example for the Hide command. Figure: An example for the LabelDis command. Figure: An example for the Label command. Figure: An example for the Label command. Figure: An example for the Label command. Figure: An example for the Label command. Figure: An example for the Label command. Figure: An example for the LightSource command. Figure: An example for the MakeImageObj command. Figure: An example for the MakeTextObj command. Figure: An example for the Oligomerize command. Figure: An example for the pH command. Figure: An example for the Print command. Figure: An example for the PrintHUD command. Figure: An example for the RayTrace command. Figure: An example for the RayTrace command. Figure: An example for the SampleDih command. Figure: An example for the SampleDih command. Figure: An example for the SampleDih command. Figure: An example for the SampleDih command. Figure: An example for the SampleLoop command. Figure: An example for the SecStr command. Figure: An example for the ShowArrow command. Figure: An example for the ShowCone command. Figure: An example for the ShowESP command. Figure: An example for the ShowHBo command. Figure: An example for the ShowImage command. Figure: An example for the ShowRota command. Figure: An example for the ShowSecStr command. Figure: An example for the ShowSecStr command. Figure: An example for the ShowSecStr command. Figure: An example for the ShowSimGrid command. Figure: An example for the ShowSphere command. Figure: An example for the ShowSurf command. Figure: An example for the ShowTab command. Figure: An example for the ShowTorus command. Figure: An example for the ShowTrace command. Figure: An example for the Show command. Figure: An example for the Stick command. Figure: An example for the Style command. Figure: An example for the Style command. Figure: An example for the Style command. Figure: An example for the SurfPar command. Figure: An example for the Surf command. Figure: An example for the SwapPosAtom command. Figure: An example for the SwapRes command. Figure: An example for the TypeAtom command. Figure: An example for the TypeAtom command. Figure: An example for the TypeBond command.