NOTE: The information in this document is based on the Systre 1.2.0 release. Other versions of Systre may behave slightly differently.
The program SYSTRE is designed to analyze periodic nets as they arise in the study of extended crystal structures (as opposed to molecular crystals). The acronym stands for Symmetry, Structure and Refinement. SYSTRE uses a method called barycentric placement to determine the ideal (i.e., maximal embeddable) symmetry of a crystal net and to analyze its topological structure. It then generates a unique "fingerprint" for the topological type of the given net and uses that to look up the structure in its built-in database (see below). Users can also create their own databases.
SYSTRE also computes a refined embedding of the given net using a method based on simulated forces. The targeted embedding is one that minimizes the edge length variance (normalized to unit length) and maximizes the unit cell volume. The forces modeled are not physically realistic, but should in most cases result in viable input for molecular modeling software.
Currently, SYSTRE's built-in database contains all feasible nets from the RCSR online resource as of May 22, 2013.
The 13 RCSR nets that Systre currently does not recognize are bad, bae, bai, bbu, bcr, cys, fco, hyx, lcw, nbo-g, tep, uld and ulm.
SYSTRE is part of The Gavrog Project.
SYSTRE requires a Java runtime environment (JRE) of version 1.5 or higher. On some systems, Java will already be installed as a prerequisite for other programs. Otherwise, the most straightforward way to get a JRE is to download it from java.com and follow the installation instructions given there. Set all path variables correctly for your system as instructed (this should be done automatically in most cases), so that the java command can be recognized. If supported by your system, make sure that the file extension .jar is associated with the Java executable.
Installing SYSTRE itself is very easy. Just download the file Systre.jar and put it anywhere you like, for example on your desktop. A SYSTRE executable is also included in the main Gavrog distribution available from http://www.gavrog.org.
The Gavrog installer automatically installs SYSTRE along with 3dt and creates a batch file Systre or Systre.bat in the bin subdirectory of your chosen installation location. Please refer to your operating system documentation on how to execute such files. On Windows and some Unix machines, the installer can also create desktop icons for both 3dt and SYSTRE.
The simplest way to start SYSTRE is to double-click its icon. If that does not work, and you are sure that Java is correctly installed and all path variables set correctly, open a console window and type the command
java -jar Systre.jar
from the same folder that you put Systre.jar in. Alternatively, add the appropriate path. For example, if you downloaded Systre.jar to a folder named C:\Programs\Systre (on a Windows system), change the above to
java -jar C:\Programs\Systre\Systre.jar
To make things easier, you can create a batch file (a.k.a. shell script) containing the command. Please refer to your operating system manual on how to create and execute such files.
Using SYSTRE is very simple. Run SYSTRE, then use the [Open...] button to read in a file of net descriptions. SYSTRE will process the first net in the file and describe the results in an informal way. If there are more nets, use the [Next] button to step through them. When you are finished with a file, you can store the results in one of several formats using the [Save as...] button. The [Help] button displays this text and, finally, the [Options...] button lets you modify some of SYSTRE's internal workings.
SYSTRE uses three basic file types:
If you read or write a file from within SYSTRE, the extension will determine the format of the file and the extend of information in it. Typically, you would read a structure file and save the output in a protocol file. But you might also want to produce a .cgd file with the new symmetry group and node positions as determined by SYSTRE.
Here are some details on how to enter certain types of information in structure files:
Enter the space group symbol as it appears in the International Tables, except that "bar 3", "bar 4" etc. are written as -3, -4 and so on and subscripts are written as regular numbers. Examples: Fd-3m, I41/amd, P212121.
If you specify a crystal without explicit edges as in the first and fourth example below, SYSTRE needs to compute edges based on nearest neighbors. This does not only depend on the correct cell parameters, but also on the origin choice. For groups that have two conventional choices as according to the international tables, SYSTRE uses the second one by default. This can be changed in the 'Options' dialog.
Another way to make sure that the correct origin choice is used is to append :1 or :2, respectively, to the group name as in Example 4 below.
Hexagonal versus rhombohedral settings for rhombohedral groups are handled analogously to the above. In this case, append :H (the default) or :R, accordingly.
Below are some examples of legal input for SYSTRE. You can cut and paste any of the following examples (or all of them) into a .cgd file using your favorite text editor (e.g. Notepad on Windows) and open it from within SYSTRE.
The SYSTRE format allows comments, which start with a # character and continue until the end of the current line.
Example 1: Diamond, specified by space group, unit cell and positions. SYSTRE computes edges by finding nearest neighbors. Edge lengths have to be larger than 0.1. If any pair of nodes is closer than that, an error is reported. If this is the case for your data, you should try scaling the unit cell parameters accordingly. The keywords NODE and ATOM are equivalent, as are the keywords ID and NAME.
# The type of data to expect CRYSTAL # Structure id (optional; ID and NAME both work) ID diamond # The space group GROUP Fd-3m # Cell parameters: a b c alpha beta gamma CELL 2.3094 2.3094 2.3094 90.00000 90.00000 90.00000 # Atom specification: name coordination x y z # (decimal numbers or fractions can be used for coordinates) ATOM 1 4 5/8 5/8 5/8 # This ends the structure description END
Example 2: Diamond, specified as a periodic graph. Here, only translational symmetries are assumed, and no coordinates are needed. Edges are given explicitly in the form u v x y z, where u and v are node numbers and x y z specifies the "address" of the unit cell to connect to as an integer vector. For example, the line 1 1 0 1 0 defines an edge between node 1 and its copy shifted one unit along the y axis.
PERIODIC_GRAPH ID diamond EDGES 1 2 0 0 0 1 2 1 0 0 1 2 0 1 0 1 2 0 0 1 END
Example 3: For CRYSTAL input, edges can be given explicitly, as well. This is often preferable to letting SYSTRE compute them.
CRYSTAL
NAME real CdSO4
GROUP Pmn21
CELL 6.558 4.698 4.719 90.0 90.0 90.0
# First kind of atom
ATOM 1 4 0.0000 0.6657 0.7306
# Edges can be specified by giving the names of the endpoints
EDGE 1 2
# or by giving a number for the first and coordinates for the second.
EDGE 1 0.0000 0.1416 0.2500
# or by giving coordinates for both
EDGE 0.0000 0.6657 0.7306 0.0000 1.1416 1.2500
# The Keyword EDGE may be missing on consecutive lines.
1 -0.5000 0.8584 0.7500
# Second kind of atom.
ATOM 2 4 0.5000 0.8584 0.7500
# Second group of edge specifications.
EDGE 2 0.0000 0.6657 0.7306
2 1.0000 0.6657 0.7306
2 0.5000 1.3343 0.2306
2 0.5000 0.3343 1.2306
END
Example 4: This example describes a more complicated graph and will take SYSTRE significantly longer to complete. It shows two situations in which quotes are required.
CRYSTAL
ID LTN
# Group Fd-3m with first origin choice instead of second
# (likewise, use ":R" for rhombohedral setting, where applicable)
GROUP "Fd-3m:1"
CELL 35.622 35.622 35.622 90.000 90.000 90.000
ATOM
# If the first field in a line starts with a letter, it is assumed
# to be a keyword, so in this example, the atom names need to be quoted.
"SI1" 4 0.3112 0.2500 0.3727
"SI2" 4 0.4345 0.2481 0.3721
"SI3" 4 0.3897 0.3285 0.4532
"SI4" 4 0.5396 0.3394 0.3996
END
If you are dealing with a large number of nets that SYSTRE does not know of, you might want to read and write your own archive files. These contain fingerprints of nets processed by SYSTRE. If you read in an archive file after starting SYSTRE, it will temporarily add those fingerprints to its list of "known" nets and thus recognize them. If you write an output file with the extension .arc, it will contain fingerprints of all the "new" nets so far encountered in the current input file. Each block of lines in which the first line starts with the word key and the last line reads end constitutes one fingerprint. You can use a standard text editor to cut and paste those blocks and thus maintain your own private archives of nets.
As of Version 1.1.8, Systre will look for a folder named .systre in your user home directory upon startup and load all archive files in that folder automatically.
If you encounter any problems, please check your input thoroughly. There are many opportunities for typos and SYSTRE is very sensitive to input errors, especially when edges are not given explicitly.
There are some quirks and limitations, though, that you should be aware of when using SYSTRE.
SYSTRE identifies nodes by their barycentric positions, which is the key to its efficient algorithms. If different nodes collide, i.e., if they have identical barycentric positions, this method fails. The present version of SYSTRE is not able to handle some nets with collisions and will produce an error message. This seems to be a fairly rare case, though, especially in nets that emerge from actual crystal structures.
Furthermore, SYSTRE currently only works for nets of dimensions 2 (plane nets) and 3.
With some versions of the Java runtime environment, occasional program crashes or miscalculations have been experienced. SYSTRE double-checks its computations very thoroughly, though, so that erroneous results are highly unlikely to go undetected. Much more likely, the program will terminate for no apparent reason or produce an "INTERNAL ERROR" message. In those cases, the best strategy is to restart SYSTRE or just to rerun the net that produced the problem.
For the moment, please report bugs to odf@gavrog.org. Make sure that your input is correct and that the problem is reproducible. Enclose your input file and any output that SYSTRE produced, or, if that is not possible, describe the problem and any messages that you may have seen as detailed as possible. Tell me which operating system and which version of Java you were using.
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
Michael O'Keeffe made me aware of the problems that SYSTRE aims to solve and has supported and guided its development over many years. He also came up with the name.
Michael Treacy, Davide Proserpio, Martin Foster, Martijn Zwijnenburg, Stuart Ramsden, Vladislav Blatov, Stephen Hyde and others helped a lot by testing, criticizing and discussing SYSTRE.
My work on SYSTRE and its theoretical background was partially supported by grants from the Petroleum Research Foundation and the National Science Foundation.